@j0hanz/thinkseq-mcp

v1.2.6

Published

2 days ago

An thinking and reasoning engine for the Model Context Protocol (MCP).

0High
0Medium
0Low

j0hanz

mcp model-context-protocol thinking reasoning

ThinkSeq MCP Server

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

One-click install

Overview

ThinkSeq exposes a single MCP tool, thinkseq, for structured, sequential thinking. The server runs over stdio and stores an in-memory thought history so it can return progress, active-path context, and revision metadata on each call.

Quick start

npx -y @j0hanz/thinkseq-mcp@latest

CLI options

thinkseq --max-thoughts 500 --max-memory-mb 100

Available flags:

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

Defaults and limits:

maxThoughts default: 500 (cap 10000).
maxMemoryBytes default: 100 MB (derived from --max-memory-mb).
packageReadTimeoutMs default: 2000 ms.
shutdownTimeoutMs default: 5000 ms.

MCP client configuration

Add this to your MCP client settings:

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

Add to your mcp.json (command palette: "MCP: Open Settings"):

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

Add to your claude_desktop_config.json:

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

Go to Cursor Settings > General > MCP.
Click Add New MCP Server.
Fill in the details:
- Name: thinkseq
- Type: command
- Command: npx -y @j0hanz/thinkseq-mcp@latest

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

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

Tool: `thinkseq`

Record a concise thinking step. Be brief: capture only the essential insight, calculation, or decision-like a minimal draft, not a verbose explanation.

Input

Output

The tool returns structuredContent with an ok flag. On success, result is populated; on error, error is populated.

Envelope fields:

Result fields:

Context fields:

Notes:

recentThoughts previews are truncated to 100 characters.
Revisions are a destructive rewind: they supersede the target thought and any later active thoughts in the active chain.
recentThoughts[].stepIndex is a contiguous 1-based index in the current active chain (useful when thought numbers become non-contiguous after revisions).

Error fields:

Example

Basic usage:

Input:

{
  "thought": "3 steps: parse -> validate -> transform"
}

Output (success):

{
  "ok": true,
  "result": {
    "thoughtNumber": 1,
    "totalThoughts": 3,
    "progress": 0.3333333333333333,
    "isComplete": false,
    "thoughtHistoryLength": 1,
    "hasRevisions": false,
    "activePathLength": 1,
    "revisableThoughts": [1],
    "context": {
      "recentThoughts": [
        {
          "stepIndex": 1,
          "number": 1,
          "preview": "3 steps: parse -> validate -> transform"
        }
      ]
    }
  }
}

Revising a thought:

If you realize an earlier step was wrong, use revisesThought to correct it:

Input:

{
  "thought": "Better approach: validate first, then parse",
  "revisesThought": 1
}

Output:

{
  "ok": true,
  "result": {
    "thoughtNumber": 2,
    "totalThoughts": 3,
    "progress": 0.6666666666666666,
    "isComplete": false,
    "thoughtHistoryLength": 2,
    "hasRevisions": true,
    "activePathLength": 1,
    "revisableThoughts": [2],
    "context": {
      "recentThoughts": [
        {
          "stepIndex": 1,
          "number": 2,
          "preview": "Better approach: validate first, then parse"
        }
      ],
      "revisionInfo": {
        "revises": 1,
        "supersedes": [1]
      }
    }
  }
}

Behavior and validation

Inputs are validated with Zod and unknown keys are rejected.
thoughtNumber is auto-incremented (1, 2, 3...).
totalThoughts defaults to 3, must be in 1-25, and is adjusted up to at least thoughtNumber.
The engine stores thoughts in memory and prunes when limits are exceeded:
- maxThoughts default: 500 (cap 10000). When exceeded, prunes the oldest 10% (minimum excess).
- maxMemoryBytes default: 100 MB. When exceeded and history is large, prunes roughly 20% of history.
- estimatedThoughtOverheadBytes default: 200.

Diagnostics

This server publishes events via node:diagnostics_channel:

thinkseq:tool for tool.start and tool.end (includes duration, errors, and request context).
thinkseq:lifecycle for lifecycle.started and lifecycle.shutdown.

Configuration

No environment variables or CLI flags are required for basic operation. The server runs over stdio, enforces MCP initialization order, and validates protocol versions. Invalid JSON-RPC message shapes and parse errors are surfaced as JSON-RPC errors on stdio.

Development

Prerequisites

Node.js >= 20.0.0

Scripts

Benchmark environment variables:

THINKSEQ_BENCH_SAMPLES (default: 1)
THINKSEQ_BENCH_NEW_ITERATIONS (default: 10000)
THINKSEQ_BENCH_REV_ITERATIONS (default: 1000)
THINKSEQ_BENCH_WARMUP (default: 1000)
THINKSEQ_BENCH_PIN (optional CPU affinity mask)

Project structure

src/
  app.ts           # Application setup and MCP wiring
  appConfig.ts     # Dependency wiring and shutdown handling
  engine.ts        # Core thinking engine
  engineConfig.ts  # Defaults and limits
  engine/          # Revision and query helpers
  lib/             # CLI, diagnostics, errors, protocol, stdio utilities
  schemas/         # Zod input/output schemas
  tools/           # MCP tool definitions (thinkseq)
tests/             # Node.js tests
benchmark/         # Benchmark targets
docs/              # Assets (logo)
dist/              # Build output
scripts/           # Quality gates and metrics helpers
metrics/           # Generated metrics outputs

Troubleshooting

CI workflow references npm run maintainability and npm run duplication, but these scripts are not defined in package.json.

Contributing

Contributions are welcome. Please open a pull request with a clear description and include relevant tests.