mcp-adr 0.1.0__tar.gz

mcp_adr-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

mcp_adr-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+.pytest_cache/
+.ruff_cache/
+.claude/
+dist/
+build/
+*.egg-info/

mcp_adr-0.1.0/CLAUDE.md

@@ -0,0 +1,83 @@
+# CLAUDE.md — mcp-adr
+
+MCP server for Architecture Decision Records: create, manage, diagram, and export ADRs from Markdown files on disk.
+
+## Quick Reference
+
+```bash
+# Install dependencies (dev + runtime)
+uv sync
+
+# Run tests
+uv run pytest
+uv run pytest tests/test_models.py -v
+
+# Lint / format
+uv run ruff check .
+uv run ruff format .
+
+# Run the MCP server locally
+uv run mcp-adr
+```
+
+## Architecture
+
+The project follows a single-package layout under `src/mcp_adr/`. Each module has one clear responsibility so tools compose without circular imports.
+
+- `models.py` — Pydantic models and enums (`Status`, `ADRType`, `DiagramFormat`, `DiagramType`, `ADRMetadata`, `ADRContent`).
+- `storage.py` — Filesystem access: locate ADR directory, read/write files, compute next ADR number.
+- `parser.py` — Parse Markdown ADR files into `ADRContent`; render `ADRContent` back to Markdown.
+- `templates.py` — Jinja2 templates for new ADRs, including `TYPE_EXTRA_SECTIONS` keyed by `ADRType`.
+- `diagrams/` — One submodule per diagram format (mermaid, plantuml, drawio). Dispatched via `get_diagram_generator()`.
+- `analysis.py` — Dependency graphs, supersession chains, status rollups across ADRs.
+- `export.py` — Bundle ADRs into HTML / PDF / single-file Markdown.
+- `index.py` — Build and refresh the ADR index (README-style table of contents).
+- `server.py` — FastMCP entrypoint. Registers every tool with `@mcp.tool()` and delegates to the modules above.
+
+## Agent Rules
+
+- **Understand before implementing.** Read the spec and plan in `docs/` before touching code.
+- **Verify before asserting.** Test assumptions against the actual code or documentation; never guess APIs.
+- **English only.** All code, identifiers, comments, docstrings, and commit messages in English.
+- **No emoji** in code, commits, or documentation.
+- **Follow existing patterns.** Do not refactor unrelated code; keep diffs scoped to the task.
+- **Scope discipline.** Do not add files or features outside the task plan.
+
+## Git Commit Conventions
+
+Use Conventional Commits:
+
+```
+<type>(<optional scope>): <imperative summary>
+```
+
+Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `perf`, `build`, `ci`.
+
+Rules:
+- Imperative mood ("add", not "added").
+- Keep the subject under ~72 chars.
+- One logical change per commit.
+- Reference plan tasks in the body when relevant.
+
+Examples:
+- `feat(parser): parse ADR metadata from Markdown header`
+- `fix(storage): handle missing ADR directory`
+- `test(models): cover ADRMetadata defaults`
+
+## Conventions
+
+### Adding a new MCP tool
+1. Implement the logic in the appropriate module (e.g. `analysis.py`).
+2. Register it in `server.py` with `@mcp.tool()`, keeping the function body a thin delegate.
+3. Add unit tests in `tests/test_<module>.py` and, if needed, an end-to-end test in `tests/test_server.py`.
+
+### Adding a new ADR template section
+- Edit `TYPE_EXTRA_SECTIONS` in `templates.py`, keyed by `ADRType`.
+- Update `parser.py` if the new section must round-trip into `ADRContent.extra_sections`.
+- Add a test in `tests/test_templates.py`.
+
+### Adding a new diagram format
+1. Add the value to the `DiagramFormat` enum in `models.py`.
+2. Create a module under `src/mcp_adr/diagrams/` implementing the generator interface.
+3. Register it in `get_diagram_generator()`.
+4. Add tests in `tests/test_diagrams.py`.

mcp_adr-0.1.0/PKG-INFO

@@ -0,0 +1,366 @@
+Metadata-Version: 2.4
+Name: mcp-adr
+Version: 0.1.0
+Summary: MCP server for Architecture Decision Records — create, manage, diagram, and export ADRs
+Project-URL: Homepage, https://github.com/mauriziomocci/mcp-adr
+Project-URL: Repository, https://github.com/mauriziomocci/mcp-adr
+Project-URL: Issues, https://github.com/mauriziomocci/mcp-adr/issues
+Author-email: Maurizio Mocci <mauriziomocci@gmail.com>
+License: MIT
+Keywords: adr,architecture,decision-records,diagrams,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: fastmcp<4.0.0,>=3.0.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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/
+```