AdrMcp MCP server

AdrMcp

<!-- portfolio-toc:start -->

Table of Contents

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

<!-- portfolio-toc:end -->

<!-- portfolio-getstarted:start -->

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

<!-- portfolio-getstarted:end -->

<!-- mcp-name: io.github.Atypical-Consulting/adr-mcp -->

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

Features

• Read & search ADRs — listadrs, getadr, searchadrs (lexical or semantic), and getadr_index for the full decision timeline.
• Author from a template — createadr drafts MADR- or Nygard-format ADRs; updateadr replaces or appends a single section.
• Lifecycle-aware transitions — setstatus enforces the ADR lifecycle; supersedeadr creates the replacement and marks/links the old one superseded in a single call.
• Relationship graph & staleness detection — findrelatedadrs / getadrgraph expose links and supersession chains; findstaleadrs flags ADRs whose code_refs no longer resolve in the codebase.
• Conflict & coverage analysis — detectconflicts surfaces contradictory accepted decisions; coveragereport 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

Shortened. The full README is on GitHub.