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	Type	Default	Description
input_text	string	required	Complete, self-contained task description with all context
system_prompt	string	optional	System prompt for role/behavior constraints
temperature	number	0.7	Sampling temperature (0.0–2.0). Low = precise, high = creative
top_p	number	0.9	Nucleus sampling threshold (0.0–1.0)
max_tokens	number	4096	Maximum output tokens (enforced server-side via API)
stop	string[]	[]	Stop sequences; empty array = natural completion
seed	number	optional	Random seed for reproducible output (with low temperature)

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

Parameter	Type	Default	Description
session_id	string	required	Session ID, consistent within a single reasoning session
input_text	string	required	Self-contained subtask description (≥30 characters)
call_type	string	drill_down	Branch type: drill_down / verify / explore / stash
parent_node_id	string	trunk	Parent node ID for tree nesting

Four Branch Types:

Type	Temperature	Purpose
drill_down	0.2	Deep-dive into a subproblem with focused precision
verify	0.0	Verify a conclusion or hypothesis with maximal determinism
explore	1.0	Divergent thinking from different angles with high creativity
stash	0.6	Temporarily record intermediate thoughts for later reference

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

Parameter	Type	Default	Description
session_id	string	required	Session ID
node_id	string	required	Branch node ID returned by create_branch

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
}

Error Type	action	Trigger
network	retry	DNS resolution failure, connection refused
api	backoff	429 rate limited
api	report	401 authentication failure
api	retry	5xx server errors
validation	fix_input	Empty input_text
config	report	Missing API Key / Model configuration

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

Script	Description
test/testFramework.ts	Interactive CLI test framework
test/comparisonTest.ts	Automated A/B comparison (with-tool vs without-tool)
test/runA.js	Scenario A: thinking model + tools (standalone, DeepSeek)
test/runB.js	Scenario B: pure thinking model (standalone, DeepSeek)
test/batchTest.ts	Batch end-to-end tests

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

Group	Model	API	Tools
A	GLM-5.2	SiliconFlow	None
B	DeepSeek-V4-Flash	DeepSeek Official	chat_agent + create_branch
C	DeepSeek-V4-Flash	DeepSeek Official	None

Key Results

Metric	A (GLM-5.2)	B (DS + Tools)	C (DS Pure)
Total Output	38,888 chars	169,484 chars 🏆	57,565 chars
Total Time	705s	1,516s	239s 🏆
Total Tokens	28,459	210,482	29,184
Total Cost	¥0.75	¥0.21	¥0.06 🏆
Avg Output/Question	7,778 chars	33,897 chars (4.4x) 🏆	11,513 chars
Tool Calls	0	30 🏆	0
Cache Hit Rate	0%	up to 68% 🏆	0%

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