🔧 Environment Configuration Reference

Complete guide to configuring the MCP ADR Analysis Server environment variables and settings.

📋 Quick Reference

Variable	Required	Default	Description
`PROJECT_PATH`	❌	`.`	Path to project directory (defaults to current directory)
`EXECUTION_MODE`	❌	`ce-mcp`	`ce-mcp` (default), `full` (legacy, needs API key), or `prompt-only`
`ADR_DIRECTORY`	❌	`docs/adrs`	Directory for ADR files relative to project path
`LOG_LEVEL`	❌	`INFO`	Logging verbosity
`OPENROUTER_API_KEY`	❌	-	OpenRouter API key (only needed for legacy `full` execution mode)
`ADR_AGGREGATOR_API_KEY`	❌	-	API key for ADR Aggregator platform

Legend: ❌ Optional — CE-MCP mode (the default) requires no API key. Your host LLM executes analysis via orchestration directives.

🎯 Essential Configuration

PROJECT_PATH (Required)

Purpose: Tells the server which project to analyze

# ✅ Correct - absolute path
PROJECT_PATH="/Users/username/my-project"

# ❌ Wrong - relative path
PROJECT_PATH="."
PROJECT_PATH="../my-project"

Common Issues:

Relative paths cause file access errors
Non-existent paths cause startup failures
Paths with spaces need proper escaping

Validation:

# Test your path
ls -la "$PROJECT_PATH"
# Should show your project files

EXECUTION_MODE

Purpose: Controls how tools return results

# ✅ CE-MCP mode (default, recommended — no API key needed)
EXECUTION_MODE="ce-mcp"

# Legacy: server-side AI execution (requires OPENROUTER_API_KEY)
EXECUTION_MODE="full"

# Legacy: returns prompts you can paste into any AI chat
EXECUTION_MODE="prompt-only"

Mode Comparison:

Mode	Returns	Requires API Key?
`ce-mcp`	Orchestration directives for your host LLM	No
`full`	Server-side AI analysis results	Yes
`prompt-only`	Prompts you can paste into any AI chat	No

CE-MCP mode is recommended for all users. Your host LLM (Claude, GPT, etc.) executes the analysis using orchestration directives returned by the tools — zero additional API cost and better results because the LLM already has your conversation context.

OPENROUTER_API_KEY (Legacy — Full Mode Only)

Purpose: Only needed if you set EXECUTION_MODE=full for server-side AI execution

# Get your key from: https://openrouter.ai/keys
OPENROUTER_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Not needed in CE-MCP mode (the default). In CE-MCP mode, your host LLM provides all AI capabilities.

🤖 AI Configuration (Legacy Full Mode Only)

Note: The settings below only apply when EXECUTION_MODE=full. In CE-MCP mode (default), your host LLM handles all AI execution and these settings are ignored.

AI_MODEL

Purpose: Choose which AI model to use for server-side analysis (full mode only)

AI_MODEL="anthropic/claude-3-sonnet"    # Default
AI_MODEL="anthropic/claude-3-haiku"     # Faster/cheaper
AI_MODEL="openai/gpt-4o"                # Alternative

📁 Project Configuration

ADR_DIRECTORY

Purpose: Where to store Architectural Decision Records

# Default location
ADR_DIRECTORY="./adrs"

# Custom locations
ADR_DIRECTORY="architecture/decisions"
ADR_DIRECTORY="./architecture/adrs"

Directory Structure Created:

./adrs/
├── README.md           # ADR index
├── 001-first-decision.md
├── 002-second-decision.md
└── template.md         # ADR template

File Patterns

# Include/exclude patterns for analysis
INCLUDE_PATTERNS="*.ts,*.js,*.py,*.md"
EXCLUDE_PATTERNS="node_modules,dist,coverage"

# Maximum file size to analyze (bytes)
MAX_FILE_SIZE="1048576"  # 1MB

🔍 Logging and Debugging

LOG_LEVEL

Purpose: Control logging verbosity

LOG_LEVEL="ERROR"   # Only errors
LOG_LEVEL="WARN"    # Warnings and errors
LOG_LEVEL="INFO"    # General information (default)
LOG_LEVEL="DEBUG"   # Detailed debugging info

When to Use Each Level:

ERROR: Production deployments
WARN: Normal usage
INFO: Development and troubleshooting
DEBUG: Investigating issues

Advanced Debugging

# Enable verbose output
VERBOSE="true"

# Enable performance timing
TIMING_ENABLED="true"

# Enable memory usage tracking
MEMORY_TRACKING="true"

🔒 Security Configuration

Content Masking

# Enable automatic content masking
ENABLE_CONTENT_MASKING="true"

# Masking sensitivity level
MASKING_LEVEL="strict"     # Most secure
MASKING_LEVEL="moderate"   # Balanced (default)
MASKING_LEVEL="lenient"    # Minimal masking

Custom Security Patterns

# Additional patterns to detect as sensitive
CUSTOM_SECRET_PATTERNS="company-api-key-.*,internal-token-.*"

# Whitelist patterns (never mask these)
WHITELIST_PATTERNS="example-.*,demo-.*,test-.*"

⚡ Performance Configuration

Caching

# Cache directory location
CACHE_DIRECTORY=".mcp-adr-cache"

# Cache size limits
MAX_CACHE_SIZE="100MB"
MAX_CACHE_AGE="7d"  # 7 days

# Cache cleanup frequency
CACHE_CLEANUP_INTERVAL="24h"

Analysis Limits

# Maximum recursion depth for project analysis
MAX_RECURSION_DEPTH="10"

# Maximum files to analyze in one operation
MAX_FILES_PER_ANALYSIS="1000"

# Timeout for individual file analysis (ms)
FILE_ANALYSIS_TIMEOUT="30000"

ADR Aggregator Configuration (Optional)

# Enable ADR Aggregator integration for cross-team visibility
# Get your API key at https://adraggregator.com
ADR_AGGREGATOR_API_KEY="agg_your_key_here"

ADR Aggregator Configuration Options:

ADR_AGGREGATOR_API_KEY: API key from adraggregator.com (auto-enables integration)

Available Tiers:

Tier	Features
Free	Sync ADRs, get context, staleness reports, templates
Pro+	+ Mermaid diagrams, compliance validation
Team	+ Cross-repository knowledge graph

🌍 Environment-Specific Configurations

Development Environment

# .env.development — CE-MCP mode (default), no API key needed
PROJECT_PATH="/Users/developer/current-project"
LOG_LEVEL="DEBUG"

Production Environment

# .env.production
PROJECT_PATH="/app/project"
LOG_LEVEL="ERROR"

CI/CD Environment

# .env.ci
PROJECT_PATH="${GITHUB_WORKSPACE}"
LOG_LEVEL="INFO"

Legacy Full Mode (server-side AI)

# Only needed if you explicitly want server-side AI execution
PROJECT_PATH="/Users/developer/current-project"
OPENROUTER_API_KEY="your-key"
EXECUTION_MODE="full"

📱 MCP Client Configuration

Claude Desktop

{
  "mcpServers": {
    "adr-analysis": {
      "command": "npx",
      "args": ["-y", "mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": "/absolute/path/to/project"
      }
    }
  }
}

That's it — CE-MCP mode is the default, so no API key or EXECUTION_MODE is needed.

Cline (VS Code)

{
  "mcpServers": {
    "mcp-adr-analysis-server": {
      "command": "npx",
      "args": ["-y", "mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": "${workspaceFolder}"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "adr-analysis": {
      "command": "npx",
      "args": ["-y", "mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": "."
      }
    }
  }
}

🔧 Configuration Validation

Test Your Configuration

# 1. Test server startup
mcp-adr-analysis-server --test

# 2. Validate environment
echo "Project: $PROJECT_PATH"
echo "ADR Dir: $ADR_DIRECTORY"
echo "Mode: $EXECUTION_MODE"

# 3. Test API key (safely)
echo $OPENROUTER_API_KEY | head -c 10

Common Configuration Errors

Error	Cause	Solution
"Project path not found"	Invalid `PROJECT_PATH`	Use a valid absolute or relative path
"Permission denied"	Wrong directory permissions	Check file permissions
"Module not found"	Server not installed properly	Reinstall with `npm install -g mcp-adr-analysis-server`

Diagnostic Tool

{
  "tool": "analyze_project_ecosystem",
  "parameters": {}
}

🚀 Optimization Tips

For Large Projects

# Reduce analysis scope
MAX_FILES_PER_ANALYSIS="500"
MAX_RECURSION_DEPTH="5"

# Enable aggressive caching
AI_CACHE_ENABLED="true"
AI_CACHE_TTL="86400"

For Team Environments

# Shared cache location
CACHE_DIRECTORY="/shared/mcp-cache"

# Standardized ADR location
ADR_DIRECTORY="./architecture/decisions"

For Security-Sensitive Projects

# Strict content masking
ENABLE_CONTENT_MASKING="true"
MASKING_LEVEL="strict"

# Custom security patterns
CUSTOM_SECRET_PATTERNS="company-.*,internal-.*,private-.*"

# Disable caching of sensitive content
AI_CACHE_ENABLED="false"

MCP Client Configuration - Detailed client setup
Troubleshooting - Common issues and solutions
Security Guide - Security configuration
API Reference - Complete tool documentation

Need help with configuration? → Troubleshooting Guide or File an Issue

📋 Quick Reference​

🎯 Essential Configuration​

PROJECT_PATH (Required)​

EXECUTION_MODE​

OPENROUTER_API_KEY (Legacy — Full Mode Only)​

🤖 AI Configuration (Legacy Full Mode Only)​

AI_MODEL​

📁 Project Configuration​

ADR_DIRECTORY​

File Patterns​

🔍 Logging and Debugging​

LOG_LEVEL​

Advanced Debugging​

🔒 Security Configuration​

Content Masking​

Custom Security Patterns​

⚡ Performance Configuration​

Caching​

Analysis Limits​

ADR Aggregator Configuration (Optional)​

🌍 Environment-Specific Configurations​

Development Environment​

Production Environment​

CI/CD Environment​

Legacy Full Mode (server-side AI)​

📱 MCP Client Configuration​

Claude Desktop​

Cline (VS Code)​

Cursor​

🔧 Configuration Validation​

Test Your Configuration​

Common Configuration Errors​

Diagnostic Tool​

🚀 Optimization Tips​

For Large Projects​

For Team Environments​

For Security-Sensitive Projects​

📚 Related Documentation​