Yggdrasil

npm version CI License: MIT Node.js

Reasoning orchestration MCP server — Tree of Thoughts with multi-agent evaluation.

A fork of Anthropic's @modelcontextprotocol/server-sequential-thinking with critical bug fixes and an ambitious roadmap for advanced reasoning capabilities.

Why Yggdrasil?

In Norse mythology, Yggdrasil is the World Tree connecting all realms. This MCP embodies that metaphor:

• Branches = Different reasoning paths through possibility space
• Roots = Deep foundational analysis (first principles)
• Connections = Links between thoughts, revisions, and evaluations

Key Features

Current (v1.1.0)

• 6 MCP tools — sequential_thinking, deep_planning, list_plans, get_plan, promote_plan, archive_plans
• Descriptive plan naming — Optional planName parameter generates dp-YYYYMMDD-{name} session IDs with duplicate detection
• Plan lifecycle management — Promote Claude Code orphan plans, archive old plans, unified discovery across both systems
• deep_planning tool — Structured multi-phase planning sessions (init → clarify → explore → evaluate → finalize)
• Session resumption — Resume planning sessions by ID with JSONL persistence
• Hybrid persistence — JSONL event log + Markdown plan export with JSON index
• String coercion fix — Fixes Claude Code bug #3084 where MCP parameters are incorrectly serialized as strings
• Oxlint + Biome — 50-100x faster linting, zero-config formatting
• Break down complex problems into manageable steps
• Revise and refine thoughts as understanding deepens
• Branch into alternative paths of reasoning
• Adjust the total number of thoughts dynamically
• Generate and verify solution hypotheses

Roadmap

See the CLAUDE.md for details:

• Mermaid diagram export
• Thought history retrieval
• Self-evaluation tools
• Multi-agent evaluation (cross-model verification)
• n8n workflow integration

Installation

Claude Desktop (recommended — one-click install)

Yggdrasil ships as a Claude Desktop Extension (.mcpb):

1. Download the latest .mcpb: packages.henrychong.com/yggdrasil-mcp/yggdrasil-mcp-latest.mcpb
2. Double-click the file — Claude Desktop opens an install dialog → click Install
3. Restart Claude Desktop

Requires Claude Desktop 1.8000 or later (bundles Node.js 24+).

Optionally verify integrity by comparing the SHA256 against SHA256SUMS:

shasum -a 256 ~/Downloads/yggdrasil-mcp-*.mcpb

Older versions remain available at packages.henrychong.com/yggdrasil-mcp/yggdrasil-mcp-{version}.mcpb.

Claude Cowork / Claude Code (plugin ZIP)

For Cowork / Code, install the plugin ZIP:

# Claude Code — local install
claude --plugin-dir https://packages.henrychong.com/yggdrasil-mcp/yggdrasil-mcp-latest.zip

For Cowork org admins (Teams / Enterprise): upload the ZIP via Organization settings → Plugins → Add plugins → Upload a file. All team members get the tools without further action.

Teams / Enterprise org admins

If your Claude workspace is on a Teams or Enterprise plan, an Owner can distribute Yggdrasil organisation-wide:

Surface	Where	Artefact
Claude Desktop	Organization settings → Connectors → Desktop → Add custom extension	.mcpb
Claude Cowork	Organization settings → Plugins → Add plugins → Upload a file	.zip

Both surface artefacts are attached to every GitHub Release. Mobile / browser-only Cowork remain out of scope (stdio MCP architecturally cannot reach those surfaces).

Claude Code

claude mcp add --scope user yggdrasil "npx -y yggdrasil-mcp"

Or add to ~/.claude.json:

{
  "mcpServers": {
    "yggdrasil": {
      "command": "npx",
      "args": ["-y", "yggdrasil-mcp"]
    }
  }
}

Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "yggdrasil": {
      "command": "npx",
      "args": ["-y", "yggdrasil-mcp"]
    }
  }
}

Local Development

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

Recommended: CLAUDE.md Configuration

After installing the MCP server, add the following to your ~/.claude/CLAUDE.md (global instructions) to unlock quick-access triggerwords and ensure Claude Code can load the tools correctly.

Why this matters

Yggdrasil tools are deferred tools in Claude Code — their full schemas are not loaded until explicitly fetched. Without the configuration below, Claude Code won't know how to invoke the tools or respond to shorthand triggers. Adding this block enables:

• Shorthand triggers (s1, s2, s3) for instant reasoning at different depth levels
• Automatic ToolSearch so Claude Code loads the tool schema before first use
• Correct thought calibration based on problem complexity

Add to ~/.claude/CLAUDE.md

Copy the following block into your ~/.claude/CLAUDE.md file:

## Structured Reasoning (Yggdrasil MCP)

### sequential_thinking — Reflective Problem-Solving

**MANDATORY Trigger:** When `s1`, `s2`, or `s3` appears ANYWHERE in user input:
1. Load via `ToolSearch` query `select:mcp__yggdrasil__sequential_thinking`
2. Invoke with appropriate `totalThoughts`
3. Complete the full chain before responding

**This is NOT optional internal reasoning — you MUST call the external MCP tool.**

| Trigger | totalThoughts | Use Case |
|---------|---------------|----------|
| **s1** | 3-5 | Quick analysis, simple decisions |
| **s2** | 6-10 | Detailed analysis, multi-factor problems |
| **s3** | 12-20 | Comprehensive analysis, complex systems |

### deep_planning — Multi-Phase Planning Sessions

Use for structured planning that needs to track state across phases:
`init → clarify → explore → evaluate → finalize`

Best for: Architecture decisions, multi-approach evaluation, implementation planning with scored trade-offs.

Both tools are deferred — load via `ToolSearch` before first use.

ToolSearch (Recommended)

Yggdrasil tools are registered as deferred tools in Claude Code. This means their parameter schemas are not available until fetched via ToolSearch. The CLAUDE.md configuration above handles this automatically for the s1/s2/s3 triggers, but if you want to invoke the tools directly, use:

ToolSearch query: "select:mcp__yggdrasil__sequential_thinking"
ToolSearch query: "select:mcp__yggdrasil__deep_planning"

This fetches the full schema and makes the tool callable for the rest of the session.

Verification

After setup, test by typing s1 followed by a question in Claude Code. You should see Claude Code automatically invoke ToolSearch and then call sequential_thinking with 3-5 thoughts.

Tool: sequential_thinking

Facilitates a detailed, step-by-step thinking process for problem-solving and analysis.

Parameters

Required

Parameter	Type	Description
thought	string	The current thinking step
nextThoughtNeeded	boolean	Whether another thought step is needed
thoughtNumber	integer	Current thought number (≥1)
totalThoughts	integer	Estimated total thoughts needed (≥1)

Optional

Parameter	Type	Description
isRevision	boolean	Whether this revises previous thinking
revisesThought	integer	Which thought is being reconsidered
branchFromThought	integer	Branching point thought number
branchId	string	Branch identifier
needsMoreThoughts	boolean	If more thoughts are needed

Output

{
  "thoughtNumber": 3,
  "totalThoughts": 5,
  "nextThoughtNeeded": true,
  "branches": ["branch-a"],
  "thoughtHistoryLength": 3
}

Tool: deep_planning

Structured planning tool that manages multi-phase planning sessions. Complements sequential_thinking by tracking state while the LLM reasons deeply between phases.

Workflow

init → clarify* → explore+ → evaluate+ → finalize → done

Parameters

Parameter	Type	Phases	Description
phase	enum	All	init, clarify, explore, evaluate, finalize
problem	string	init	Problem statement
planName	string	init	Descriptive name → dp-YYYYMMDD-{name} session ID
context	string	init	Additional background
constraints	string	init	JSON array of constraint strings
question	string	clarify	Clarifying question
answer	string	clarify	Answer to the question
branchId	string	explore/evaluate	Unique approach identifier
name	string	explore	Short approach name
description	string	explore	Detailed approach description
pros/cons	string	explore	JSON arrays of strings
feasibility	number	evaluate	Score 0-10
completeness	number	evaluate	Score 0-10
coherence	number	evaluate	Score 0-10
risk	number	evaluate	Score 0-10 (lower is better)
rationale	string	evaluate	Reasoning for scores
recommendation	string	evaluate	pursue, refine, or abandon
selectedBranch	string	finalize	Branch ID of chosen approach
steps	string	finalize	JSON array of step objects
risks	string	finalize	JSON array of risk objects
assumptions	string	finalize	JSON array of strings
successCriteria	string	finalize	JSON array of strings
format	string	finalize	markdown (default) or json

Output

{
  "sessionId": "dp-abc123",
  "phase": "explore",
  "status": "ok",
  "approachCount": 2,
  "evaluationCount": 0,
  "validNextPhases": ["explore", "evaluate", "clarify"],
  "message": "Approach recorded..."
}

Plan Management Tools

list_plans

List saved plans with unified view of Yggdrasil plans and Claude Code orphans. Supports pagination, source filtering, and keyword search.

Parameter	Type	Description
status	enum	complete or in-progress (Yggdrasil only)
keyword	string	Case-insensitive search in title/problem text
source	enum	yggdrasil (default), cc (Claude Code orphans), all
limit	number	Max results (default 20, max 50)
offset	number	Skip first N results (default 0)

get_plan

Retrieve a saved session by ID. Formats: markdown (default, finalized plans) or jsonl (full event log).

promote_plan

Promote a Claude Code plan file to the Yggdrasil index. Renames the file to YYYYMMDD-{name}.md format and adds it to the index for unified discovery. Includes path traversal protection.

Parameter	Type	Description
filename	string	Current CC plan filename (e.g., silly-parrot.md)
name	string	Descriptive name (sanitized to kebab-case)

archive_plans

Archive old plans by moving files to archive/YYYY/ subdirectory. Supports archiving both Yggdrasil index entries and Claude Code orphan files. Default mode is dry run (preview only).

Parameter	Type	Description
olderThan	number	Archive plans older than N days
sessionIds	string	JSON array of specific session IDs
source	enum	yggdrasil, cc, promoted, all
dryRun	boolean	Preview mode (default: true)

Use Cases

Yggdrasil is designed for:

• Complex problem decomposition — Break down multi-step problems
• Iterative planning — Design with room for revision
• Course correction — Analysis that adapts as understanding deepens
• Scope discovery — Problems where the full scope isn't clear initially
• Context maintenance — Tasks requiring state across multiple steps
• Information filtering — Situations where irrelevant details need filtering

Configuration

Environment Variables

Variable	Default	Description
DISABLE_THOUGHT_LOGGING	false	Suppress stderr thought output

The String Coercion Fix

This fork addresses a critical bug in Claude Code (#3084) where MCP parameters are serialized as strings regardless of their schema type.

The Problem

// Claude Code sends:
{ nextThoughtNeeded: "true", thoughtNumber: "5" }

// Instead of:
{ nextThoughtNeeded: true, thoughtNumber: 5 }

Using z.coerce.boolean() is dangerous:

z.coerce.boolean().parse('false'); // Returns TRUE! (non-empty string = truthy)

Our Solution

// Safe coercion that correctly handles "false" → false
const coerceBoolean = (val: unknown): boolean => {
  if (typeof val === 'boolean') return val;
  if (typeof val === 'string') {
    if (val.toLowerCase() === 'true') return true;
    if (val.toLowerCase() === 'false') return false;
  }
  throw new Error(`Cannot coerce "${val}" to boolean`);
};

// Applied via z.preprocess (NOT z.coerce)
const booleanSchema = z.preprocess(coerceBoolean, z.boolean());

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Lint
pnpm lint

# Format
pnpm format

# Full quality check
pnpm check

# Watch mode
pnpm watch

Requirements

• Node.js >=24
• pnpm (corepack-managed via packageManager field)

Upstream

This is a fork of @modelcontextprotocol/server-sequential-thinking.

We periodically sync relevant changes from upstream while maintaining our string coercion fix and additional features.

Changelog

See CHANGELOG.md for the full version history.

License

MIT License — see LICENSE file for details.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

1. All tests pass (pnpm test)
2. Linting passes (pnpm lint)
3. Code is formatted (pnpm format)
4. Version is incremented appropriately