Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@mettamatt/code-reasoning) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Code Reasoning MCP Server

A Model Context Protocol (MCP) server that enhances Claude's ability to solve complex programming tasks through structured, step-by-step thinking.

What Is This?

Code Reasoning is a tool that helps Claude break down complex programming problems into manageable steps using sequential thinking methodology. It enables:

Step-by-step reasoning about code problems
Exploring alternative approaches through branching
Revising earlier reasoning when needed
Detailed logging of the thinking process

While based on the sequential thinking approach, this server is specifically optimized for programming tasks and code analysis, hence the name "Code Reasoning".

Quick Installation

# Option 1: Use with npx (recommended for most users)
npx @mettamatt/code-reasoning

# Option 2: Install globally
npm install -g @mettamatt/code-reasoning

Using with Claude

Configure Claude Desktop by editing: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "code-reasoning": {
      "command": "npx",
      "args": ["-y", "@mettamatt/code-reasoning"]
    }
  }
}

Ask Claude to use sequential thinking in your prompts:

Please analyze this code using sequential-thinking to break down the solution step by step.

Command Line Options

--debug: Enable detailed logging
--help or -h: Show help information

Key Features

Programming Focus: Optimized for coding tasks and problem-solving
Structured Thinking: Break down complex problems into manageable steps
Thought Branching: Explore multiple solution paths in parallel
Thought Revision: Refine earlier reasoning as understanding improves
Safety Limits: Automatically stops after 20 thought steps to prevent loops
Advanced Debugging: Comprehensive logging system

Documentation

Detailed documentation available in the docs directory:

Usage Examples: Examples of sequential thinking
Configuration Guide: All configuration options
Publishing Guide: Version management and publishing
Testing Framework: Testing information

Advanced Installation

To install from source:

git clone https://github.com/mettamatt/code-reasoning.git
cd code-reasoning
npm install
npm run build
npm link

Project Structure

├── index.ts                  # Entry point
├── src/                      # Implementation source files
└── test/                     # Testing framework

VS Code Integration

Configure in your VS Code settings:

{
  "mcp": {
    "servers": {
      "code-reasoning": {
        "command": "npx",
        "args": ["-y", "@mettamatt/code-reasoning"]
      }
    }
  }
}

Troubleshooting

For debugging issues, use the --debug flag and check logs at ~/.code-reasoning/logs/latest.log
For parameter errors, ensure snake_case format (e.g., thought_number, not thoughtNumber)

Run tests using:

npm test                # Run basic tests
npm run test:verbose    # Run with verbose output
npm run test:basic      # Run basic test scenarios
npm run test:branch     # Run branching test scenarios
npm run test:revision   # Run revision test scenarios

Evaluate prompt effectiveness:

npm run eval            # Run prompt evaluation system

Prompt Evaluation

The Code Reasoning MCP Server includes a prompt evaluation system that assesses Claude's ability to follow the code reasoning prompts. This system allows:

Testing different prompt variations against scenario problems
Verifying parameter format adherence
Scoring solution quality
Generating comprehensive reports

To use the prompt evaluation system, run:

npm run eval

Prompt Comparison and Development

Significant effort went into developing the optimal prompt for the Code Reasoning server. The current implementation uses the HYBRID_DESIGN prompt, which emerged as the winner from our evaluation process.

We compared four different prompt designs:

Prompt Design	Description
SEQUENTIAL	The original sequential thinking prompt design
DEFAULT	The baseline prompt previously used in the server
CODE_REASONING_0_30	An experimental variant focusing on code-specific reasoning
HYBRID_DESIGN	A refined design incorporating the best elements of other approaches

Our evaluation across seven diverse programming scenarios showed that HYBRID_DESIGN outperformed other prompts:

Scenario	HYBRID_DESIGN	CODE_REASONING_0_30	DEFAULT	SEQUENTIAL
Algorithm Selection	87%	82%	88%	82%
Bug Identification	87%	91%	88%	92%
Multi-Stage Implementation	83%	67%	79%	82%
System Design Analysis	82%	87%	78%	82%
Code Debugging Task	92%	87%	92%	92%
Compiler Optimization	83%	78%	67%	73%
Cache Strategy	86%	88%	82%	87%
Average	86%	83%	82%	84%

The HYBRID_DESIGN prompt marginally demonstrated both the highest average solution quality (86%) and the most consistent performance across all scenarios, with no scores below 80%. It also prodouced the most thoughts. The src/server.ts file has been updated to use this optimal prompt design.

Personally, I think the biggest improvement was adding this to the end of the prompt: "✍️ End each thought by asking: "What am I missing or need to reconsider?"

See Testing Framework for more details on the prompt evaluation system.

License

This project is licensed under the MIT License. See the LICENSE file for details.