[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_130":131},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":-5,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":48,"_57":58,"_59":60,"_61":-5,"_62":-5,"_63":-5,"_64":-5,"_65":66,"_67":68,"_69":70,"_71":72,"_73":74,"_75":-5,"_76":-5,"_77":-5,"_78":48,"_79":-5,"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91,"_92":93},"apiUrl","https://odel.app/api","creator","atypical-consulting","moduleId","adrmcp","@atypical-consulting/adrmcp","displayName","AdrMcp","tagline","MCP server for Architectural Decision Records: navigate, author, validate, link, and analyze them.","iconKey","https://avatars.githubusercontent.com/u/64837952?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1783657290000,"updatedAt",1788323873000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.Atypical-Consulting%2Fadr-mcp","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",1,"upstreamUpdatedAt",1787360732000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/Atypical-Consulting/AdrMcp","githubRepoFullName","Atypical-Consulting/AdrMcp","releaseId","ext-atypical-consulting-adrmcp","version","0.2.1","descriptionMarkdown","![AdrMcp banner](https://raw.githubusercontent.com/Atypical-Consulting/AdrMcp/dev/.github/banner.png)\n\n# AdrMcp\n\n\n\n## Table of Contents\n\n- [Features](#features)\n- [The problem](#the-problem)\n- [The solution](#the-solution)\n- [Storage & format](#storage--format)\n- [Tools](#tools)\n- [Configuration](#configuration)\n- [Run](#run)\n- [Usage](#usage)\n- [Claude skills](#claude-skills)\n- [Develop](#develop)\n- [Continuous integration](#continuous-integration)\n- [Project layout](#project-layout)\n- [Tech Stack](#tech-stack)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n\n\n\n\n\n## Getting Started\n\n### Prerequisites\n\n- [.NET SDK](https://dotnet.microsoft.com/download)\n\n### Run\n\n```bash\ngit clone https://github.com/Atypical-Consulting/AdrMcp.git\ncd AdrMcp\ndotnet restore\ndotnet build\ndotnet run --project AdrMcp/AdrMcp.csproj\n```\n\n\n\n\n\n\n\n**Every architectural decision, on the record** — an MCP server that turns a folder of Markdown\nADRs into live tools your AI agent can use: search, author, validate, link, and trace decisions.\n\n[![CI](https://github.com/Atypical-Consulting/AdrMcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Atypical-Consulting/AdrMcp/actions/workflows/ci.yml)\n[![NuGet](https://img.shields.io/nuget/v/AdrMcp.svg)](https://www.nuget.org/packages/AdrMcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![.NET 10](https://img.shields.io/badge/.NET-10-512BD4)\n![MCP server](https://img.shields.io/badge/MCP-server-f4b942)\n\n🌐 **[atypical-consulting.github.io/AdrMcp](https://atypical-consulting.github.io/AdrMcp/)**\n\n![AdrMcp — Every architectural decision, on the record](https://atypical-consulting.github.io/AdrMcp/og.png)\n\n## Features\n\n- **Read & search ADRs** — `list_adrs`, `get_adr`, `search_adrs` (lexical or semantic), and `get_adr_index` for the full decision timeline.\n- **Author from a template** — `create_adr` drafts MADR- or Nygard-format ADRs; `update_adr` replaces or appends a single section.\n- **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.\n- **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.\n- **Conflict & coverage analysis** — `detect_conflicts` surfaces contradictory accepted decisions; `coverage_report` highlights ADR coverage gaps by architectural area.\n- **Preview-by-default writes** — every mutating tool defaults to `previewOnly: true` and returns a unified diff before anything touches disk.\n- **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.\n\n## The problem\n\nArchitectural decisions get made in Slack threads, PR comments, and someone's head — then the\nreasoning evaporates. Months later a teammate asks \"why is it done this way?\", nobody remembers, and\nthe decision gets silently re-litigated or accidentally reversed. ADRs fix that — *if* they're\nwritten and kept honest. But a folder of Markdown files is inert: you can't ask it what's still\n`accepted`, trace what superseded what, or notice a decision that no longer matches the code.\n\nIt's worse with AI coding agents: the one collaborator that could keep decisions current has no way\nto read, write, or reason about them.\n\n## The solution\n\nAdrMcp makes that folder a live surface any MCP client can work. It gives your agent tools to list\nand search decisions, draft new ones from a [MADR](https://adr.github.io/madr/) template, validate\nstructure and links, **supersede** a decision while preserving its history, and flag stale or\nconflicting ones — all **preview-by-default**, so nothing is written without you seeing the diff.\n\nThe records stay plain Markdown in git; AdrMcp adds the tools. Built as a .NET 10 stdio MCP server,\narchitecturally modeled on [RoselineMCP](https://github.com/Atypical-Consulting/RoselineMCP) —\nlayered `Tools → Services`, `[McpServerTool]` attributes, shipped as a `dotnet tool` + Docker image.\n\n## Storage & format\n\nADRs are markdown files under an ADR root (default `docs/adr/`), one file per decision named\n`NNNN-kebab-title.md`, using **MADR 4.0** frontmatter + sections:\n\n```markdown\n---\nid: 1\ntitle: Use PostgreSQL for persistence\nstatus: accepted # proposed | accepted | rejected | deprecated | superseded\ndate: 2026-07-08\ntags: [data]\nlinks:\n - { type: superseded-by, target: 5 }\ncode_refs:\n - { path: src/Data/Repository.cs, symbol: PostgresRepository }\n---\n\n# Use PostgreSQL for persistence\n\n## Context and Problem Statement\n...\n## Decision Outcome\n...\n## Consequences\n...\n```\n\nEverything is git-native, human-readable, and diff-able — no database.\n\n## Tools\n\n| Tool | Kind | Description |\n| --- | --- | --- |\n| `list_adrs` | read | List/filter ADRs (status, tag, date range) |\n| `get_adr` | read | Get one ADR; optionally only selected `##` sections |\n| `search_adrs` | read | Lexical (default) or `semantic` term-vector search |\n| `get_adr_index` | read | The decision log / timeline |\n| `find_related_adrs` | read | Incoming/outgoing links + supersession chain |\n| `get_adr_graph` | read | Full relationship graph (nodes + typed edges) |\n| `create_adr` | write | Create an ADR from a template (`madr` or `nygard`) |\n| `update_adr` | write | Replace/append a single `##` section |\n| `set_status` | write | Transition status (enforces the lifecycle) |\n| `supersede_adr` | write | Create replacement + mark old superseded + link, in one call |\n| `link_adrs` | write | Typed link between two ADRs (adds inverse) |\n| `validate_adr` | read | MADR compliance: sections, status, dangling links, duplicate ids |\n| `detect_conflicts` | read | Explicit `conflicts-with` + highly similar accepted ADRs |\n| `find_stale_adrs` | read | ADRs whose `code_refs` no longer resolve |\n| `coverage_report` | read | ADR coverage per architectural area (tag); surfaces gaps |\n| `suggest_adr_from_change` | read | Draft an ADR proposal from a unified diff |\n| `render_index` | write | Regenerate the browsable `README.md` decision index |\n| `diff_adr` | read | Diff two ADRs, or a file vs its canonical rendering |\n\n**Writes are preview-by-default.** Every mutating tool takes `previewOnly` (default `true`) and\nreturns a unified diff of the intended change; pass `previewOnly=false` to write to disk.\n\n## Configuration\n\nResolved in order: CLI arg → env var → default.\n\n| Setting | CLI | Env | Default |\n| --- | --- | --- | --- |\n| ADR root | `--adr-root ` | `ADR_ROOT` | `/docs/adr` |\n| Repo root (for `code_refs`) | `--repo-root ` | `ADR_REPO_ROOT` | current directory |\n\n### Code-linking is provider-based\n\n`find_stale_adrs` resolves `code_refs` through an `ICodeLinkProvider`. The default\n`FileSystemCodeLinkProvider` is language-agnostic (a ref resolves if the file exists and, when a\nsymbol is given, that symbol's text is present). A Roslyn (.NET) or codebase-memory provider can be\nplugged in behind the same interface — deep symbol resolution stays the client's job.\n\n## Run\n\n```bash\n# from source\ndotnet run --project AdrMcp -- --adr-root ./docs/adr\n\n# as a global tool\ndotnet tool install -g AdrMcp\nadr-mcp --adr-root ./docs/adr\n```\n\n### MCP client config\n\n```json\n{\n \"mcpServers\": {\n \"adr\": {\n \"command\": \"adr-mcp\",\n \"args\": [\"--adr-root\", \"/path/to/repo/docs/adr\", \"--repo-root\", \"/path/to/repo\"]\n }\n }\n}\n```\n\n### Docker\n\n```bash\ndocker build -t adr-mcp .\ndocker run --rm -i -v \"$PWD:/workspace\" adr-mcp --adr-root /workspace/docs/adr\n```\n\n## Usage\n\nOnce `adr-mcp` is registered as an MCP server, an agent calls its tools directly. A typical\nread-then-write flow:\n\n```jsonc\n// \"What ADRs do we have about data storage?\"\nlist_adrs({ \"tag\": \"data\" })\n// → [{ \"id\": 5, \"title\": \"Use PostgreSQL for persistence\", \"status\": \"accepted\", \"tags\": [\"data\"] }]\n\n// \"Draft a decision for switching to gRPC internally\" — nothing is written yet\ncreate_adr({\n \"title\": \"Adopt gRPC for internal services\",\n \"template\": \"madr\",\n \"previewOnly\": true\n})\n// → unified diff of the new docs/adr/0006-adopt-grpc-for-internal-services.md\n\n// Once the content looks right, write it for real\ncreate_adr({ \"title\": \"Adopt gRPC for internal services\", \"template\": \"madr\", \"previewOnly\": false })\n\n// Later, retire an old decision in favor of a new one, preserving history\nsupersede_adr({ \"oldId\": 2, \"newTitle\": \"Replace REST gateway with gRPC\", \"previewOnly\": false })\n```\n\n## Claude skills\n\nThree project skills under `.claude/skills/` add the judgment/workflow layer on top of the\nMCP tools (the server provides the mechanics; the skills provide the craft). They activate\nautomatically in Claude Code when the connected AdrMcp server is available:\n\n| Skill | Triggers on | What it does |\n| --- | --- | --- |\n| `adr-author` | \"write an ADR\", \"record this decision\" | Decide if a decision warrants an ADR, frame a sharp Context/Decision/Consequences, draft via `create_adr` + `validate_adr` |\n| `adr-review` | \"review this ADR\", \"does this decision hold up\" | Structural + substantive critique against a rubric, using `validate_adr` / `detect_conflicts` |\n| `adr-supersede` | \"we changed our mind\", \"retire this decision\" | Pick the right lifecycle move and drive `supersede_adr` / `set_status` with correct linking |\n\n## Develop\n\n```bash\ndotnet build AdrMcp.slnx\ndotnet test AdrMcp.slnx # unit tests + MCP-over-stdio integration tests\ndotnet pack AdrMcp/AdrMcp.csproj -c Release -o ./artifacts\n```\n\n## Continuous integration\n\nCI/CD runs on GitHub Actions, modeled on [RoselineMCP](https://github.com/Atypical-Consulting/RoselineMCP):\n\n| Workflow | Trigger | What it does |\n| --- | --- | --- |\n| `ci.yml` | push / PR to `main`/`dev` | Build + test matrix (ubuntu/windows/macos); 80% line-coverage gate on ubuntu |\n| `codeql.yml` | push / PR / weekly | CodeQL security analysis (C#) |\n| `pages.yml` | push to `site/**` on `dev` | Publish the landing page to GitHub Pages |\n| `release-please.yml` | push to `dev` | Maintain a release PR (Conventional Commits); on merge, publish NuGet + MCPB + MCP Registry + GHCR image |\n\nReleases are automated with [release-please](https://github.com/googleapis/release-please): merge the\nrelease PR it opens to ship. See [PUBLISH.md](https://github.com/Atypical-Consulting/AdrMcp/blob/dev/PUBLISH.md).\n\n## Project layout\n\n```\nAdrMcp/\n├── Interfaces/ service contracts (IAdrRepository, ICodeLinkProvider, …)\n├── Services/ repository, templates, validation, graph, search, embeddings, code-links\n├── Tools/ Navigation / Authoring / Intelligence / Utility MCP tools\n├── Models/ Adr, AdrStatus, AdrLink, CodeRef, response DTOs\n└── Program.cs DI wiring + stdio MCP host\n```\n\n---\n\n\n\n## Tech Stack\n\n- **.NET 10**\n- ModelContextProtocol\n- xunit\n- xunit.runner.visualstudio\n- DiffPlex\n- Markdig\n- Microsoft.Extensions.Hosting\n- YamlDotNet\n\n\n\n## Roadmap\n\n- [ ] Real embedding-backed semantic search for `search_adrs` / `detect_conflicts` (beyond term-vector similarity)\n- [ ] Roslyn-based `ICodeLinkProvider` for deep C# symbol resolution in `find_stale_adrs`\n- [ ] Additional ADR templates beyond MADR/Nygard (e.g. Y-statements)\n- [ ] Editor extension (VS Code / JetBrains) to browse and visualize the decision graph\n- [ ] Broaden the CI coverage gate and publish to additional package registries\n\nSee the [open issues](https://github.com/Atypical-Consulting/AdrMcp/issues) for details and to propose new ideas.\n\n## Atypical MCP servers\n\nPart of a suite of Model Context Protocol servers by Atypical Consulting:\n\n- [RoselineMCP](https://github.com/Atypical-Consulting/RoselineMCP) — Roslyn code intelligence for AI agents\n- [ASTral](https://github.com/Atypical-Consulting/ASTral) — structured code retrieval (tree-sitter)\n- [AdrMcp](https://github.com/Atypical-Consulting/AdrMcp) — Architecture Decision Records over MCP\n- [MarkdownInk](https://github.com/Atypical-Consulting/MarkdownInk) — Markdown rendering for the terminal\n\n\n\n## Contributing\n\nContributions are welcome. Open an issue first to discuss any significant change.\n\n1. Fork the repository and create your branch (`git checkout -b feat/my-feature`)\n2. Commit your changes (`git commit -m 'feat: ...'`)\n3. Push the branch and open a Pull Request\n\n\n\n\n---\nBuilt by [Atypical Consulting](https://www.atypical.consulting). We also make\n[NuGetKeep](https://nugetkeep.com/?utm_source=github-readme&utm_medium=readme&utm_campaign=launch-2026-07),\na self-hosted NuGet server with supply-chain quarantine.\n\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_111":112,"_113":114,"_115":116,"_117":118,"_119":120,"_121":122},"requiredSecrets",[],"tags",[96,97,98,99,100,101,102,103,104,105,106,107,108,109,110],"assets",[],"stats",{"_94":81,"_95":81},"ratingAvg","reviewCount","adr","ai","ai-agents","architecture-decision-records","claude","claude-code","copilot","csharp","cursor","decision-records","developer-tools","documentation","dotnet","llm","madr","topics",[96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,127,128,129],"license","MIT","language","C#","registryName","io.github.Atypical-Consulting/adr-mcp","homepage","https://atypical-consulting.github.io/AdrMcp/","packages",[123],{"_124":125,"_126":24,"_71":72},"registryType","nuget","identifier","mcp","mcp-server","model-context-protocol","ENV",{"_132":133,"_134":135,"_136":137},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]