mcp-adr

mcp-adr

An MCP server that lets AI assistants create, manage, diagram, and export Architecture Decision Records (ADRs) directly from your conversation.

What are ADRs?

Architecture Decision Records are lightweight documents that capture the context, rationale, and consequences of significant architectural choices made during software development. They provide a searchable, version-controlled audit trail that helps teams understand why the system is built the way it is — not just how. Keeping ADRs close to the code prevents institutional knowledge from walking out the door when team members change.

Features

• Six typed templates — architecture, technology, integration, data, security, infrastructure — each with domain-specific sections generated automatically
• Full lifecycle management — propose, accept, deprecate, or supersede ADRs with a single tool call; bidirectional links are maintained automatically
• Diagram generation — Mermaid, PlantUML, and Draw.io output formats with per-ADR and project-wide overview diagrams
• Impact analysis — find every ADR that mentions a component, build a full transitive dependency graph
• Full-text search — query across all ADR content in the project
• HTML export — render every ADR to standalone HTML pages with navigation
• Companion skill — a Claude Code skill that gives the assistant deep ADR workflow knowledge without tool calls

Installation

pip install mcp-adr
# or
uv add mcp-adr

Configuration

Claude Code (settings.json)

{
  "mcpServers": {
    "mcp-adr": {
      "command": "mcp-adr"
    }
  }
}

Environment variables

Every tool also accepts an optional project_path parameter to override the working directory at call time.

Tools Reference

CRUD

Lifecycle

Diagrams

Analysis

Export

Example Workflow

The following example walks through capturing a major API migration decision.

1. Create the ADR

adr_create(
    title="Migrate from REST to GraphQL",
    type="architecture",
    context="The mobile team reports over-fetching on every screen. REST endpoints return 40+ fields; clients use 5.",
    decision="Adopt GraphQL via Apollo Server. REST endpoints remain for external partners.",
    deciders="platform-team"
)
# → {"number": 1, "title": "Migrate from REST to GraphQL", "status": "Proposed", ...}

2. Generate a diagram

adr_diagram(number=1, format="mermaid")
# → {"number": 1, "format": "mermaid", "result": "<Mermaid context for LLM to render>"}

3. Accept the decision

adr_update_status(number=1, status="Accepted", reason="Approved in architecture review 2026-04-11")
# → {"number": 1, "old_status": "Proposed", "new_status": "Accepted"}

4. Check impact before changing the API layer

adr_impact(component="REST")
# → {"component": "REST", "count": 1, "results": [...]}

5. Export to HTML for sharing

adr_export(output_dir="site/adrs")
# → {"output_dir": "site/adrs", "files_count": 1, "files": ["site/adrs/ADR-0001.html"]}

Template Types

Each type value activates a set of domain-specific extra sections inserted between Consequences and Diagram.

All types share the common sections: Context, Decision, Alternatives Considered, Consequences (Positive / Negative / Risks), Diagram, Notes.

Diagram Formats

For mermaid and plantuml, the tool returns a context block that the LLM uses to render or display the diagram. For drawio, the tool writes a .drawio file alongside the ADR and records a link in the ADR's Diagram section.

Export

adr_export renders every ADR in the project to a self-contained HTML file using a built-in Jinja2 template. Files are written to output_dir (default: docs/adr/html). An index.html is also generated.

adr_export(output_dir="docs/adr/html")
# Produces:
#   docs/adr/html/index.html
#   docs/adr/html/ADR-0001-migrate-from-rest-to-graphql.html
#   ...

Companion Skill

A Claude Code skill is included that gives the assistant deep ADR workflow knowledge — it understands naming conventions, when to propose vs accept, how to chain tools, and how to produce complete ADRs in one pass.

Install

cp skills/adr/SKILL.md ~/.claude/skills/adr/SKILL.md

After installation, Claude Code will automatically load the skill when working with ADRs.

Development

git clone https://github.com/mauriziomocci/mcp-adr.git
cd mcp-adr
uv sync
uv run pytest -v
uv run ruff check src/mcp_adr/
uv run ruff format --check src/mcp_adr/

mcp-adr (Italiano)

Un server MCP che permette agli assistenti AI di creare, gestire, visualizzare ed esportare Architecture Decision Records (ADR) direttamente dalla conversazione.

Cosa sono gli ADR?

Gli Architecture Decision Records sono documenti leggeri che catturano il contesto, la motivazione e le conseguenze delle scelte architetturali significative prese durante lo sviluppo software. Forniscono una traccia verificabile e versionata che aiuta i team a capire perché il sistema e costruito in un certo modo — non solo come. Mantenere gli ADR vicino al codice evita la perdita di conoscenza istituzionale quando i membri del team cambiano.

Installazione

pip install mcp-adr
# oppure
uv add mcp-adr

Configurazione

Claude Code (settings.json)

{
  "mcpServers": {
    "mcp-adr": {
      "command": "mcp-adr"
    }
  }
}

Variabili d'ambiente

Riferimento strumenti

CRUD

Ciclo di vita

Diagrammi

Analisi

Esportazione

Esempio di workflow

# 1. Crea l'ADR
adr_create(
    title="Migrazione da REST a GraphQL",
    type="architecture",
    context="Il team mobile segnala over-fetching su ogni schermata.",
    decision="Adottare GraphQL via Apollo Server. Gli endpoint REST rimangono per i partner esterni.",
)
# → ADR-0001 creato con stato Proposed

# 2. Genera il diagramma
adr_diagram(number=1, format="mermaid")
# → Contesto Mermaid restituito all'LLM

# 3. Accetta la decisione
adr_update_status(number=1, status="Accepted")
# → Stato cambiato: Proposed → Accepted

# 4. Analizza l'impatto
adr_impact(component="REST")
# → Lista degli ADR che menzionano REST

# 5. Esporta in HTML
adr_export(output_dir="docs/adr/html")
# → File HTML generati

Sviluppo

git clone https://github.com/mauriziomocci/mcp-adr.git
cd mcp-adr
uv sync
uv run pytest -v
uv run ruff check src/mcp_adr/