mcp-adr-analysis

This MCP ADR Analysis Server provides AI-powered architectural decision analysis and ADR management. It integrates with OpenRouter to fetch AI capabilities and can perform tree-sitter-based code analysis, security masking, and knowledge-graph-backed tracing of ADRs to implementations. To use it, configure a client (Claude Desktop, Cline, Cursor, Windsurf, or other MCP-compatible clients) with the server's MCP configuration, including your API key for OpenRouter. Start the server using the mcp-adr-analysis-server CLI and point your client to the configured mcpServers entry. The server supports ADR creation, suggestions, and maintenance, along with smart code linking to surface related files and patterns across a codebase. Ensure your environment variables are set (PROJECT_PATH, OPENROUTER_API_KEY, EXECUTION_MODE) so the server can access your project, authenticate with the API gateway, and run in the desired execution mode (full or prompt-only).

Key capabilities include: AI-powered architectural analysis via OpenRouter integration, automatic technology detection, ADR generation and management, smart code linking to find related files, security and compliance masking of sensitive content, test-driven development (TDD) workflow integration, and deployment-readiness validation with hard checks. To get started, obtain an API key from OpenRouter, set the environment, and configure your MCP client with the provided server entry.

Prerequisites:

• Node.js 20.0.0 or higher
• npm 9.0.0 or higher (comes with Node.js 20+)
• An MCP-compatible client (Claude Desktop, Cline, Cursor, Windsurf) or a compatible environment

Step-by-step installation:

1. Global installation (recommended for frequent use) npm install -g mcp-adr-analysis-server

2. Use npx (no installation required) npx mcp-adr-analysis-server

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

4. RHEL 9/10 setup (optional) 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.

Tips and common issues:

• Ensure you have Internet access during npm install for native module compilation (e.g., tree-sitter addons). If behind a proxy, set HTTP_PROXY and HTTPS_PROXY environment variables.
• If native builds fail, the server operates in reduced mode without tree-sitter code analysis.
• Store your OpenRouter API key securely; do not commit it to public repositories.
• The config file example shows how to wire the MCP server into a client; adjust PROJECT_PATH to your project root and provide a valid OPENROUTER_API_KEY.
• If you need offline or reduced capabilities, you can run with EXECUTION_MODE set to a non-full mode as documented by the project.