MCP Adr Analysis Server

MCP (Model Context Protocol) ADR (Architectural Decision Record) Analysis Server

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 63 tools powered by your host LLM via CE-MCP.

Table of contents

• What is MCP?
• Prerequisites
• Quick Installation
• Quick Setup
• Usage Examples
• Use Cases
• Technology Stack
• Project Structure
• Testing
• ADR Aggregator Integration
• Development
• Troubleshooting
• Security & Performance
• Contributing
• Resources
• License

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

Author: Tosin Akinosho | Repository: GitHub | Version: 2.14.12

✨ 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 →](docs/explanation/index.md) · 📜 [Release policy →](RELEASES.md) · 🗒️ [Changelog →](CHANGELOG.md)

Prerequisites

Before installing, verify you have:

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 or use nvm/fnm
• npm 9.0.0 or higher (included with Node.js 20+)
• An MCP-compatible client — Claude Desktop, Cline, Cursor, or Windsurf

Network Requirements

• Internet access required during npm install for native module compilation (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

# 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 →](docs/tutorials/01-first-steps.md) | [RHEL Setup →](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

{

"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

📖 [VS Code Integration Guide →](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:

{

"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. This mode is not recommended — CE-MCP produces equivalent results using your existing host LLM context.

Optional: ADR Aggregator integration

{

"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

📖 [Full Configuration Guide →](docs/reference/mcp-client-config.md) | [Client Setup →](docs/reference/environment-config.md)

Execution Modes