AD
Security

ADR Analysis MCP Server: AI Architectural Insights

Analyze ADRs with the MCP server to gain AI-driven architectural insights, detect tech stacks, run security checks, and streamline TDD workflows.

View on GitHub
Quick Install
npx -y @tosin2013/mcp-adr-analysis-server

Overview

The MCP (Model Context Protocol) ADR Analysis Server processes Architectural Decision Records (ADRs) and returns structured, AI-driven insights about architecture choices. It combines automated natural language analysis with lightweight tooling to detect technology stacks, summarize decisions, highlight security concerns, and suggest test-driven development (TDD) steps based on each ADR. The server is designed to help engineering teams reason about architecture history, speed onboarding, and integrate automated checks into CI/CD pipelines.

Because ADRs are human-written artifacts that vary in style and granularity, the MCP server standardizes analysis using a model-driven protocol. This enables consistent outputs (summaries, risk flags, recommended tests) that can be consumed by other tools or surfaced in pull requests, issue trackers, or docs sites.

Features

  • AI-powered ADR summarization and rationale extraction
  • Automatic detection of referenced tech stacks, libraries, and frameworks
  • Security-oriented checks and flagged risks (e.g., insecure defaults, deprecated components)
  • TDD workflow suggestions: example tests, test targets, and test priorities
  • REST API endpoints and optional CLI for integration into tooling and CI
  • Local or containerized deployment for privacy/compliance
  • Configurable model and analysis options via environment variables

Installation / Configuration

Clone the repository and run locally or with Docker. Below are common setup options.

  1. Clone and run locally (Node.js example)
git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
cd mcp-adr-analysis-server
# install dependencies (example using npm)
npm install
# set env variables, then start
export OPENAI_API_KEY="sk-..."   # or your model provider key
export PORT=3000
npm run dev
  1. Docker (recommended for CI or isolated environments)
# build image
docker build -t mcp-adr-server .

# run container
docker run -e OPENAI_API_KEY="sk-..." -p 3000:3000 mcp-adr-server
  1. Example .env file
OPENAI_API_KEY=sk-...
PORT=3000
MODEL=gpt-4o-mini
MAX_TOKENS=1024
SECURITY_CHECK_LEVEL=medium   # low | medium | high

Configuration notes:

  • OPENAI_API_KEY (or equivalent) is required for model-driven analysis.
  • MODEL controls which model/provider the server uses.
  • SECURITY_CHECK_LEVEL adjusts strictness and depth of security heuristics.

Available Tools / Resources

The server typically exposes modular analysis “tools” that can be invoked independently or as a pipeline:

  • adr-summarizer: Condenses an ADR into a short rationale and decision summary.
  • tech-detector: Identifies tech stacks, languages, frameworks, versions, and common libraries referenced in the ADR.
  • security-checker: Runs static heuristics and model-guided checks to flag potential security concerns.
  • tdd-helper: Produces test ideas, sample test cases, and suggested testing scope for TDD workflows.
  • diff/explain: Compares two ADRs or revisions and highlights changes in rationale, trade-offs, or risks.

These tools are available through REST endpoints and can be composed by clients.

API: Example Usage

Example request to analyze an ADR (replace host/port as needed):

curl -X POST http://localhost:3000/api/v1/adr/analyze \
  -H "Content-Type: application/json" \
  -d '{"title":"Use PostgreSQL for primary datastore","body":"We chose Postgres because..."}'

Typical JSON response structure:

{
  "summary": "Use PostgreSQL as the primary relational datastore for consistency...",
  "tech_stack": ["PostgreSQL", "Node.js", "TypeORM"],
  "security_flags": [
    {"severity":"medium","message":"Connection credentials not rotated periodically"},
    {"severity":"low","message":"No backup/restore cadence specified"}
  ],
  "tdd_suggestions": [
    {"area":"migrations","tests":["rollback tests","schema integrity tests"]},
    {"area":"connection","tests":["connection pooling failure tests"]}
  ]
}

Use Cases

  • Architecture review automation: Run ADRs through the server in CI to produce a report of potential regressions or security flags before merging.
  • Onboarding and documentation: Generate concise summaries and tech stack overviews from ADRs to help new team members understand historical decisions faster.
  • Security audits: Aggregate security flags across ADRs to prioritize architectural hardening work (e.g., credential management, transport-level encryption).
  • TDD-First development: Use generated TDD suggestions to create initial test suites tied to the architectural decision, ensuring design constraints are verified.
  • Pull request integrations: Surface ADR analysis in PR comments or checks to enforce documentation quality and highlight risky design changes.

Security & Operational Considerations

  • Keep model API keys and ADR content private; prefer running the server inside your network or on CI runners for sensitive repositories.
  • Tune SECURITY_CHECK_LEVEL to balance false positives/negatives in automated scanning.
  • Review generated recommendations manually—AI outputs should assist, not replace, security engineering review.
  • Log retention and access controls: ensure ADR analysis logs do not leak sensitive design details.

For full source, configuration options, and advanced integrations (webhooks, CLI flags, or MCP protocol specifics), see the project repository: https://github.com/tosin2013/mcp-adr-analysis-server.

Tags:security