mcp-adr-analysis-server

MCP（Model Context Protocol）ADR（Architectural Decision Record）分析サーバー

ADRは真実を語っていません。 このMCPサーバーがそれを検出します。ライブドリフト検出により、アーキテクチャ上の決定を実際のコードと照合して検証できます。さらに、コンテンツの安全性、決定の記憶機能、CE-MCPを通じてホストのLLMを活用する63個のツールを備えています。

目次

• MCPとは？
• 前提条件
• クイックインストール
• クイックセットアップ
• 使用例
• ユースケース
• 技術スタック
• プロジェクト構成
• テスト
• ADR Aggregatorとの連携
• 開発
• トラブルシューティング
• セキュリティとパフォーマンス
• コントリビューション
• リソース
• ライセンス

MCPとは？

**Model Context Protocol（MCP）**は、AIアシスタントと外部のツールやデータソースをシームレスに連携させるオープンスタンダードです。Claude、Cline、CursorなどのAIアシスタントが、専門のサーバーに接続するためのユニバーサルアダプターと考えることができます。このサーバーを使うと、AIアシスタントは実際のコードに照らしてADRのドリフトを検出し、機密コンテンツが漏洩する前にマスキングし、会話をまたいでアーキテクチャ上の決定を記憶できるようになります。

要約

概要： 実際のコードを基にアーキテクチャ上の決定を検証する MCP サーバー — ドリフト検出、コンテンツの安全性、決定の記憶
対象： AI コーディングアシスタント（Claude、Cline、Cursor、Windsurf）、エンタープライズアーキテクト、開発チーム
理由： 古くなった ADR が本番環境のインシデントを引き起こす前に検出します — コードの証拠に基づいてリアルタイムで検証し、API キーは不要です
方法： npm install -g mcp-adr-analysis-server → MCP クライアントに追加 → 分析を開始

主な機能： Tree-sitter AST 分析 • セキュリティコンテンツのマスキング • ドリフト検出 • CE-MCP オーケストレーション指示 • デプロイ準備状況の検証

作成者：Tosin Akinosho | リポジトリ：GitHub | バージョン：2.14.12

✨ 主な機能

🔄 ドリフト検出 - ADR の決定を、実際のコードやインフラの証拠に基づいて検証します
🛡️ コンテンツの安全性 - シークレット、個人識別情報（PII）、機密コンテンツを自動的に検出してマスキングします
🧠 決定の記憶 - セッションとツールの使用状況を追跡し、キーワードスコア付きの検索を行います
🏗️ テクノロジー検出 - あらゆる技術スタックとアーキテクチャパターンを特定します
📋 ADR 管理 - アーキテクチャ決定記録を生成、提案、管理します
🔗 スマートコードリンク - ADR や決定に関連するコードファイルを検出します
🚀 デプロイ準備状況 - 厳格なブロッキングを伴う、許容度ゼロのテスト検証を行います

📖 機能の詳細を見る → · 📜 リリースポリシー → · 🗒️ 変更履歴 →

前提条件

インストールする前に、以下を確認してください。

node --version  # Should show v20.0.0 or higher
npm --version   # Should show 9.0.0 or higher (included with Node.js 20+)

必須：

• Node.js 20.0.0 以降 — ダウンロードするか、nvm/fnmを使用してください
• npm 9.0.0 以降（Node.js 20 以降に含まれています）
• MCP 対応クライアント — Claude Desktop、Cline、Cursor、またはWindsurf

ネットワーク要件

• YAML と TypeScript 用のインクリメンタルコードパーサーであるネイティブモジュールをコンパイルするため、npm install中はインターネット接続が必要です（tree-sitter）
• 企業プロキシの背後にいる場合は、HTTP_PROXYとHTTPS_PROXY環境変数を設定してください
• オフライン時の代替動作：ネイティブビルドに失敗した場合、サーバーはtree-sitterによるコード分析なしの縮退モードで動作します

📦 クイックインストール

# Option 1: Global installation (recommended for frequent use)
npm install -g mcp-adr-analysis-server

# Option 2: Use npx (no installation required)
npx mcp-adr-analysis-server

# Option 3: From source (for development or customization)
git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
cd mcp-adr-analysis-server && npm install && npm run build

# Option 4: RHEL 9/10 systems (special installer)
curl -sSL https://raw.githubusercontent.com/tosin2013/mcp-adr-analysis-server/main/scripts/install-rhel.sh | bash

注記： ソースからインストールする場合、binのエントリーポイントが./dist/src/index.jsを参照しているため、サーバーを実行する前にnpm run buildが必要です。

📖 詳細なインストールガイド → | RHEL のセットアップ →

⚡ クイックセットアップ（2 ステップ）

1. インストール：npm install -g mcp-adr-analysis-server
2. クライアントを設定：Claude Desktop、Cline、Cursor、またはWindsurfに追加します — APIキーは不要です

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/project"
      }
    }
  }
}

以上で完了です。サーバーはデフォルトでCE-MCP モードで動作します — ツールが返すオーケストレーション指示を使って、ホストのLLM（Claude、GPTなど）が分析を実行します。外部APIキーは必要ありません。

Claude Desktop ユーザーの方へ： このJSONを~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または%APPDATA%\Claude\claude_desktop_config.json（Windows）に保存してください。

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full"
      }
    }
  }
}

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "ADR_AGGREGATOR_API_KEY": "agg_your_key_here"
      }
    }
  }
}

📖 設定ガイド全文 → | クライアントのセットアップ →

実行モード

CE-MCP 指示とは何ですか？ ツールを呼び出すと、分析対象、収集するデータ、結果のフォーマット方法をホスト LLM に伝える、構造化されたオーケストレーション指示が返されます。ホスト LLM（Claude Desktop の Claude や Cursor の GPT など）が、既存のコンテキストウィンドウを使って指示を実行します。これにより、追加の API コストがゼロになり、LLM が会話のコンテキストをすでに把握しているため、より良い結果が得られます。

🚀 使用例

自然な言葉で MCP クライアントに依頼するだけです。コードは必要ありません。

「この React プロジェクトのアーキテクチャを分析し、暗黙的な決定があれば ADR を提案してください」

「PRD.md ファイルから ADR を生成し、実装タスクをまとめた todo.md を作成してください」

「このコードベースにセキュリティ上の問題がないか確認し、マスキングに関する推奨事項を提示してください」

サーバーは、ホスト LLM がコンテキスト内で実行する構造化された分析結果とオーケストレーション指示を返します。

// Basic project analysis
const analysis = await analyzeProjectEcosystem({
  projectPath: '/path/to/project',
  analysisType: 'comprehensive',
});

// Generate ADRs from requirements
const adrs = await generateAdrsFromPrd({
  prdPath: 'docs/PRD.md',
  outputDirectory: 'docs/adrs',
});

// Smart Code Linking - Find code related to ADR decisions
const relatedCode = await findRelatedCode(
  'docs/adrs/001-auth-system.md',
  'We will implement JWT authentication with Express middleware',
  '/path/to/project',
  {
    useRipgrep: true, // Fast text search
    maxFiles: 10, // Limit results
    includeContent: true, // Include file contents
  }
);

📖 使用ガイド全文 → | API リファレンス →

お試しください： このリポジトリには、ADR とソースコードの例を含む sample-project/ ディレクトリがあります。PROJECT_PATH をこのディレクトリに設定すれば、自分のコードベースに影響を与えずに試せます。

注： サンプルプロジェクトは、ソースからクローンした場合（上記のオプション 3）にのみ利用できます。npm からインストールした場合（オプション 1 または 2）は、サンプルを利用するために独自のテストプロジェクトを作成するか、リポジトリを別途クローンしてください：git clone --depth 1 https://github.com/tosin2013/mcp-adr-analysis-server.git sample-test

🎯 ユースケース

👨‍💻 AI コーディングアシスタント - Claude、Cline、Cursor にアーキテクチャの知見を追加
💬 会話型 AI - 信頼度スコア付きでアーキテクチャに関する質問に回答
🤖 自律型エージェント - 継続的な分析とルールの適用
🏢 エンタープライズチーム - ポートフォリオ分析と移行計画

📖 ユースケースの詳細 →

🛠️ 技術スタック

ランタイム： Node.js 20+ • 言語： TypeScript • フレームワーク： MCP SDK • テスト： Vitest（ステートメントカバレッジ約49％、下限を適用） 検索： ripgrep（高速な再帰テキスト検索）＋ fast-glob（ファイル照合） • AI 統合： CE-MCP オーケストレーションディレクティブ（ホスト LLM） • コード解析： tree-sitter（インクリメンタルコードパーサー）＋スマートコードリンク

📖 技術詳細 → | CE-MCP 移行プレイブック →

📁 プロジェクト構成

src/tools/     # 64 MCP tools with annotated metadata
docs/adrs/     # Architectural Decision Records
tests/         # ~49% statement coverage, floor enforced in CI
.github/       # CI/CD automation

📖 構成の全容 →

🧪 テスト

npm test              # Run all tests
npm run test:coverage # Coverage report

📖 テストガイド →

🌐 ADR Aggregator との統合（任意）

ADR Aggregator は、チーム横断で ADR の可視化とガバナンスを実現するプラットフォームです。以下の機能を提供します。

• リポジトリ横断のナレッジグラフ — プロジェクト間でアーキテクチャ上の決定がどのように関連しているかを確認できます
• ガバナンスダッシュボード — ADR の準拠状況、陳腐化、レビューサイクルを追跡できます
• テンプレートライブラリ — ドメイン固有の ADR テンプレート（セキュリティ、API、データベースなど）を利用できます
• チームコラボレーション — 組織全体でアーキテクチャ上の決定を共有できます

注： ADR Aggregator は任意です。中核となる分析機能は、これがなくてもすべて利用できます。

# Set your API key (get one at adraggregator.com)
export ADR_AGGREGATOR_API_KEY="agg_your_key_here"

利用可能なツール

新規リポジトリ向けワークフロー

# 1. Analyze codebase for implicit architectural decisions
suggest_adrs(analysisType: 'implicit_decisions')

# 2. Generate ADR files from suggestions
generate_adr_from_decision(decisionData)

# 3. Save ADRs to docs/adrs/

# 4. (Optional) Sync to adraggregator.com
sync_to_aggregator(full_sync: true)

メリット： チーム横断の可視性 • 陳腐化アラート • 準拠状況の追跡 • 組織全体のナレッジグラフ

📖 ADR Aggregator ガイド → | 📖 MCP 統合ガイド →

🔧 開発

git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
cd mcp-adr-analysis-server
npm install && npm run build && npm test

品質基準： TypeScript の strict モード • ESLint • カバレッジの下限を適用 • コミット前フック

ドキュメントをローカルで表示する

API ドキュメントは TypeDoc で生成されます。

npm install          # Required once after cloning (installs typedoc)
npm run docs:build   # Generate API docs into docs/api/
npm run docs:serve   # Serve locally via Python HTTP server

その後、ブラウザーで http://localhost:8080 を開いてください。Markdown ドキュメントは docs/ にあり、GitHub で直接閲覧できます。

📖 開発ガイド → | 📖 コントリビューション →

🔧 トラブルシューティング

よくある問題：

• RHEL システム： 専用のインストーラースクリプトを使用してください
• ツールが結果ではなくディレクティブを返す： CE-MCP モードでは想定される動作です。ホスト LLM がディレクティブを実行します。サーバー側で実行するには、EXECUTION_MODE=full と OPENROUTER_API_KEY を設定してください
• モジュールが見つからない： npm install && npm run build を実行してください
• アクセスが拒否された： ファイル権限とプロジェクトパスを確認してください

📖 トラブルシューティング完全ガイド →

🔒 セキュリティとパフォーマンス

セキュリティ： シークレットの自動検出 • コンテンツのマスキング • ローカル処理 • ゼロトラスト
パフォーマンス： マルチレベルキャッシュ • インクリメンタル分析 • 並列処理 • メモリ最適化

📖 セキュリティガイド → | パフォーマンス →

🔐 セキュリティ脆弱性の報告

セキュリティ上の問題を見つけましたか？責任ある情報開示の手順について、セキュリティポリシーをお読みください。セキュリティ脆弱性について、公開の Issue を作成しないでください。

🤝 コントリビュート

コントリビュートを歓迎します！バグの修正、機能の追加、ドキュメントの改善など、皆さんのご協力に感謝します。

🌟 コントリビューター向けクイックスタート

1. リポジトリをフォークします
2. フォークをクローンします：git clone https://github.com/YOUR_USERNAME/mcp-adr-analysis-server.git
3. ブランチを作成します：git checkout -b feature/your-feature-name
4. テストを追加して変更を加えます
5. テストします：npm test（カバレッジの下限を下回らないようにしてください）
6. プルリクエストを送信します

🗺️ ロードマップ

作業はGitHub のマイルストーンで追跡しており、マイルストーンへの追加によって Issue が採用済みとしてマークされます。

アーキテクチャの方針はdocs/adrs/に、リリースの頻度は RELEASES.mdに記載されています。

👶 初めてコントリビュートしますか？

最初の Issue をお探しですか？good first issuesをご覧ください。初心者に取り組みやすく、始めるのに最適なタスクです！

オープンソースは初めてですか？コントリビューションガイドでは、手順を一つずつ詳しく説明しています。

📝 Issue の報告

バグの報告や機能のリクエストには、Issue テンプレートを使用してください。テンプレートを使うと、問題をより迅速に把握して解決できます。

基準： TypeScript strict • 適用されるカバレッジ下限 • ESLint • セキュリティ検証 • MCP 準拠

📖 コントリビューションガイド全文 → | 行動規範 →

🔗 リソース

公式： MCP 仕様 • MCP SDK
コミュニティ： MCP Registry • Discord
プロジェクト： ADR • 進捗状況 • 公開ガイド

📄 ライセンス

MIT ライセンスの詳細については、LICENSEファイルをご覧ください。

🙏 謝辞

• Model Context Protocol を作成した Anthropic
• アイデアとベストプラクティスを提供してくれた MCP コミュニティ
• このプロジェクトの改善に協力してくださる コントリビューターの皆さん

AI によるアーキテクチャ分析のため、Tosin Akinosho が ❤️ を込めて開発

CE-MCP オーケストレーションディレクティブを通じて、ドリフト検出、コンテンツの安全性、意思決定の記憶機能を備えた AI アシスタントを実現します。