Analyze Architecture and Generate ADRs

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

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 → · 📜 Release policy → · 🗒️ Changelog →

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 → | RHEL Setup →

⚡ 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).

📖 VS Code Integration Guide → - step-by-step setup for Cline, Continue, and VS Code native MCP with example configs.

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.

{
  "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 → | Client Setup →

Execution Modes

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.

If you're integrating the server into your own tooling via the 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',
  {
    useRipgrep: true, // Fast text search
    maxFiles: 10, // Limit results
    includeContent: true, // Include file contents
  }
);

📖 Complete Usage Guide → | API Reference →

Try it out: This repo includes a sample-project/ 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 →

🛠️ Technology Stack

Runtime: Node.js 20+ • Language: TypeScript • Framework: MCP SDK • Testing: Vitest (~49% statements, enforced floor) Search: ripgrep (fast recursive text search) + fast-glob (file matching) • AI Integration: CE-MCP orchestration directives (host LLM) • Code Analysis: tree-sitter (incremental code parser) + Smart Code Linking

📖 Technical Details → | CE-MCP Migration Playbook →

📁 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 →

🧪 Testing

npm test              # Run all tests
npm run test:coverage # Coverage report

📖 Testing Guide →

🌐 ADR Aggregator Integration (Optional)

ADR Aggregator 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.

# Set your API key (get one at adraggregator.com)
export ADR_AGGREGATOR_API_KEY="agg_your_key_here"

Available Tools

Workflow for New Repos

# 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 → | 📖 MCP Integration Guide →

🔧 Development

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:

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 → | Contributing →

🔧 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 →

🔒 Security & Performance

Security: Automatic secret detection • Content masking • Local processing • Zero trust
Performance: Multi-level caching • Incremental analysis • Parallel processing • Memory optimization

📖 Security Guide → | Performance →

🔐 Security Vulnerability Reporting

Found a security issue? Please read our Security Policy 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, and milestone membership is what marks an issue as admitted.

Architectural direction lives in docs/adrs/; release cadence is in RELEASES.md.

👶 First Time Contributing?

Looking for a good first issue? Check out our good first issues - these are beginner-friendly tasks perfect for getting started!

New to open source? Our Contributing Guide walks you through the entire process step-by-step.

📝 Reporting Issues

Use our issue templates 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 → | Code of Conduct →

🔗 Resources

Official: MCP Specification • MCP SDK
Community: MCP Registry • Discord
Project: ADRs • Progress • Publishing Guide

📄 License

MIT License - see 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 for AI-driven architectural analysis

Empowering AI assistants with drift detection, content safety, and decision memory via CE-MCP orchestration directives.

scripts/install-rhel.sh

#!/bin/bash

# MCP ADR Analysis Server - RHEL Installation Script
# Handles RHEL 9/10 specific issues with npm global installations and PATH

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_DIR="$(dirname "$SCRIPT_DIR")"

echo "🎯 MCP ADR Analysis Server - RHEL Installation"
echo "============================================="

# Check if we're on RHEL
if [ ! -f /etc/redhat-release ]; then
    echo "❌ This script is designed for RHEL systems"
    echo "For other systems, use: npm install -g mcp-adr-analysis-server"
    exit 1
fi

RHEL_VERSION=$(cat /etc/redhat-release)
echo "📋 Detected: $RHEL_VERSION"

# Check Node.js version
if ! command -v node >/dev/null 2>&1; then
    echo "❌ Node.js is not installed"
    echo "Install Node.js first:"
    echo "  sudo dnf module install nodejs:20/common"
    exit 1
fi

NODE_VERSION=$(node --version)
echo "✅ Node.js: $NODE_VERSION"

# Check npm version
if ! command -v npm >/dev/null 2>&1; then
    echo "❌ npm is not installed"
    exit 1
fi

NPM_VERSION=$(npm --version)
echo "✅ npm: $NPM_VERSION"

# RHEL-specific npm configuration
echo ""
echo "🔧 Configuring npm for RHEL..."

# Set npm prefix to user directory to avoid permission issues
NPM_PREFIX="$HOME/.npm-global"
mkdir -p "$NPM_PREFIX"

echo "Setting npm prefix to: $NPM_PREFIX"
npm config set prefix "$NPM_PREFIX"

# Add npm global bin to PATH if not already there
NPM_BIN_PATH="$NPM_PREFIX/bin"
if [[ ":$PATH:" != *":$NPM_BIN_PATH:"* ]]; then
    echo "Adding npm global bin to PATH"
    
    # Add to current session
    export PATH="$NPM_BIN_PATH:$PATH"
    
    # Add to bashrc for future sessions
    if ! grep -q "export PATH.*npm-global/bin" ~/.bashrc 2>/dev/null; then
        echo "" >> ~/.bashrc
        echo "# Add npm global bin to PATH (added by MCP ADR Analysis Server installer)" >> ~/.bashrc
        echo "export PATH=\"$NPM_BIN_PATH:\$PATH\"" >> ~/.bashrc
        echo "✅ Added npm global bin to ~/.bashrc"
    else
        echo "✅ npm global bin already in ~/.bashrc"
    fi
else
    echo "✅ npm global bin already in PATH"
fi

echo ""
echo "📦 Installing MCP ADR Analysis Server..."

# Try global installation first
if npm install -g mcp-adr-analysis-server; then
    echo "✅ Global installation successful"
    
    # Verify binary exists and is executable
    BINARY_PATH="$NPM_BIN_PATH/mcp-adr-analysis-server"
    if [ -f "$BINARY_PATH" ] && [ -x "$BINARY_PATH" ]; then
        echo "✅ Binary installed and executable at: $BINARY_PATH"
    else
        echo "⚠️  Binary not found or not executable, checking alternatives..."
        
        # Look for the binary in node_modules
        GLOBAL_NODE_MODULES="$(npm root -g)"
        ALT_BINARY="$GLOBAL_NODE_MODULES/mcp-adr-analysis-server/dist/src/index.js"
        
        if [ -f "$ALT_BINARY" ]; then
            echo "Found binary at: $ALT_BINARY"
            # Create symlink
            ln -sf "$ALT_BINARY" "$BINARY_PATH"
            chmod +x "$BINARY_PATH"
            echo "✅ Created symlink and made executable"
        fi
    fi
else
    echo "❌ Global installation failed, trying alternative approach..."
    
    # Alternative: Install locally and create wrapper script
    echo "Installing locally..."
    cd "$PROJECT_DIR"
    npm install
    npm run build
    
    # Create wrapper script
    WRAPPER_SCRIPT="$NPM_BIN_PATH/mcp-adr-analysis-server"
    mkdir -p "$(dirname "$WRAPPER_SCRIPT")"
    
    cat > "$WRAPPER_SCRIPT" << 'EOF'
#!/bin/bash
# MCP ADR Analysis Server wrapper script for RHEL

# Try to use global installation first
if command -v node >/dev/null 2>&1; then
    # Check if we can find the package
    GLOBAL_MODULES="$(npm root -g 2>/dev/null)"
    if [ -f "$GLOBAL_MODULES/mcp-adr-analysis-server/dist/src/index.js" ]; then
        exec node "$GLOBAL_MODULES/mcp-adr-analysis-server/dist/src/index.js" "$@"
    fi
    
    # Try npx as fallback
    if command -v npx >/dev/null 2>&1; then
        exec npx mcp-adr-analysis-server "$@"
    fi
    
    # Try local installation
    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
    PROJECT_BINARY="$SCRIPT_DIR/../mcp-adr-analysis-server/dist/src/index.js"
    if [ -f "$PROJECT_BINARY" ]; then
        exec node "$PROJECT_BINARY" "$@"
    fi
fi

echo "❌ MCP ADR Analysis Server not found"
echo "Try running: npm install -g mcp-adr-analysis-server"
exit 1
EOF
    
    chmod +x "$WRAPPER_SCRIPT"
    echo "✅ Created wrapper script at: $WRAPPER_SCRIPT"
fi

echo ""
echo "🧪 Testing installation..."

# Test the binary
if command -v mcp-adr-analysis-server >/dev/null 2>&1; then
    echo "✅ Binary found in PATH"
    
    # Test version
    if mcp-adr-analysis-server --version >/dev/null 2>&1; then
        VERSION=$(mcp-adr-analysis-server --version)
        echo "✅ $VERSION"
    else
        echo "⚠️  Binary found but version check failed"
    fi
    
    # Test health check
    if mcp-adr-analysis-server --test >/dev/null 2>&1; then
        echo "✅ Health check passed"
    else
        echo "⚠️  Health check failed"
    fi
else
    echo "❌ Binary not found in PATH"
    echo "You may need to restart your terminal or run: source ~/.bashrc"
fi

echo ""
echo "🎉 Installation completed!"
echo ""
echo "📋 MCP Configuration for RHEL:"
echo "Add this to your Claude Desktop config:"
echo ""
echo "{"
echo "  \"mcpServers\": {"
echo "    \"adr-analysis\": {"
echo "      \"command\": \"mcp-adr-analysis-server\","
echo "      \"env\": {"
echo "        \"PROJECT_PATH\": \"/path/to/your/project\","
echo "        \"OPENROUTER_API_KEY\": \"your_openrouter_api_key_here\","
echo "        \"EXECUTION_MODE\": \"full\","
echo "        \"AI_MODEL\": \"anthropic/claude-3-sonnet\","
echo "        \"ADR_DIRECTORY\": \"docs/adrs\","
echo "        \"LOG_LEVEL\": \"ERROR\""
echo "      }"
echo "    }"
echo "  }"
echo "}"
echo ""
echo "🚨 RHEL Alternative (if command still not found):"
echo "{"
echo "  \"mcpServers\": {"
echo "    \"adr-analysis\": {"
echo "      \"command\": \"npx\","
echo "      \"args\": [\"mcp-adr-analysis-server\"],"
echo "      \"env\": {"
echo "        \"PROJECT_PATH\": \"/path/to/your/project\","
echo "        \"OPENROUTER_API_KEY\": \"your_openrouter_api_key_here\","
echo "        \"EXECUTION_MODE\": \"full\","
echo "        \"AI_MODEL\": \"anthropic/claude-3-sonnet\","
echo "        \"ADR_DIRECTORY\": \"docs/adrs\","
echo "        \"LOG_LEVEL\": \"ERROR\""
echo "      }"
echo "    }"
echo "  }"
echo "}"
echo ""
echo "💡 Troubleshooting:"
echo "- If command not found: source ~/.bashrc or restart terminal"
echo "- If still issues: use the npx configuration above"
echo "- For debugging: run with LOG_LEVEL=DEBUG"