MCP ADR Analysis Server

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

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

What is MCP?

The Model Context Protocol enables seamless integration between AI assistants and external tools. This server enhances AI assistants with deep architectural analysis capabilities, enabling intelligent code generation, decision tracking, and development workflow automation.

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

Prerequisites

• Node.js 20.0.0
• ripgrep (rg) - Required for code search functionality

# Install ripgrep
# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# RHEL/Fedora
sudo dnf install ripgrep

# Windows (with Chocolatey)
choco install ripgrep

# Windows (with Scoop)
scoop install ripgrep

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: RHEL 9/10 systems (special installer)
curl -sSL https://raw.githubusercontent.com/tosin2013/mcp-adr-analysis-server/main/scripts/install-rhel.sh | bash

Detailed Installation Guide | RHEL Setup

Quick Setup (3 Steps)

1. Get API Key: OpenRouter.ai/keys
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"
      }
    }
  }
}

Full Configuration Guide | Client Setup

Usage Examples

Ask Claude (or any MCP client):

"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!

// 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',
  {
    useAI: true, // AI-powered keyword extraction
    useRipgrep: true, // Fast text search
    maxFiles: 10, // Limit results
    includeContent: true, // Include file contents
  }
);

Complete Usage Guide | API Reference

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: Jest (>80% coverage)
Search: ripgrep + fast-glob AI Integration: OpenRouter.ai Web Research: Firecrawl Code Analysis: Smart Code Linking

Technical Details

Project Structure

src/tools/     # 23 MCP tools for analysis
docs/adrs/     # Architectural Decision Records
tests/         # >80% test coverage
.github/       # CI/CD automation

Full Structure

Testing

npm test              # Run all tests (>80% coverage)
npm run test:coverage # Coverage report

Testing Guide

Firecrawl Integration (Optional)

Enhanced web research capabilities for comprehensive architectural analysis.

# Option 1: Cloud service (recommended)
export FIRECRAWL_ENABLED="true"
export FIRECRAWL_API_KEY="fc-your-api-key-here"

# Option 2: Self-hosted
export FIRECRAWL_ENABLED="true"
export FIRECRAWL_BASE_URL="http://localhost:3000"

# Option 3: Disabled (default - server works without web search)

Benefits: Real-time research Enhanced ADRs Best practices discovery Intelligent web scraping

Firecrawl Setup 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 >80% test coverage Pre-commit hooks

Development Guide | Contributing

Troubleshooting

Common Issues:

• RHEL Systems: Use special installer script
• Tools return prompts: Set EXECUTION_MODE=full + 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 (maintain >80% coverage)
6. Submit a Pull Request

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 >80% coverage 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 deep architectural intelligence and decision-making capabilities.