AI-powered architectural analysis for intelligent development workflows. This Model Context Protocol (MCP) server provides immediate, actionable architectural insights instead of prompts. Get real ADR suggestions, technology analysis, and security recommendations through OpenRouter.ai integration.

Key Differentiator: Returns actual analysis results, not prompts to submit elsewhere.

Author: Tosin Akinosho | Repository: GitHub

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.

🤖 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 🛡️ Security & Compliance - Detect and mask sensitive content automatically 📊 Workflow Automation - Todo generation, deployment tracking, and rule validation 🧪 TDD Integration - Two-phase Test-Driven Development with ADR linking and validation 🔍 Mock Detection - Sophisticated analysis to distinguish mock from production code 🚀 Deployment Readiness - Zero-tolerance test validation with deployment history tracking and hard blocking

# Global installation
npm install -g mcp-adr-analysis-server

# Local installation
npm install mcp-adr-analysis-server

# Download and run the RHEL-specific installer
curl -sSL https://raw.githubusercontent.com/tosin2013/mcp-adr-analysis-server/main/scripts/install-rhel.sh | bash

# Or if you have the repository cloned:
git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
cd mcp-adr-analysis-server
./scripts/install-rhel.sh

Why RHEL needs special handling:

• RHEL 9/10 have specific npm PATH and permission issues
• Global npm installations often fail due to SELinux policies
• The script handles npm prefix configuration and PATH setup automatically

git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
cd mcp-adr-analysis-server
npm install
npm run build
npm start

The MCP server supports AI-powered execution that transforms tools from returning prompts to returning actual results. This solves the fundamental UX issue where AI agents receive prompts instead of actionable data.

1. Get OpenRouter API Key: Visit https://openrouter.ai/keys
2. Set Environment Variables:

   OPENROUTER_API_KEY=your_openrouter_api_key_here
   EXECUTION_MODE=full
   AI_MODEL=anthropic/claude-3-sonnet

3. Restart MCP Server: Tools now return actual results instead of prompts!

• OPENROUTER_API_KEY (Required for AI): OpenRouter API key from https://openrouter.ai/keys
• EXECUTION_MODE (Optional): full (AI execution) or prompt-only (legacy)
• AI_MODEL (Optional): AI model to use (see supported models below)

• AI_TEMPERATURE (Optional): Response consistency (0-1, default: 0.1)
• AI_MAX_TOKENS (Optional): Response length limit (default: 4000)
• AI_TIMEOUT (Optional): Request timeout in ms (default: 60000)
• AI_CACHE_ENABLED (Optional): Enable response caching (default: true)

• PROJECT_PATH (Required): Path to the project directory to analyze
• ADR_DIRECTORY (Optional): Directory containing ADR files (default: docs/adrs)
• LOG_LEVEL (Optional): Logging level (DEBUG, INFO, WARN, ERROR)

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "EXECUTION_MODE": "full",
        "ADR_DIRECTORY": "docs/adrs",
        "LOG_LEVEL": "ERROR"
      }
    }
  }
}

Add to your cline_mcp_settings.json:

{
  "mcpServers": {
    "mcp-adr-analysis-server": {
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": "${workspaceFolder}",
        "ADR_DIRECTORY": "docs/adrs",
        "LOG_LEVEL": "ERROR"
      }
    }
  }
}

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "adr-analysis": {
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": ".",
        "ADR_DIRECTORY": "docs/adrs",
        "LOG_LEVEL": "ERROR"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "args": [],
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "ADR_DIRECTORY": "docs/adrs",
        "LOG_LEVEL": "ERROR"
      }
    }
  }
}

// Analyze any project's technology stack and architecture
const analysis = await analyzeProjectEcosystem({
  projectPath: "/path/to/project",
  analysisType: "comprehensive"
});

// Get intelligent architectural insights
const context = await getArchitecturalContext({
  projectPath: "/path/to/project",
  focusAreas: ["security", "scalability", "maintainability"]
});

// Convert PRD to structured ADRs
const adrs = await generateAdrsFromPrd({
  prdPath: "docs/PRD.md",
  outputDirectory: "docs/adrs",
  template: "nygard"
});

// Generate actionable todos from ADRs with enhanced TDD approach
const todos = await generateAdrTodo({
  adrDirectory: "docs/adrs",
  outputPath: "todo.md",
  phase: "both",           // Two-phase TDD: test + production
  linkAdrs: true,          // Link all ADRs for system-wide coverage
  includeRules: true       // Include architectural rules validation
});

// Phase 1: Generate comprehensive test specifications
const testPhase = await generateAdrTodo({
  adrDirectory: "docs/adrs",
  outputPath: "todo-tests.md",
  phase: "test",           // Generate mock test specifications
  linkAdrs: true,          // Connect all ADRs for complete test coverage
  includeRules: true       // Validate against architectural rules
});

// Phase 2: Generate production implementation tasks
const prodPhase = await generateAdrTodo({
  adrDirectory: "docs/adrs", 
  outputPath: "todo-implementation.md",
  phase: "production",     // Generate production-ready implementation tasks
  linkAdrs: true,          // Ensure system-wide consistency
  includeRules: true       // Enforce architectural compliance
});

// Validate progress and detect mock vs production code
const validation = await compareAdrProgress({
  todoPath: "todo.md",
  adrDirectory: "docs/adrs",
  projectPath: "/path/to/project",
  deepCodeAnalysis: true,     // Distinguish mock from production code
  functionalValidation: true, // Validate code actually works
  strictMode: true           // Reality-check against LLM overconfidence
});

// Analyze and mask sensitive content
const maskedContent = await maskContent({
  content: "API_KEY=secret123",
  maskingLevel: "strict"
});

// Validate architectural rules
const validation = await validateRules({
  projectPath: "/path/to/project",
  ruleSet: "enterprise-security"
});

// Generate context-aware research questions
const questions = await generateResearchQuestions({
  projectContext: analysis,
  focusArea: "microservices-migration"
});

// Incorporate research findings
const updatedAdrs = await incorporateResearch({
  researchFindings: findings,
  adrDirectory: "docs/adrs"
});

// Comprehensive validation with mock detection
const qualityCheck = await compareAdrProgress({
  todoPath: "todo.md",
  adrDirectory: "docs/adrs",
  projectPath: "/path/to/project",
  
  // Prevent LLM deception about code completeness
  deepCodeAnalysis: true,        // Detects mock patterns vs real implementation
  functionalValidation: true,    // Tests if code actually works
  strictMode: true,             // Reality-check mechanisms
  
  // Advanced analysis options
  includeTestCoverage: true,     // Validate test coverage meets ADR goals
  validateDependencies: true,    // Check cross-ADR dependencies
  environmentValidation: true    // Test in realistic environments
});

// Generate architectural rules from ADRs and patterns
const rules = await generateRules({
  source: "both",               // Extract from ADRs and code patterns
  adrDirectory: "docs/adrs",
  projectPath: "/path/to/project",
  outputFormat: "json"          // Machine-readable format
});

// Comprehensive deployment validation with zero tolerance
const deploymentCheck = await deploymentReadiness({
  operation: "full_audit",
  projectPath: "/path/to/project",
  targetEnvironment: "production",
  
  // Test validation (zero tolerance by default)
  maxTestFailures: 0,              // Hard block on any test failures
  requireTestCoverage: 80,         // Minimum coverage requirement
  blockOnFailingTests: true,       // Prevent deployment with failing tests
  
  // Deployment history validation
  maxRecentFailures: 2,            // Max recent deployment failures
  deploymentSuccessThreshold: 80,  // Required success rate
  rollbackFrequencyThreshold: 20,  // Max rollback frequency
  
  // Integration options
  integrateTodoTasks: true,        // Auto-create blocking tasks
  updateHealthScoring: true,       // Update project metrics
  strictMode: true                 // Enable all safety checks
});

// Enhanced git push with deployment readiness
const pushResult = await smartGitPush({
  message: "Deploy feature X",
  branch: "main",
  
  // Deployment readiness integration
  checkDeploymentReadiness: true,     // Validate before push
  enforceDeploymentReadiness: true,   // Hard block on issues
  targetEnvironment: "production",    // Environment-specific checks
  strictDeploymentMode: true          // Maximum safety
});

// Emergency override for critical fixes
const override = await deploymentReadiness({
  operation: "emergency_override",
  businessJustification: "Critical security patch - CVE-2024-XXXX",
  approvalRequired: true
});

Enhance AI coding assistants like Cline, Cursor, and Claude Code

• Test-Driven Development: Two-phase TDD workflow with comprehensive ADR integration
• Intelligent Code Generation: Generate code that follows architectural patterns and best practices
• Mock vs Production Detection: Prevent AI assistants from claiming mock code is production-ready
• Architecture-Aware Refactoring: Refactor code while maintaining architectural integrity
• Decision Documentation: Automatically document architectural decisions as you code
• Pattern Recognition: Identify and suggest architectural patterns for new features
• Quality Validation: Reality-check mechanisms against overconfident AI assessments

Enhance chatbots and business agents with architectural intelligence

• Technical Documentation: Answer questions about system architecture and design decisions
• Compliance Checking: Verify that proposed changes meet architectural standards
• Knowledge Synthesis: Combine information from multiple sources for comprehensive answers
• Decision Support: Provide data-driven recommendations for architectural choices

Enable autonomous agents to understand and work with complex architectures

• Automated Analysis: Continuously analyze codebases for architectural drift
• Rule Enforcement: Automatically enforce architectural rules and patterns
• Documentation Generation: Generate and maintain architectural documentation
• Deployment Validation: Verify deployment readiness and compliance

Support enterprise architects and development teams

• Portfolio Analysis: Analyze multiple projects for consistency and compliance
• Migration Planning: Plan and track architectural migrations and modernization
• Risk Assessment: Identify architectural risks and technical debt
• Standards Enforcement: Ensure compliance with enterprise architectural standards

• Runtime: Node.js (>=18.0.0)
• Language: TypeScript with strict configuration
• Core Framework: @modelcontextprotocol/sdk
• Validation: Zod schemas for all data structures
• Testing: Jest with >80% coverage target
• Linting: ESLint with comprehensive rules
• Build: TypeScript compiler with incremental builds
• CI/CD: GitHub Actions with automated testing and publishing

mcp-adr-analysis-server/
├── src/
│   ├── index.ts              # Main MCP server entry point
│   ├── tools/                # MCP tool implementations (23 tools)
│   ├── resources/            # MCP resource implementations
│   ├── prompts/              # MCP prompt implementations
│   ├── types/                # TypeScript interfaces & schemas
│   ├── utils/                # Utility functions and helpers
│   └── cache/                # Intelligent caching system
├── docs/
│   ├── adrs/                 # Architectural Decision Records
│   ├── research/             # Research findings and templates
│   └── NPM_PUBLISHING.md     # NPM publishing guide
├── tests/                    # Comprehensive test suite
├── .github/workflows/        # CI/CD automation
├── scripts/                  # Build and deployment scripts
└── dist/                     # Compiled JavaScript output

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Test MCP server functionality
npm run test:package

• Unit Tests: Individual component testing with >80% coverage
• Integration Tests: MCP protocol and file system testing
• Custom Matchers: ADR and schema validation helpers
• Performance Tests: Caching and optimization validation

• Node.js >= 18.0.0
• npm or yarn
• Git

# Clone the repository
git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
cd mcp-adr-analysis-server

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Start development server
npm run dev

npm run build         # Build TypeScript to JavaScript
npm run dev           # Start development server with hot reload
npm test              # Run Jest tests with coverage
npm run lint          # Run ESLint checks
npm run lint:fix      # Fix ESLint issues automatically
npm run clean         # Clean build artifacts and cache
npm run format        # Format code with Prettier
npm run typecheck     # Run TypeScript type checking

• TypeScript: Strict mode with comprehensive type checking
• ESLint: Enforced code quality and security rules
• Testing: Jest with custom matchers for ADR validation
• Coverage: Minimum 80% test coverage required
• Security: Content masking and secret prevention
• MCP Compliance: Strict adherence to Model Context Protocol specification

1. Install: npm install -g mcp-adr-analysis-server
2. Get API Key: Visit https://openrouter.ai/keys
3. Configure Claude Desktop: Add to your configuration:

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet"
      }
    }
  }
   }

4. Restart Claude Desktop and start getting AI-powered architectural insights!

Once configured, you can ask Claude:

"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 will now return actual analysis results instead of prompts to submit elsewhere!

The MCP server now provides a complete development lifecycle assistant with intelligent workflow guidance:

get_workflow_guidance

Parameters:

{
  "goal": "analyze new project and set up architectural documentation",
  "projectContext": "new_project",
  "availableAssets": ["codebase"],
  "timeframe": "thorough_review"
}

Result: Intelligent tool sequence recommendations and workflow guidance.

get_development_guidance

Parameters:

{
  "developmentPhase": "implementation",
  "adrsToImplement": ["ADR-001: API Design", "ADR-002: Database Schema"],
  "technologyStack": ["TypeScript", "React", "Node.js"],
  "teamContext": {"size": "small_team", "experienceLevel": "mixed"}
}

Result: Specific coding tasks, implementation patterns, and development roadmap.

Follow the workflow guidance to execute the recommended tool sequence for your specific goals.

1. get_workflow_guidance → 2. analyze_project_ecosystem → 3. get_architectural_context → 4. suggest_adrs → 5. get_development_guidance

1. get_workflow_guidance → 2. discover_existing_adrs (initializes cache) → 3. get_architectural_context → 4. generate_adr_todo → 5. get_development_guidance

1. get_workflow_guidance → 2. analyze_content_security → 3. generate_content_masking → 4. validate_content_masking

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/Users/username/my-react-app",
        "ADR_DIRECTORY": "docs/decisions",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "AI_TEMPERATURE": "0.1",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/Users/username/my-project",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-haiku",
        "AI_MAX_TOKENS": "2000",
        "AI_TEMPERATURE": "0.05"
      }
    }
  }
}

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/Users/username/my-project",
        "EXECUTION_MODE": "prompt-only",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

{
  "mcpServers": {
    "adr-analysis-frontend": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/Users/username/frontend-app",
        "ADR_DIRECTORY": "docs/adrs",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "openai/gpt-4o-mini",
        "LOG_LEVEL": "ERROR"
      }
    },
    "adr-analysis-backend": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/Users/username/backend-api",
        "ADR_DIRECTORY": "architecture/decisions",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "${workspaceFolder}",
        "ADR_DIRECTORY": "docs/adrs",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-haiku",
        "AI_CACHE_ENABLED": "true",
        "AI_CACHE_TTL": "1800",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Problem: "Command 'mcp-adr-analysis-server' not found" on RHEL systems

Root Cause: RHEL has specific npm global installation and PATH issues due to SELinux policies and default npm configuration.

Solution: Use the RHEL-specific installer:

curl -sSL https://raw.githubusercontent.com/tosin2013/mcp-adr-analysis-server/main/scripts/install-rhel.sh | bash

Manual Fix for RHEL:

# Fix npm prefix for user directory
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

# Add to PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Reinstall
npm install -g mcp-adr-analysis-server

RHEL MCP Configuration: If the command is still not found, use the npx approach:

{
  "mcpServers": {
    "adr-analysis": {
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "ADR_DIRECTORY": "docs/adrs",
        "LOG_LEVEL": "ERROR"
      }
    }
  }
}

Symptom: When calling tools like suggest_adrs, you receive large detailed instructions and prompts instead of actual ADR suggestions.

Root Cause: AI execution is not properly configured. The tool is falling back to prompt-only mode.

Solution: Add these required environment variables to your MCP configuration:

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet"
      }
    }
  }
}

Verification: After adding these variables and restarting, tools should return actual results like:

• suggest_adrs → Actual ADR suggestions with titles and reasoning
• analyze_project_ecosystem → Real technology analysis and recommendations
• generate_content_masking → Actual masked content, not masking instructions

Quick Diagnostic: Use the built-in diagnostic tool:

check_ai_execution_status

This will show exactly what's wrong with your configuration and provide step-by-step fix instructions.

Problem: "AI execution not available" errors

# Check execution mode
echo $EXECUTION_MODE

# Verify API key is set
echo $OPENROUTER_API_KEY | head -c 10

# Test AI connectivity
curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
     https://openrouter.ai/api/v1/models

Problem: "AI execution not available" errors

• ✅ Verify OPENROUTER_API_KEY is set correctly
• ✅ Check EXECUTION_MODE=full in environment
• ✅ Ensure API key has sufficient credits
• ✅ Verify network connectivity to OpenRouter

Problem: Slow AI responses

# Reduce token limits for faster responses
AI_MAX_TOKENS=2000
AI_TEMPERATURE=0.05

# Enable caching for repeated queries
AI_CACHE_ENABLED=true
AI_CACHE_TTL=3600

Problem: High API costs

# Use cost-effective models
AI_MODEL=anthropic/claude-3-haiku
# or
AI_MODEL=openai/gpt-4o-mini

# Reduce token usage
AI_MAX_TOKENS=2000
AI_TEMPERATURE=0.1

Check current configuration:

# View AI execution status
node -e "
const { getAIExecutionStatus } = require('./dist/utils/prompt-execution.js');
console.log(JSON.stringify(getAIExecutionStatus(), null, 2));
"

Reset configuration:

# Clear cache and restart
rm -rf .mcp-adr-cache
npm run build

• Automatic Secret Detection: Identifies API keys, passwords, and sensitive data
• Intelligent Masking: Context-aware content masking with configurable levels
• Security Validation: Comprehensive security checks and recommendations
• Compliance Tracking: Ensure adherence to security standards and best practices

• Local Processing: All analysis performed locally, no data sent to external services
• Configurable Masking: Customize masking rules for your organization's needs
• Audit Trail: Track all security-related actions and decisions
• Zero Trust: Assume all content may contain sensitive information

• Multi-level Caching: File system, memory, and analysis result caching
• Cache Invalidation: Smart cache invalidation based on file changes
• Performance Optimization: Optimized for large codebases and complex projects
• Resource Management: Efficient memory and CPU usage

• Incremental Analysis: Only analyze changed files and dependencies
• Parallel Processing: Multi-threaded analysis for large projects
• Memory Optimization: Efficient memory usage for large codebases
• Streaming Results: Stream analysis results for real-time feedback

We welcome contributions! This project follows strict development standards to ensure quality and security.

• TypeScript: Strict mode with comprehensive type checking
• Testing: >80% code coverage with Jest
• Linting: ESLint with security-focused rules
• Security: All contributions must pass security validation
• MCP Compliance: Strict adherence to Model Context Protocol specification

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run the full test suite
5. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

• Model Context Protocol Specification
• MCP Server Development Guide
• TypeScript MCP SDK

• MCP Servers Registry
• Awesome MCP Servers
• MCP Community Discord

• Implementation Progress
• Architecture Decisions
• NPM Publishing Guide

MIT License - see LICENSE file for details.

• 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.