# mcp-adr

[![PyPI version](https://img.shields.io/pypi/v/mcp-adr.svg)](https://pypi.org/project/mcp-adr/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/pypi/pyversions/mcp-adr.svg)](https://pypi.org/project/mcp-adr/)

An [MCP](https://modelcontextprotocol.io) 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

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

## Configuration

### Claude Code (`settings.json`)

```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**

```python
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**

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

**3. Accept the decision**

```python
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**

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

**5. Export to HTML for sharing**

```python
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.

```python
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**

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

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

---

## Development

```bash
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](https://modelcontextprotocol.io) 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

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

## Configurazione

### Claude Code (`settings.json`)

```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

```python
# 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

```bash
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/
```