npm package: @felkot/think-mcp
Description: MCP Server for structured sequential thinking with Burst Thinking, Logic Methodology Generator, branching, revisions, dead-ends tracking, and fuzzy recall
Author: FelKot
Latest version: 1.1.5

# Think MCP

Reasoning control layer for any MCP client.

[![npm version](https://img.shields.io/npm/v/@felkot/think-mcp?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@felkot/think-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-2D77FF?style=flat-square)](https://modelcontextprotocol.io/)

Think MCP does not replace your model. It enforces a structured thinking workflow so both thinking and non-thinking models produce better, safer, and more consistent results.

---

## Why use Think MCP? 🧠

Many models are fast but unstable on medium/heavy tasks. Think MCP adds a practical quality loop:

- structured reasoning with validation,
- branch exploration when confidence is low,
- synthesis gate before final answer,
- objective quality scoring.

New in current development:

- confidence calibration (predicted vs actual confidence),
- auto-diverge trigger when confidence drops too low.

Works across domains:

- frontend, backend, fullstack,
- finance, crypto, math,
- game dev, game modding,
- web, data, devops,
- and general problem solving.

---

## Changelog 📦

<details>
<summary><strong>v1.1.5 - ThinkingService Architecture Hardening (current)</strong></summary>

### New

- Extracted `ThinkingService` internals into dedicated services for session state, session persistence, and result assembly.
- Extracted the `processThought` orchestration into `ThoughtProcessingService` so validation, context capture, nudges, quick extensions, and dead-end warnings now live behind a dedicated pipeline boundary.
- Added regression coverage for the new internal boundaries and MCP-visible result assembly.

### Fixed

- Fixed transient Windows cleanup failures during session retention maintenance by retrying `EPERM`, `EBUSY`, and `EACCES` deletes.
- Fixed duplicated result-building paths inside `ThinkingService`, reducing drift risk between rejection and success responses.
- Fixed `extendThought` / persistence race conditions by rejecting extensions during active mutations and by building persisted session snapshots only after the filesystem lock is acquired.

### Why it is better

- Better maintainability without changing the public MCP contract.
- Better Windows runtime stability during background session cleanup.
- Better confidence that internal refactors do not silently degrade `think` behavior.
- Better protection against stale session writes when sync extensions and async thought mutations happen close together.
- Better separation between MCP-facing facade logic and the actual reasoning pipeline.

</details>

<details>
<summary><strong>v1.1.4 - think_logic Surface Hints + Domain Packs</strong></summary>

### Changed

- Added optional `surface` hint to `think_logic` for `ui/api/cli/worker/bot/plugin/desktop/mobile/game`.
- Added optional `domainPack` presets for trace-first chains: `web-fullstack`, `telegram-bot`, `vk-bot`, `game-runtime`, `game-bot`, `payments`, `trading`, `defi`.
- Improved event-flow guidance for mixed-language and non-web flows.
- Added real MCP `stdio` smoke coverage for `think_logic`.
- Updated README examples for `surface`- and `domainPack`-aware prompts.

### Why it is better

- Better release guidance for models that need explicit runtime context.
- Better coverage outside website-only scenarios.
- Better end-to-end tracing for domain-specific chains like `UI -> store -> request -> route -> service -> persistence -> user outcome`.
- Better confidence that the published MCP contract matches runtime behavior.

</details>

<details>
<summary><strong>v1.1.2 - README UX Refresh</strong></summary>

### Changed

- Full README rewrite with improved structure and scanability.
- Changelog moved near the top for npm visibility.
- Features table upgraded with visual emoji markers.
- Added dedicated Mini Prompt section.
- OpenCode example key switched to `think-mcp` for copy-paste usage.

### Why it is better

- Faster onboarding.
- Fewer setup mistakes.
- Clearer release communication on npm.

</details>

<details>
<summary><strong>v1.1.1 - Quality Scoring + Event-Flow Upgrade</strong></summary>

### Added

- `qualityScore` in `think_done`:
  - `overall` (`0-100`)
  - `grade` (`A/B/C/D/F`)
  - `breakdown`: `coherence`, `riskCoverage`, `evidenceDiscipline`, `executionReadiness`, `flowIntegrity`
  - `nextActions` for practical remediation
- `analysisMode` in `think_logic`:
  - `standard`
  - `event-flow` (trigger-to-outcome mapping)
- Event-flow map sections:
  - Trigger
  - Bindings
  - Call Chain
  - State Mutations
  - Side Effects
  - User Outcome
  - Failure Path
  - Unknown Nodes
  - Verification Plan

### Changed

- `think_done` output now surfaces quality metrics directly.
- README expanded with tool-by-tool schemas and best practices.
- Added OpenCode local MCP setup example with `@latest`.

### Fixed

- Improved visibility of final reasoning quality with machine-readable scoring.
- Added explicit post-analysis guidance via `nextActions` when score is weak.
- Reduced false confidence by penalizing incomplete chains (`flowIntegrity`).
- Closed a practical gap where trigger-driven flows were not explicitly mapped end-to-end.

### Why it is better

- Better for non-thinking models: stronger guardrails before finalization.
- Better for thinking models: clearer calibration and measurable completion criteria.
- Better for any MCP client: quality signal is structured, not UI-dependent.

</details>

<details>
<summary><strong>v1.1.0 - Universal Routing Layer</strong></summary>

### Added

- Domain-aware profiles in `think_logic`:
  `frontend`, `backend`, `fullstack`, `game-dev`, `game-modding`, `finance`, `crypto`, `math`, `web`, `data`, `devops`, `general`
- `complexityMode`: `auto | simple | medium | heavy`
- `tokenDiscipline`: `strict | balanced | exploratory`
- Domain checklist and token policy sections in generated methodology.

### Why it matters

- Extends one MCP to many task types without tool sprawl.
- Improves token efficiency by matching depth to actual complexity.

</details>

<details>
<summary><strong>v1.0.0 - Stable Public Release</strong></summary>

### Added

- Stable Think MCP core workflow.
- Heavy-task validation gates.
- Context safety hardening and sensitive-data redaction.
- Sanitized export/insights pipeline.

</details>

---

## Features ✨

| Feature | What it gives you | Why it matters |
| :--- | :--- | :--- |
| 🧭 Sequential reasoning | Step-by-step thought chain | Reduces random jumps and missing logic |
| ✅ Quality gate (`think_done`) | Ready/Blocked + score + next actions | Prevents premature final answers |
| 🎯 Confidence calibration | Predicted vs actual confidence + delta | Reduces overconfidence and improves self-checking |
| 🔗 Flow integrity scoring | Checks chain completeness | Catches broken trigger-to-outcome paths |
| ⚡ Event-flow mode | Trigger -> bindings -> call chain -> outcome | Great for click/submit/api/webhook/cron scenarios |
| 🌍 Domain routing | Domain-aware checklists | Better guidance without adding more tools |
| 📏 Complexity routing | `simple / medium / heavy` | Saves tokens on easy tasks, deepens hard ones |
| 💸 Token discipline | `strict / balanced / exploratory` | Controls verbosity and cost |
| 🧠 Recall memory | Search session or cross-session insights | Reuse past lessons, avoid repeating errors |
| 🔒 Safe context handling | Redaction + sensitive file blocking | Reduces accidental leaks |

---

## Quick Start 🚀

Run directly:

```bash
npx @felkot/think-mcp@latest
```

Generic MCP config:

```json
{
  "mcpServers": {
    "think": {
      "command": "npx",
      "args": ["-y", "@felkot/think-mcp@latest"]
    }
  }
}
```

OpenCode local MCP example:

```json
{
  "mcp": {
    "think-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@felkot/think-mcp@latest"
      ],
      "environment": {},
      "enabled": true
    }
  }
}
```

Example with environment overrides:

```json
{
  "mcp": {
    "think-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@felkot/think-mcp@latest"
      ],
      "environment": {
        "THINK_MCP_STORAGE_DIR": "D:\\mcp-data",
        "THINK_MCP_AUTO_DIVERGE_CONFIDENCE_THRESHOLD": "6",
        "THINK_MCP_CALIBRATION_TREND_WINDOW": "12"
      },
      "enabled": true
    }
  }
}
```

---

## Mini Prompt for Any AI 🧩

Use this prompt with models that should follow Think MCP workflow:

```text
You are a disciplined assistant.
Use Think MCP to improve reasoning quality without wasting tokens.

Rules:
1) Start non-trivial tasks with think_logic.
2) Match effort to complexity (simple/medium/heavy).
3) Use think for sequential execution and verification.
4) If confidence < 5 or trade-offs are unclear, use think_diverge.
5) For trigger chains (click/submit/api/webhook/cron), use analysisMode=event-flow.
6) Before final output, call think_done and inspect qualityScore.
7) If blocked or score is weak, continue reasoning before concluding.
```

---

## Tool Catalog 🛠️

| # | Tool | Role |
| :---: | :--- | :--- |
| 1 | `think` | Add one reasoning step with confidence, substeps, alternatives, and optional context snapshots |
| 2 | `think_batch` | Submit complete reasoning chain in one call |
| 3 | `think_done` | Final synthesis gate with readiness + quality score |
| 4 | `think_recall` | Search session memory or cross-session insights |
| 5 | `think_reset` | Clear current session state |
| 6 | `think_logic` | Generate domain-aware methodology with complexity/token controls |
| 7 | `think_diverge` | Create 2-3 alternative branches from one thought |
| 8 | `get_model_instructions` | Return built-in disciplined model instructions |

---

## Tool Details (Best Practices + Schema) 📘

### 1) `think`

Single step in a reasoning chain.

Best practices:

- Use for non-trivial tasks where traceability matters.
- Set `goal` in the first thought and keep it stable.
- Keep `subSteps` short and executable.
- If confidence drops, use `think_diverge`.
- Use `includeContextContent: true` only when really needed.

```ts
{
  thought: string,
  nextThoughtNeeded: boolean,
  thoughtNumber: number,
  totalThoughts: number,
  phase?: 'initialization' | 'analysis' | 'strategy' | 'execution' | 'verification' | 'conclusion',
  context_files?: string[],
  includeContextContent?: boolean,
  confidence?: number,
  subSteps?: string[],
  alternatives?: string[],
  goal?: string,
  quickExtension?: {
    type: 'critique' | 'elaboration' | 'correction' | 'alternative_scenario' | 'assumption_testing' | 'innovation' | 'optimization' | 'polish',
    content: string,
    impact?: 'low' | 'medium' | 'high' | 'blocker'
  },
  isRevision?: boolean,
  revisesThought?: number,
  branchFromThought?: number,
  branchId?: string,
  showTree?: boolean
}
```

### 2) `think_batch`

Submit a complete chain in one call.

Best practices:

- Use when you already have a full structured chain.
- Great for import/migration of offline reasoning.
- Keep thoughts concise; avoid repeated content.

```ts
{
  goal: string,
  thoughts: Array<{
    thoughtNumber: number,
    thought: string,
    confidence?: number,
    subSteps?: string[],
    alternatives?: string[],
    isRevision?: boolean,
    revisesThought?: number,
    branchFromThought?: number,
    branchId?: string,
    extensions?: Array<{
      type: 'critique' | 'elaboration' | 'correction' | 'alternative_scenario' | 'assumption_testing' | 'innovation' | 'optimization' | 'polish',
      content: string,
      impact?: 'low' | 'medium' | 'high' | 'blocker'
    }>
  }>,
  consolidation?: {
    winningPath: number[],
    summary: string,
    verdict: 'ready' | 'needs_more_work'
  },
  showTree?: boolean
}
```

### 3) `think_done`

The synthesis gate. Decides if final answer is ready.

Best practices:

- Use before final output on medium/heavy tasks.
- For heavy tasks, include `constraintCheck` and `potentialFlaws`.
- Read `qualityScore.nextActions` and continue if blocked.

Quality score includes:

- `coherence`
- `riskCoverage`
- `evidenceDiscipline`
- `executionReadiness`
- `flowIntegrity`

Also returns confidence calibration (when session has confidence values):

- `predicted` (average self-confidence),
- `actual` (`qualityScore.overall / 10`),
- `delta`, `status`, and recommendation.

And confidence calibration trend:

- `direction` (`stable | improving | worsening`),
- `averageDelta`,
- counts: `overconfident`, `underconfident`, `aligned`.

```ts
{
  winningPath: number[],
  summary: string,
  verdict: 'ready' | 'needs_more_work',
  constraintCheck?: string,
  potentialFlaws?: string,
  exportReport?: 'markdown' | 'json',
  includeMermaid?: boolean
}
```

### 4) `think_recall`

The Memory Bank. Search current session or past insights.

Best Practices:

- BEFORE `complex_task` -> Check `scope: 'insights'`
- IF `repeating_logic` -> Check session for dead ends
- IF unsure -> Verify established context

```ts
{
  query: string,
  scope?: 'session' | 'insights',
  searchIn?: 'thoughts' | 'extensions' | 'alternatives' | 'all',
  limit?: number,
  threshold?: number
}
```

### 5) `think_reset`

Clears current session state.

Best practices:

- Use for fully unrelated tasks.
- Do not use mid-execution when a branch/revision is enough.

```ts
{}
```

### 6) `think_logic`

Generates methodology before execution.

Best practices:

- Start medium/heavy tasks with this tool.
- Use `analysisMode: 'event-flow'` for interaction chains.
- Use `complexityMode: 'auto'` unless you need strict control.
- Use `surface` when the runtime shape matters more than the wording of the prompt.
- Use `domainPack` when you know the environment and want stronger stage-by-stage checkpoints without losing the full trigger-to-outcome chain.
- Keep prompt phrasing in English when possible for the clearest tool-facing instructions.

```ts
{
  target: string,
  context?: string,
  domainPack?: 'web-fullstack' | 'telegram-bot' | 'vk-bot' | 'game-runtime' | 'game-bot' | 'payments' | 'trading' | 'defi',
  surface?: 'generic' | 'ui' | 'api' | 'cli' | 'worker' | 'bot' | 'plugin' | 'desktop' | 'mobile' | 'game',
  analysisMode?: 'standard' | 'event-flow',
  domain?: 'general' | 'frontend' | 'backend' | 'fullstack' | 'game-dev' | 'game-modding' | 'finance' | 'crypto' | 'math' | 'web' | 'data' | 'devops',
  complexityMode?: 'auto' | 'simple' | 'medium' | 'heavy',
  tokenDiscipline?: 'strict' | 'balanced' | 'exploratory',
  depth?: 'quick' | 'standard' | 'deep',
  focus?: Array<'security' | 'performance' | 'reliability' | 'ux' | 'architecture' | 'data-flow' | 'testing'>,
  stack?: Array<'nestjs' | 'prisma' | 'ts-rest' | 'react' | 'redis' | 'zod' | 'trpc' | 'nextjs' | 'drizzle' | 'hono'>
}
```

Examples:

- `surface: 'ui'` for click/tap/desktop/mobile interaction chains
- `surface: 'api'` for route/controller/request/response tracing
- `surface: 'cli'` for command/subcommand/stdout/exit-code flows
- `surface: 'worker'` for queue/cron/background pipelines
- `surface: 'bot'` or `surface: 'plugin'` for chat adapters and host-hook integrations
- `domainPack: 'web-fullstack'` for UI/store/request/backend/response chains like add-to-cart or checkout
- `domainPack: 'telegram-bot' | 'vk-bot'` for update/router/handler/reply flows
- `domainPack: 'payments' | 'trading' | 'defi'` for irreversible or contract-heavy finance/crypto flows

### 7) `think_diverge`

Create alternative branches from one thought.

Best practices:

- Use when confidence < 5.
- Use when trade-offs are unclear.
- Keep branches distinct, not cosmetic rewrites.

Auto-trigger note:

- In `think`, if confidence is below threshold and no alternatives are present,
  the tool recommends `think_diverge` automatically and sets `next: think_diverge`.
- Threshold is configurable via `THINK_MCP_AUTO_DIVERGE_CONFIDENCE_THRESHOLD` (1..10).

```ts
{
  thoughtNumber: number,
  alternatives: string[]
}
```

### 8) `get_model_instructions`

Returns built-in deep-thinking model instructions.

Best practices:

- Use to align third-party/non-thinking models with Think MCP workflow.

```ts
{}
```

---

## Event-Flow Analysis (Trigger → Outcome) 🔗

When behavior starts from an interaction/event, use:

```ts
analysisMode: 'event-flow'
```

Typical traces:

- UI click -> handler -> state update -> API -> service -> DB -> UI feedback
- Form submit -> validation -> transform -> API -> response -> error/success state
- API request -> middleware -> service -> repo -> side effects -> response
- Webhook -> signature check -> parser -> dedupe -> processing -> ack
- Scheduled job -> lock -> pipeline -> persistence -> reporting
- CLI command -> parser -> handler -> domain logic -> side effects -> stdout/stderr
- Bot update -> adapter -> handler -> domain logic -> reply/update
- Plugin hook -> bridge -> callback -> domain logic -> host-visible result

`domainPack` does not replace the chain. It strengthens the same trigger-to-outcome map with domain-specific checkpoints. Example:

- `web-fullstack`: UI event -> component/store action (`addToCart(id)`) -> request client -> route/controller -> service/use-case -> DB/cache -> response mapper -> rendered cart state
- `telegram-bot`: update -> adapter/router -> handler -> domain service -> storage/external API -> reply/edit/send
- `payments`: user/payment intent -> idempotency/auth -> API/controller -> orchestration -> PSP/bank -> ledger/order persistence -> receipt/result

Surface hint example:

```ts
{
  target: 'Investigate how this flow starts, runs, and reports the final result',
  context: 'Need a clear trigger-to-outcome map',
  surface: 'cli',
  analysisMode: 'event-flow',
  complexityMode: 'medium'
}
```

Domain pack example:

```ts
{
  target: 'Trace add to cart from button click to final cart state',
  context: 'Button click calls addToCart(id) in store and then sends a request to backend cart endpoint',
  domainPack: 'web-fullstack',
  analysisMode: 'event-flow',
  complexityMode: 'medium'
}
```

The model is forced to map:

- Trigger
- Bindings
- Call Chain
- State Mutations
- Side Effects
- User Outcome
- Failure Path
- Unknown Nodes
- Verification Plan

---

## Quality Score Guide 📊

`think_done` returns score `0..100` and grade `A..F`.

Quick interpretation:

| Range | Meaning | Typical action |
| :---: | :--- | :--- |
| 90-100 | Excellent | Finalize |
| 75-89 | Good | Finalize if no blocker warnings |
| 60-74 | Needs improvement | Address `nextActions` first |
| 40-59 | Weak | Rework core reasoning path |
| 0-39 | Unsafe | Rebuild path before final answer |

High-impact signals:

- low `flowIntegrity`: chain likely incomplete/disconnected,
- low `riskCoverage`: risks or constraints not handled,
- low `evidenceDiscipline`: claims not sufficiently verified.

---

## Recommended Workflows 🧭

Simple task:

1. `think`
2. `think_done`

Medium task:

1. `think_logic`
2. `think` (+ alternative if needed)
3. `think_done`

Heavy task:

1. `think_logic`
2. `think` loop + `think_diverge`
3. `think_recall`
4. `think_done` with `constraintCheck` + `potentialFlaws`
5. Finalize only when status is ready and score is acceptable

---

## Security & Safety 🔒

- Workspace-bounded context access
- Symlink escape protection
- Sensitive file blocking (`.env`, keys/certs patterns)
- Secret-like content redaction
- Context content is explicit opt-in (`includeContextContent: true`)
- Context details safety truncation
- Sanitized exports and insights persistence

Storage:

- Active sessions: `.think/sessions/active/*.json`
- Archived sessions: `.think/sessions/archive/*.json`
- Insights: `.think/insights.json`
- Confidence calibration: `.think/confidence_calibration.json`
- Optional override: `THINK_MCP_STORAGE_DIR`

Environment variables:

- `THINK_MCP_STORAGE_DIR` - base directory where `.think` will be created.
- `THINK_MCP_AUTO_DIVERGE_CONFIDENCE_THRESHOLD` - low-confidence threshold for auto-diverge (`1..10`, default `5`).
- `THINK_MCP_CALIBRATION_TREND_WINDOW` - number of recent calibration records for trend (`1..50`, default `10`).

All overrides are optional:

- If `environment` is empty, Think MCP uses safe defaults.
- Use overrides only when you want custom storage location or tuning behavior.

---

## Development 👨‍💻

```bash
npm ci
npm run typecheck
npm test
npm run build
npm run audit:prod
```

Optional package check:

```bash
npm pack --dry-run
```

---

## License

MIT

---

Created by FelKot