Adr Analysis Server

MCP（模型上下文协议）ADR（体系结构决策记录）分析服务器

](https://github.com/tosin2013/mcp-adr-analysis-server)  ](https://www.npmjs.com/package/mcp-adr-analysis-server) ](https://nodejs.org/)  

基于人工智能的架构分析，用于智能开发工作流程。 返回实际分析结果，而不是提示提交到其他地方。

什么是MCP？

这 模型上下文协议（MCP） 是一个开放标准，可实现人工智能助手与外部工具和数据源之间的无缝集成。将其视为一个通用适配器，让Claude、Cline和Cursor等AI助手连接到专门的分析服务器。该服务器增强了AI助手的深度架构分析能力，实现了智能代码生成、决策跟踪和开发工作流自动化。

太长，读不下去了

什么： 提供人工智能架构决策分析和ADR管理的MCP服务器\ 谁： AI编码助理（Claude、Cline、Cursor）、企业架构师、开发团队\ 为什么？ 立即获得架构见解，而不是提示，置信度得分为95%\ 怎样： npm install -g mcp-adr-analysis-server → 使用OpenRouter API进行配置→ 开始分析

主要特点： 树型AST分析•安全内容屏蔽•测试驱动开发•部署就绪性验证

Key Terms

______________________________________________________________________

作者: Tosin Akinosho | 仓库:

✨ 核心能力

🤖 AI驱动的分析 -通过OpenRouter.ai集成立即获得架构见解 🏗️ 技术检测 -识别任何技术栈和架构模式 📋 ADR管理 -生成、建议和维护架构决策记录 🔗 智能代码链接 -人工智能驱动的ADR和决策相关代码文件的发现 🛡️ 安全与合规 -自动检测并屏蔽敏感内容 🧪 TDD集成 -两阶段测试驱动开发和验证 🚀 部署准备情况 -硬阻断的零容忍测试验证

📖 查看全部功能→ · 📜 发布策略→ · 🗒️ 更新日志→

先决条件

安装前，请确认您已：

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

必修的：

• npm 9.0.0或更高版本 （包含在Node.js 20+中）

网络要求

• 需要互联网接入 在...期间 npm install 用于本机模块编译(树保姆 用于YAML和TypeScript的增量代码解析器）
• 如果在公司代理之后，请设置 HTTP_PROXY 和 HTTPS_PROXY 环境变量
• 离线回退：如果本机构建失败，服务器将在简化模式下运行，而不进行树保姆代码分析

📦 快速安装

# 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设置→

⚡ 快速设置（3步）

1. 获取API密钥：注册地址： OpenRouter.ai/keys -OpenRouter是一个API网关，通过单个密钥提供对多个人工智能模型（Claude、GPT等）的访问。 _没有API密钥？服务器仍在仅提示模式下工作——请参阅 执行模式 在......下面_
2. 设置环境: OPENROUTER_API_KEY=your_key + EXECUTION_MODE=full
3. 配置客户端：添加到Claude Desktop、Cline、Cursor或Windsurf

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

克劳德桌面用户： 将此JSON保存到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）。

Config locations for other clients

With ADR Aggregator (Optional)

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

获取API密钥： adraggregator.com

📖 完整配置指南→ | 客户端设置→

执行模式

提示： 从即时模式开始探索工具目录-您可以在没有API键的情况下分析项目、发现ADR和生成模板。当您准备好进行AI分析并进行置信度评分时，添加API密钥。

🚀 使用示例

只需用自然语言询问您的MCP客户端——不需要代码：

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

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

“检查此代码库是否存在安全问题，并提供屏蔽建议”

服务器返回实际分析结果 而不是提示提交到其他地方！

Programmatic Usage (Advanced)

如果您通过MCP SDK将服务器集成到自己的工具中：

// 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',
  {
    useAI: true, // AI-powered keyword extraction
    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 -用信心评分回答架构问题\ 🤖 自治代理 -持续分析和规则执行\ 🏢 企业团队 -投资组合分析和迁移规划

📖 详细用例→

🛠️ 技术栈

运行时间： Node.js 20+ 语言： TypeScript• 框架： MCP-SDK• 测试： Jest（覆盖率>80%）

📖 技术细节→

📁 项目结构

src/tools/     # 73 MCP tools for analysis
docs/adrs/     # Architectural Decision Records
tests/         # >80% test coverage
.github/       # CI/CD automation

📖 结构→

🧪 测试

npm test              # Run all tests (>80% coverage)
npm run test:coverage # Coverage report

📖 测试指导→

🔥 Firecrawl集成（可选——跳过入门）

增强网络研究能力，进行全面的架构分析。

注： 您不需要Firecrawl进行基本的ADR分析。服务器完全可以在没有它的情况下工作。只有当你需要像 perform_research 工具与外部资源。

When is Firecrawl useful?

• ADR研究 --生成ADR时自动从官方文档中提取最佳实践
• 技术评估 --通过抓取框架的文档和变更日志来比较框架
• 安全审计 --检查CVE数据库和安全公告，了解您的依赖关系
• 迁移规划 --从上游项目中收集迁移指南和变更通知

# Option 1: Cloud service (recommended)
export FIRECRAWL_ENABLED="true"
export FIRECRAWL_API_KEY="fc-your-api-key-here"

# Option 2: Self-hosted
export FIRECRAWL_ENABLED="true"
export FIRECRAWL_BASE_URL="http://localhost:3000"

# Option 3: Disabled (default - server works without web search)

📖 Firecrawl设置指南→

🌐 ADR聚合器集成（可选）

ADR聚合器 是一个跨团队ADR可见性和治理的平台。它提供：

• 跨存储库知识图 --了解架构决策在项目之间的关系
• 治理仪表板 --跟踪ADR合规性、陈旧性和审查周期
• 模板库 -访问特定于域的ADR模板（安全、API、数据库等）
• 团队协作 --在整个组织内共享架构决策

注： ADR聚合器是可选的。没有它，所有核心分析功能都可以工作。

# 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聚合器指南→ | 📖 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•>80%的测试覆盖率•预提交挂钩

在本地查看文档

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系统：使用特殊的安装程序脚本
• 工具返回提示：设置 EXECUTION_MODE=full +API密钥
• 未找到模块：运行 npm install && npm run build
• 权限不足：检查文件权限和项目路径

📖 完整的故障排除指南→

🔒 安全与性能

安全： 自动秘密检测•内容屏蔽•本地处理•零信任\ 演出 多级缓存•增量分析•并行处理•内存优化

📖 安全指南→ | 演出→

🔐 安全漏洞报告

发现安全问题？请阅读我们的 安全策略 负责披露程序。 不要 为安全漏洞制造公共问题。

🤝 贡献

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

🌟 贡献者快速入门

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 （保持>80%的覆盖率）
6. 提交 拉取请求

👶 首次捐款？

寻找一个好的第一期？查看我们的 好的第一个问题 -这些是适合初学者的任务，非常适合初学者！

开源新手？ 我们的 贡献指南 逐步引导您完成整个过程。

📝 报告问题

使用我们的 问题模板 在报告错误或请求功能时。模板帮助我们更快地理解和解决问题。

标准： TypeScript严格•覆盖率>80%•ESLint•安全验证•MCP合规性

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

🔗 资源

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 人类 用于创建模型上下文协议
• MCP社区 寻求灵感和最佳实践
• 贡献者 谁帮助这个项目变得更好

______________________________________________________________________

内置于❤️ 通过 Tosin Akinosho 用于人工智能驱动的架构分析

_赋予人工智能助手深厚的架构智能和决策能力。_