# tosin2013/mcp-adr-analysis-server [Health: Active] **Category:** πŸ“Š Data Visualization **Repository:** https://github.com/tosin2013/mcp-adr-analysis-server **GitHub Stars:** 33 **npm Downloads (last month):** 8443 **Views:** 2 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/tosin2013-mcp-adr-analysis-server ## Description AI-powered architectural analysis server for software projects. Provides technology stack detection, ADR management, security checks, enhanced TDD workflow, and deployment readiness validation with support for multiple AI models. ## Tools Capabilities this server exposes over MCP: - **sync_to_aggregator** β€” Push local ADRs to platform - **get_adr_context** β€” Pull ADR context from platform - **get_staleness_report** β€” Get ADR governance/health reports - **get_adr_templates** β€” Retrieve domain-specific templates - **get_adr_diagrams** β€” Get Mermaid diagrams for ADRs - **validate_adr_compliance** β€” Validate ADR implementation - **get_knowledge_graph** β€” Cross-repository knowledge graph ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "mcp-adr-analysis-server": { "command": "npx", "args": ["-y","mcp-adr-analysis-server"] } } ``` ## Documentation & README # MCP (Model Context Protocol) ADR (Architectural Decision Record) Analysis Server [![GitHub](https://img.shields.io/badge/github-tosin2013/mcp--adr--analysis--server-blue.svg?style=flat&logo=github)](https://github.com/tosin2013/mcp-adr-analysis-server) [![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE) [![NPM Version](https://img.shields.io/npm/v/mcp-adr-analysis-server)](https://www.npmjs.com/package/mcp-adr-analysis-server) [![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue)](https://www.typescriptlang.org/) [![Good First Issues](https://img.shields.io/github/issues/tosin2013/mcp-adr-analysis-server/good%20first%20issue?label=good%20first%20issues&color=7057ff)](https://github.com/tosin2013/mcp-adr-analysis-server/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) > **Your ADRs are lying to you.** This MCP server catches it β€” live drift detection validates architectural decisions against your actual code. Plus content safety, decision memory, and 64 tools powered by your host LLM via CE-MCP. ## What is MCP? 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 servers. This server gives your AI assistant the ability to detect ADR drift against live code, mask sensitive content before it leaks, and remember architectural decisions across conversations. ## TL;DR **What:** MCP server that validates architectural decisions against your actual code β€” drift detection, content safety, and decision memory **Who:** AI coding assistants (Claude, Cline, Cursor, Windsurf), enterprise architects, development teams **Why:** Catch stale ADRs before they cause production incidents β€” live validation against code evidence, no API key required **How:** `npm install -g mcp-adr-analysis-server` β†’ Add to your MCP client β†’ Start analyzing **Key Features:** Tree-sitter AST analysis β€’ Security content masking β€’ Drift detection β€’ CE-MCP orchestration directives β€’ Deployment readiness validation
Key Terms | Term | Definition | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **ADR** | **Architectural Decision Record** β€” A document that captures an important architectural decision along with its context, alternatives considered, and consequences. | | **MCP** | **Model Context Protocol** β€” An open standard enabling AI assistants to connect to external tools and data sources. | | **CE-MCP** | **Claude-Enriched MCP** β€” Execution mode where tools return orchestration directives for the host LLM instead of making their own AI calls. Default since v2.14. | | **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. | | **Session & Tool-Usage Tracker** | Project-local tracking of session intents, tool executions, and ADR registrations, with keyword-scored retrieval over JSON snapshots. Supports workflow continuity and tool-usage evidence β€” not a graph database. | | **Smart Code Linking** | Discovery of code files related to ADRs and architectural decisions, using keyword extraction and ripgrep search. | | **ADR Aggregator** | Optional SaaS integration for syncing and sharing ADR context across teams (`ADR_AGGREGATOR_API_KEY`). |
--- **Author**: [Tosin Akinosho](https://github.com/tosin2013) | **Repository**: [GitHub](https://github.com/tosin2013/mcp-adr-analysis-server.git) ## ✨ Core Capabilities πŸ”„ **Drift Detection** - Validate ADR decisions against live code and infrastructure evidence πŸ›‘οΈ **Content Safety** - Detect and mask secrets, PII, and sensitive content automatically 🧠 **Decision Memory** - Session & tool-usage tracking with keyword-scored retrieval πŸ—οΈ **Technology Detection** - Identify any tech stack and architectural patterns πŸ“‹ **ADR Management** - Generate, suggest, and maintain Architectural Decision Records πŸ”— **Smart Code Linking** - Discovery of code files related to ADRs and decisions πŸš€ **Deployment Readiness** - Zero-tolerance test validation with hard blocking πŸ“– **[View Full Capabilities β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/explanation/index.md)** Β· πŸ“œ **[Release policy β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/RELEASES.md)** Β· πŸ—’οΈ **[Changelog β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/CHANGELOG.md)** ## Prerequisites Before installing, verify you have: ```bash node --version # Should show v20.0.0 or higher npm --version # Should show 9.0.0 or higher (included with Node.js 20+) ``` **Required:** - **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) - **npm 9.0.0 or higher** (included with Node.js 20+) - **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) ### Network Requirements - **Internet access required** during `npm install` for native module compilation ([tree-sitter](https://tree-sitter.github.io/tree-sitter/) incremental code parsers for YAML and TypeScript) - If behind a corporate proxy, set `HTTP_PROXY` and `HTTPS_PROXY` environment variables - **Offline fallback**: If native builds fail, the server operates in reduced mode without tree-sitter code analysis ## πŸ“¦ Quick Installation ```bash # 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 ``` > **Note:** When installing from source, `npm run build` is required before running the server since the `bin` entry points to `./dist/src/index.js`. πŸ“– **[Detailed Installation Guide β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/tutorials/01-first-steps.md)** | **[RHEL Setup β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/scripts/install-rhel.sh)** ## ⚑ Quick Setup (2 Steps) 1. **Install**: `npm install -g mcp-adr-analysis-server` 2. **Configure Client**: Add to Claude Desktop, Cline, Cursor, or Windsurf β€” no API key required ```json { "mcpServers": { "adr-analysis": { "command": "mcp-adr-analysis-server", "env": { "PROJECT_PATH": "/path/to/your/project" } } } } ``` That's it. The server runs in **CE-MCP mode** by default β€” your host LLM (Claude, GPT, etc.) executes the analysis using orchestration directives returned by the tools. No external API key needed. > **Claude Desktop users:** Save this JSON to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
Config locations for other clients | Client | Config file location | | ---------------------------- | ----------------------------------------------------------------------------- | | **Claude Desktop (macOS)** | `~/Library/Application Support/Claude/claude_desktop_config.json` | | **Claude Desktop (Windows)** | `%APPDATA%\Claude\claude_desktop_config.json` | | **Cline (VS Code)** | VS Code Settings β†’ Cline β†’ MCP Servers (or `.vscode/cline_mcp_settings.json`) | | **VS Code (native MCP)** | `.vscode/mcp.json` in workspace root | | **Cursor** | Cursor Settings β†’ MCP β†’ Add Server | πŸ“– **[VS Code Integration Guide β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/how-to-guides/vscode-integration.md)** β€” step-by-step setup for Cline, Continue, and VS Code native MCP with example configs.
Optional: OpenRouter Full Mode (legacy) If you want the server to make its own AI calls (bypassing the host LLM), add an OpenRouter API key: ```json { "mcpServers": { "adr-analysis": { "command": "mcp-adr-analysis-server", "env": { "PROJECT_PATH": "/path/to/your/project", "OPENROUTER_API_KEY": "your_key_here", "EXECUTION_MODE": "full" } } } } ``` Sign up at [OpenRouter.ai/keys](https://openrouter.ai/keys). This mode is **not recommended** β€” CE-MCP produces equivalent results using your existing host LLM context.
Optional: ADR Aggregator integration ```json { "mcpServers": { "adr-analysis": { "command": "mcp-adr-analysis-server", "env": { "PROJECT_PATH": "/path/to/your/project", "ADR_AGGREGATOR_API_KEY": "agg_your_key_here" } } } } ``` Get your API key at [adraggregator.com](https://adraggregator.com)
πŸ“– **[Full Configuration Guide β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/reference/mcp-client-config.md)** | **[Client Setup β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/reference/environment-config.md)** ### Execution Modes | | **CE-MCP (default)** | **Full Mode (legacy)** | **Prompt-Only** | | --------------------- | ---------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------- | | **Requires API key?** | No | Yes (`OPENROUTER_API_KEY`) | No | | **Returns** | Orchestration directives for the host LLM to execute | Server-side AI analysis results | Prompts you can paste into any AI chat | | **Set via** | Default (no env var needed) | `EXECUTION_MODE=full` | `EXECUTION_MODE=prompt-only` | | **Best for** | All users β€” recommended | Legacy workflows with dedicated API budget | Offline exploration | | **Tools available** | All 64 tools with annotated MCP metadata | All 64 tools | Analysis prompts, templates, local file operations, ADR discovery | **What are CE-MCP directives?** When a tool is called, it returns a structured orchestration directive that tells your host LLM what to analyze, what data to gather, and how to format results. The host LLM (e.g. Claude in Claude Desktop, or GPT in Cursor) executes the directive using its existing context window. This means **zero additional API costs** and **better results** because the LLM already has your conversation context. ## πŸš€ Usage Examples Just ask your MCP client in natural language β€” no code required: > "Analyze this React project's architecture and suggest ADRs for any implicit decisions" > "Generate ADRs from the PRD.md file and create a todo.md with implementation tasks" > "Check this codebase for security issues and provide masking recommendations" **The server returns structured analysis and orchestration directives** that your host LLM executes in context.
Programmatic Usage (Advanced) If you're integrating the server into your own tooling via the MCP SDK: ```typescript // 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 } ); ```
πŸ“– **[Complete Usage Guide β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/tutorials/01-first-steps.md)** | **[API Reference β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/reference/index.md)** > **Try it out:** This repo includes a [`sample-project/`](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/sample-project/README.md) directory with example ADRs and source code. Point `PROJECT_PATH` at it to experiment without affecting your own codebase. > > **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` ## 🎯 Use Cases πŸ‘¨β€πŸ’» **AI Coding Assistants** - Enhance Claude, Cline, Cursor with architectural intelligence πŸ’¬ **Conversational AI** - Answer architecture questions with confidence scoring πŸ€– **Autonomous Agents** - Continuous analysis and rule enforcement 🏒 **Enterprise Teams** - Portfolio analysis and migration planning πŸ“– **[Detailed Use Cases β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/explanation/mcp-concepts.md)** ## πŸ› οΈ Technology Stack **Runtime:** Node.js 20+ β€’ **Language:** TypeScript β€’ **Framework:** MCP SDK β€’ **Testing:** Vitest (~49% statements, enforced floor) **Search:** [ripgrep](https://github.com/BurntSushi/ripgrep) (fast recursive text search) + fast-glob (file matching) β€’ **AI Integration:** CE-MCP orchestration directives (host LLM) β€’ **Code Analysis:** [tree-sitter](https://tree-sitter.github.io/tree-sitter/) (incremental code parser) + Smart Code Linking πŸ“– **[Technical Details β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/explanation/server-architecture.md)** | **[CE-MCP Migration Playbook β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/how-to-guides/ce-mcp-migration-playbook.md)** ## πŸ“ Project Structure ``` 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 ``` πŸ“– **[Full Structure β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/tutorials/01-first-steps.md)** ## πŸ§ͺ Testing ```bash npm test # Run all tests npm run test:coverage # Coverage report ``` πŸ“– **[Testing Guide β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/how-to-guides/troubleshooting.md)** ## 🌐 ADR Aggregator Integration (Optional) [ADR Aggregator](https://adraggregator.com) is a platform for cross-team ADR visibility and governance. It provides: - **Cross-repository knowledge graphs** β€” See how architectural decisions relate across projects - **Governance dashboards** β€” Track ADR compliance, staleness, and review cycles - **Template library** β€” Access domain-specific ADR templates (security, API, database, etc.) - **Team collaboration** β€” Share architectural decisions organization-wide > **Note:** ADR Aggregator is optional. All core analysis features work without it. ```bash # Set your API key (get one at adraggregator.com) export ADR_AGGREGATOR_API_KEY="agg_your_key_here" ``` ### Available Tools | Tool | Description | Free | Pro+ | Team | | ------------------------- | ---------------------------------- | ---- | ---- | ---- | | `sync_to_aggregator` | Push local ADRs to platform | βœ… | βœ… | βœ… | | `get_adr_context` | Pull ADR context from platform | βœ… | βœ… | βœ… | | `get_staleness_report` | Get ADR governance/health reports | βœ… | βœ… | βœ… | | `get_adr_templates` | Retrieve domain-specific templates | βœ… | βœ… | βœ… | | `get_adr_diagrams` | Get Mermaid diagrams for ADRs | β€” | βœ… | βœ… | | `validate_adr_compliance` | Validate ADR implementation | β€” | βœ… | βœ… | | `get_knowledge_graph` | Cross-repository knowledge graph | β€” | β€” | βœ… | ### Workflow for New Repos ```bash # 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) ``` **Benefits:** Cross-team visibility β€’ Staleness alerts β€’ Compliance tracking β€’ Organization-wide knowledge graph πŸ“– **[ADR Aggregator Guide β†’](https://adraggregator.com/docs)** | πŸ“– **[MCP Integration Guide β†’](https://adraggregator.com/mcp-guide)** ## πŸ”§ Development ```bash git clone https://github.com/tosin2013/mcp-adr-analysis-server.git cd mcp-adr-analysis-server npm install && npm run build && npm test ``` **Quality Standards:** TypeScript strict mode β€’ ESLint β€’ enforced coverage floor β€’ Pre-commit hooks ### Viewing Documentation Locally API documentation is generated with [TypeDoc](https://typedoc.org/): ```bash 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 ``` Then open `http://localhost:8080` in your browser. Markdown documentation lives in `docs/` and can be browsed directly on GitHub. πŸ“– **[Development Guide β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/how-to-guides/getting-started-workflow-guidance.md)** | **[Contributing β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/CONTRIBUTING.md)** ## πŸ”§ Troubleshooting **Common Issues:** - **RHEL Systems**: Use special installer script - **Tools return directives instead of results**: This is expected in CE-MCP mode β€” your host LLM executes the directives. For server-side execution, set `EXECUTION_MODE=full` + `OPENROUTER_API_KEY` - **Module not found**: Run `npm install && npm run build` - **Permission denied**: Check file permissions and project path πŸ“– **[Complete Troubleshooting Guide β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/how-to-guides/troubleshooting.md)** ## πŸ”’ Security & Performance **Security:** Automatic secret detection β€’ Content masking β€’ Local processing β€’ Zero trust **Performance:** Multi-level caching β€’ Incremental analysis β€’ Parallel processing β€’ Memory optimization πŸ“– **[Security Guide β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/explanation/security-philosophy.md)** | **[Performance β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/explanation/performance-design.md)** ### πŸ” Security Vulnerability Reporting Found a security issue? Please read our [Security Policy](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/SECURITY.md) for responsible disclosure procedures. **Do not** create public issues for security vulnerabilities. ## 🀝 Contributing We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated. ### 🌟 Quick Start for Contributors 1. **Fork** the repository 2. **Clone** your fork: `git clone https://github.com/YOUR_USERNAME/mcp-adr-analysis-server.git` 3. **Create** a branch: `git checkout -b feature/your-feature-name` 4. **Make** your changes with tests 5. **Test**: `npm test` (do not drop below the coverage floor) 6. **Submit** a Pull Request ### πŸ—ΊοΈ Roadmap Work is tracked in [GitHub milestones](https://github.com/tosin2013/mcp-adr-analysis-server/milestones), and milestone membership is what marks an issue as admitted. Architectural direction lives in [`docs/adrs/`](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/adrs/README.md); release cadence is in [`RELEASES.md`](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/RELEASES.md). ### πŸ‘Ά First Time Contributing? Looking 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! **New to open source?** Our [Contributing Guide](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/CONTRIBUTING.md) walks you through the entire process step-by-step. ### πŸ“ Reporting Issues Use 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. **Standards:** TypeScript strict β€’ enforced coverage floor β€’ ESLint β€’ Security validation β€’ MCP compliance πŸ“– **[Full Contributing Guide β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/CONTRIBUTING.md)** | **[Code of Conduct β†’](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/community/CODE_OF_CONDUCT.md)** ## πŸ”— Resources **Official:** [MCP Specification](https://modelcontextprotocol.io/) β€’ [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) **Community:** [MCP Registry](https://github.com/modelcontextprotocol/servers) β€’ [Discord](https://discord.gg/modelcontextprotocol) **Project:** [ADRs](https://github.com/tosin2013/mcp-adr-analysis-server/tree/main/docs/adrs) β€’ [Progress](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/release-dashboard.md) β€’ [Publishing Guide](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/docs/how-to-guides/push-tags-to-npm.md) ## πŸ“„ License MIT License - see [LICENSE](https://github.com/tosin2013/mcp-adr-analysis-server/blob/HEAD/LICENSE) file for details. ## πŸ™ Acknowledgments - **Anthropic** for creating the Model Context Protocol - **The MCP Community** for inspiration and best practices - **Contributors** who help make this project better --- **Built with ❀️ by [Tosin Akinosho](https://github.com/tosin2013) for AI-driven architectural analysis** _Empowering AI assistants with drift detection, content safety, and decision memory via CE-MCP orchestration directives._