# ADR Aggregator Integration Guide

This guide explains how to integrate the MCP ADR Analysis Server with [ADR Aggregator](https://adraggregator.com) 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:

1. **MCP ADR Analysis Server** installed (`npm install -g @tosin2013/mcp-adr-analysis-server`)
2. **Git repository** initialized in your project
3. **ADR Aggregator account** at [adraggregator.com](https://adraggregator.com)

## Setup

### Step 1: Get Your API Key

1. Sign up or log in at [adraggregator.com](https://adraggregator.com)
2. Navigate to **Settings** > **API Keys**
3. Click **Generate New Key**
4. 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:

```bash
# 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:

```bash
# 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:

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

**What happens:**

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

### Workflow 2: Pull ADR Context for AI Analysis

Get enriched ADR context for AI-assisted decision making:

```json
// 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:

```json
// 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:

```json
// 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:

```json
// 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:

```json
// 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:

```json
// 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

```yaml
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`:

```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:

```bash
export ADR_AGGREGATOR_API_KEY="your-key"
```

### Error: "Not a git repository"

**Solution:** Initialize git and add a remote:

```bash
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](https://adraggregator.com/pricing)

### Error: "Repository not found"

**Solution:** Sync your ADRs first:

```json
// 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](../reference/api-reference.md#-adr-aggregator-integration-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:

1. Review the suggested ADR title
2. Create the ADR using templates from `get_adr_templates`
3. 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](https://adraggregator.com/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.

## Related Documentation

- [Installation Guide](./installation-guide.md)
- [Work with Existing ADRs](./work-with-existing-adrs.md)
- [CI/CD Integration](./cicd-integration.md)
- [Troubleshooting](./troubleshooting.md)
- [ADR Aggregator MCP Guide](https://adraggregator.com/mcp-guide)
