🔧 Environment Configuration Reference

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

📋 Quick Reference

Variable	Required	Default	Description
`PROJECT_PATH`	✅	-	Absolute path to project directory
`OPENROUTER_API_KEY`	⚡	-	API key for AI-powered analysis
`EXECUTION_MODE`	⚡	`prompt-only`	`full` or `prompt-only`
`AI_MODEL`	❌	`anthropic/claude-3-sonnet`	AI model to use
`ADR_DIRECTORY`	❌	`./adrs`	Directory for ADR files
`LOG_LEVEL`	❌	`INFO`	Logging verbosity
`FIRECRAWL_API_KEY`	❌	-	API key for Firecrawl web scraping
`FIRECRAWL_BASE_URL`	❌	`https://localhost:3000`	Base URL for self-hosted Firecrawl
`FIRECRAWL_ENABLED`	❌	`false`	Enable Firecrawl integration

Legend: ✅ Required • ⚡ Required for AI features • ❌ Optional

🎯 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

OPENROUTER_API_KEY (Required for AI)

Purpose: Enables AI-powered analysis instead of prompt-only mode

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

Without this key:

Tools return prompts instead of analysis results
No AI-powered insights or suggestions
Limited to basic file operations

Validation:

# Test API key (first 10 characters only for security)
echo $OPENROUTER_API_KEY | head -c 10
# Should show: sk-or-v1-x

EXECUTION_MODE (Critical for AI)

Purpose: Controls whether tools execute AI analysis or return prompts

# ✅ AI-powered execution (recommended)
EXECUTION_MODE="full"

# ❌ Legacy prompt-only mode
EXECUTION_MODE="prompt-only"

Mode Comparison:

Mode	`suggest_adrs` Returns	`analyze_project_ecosystem` Returns
`full`	Actual ADR suggestions with reasoning	Complete technology analysis
`prompt-only`	Instructions to analyze architecture	Instructions to examine project

🤖 AI Configuration

AI_MODEL

Purpose: Choose which AI model to use for analysis

# Recommended models
AI_MODEL="anthropic/claude-3-sonnet"    # Best quality
AI_MODEL="anthropic/claude-3-haiku"     # Fastest/cheapest
AI_MODEL="openai/gpt-4o"                # Alternative quality option
AI_MODEL="openai/gpt-4o-mini"          # Alternative fast option

Model Comparison:

Model	Speed	Quality	Cost	Best For
`claude-3-sonnet`	Medium	Excellent	High	Complex analysis
`claude-3-haiku`	Fast	Good	Low	Quick tasks
`gpt-4o`	Medium	Excellent	High	Alternative to Claude
`gpt-4o-mini`	Fast	Good	Low	Cost-effective

AI Performance Tuning

# Response consistency (0-1, lower = more consistent)
AI_TEMPERATURE="0.1"

# Maximum response length
AI_MAX_TOKENS="4000"

# Request timeout (milliseconds)
AI_TIMEOUT="60000"

# Enable response caching
AI_CACHE_ENABLED="true"
AI_CACHE_TTL="3600"  # 1 hour

📁 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"

Firecrawl Configuration

# Enable Firecrawl integration for web search
FIRECRAWL_ENABLED="true"

# Firecrawl API key (get from https://firecrawl.dev)
FIRECRAWL_API_KEY="fc-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Self-hosted Firecrawl base URL (if not using API key)
FIRECRAWL_BASE_URL="https://localhost:3000"

Firecrawl Configuration Options:

FIRECRAWL_ENABLED: Set to true to enable Firecrawl integration
FIRECRAWL_API_KEY: API key for Firecrawl service (optional, enables cloud service)
FIRECRAWL_BASE_URL: Base URL for self-hosted Firecrawl (default: https://localhost:3000)

Usage Modes:

Cloud Service: Set FIRECRAWL_API_KEY to use Firecrawl cloud service
Self-Hosted: Set FIRECRAWL_BASE_URL to point to your self-hosted instance
Disabled: Leave FIRECRAWL_ENABLED unset or set to false (default)

🌍 Environment-Specific Configurations

Development Environment

# .env.development
PROJECT_PATH="/Users/developer/current-project"
OPENROUTER_API_KEY="your-dev-key"
EXECUTION_MODE="full"
AI_MODEL="anthropic/claude-3-haiku"  # Faster for dev
LOG_LEVEL="DEBUG"
AI_CACHE_ENABLED="true"
TIMING_ENABLED="true"
FIRECRAWL_ENABLED="true"
FIRECRAWL_API_KEY="your-firecrawl-key"

Production Environment

# .env.production
PROJECT_PATH="/app/project"
OPENROUTER_API_KEY="your-prod-key"
EXECUTION_MODE="full"
AI_MODEL="anthropic/claude-3-sonnet"  # Best quality
LOG_LEVEL="ERROR"
AI_CACHE_ENABLED="true"
AI_CACHE_TTL="86400"  # 24 hours
FIRECRAWL_ENABLED="true"
FIRECRAWL_BASE_URL="https://firecrawl:3000"  # Self-hosted

CI/CD Environment

# .env.ci
PROJECT_PATH="${GITHUB_WORKSPACE}"
OPENROUTER_API_KEY="${OPENROUTER_API_KEY}"  # From secrets
EXECUTION_MODE="full"
AI_MODEL="anthropic/claude-3-haiku"  # Fast for CI
LOG_LEVEL="INFO"
AI_CACHE_ENABLED="false"  # Fresh analysis each time
FIRECRAWL_ENABLED="false"  # Disable for CI performance

📱 MCP Client Configuration

Claude Desktop

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/absolute/path/to/project",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "ERROR",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "your_firecrawl_key"
      }
    }
  }
}

Cline (VS Code)

{
  "mcpServers": {
    "mcp-adr-analysis-server": {
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": "${workspaceFolder}",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "ERROR"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "adr-analysis": {
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": ".",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "ERROR"
      }
    }
  }
}

🔧 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"	Relative or invalid `PROJECT_PATH`	Use absolute path
"Tools return prompts"	Missing `EXECUTION_MODE=full`	Set execution mode
"AI execution not available"	Missing `OPENROUTER_API_KEY`	Add API key
"Permission denied"	Wrong directory permissions	Check file permissions
"Module not found"	Server not installed properly	Reinstall server

Diagnostic Tool

{
  "tool": "check_ai_execution_status",
  "parameters": {}
}

Expected Response:

{
  "aiExecutionAvailable": true,
  "executionMode": "full",
  "apiKeyConfigured": true,
  "model": "anthropic/claude-3-sonnet",
  "projectPath": "/absolute/path/to/project",
  "adrDirectory": "./adrs"
}

🚀 Optimization Tips

For Large Projects

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

# Use faster model for initial analysis
AI_MODEL="anthropic/claude-3-haiku"

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

For Team Environments

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

# Consistent model across team
AI_MODEL="anthropic/claude-3-sonnet"

# 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)​

OPENROUTER_API_KEY (Required for AI)​

EXECUTION_MODE (Critical for AI)​

🤖 AI Configuration​

AI_MODEL​

AI Performance Tuning​

📁 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​

Firecrawl Configuration​

🌍 Environment-Specific Configurations​

Development Environment​

Production Environment​

CI/CD Environment​

📱 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​