An thinking and reasoning engine for the Model Context Protocol (MCP).
npm install @j0hanz/thinkseq-mcp
 

An MCP server for structured, sequential thinking with revision support.
ThinkSeq exposes a single MCP tool, thinkseq, that enables Language Models to "think" in a structured, step-by-step manner. It maintains an in-memory history of thoughts, calculates progress, and critically allows for destructive revision—where a model can realize a mistake, "rewind" to a previous step, and branch off with a correction. This capability mirrors human reasoning patterns and improves problem-solving accuracy for complex tasks.
- Sequential Thinking: Records thoughts as discrete steps with auto-incrementing numbers.
- Progress Tracking: Automatically calculates progress (0.0 to 1.0) based on estimated total thoughts.
- Revision Support: Allows models to revise specific past thoughts, superseding the old path and starting a new reasoning branch.
- Context Awareness: Returns recent thoughts and revision context with every tool call to keep the model grounded.
- Session Isolation: Supports multiple concurrent thinking sessions via sessionId.
- Memory Management: Configurable limits for max thoughts and memory usage to prevent resource exhaustion.
- Runtime: Node.js >=22.0.0
- Language: TypeScript 5.9+
- MCP SDK: @modelcontextprotocol/sdk
- Validation: zod
``text`
c:\thinkseq-mcp
├── dist/ # Compiled JavaScript
├── src/
│ ├── app.ts # Application entry and MCP wiring
│ ├── engine.ts # Core thinking engine logic
│ ├── engineConfig.ts # Configuration defaults
│ ├── index.ts # CLI entrypoint
│ ├── lib/ # Utilities (CLI, logging, types)
│ ├── schemas/ # Zod schemas for inputs/outputs
│ └── tools/ # MCP tool definitions
├── package.json
└── tsconfig.json
- Node.js: Version 22.0.0 or higher.
To run the server using npx:
`bash`
npx -y @j0hanz/thinkseq-mcp@latest
Quick Test with MCP Inspector
You can inspect the tools using the MCP Inspector:
`bash`
npx @modelcontextprotocol/inspector npx -y @j0hanz/thinkseq-mcp@latest
This server is designed to be run directly via npx in your MCP client configuration.
`bash`
npx -y @j0hanz/thinkseq-mcp@latest
1. Clone the repository:
`bash`
git clone https://github.com/j0hanz/thinkseq-mcp-server.git
cd thinkseq-mcp-server
2. Install dependencies:
`bash`
npm install
3. Build the project:
`bash`
npm run build
4. Run the server:
`bash`
node dist/index.js
The server is configured via CLI arguments.
| Argument | Description | Default |
| :----------------------------------- | :-------------------------------------------- | :------ |
| --max-thoughts | Max thoughts to keep in memory before pruning | 500 |--max-memory-mb
| | Max memory (MB) for stored thoughts | 100 |--shutdown-timeout-ms
| | Graceful shutdown timeout in ms | 5000 |--package-read-timeout-ms
| | Package.json read timeout in ms | 2000 |-h, --help
| | Show help message | - |
#### thinkseq
Record a concise thinking step. Be brief: capture only the essential insight, calculation, or decision.
Parameters:
| Name | Type | Required | Description |
| :--------------- | :------ | :------: | :-------------------------------------------------------------------------------------------------------------------- |
| thought | string | Yes | Your current thinking step (1-8000 chars). |sessionId
| | string | No | Optional session identifier (max 200 chars) to isolate thought histories. |totalThoughts
| | integer | No | Estimated total thoughts (1-25, default: 3). |revisesThought
| | integer | No | Revise a previous thought by number. The original is preserved for audit, but the active chain rewinds to this point. |
Returns:
A JSON object containing the current state of the thinking process, including:
- thoughtNumber: The current step number.progress
- : A value between 0 and 1 indicating completion.isComplete
- : Boolean indicating if the thought process is finished.revisableThoughts
- : Array of thought numbers that can be revised.context
- : Recent thoughts and revision information.
Example Input:
`json`
{
"thought": "I need to calculate the fibonacci sequence up to 10.",
"totalThoughts": 5
}
Example Output:
`json`
{
"ok": true,
"result": {
"thoughtNumber": 1,
"totalThoughts": 5,
"progress": 0.2,
"isComplete": false,
"revisableThoughts": [1],
"context": {
"recentThoughts": [
{
"stepIndex": 1,
"number": 1,
"preview": "I need to calculate the fibonacci sequence up to 10."
}
]
}
}
}
_No resources are currently exposed by this server._
_No prompts are currently exposed by this server._
VS Code (mcp.json)
`json`
{
"mcpServers": {
"thinkseq": {
"command": "npx",
"args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
}
}
}
Claude Desktop
Add this to your claude_desktop_config.json:
`json`
{
"mcpServers": {
"thinkseq": {
"command": "npx",
"args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
}
}
}
Cursor
1. Navigate to Settings > General > MCP.
2. Click Add New MCP Server.
3. Name: thinkseqcommand
4. Type: npx -y @j0hanz/thinkseq-mcp@latest
5. Command:
- Stdio Transport: This server runs over stdio. It creates a console bridge to intercept console.log calls and redirect them to standard error (stderr) to prevent interfering with the JSON-RPC protocol.
- Memory Limits: The server enforces maximum thought counts and memory usage limits (configurable via CLI) to prevent memory exhaustion attacks.
- Input Validation: All inputs are strictly validated using Zod schemas.
1. Install dependencies:
`bash`
npm install
2. Run in development mode:
`bash`
npm run dev # Runs tsc in watch mode
npm run dev:run # Runs the built app in watch mode
3. Run tests:
`bash`
npm test
4. Lint and Format:
`bash``
npm run lint
npm run format
This project is licensed under the MIT License.