Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claude-augur-mcp Show me the decisions in my plan file at ~/.claude/plans/plan.md"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Requirements:
From shell:
claude mcp add claude-augur-mcp -- npx claude-augur-mcpFrom inside Claude (restart required):
Add this to our global mcp config: npx claude-augur-mcp
Install this mcp: https://github.com/Vvkmnn/claude-augur-mcpFrom 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-mcpRelated MCP server: Dev Notes MCP Server
1 tool. Plan structure extraction. Template seeding. Inline rendering.
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 doneBlock 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 |
|
Purpose | First | Full text, word-wrapped |
Sections | H2 headings (excluding |
|
Progress |
|
|
Done steps | Steps where all items are | Capped at 2 names + |
Next steps | Steps with pending items | First name + |
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 reasoningTwo-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 demoDesign 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_explain does 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
git clone https://github.com/Vvkmnn/claude-augur-mcp && cd claude-augur-mcp
npm install && npm run buildScripts:
Command | Description |
| TypeScript compilation ( |
| Watch mode ( |
| Run MCP server ( |
| Remove build artifacts ( |
| TypeScript validation without emit |
| 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
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.
Extract plan structure and return a template for inline rendering. Call after writing/editing plan files. Render the filled template INLINE in your response (not in a code block).
| Name | Required | Description | Default |
|---|---|---|---|
| plan_path | Yes | Absolute path to the plan file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds non-obvious behavioral context the annotations do not: that it returns a template, and that the agent must render the filled template inline rather than in a code block.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, all front-loaded: purpose first, then trigger condition, then rendering instruction. No filler and every sentence carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description appropriately discloses the return value (a template) and how to consume it. No auth, error, or edge-case behavior is mentioned, but for this simple read-only extraction tool the coverage is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter (plan_path) is fully documented by the schema. The description only obliquely references 'plan files' and adds no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Extract plan structure and return a template') and a concrete resource (plan files). It is clear what the tool produces, though 'plan structure' remains somewhat abstract and there are no siblings to distinguish it from.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit timing guidance ('Call after writing/editing plan files') and a clear rendering instruction ('INLINE ... not in a code block'). There are no alternatives to name since no sibling tools exist, so no exclusions are possible.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1augur_explainScored across 1 tool
Only one tool is exposed, so there is no possibility of selecting the wrong tool or confusing overlapping purposes. Its purpose—extracting plan structure and returning an inline template—is clearly stated.
The sole tool uses a clear snake_case name with a consistent augur_ prefix. With only one tool, there are no naming inconsistencies to evaluate.
One tool is thin for an MCP server, but it matches a narrow, single-purpose helper. It is borderline rather than extreme because the operation is non-trivial and self-contained.
The tool covers the stated operation of extracting plan structure and producing a renderable template. There are no lifecycle operations like validation or template customization, but those are not clearly required by the described scope.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
Read and write your Fresh Jots notes from Claude, Cursor, and any MCP client.
Structured visual plans and PR recaps with diagrams, prototypes, annotations, and sharing
