Tree of Thoughts MCP Server

Tree of Thoughts MCP Server

A Model Context Protocol (MCP) server that enables structured multi-path investigations using a Tree of Thoughts approach. Designed for AI agents to explore complex problems systematically with parallel research paths.

Features

• Single Root Paradigm - Start with one root, branch wide at R2
• 5-State System - EXPLORE, FOUND, VERIFY, EXHAUST, DEAD states enforce thorough investigation
• Anti-Gaming Measures - Timing checks and agentId tracking prevent shortcut-taking
• Reference Extraction - Automatically collects URLs and file paths from findings
• DOT Graph Output - Visualize investigation tree structure

Installation

# Clone the repository
git clone https://github.com/NikkeTryHard/tree-of-thoughts-mcp.git
cd tree-of-thoughts-mcp

# Install dependencies
bun install

# Build
bun run build

Configuration

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "tree-of-thoughts": {
      "command": "node",
      "args": ["/path/to/tree-of-thoughts-mcp/dist/index.js"]
    }
  }
}

State Machine

| State | Meaning | Children Required | Terminal | Min Round | Valid Child States | |---------|----------------------|----------------------|----------|-----------|-------------------| | EXPLORE | Dig deeper | 2+ (R1-R2), 1+ (R3+) | No | R1 | Any | | FOUND | Provisional solution | 1+ any | No | R4 | EXPLORE, FOUND, VERIFY | | VERIFY | Confirms FOUND | 0 | Yes | R4 | - | | EXHAUST | Exhausted path | 1+ any | No | R4 | EXPLORE, EXHAUST, DEAD | | DEAD | Confirmed dead end | 0 | Yes | R4 | - |

Key insight: FOUND is NOT terminal. Every promising finding must be verified by at least one child before the investigation can end.

Key insight: EXHAUST is NOT terminal. Every exhausted path must be confirmed by at least one child.

Invalid Transitions (Semantic Conflicts): | From | Cannot Go To | Why | |------|--------------|-----| | FOUND | EXHAUST, DEAD | Found something - can't be exhausted/dead | | EXHAUST | FOUND, VERIFY | Exhausted path - can't suddenly find/verify |

Workflow (Single Root Paradigm)

1. tot_start    → Get sessionId, begin investigation
2. tot_propose  → Declare single root R1.A
3. Spawn agent  → Execute research for R1.A
4. tot_commit   → Submit as EXPLORE
5. tot_propose  → Branch into 3-5 children at R2
6. Repeat       → Continue until R4+ for FOUND, R5+ to end
7. tot_end      → Finalize and get results with references

Node ID Format

Round 1: R1.A (single root, parent: null)
Round 2: R2.A1, R2.A2, R2.A3 (branch wide from R1.A)
Round 3: R3.A1a (parent: R2.A1)
Round 4: R4.A1a1 (parent: R3.A1a) - can use FOUND here
Round 5: R5.A1a1a (parent: R4.A1a1) - VERIFY node

Rules

1. Single root R1.A - Then branch wide at R2 (5+ nodes recommended)
2. Minimum 5 rounds - Cannot end before Round 5
3. EXPLORE needs 2+ children at R1-R2, 1+ at R3+ - Relaxed requirements later
4. R3 must be EXPLORE only - Forces deeper investigation before conclusions
5. FOUND only at R4+ - Earlier rounds auto-convert to EXPLORE
6. FOUND needs 1+ child (EXPLORE, FOUND, or VERIFY) - Cannot end until verified
7. EXHAUST only at R4+ - Earlier rounds auto-convert to EXPLORE
8. EXHAUST needs 1+ child (EXPLORE, EXHAUST, or DEAD) - Cannot end unconfirmed
9. DEAD only at R4+ - R1-R3 converts to EXPLORE

Example

// Start investigation
tot_start({ query: "How to optimize database queries?" })

// Round 1: Single root
tot_propose({ sessionId, nodes: [
  { id: "R1.A", parent: null, title: "Query Optimization", plannedAction: "Analyze problem" }
]})
tot_commit({ sessionId, results: [
  { nodeId: "R1.A", state: "EXPLORE", findings: "Found multiple paths...", agentId: "abc-123" }
]})

// Round 2: Branch wide
tot_propose({ sessionId, nodes: [
  { id: "R2.A1", parent: "R1.A", title: "Index Analysis", plannedAction: "Analyze indexes" },
  { id: "R2.A2", parent: "R1.A", title: "Query Patterns", plannedAction: "Review patterns" },
  { id: "R2.A3", parent: "R1.A", title: "Schema Design", plannedAction: "Evaluate schema" }
]})

// Continue through R3, R4...

// Round 4+: Use FOUND
tot_commit({ sessionId, results: [
  { nodeId: "R4.A1a1", state: "FOUND", findings: "Solution: Add composite index...", agentId: "..." }
]})

// Round 5: Verify the finding
tot_propose({ sessionId, nodes: [
  { id: "R5.A1a1a", parent: "R4.A1a1", title: "Verify Index", plannedAction: "Test performance" }
]})
tot_commit({ sessionId, results: [
  { nodeId: "R5.A1a1a", state: "VERIFY", findings: "Confirmed: 10x improvement", agentId: "..." }
]})

// End when canEnd=true
tot_end({ sessionId })

Anti-Gaming Measures

The server includes protections against agents taking shortcuts:

| Warning | Trigger | |----------------|--------------------------------------| | SUSPICIOUS | Commit within 10s of propose | | MISSING_AGENT | No agentId provided | | DEPTH_ENFORCED | FOUND before R4 (auto-converts) |

Claude Code Skill

Skills are located in the tree-of-thoughts/ folder. Copy tree-of-thoughts/SKILL.md to ~/.claude/skills/tree-of-thoughts/SKILL.md to enable the /tree-of-thoughts command in Claude Code.

Development

# Run tests
bun test

# Build
bun run build

See CLAUDE.md for development guidelines.

License

MIT