ThinkSeq MCP Server


 


An MCP server for structured, sequential thinking with revision support.

Overview

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.

Key Features

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

Tech Stack

- Runtime: Node.js >=22.0.0
- Language: TypeScript 5.9+
- MCP SDK: @modelcontextprotocol/sdk
- Validation: zod

Repository Structure

``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
`

Requirements

- Node.js: Version 22.0.0 or higher.

Quickstart

To run the server using npx:

`bash
npx -y @j0hanz/thinkseq-mcp@latest
`

Installation

$3

This server is designed to be run directly via npx in your MCP client configuration.

`bash
npx -y @j0hanz/thinkseq-mcp@latest
`

$3

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
`

Configuration

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

MCP Surface

$3

#### 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."
}
]
}
}
}
`

$3

_No resources are currently exposed by this server._

$3

_No prompts are currently exposed by this server._

Client Configuration Examples

Security

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

Development Workflow

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
``

Contributing & License

This project is licensed under the MIT License.