ThinkSeq MCP Server

A thinking and reasoning engine for the Model Context Protocol (MCP). Enables AI assistants to capture structured, sequential reasoning chains with full revision (destructive rewind) support, session isolation, and progress tracking.

Overview

ThinkSeq provides an MCP server that exposes a single thinkseq tool for recording concise thinking steps. Each step is stored in-memory within isolated sessions, and the engine supports revising earlier steps — superseding the target and all subsequent active thoughts while preserving the full audit trail. The server communicates exclusively over stdio transport.

Key Features

• Sequential thinking steps — Record atomic reasoning steps (up to 8,000 characters each) in order
• Destructive revision (rewind) — Revise any active thought; the target and all later thoughts are superseded, continuing from the corrected step
• Session isolation — Multiple independent thought histories via session IDs with pinned LRU eviction (default: 50 sessions)
• Progress tracking — Automatic progress (0–1) and isComplete signals returned with every response

Tech Stack

Architecture

1. CLI parses arguments (--max-thoughts, --max-memory-mb, etc.)
2. run() resolves dependencies and reads package.json for server identity
3. McpServer is created with embedded instructions, the thinkseq tool, internal://instructions resource, and get-help prompt
4. StdioServerTransport connects the server (stdio only)
5. Stdio guards are installed: initialization enforcement, invalid message rejection, parse error responder
6. Shutdown handlers listen for SIGTERM/SIGINT and gracefully close server, engine, and transport within a configurable timeout

Repository Structure

thinkseq-mcp/
├── src/
│   ├── appConfig/        # Environment, run dependencies, shutdown, types
│   ├── engine/           # Revision logic, thought queries, thought store
│   ├── lib/              # CLI, context, diagnostics, errors, MCP logging, stdio guards
│   ├── schemas/          # Zod input/output schemas
│   ├── tools/            # MCP tool registration (thinkseq)
│   ├── app.ts            # Core application wiring and lifecycle
│   ├── engine.ts         # ThinkingEngine class (session management, processing)
│   ├── engineConfig.ts   # Engine constants and defaults
│   ├── index.ts          # Entry point (CLI → run)
│   └── instructions.md   # Server instructions (bundled as resource/prompt)
├── tests/                # Unit and integration tests
├── scripts/
│   └── tasks.mjs         # Custom build/test task runner
├── assets/
│   └── logo.svg          # Server icon
├── package.json
└── tsconfig.json

Requirements

• Node.js ≥ 24
• npm (included with Node.js)

Quickstart

npx -y @j0hanz/thinkseq-mcp@latest

Add to your MCP client configuration:

{
  "mcpServers": {
    "thinkseq": {
      "command": "npx",
      "args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
    }
  }
}

Installation

NPX (recommended)

npx -y @j0hanz/thinkseq-mcp@latest

Global Install

npm install -g @j0hanz/thinkseq-mcp
thinkseq

From Source

git clone https://github.com/j0hanz/thinkseq-mcp-server.git
cd thinkseq-mcp-server
npm install
npm run build
npm start

Configuration

CLI Arguments

Engine Defaults

Environment Variables

Usage

stdio (default and only transport)

# Direct
npx -y @j0hanz/thinkseq-mcp@latest

# With options
npx -y @j0hanz/thinkseq-mcp@latest --max-thoughts 1000 --max-memory-mb 200

MCP Surface

Tools

thinkseq

Record a concise thinking step. Supports sequential appending and destructive revision of prior steps.

Parameters:

Returns (structured output):

{
  "ok": true,
  "result": {
    "thoughtNumber": 1,
    "totalThoughts": 3,
    "progress": 0.333,
    "isComplete": false,
    "thoughtHistoryLength": 1,
    "hasRevisions": false,
    "activePathLength": 1,
    "revisableThoughts": [1],
    "revisableThoughtsTotal": 1,
    "context": {
      "recentThoughts": [
        {
          "stepIndex": 1,
          "number": 1,
          "preview": "First step of reasoning..."
        }
      ]
    }
  }
}

Revision example:

{
  "thought": "Better approach: use caching instead",
  "revisesThought": 2
}

Returns additional revisionInfo in context:

{
  "context": {
    "recentThoughts": [...],
    "revisionInfo": {
      "revises": 2,
      "supersedes": [2, 3],
      "supersedesTotal": 2
    }
  }
}

Error codes:

Resources

Prompts

Client Configuration Examples

{
  "mcpServers": {
    "thinkseq": {
      "command": "npx",
      "args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "thinkseq": {
      "command": "npx",
      "args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "thinkseq": {
      "command": "npx",
      "args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
    }
  }
}

cursor://anysphere.cursor-deeplink/mcp/install?name=thinkseq&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovdGhpbmtzZXEtbWNwQGxhdGVzdCJdfQ==

{
  "mcpServers": {
    "thinkseq": {
      "command": "npx",
      "args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
    }
  }
}

Security

stdio Transport

• stdout protection: console.log and console.warn are bridged to MCP logging messages to prevent polluting the JSON-RPC stdio channel.
• Initialization enforcement: The server rejects any request before a valid initialize handshake and requires notifications/initialized before accepting tool calls.
• Invalid message rejection: Non-object and batch JSON-RPC messages are rejected with proper error codes.
• Parse error handling: Malformed JSON on stdin receives a JSON-RPC Parse Error response.

Process Safety

• Unhandled rejections and uncaught exceptions are caught and result in a clean process exit.
• Graceful shutdown on SIGTERM/SIGINT with configurable timeout (default: 5 seconds).

Development Workflow

Install Dependencies

npm install

Scripts

Build and Release

The build pipeline (npm run build) executes:

1. Clean — Remove dist/ and .tsbuildinfo files
2. Compile — TypeScript compilation via tsconfig.build.json
3. Validate — Ensure src/instructions.md exists
4. Copy assets — Bundle instructions.md and assets/ (including logo.svg) into dist/
5. Make executable — Set dist/index.js to mode 755

Publishing

Publishing is automated via GitHub Actions (.github/workflows/publish.yml):

• Triggered on GitHub release publication
• Pipeline: lint → type-check → test → coverage → build → npm publish --access public
• Uses npm Trusted Publishing (OIDC) for authentication

Troubleshooting

MCP Inspector

Use the MCP Inspector to debug and test the server interactively:

npx @modelcontextprotocol/inspector

Common Issues

stdout/stderr Guidance

When running as a stdio MCP server, never write directly to stdout from custom code — this would corrupt the JSON-RPC protocol. The server automatically bridges console.log/console.warn to MCP logging. Use console.error for debug output that bypasses MCP.

License

MIT