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

すべてのアーキテクチャ上の決定を記録に残す — Markdown の ADR が保存されたフォルダーを、AI エージェントが利用できるライブツールに変換する MCP サーバーです。決定の検索、作成、検証、リンク、追跡ができます。

🌐 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 は置き換え先を作成するとともに、1 回の呼び出しで旧 ADR を廃止済みに設定し、リンクします。
• 関連グラフと陳腐化の検出 — find_related_adrs／get_adr_graph はリンクと置き換えの連鎖を公開します。find_stale_adrs は、code_refs がコードベース内で解決できなくなった ADR を検出します。
• 競合と網羅性の分析 — detect_conflicts は矛盾する採用済みの決定を明らかにし、coverage_report はアーキテクチャ領域ごとの ADR の不足箇所を示します。
• 既定でプレビューして書き込み — 変更を伴うすべてのツールは、既定で previewOnly: true となり、ディスクに書き込む前に統一 diff を返します。
• dotnet ツール、NuGet パッケージ、Docker イメージとして提供されるほか、基本ツールの上位にある判断レイヤーとして、Claude Code スキルが 3 つ同梱されています（adr-author、adr-review、adr-supersede）。

課題

アーキテクチャ上の決定は Slack のスレッドや PR のコメント、誰かの頭の中で行われ、その根拠はやがて消えてしまいます。数か月後、チームメイトが「なぜこのようになっているのか」と尋ねても、誰も覚えておらず、決定はいつの間にか再検討されたり、誤って覆されたりします。ADR はこの問題を解決します。ただし、作成され、内容が正確に保たれていればの話です。しかし、Markdown ファイルのフォルダーは、それだけでは何もできません。現在も accepted である決定を尋ねたり、何が何に置き換えられたかを追跡したり、コードと一致しなくなった決定に気づいたりすることはできません。

AI コーディングエージェントが関わると、状況はさらに悪化します。決定を最新の状態に保てる唯一の協力者であるにもかかわらず、決定を読み取ることも、書き込むことも、それについて推論することもできません。

解決策

AdrMcp は、どの MCP クライアントからでも利用できるライブな窓口として、そのフォルダーを機能させます。エージェントが決定の一覧表示や検索、MADR テンプレートを使った新しい決定の作成、構造とリンクの検証、履歴を保ったままの決定の置き換え、陳腐化や競合の検出を行うツールを提供します。すべて既定でプレビューされるため、diff を確認せずに書き込まれることはありません。

記録は Git 内のプレーンな Markdown のままです。AdrMcp がツールを追加します。.NET 10 の stdio MCP サーバーとして構築され、RoselineMCP をアーキテクチャ上のモデルとしています。レイヤー構成は Tools → Services、属性は [McpServerTool] で、dotnet tool と Docker イメージとして提供されます。

ストレージと形式

ADR は ADR ルート（デフォルトは docs/adr/）配下に Markdown ファイルとして保存され、意思決定ごとに NNNN-kebab-title.md という名前のファイルを1つ作成します。MADR 4.0 のフロントマターとセクションを使用します。

---
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 を1件取得します。選択した ## セクションのみを取得することもできます
search_adrs	読み取り	用語ベクトル検索。字句検索（デフォルト）または semantic を使用します
get_adr_index	読み取り	意思決定ログ／タイムライン
find_related_adrs	読み取り	受信／送信リンクと置き換えの連鎖
get_adr_graph	読み取り	関係性の完全なグラフ（ノードと型付きエッジ）
create_adr	書き込み	テンプレート（madr または nygard）から ADR を作成します
update_adr	書き込み	単一の ## セクションを置換／追記します
set_status	書き込み	ステータスを遷移します（ライフサイクルを適用）
supersede_adr	書き込み	置き換えとなる ADR を作成し、古い ADR を置き換え済みにしてリンクします（1回の呼び出しで実行）
link_adrs	書き込み	2件の ADR 間に型付きリンクを作成します（逆リンクも追加）
validate_adr	読み取り	MADR 準拠状況を検証します。セクション、ステータス、リンク切れ、ID の重複を確認します
detect_conflicts	読み取り	明示的な conflicts-with と、内容が非常に類似する採択済み ADR を検出します
find_stale_adrs	読み取り	code_refs の参照先が解決できなくなった ADR を検索します
coverage_report	読み取り	アーキテクチャ領域（タグ）ごとの ADR カバレッジをレポートし、抜けを明らかにします
suggest_adr_from_change	読み取り	unified diff から ADR の提案を下書きします
render_index	書き込み	閲覧可能な意思決定インデックス README.md を再生成します
diff_adr	読み取り	2件の ADR 間、またはファイルと正規レンダリング版との間の差分を表示します

書き込みはデフォルトでプレビューされます。 変更を加える各ツールは previewOnly（デフォルトは true）を受け取り、予定されている変更の unified diff を返します。ディスクに書き込むには 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 サーバーとして登録されると、エージェントはそのツールを直接呼び出します。一般的な読み取り後に書き込むワークフローは次のとおりです。

// "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/ 配下にある3つのプロジェクトスキルが、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 は、RoselineMCP を参考に、GitHub Actions で実行されます。

ワークフロー	トリガー	内容
ci.yml	main/dev への push / PR	ビルド＋テストのマトリックス（ubuntu/windows/macos）。ubuntu で行カバレッジ 80% のゲートを適用
codeql.yml	push / PR / 毎週	CodeQL によるセキュリティ分析（C#）
pages.yml	dev 上の site/** への push	ランディングページを GitHub Pages に公開
release-please.yml	dev への push	リリース 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 のための、実際の埋め込みベースのセマンティック検索（用語ベクトルの類似度を超えるもの）
• find_stale_adrs で C# シンボルを詳細に解決する、Roslyn ベースの ICodeLinkProvider
• MADR/Nygard 以外の ADR テンプレートの追加（例：Y ステートメント）
• 意思決定グラフを閲覧・視覚化するエディター拡張機能（VS Code / JetBrains）
• CI カバレッジゲートを拡大し、追加のパッケージレジストリに公開

詳細の確認や新しいアイデアの提案については、オープンイシューをご覧ください。

Atypical MCP サーバー

Atypical Consulting による Model Context Protocol サーバー群の一部です。

• RoselineMCP — AI エージェント向けの Roslyn コードインテリジェンス
• ASTral — 構造化コード検索（tree-sitter）
• AdrMcp — MCP によるアーキテクチャ決定記録
• MarkdownInk — ターミナル向け Markdown レンダリング

コントリビューション

コントリビューションを歓迎します。大きな変更については、まずイシューを作成して相談してください。

1. リポジトリをフォークし、ブランチを作成します（git checkout -b feat/my-feature）
2. 変更をコミットします（git commit -m 'feat: ...'）
3. ブランチをプッシュし、プルリクエストを作成します

---

Atypical Consulting が開発しました。また、サプライチェーン隔離機能を備えたセルフホスト可能な NuGet サーバー、 NuGetKeep も提供しています。