MCP ADR Analysis Server

Overview

The MCP ADR Analysis Server is a specialized AI‑powered tool that bridges the gap between codebases and architectural decision records (ADRs). By leveraging the Model Context Protocol, it allows AI assistants—such as Claude, Cline, or Cursor—to query a project’s source tree and receive detailed architectural insights without leaving the assistant interface. The server performs deep static analysis using a Tree‑Sitter parser, then feeds the extracted structure to an OpenRouter.ai model that produces confidence‑scored recommendations, ADR drafts, and compliance checks.

Solving a Common Pain Point

In many development workflows, architects manually review code to surface implicit design decisions, then craft ADRs in a separate system. This manual loop is error‑prone and consumes valuable time. The ADR Analysis Server eliminates that friction by automating the extraction of architectural patterns, detecting security or compliance gaps, and generating ADR templates directly within the AI assistant’s chat. Teams no longer need to switch contexts or copy code snippets into separate tools; the server delivers actionable analysis in a single interaction.

What It Does and Why It Matters

• Tree‑Sitter AST Analysis: Parses source files into abstract syntax trees, enabling precise identification of components, services, and dependencies across languages.
• Technology & Pattern Detection: Recognizes frameworks, libraries, and architectural styles (e.g., micro‑services, event‑driven) without manual annotation.
• ADR Lifecycle Support: Generates new ADRs, suggests updates to existing records, and links relevant code files automatically.
• Security & Compliance Masking: Detects sensitive data (e.g., API keys, secrets) and masks them before they reach the AI model, safeguarding confidential information.
• Test‑Driven Development Validation: Implements a two‑phase TDD workflow, ensuring that new ADRs are backed by tests and that existing code meets test coverage thresholds.
• Deployment Readiness Checks: Enforces a zero‑tolerance policy on test failures, blocking deployments until all validation criteria are met.

These capabilities provide developers with immediate, trustworthy architectural feedback that can be incorporated into code reviews, continuous integration pipelines, or documentation workflows.

Real‑World Use Cases

• Rapid ADR Generation: A team working on a new micro‑service can ask the assistant to “Generate ADRs for this service” and receive a complete, formatted record with confidence scores.
• Code‑to‑ADR Mapping: When refactoring a legacy codebase, the server can map affected modules to existing ADRs, ensuring consistency and traceability.
• Security Audits: Before a release, the assistant can “Check for sensitive data leaks” and receive a masked report that highlights potential exposure points.
• CI/CD Integration: Embedding the server in a pipeline allows automated validation of ADR compliance and test coverage, preventing accidental architectural drift.
• Onboarding: New developers can query the assistant for an overview of the project’s architecture, receiving a concise summary and relevant ADRs without digging through documentation.

Integration with AI Workflows

The server is designed to be a first‑class MCP provider. Developers configure it once in their assistant’s client settings, pointing to the project root and supplying an OpenRouter API key. Subsequent queries—whether they are textual prompts or file‑based requests—are routed through the MCP protocol, and the server returns structured responses that can be rendered directly in the chat interface. Because it operates entirely within the assistant’s context, developers experience a seamless flow from code inspection to decision documentation, all powered by AI.

Unique Advantages

• Zero‑Code Dependency: No need to write custom scripts or plugins; the server exposes a ready‑to‑use MCP endpoint.
• High Confidence Scoring: Each analysis result includes a confidence metric, enabling teams to gauge reliability before acting on recommendations.
• Security‑First Design: Automatic content masking protects sensitive data, a critical feature for enterprise environments.
• Extensible Architecture: Built on TypeScript and Node.js, the server can be extended or integrated into other tooling ecosystems with minimal effort.

In summary, the MCP ADR Analysis Server transforms architectural decision making from a manual, siloed activity into an AI‑augmented, continuous process that delivers immediate, actionable insights directly within the developer’s preferred assistant.