Think MCP

Structured reasoning tools for MCP-compatible LLM clients

Reason step by step, branch when needed, block weak finals, and keep useful memory across sessions.

Install | Tools | think_cycle | Quality Gates | Changelog

Why this exists

Most LLM workflows fail in predictable ways:

• They answer too early.
• They stay linear when the task needs alternatives or critique.
• They lose earlier insights between steps.
• They finish with confidence that is not backed by verification.

Think MCP adds an external reasoning layer for those failures. It does not replace the model's intelligence. It constrains and structures the way that intelligence is used.

What is in 5.6.0

• Added explicit coaching, completion blockers, and deterministic next-action routing for models.
• Made finalized cycles terminal, restart-safe, and idempotent, including insight retries.
• Rejected blank summaries and disconnected winning paths before state or insights are committed.
• Kept omitted confidence optional instead of inventing false low-confidence failures.
• Strengthened deep logic guidance with source evidence and an attempted refutation.
• Replaced title-only regex evals with executable MCP and cycle behavioral tests.

Core model

Think MCP combines three layers:

| Layer | Role | Outcome | | :--- | :--- | :--- | | think / think_batch | Capture incremental or prebuilt reasoning | Better decomposition, branching, revisions | | think_cycle | Enforce adaptive depth and hard final gate | Blocks shallow or weak final answers | | Recall + coaching + validation | Preserve useful context and warn on weak patterns | Better consistency and fewer dead-end sessions |

Install

Run directly

npx -y @gofman3/think-mcp

MCP config

{
  "mcpServers": {
    "think": {
      "command": "npx",
      "args": ["-y", "@gofman3/think-mcp"]
    }
  }
}

Local development

npm install
npm run build
npm test

Toolset

| Tool | Purpose | Best use | | :--- | :--- | :--- | | think | Add one structured reasoning step | Medium-complexity tasks that need guided progression | | think_batch | Submit one already-built reasoning chain | Fast validation of a complete prebuilt chain | | think_cycle | Adaptive reasoning state machine with a hard process gate | High-risk or high-complexity tasks | | think_logic | Return a read-only analysis checklist | Choosing methodology before doing an audit | | think_recall | Search the active scope or stored insights | Reuse patterns, avoid repeating dead ends | | think_done | Finalize a think or think_batch scope | Controlled non-cycle completion | | think_reset | Clear the active scope state | Hard context shift only |

think_cycle

think_cycle is the main depth-control tool in the current release.

It runs a session as a state machine:

start -> step -> status -> finalize

If the reasoning process is incomplete, finalize does not silently pass. It blocks completion and returns one concrete next action plus the required minimum of additional thoughts.

Key behavior

• Adaptive required depth based on goal complexity and risk markers.
• Hard gate for phase coverage: decompose, alternative, critique, synthesis, verification.
• Structural quality score with penalties for repetition, weak verification, and unstable confidence. It does not pretend to judge semantic truth.
• Confidence is optional; stability is reported only after two scored steps instead of inventing missing data.
• Explicit constraintCheck before finalizing a session that started with constraints.
• Terminal completion: a completed cycle keeps its approved answer, rejects new steps, and retries a failed deduplicated insight save safely.
• Fallback interop with the regular think backend when backendMode=auto.
• Loop budget control to avoid infinite cost and latency growth.

Input shape

{
  action: 'start' | 'step' | 'status' | 'finalize' | 'reset',
  sessionId?: string,
  scopeId?: string,
  goal?: string,
  context?: string,
  constraints?: string[],
  thought?: string,
  thoughtType?: 'decompose' | 'alternative' | 'critique' | 'synthesis' | 'verification' | 'revision',
  confidence?: number,
  finalAnswer?: string,
  constraintCheck?: string,
  backendMode?: 'auto' | 'independent' | 'think',
  maxLoops?: number,
  showTrace?: boolean,
  exportReport?: 'markdown' | 'json',
  includeMermaid?: boolean
}

Output shape

{
  status: 'in_progress' | 'blocked' | 'ready' | 'completed' | 'error',
  sessionId: string,
  scopeId?: string,
  loop: { current: number, max: number, required: number, remaining: number },
  quality: {
    overall: number,
    coverage: number,
    critique: number,
    verification: number,
    diversity: number,
    confidenceStability?: number
  },
  gate: { passed: boolean, reasonCodes: string[] },
  requiredMoreThoughts: number,
  nextPrompts: string[],
  shortTrace?: string[],
  finalApprovedAnswer?: string
}

Example flow

// 1. Start
{
  action: 'start',
  goal: 'Design a safe migration from Redis session cache to Postgres-backed sessions',
  constraints: ['zero logout spike', 'rollback in under 5 minutes'],
  backendMode: 'auto'
}

// 2. Add steps
{
  action: 'step',
  sessionId: 'cycle_xxx',
  thought: 'Break the migration into dual-write, read-fallback, rollout metrics, and rollback paths.'
}

// 3. Try to finalize
{
  action: 'finalize',
  sessionId: 'cycle_xxx',
  finalAnswer: 'We should migrate in phases and monitor it carefully...'
}

Typical blocked response:

{
  status: 'blocked',
  gate: { passed: false, reasonCodes: ['MISSING_PHASE_VERIFICATION'] },
  requiredMoreThoughts: 1,
  nextPrompts: [
    'Next: think_cycle step with thoughtType="verification" — define tests, metrics, and rollback triggers.'
  ]
}

Other tools

think

Use when you want incremental reasoning with revisions, branches, substeps, and quick extensions.

scopeId is optional and accepted only on thoughtNumber=1. If omitted on the first thought, a new active scope is created.

{
  thought: 'The bug likely comes from stale branch state after retry.',
  thoughtNumber: 1,
  totalThoughts: 3,
  nextThoughtNeeded: true,
  confidence: 6,
  quickExtension: {
    type: 'critique',
    content: 'Verify whether retry state is recreated or reused.'
  }
}

think_batch

Use only when the complete chain is already built and you want to validate it atomically in one call.

scopeId is optional. If omitted, batch submission creates a new active scope.

{
  goal: 'Audit deployment rollback flow',
  thoughts: [
    { thoughtNumber: 1, thought: 'Identify every entry point that can change rollout state and ownership.' },
    { thoughtNumber: 2, thought: 'Trace rollback triggers, timeout behavior, and observable recovery evidence.' }
  ]
}

think_logic

Use for strict methodology generation before an audit. It returns instructions, not findings; deep adds an evidence-and-disconfirmation gate.

{
  target: 'Review the payment retry pipeline for consistency and failure isolation',
  depth: 'deep',
  focus: ['reliability', 'performance', 'data-flow']
}

think_recall

Use before starting a familiar class of problem. Session recall searches the full active scope across the active think state and every attached think_cycle session. You can also pass an explicit scopeId.

{
  query: 'rollback strategy cache migration',
  scope: 'insights',
  limit: 5
}

think_done

By default, think_done finalizes the active think scope. Pass scopeId to finalize an inactive think scope explicitly. A cycle-only scope has no think history, so finalize it with think_cycle action finalize instead.

Quality and release gates

Release verification is built into the repo:

npm run validate:release

Main checks:

• TypeScript typecheck
• Unit and behavioral MCP tests (npm test; focused: npm run eval:local)
• Repo structure validation
• Security audit
• Hard quality baseline in docs/quality/HARD_QUALITY_STANDARD.md

Runtime storage

• Default data directory: ~/.think-mcp
• Override with THINK_MCP_DATA_DIR
• think_cycle sessions persist in runtime storage with TTL cleanup
• Shared scope metadata persists in runtime_state.json

Package links

• npm: @gofman3/think-mcp
• repo: GofMan5/think-mcp

Changelog

v5.6.0

• Added actionable model guidance and deterministic tool routing.
• Hardened cycle completion, persistence, retries, confidence scoring, and state integrity.
• Added real stdio and cycle behavioral evaluation while simplifying the build and package.

v5.5.1

• Fixed broken mojibake output in runtime coaching strings.
• Rebuilt and refreshed README for the current toolset and quality model.
• Released documentation and packaging cleanup on top of 5.5.0.

v5.5.0

• Added think_cycle for adaptive external reasoning with hard quality gates.
• Added release-gated hard quality policy based on NEED_ADD.
• Added eval scenarios for cycle gating, fallback behavior, autonomy quality, safety gates, and bounded retries.

v5.1.0

• Switched prompt style toward imperative IF/THEN instructions.
• Reduced token overhead significantly for common reasoning flows.

v5.0.0

• Added think_logic methodology generation.