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

Variable	Default	Description
ADR_DIR	docs/adr	Directory where ADR markdown files live

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

---

Tools Reference

CRUD

Tool	Key parameters	Description
adr_create	title, type, context, decision, deciders	Create a new ADR from a typed template
adr_read	query	Read an ADR by number or title substring
adr_update	number, content	Overwrite an ADR with new markdown content
adr_list	status, type	List all ADRs, optionally filtered
adr_search	query	Full-text search across all ADR content

Lifecycle

Tool	Key parameters	Description
adr_update_status	number, status, reason	Change status (Proposed/Accepted/Deprecated/Superseded)
adr_supersede	old_number, new_number	Mark an ADR as superseded, linking both documents
adr_deprecate	number, reason	Deprecate an ADR with a recorded reason
adr_link	from_number, to_number	Add a bidirectional related link between two ADRs
adr_history	query	Return matching ADRs as a timeline sorted by date

Diagrams

Tool	Key parameters	Description
adr_diagram	number, format, diagram_type	Generate a diagram for a single ADR
adr_overview	format, status_filter	Generate an overview diagram of all ADRs

Analysis

Tool	Key parameters	Description
adr_impact	component	Find all ADRs that mention a given component
adr_dependencies	number, format	Build or filter the ADR dependency graph

Export

Tool	Key parameters	Description
adr_export	output_dir	Export all ADRs to HTML files

---

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.

Type	Extra sections
architecture	Components, Interactions, Constraints
technology	Evaluation Criteria, Comparison Matrix
integration	Interface Contract, Data Flow, Failure Modes
data	Schema Changes, Migration Strategy, Rollback Plan
security	Threat Model, Controls, Compliance
infrastructure	Topology, Scaling Strategy, DR Plan

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

---

Diagram Formats

Format	Output	Rendering	Best for
mermaid	Text	GitHub, GitLab, Notion, etc.	Quick inline diagrams in markdown
plantuml	Text	PlantUML server or plugin	Richer UML notation, sequence diagrams
drawio	XML file	draw.io / diagrams.net	Editable, polished architecture diagrams

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

Variabile	Predefinito	Descrizione
ADR_DIR	docs/adr	Directory in cui risiedono i file markdown ADR

---

Riferimento strumenti

CRUD

Strumento	Parametri principali	Descrizione
adr_create	title, type, context, decision, deciders	Crea un nuovo ADR da un template tipizzato
adr_read	query	Legge un ADR per numero o sottostringa del titolo
adr_update	number, content	Sovrascrive un ADR con nuovo contenuto markdown
adr_list	status, type	Elenca tutti gli ADR, con filtri opzionali
adr_search	query	Ricerca full-text su tutto il contenuto ADR

Ciclo di vita

Strumento	Parametri principali	Descrizione
adr_update_status	number, status, reason	Cambia lo stato (Proposed/Accepted/Deprecated/Superseded)
adr_supersede	old_number, new_number	Marca un ADR come sostituito, collegando entrambi
adr_deprecate	number, reason	Depreca un ADR con una motivazione registrata
adr_link	from_number, to_number	Aggiunge un collegamento bidirezionale tra due ADR
adr_history	query	Restituisce gli ADR corrispondenti come timeline

Diagrammi

Strumento	Parametri principali	Descrizione
adr_diagram	number, format, diagram_type	Genera un diagramma per un singolo ADR
adr_overview	format, status_filter	Genera un diagramma panoramico di tutti gli ADR

Analisi

Strumento	Parametri principali	Descrizione
adr_impact	component	Trova tutti gli ADR che menzionano un componente
adr_dependencies	number, format	Costruisce o filtra il grafo delle dipendenze ADR

Esportazione

Strumento	Parametri principali	Descrizione
adr_export	output_dir	Esporta tutti gli ADR in HTML

---

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/