Skip to main content

Configuration Reference

Complete reference for all environment variables and configuration options.

Quick Start​

The minimal configuration requires only setting your MCP client to run the server:

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/project"
      }
    }
  }
}

For AI-powered analysis, add your OpenRouter API key:

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "OPENROUTER_API_KEY": "your_api_key_here",
        "EXECUTION_MODE": "full"
      }
    }
  }
}

Environment Variables​

Required​

VariableDescriptionDefault
PROJECT_PATHAbsolute path to the project to analyzeCurrent working directory

AI Execution​

VariableDescriptionDefault
OPENROUTER_API_KEYOpenRouter API key for AI execution— (prompt-only mode)
EXECUTION_MODEfull, prompt-only, ce-mcp, or hybridprompt-only
AI_MODELAI model identifieranthropic/claude-3-sonnet
AI_TEMPERATUREResponse consistency (0.0–1.0)0.3
AI_MAX_TOKENSMaximum response length4096
AI_TIMEOUTRequest timeout in milliseconds30000

ADR Management​

VariableDescriptionDefault
ADR_DIRECTORYDirectory for ADR files (relative to project)docs/adrs

Logging​

VariableDescriptionDefault
LOG_LEVELLogging verbosity: DEBUG, INFO, WARN, ERRORINFO

Caching​

VariableDescriptionDefault
CACHE_ENABLEDEnable analysis cachingtrue
CACHE_DIRECTORYCache directory (relative to project).mcp-adr-cache
MAX_CACHE_SIZEMaximum cache size in bytes104857600 (100MB)

Analysis​

VariableDescriptionDefault
ANALYSIS_TIMEOUTTool execution timeout in milliseconds30000

Firecrawl (Web Research)​

VariableDescriptionDefault
FIRECRAWL_ENABLEDEnable Firecrawl integrationfalse
FIRECRAWL_API_KEYFirecrawl API key (cloud service)—
FIRECRAWL_BASE_URLFirecrawl base URL (self-hosted)http://localhost:3000

ADR Aggregator​

VariableDescriptionDefault
ADR_AGGREGATOR_ENABLEDEnable ADR Aggregator integrationfalse
ADR_AGGREGATOR_API_KEYADR Aggregator API key—
ADR_AGGREGATOR_URLADR Aggregator endpointhttps://jvgdaquuggzbkenxnkja.supabase.co

Execution Modes​

prompt-only (Default)​

Returns structured prompts without AI execution. Use this to:

  • Explore available tools without cost
  • Copy prompts to your preferred AI interface
  • Test tool parameters before enabling AI
EXECUTION_MODE=prompt-only

full​

Executes prompts via OpenRouter API. Requires OPENROUTER_API_KEY.

EXECUTION_MODE=full
OPENROUTER_API_KEY=sk-or-v1-xxxxx

ce-mcp​

Returns orchestration directives for the host LLM (MCP client) to execute. This is the recommended mode for advanced integrations.

EXECUTION_MODE=ce-mcp

hybrid​

Supports both CE-MCP directives and OpenRouter fallback. Uses OpenRouter when CE-MCP execution fails.

EXECUTION_MODE=hybrid
OPENROUTER_API_KEY=sk-or-v1-xxxxx

AI Model Selection​

Set AI_MODEL to any model supported by OpenRouter:

ModelIdentifierBest For
Claude 3 Sonnetanthropic/claude-3-sonnetGeneral analysis (default)
Claude 3 Haikuanthropic/claude-3-haikuFast, cost-effective
Claude 3 Opusanthropic/claude-3-opusComplex reasoning
GPT-4 Turboopenai/gpt-4-turboAlternative to Claude
Llama 3 70Bmeta-llama/llama-3-70b-instructOpen-source alternative

Example:

AI_MODEL=anthropic/claude-3-haiku
AI_TEMPERATURE=0.2
AI_MAX_TOKENS=8192

Client-Specific Configuration​

Claude Desktop​

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/project",
        "OPENROUTER_API_KEY": "sk-or-v1-xxxxx",
        "EXECUTION_MODE": "full",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Cursor​

Settings → MCP → Add Server

{
  "mcp-adr-analysis-server": {
    "command": "npx",
    "args": ["mcp-adr-analysis-server"],
    "env": {
      "PROJECT_PATH": "${workspaceFolder}",
      "OPENROUTER_API_KEY": "sk-or-v1-xxxxx",
      "EXECUTION_MODE": "full"
    }
  }
}

Cline (VS Code)​

.vscode/cline_mcp_settings.json:

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "${workspaceFolder}",
        "OPENROUTER_API_KEY": "sk-or-v1-xxxxx",
        "EXECUTION_MODE": "full"
      }
    }
  }
}

Full Configuration Example​

All options with recommended values:

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/project",
        "ADR_DIRECTORY": "docs/adrs",
        "OPENROUTER_API_KEY": "sk-or-v1-xxxxx",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "AI_TEMPERATURE": "0.3",
        "AI_MAX_TOKENS": "4096",
        "LOG_LEVEL": "INFO",
        "CACHE_ENABLED": "true",
        "CACHE_DIRECTORY": ".mcp-adr-cache",
        "MAX_CACHE_SIZE": "104857600",
        "ANALYSIS_TIMEOUT": "30000",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "fc-xxxxx",
        "ADR_AGGREGATOR_ENABLED": "true",
        "ADR_AGGREGATOR_API_KEY": "agg_xxxxx"
      }
    }
  }
}

Validation​

Check your configuration by running the server with LOG_LEVEL=DEBUG:

PROJECT_PATH=/your/project LOG_LEVEL=DEBUG mcp-adr-analysis-server

The server logs configuration details on startup:

[INFO] MCP ADR Analysis Server Configuration:
[INFO]   Project Path: /your/project
[INFO]   ADR Directory: docs/adrs
[INFO]   Log Level: DEBUG
[INFO]   Cache Enabled: true
[INFO]   Firecrawl Enabled: false
[INFO]   ADR Aggregator Enabled: false

Common Issues​

"PROJECT_PATH does not exist"​

The specified project path doesn't exist or isn't a directory:

# Verify path exists
ls -la /path/to/project

# Use absolute path
PROJECT_PATH=$(pwd) mcp-adr-analysis-server

"Missing OPENROUTER_API_KEY"​

AI execution requires an API key:

  1. Sign up at openrouter.ai/keys
  2. Set the environment variable: 
    OPENROUTER_API_KEY=sk-or-v1-xxxxx
    EXECUTION_MODE=full

Cache corruption​

Clear the cache and restart:

rm -rf /path/to/project/.mcp-adr-cache

Questions about configuration? → Open an Issue