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.

• 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

# 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

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"]
    }
  }
}

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):

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

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

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

// 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 })

The server includes protections against agents taking shortcuts:

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.

# Run tests
bun test

# Build
bun run build

See CLAUDE.md for development guidelines.

MIT