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

| Component | Technology | | --------------- | ---------------------------------------- | | Runtime | Node.js ≥ 24 | | Language | TypeScript 5.9+ | | MCP SDK | @modelcontextprotocol/sdk ^1.26.0 | | Validation | zod ^4.3.6 | | Test framework | Native Node.js Test Runner (node:test) | | Package manager | npm |

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

| Flag | Type | Description | | ------------------------------------ | ------ | ----------------------------------- | | --max-thoughts <number> | number | Max thoughts to keep in memory | | --max-memory-mb <number> | number | Max memory (MB) for stored thoughts | | --shutdown-timeout-ms <number> | number | Graceful shutdown timeout (ms) | | --package-read-timeout-ms <number> | number | Package.json read timeout (ms) | | -h, --help | flag | Show help text |

Engine Defaults

| Parameter | Default | Max | | ------------------------- | -------- | ------ | | Max thoughts per session | 500 | 10,000 | | Max memory | 100 MB | — | | Thought overhead estimate | 200 B | — | | Max sessions (LRU) | 50 | 10,000 | | Default total thoughts | 3 | 25 | | Default shutdown timeout | 5,000 ms | — | | Package read timeout | 2,000 ms | — |

Environment Variables

| Variable | Default | Description | | ------------------------------- | ------- | ------------------------------------------------------------------------------ | | THINKSEQ_INCLUDE_TEXT_CONTENT | true | Set to 0, false, no, or off to omit JSON string content from responses |

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:

| Name | Type | Required | Default | Description | | ---------------- | ------ | -------- | ----------- | -------------------------------------------------------------------------- | | thought | string | Yes | — | Your current thinking step (1–8,000 characters) | | sessionId | string | No | "default" | Session identifier to isolate thought histories (1–200 chars) | | totalThoughts | number | No | 3 | Estimated total thoughts (1–25) | | revisesThought | number | No | — | Revise a previous thought by number (≥ 1). Original is preserved for audit |

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:

| Code | Description | | ------------------------------ | ------------------------------------------ | | E_THINK | General processing error | | E_REVISION_MISSING | revisesThought required but not provided | | E_REVISION_TARGET_NOT_FOUND | Target thought number does not exist | | E_REVISION_TARGET_SUPERSEDED | Target thought was already superseded |

Resources

| URI | MIME Type | Description | | ------------------------- | --------------- | ------------------------- | | internal://instructions | text/markdown | Server usage instructions |

Prompts

| Name | Description | | ---------- | -------------------------------------- | | get-help | Get usage instructions for this server |

Client Configuration Examples

Add to your VS Code MCP settings (.vscode/mcp.json or User Settings):

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

Add to claude_desktop_config.json:

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

Add to Cursor MCP settings:

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

Or use the deeplink:

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

Add to ~/.codeium/windsurf/mcp_config.json:

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

| Script | Command | Purpose | | --------------- | -------------------------------------------- | ----------------------------------------------------------------- | | dev | tsc --watch --preserveWatchOutput | Watch mode TypeScript compilation | | dev:run | node --env-file=.env --watch dist/index.js | Run built server with auto-reload | | build | node scripts/tasks.mjs build | Full build pipeline (clean → compile → validate → assets → chmod) | | start | node dist/index.js | Run the built server | | test | node scripts/tasks.mjs test | Run all tests (builds first) | | test:coverage | node scripts/tasks.mjs test --coverage | Run tests with coverage | | type-check | node scripts/tasks.mjs type-check | TypeScript type checking | | lint | eslint . | Run ESLint | | lint:fix | eslint . --fix | Auto-fix lint issues | | format | prettier --write . | Format code with Prettier | | clean | node scripts/tasks.mjs clean | Remove dist and build info files | | inspector | npx @modelcontextprotocol/inspector | Launch MCP Inspector for debugging | | knip | knip | Detect unused exports/dependencies |

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

| Issue | Solution | | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Server not responding | Ensure Node.js ≥ 24 is installed; check node --version | | initialize must be first request | Client must send initialize before any other request | | notifications/initialized must follow initialize | Client must send notifications/initialized after successful initialize | | Thoughts disappearing | Check --max-thoughts and --max-memory-mb limits; old thoughts are pruned when limits are reached | | Session not found | Sessions are in-memory only; they reset on server restart. Max 50 sessions by default (LRU eviction) |

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