Adr Analysis

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

AI-powered architectural analysis for intelligent development workflows. Returns actual analysis results, not prompts to submit elsewhere.

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 analysis servers. This server enhances AI assistants with deep architectural analysis capabilities, enabling intelligent code generation, decision tracking, and development workflow automation.

TL;DR

What: MCP server that provides AI-powered architectural decision analysis and ADR management
Who: AI coding assistants (Claude, Cline, Cursor), enterprise architects, development teams
Why: Get immediate architectural insights instead of prompts, with 95% confidence scoring
How: npm install -g mcp-adr-analysis-server → Configure with OpenRouter API → Start analyzing

Key Features: Tree-sitter AST analysis • Security content masking • Test-driven development • Deployment readiness validation

Author: Tosin Akinosho | Repository: GitHub

✨ Core Capabilities

🤖 AI-Powered Analysis - Immediate architectural insights with OpenRouter.ai integration 🏗️ Technology Detection - Identify any tech stack and architectural patterns 📋 ADR Management - Generate, suggest, and maintain Architectural Decision Records 🔗 Smart Code Linking - AI-powered discovery of code files related to ADRs and decisions 🛡️ Security & Compliance - Detect and mask sensitive content automatically 🧪 TDD Integration - Two-phase Test-Driven Development with validation 🚀 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 (3 Steps)

1. Get API Key: Sign up at 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 below.
2. Set Environment: OPENROUTER_API_KEY=your_key + EXECUTION_MODE=full
3. Configure Client: Add to Claude Desktop, Cline, Cursor, or 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"
      }
    }
  }
}

Claude Desktop users: Save this JSON to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

{
  "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"
      }
    }
  }
}

Get your API key at adraggregator.com

📖 Full Configuration Guide → | Client Setup →

Execution Modes

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.

🚀 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 actual analysis results instead of prompts to submit elsewhere!

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 Li

…