mcp-adr-analysis-server

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

[![GitHub](https://img.shields.io/badge/github-tosin2013/mcp--adr--analysis--server-blue.svg?style=flat&logo=github)](https://github.com/tosin2013/mcp-adr-analysis-server)
[![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
[![NPM Version](https://img.shields.io/npm/v/mcp-adr-analysis-server)](https://www.npmjs.com/package/mcp-adr-analysis-server)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue)](https://www.typescriptlang.org/)
[![Good First Issues](https://img.shields.io/github/issues/tosin2013/mcp-adr-analysis-server/good%20first%20issue?label=good%20first%20issues&color=7057ff)](https://github.com/tosin2013/mcp-adr-analysis-server/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)

> **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><b>Key Terms</b></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](https://github.com/tosin2013) | **Repository**: [GitHub](https://github.com/tosin2013/mcp-adr-analysis-server.git)

## ✨ 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 →](docs/explanation/index.md)** · 📜 **[Release policy →](RELEASES.md)** · 🗒️ **[Changelog →](CHANGELOG.md)**

## 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](https://nodejs.org/) or use [nvm](https://github.com/nvm-sh/nvm)/[fnm](https://github.com/Schniz/fnm)
- **npm 9.0.0 or higher** (included with Node.js 20+)
- **An MCP-compatible client** — [Claude Desktop](https://claude.ai/download), [Cline](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev), [Cursor](https://cursor.sh/), or [Windsurf](https://codeium.com/windsurf)

### Network Requirements

- **Internet access required** during `npm install` for native module compilation ([tree-sitter](https://tree-sitter.github.io/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 →](docs/tutorials/01-first-steps.md)** | **[RHEL Setup →](scripts/install-rhel.sh)**

## ⚡ Quick Setup (3 Steps)

1. **Get API Key**: Sign up at [OpenRouter.ai/keys](https://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](#execution-modes) below._
2. **Set Environment**: `OPENROUTER_API_KEY=your_key` + `EXECUTION_MODE=full`
3. **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><b>Config locations for other clients</b></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><b>With ADR Aggregator (Optional)</b></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](https://adraggregator.com)

</details>

📖 **[Full Configuration Guide →](docs/reference/mcp-client-config.md)** | **[Client Setup →](docs/reference/environment-config.md)**

### Execution Modes

|                          | **Full Mode**                                                                      | **Prompt-Only Mode**                                              |
| ------------------------ | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Requires API key?**    | Yes (`OPENROUTER_API_KEY`)                                                         | No                                                                |
| **Returns**              | Actual a