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 with numbered thoughts
• Branch exploration of alternative approaches (🌿)
• Thought revision to correct earlier reasoning (🔄)
• Detailed thinking logs for transparency and debugging

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

1. Configure Claude Desktop by editing:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

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

2. 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

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:

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

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.

Contributing

Contributions to the Code Reasoning MCP Server are welcome! Here's how to contribute:

1. Fork the repository
2. Create a feature branch:

   git checkout -b feature/your-feature-name

3. Make your changes
4. Run tests locally:

   npm run test:validate

5. Commit your changes:

   git commit -m "Add your meaningful commit message"

6. Push to your branch:

   git push origin feature/your-feature-name

7. Create a Pull Request

When you create a pull request, the CI workflow will automatically run to verify your changes. This includes linting, format checking, building, and testing. Your PR will show the status of these checks.

Continuous Integration

This project uses GitHub Actions for CI/CD:

• CI Workflow: Runs automatically on pull requests and pushes to main
• Release Workflow: Runs when a new release is created or a version tag is pushed
• Dependabot: Automatically opens PRs for dependency updates

License

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