https://github.com/mettamatt/code-reasoning
A code reasoning MCP server, a fork of sequential-thinking
https://github.com/mettamatt/code-reasoning
Last synced: about 1 month ago
JSON representation
A code reasoning MCP server, a fork of sequential-thinking
- Host: GitHub
- URL: https://github.com/mettamatt/code-reasoning
- Owner: mettamatt
- License: mit
- Created: 2025-04-23T15:59:18.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-08-11T23:18:29.000Z (about 2 months ago)
- Last Synced: 2025-08-21T17:40:36.599Z (about 2 months ago)
- Language: TypeScript
- Size: 736 KB
- Stars: 191
- Watchers: 2
- Forks: 17
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-mcp-servers - mettamatt/code-reasoning - solving capabilities by breaking down complex programming tasks into manageable steps using structured, sequential thinking. (✨ Code Analysis & Quality)
- awesome-mcp-servers - **mettamatt/code-reasoning** - Enhances Claude's problem-solving capabilities by breaking down complex programming tasks into manageable steps using structured, sequential thinking. `http` `git` `github` (Other)
- awesome-mcp-servers - **mettamatt/code-reasoning** - Enhances Claude's problem-solving capabilities by breaking down complex programming tasks into manageable steps using structured, sequential thinking. `http` `git` `github` (Other)
- mcp-index - Code Reasoning - Enhances the ability to solve complex programming tasks by breaking them down into structured, step-by-step reasoning. Provides detailed logging and alternative solution paths to improve code analysis and problem-solving capabilities. (Developer Tools)
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.
[](https://www.npmjs.com/package/@mettamatt/code-reasoning)
[](https://opensource.org/licenses/MIT)
[](https://github.com/mettamatt/code-reasoning/actions/workflows/ci.yml)
## Quick Installation
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`
```json
{
"mcpServers": {
"code-reasoning": {
"command": "npx",
"args": ["-y", "@mettamatt/code-reasoning"]
}
}
}
```
2. Configure VS Code:
```json
{
"mcp": {
"servers": {
"code-reasoning": {
"command": "npx",
"args": ["-y", "@mettamatt/code-reasoning"]
}
}
}
}
```
## Usage
1. To trigger this MCP, append this to your chat messages:
```
Use sequential thinking to reason about this.
```
2. Use ready-to-go prompts that trigger Code-Reasoning:
- Click the "+" icon in the Claude Desktop chat window, or in Claude Code type `/help` to see the specific commands.
- Select "Add from Code Reasoning" from the available tools
- Choose a prompt template and fill in the required information
- Submit the form to add the prompt to your chat message and hit return
See the [Prompts Guide](./docs/prompts.md) for details on using the prompt templates.
## 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
- **Ready-to-Use Prompts**: Pre-defined templates for common development tasks
## Documentation
Detailed documentation available in the docs directory:
- [Usage Examples](./docs/examples.md): Examples of sequential thinking with the MCP server
- [Configuration Guide](./docs/configuration.md): All configuration options for the MCP server
- [Prompts Guide](./docs/prompts.md): Using and customizing prompts with the MCP server
- [Testing Framework](./docs/testing.md): Testing information
## Project Structure
```
├── index.ts # Entry point
├── src/ # Implementation source files
└── test/ # Testing framework
```
## 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
To use the prompt evaluation system, run:
```bash
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 | 89% | 82% | 92% | 88% |
| Bug Identification | 92% | 91% | 88% | 94% |
| Multi-Stage Implementation | 87% | 67% | 82% | 87% |
| System Design Analysis | 87% | 87% | 83% | 82% |
| Code Debugging Task | 96% | 87% | 91% | 93% |
| Compiler Optimization | 83% | 78% | 72% | 78% |
| Cache Strategy | 87% | 88% | 89% | 87% |
| **Average** | **89%** | **83%** | **85%** | **87%** |
The HYBRID_DESIGN prompt demonstrates the highest average solution quality (89%) and the most consistent performance across all scenarios, with no scores below 80%. It also produces 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](./docs/testing.md) for more details on the prompt evaluation system.
## License
This project is licensed under the MIT License. See the LICENSE file for details.