ADR Aggregator Integration Guide

This guide explains how to integrate the MCP ADR Analysis Server with ADR Aggregator for centralized ADR management, cross-repository insights, and team collaboration.

Overview

ADR Aggregator provides a cloud platform for managing Architectural Decision Records (ADRs) across multiple repositories. The integration enables:

Centralized ADR management - View and manage ADRs from all repositories in one dashboard
Staleness tracking - Automatic detection of stale ADRs requiring review
Gap analysis - Identify missing documentation and code-ADR mismatches
Cross-repository insights - Discover patterns and relationships across projects (Team tier)
Compliance validation - Ensure ADRs are properly implemented (Pro+ tier)

Prerequisites

Before you begin, ensure you have:

MCP ADR Analysis Server installed (npm install -g @tosin2013/mcp-adr-analysis-server)
Git repository initialized in your project
ADR Aggregator account at adraggregator.com

Setup

Step 1: Get Your API Key

Sign up or log in at adraggregator.com
Navigate to Settings > API Keys
Click Generate New Key
Copy your API key (you won't be able to see it again)

Step 2: Configure Environment Variables

Set the API key in your environment:

# Linux/macOS
export ADR_AGGREGATOR_API_KEY="your-api-key-here"

# Windows PowerShell
$env:ADR_AGGREGATOR_API_KEY = "your-api-key-here"

# In .env file (recommended for projects)
ADR_AGGREGATOR_API_KEY=your-api-key-here

Step 3: Verify Configuration

Run the MCP server and test the connection:

# Start the MCP server
mcp-adr-analysis-server

# In your MCP client, call get_adr_templates (no auth required)
# This verifies basic connectivity

Tier Features

ADR Aggregator offers three tiers with different capabilities:

Feature	Free	Pro+	Team
ADR Sync	10 ADRs	Unlimited	Unlimited
Staleness Reports	✅	✅	✅
Templates	✅	✅	✅
Gap Analysis	✅	✅	✅
Priority Tracking	✅	✅	✅
Mermaid Diagrams	❌	✅	✅
Compliance Validation	❌	✅	✅
Implementation Status	❌	✅	✅
Knowledge Graph	❌	❌	✅
Cross-repo Patterns	❌	❌	✅
Organization Scope	❌	❌	✅

Common Workflows

Workflow 1: Initial ADR Sync

Sync your existing ADRs to the aggregator platform:

// Tool: sync_to_aggregator
{
  "full_sync": true,
  "include_metadata": true,
  "include_timeline": true
}

What happens:

Tool auto-detects repository from git remote
Scans docs/adrs/ directory for ADR files
Parses ADR content and extracts metadata
Uploads to ADR Aggregator platform

Workflow 2: Pull ADR Context for AI Analysis

Get enriched ADR context for AI-assisted decision making:

// Tool: get_adr_context
{
  "include_timeline": true,
  "staleness_filter": "all"
}

Use cases:

Inform AI about existing architectural decisions
Check if similar decisions already exist
Get staleness information for each ADR

Workflow 3: Check ADR Staleness

Generate a staleness report for governance:

// Tool: get_staleness_report
{
  "threshold": 90
}

Response includes:

Fresh/Recent/Stale/Very Stale counts
Review cycle compliance percentage
List of stale ADRs with recommended actions

Workflow 4: Analyze Code-ADR Gaps

Detect mismatches between ADRs and codebase:

// Tool: analyze_gaps
{
  "reportToAggregator": true,
  "scanDirectories": ["src", "lib"]
}

Gap types detected:

ADR-to-Code: File references in ADRs that don't exist
Code-to-ADR: Technologies in code without ADR coverage
- Databases (PostgreSQL, MongoDB, Redis)
- Authentication (Passport, JWT, OAuth)
- Cloud providers (AWS, GCP, Azure)
- Frameworks (React, Vue, Angular)
- Patterns (Microservices, CQRS, Event Sourcing)

Workflow 5: Track Implementation Progress (Pro+)

Update implementation status of ADRs:

// Tool: update_implementation_status
{
  "updates": [
    {
      "adr_path": "docs/adrs/001-use-typescript.md",
      "implementation_status": "implemented",
      "notes": "Migration completed in v2.0"
    },
    {
      "adr_path": "docs/adrs/002-api-design.md",
      "implementation_status": "in_progress"
    }
  ]
}

Valid status values:

not_started - Implementation has not begun
in_progress - Implementation is underway
implemented - Decision fully implemented
deprecated - Decision no longer relevant
blocked - Implementation blocked

Workflow 6: Prioritize ADRs for Roadmap

Get prioritized list of ADRs for planning:

// Tool: get_adr_priorities
{
  "include_ai": true
}

Response includes:

Priority scores (0-100)
Dependencies between ADRs
Blockers preventing implementation
Gap counts per ADR
AI-enhanced prioritization (when enabled)

Workflow 7: Cross-Repository Knowledge Graph (Team)

Discover patterns across your organization's repositories:

// Tool: get_knowledge_graph
{
  "scope": "organization",
  "include_analytics": true
}

Insights provided:

Most connected ADRs across repos
Orphan decisions (no links)
Pattern trends over time
Cross-repository patterns

CI/CD Integration

GitHub Actions Example

name: ADR Sync

on:
  push:
    paths:
      - 'docs/adrs/**'
  workflow_dispatch:

jobs:
  sync-adrs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install MCP ADR Server
        run: npm install -g @tosin2013/mcp-adr-analysis-server

      - name: Sync ADRs to Aggregator
        env:
          ADR_AGGREGATOR_API_KEY: ${{ secrets.ADR_AGGREGATOR_API_KEY }}
        run: |
          # Use the MCP server in standalone mode
          mcp-adr-analysis-server --tool sync_to_aggregator --args '{"include_metadata": true}'

Pre-commit Hook

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: analyze-adr-gaps
        name: Analyze ADR Gaps
        entry: bash -c 'npx mcp-adr-analysis-server --tool analyze_gaps --args "{}"'
        language: system
        pass_filenames: false
        files: ^(docs/adrs/|src/)

Troubleshooting

Error: "ADR Aggregator API key not configured"

Solution: Set the ADR_AGGREGATOR_API_KEY environment variable:

export ADR_AGGREGATOR_API_KEY="your-key"

Error: "Not a git repository"

Solution: Initialize git and add a remote:

git init
git remote add origin https://github.com/owner/repo.git

Error: "This feature requires Pro+ tier"

Solution: Upgrade your ADR Aggregator subscription at adraggregator.com/pricing

Error: "Repository not found"

Solution: Sync your ADRs first:

// Tool: sync_to_aggregator
{ "full_sync": true }

Error: "Request timed out"

Solution: Check your internet connection or try again. The default timeout is 30 seconds.

API Reference

For complete API documentation, see:

API Reference - ADR Aggregator Tools

Best Practices

1. Sync Regularly

Set up automated sync in CI/CD to keep ADR Aggregator updated:

Trigger sync on ADR file changes
Run weekly full sync to ensure consistency

2. Address Gaps Promptly

When gap analysis detects missing ADRs:

Review the suggested ADR title
Create the ADR using templates from get_adr_templates
Re-run gap analysis to verify

3. Track Implementation Status

Keep implementation status updated to:

Enable accurate priority calculations
Identify blocked decisions early
Measure architectural debt

4. Use Staleness Thresholds

Configure appropriate staleness thresholds:

90 days (default): Standard review cycle
30 days: Fast-moving projects
180 days: Stable systems with infrequent changes

5. Leverage Cross-Repo Insights (Team)

For organizations with multiple repositories:

Use knowledge graph to identify common patterns
Share successful ADRs across teams
Detect architectural inconsistencies

Endpoint and Tool Reference

The MCP tool names and API endpoints in this server are aligned with the official ADR Aggregator MCP Guide. A mapping parity test enforces that every documented endpoint has a corresponding MCP tool, client method, and handler.

The default API base URL is https://jvgdaquuggzbkenxnkja.supabase.co. All endpoints are at {baseUrl}/functions/v1/{endpoint-name}. You can override the base URL with the ADR_AGGREGATOR_URL environment variable.

Overview​

Prerequisites​

Setup​

Step 1: Get Your API Key​

Step 2: Configure Environment Variables​

Step 3: Verify Configuration​

Tier Features​

Common Workflows​

Workflow 1: Initial ADR Sync​

Workflow 2: Pull ADR Context for AI Analysis​

Workflow 3: Check ADR Staleness​

Workflow 4: Analyze Code-ADR Gaps​

Workflow 5: Track Implementation Progress (Pro+)​

Workflow 6: Prioritize ADRs for Roadmap​

Workflow 7: Cross-Repository Knowledge Graph (Team)​

CI/CD Integration​

GitHub Actions Example​

Pre-commit Hook​

Troubleshooting​

Error: "ADR Aggregator API key not configured"​

Error: "Not a git repository"​

Error: "This feature requires Pro+ tier"​

Error: "Repository not found"​

Error: "Request timed out"​

API Reference​

Best Practices​

1. Sync Regularly​

2. Address Gaps Promptly​

3. Track Implementation Status​

4. Use Staleness Thresholds​

5. Leverage Cross-Repo Insights (Team)​

Endpoint and Tool Reference​

Related Documentation​