A
securityA
licenseA
qualityFacilitates comprehensive architectural design and evaluation through specialized agents, rich resources, and powerful tools covering diverse architectural domains, including cloud, AI, and blockchain.
This MCP server provides AI-powered architectural analysis and automated development workflows for comprehensive project management.
Core Capabilities: • Architectural Analysis - Perform recursive project ecosystem analysis, technology stack detection, and generate architectural insights using OpenRouter.ai integration • ADR Management - Generate, suggest, discover, and manage Architectural Decision Records from PRDs, code changes, or project context • Enhanced TDD Workflows - Create two-phase Test-Driven Development tasks from ADRs, linking tests and production code with dependency tracking • Security & Compliance - Detect and mask sensitive content, configure custom security patterns, validate architectural rules, and ensure compliance • Deployment Readiness - Perform zero-tolerance validation, track deployment history, generate environment-specific guidance, and hard-block unsafe deployments • Smart Git Operations - AI-driven, security-focused git pushes with integrated deployment readiness checks and credential detection • Research Integration - Generate context-aware research questions and incorporate findings into architectural decisions • Project Health Scoring - Central coordination system for calculating health metrics across task completion, deployment readiness, and security posture • Workflow Automation - Generate intelligent development guidance, recommend tool sequences, and translate architectural decisions into actionable coding tasks • Content Management - Read, write, and list files and directories with multi-level caching for performance optimization • Failure Analysis - Structured troubleshooting with test plan generation and guided workflow analysis
Provides GitHub integration for repository management, including smart git push operations with deployment readiness validation and GitHub Actions CI/CD automation
Enables automated testing, building, and publishing workflows through GitHub Actions integration for continuous integration and deployment
Integrates with OpenAI's GPT models via OpenRouter for AI-powered architectural analysis, providing intelligent code generation, decision tracking, and development workflow automation
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
📦 Quick Installation
# Global installation (recommended)
npm install -g mcp-adr-analysis-server
# 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)
Get API Key: OpenRouter.ai/keys
Set Environment:
OPENROUTER_API_KEY=your_key+EXECUTION_MODE=fullConfigure 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
🛠️ 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
📁 Project Structure
src/tools/ # 23 MCP tools for analysis
docs/adrs/ # Architectural Decision Records
tests/ # >80% test coverage
.github/ # CI/CD automation
🧪 Testing
npm test # Run all tests (>80% coverage)
npm run test:coverage # Coverage report
🔥 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
🔧 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 keyModule not found: Run
npm install && npm run buildPermission 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 →
🤝 Contributing
We welcome contributions! Fork → Create branch → Add tests → Submit PR
Standards: TypeScript strict • >80% coverage • ESLint • Security validation • MCP compliance
🔗 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
Empowering AI assistants with deep architectural intelligence and decision-making capabilities.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
Transform your codebase into professional architectural decision records with intelligent AI analysis
Related MCP Servers
- -securityFlicense-qualityAnalyzes codebases to generate dependency graphs and architectural insights across multiple programming languages, helping developers understand code structure and validate against architectural rules.Last updated -6914
- -security-license-qualityEnables AI assistants like Claude to interact with Autodesk Construction Cloud Build platform for construction project management, including issues tracking, RFIs, submittals, and document management through natural language.Last updated -
- -securityAlicense-qualityA sophisticated server that enables AI assistants to automatically analyze codebases and generate comprehensive, professional documentation.Last updated -1MIT License