io.github.tosin2013/mcp-adr-analysis-server

Official

by tosin2013 · TypeScript

AI-powered MCP server for analyzing Architectural Decision Records (ADRs).

Analyze Architectural Decision Records (ADRs) with AI-powered insights.

Topics

adrarchitectural-decision-recordsmcp-serverai-agentsarchitectureclaudecursortypescript

README.md22 KBView on GitHub

MCP (Model Context Protocol) ADR (Architectural Decision Record) Analysis Server

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

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables seamless integration between AI assistants and external tools and data sources. Think of it as a universal adapter that lets AI assistants like Claude, Cline, and Cursor connect to specialized analysis servers. This server enhances AI assistants with deep architectural analysis capabilities, enabling intelligent code generation, decision tracking, and development workflow automation.

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

<details> <summary>Key Terms</summary>

Term	Definition
ADR	Architectural Decision Record — A document that captures an important architectural decision along with its context, alternatives considered, and consequences.
MCP	Model Context Protocol — An open standard enabling AI assistants to connect to external tools and data sources.
Tree-sitter	An incremental parsing library that provides AST (Abstract Syntax Tree) analysis for 50+ languages. Used for semantic code understanding, extracting function signatures, and identifying architectural patterns.
Knowledge Graph	A graph database maintained by the server that tracks relationships between ADRs, code implementations, and architectural decisions. Enables intelligent code linking and impact analysis.
Smart Code Linking	AI-powered discovery of code files related to ADRs and architectural decisions, using keyword extraction and semantic search.
Firecrawl	Web page extraction/search service used by optional research tools (`FIRECRAWL_API_KEY`).
ADR Aggregator	Optional SaaS integration for syncing and sharing ADR context across teams (`ADR_AGGREGATOR_API_KEY`).

</details>

Author: Tosin Akinosho | Repository: GitHub

✨ 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 → · 📜 Release policy → · 🗒️ Changelog →

Prerequisites

Before installing, verify you have:

bash

node --version  # Should show v20.0.0 or higher
npm --version   # Should show 9.0.0 or higher (included with Node.js 20+)

Required:

Node.js 20.0.0 or higher — Download or use nvm/fnm
npm 9.0.0 or higher (included with Node.js 20+)
An MCP-compatible client — Claude Desktop, Cline, Cursor, or Windsurf

Network Requirements

Internet access required during npm install for native module compilation (tree-sitter incremental code parsers for YAML and TypeScript)
If behind a corporate proxy, set HTTP_PROXY and HTTPS_PROXY environment variables
Offline fallback: If native builds fail, the server operates in reduced mode without tree-sitter code analysis

📦 Quick Installation

bash

# 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: From source (for development or customization)
git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
cd mcp-adr-analysis-server && npm install && npm run build

# Option 4: RHEL 9/10 systems (special installer)
curl -sSL https://raw.githubusercontent.com/tosin2013/mcp-adr-analysis-server/main/scripts/install-rhel.sh | bash

Note: When installing from source, npm run build is required before running the server since the bin entry points to ./dist/src/index.js.

📖 Detailed Installation Guide → | RHEL Setup →

⚡ Quick Setup (3 Steps)

Get API Key: Sign up at OpenRouter.ai/keys — OpenRouter is an API gateway that provides access to multiple AI models (Claude, GPT, etc.) through a single key. No API key? The server still works in prompt-only mode — see Execution Modes below.
Set Environment: OPENROUTER_API_KEY=your_key + EXECUTION_MODE=full
Configure Client: Add to Claude Desktop, Cline, Cursor, or Windsurf

json

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full"
      }
    }
  }
}

Claude Desktop users: Save this JSON to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

<details> <summary>Config locations for other clients</summary>

Client	Config file location
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cline (VS Code)	VS Code Settings → Cline → MCP Servers (or `.vscode/cline_mcp_settings.json`)
Cursor	Cursor Settings → MCP → Add Server

</details> <details> <summary>With ADR Aggregator (Optional)</summary>

json

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "ADR_AGGREGATOR_API_KEY": "agg_your_key_here"
      }
    }
  }
}

Get your API key at adraggregator.com

</details>

📖 Full Configuration Guide → | Client Setup →

Execution Modes

	Full Mode	Prompt-Only Mode
Requires API key?	Yes (`OPENROUTER_API_KEY`)	No
Returns	Actual analysis results with confidence scores	Prompts you can paste into any AI chat
Set via	`EXECUTION_MODE=full`	`EXECUTION_MODE=prompt-only` (default)
Best for	Production use, automation	Trying it out, no-cost exploration
Available Features	All 73 tools, AI analysis, confidence scoring, Smart Code Linking, Knowledge Graph	Analysis prompts, templates, local file operations, ADR discovery
Unavailable Features	—	AI execution, confidence scores, Smart Code Linking, web research

Tip: Start with prompt-only mode to explore the tool catalog — you can analyze projects, discover ADRs, and generate templates without an API key. Add an API key when you're ready for AI-powered analysis with confidence scoring.

🚀 Usage Examples

Just ask your MCP client in natural language — no code required:

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

<details> <summary>Programmatic Usage (Advanced)</summary>

If you're integrating the server into your own tooling via the MCP SDK:

typescript

// 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
  }
);

</details>

📖 Complete Usage Guide → | API Reference →

Try it out: This repo includes a sample-project/ directory with example ADRs and source code. Point PROJECT_PATH at it to experiment without affecting your own codebase.

Note: The sample project is only available when cloning from source (Option 3 above). If you installed via npm (Option 1 or 2), create your own test project or clone the repo separately to access the sample: git clone --depth 1 https://github.com/tosin2013/mcp-adr-analysis-server.git sample-test

🎯 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 recursive text search) + fast-glob (file matching) • AI Integration: OpenRouter.ai • Web Research: Firecrawl (web page extraction API) • Code Analysis: tree-sitter (incremental code parser) + Smart Code Linking

📖 Technical Details → | CE-MCP Migration Playbook →

📁 Project Structure

code

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

📖 Full Structure →

🧪 Testing

bash

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

📖 Testing Guide →

🔥 Firecrawl Integration (Optional — Skip for Getting Started)

Enhanced web research capabilities for comprehensive architectural analysis.

Note: You don't need Firecrawl for basic ADR analysis. The server works fully without it. Only configure Firecrawl if you need web research features like the perform_research tool with external sources.

<details> <summary>When is Firecrawl useful?</summary>

ADR research — automatically pull best practices from official docs when generating ADRs
Technology evaluation — compare frameworks by crawling their documentation and changelogs
Security audits — check CVE databases and security advisories for your dependencies
Migration planning — gather migration guides and breaking-change notes from upstream projects

</details>

bash

# 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)

📖 Firecrawl Setup Guide →

🌐 ADR Aggregator Integration (Optional)

ADR Aggregator is a platform for cross-team ADR visibility and governance. It provides:

Cross-repository knowledge graphs — See how architectural decisions relate across projects
Governance dashboards — Track ADR compliance, staleness, and review cycles
Template library — Access domain-specific ADR templates (security, API, database, etc.)
Team collaboration — Share architectural decisions organization-wide

Note: ADR Aggregator is optional. All core analysis features work without it.

bash

# Set your API key (get one at adraggregator.com)
export ADR_AGGREGATOR_API_KEY="agg_your_key_here"

Available Tools

Tool	Description	Free	Pro+	Team
`sync_to_aggregator`	Push local ADRs to platform	✅	✅	✅
`get_adr_context`	Pull ADR context from platform	✅	✅	✅
`get_staleness_report`	Get ADR governance/health reports	✅	✅	✅
`get_adr_templates`	Retrieve domain-specific templates	✅	✅	✅
`get_adr_diagrams`	Get Mermaid diagrams for ADRs	—	✅	✅
`validate_adr_compliance`	Validate ADR implementation	—	✅	✅
`get_knowledge_graph`	Cross-repository knowledge graph	—	—	✅

Workflow for New Repos

bash

# 1. Analyze codebase for implicit architectural decisions
suggest_adrs(analysisType: 'implicit_decisions')

# 2. Generate ADR files from suggestions
generate_adr_from_decision(decisionData)

# 3. Save ADRs to docs/adrs/

# 4. (Optional) Sync to adraggregator.com
sync_to_aggregator(full_sync: true)

Benefits: Cross-team visibility • Staleness alerts • Compliance tracking • Organization-wide knowledge graph

📖 ADR Aggregator Guide → | 📖 MCP Integration Guide →

🔧 Development

bash

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

Viewing Documentation Locally

API documentation is generated with TypeDoc:

bash

npm install          # Required once after cloning (installs typedoc)
npm run docs:build   # Generate API docs into docs/api/
npm run docs:serve   # Serve locally via Python HTTP server

Then open http://localhost:8080 in your browser. Markdown documentation lives in docs/ and can be browsed directly on GitHub.

📖 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

Fork the repository
Clone your fork: git clone https://github.com/YOUR_USERNAME/mcp-adr-analysis-server.git
Create a branch: git checkout -b feature/your-feature-name
Make your changes with tests
Test: npm test (maintain >80% coverage)
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.

Install

Configuration

Environment variables

PROJECT_PATH

Path to the project directory to analyze (defaults to current directory)

OPENROUTER_API_KEYsecret

OpenRouter API key for AI-powered analysis (required for full execution mode)

EXECUTION_MODE

Execution mode: 'full' for AI results or 'prompt-only' for prompts (default: prompt-only)

ADR_DIRECTORY

ADR directory relative to project path (default: docs/adrs)

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-adr-analysis-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-adr-analysis-server@2.6.9"
      ],
      "env": {
        "PROJECT_PATH": "<YOUR_PROJECT_PATH>",
        "OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>",
        "EXECUTION_MODE": "<YOUR_EXECUTION_MODE>",
        "ADR_DIRECTORY": "<YOUR_ADR_DIRECTORY>"
      }
    }
  }
}