Code Reasoning MCP Server

An enhanced fork of the Sequential Thinking MCP server, optimized for programming tasks and complex problem-solving through a structured thinking process.

Quick Start

# Install globally
npm install -g code-reasoning

# Configure Claude Desktop
# Edit ~/Library/Application Support/Claude-Desktop/claude_desktop_config.json:
{
  "mcpServers": {
    "sequential-thinking": {
      "command": "code-reasoning",
      "args": []
    }
  }
}

# Start Claude Desktop and enjoy enhanced sequential thinking!

Why This Fork?

This fork was created to enhance the original Sequential Thinking server with several key improvements:

Programming Focus: Optimized for coding tasks and programming problem-solving
Improved Parameter Naming: Consistent snake_case naming convention (e.g., thought_number instead of thoughtNumber)
Enhanced Prompting: Clearer, more structured guidance in the tool description
Enforcement of Best Practices: Automatically aborts chains after 20 steps to prevent excessive recursion
Local Development: Designed to work seamlessly with Claude Desktop for programming tasks

Key Differences from Original

Feature	Original	Code Reasoning
Parameter Style	camelCase	snake_case
Max Steps	Not enforced	Enforced (max 20)
Tool Description	Basic	Enhanced markdown with examples
Primary Focus	General problem-solving	Programming/code tasks
Error Handling	Basic	Improved with status codes

Enhanced Prompt

This fork features a significantly improved prompt that provides clearer guidance and examples:

🧠 **Sequential Thinking Tool**

Purpose → break complex problems into **self-auditing, exploratory** thought steps that can *branch*, *revise*, or *back-track* until a **single, well-supported answer** emerges.

---

## WHEN TO CALL
• Multi-step planning, design, debugging, or open-ended analysis  
• Whenever *further private reasoning* or *hypothesis testing* is required **before** replying to the user

---

## ENCOURAGED PRACTICES
🔍 **Question aggressively** – ask "What am I missing?" after each step  
🔄 **Revise freely** – mark `is_revision=true` even late in the chain  
🌿 **Branch often** – explore plausible alternatives in parallel; you can merge or discard branches later  
↩️ **Back-track** – if a path looks wrong, start a new branch from an earlier thought  
❓ **Admit uncertainty** – explicitly note unknowns and schedule extra thoughts to resolve them

---

## MUST DO
✅ Put **every** private reasoning step in `thought`  
✅ Keep `thought_number` correct; update `total_thoughts` when scope changes  
✅ Use `is_revision` & `branch_from_thought`/`branch_id` precisely  
✅ Set `next_thought_needed=false` *only* when **all** open questions are resolved  
✅ Abort and summarise if `thought_number > 20`  

---

## DO NOT
⛔️ Reveal the content of `thought` to the end-user  
⛔️ Continue thinking once `next_thought_needed=false`  
⛔️ Assume thoughts must proceed strictly linearly – *branching is first-class*

---

### PARAMETER CHEAT-SHEET
• `thought` (string) – current reasoning step  
• `next_thought_needed` (boolean) – request further thinking?  
• `thought_number` (int ≥ 1) – 1-based counter  
• `total_thoughts` (int ≥ 1) – mutable estimate  
• `is_revision`, `revises_thought` (int) – mark corrections  
• `branch_from_thought`, `branch_id` – manage alternative paths  
• `needs_more_thoughts` (boolean) – optional hint that more thoughts may follow  

_All JSON keys **must** use `lower_snake_case`._

---

### EXAMPLE ✔️
```json
{
  "thought": "List solution candidates and pick the most promising",
  "thought_number": 1,
  "total_thoughts": 4,
  "next_thought_needed": true
}

EXAMPLE ✔️ (branching late)

{
  "thought": "Alternative approach: treat it as a graph-search problem",
  "thought_number": 6,
  "total_thoughts": 8,
  "branch_from_thought": 3,
  "branch_id": "B1",
  "next_thought_needed": true
}

Features

Break down complex programming problems into manageable steps
Revise and refine thoughts as understanding deepens
Branch into alternative paths of reasoning
Adjust the total number of thoughts dynamically
Generate and verify solution hypotheses
Enforce a maximum of 20 thought steps to prevent excessive reasoning

Tool

sequentialthinking

Facilitates a detailed, step-by-step thinking process for programming and technical problem-solving.

Inputs:

thought (string): The current thinking step
next_thought_needed (boolean): Whether another thought step is needed
thought_number (integer): Current thought number
total_thoughts (integer): Estimated total thoughts needed
is_revision (boolean, optional): Whether this revises previous thinking
revises_thought (integer, optional): Which thought is being reconsidered
branch_from_thought (integer, optional): Branching point thought number
branch_id (string, optional): Branch identifier
needs_more_thoughts (boolean, optional): If more thoughts are needed

Important: All parameters must use snake_case format (e.g., thought_number, not thoughtNumber). The server will reject requests using camelCase parameters.

Usage

The Code Reasoning tool is designed for:

Breaking down complex programming problems into steps
Algorithm design and optimization
Debugging and error analysis
Code architecture planning
Technical decision-making when multiple approaches exist
Understanding complex codebases

Configuration

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "code-reasoning",
      "args": []
    }
  }
}

Location of Claude Desktop config file on macOS:

~/Library/Application Support/Claude-Desktop/claude_desktop_config.json

Usage with VS Code

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open Settings (JSON).

Optionally, you can add it to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others.

{
  "mcp": {
    "servers": {
      "sequential-thinking": {
        "command": "code-reasoning",
        "args": []
      }
    }
  }
}

Installation

# Create the directory
mkdir -p ~/Sites/code-reasoning

# Copy files from original repository (if you have it)
cp -r /path/to/mcp-servers/src/sequentialthinking/* ~/Sites/code-reasoning/

# Navigate to the directory
cd ~/Sites/code-reasoning

# Update package.json and index.ts with the custom changes

# Install dependencies
npm install

# Build the package
npm run build

# Install globally
npm link

Troubleshooting

TypeScript Configuration Error

If you encounter an error like:

error TS5083: Cannot read file '/tsconfig.json'.

This is because the original tsconfig.json extends a parent configuration. Update your tsconfig.json to be self-contained:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "rootDir": ".",
    "declaration": true
  },
  "include": ["./**/*.ts"]
}

Parameter Naming Errors

If Claude receives errors from the server, ensure all parameters use snake_case:

Use thought_number instead of thoughtNumber
Use next_thought_needed instead of nextThoughtNeeded
Use total_thoughts instead of totalThoughts

Keeping Up-to-Date with Upstream

This is a fork of the original Sequential Thinking server. To incorporate updates from the original while maintaining our customizations:

Check for updates to the original repository:
cd /path/to/original/mcp-servers git pull
Compare the changes to our fork:
diff -r /path/to/original/mcp-servers/src/sequentialthinking/ ~/Sites/code-reasoning/
Selectively incorporate updates:
- Update dependencies to match the original (especially important for SDK updates)
- Add new features or bug fixes while maintaining our snake_case naming conventions
- Update the tool description if improvements are made to the original
Rebuild and reinstall after updating:
npm install npm run build npm link

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.