ADR

The MCP ADR Analysis Server provides AI-powered architectural decision analysis and ADR management that plugs into your AI assistants to deliver actual analysis results, confidence scoring, and intelligent code linking for architectural work across projects.

How to use

You connect your MCP client to the server using a local, process-based endpoint. Run the server on your machine and configure your MCP client with a server entry that points to the local process. When you issue natural language requests through your MCP client, you receive concrete analysis results, suggested ADRs, and linked code contexts rather than prompts to submit elsewhere.

How to install

Prerequisites: you need Node.js 20 or higher and npm 9 or higher.

Install the MCP ADR Analysis Server globally so you can invoke it from any project:

npm install -g mcp-adr-analysis-server

If you prefer not to install globally, you can run it with npx for a one-off session:

npx mcp-adr-analysis-server

From source for development or customization, clone the repository, install dependencies, and build before running the server:

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

If you are on RHEL 9/10, use the special installer script to set up the server and its runtime environment:

curl -sSL https://raw.githubusercontent.com/tosin2013/mcp-adr-analysis-server/main/scripts/install-rhel.sh | bash

Additional setup you will likely configure

Prepare basic client configuration to connect to the local MCP server. The server runs as a process and exposes an internal MCP endpoint for your client to communicate with. You will provide the server command and environment variables through your MCP client’s server configuration.

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

If you also want optional ADR governance and cross-repo features, configure the ADR Aggregator alongside the base server by adding the ADR Aggregator API key in the environment for the same server or a separate one as needed.

{
  "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"
      }
    }
  }
}

Configuration and security notes

The server supports two operational modes: full mode with API key access to actual analysis results and prompt-only mode without an API key. Use full mode for production automation and prompt-only mode for exploration.

You can enable or disable advanced features such as ADR aggregation, smart code linking, and knowledge graph integration through environment variables and client configuration. When you enable features that contact external services, ensure you protect your API keys and follow your organization’s security policy.

Execution modes and usage patterns

Full Mode requires an API key and returns authentic analysis outputs along with confidence scores. Prompt-Only Mode does not require an API key and returns analysis prompts that you can paste into a chat or another tool. Start with Prompt-Only Mode to explore the tool catalog, and switch to Full Mode when you’re ready to run analyses with confidence scoring.

Troubleshooting

Common issues include making sure the local server is running before your MCP client connects, installing dependencies when asked to build native modules, and ensuring your environment variables are set correctly. If you encounter a module not found error after cloning the repository, run npm install and then npm run build.

Security & performance

The server automatically masks sensitive content, processes data locally, and applies multi-level caching and incremental analysis to optimize performance while preserving security.

Developer and contributor notes

If you are developing or testing, you can run the test suite with npm test and generate coverage reports with npm run test:coverage to verify quality and maintain high test coverage.

Available tools

analyzeProjectEcosystem

Performs a comprehensive analysis of the project's tech stack and architecture to surface insights and patterns.

generateAdrsFromPrd

Generates Architectural Decision Records from product requirements documents or similar sources.

findRelatedCode

Finds code files related to ADR decisions using AI-driven keyword extraction and semantic search.

sync_to_aggregator

Push local ADRs to the cross-team ADR Aggregator platform for governance.

get_adr_context

Retrieves ADR context from the aggregation platform for context-aware analysis.

get_staleness_report

Provides governance reports showing ADR freshness and compliance status.

get_adr_templates

Fetches domain-specific ADR templates for standardized documentation.

get_adr_diagrams

Obtains Mermaid diagrams that illustrate ADR relationships and dependencies.

validate_adr_compliance

Checks ADR implementations against governance rules and best practices.

get_knowledge_graph

Accesses a cross-repository knowledge graph linking ADRs, code, and decisions.