AdrMcp

AdrMcp

目录

• 功能
• 问题
• 解决方案
• 存储与格式
• 工具
• 配置
• 运行
• 用法
• Claude 技能
• 开发
• 持续集成
• 项目布局
• 技术栈
• 路线图
• 贡献

快速开始

前置条件

• .NET SDK

运行

git clone https://github.com/Atypical-Consulting/AdrMcp.git
cd AdrMcp
dotnet restore
dotnet build
dotnet run --project AdrMcp/AdrMcp.csproj

每项架构决策，都有据可查——一个 MCP 服务，可将一组 Markdown ADR 转化为 AI Agent 可用的实时工具：搜索、撰写、验证、关联并追溯决策。

🌐 atypical-consulting.github.io/AdrMcp

功能

• 读取和搜索 ADR——list_adrs、get_adr、search_adrs（词法或语义搜索），以及用于查看完整决策时间线的 get_adr_index。
• 根据模板撰写——create_adr 根据 MADR 或 Nygard 格式起草 ADR；update_adr 替换或追加单个章节。
• 感知生命周期的状态转换——set_status 强制执行 ADR 生命周期；supersede_adr 在一次调用中创建替代 ADR，并将旧 ADR 标记为已取代且建立关联。
• 关系图与过时检测——find_related_adrs / get_adr_graph 展示关联和取代链；find_stale_adrs 标记 code_refs 在代码库中已无法解析的 ADR。
• 冲突与覆盖分析——detect_conflicts 揭示相互矛盾的已接受决策；coverage_report 按架构领域指出 ADR 覆盖缺口。
• 默认预览写入——所有变更类工具默认将 previewOnly: true，并在写入磁盘前返回统一差异。
• 以 dotnet 工具、NuGet 包和 Docker 镜像形式发布，另附三个 Claude Code 技能（adr-author、adr-review、adr-supersede），用于在底层工具之上提供判断能力。

问题

架构决策往往产生于 Slack 讨论串、PR 评论和某人的脑海中，随后推理过程便逐渐消失。几个月后，队友问“为什么要这样做？”，却没人记得，于是决策被悄悄重新讨论，或意外推翻。ADR 可以解决这个问题——前提是有人撰写并如实维护它们。但一组 Markdown 文件是静态的：你无法询问哪些决策仍处于 accepted 状态、追溯哪些决策取代了哪些决策，或发现不再符合代码现状的决策。

对于 AI 编码 Agent 来说，情况更糟：这个本可以让决策保持最新的协作者，却无从读取、编写或推理这些决策。

解决方案

AdrMcp 将这组文件变为任何 MCP 客户端都能使用的实时界面。它为你的 Agent 提供工具，用于列出和搜索决策、根据 MADR 模板起草新决策、验证结构和关联、在保留历史记录的同时取代决策，以及标记过时或相互冲突的决策——所有写入都默认先预览，你查看差异后才会写入任何内容。

记录仍以纯 Markdown 格式存储在 git 中；AdrMcp 负责提供工具。它基于 .NET 10 构建为 stdio MCP 服务，架构参考了 RoselineMCP——采用分层的 Tools → Services 结构、[McpServerTool] 特性，并以 dotnet tool 和 Docker 镜像形式发布。

存储与格式

ADR 是存放在 ADR 根目录（默认为 docs/adr/）下的 Markdown 文件，每个决策对应一个文件，命名为 NNNN-kebab-title.md，采用 MADR 4.0 frontmatter 和章节：

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

所有内容都原生支持 Git、便于阅读和比较差异——无需数据库。

工具

工具	类型	描述
list_adrs	读取	列出／筛选 ADR（按状态、标签、日期范围）
get_adr	读取	获取一条 ADR；可选仅获取选定的 ## 章节
search_adrs	读取	词法搜索（默认）或 semantic 术语向量搜索
get_adr_index	读取	决策日志／时间线
find_related_adrs	读取	入站／出站链接及取代链
get_adr_graph	读取	完整关系图（节点 + 类型化边）
create_adr	写入	使用模板（madr 或 nygard）创建 ADR
update_adr	写入	替换／追加单个 ## 章节
set_status	写入	转换状态（强制遵循生命周期）
supersede_adr	写入	一次调用即可创建替代项、将旧项标记为已取代并建立链接
link_adrs	写入	在两条 ADR 之间建立类型化链接（并添加反向链接）
validate_adr	读取	检查 MADR 合规性：章节、状态、失效链接、重复 ID
detect_conflicts	读取	显式的 conflicts-with 关系及高度相似的已接受 ADR
find_stale_adrs	读取	code_refs 不再有效的 ADR
coverage_report	读取	按架构领域（标签）报告 ADR 覆盖情况；指出缺口
suggest_adr_from_change	读取	根据统一差异草拟 ADR 提案
render_index	写入	重新生成可浏览的决策索引 README.md
diff_adr	读取	比较两条 ADR，或比较文件与其规范化渲染结果

写入操作默认仅预览。 每个修改类工具都接受 previewOnly（默认值为 true），并返回预期变更的统一差异；传入 previewOnly=false 即可写入磁盘。

配置

按以下顺序解析：CLI 参数 → 环境变量 → 默认值。

设置	CLI	环境变量	默认值
ADR 根目录	--adr-root <path>	ADR_ROOT	<repo>/docs/adr
仓库根目录（用于 code_refs）	--repo-root <path>	ADR_REPO_ROOT	当前目录

代码链接采用提供程序机制

find_stale_adrs 通过 ICodeLinkProvider 解析 code_refs。默认的 FileSystemCodeLinkProvider 与语言无关（文件存在时即可解析引用；若指定了符号，则还要求文件中包含该符号文本）。可以通过相同接口接入 Roslyn（.NET）或 codebase-memory 提供程序——深入解析符号仍由客户端负责。

运行

# 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 客户端配置

{
  "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

用法

将 adr-mcp 注册为 MCP 服务后，Agent 会直接调用其工具。典型的先读取后写入流程：

// "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 技能

项目在 .claude/skills/ 下提供三项技能，为 MCP 工具增添判断／工作流层（服务端提供机制；技能提供实践方法）。连接的 AdrMcp 服务可用时，这些技能会在 Claude Code 中自动激活：

技能	触发条件	功能
adr-author	“编写 ADR”、“记录此决策”	判断某项决策是否值得记录为 ADR，清晰界定 Context／Decision／Consequences，并通过 create_adr + validate_adr 起草
adr-review	“审查这条 ADR”、“这项决策是否站得住脚”	按照评审标准进行结构与实质性评估，使用 validate_adr / detect_conflicts
adr-supersede	“我们改变主意了”、“弃用这项决策”	选择合适的生命周期操作，并通过 supersede_adr / set_status 完成操作及正确链接

开发

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

持续集成

CI/CD 在 GitHub Actions 上运行，参考了 RoselineMCP：

工作流	触发条件	功能
ci.yml	向 main/dev 推送 / 提交 PR	构建 + 测试矩阵（ubuntu/windows/macos）；ubuntu 上的行覆盖率门槛为 80%
codeql.yml	推送 / 提交 PR / 每周	CodeQL 安全分析（C#）
pages.yml	向 dev 上的 site/** 推送	将着陆页发布到 GitHub Pages
release-please.yml	向 dev 推送	维护发布 PR（Conventional Commits）；合并后发布 NuGet + MCPB + MCP Registry + GHCR 镜像

发布由 release-please 自动完成：合并它创建的 发布 PR 即可发布。参见 PUBLISH.md。

项目结构

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

---

技术栈

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

路线图

• 为 search_adrs / detect_conflicts 实现基于真实嵌入的语义搜索（超越词项向量相似度）
• 基于 Roslyn 的 ICodeLinkProvider，用于在 find_stale_adrs 中深入解析 C# 符号
• 增加 MADR/Nygard 之外的 ADR 模板（例如 Y-statements）
• 开发编辑器扩展（VS Code / JetBrains），用于浏览和可视化决策图
• 扩大 CI 覆盖率门槛，并发布到其他软件包注册表

详情请参阅未解决的问题，也欢迎提出新想法。

Atypical MCP 服务

这是 Atypical Consulting 的一系列 Model Context Protocol 服务之一：

• RoselineMCP — 为 AI Agent 提供 Roslyn 代码智能
• ASTral — 结构化代码检索（tree-sitter）
• AdrMcp — 通过 MCP 管理架构决策记录
• MarkdownInk — 在终端中渲染 Markdown

贡献

欢迎贡献。对于任何重大更改，请先创建 issue 进行讨论。

1. Fork 仓库并创建分支（git checkout -b feat/my-feature）
2. 提交更改（git commit -m 'feat: ...'）
3. 推送分支并创建 Pull Request

---

由 Atypical Consulting 构建。我们还开发了 NuGetKeep， 这是一个可自托管的 NuGet 服务，提供供应链隔离功能。