# 🔧 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        |
| `ADR_AGGREGATOR_API_KEY` | ❌       | -                           | API key for ADR Aggregator platform |

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

---

## 🎯 Essential Configuration

### PROJECT_PATH (Required)

**Purpose**: Tells the server which project to analyze

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

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

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

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

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

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

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

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

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

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

```bash
# Enable verbose output
VERBOSE="true"

# Enable performance timing
TIMING_ENABLED="true"

# Enable memory usage tracking
MEMORY_TRACKING="true"
```

---

## 🔒 Security Configuration

### Content Masking

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

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

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

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

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

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

### ADR Aggregator Configuration (Optional)

```bash
# 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](https://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

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

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

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

```json
{
  "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)

```json
{
  "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

```json
{
  "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

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

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

**Expected Response**:

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

---

## 🚀 Optimization Tips

### For Large Projects

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

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

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

---

## 📚 Related Documentation

- **[MCP Client Configuration](mcp-client-config.md)** - Detailed client setup
- **[Troubleshooting](../how-to-guides/troubleshooting.md)** - Common issues and solutions
- **[Security Guide](../how-to-guides/security-analysis.md)** - Security configuration
- **[API Reference](api-reference.md)** - Complete tool documentation

---

**Need help with configuration?** → **[Troubleshooting Guide](../how-to-guides/troubleshooting.md)** or **[File an Issue](https://github.com/tosin2013/mcp-adr-analysis-server/issues)**
