claude-augur-mcp
A Model Context Protocol (MCP) server for plan reasoning summaries in Claude Code. Surfaces decisions, tradeoffs, and assumptions as scannable abstracts so you can correct Claude's reasoning at a glance.
Claude's reasoning about plans is invisible. When Claude writes a plan, its decisions, assumptions, and tradeoffs are buried in the document. You have to read the entire thing to find them. If Claude assumed the wrong approach or made a bad tradeoff, you won't know until implementation is underway and something breaks.
Augur reads the plan structure and returns a template that Claude fills with its actual reasoning, inline in the response rather than hidden in a collapsed tool result. You see decisions, assumptions, and tradeoffs at a glance and can correct them before a single line of code is written.
install
Requirements:
From shell:
claude mcp add claude-augur-mcp -- npx claude-augur-mcp
From inside Claude (restart required):
Add this to our global mcp config: npx claude-augur-mcp
Install this mcp: https://github.com/Vvkmnn/claude-augur-mcp
From any manually configurable mcp.json: (Cursor, Windsurf, etc.)
{
"mcpServers": {
"claude-augur-mcp": {
"command": "npx",
"args": ["claude-augur-mcp"],
"env": {}
}
}
}
There is no npm install required: no external databases, no indexing, only Node.js built-ins for filesystem access.
However, if npx resolves the wrong package, you can force resolution with:
npm install -g claude-augur-mcp
features
1 tool. Plan structure extraction. Template seeding. Inline rendering.
augur_explain
Read a plan file and return a structured template for Claude to fill with its reasoning. Claude renders the abstract inline in its response, not hidden in a collapsed tool result.
Call after writing or editing a plan file:
augur_explain plan_path="/Users/you/.claude/plans/your-plan.md"
MCP returns two content blocks:
Block 1: one-line summary, visible even when the tool result is collapsed.
your-plan.md · 10/18 done
Block 2: template with pre-rendered header, progress, and [FILL] markers.
┌ 📐 my-project · your-plan.md ────────────────────────────────────
│ Build a REST API with authentication, rate limiting,
│ and WebSocket support for real-time notifications.
│
├ Progress ───────────────────────────────────────────────────────
│ Done (10/18): Auth scaffold, Rate limiter + 1 more
│ Next: WebSocket layer + 1 more
│
├ Decisions ──────────────────────────────────────────────────────
│ [FILL: 2-4 decisions, format: "✓ choice — reason"]
│ [child decisions use: " └ choice — reason"]
│
├ Assumptions ────────────────────────────────────────────────────
│ [FILL: 1-2 assumptions, format: "? statement"]
│
├ Tradeoffs ──────────────────────────────────────────────────────
│ [FILL: 1-2 lines, "+" for pro, "−" for con]
│
├ Reasoning ──────────────────────────────────────────────────────
│ [FILL: 2-3 lines explaining WHY]
└──────────────────────────────────────────────────────────────────
Claude fills the template inline:
┌ 📐 my-project · your-plan.md ────────────────────────────────────
│ Build a REST API with authentication, rate limiting,
│ and WebSocket support for real-time notifications.
│
├ Progress ───────────────────────────────────────────────────────
│ Done (10/18): Auth scaffold, Rate limiter + 1 more
│ Next: WebSocket layer + 1 more
│
├ Decisions ──────────────────────────────────────────────────────
│ ✓ Express over Fastify — team familiarity, middleware ecosystem
│ └ Passport.js for auth — proven, supports OAuth + JWT
│ ✓ Redis for rate limiting — atomic counters, TTL built-in
│ ✓ ws over Socket.io — lighter, no fallback polling needed
│
├ Assumptions ────────────────────────────────────────────────────
│ ? Single Redis instance sufficient for current scale
│ ? WebSocket clients handle reconnection gracefully
│
├ Tradeoffs ──────────────────────────────────────────────────────
│ + Redis rate limiting: sub-ms response, horizontal scaling
│ − Extra infrastructure dependency to operate
│
├ Reasoning ──────────────────────────────────────────────────────
│ Auth must be production-grade from day one — Passport.js
│ handles OAuth/JWT without custom crypto. Redis rate limiting
│ chosen over in-memory because the API will be multi-process.
│ ws chosen over Socket.io to avoid 200KB bundle overhead.
└──────────────────────────────────────────────────────────────────
What gets extracted from the plan file:
| Field | Source | Example |
|---|---|---|
| Project name | H1 title before : |
my-project |
| Purpose | First **Primary goal**: line, or first prose paragraph |
Full text, word-wrapped |
| Sections | H2 headings (excluding Detail: sections) |
Context, Architecture, ... |
| Progress | ### Step N: headings with - [x] / - [ ] counts |
Done (10/18): Auth, Rate limiter |
| Done steps | Steps where all items are [x] |
Capped at 2 names + N more |
| Next steps | Steps with pending items | First name + N more |
methodology
How claude-augur-mcp reads plans:
📐 claude-augur-mcp
━━━━━━━━━━━━━━━━━━━
Claude writes a plan
augur_explain
│
▼
┌─────────────────┐
│ read plan file │ from disk (read-only)
│ (session.ts) │
└────────┬────────┘
│
├── title → project name (before ":")
├── purpose → **Primary goal**: or first prose
├── sections → H2 headings
└── progress → ### Step N: with [x]/[ ] counts
│
┌────────▼────────┐
│ render template │ left-gutter format
│ (render.ts) │ [FILL] markers for Claude
└────────┬────────┘
│
┌────────────┴────────────┐
▼ ▼
block 1 block 2
summary template
(visible collapsed) (Claude renders inline)
│ │
▼ ▼
plan.md · 10/18 done ┌ 📐 project · plan.md ──
│ purpose...
├ Progress ────────────
│ Done (10/18): Auth + 1
├ Decisions ───────────
│ [FILL]
├ Assumptions ─────────
│ [FILL]
└──────────────────────
TEMPLATE SEEDING:
Regex extraction of Claude's thinking blocks produces garbage:
free-form prose has no structured patterns to match.
Augur takes a different approach: extract plan structure (the
deterministic part), seed a template, let Claude fill reasoning
(the part only Claude knows). Structure from MCP, content from
Claude. Consistent format, accurate reasoning.
MCP pre-renders Claude fills
────────────── ────────────
header + purpose decisions
progress counts assumptions
section labels tradeoffs
formatting rules reasoning
Two-block return: MCP tool results get collapsed in Claude Code UI. Block 1 is a one-line summary visible even when collapsed. Block 2 is the full template that Claude renders inline in its response, visible to the user without expanding.
Read-only: augur_explain only reads the plan file. No disk writes, no state, no side effects. Works in plan mode.
Architecture:
claude-augur-mcp/
├── package.json
├── tsconfig.json
├── src/
│ ├── index.ts # MCP server, 1 tool
│ ├── types.ts # PlanStructure interface
│ ├── session.ts # Plan file parser + step progress extractor
│ └── render.ts # Template generator with left-gutter format
└── demo/
├── demo.cast # asciinema recording
└── demo.gif # animated demo
Design principles:
- Template seeding over regex extraction: regex on thinking blocks produced garbage; template seeding lets Claude fill its own reasoning accurately
- Inline over collapsed: tool results get collapsed in Claude Code UI; inline rendering keeps the abstract visible
- Read-only: no disk writes, no state, works in plan mode
- Single tool:
augur_explaindoes one thing well; no CRUD, no storage, no insight management - Left-gutter format:
┌│├└vertical bar with no right border; can't misalign, renders cleanly in any terminal width - Never truncate: purpose and header always render in full; word-wrapped, never cut
Design influences:
- Architecture Decision Records: structured format for capturing decisions with context and consequences
- Y-Statement ADR variant: concise decision format: "In context X, facing Y, we decided Z, accepting C"
- Roman Augurs: priests who interpreted signs and patterns to reveal meaning hidden from ordinary observation
development
git clone https://github.com/Vvkmnn/claude-augur-mcp && cd claude-augur-mcp
npm install && npm run build
Scripts:
| Command | Description |
|---|---|
npm run build |
TypeScript compilation (tsc && chmod +x dist/index.js) |
npm run dev |
Watch mode (tsc --watch) |
npm start |
Run MCP server (node dist/index.js) |
npm run clean |
Remove build artifacts (rm -rf dist) |
npm run typecheck |
TypeScript validation without emit |
npm test |
Type-check |
Contributing:
- Fork the repository and create feature branches
- Follow TypeScript strict mode and MCP protocol standards
Learn from examples:
- Official MCP servers for reference implementations
- TypeScript SDK for best practices
- Creating Node.js modules for npm package development
license
MIT
Tomb of the Augurs, fresco (Tarquinia, ~530 BCE). Claudius, emperor, scholar, and member of the Augural College, wrote Tyrrenika, a lost 20-volume history of Etruscan civilization and their methods of divination. The augurs' role was not to predict the future, but to interpret the signs and reveal whether a proposed course of action had merit.
