mcp-adr-analysis-server
Advanced tools
MCP server for analyzing Architectural Decision Records and project architecture
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
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.
OPENROUTER_API_KEY=your_openrouter_api_key_here
EXECUTION_MODE=full
AI_MODEL=anthropic/claude-3-sonnet
OPENROUTER_API_KEY (Required for AI): OpenRouter API key from https://openrouter.ai/keysEXECUTION_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 analyzeADR_DIRECTORY (Optional): Directory containing ADR files (default: docs/adrs)LOG_LEVEL (Optional): Logging level (DEBUG, INFO, WARN, ERROR)| Model | Provider | Use Case | Input Cost | Output Cost |
|---|---|---|---|---|
anthropic/claude-3-sonnet | Anthropic | Analysis, reasoning | $3.00/1K | $15.00/1K |
anthropic/claude-3-haiku | Anthropic | Quick tasks | $0.25/1K | $1.25/1K |
openai/gpt-4o | OpenAI | Versatile analysis | $5.00/1K | $15.00/1K |
openai/gpt-4o-mini | OpenAI | Cost-effective | $0.15/1K | $0.60/1K |
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
Enhance chatbots and business agents with architectural intelligence
Enable autonomous agents to understand and work with complex architectures
Support enterprise architects and development teams
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
# 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
npm install -g mcp-adr-analysis-server{
"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"
}
}
}
}
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.
get_workflow_guidance โ 2. analyze_project_ecosystem โ 3. get_architectural_context โ 4. suggest_adrs โ 5. get_development_guidanceget_workflow_guidance โ 2. discover_existing_adrs (initializes cache) โ 3. get_architectural_context โ 4. generate_adr_todo โ 5. get_development_guidanceget_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"
}
}
}
}
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 reasoninganalyze_project_ecosystem โ Real technology analysis and recommendationsgenerate_content_masking โ Actual masked content, not masking instructionsQuick 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
OPENROUTER_API_KEY is set correctlyEXECUTION_MODE=full in environmentProblem: 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
| Issue | Solution |
|---|---|
| "Module not found" errors | Run npm install && npm run build |
| TypeScript compilation errors | Check Node.js version >= 18.0.0 |
| Permission denied | Check file permissions and project path |
| API rate limits | Reduce AI_MAX_TOKENS or increase AI_TIMEOUT |
| Cache issues | Clear cache with rm -rf .mcp-adr-cache |
We welcome contributions! This project follows strict development standards to ensure quality and security.
See CONTRIBUTING.md for detailed guidelines.
MIT License - see LICENSE file for details.
Built with โค๏ธ by Tosin Akinosho for AI-driven architectural analysis
Empowering AI assistants with deep architectural intelligence and decision-making capabilities.
FAQs
MCP server for analyzing Architectural Decision Records and project architecture
The npm package mcp-adr-analysis-server receives a total of 35 weekly downloads. As such, mcp-adr-analysis-server popularity was classified as not popular.
We found that mcp-adr-analysis-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.ย It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Four npm packages disguised as cryptographic tools steal developer credentials and send them to attacker-controlled Telegram infrastructure.
Security News
Ruby maintainers from Bundler and rbenv teams are building rv to bring Python uv's speed and unified tooling approach to Ruby development.
Security News
Following last weekโs supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.