Thinking Agent MCP

Extend your thinking model's chain of thought via MCP tools — a Model Context Protocol server that exposes chat_agent, create_branch, and get_branch_details tools, enabling thinking models to offload subtasks to non-thinking models and build tree-structured multi-perspective analysis.

Features

• 🧠 Chain of Thought Extension — Thinking models can delegate reasoning subtasks to non-thinking models via chat_agent, extending effective reasoning depth beyond single-model token limits
• 🌳 Tree-Structured Thinking — create_branch enables recursive, multi-perspective exploration with four branch types (drill down / verify / explore / stash)
• 🔍 Full Traceability — get_branch_details retrieves the complete raw reasoning process of any created branch
• 🛡️ Context Isolation — Tools are stateless and self-contained; all context must be packed into input_text. No conversation history dependency
• 🎛️ Parameter Control — Fine-grained control over tool model output via temperature, top_p, seed, stop, and max_tokens
• 🔌 Dual API Support — Works with both DeepSeek official API (recommended) and SiliconFlow API

Table of Contents

• Quick Start
• Configuration
• Tools
• chat_agent
• create_branch
• get_branch_details
• Error Handling
• MCP Client Setup
• Testing
• Project Structure
• Development
• License

Quick Start

# Clone and install
git clone https://github.com/ScarletLilith/DeepSeekV4Flash_Thinking_TreeMCP.git
cd meditatorMCP
npm install

# Configure API (see Configuration section below)
# edit test/config.json or set environment variables

# Start the server
npm run build
npm start

# Or run development mode
npm run dev

Configuration

Configuration is loaded with the following priority: Environment variables > `test/config.json`

Option 1: DeepSeek Official API (Recommended)

export DEEPSEEK_API_KEY=sk-your-key
export DEEPSEEK_BASE_URL=https://api.deepseek.com
export DEEPSEEK_MODEL=deepseek-v4-pro

Note: DeepSeek's thinking mode uses thinking: {type: "enabled"} (not enable_thinking: true).

Option 2: SiliconFlow API (Fallback)

export SILICONFLOW_API_KEY=sk-your-key
export SILICONFLOW_BASE_URL=https://api.siliconflow.cn/v1
export SILICONFLOW_MODEL=deepseek-ai/DeepSeek-V4-Flash

Config File

Create test/config.json (gitignored automatically):

{
  "baseUrl": "https://api.deepseek.com",
  "model": "deepseek-v4-pro",
  "apiKey": "sk-xxx"
}

Tools

chat_agent

Calls a non-thinking model to execute an independent subtask, extending the thinking model's chain of thought.

#### Parameters

#### Parameter Strategies

Verification:  temperature=0.1, top_p=0.1,  max_tokens=2048, seed=42
Exploration:   temperature=1.2, top_p=0.95, max_tokens=4096
Balanced:      temperature=0.5, top_p=0.8,  max_tokens=4096

create_branch

Creates a thinking branch node with recursive nesting support for deep multi-perspective analysis.

#### Parameters

Four Branch Types:

#### Response

{
  "status": "success",
  "node_id": "n_a1b2c3d4",
  "conclusion": "The extracted conclusion text...",
  "confidence": 0.85,
  "remaining_quota": 12,
  "suggestions": [
    "发散探索完成，可对有价值的方向用 drill_down 深入",
    "还可创建 12 个分支，建议继续多角度探索"
  ]
}

get_branch_details

Retrieves the complete raw reasoning process of a previously created branch node.

#### Parameters

#### Response

{
  "status": "success",
  "node_id": "n_a1b2c3d4",
  "raw_process": "The complete raw reasoning output from the model..."
}

Error Handling

Tools return structured errors with type and action fields for the thinking model to make informed decisions:

{
  "success": false,
  "type": "api",
  "action": "report",
  "error": "API authentication failed (401)",
  "status_code": 401
}

The server-side retry mechanism uses exponential backoff with jitter (1s→3s→7s, max 3 retries) for 429 and 5xx errors. Network errors (ENOTFOUND, ECONNREFUSED, ECONNRESET) are not automatically retried.

MCP Client Setup

Claude Desktop

{
  "mcpServers": {
    "thinking-agent": {
      "command": "node",
      "args": ["path/to/meditatorMCP/dist/index.js"],
      "env": {
        "DEEPSEEK_API_KEY": "sk-your-key",
        "DEEPSEEK_BASE_URL": "https://api.deepseek.com",
        "DEEPSEEK_MODEL": "deepseek-v4-pro"
      }
    }
  }
}

Any MCP-compatible Client

Configure stdio transport to point to node dist/index.js in the project directory, with the required environment variables set.

Testing

The project includes both interactive and automated test frameworks:

# Interactive CLI (with tools mode)
npm run test:with-tool

# Interactive CLI (pure thinking, no tools)
npm run test:without-tool

# Automated comparison test (runs both scenarios + generates report)
npm run test:comparison

# Batch end-to-end tests
npm run test:batch

Test Scripts

Scoring: Each question is evaluated against 10 objective checkpoints (50 total). Evaluation is done by human reviewers, not automated scripts.

Note: The test/config.json file contains your API key and is automatically gitignored.

Project Structure

├── src/
│   ├── index.ts           # MCP Server entry point
│   ├── chatAgentTool.ts   # Tool implementations (chat_agent, create_branch, get_branch_details)
│   ├── gatekeeper.ts      # Input validation and quota enforcement
│   ├── strategyEngine.ts  # Parameter strategy mapping (call_type → temperature/top_p)
│   ├── nodeStore.ts       # Branch node storage and conclusion extraction
│   ├── schemas.ts         # Zod validation schemas and TypeScript types
│   ├── logger.ts          # Structured logging to stderr
│   └── polyfill.ts        # Node 14 fetch polyfill
├── test/
│   ├── comparisonTest.ts  # A/B comparison test
│   ├── testFramework.ts   # Interactive CLI test framework
│   ├── batchTest.ts       # Batch testing
│   ├── runA.js            # Scenario A test (DeepSeek)
│   ├── runB.js            # Scenario B test (DeepSeek)
│   └── config.json        # API configuration (gitignored)
├── .env.example           # Environment variable template
├── blueprint.md           # Project design blueprint (Chinese)
├── package.json
├── tsconfig.json
└── README.md

Development

# Build TypeScript
npm run build

# Start production server
npm run start

# Development mode (ts-node, no build step)
npm run dev

Design Philosophy

1. Self-Contained Task Descriptions — All context must be packed into input_text; tools never rely on conversation history
2. Context Isolation — Each tool call is stateless and independent, preventing context explosion in the main chain
3. Token Cost Optimization — Context is consumed by the cheaper non-thinking model's input tokens, not the thinking model's output tokens
4. Tree-Structured Reasoning — Complex problems are decomposed into independent branches, each analyzed separately, then synthesized

Benchmark: MCP Tools Impact on Output Quality

We conducted a controlled experiment comparing 3 approaches across 5 challenging engineering problems (distributed consensus, service mesh, RTOS kernel, columnar storage engine, multi-modal AI agent framework).

Test Groups

Key Results

What We Found

• With MCP tools, DeepSeek-V4-Flash produced 4.4x more detailed engineering solutions — including complete Go-style Raft consensus implementations, assembly-level RTOS scheduler code, and production-ready service mesh configurations
• Tree-structured thinking (create_branch) enabled the model to explore 5-6 levels deep on complex problems, creating subtrees for architecture, implementation, testing, and verification
• Cost comparison: GLM-5.2 costs 13x more than DeepSeek-V4-Flash pure thinking mode (¥0.75 vs ¥0.06) for comparable output quality. With tools enabled, DeepSeek-V4-Flash cost increased to ¥0.21 due to deeper exploration (3.7x more tokens), but remained 3.6x cheaper than GLM-5.2.
• Cache hit rates reached 68% during multi-round tool calls, dramatically reducing effective input costs via DeepSeek's prefix caching

Full experiment results and data: results/comparison/report.md

License

MIT