thinker-context

Thinker Context

AI-powered context management and chain-of-thought planning for developers

An MCP (Model Context Protocol) server that uses DeepSeek-V3.1 to provide intelligent code planning, context tracking, and project documentation.

🚀 Quick Start

Installation

npm install -g @thinker/context

✨ Features

• 🧠 AI-Powered Planning: DeepSeek-V3.1 breaks down complex tasks into detailed steps
• 📊 Context Management: Automatic project documentation and tracking
• 📝 Change Logging: Complete history of all modifications
• 💾 Checkpoints: Save and restore project states
• ⚡ Fast: 244 tokens/second with 5/5 reasoning quality
• 🔌 MCP Compatible: Works with Kiro, Claude Desktop, and other MCP clients

Usage

As an MCP Server

Add to your MCP client configuration (e.g., Kiro's mcp.json):

{
  "mcpServers": {
    "context-chain-thinking": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "WORKSPACE_ROOT": "${workspaceFolder}",
        "SAMBANOVA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

🧠 Planning & Analysis

• analyze_prompt - Break down prompts into execution plans using DeepSeek-V3.1 AI
  • Returns 10-20 detailed steps with files, dependencies, and reasoning
  • Example: "Add user authentication" → 17-step implementation plan
• validate_plan - Check plan validity against project state

📊 Context Management

• get_project_context - Retrieve project documentation
• update_project_context - Update file documentation

📝 Change Tracking

• log_change - Record modifications
• get_change_history - View changelog

💾 Safety

• create_checkpoint - Save current state
• list_checkpoints - View available checkpoints

🎯 Example: AI-Powered Planning

// User prompt
"Add user authentication with JWT to my Express.js app"

// MCP calls DeepSeek-V3.1
analyze_prompt({ prompt: "Add user authentication..." })

// Returns detailed plan:
{
  "plan_id": "plan-1773666002007",
  "steps": [
    {
      "step_number": 1,
      "action": "Install Required Dependencies",
      "files_affected": ["package.json"],
      "dependencies": [],
      "reasoning": "Install JWT, bcrypt, and related packages",
      "estimated_complexity": "low"
    },
    {
      "step_number": 2,
      "action": "Create User Model/Schema",
      "files_affected": ["src/models/User.ts"],
      "dependencies": [1],
      "reasoning": "Define user data structure",
      "estimated_complexity": "low"
    },
    // ... 15 more detailed steps
  ]
}

How It Works

1. User Submits Prompt

"Add user authentication with JWT"

2. MCP Analyzes with Chain Thinking

analyze_prompt({ prompt: "Add user authentication with JWT" })

Returns a detailed execution plan with steps, dependencies, and reasoning.

3. Execute with Context

For each step:

• Get current context
• Make changes
• Update documentation
• Log changes

4. Context Files

The server maintains files in .ai-context/:

• project-map.json - Structured project knowledge
• project-map.md - Human-readable version
• changelog.jsonl - All changes
• execution-plans/ - Historical plans
• checkpoints/ - State snapshots

Example Workflow

// 1. Analyze the prompt
const plan = await analyze_prompt({
  prompt: "Add user authentication"
});

// 2. Create a checkpoint before starting
await create_checkpoint({
  description: "Before adding auth"
});

// 3. Get current context
const context = await get_project_context({});

// 4. Make changes (in your code)
// ...

// 5. Update context
await update_project_context({
  file_path: "src/auth.ts",
  purpose: "Handles user authentication with JWT",
  exports: ["login", "register", "verifyToken"],
  functions: {
    login: {
      description: "Authenticates user and returns JWT",
      parameters: ["email", "password"],
      returns: "JWT token"
    }
  }
});

// 6. Log the change
await log_change({
  type: "create",
  files: ["src/auth.ts"],
  description: "Added authentication module",
  prompt: "Add user authentication",
  diff_summary: "Created new auth module with login/register"
});

Development

# Watch mode
npm run dev

# Build
npm run build

# Run
npm start

Architecture

• src/types.ts - TypeScript type definitions
• src/context-manager.ts - File system operations for context
• src/chain-thinker.ts - Chain-of-thought reasoning logic
• src/index.ts - MCP server implementation

Future Enhancements

• Semantic search with embeddings
• File watcher integration
• Git integration
• Visual context explorer
• Team collaboration features
• LLM integration for smarter planning

License

MIT

🧪 Testing

All test files are in the tests/ folder:

Run Integration Test

node tests/test-mcp-integration.js

Test All DeepSeek Models

node tests/test-reasoning-quality.js

Test in Browser

Open tests/test-sambanova-simple.html in your browser

📊 Performance

Based on comprehensive testing of all 7 DeepSeek models:

Model	Speed	Quality	Status
DeepSeek-V3.1 ⭐	244.71 tok/s	5/5	WINNER
DeepSeek-V3.1-Terminus	230.47 tok/s	5/5	Preview
DeepSeek-R1-Distill-Llama-70B	228.64 tok/s	5/5	Production
DeepSeek-V3.2	226.65 tok/s	5/5	Preview
DeepSeek-V3-0324	223.53 tok/s	5/5	Production
DeepSeek-R1-0528	214.50 tok/s	5/5	Production

Why DeepSeek-V3.1?

• Fastest with perfect reasoning quality
• 8,352 character detailed responses
• Production ready and stable
• Latest model with best capabilities

📚 Documentation

All documentation is in the docs/ folder:

• docs/KIRO_SETUP_GUIDE.md - How to add to Kiro (START HERE)
• docs/QUICK_REFERENCE.md - Quick reference card
• docs/INTEGRATION_COMPLETE.md - Full integration details
• docs/COMMANDS.md - Command reference
• docs/FINAL_SUMMARY.md - Project overview
• docs/PROJECT_PLAN.md - Original planning
• docs/SAMBANOVA_TESTING.md - Model testing
• docs/SAMBANOVA_QUICK_START.md - SambaNova guide

🎯 Real-World Example

See the test output in INTEGRATION_COMPLETE.md for a real example where the AI generated a 17-step plan for adding JWT authentication, including:

• Specific file paths for each step
• Dependency tracking between steps
• Complexity estimates
• Detailed reasoning for each decision

📁 Project Structure

mcp-context-chain-thinking/
├── src/                          # Source code
│   ├── types.ts                  # TypeScript interfaces
│   ├── context-manager.ts        # File operations
│   ├── chain-thinker.ts          # AI reasoning with DeepSeek-V3.1
│   └── index.ts                  # MCP server
├── dist/                         # Compiled JavaScript
├── docs/                         # Documentation
│   ├── INTEGRATION_COMPLETE.md   # Full integration guide
│   ├── KIRO_SETUP_GUIDE.md       # Kiro setup instructions
│   ├── QUICK_REFERENCE.md        # Quick reference card
│   ├── COMMANDS.md               # Command reference
│   ├── PROJECT_PLAN.md           # Original planning
│   ├── FINAL_SUMMARY.md          # Project summary
│   ├── SAMBANOVA_TESTING.md      # Model testing docs
│   └── SAMBANOVA_QUICK_START.md  # Quick start guide
├── tests/                        # Test files
│   ├── test-mcp-integration.js   # Full integration test
│   ├── test-reasoning-quality.js # AI quality comparison
│   ├── test-sambanova-models.js  # Performance benchmarks
│   └── test-sambanova-simple.html# Browser-based testing
├── .ai-context/                  # Generated context files
├── .kiro/                        # Kiro configuration
├── .env                          # Environment variables
├── .env.example                  # Example environment
├── package.json                  # NPM configuration
├── tsconfig.json                 # TypeScript config
└── README.md                     # This file

🚀 What's Next

Potential enhancements:

• File watcher integration for auto-updates
• Semantic search with embeddings
• Git integration for version control sync
• Visual context explorer UI
• Checkpoint restore functionality
• Multi-model routing (fast models for simple tasks)

📄 License

MIT