@j0hanz/thinkseq-mcp

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

• CLI parses arguments (--max-thoughts, --max-memory-mb, etc.)
• run() resolves dependencies and reads package.json for server identity
• McpServer is created with embedded instructions, the thinkseq tool, internal://instructions resource, and get-help prompt
• StdioServerTransport connects the server (stdio only)
• Stdio guards are installed: initialization enforcement, invalid message rejection, parse error responder
• 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

VS Code / VS Code Insiders

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

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

Claude Desktop

Add to claude_desktop_config.json:

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

Cursor

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

Windsurf

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:

• Clean — Remove dist/ and .tsbuildinfo files
• Compile — TypeScript compilation via tsconfig.build.json
• Validate — Ensure src/instructions.md exists
• Copy assets — Bundle instructions.md and assets/ (including logo.svg) into dist/
• 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