How to Use the MCP ADR Analysis Server: AI-Powered Architectural Insights for Modern Development

Introduction

MCP ADR Analysis Server is a sophisticated Model Context Protocol (MCP) server designed to analyze Architectural Decision Records (ADRs) and provide deep architectural insights to AI agents. Unlike traditional tools, it returns actionable analysis results, not just prompts, making it a powerful addition to intelligent development workflows.

Table of Contents

• Key Features
• Installation
• Configuration & Setup
• Usage Examples
• Advanced Workflows
• Conclusion

Key Features

• AI-Powered Analysis: Immediate architectural insights with OpenRouter.ai integration
• Technology Detection: Identifies tech stacks and architectural patterns
• ADR Management: Generate, suggest, and maintain ADRs
• Security & Compliance: Detects and masks sensitive content automatically
• Workflow Automation: Todo generation, deployment tracking, and rule validation
• TDD Integration: Two-phase Test-Driven Development with ADR linking and validation
• Deployment Readiness: Zero-tolerance test validation and deployment history tracking

Installation

Install via NPM (Recommended):

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

Install from Source:

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

Configuration & Setup

To enable AI-powered execution, configure your environment variables:

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

For Claude Desktop integration, 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"
      }
    }
  }
}

Supported models include anthropic/claude-3-sonnet, anthropic/claude-3-haiku, openai/gpt-4o, and openai/gpt-4o-mini.

Usage Examples

Basic Project Analysis

// Analyze a 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"]
});

ADR Generation from Requirements

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

Enhanced TDD Workflow

// Phase 1: Generate comprehensive test specifications
const testPhase = await generateAdrTodo({
  adrDirectory: "docs/adrs",
  outputPath: "todo-tests.md",
  phase: "test",
  linkAdrs: true,
  includeRules: true
});

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

Security and Compliance

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

Advanced Workflows

• Deployment Readiness: Validate deployments with zero tolerance for test failures and track deployment history.
• Mock vs Production Detection: Distinguish between mock and production code for reliable validation.
• Rule Generation: Extract architectural rules from ADRs and code patterns for compliance.
• Multi-Project Support: Analyze and manage multiple projects with custom configurations.

Conclusion

The MCP ADR Analysis Server empowers AI assistants, developers, and enterprise architects with actionable architectural intelligence, advanced automation, and robust compliance features. Its prompt-driven, AI-powered approach transforms how teams manage architectural decisions and development workflows.

For more expert insights and tutorials on AI and automation, visit us at decisioncrafters.com.