wooxogh/adr-mcp-setup

**adr-skills** is an MCP server for Claude Code that automatically captures development conversations and uses Claude Opus to generate, review, and manage Architecture Decision Records (ADRs).
> **TL;DR:** Install once, and every Claude Code session ends with a structured ADR saved to ~/.adr-mcp/adrs/ — no manual writing required.
What problem does this solve?
Engineering teams make dozens of architectural decisions every week — which database to use, how to handle auth, whether to go monolith or microservices — but rarely write them down. Months later, nobody remembers why Redis was chosen over Memcached, or why the team avoided GraphQL.
**adr-skills** solves this by turning your existing Claude Code conversations into permanent, searchable ADR documents automatically.
How it works
1. You have a normal development conversation in Claude Code
2. When the session ends, the Stop Hook captures the transcript
3. Claude Opus analyzes the conversation and extracts the architectural decision
4. A structured markdown ADR is saved to ~/.adr-mcp/adrs/ADR-0001-*.md
5. Use review_adr to score quality, link_adrs to map dependencies, check_stale_adrs to surface outdated decisions
Features
- **Auto session capture** — Stop Hook saves conversations automatically on Claude Code exit; no manual steps
- **AI-powered ADR generation** — Claude Opus extracts context, decision, and consequences from raw conversation
- **AI quality review** — Scores ADR completeness 0–100 and flags missing context, unconsidered alternatives, or optimistic consequences
- **Duplicate detection** — Warns when a new decision overlaps with a past one before saving
- **Markdown export** — Every ADR exported as ADR-NNNN-slug.md, ready to commit alongside your code
- **Status lifecycle** — Track decisions through Proposed → Accepted → Deprecated → Superseded
- **Dependency graph** — Link ADRs with related_to, conflicts_with, depends_on and visualize relationships
- **Stale ADR alerts** — Surface Accepted decisions older than N months that may need revisiting
- **Keyword search** — Find past decisions by technology name (e.g. Redis, JWT, PostgreSQL)
- **Timeline view** — Full decision history per project, correlated with git commits
How is this different from existing ADR tools?
| Tool | Auto-capture from chat | AI generation | Quality review | MCP server |
|---|:---:|:---:|:---:|:---:|
| **adr-skills** | ✅ | ✅ Claude Opus | ✅ | ✅ |
| adr-tools (CLI) | ❌ | ❌ | ❌ | ❌ |
| mcp-adr-analysis-server | ❌ | ✅ OpenRouter | ❌ | ✅ |
| claude-historian-mcp | ✅ | ❌ | ❌ | ✅ |
| log4brains | ❌ | ❌ | ❌ | ❌ |
No existing tool combines automatic conversation capture with AI-powered ADR generation in a single MCP server. There is an open feature request on the Anthropic repo for native ADR support — adr-skills fills that gap today.
Installation
Register with Claude Code
Environment setup
> Without the API key, generate_adr falls back to keyword-based extraction and review_adr is unavailable. .env is in .gitignore — your key will never be committed.
Enable auto session capture (Stop Hook)