The Model Context Protocol (MCP) is an open standard that enables seamless integration between AI assistants and external tools and data sources. Think of it as a universal adapter that lets AI assistants like Claude, Cline, and Cursor connect to specialized analysis servers. This server enhances AI assistants with deep architectural analysis capabilities, enabling intelligent code generation, dec
Add this skill
npx mdskills install tosin2013/mcp-adr-analysis-serverComprehensive MCP server with 73 ADR analysis tools, tree-sitter parsing, and AI-powered insights
1# MCP (Model Context Protocol) ADR (Architectural Decision Record) Analysis Server23[](https://github.com/tosin2013/mcp-adr-analysis-server)4[](LICENSE)5[](https://www.npmjs.com/package/mcp-adr-analysis-server)6[](https://nodejs.org/)7[](https://www.typescriptlang.org/)8[](https://github.com/tosin2013/mcp-adr-analysis-server/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)910> **AI-powered architectural analysis for intelligent development workflows.** Returns actual analysis results, not prompts to submit elsewhere.1112## What is MCP?1314The **Model Context Protocol (MCP)** is an open standard that enables seamless integration between AI assistants and external tools and data sources. Think of it as a universal adapter that lets AI assistants like Claude, Cline, and Cursor connect to specialized analysis servers. This server enhances AI assistants with deep architectural analysis capabilities, enabling intelligent code generation, decision tracking, and development workflow automation.1516## TL;DR1718**What:** MCP server that provides AI-powered architectural decision analysis and ADR management19**Who:** AI coding assistants (Claude, Cline, Cursor), enterprise architects, development teams20**Why:** Get immediate architectural insights instead of prompts, with 95% confidence scoring21**How:** `npm install -g mcp-adr-analysis-server` → Configure with OpenRouter API → Start analyzing2223**Key Features:** Tree-sitter AST analysis • Security content masking • Test-driven development • Deployment readiness validation2425<details>26<summary><b>Key Terms</b></summary>2728| Term | Definition |29| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |30| **ADR** | **Architectural Decision Record** — A document that captures an important architectural decision along with its context, alternatives considered, and consequences. |31| **MCP** | **Model Context Protocol** — An open standard enabling AI assistants to connect to external tools and data sources. |32| **Tree-sitter** | An incremental parsing library that provides AST (Abstract Syntax Tree) analysis for 50+ languages. Used for semantic code understanding, extracting function signatures, and identifying architectural patterns. |33| **Knowledge Graph** | A graph database maintained by the server that tracks relationships between ADRs, code implementations, and architectural decisions. Enables intelligent code linking and impact analysis. |34| **Smart Code Linking** | AI-powered discovery of code files related to ADRs and architectural decisions, using keyword extraction and semantic search. |3536</details>3738---3940**Author**: [Tosin Akinosho](https://github.com/tosin2013) | **Repository**: [GitHub](https://github.com/tosin2013/mcp-adr-analysis-server.git)4142## ✨ Core Capabilities4344🤖 **AI-Powered Analysis** - Immediate architectural insights with OpenRouter.ai integration45🏗️ **Technology Detection** - Identify any tech stack and architectural patterns46📋 **ADR Management** - Generate, suggest, and maintain Architectural Decision Records47🔗 **Smart Code Linking** - AI-powered discovery of code files related to ADRs and decisions48🛡️ **Security & Compliance** - Detect and mask sensitive content automatically49🧪 **TDD Integration** - Two-phase Test-Driven Development with validation50🚀 **Deployment Readiness** - Zero-tolerance test validation with hard blocking5152📖 **[View Full Capabilities →](docs/explanation/)**5354## Prerequisites5556Before installing, verify you have:5758```bash59node --version # Should show v20.0.0 or higher60npm --version # Should show 9.0.0 or higher (included with Node.js 20+)61```6263**Required:**6465- **Node.js 20.0.0 or higher** — [Download](https://nodejs.org/) or use [nvm](https://github.com/nvm-sh/nvm)/[fnm](https://github.com/Schniz/fnm)66- **npm 9.0.0 or higher** (included with Node.js 20+)67- **An MCP-compatible client** — [Claude Desktop](https://claude.ai/download), [Cline](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev), [Cursor](https://cursor.sh/), or [Windsurf](https://codeium.com/windsurf)6869### Network Requirements7071- **Internet access required** during `npm install` for native module compilation (tree-sitter-yaml, tree-sitter-typescript)72- If behind a corporate proxy, set `HTTP_PROXY` and `HTTPS_PROXY` environment variables73- **Offline fallback**: If native builds fail, the server operates in reduced mode without tree-sitter code analysis7475## 📦 Quick Installation7677```bash78# Option 1: Global installation (recommended for frequent use)79npm install -g mcp-adr-analysis-server8081# Option 2: Use npx (no installation required)82npx mcp-adr-analysis-server8384# Option 3: From source (for development or customization)85git clone https://github.com/tosin2013/mcp-adr-analysis-server.git86cd mcp-adr-analysis-server && npm install && npm run build8788# Option 4: RHEL 9/10 systems (special installer)89curl -sSL https://raw.githubusercontent.com/tosin2013/mcp-adr-analysis-server/main/scripts/install-rhel.sh | bash90```9192> **Note:** When installing from source, `npm run build` is required before running the server since the `bin` entry points to `./dist/src/index.js`.9394📖 **[Detailed Installation Guide →](docs/tutorials/01-first-steps.md)** | **[RHEL Setup →](scripts/install-rhel.sh)**9596## ⚡ Quick Setup (3 Steps)97981. **Get API Key**: Sign up at [OpenRouter.ai/keys](https://openrouter.ai/keys) — OpenRouter is an API gateway that provides access to multiple AI models (Claude, GPT, etc.) through a single key. _No API key? The server still works in prompt-only mode — see [Execution Modes](#execution-modes) below._992. **Set Environment**: `OPENROUTER_API_KEY=your_key` + `EXECUTION_MODE=full`1003. **Configure Client**: Add to Claude Desktop, Cline, Cursor, or Windsurf101102```json103{104 "mcpServers": {105 "adr-analysis": {106 "command": "mcp-adr-analysis-server",107 "env": {108 "PROJECT_PATH": "/path/to/your/project",109 "OPENROUTER_API_KEY": "your_key_here",110 "EXECUTION_MODE": "full"111 }112 }113 }114}115```116117> **Claude Desktop users:** Save this JSON to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).118119<details>120<summary><b>Config locations for other clients</b></summary>121122| Client | Config file location |123| ---------------------------- | ----------------------------------------------------------------------------- |124| **Claude Desktop (macOS)** | `~/Library/Application Support/Claude/claude_desktop_config.json` |125| **Claude Desktop (Windows)** | `%APPDATA%\Claude\claude_desktop_config.json` |126| **Cline (VS Code)** | VS Code Settings → Cline → MCP Servers (or `.vscode/cline_mcp_settings.json`) |127| **Cursor** | Cursor Settings → MCP → Add Server |128129</details>130131<details>132<summary><b>With ADR Aggregator (Optional)</b></summary>133134```json135{136 "mcpServers": {137 "adr-analysis": {138 "command": "mcp-adr-analysis-server",139 "env": {140 "PROJECT_PATH": "/path/to/your/project",141 "OPENROUTER_API_KEY": "your_key_here",142 "EXECUTION_MODE": "full",143 "ADR_AGGREGATOR_API_KEY": "agg_your_key_here"144 }145 }146 }147}148```149150Get your API key at [adraggregator.com](https://adraggregator.com)151152</details>153154📖 **[Full Configuration Guide →](docs/reference/mcp-client-config.md)** | **[Client Setup →](docs/reference/environment-config.md)**155156### Execution Modes157158| | **Full Mode** | **Prompt-Only Mode** |159| ------------------------ | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- |160| **Requires API key?** | Yes (`OPENROUTER_API_KEY`) | No |161| **Returns** | Actual analysis results with confidence scores | Prompts you can paste into any AI chat |162| **Set via** | `EXECUTION_MODE=full` | `EXECUTION_MODE=prompt-only` (default) |163| **Best for** | Production use, automation | Trying it out, no-cost exploration |164| **Available Features** | All 73 tools, AI analysis, confidence scoring, Smart Code Linking, Knowledge Graph | Analysis prompts, templates, local file operations, ADR discovery |165| **Unavailable Features** | — | AI execution, confidence scores, Smart Code Linking, web research |166167**Tip:** Start with prompt-only mode to explore the tool catalog — you can analyze projects, discover ADRs, and generate templates without an API key. Add an API key when you're ready for AI-powered analysis with confidence scoring.168169## 🚀 Usage Examples170171Just ask your MCP client in natural language — no code required:172173> "Analyze this React project's architecture and suggest ADRs for any implicit decisions"174175> "Generate ADRs from the PRD.md file and create a todo.md with implementation tasks"176177> "Check this codebase for security issues and provide masking recommendations"178179**The server returns actual analysis results** instead of prompts to submit elsewhere!180181<details>182<summary><b>Programmatic Usage (Advanced)</b></summary>183184If you're integrating the server into your own tooling via the MCP SDK:185186```typescript187// Basic project analysis188const analysis = await analyzeProjectEcosystem({189 projectPath: '/path/to/project',190 analysisType: 'comprehensive',191});192193// Generate ADRs from requirements194const adrs = await generateAdrsFromPrd({195 prdPath: 'docs/PRD.md',196 outputDirectory: 'docs/adrs',197});198199// Smart Code Linking - Find code related to ADR decisions200const relatedCode = await findRelatedCode(201 'docs/adrs/001-auth-system.md',202 'We will implement JWT authentication with Express middleware',203 '/path/to/project',204 {205 useAI: true, // AI-powered keyword extraction206 useRipgrep: true, // Fast text search207 maxFiles: 10, // Limit results208 includeContent: true, // Include file contents209 }210);211```212213</details>214215📖 **[Complete Usage Guide →](docs/tutorials/)** | **[API Reference →](docs/reference/)**216217> **Try it out:** This repo includes a [`sample-project/`](sample-project/) directory with example ADRs and source code. Point `PROJECT_PATH` at it to experiment without affecting your own codebase.218>219> **Note:** The sample project is only available when **cloning from source** (Option 3 above). If you installed via npm (Option 1 or 2), create your own test project or clone the repo separately to access the sample: `git clone --depth 1 https://github.com/tosin2013/mcp-adr-analysis-server.git sample-test`220221## 🎯 Use Cases222223👨💻 **AI Coding Assistants** - Enhance Claude, Cline, Cursor with architectural intelligence224💬 **Conversational AI** - Answer architecture questions with confidence scoring225🤖 **Autonomous Agents** - Continuous analysis and rule enforcement226🏢 **Enterprise Teams** - Portfolio analysis and migration planning227228📖 **[Detailed Use Cases →](docs/explanation/mcp-concepts.md)**229230## 🛠️ Technology Stack231232**Runtime:** Node.js 20+ • **Language:** TypeScript • **Framework:** MCP SDK • **Testing:** Jest (>80% coverage)233**Search:** ripgrep (fast text search) + fast-glob (file matching) • **AI Integration:** OpenRouter.ai • **Web Research:** Firecrawl • **Code Analysis:** tree-sitter (code parser) + Smart Code Linking234235📖 **[Technical Details →](docs/explanation/server-architecture.md)**236237## 📁 Project Structure238239```240src/tools/ # 73 MCP tools for analysis241docs/adrs/ # Architectural Decision Records242tests/ # >80% test coverage243.github/ # CI/CD automation244```245246📖 **[Full Structure →](docs/tutorials/)**247248## 🧪 Testing249250```bash251npm test # Run all tests (>80% coverage)252npm run test:coverage # Coverage report253```254255📖 **[Testing Guide →](docs/how-to-guides/troubleshooting.md)**256257## 🔥 Firecrawl Integration (Optional — Skip for Getting Started)258259**Enhanced web research capabilities for comprehensive architectural analysis.**260261> **Note:** You don't need Firecrawl for basic ADR analysis. The server works fully without it. Only configure Firecrawl if you need web research features like the `perform_research` tool with external sources.262263<details>264<summary><b>When is Firecrawl useful?</b></summary>265266- **ADR research** — automatically pull best practices from official docs when generating ADRs267- **Technology evaluation** — compare frameworks by crawling their documentation and changelogs268- **Security audits** — check CVE databases and security advisories for your dependencies269- **Migration planning** — gather migration guides and breaking-change notes from upstream projects270271</details>272273```bash274# Option 1: Cloud service (recommended)275export FIRECRAWL_ENABLED="true"276export FIRECRAWL_API_KEY="fc-your-api-key-here"277278# Option 2: Self-hosted279export FIRECRAWL_ENABLED="true"280export FIRECRAWL_BASE_URL="http://localhost:3000"281282# Option 3: Disabled (default - server works without web search)283```284285📖 **[Firecrawl Setup Guide →](docs/reference/environment-config.md#firecrawl-configuration)**286287## 🌐 ADR Aggregator Integration (Optional)288289[ADR Aggregator](https://adraggregator.com) is a platform for cross-team ADR visibility and governance. It provides:290291- **Cross-repository knowledge graphs** — See how architectural decisions relate across projects292- **Governance dashboards** — Track ADR compliance, staleness, and review cycles293- **Template library** — Access domain-specific ADR templates (security, API, database, etc.)294- **Team collaboration** — Share architectural decisions organization-wide295296> **Note:** ADR Aggregator is optional. All core analysis features work without it.297298```bash299# Set your API key (get one at adraggregator.com)300export ADR_AGGREGATOR_API_KEY="agg_your_key_here"301```302303### Available Tools304305| Tool | Description | Free | Pro+ | Team |306| ------------------------- | ---------------------------------- | ---- | ---- | ---- |307| `sync_to_aggregator` | Push local ADRs to platform | ✅ | ✅ | ✅ |308| `get_adr_context` | Pull ADR context from platform | ✅ | ✅ | ✅ |309| `get_staleness_report` | Get ADR governance/health reports | ✅ | ✅ | ✅ |310| `get_adr_templates` | Retrieve domain-specific templates | ✅ | ✅ | ✅ |311| `get_adr_diagrams` | Get Mermaid diagrams for ADRs | — | ✅ | ✅ |312| `validate_adr_compliance` | Validate ADR implementation | — | ✅ | ✅ |313| `get_knowledge_graph` | Cross-repository knowledge graph | — | — | ✅ |314315### Workflow for New Repos316317```bash318# 1. Analyze codebase for implicit architectural decisions319suggest_adrs(analysisType: 'implicit_decisions')320321# 2. Generate ADR files from suggestions322generate_adr_from_decision(decisionData)323324# 3. Save ADRs to docs/adrs/325326# 4. (Optional) Sync to adraggregator.com327sync_to_aggregator(full_sync: true)328```329330**Benefits:** Cross-team visibility • Staleness alerts • Compliance tracking • Organization-wide knowledge graph331332📖 **[ADR Aggregator Guide →](https://adraggregator.com/docs)**333334## 🔧 Development335336```bash337git clone https://github.com/tosin2013/mcp-adr-analysis-server.git338cd mcp-adr-analysis-server339npm install && npm run build && npm test340```341342**Quality Standards:** TypeScript strict mode • ESLint • >80% test coverage • Pre-commit hooks343344### Viewing Documentation Locally345346The documentation site is built with [Docusaurus](https://docusaurus.io/):347348```bash349cd docs350npm install351npm run build352npm run serve353```354355Then open `http://localhost:3000/mcp-adr-analysis-server/` in your browser.356357📖 **[Development Guide →](docs/how-to-guides/getting-started-workflow-guidance.md)** | **[Contributing →](CONTRIBUTING.md)**358359## 🔧 Troubleshooting360361**Common Issues:**362363- **RHEL Systems**: Use special installer script364- **Tools return prompts**: Set `EXECUTION_MODE=full` + API key365- **Module not found**: Run `npm install && npm run build`366- **Permission denied**: Check file permissions and project path367368📖 **[Complete Troubleshooting Guide →](docs/how-to-guides/troubleshooting.md)**369370## 🔒 Security & Performance371372**Security:** Automatic secret detection • Content masking • Local processing • Zero trust373**Performance:** Multi-level caching • Incremental analysis • Parallel processing • Memory optimization374375📖 **[Security Guide →](docs/explanation/security-philosophy.md)** | **[Performance →](docs/explanation/performance-design.md)**376377### 🔐 Security Vulnerability Reporting378379Found a security issue? Please read our [Security Policy](SECURITY.md) for responsible disclosure procedures. **Do not** create public issues for security vulnerabilities.380381## 🤝 Contributing382383We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.384385### 🌟 Quick Start for Contributors3863871. **Fork** the repository3882. **Clone** your fork: `git clone https://github.com/YOUR_USERNAME/mcp-adr-analysis-server.git`3893. **Create** a branch: `git checkout -b feature/your-feature-name`3904. **Make** your changes with tests3915. **Test**: `npm test` (maintain >80% coverage)3926. **Submit** a Pull Request393394### 👶 First Time Contributing?395396Looking for a good first issue? Check out our [**good first issues**](https://github.com/tosin2013/mcp-adr-analysis-server/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) - these are beginner-friendly tasks perfect for getting started!397398**New to open source?** Our [Contributing Guide](CONTRIBUTING.md) walks you through the entire process step-by-step.399400### 📝 Reporting Issues401402Use our [**issue templates**](https://github.com/tosin2013/mcp-adr-analysis-server/issues/new/choose) when reporting bugs or requesting features. Templates help us understand and resolve issues faster.403404**Standards:** TypeScript strict • >80% coverage • ESLint • Security validation • MCP compliance405406📖 **[Full Contributing Guide →](CONTRIBUTING.md)** | **[Code of Conduct →](docs/community/CODE_OF_CONDUCT.md)**407408## 🔗 Resources409410**Official:** [MCP Specification](https://modelcontextprotocol.io/) • [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)411**Community:** [MCP Registry](https://github.com/modelcontextprotocol/servers) • [Discord](https://discord.gg/modelcontextprotocol)412**Project:** [ADRs](./docs/adrs/) • [Progress](./docs/release-dashboard.md) • [Publishing Guide](./docs/how-to-guides/NPM_PUBLISHING.md)413414## 📄 License415416MIT License - see [LICENSE](LICENSE) file for details.417418## 🙏 Acknowledgments419420- **Anthropic** for creating the Model Context Protocol421- **The MCP Community** for inspiration and best practices422- **Contributors** who help make this project better423424---425426**Built with ❤️ by [Tosin Akinosho](https://github.com/tosin2013) for AI-driven architectural analysis**427428_Empowering AI assistants with deep architectural intelligence and decision-making capabilities._429
Full transparency — inspect the skill content before installing.