mcp-adr-analysis-server

MCP（Model Context Protocol）ADR（架构决策记录）分析服务

**你的 ADR 在欺骗你。**这个 MCP 服务会揭穿它们——实时偏移检测会根据实际代码验证架构决策。此外，它还具备内容安全防护、决策记忆功能，并通过 CE-MCP 调用宿主大模型提供 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

网络要求

• 在 npm install 期间需要访问互联网，以编译原生模块（tree-sitter 是用于 YAML 和 TypeScript 的增量代码解析器）
• 如果处于企业代理环境，请设置 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

注意： 从源代码安装时，运行服务前必须执行 npm run build，因为 bin 的入口指向 ./dist/src/index.js。

📖 详细安装指南 → | 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 模式运行 — 由宿主大模型（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 指令？ 调用工具时，它会返回一条结构化的编排指令，告知宿主大模型要分析什么、要收集哪些数据，以及如何格式化结果。宿主大模型（例如 Claude Desktop 中的 Claude，或 Cursor 中的 GPT）会利用自身已有的上下文窗口执行该指令。这意味着无需额外的 API 费用，且结果更佳，因为大模型已拥有你的对话上下文。

🚀 使用示例

只需用自然语言向 MCP 客户端提出请求——无需编写代码：

“分析这个 React 项目的架构，并为任何隐含的决策提出 ADR 建议”

“根据 PRD.md 文件生成 ADR，并创建包含实现任务的 todo.md”

“检查此代码库中的安全问题，并提供脱敏建议”

服务会返回结构化分析和编排指令，由宿主大模型结合上下文执行。

// 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 参考 →

试试看： 此仓库包含一个 sample-project/ 目录，其中有示例 ADR 和源代码。将 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 - 以置信度评分解答架构问题
🤖 自主 Agent - 持续分析并强制执行规则
🏢 企业团队 - 组合分析与迁移规划

📖 详细使用场景 →

🛠️ 技术栈

运行时： Node.js 20+ • 语言： TypeScript • 框架： MCP SDK • 测试： Vitest（语句覆盖率约为 49%，设有强制最低标准） 搜索： ripgrep（快速递归文本搜索）+ fast-glob（文件匹配）• AI 集成： CE-MCP 编排指令（宿主大模型）• 代码分析： 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 严格模式 • 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 模式下的预期行为——由宿主大模型执行这些指令。若要在服务端执行，请设置 EXECUTION_MODE=full + OPENROUTER_API_KEY
• 找不到模块：运行 npm install && npm run build
• 权限被拒绝：检查文件权限和项目路径

📖 完整故障排除指南 →

🔒 安全与性能

安全： 自动检测密钥 • 内容脱敏 • 本地处理 • 零信任
性能： 多级缓存 • 增量分析 • 并行处理 • 内存优化

📖 安全指南 → | 性能 →

🔐 安全漏洞报告

发现安全问题？请阅读我们的 安全政策，了解负责任的披露流程。请勿公开提交安全漏洞问题。

🤝 参与贡献

欢迎贡献！无论是修复错误、添加功能，还是改进文档，我们都感谢您的帮助。

🌟 贡献者快速入门

1. Fork 此仓库
2. 克隆 您的 fork：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. 提交 Pull Request

🗺️ 路线图

工作进展通过 GitHub 里程碑进行跟踪，问题被纳入里程碑即表示已获准。

架构方向见 docs/adrs/；发布节奏见 RELEASES.md。

👶 首次参与贡献？

想找一个适合入门的问题？请查看我们的 适合新手的问题——这些任务对新手友好，非常适合开始参与！

刚接触开源？ 我们的贡献指南将逐步带您了解完整流程。

📝 报告问题

报告错误或申请功能时，请使用我们的问题模板。模板有助于我们更快地理解和解决问题。

标准： TypeScript 严格模式 • 强制覆盖率下限 • ESLint • 安全验证 • MCP 合规性

📖 完整贡献指南 → | 行为准则 →

🔗 资源

官方： MCP 规范 • MCP SDK
社区： MCP Registry • Discord
项目： ADR • 进度 • 发布指南

📄 许可证

MIT 许可证——详情请参阅 LICENSE 文件。

🙏 致谢

• 感谢 Anthropic 创建 Model Context Protocol
• 感谢 MCP 社区 提供灵感和最佳实践
• 感谢帮助改进本项目的 贡献者

由 Tosin Akinosho 倾心打造，助力 AI 驱动的架构分析

通过 CE-MCP 编排指令，为 AI 助手提供漂移检测、内容安全和决策记忆能力。