AdrMcp

AdrMcp

Table of Contents

• Features
• The problem
• The solution
• Storage & format
• Tools
• Configuration
• Run
• Usage
• Claude skills
• Develop
• Continuous integration
• Project layout
• Tech Stack
• Roadmap
• Contributing

Getting Started

Prerequisites

• .NET SDK

Run

git clone https://github.com/Atypical-Consulting/AdrMcp.git

cd AdrMcp dotnet restore dotnet build dotnet run --project AdrMcp/AdrMcp.csproj

Every architectural decision, on the record — an MCP server that turns a folder of Markdown ADRs into live tools your AI agent can use: search, author, validate, link, and trace decisions.

🌐 [atypical-consulting.github.io/AdrMcp](https://atypical-consulting.github.io/AdrMcp/)

Features

• Read & search ADRs — list_adrs, get_adr, search_adrs (lexical or semantic), and get_adr_index for the full decision timeline.
• Author from a template — create_adr drafts MADR- or Nygard-format ADRs; update_adr replaces or appends a single section.
• Lifecycle-aware transitions — set_status enforces the ADR lifecycle; supersede_adr creates the replacement and marks/links the old one superseded in a single call.
• Relationship graph & staleness detection — find_related_adrs / get_adr_graph expose links and supersession chains; find_stale_adrs flags ADRs whose code_refs no longer resolve in the codebase.
• Conflict & coverage analysis — detect_conflicts surfaces contradictory accepted decisions; coverage_report highlights ADR coverage gaps by architectural area.
• Preview-by-default writes — every mutating tool defaults to previewOnly: true and returns a unified diff before anything touches disk.
• Ships as a dotnet tool, NuGet package, and Docker image, plus three bundled Claude Code skills (adr-author, adr-review, adr-supersede) for the judgment layer on top of the raw tools.

The problem

Architectural decisions get made in Slack threads, PR comments, and someone's head — then the reasoning evaporates. Months later a teammate asks "why is it done this way?", nobody remembers, and the decision gets silently re-litigated or accidentally reversed. ADRs fix that — *if* they're written and kept honest. But a folder of Markdown files is inert: you can't ask it what's still accepted, trace what superseded what, or notice a decision that no longer matches the code.

It's worse with AI coding agents: the one collaborator that could keep decisions current has no way to read, write, or reason about them.

The solution

AdrMcp makes that folder a live surface any MCP client can work. It gives your agent tools to list and search decisions, draft new ones from a MADR template, validate structure and links, supersede a decision while preserving its history, and flag stale or conflicting ones — all preview-by-default, so nothing is written without you seeing the diff.

The records stay plain Markdown in git; AdrMcp adds the tools. Built as a .NET 10 stdio MCP server, architecturally modeled on RoselineMCP — layered Tools → Services, [McpServerTool] attributes, shipped as a dotnet tool + Docker image.

Storage & format

ADRs are markdown files under an ADR root (default docs/adr/), one file per decision named NNNN-kebab-title.md, using MADR 4.0 frontmatter + sections:

---

id: 1 title: Use PostgreSQL for persistence status: accepted # proposed | accepted | rejected | deprecated | superseded date: 2026-07-08 tags: [data] links:

• { type: superseded-by, target: 5 }

code_refs:

• { path: src/Data/Repository.cs, symbol: PostgresRepository }

---

Use PostgreSQL for persistence

Context and Problem Statement

...

Decision Outcome

...

Consequences

...

Everything is git-native, human-readable, and diff-able — no database.

Tools

Writes are preview-by-default. Every mutating tool takes previewOnly (default true) and returns a unified diff of the intended change; pass previewOnly=false to write to disk.

Configuration

Resolved in order: CLI arg → env var → default.

Code-linking is provider-based

find_stale_adrs resolves code_refs through an ICodeLinkProvider. The default FileSystemCodeLinkProvider is language-agnostic (a ref resolves if the file exists and, when a symbol is given, that symbol's text is present). A Roslyn (.NET) or codebase-memory provider can be plugged in behind the same interface — deep symbol resolution stays the client's job.

Run

# from source

dotnet run --project AdrMcp -- --adr-root ./docs/adr

as a global tool

dotnet tool install -g AdrMcp adr-mcp --adr-root ./docs/adr

MCP client config

{

"mcpServers": { "adr": { "command": "adr-mcp", "args": ["--adr-root", "/path/to/repo/docs/adr", "--repo-root", "/path/to/repo"] } } }

Docker

docker build -t adr-mcp .

docker run --rm -i -v "$PWD:/workspace" adr-mcp --adr-root /workspace/docs/adr

Usage

Once adr-mcp is registered as an MCP server, an agent calls its tools directly. A typical read-then-write flow:

// "What ADRs do we have about data storage?"

list_adrs({ "tag": "data" }) // → [{ "id": 5, "title": "Use PostgreSQL for persistence", "status": "accepted", "tags": ["data"] }]

// "Draft a decision for switching to gRPC internally" — nothing is written yet create_adr({ "title": "Adopt gRPC for internal services", "template": "madr", "previewOnly": true }) // → unified diff of the new docs/adr/0006-adopt-grpc-for-internal-services.md

// Once the content looks right, write it for real create_adr({ "title": "Adopt gRPC for internal services", "template": "madr", "previewOnly": false })

// Later, retire an old decision in favor of a new one, preserving history supersede_adr({ "oldId": 2, "newTitle": "Replace REST gateway with gRPC", "previewOnly": false })

Claude skills

Three project skills under .claude/skills/ add the judgment/workflow layer on top of the MCP tools (the server provides the mechanics; the skills provide the craft). They activate automatically in Claude Code when the connected AdrMcp server is available:

Develop

dotnet build AdrMcp.slnx

dotnet test AdrMcp.slnx # unit tests + MCP-over-stdio integration tests dotnet pack AdrMcp/AdrMcp.csproj -c Release -o ./artifacts

Continuous integration

CI/CD runs on GitHub Actions, modeled on RoselineMCP:

Releases are automated with release-please: merge the release PR it opens to ship. See PUBLISH.md.

Project layout

AdrMcp/

├── Interfaces/ service contracts (IAdrRepository, ICodeLinkProvider, …) ├── Services/ repository, templates, validation, graph, search, embeddings, code-links ├── Tools/ Navigation / Authoring / Intelligence / Utility MCP tools ├── Models/ Adr, AdrStatus, AdrLink, CodeRef, response DTOs └── Program.cs DI wiring + stdio MCP host

---

Tech Stack

• .NET 10
• ModelContextProtocol
• xunit
• xunit.runner.visualstudio
• DiffPlex
• Markdig
• Microsoft.Extensions.Hosting
• YamlDotNet

Roadmap

• Real embedding-backed semantic search for search_adrs / detect_conflicts (beyond term-vector similarity)
• Roslyn-based ICodeLinkProvider for deep C# symbol resolution in find_stale_adrs
• Additional ADR templates beyond MADR/Nygard (e.g. Y-statements)
• Editor extension (VS Code / JetBrains) to browse and visualize the decision graph
• Broaden the CI coverage gate and publish to additional package registries

See the open issues for details and to propose new ideas.

Atypical MCP servers

Part of a suite of Model Context Protocol servers by Atypical Consulting:

• RoselineMCP — Roslyn code intelligence for AI agents
• ASTral — structu