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

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

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

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

| Variable       | Description                             | Default                   |
| -------------- | --------------------------------------- | ------------------------- |
| `PROJECT_PATH` | Absolute path to the project to analyze | Current working directory |

### AI Execution

| Variable             | Description                                  | Default                     |
| -------------------- | -------------------------------------------- | --------------------------- |
| `OPENROUTER_API_KEY` | OpenRouter API key for AI execution          | — (prompt-only mode)        |
| `EXECUTION_MODE`     | `full`, `prompt-only`, `ce-mcp`, or `hybrid` | `prompt-only`               |
| `AI_MODEL`           | AI model identifier                          | `anthropic/claude-3-sonnet` |
| `AI_TEMPERATURE`     | Response consistency (0.0–1.0)               | `0.3`                       |
| `AI_MAX_TOKENS`      | Maximum response length                      | `4096`                      |
| `AI_TIMEOUT`         | Request timeout in milliseconds              | `30000`                     |

### ADR Management

| Variable        | Description                                   | Default     |
| --------------- | --------------------------------------------- | ----------- |
| `ADR_DIRECTORY` | Directory for ADR files (relative to project) | `docs/adrs` |

### Logging

| Variable    | Description                                         | Default |
| ----------- | --------------------------------------------------- | ------- |
| `LOG_LEVEL` | Logging verbosity: `DEBUG`, `INFO`, `WARN`, `ERROR` | `INFO`  |

### Caching

| Variable          | Description                           | Default             |
| ----------------- | ------------------------------------- | ------------------- |
| `CACHE_ENABLED`   | Enable analysis caching               | `true`              |
| `CACHE_DIRECTORY` | Cache directory (relative to project) | `.mcp-adr-cache`    |
| `MAX_CACHE_SIZE`  | Maximum cache size in bytes           | `104857600` (100MB) |

### Analysis

| Variable           | Description                            | Default |
| ------------------ | -------------------------------------- | ------- |
| `ANALYSIS_TIMEOUT` | Tool execution timeout in milliseconds | `30000` |

### Firecrawl (Web Research)

| Variable             | Description                       | Default                 |
| -------------------- | --------------------------------- | ----------------------- |
| `FIRECRAWL_ENABLED`  | Enable Firecrawl integration      | `false`                 |
| `FIRECRAWL_API_KEY`  | Firecrawl API key (cloud service) | —                       |
| `FIRECRAWL_BASE_URL` | Firecrawl base URL (self-hosted)  | `http://localhost:3000` |

### ADR Aggregator

| Variable                 | Description                       | Default                                    |
| ------------------------ | --------------------------------- | ------------------------------------------ |
| `ADR_AGGREGATOR_ENABLED` | Enable ADR Aggregator integration | `false`                                    |
| `ADR_AGGREGATOR_API_KEY` | ADR Aggregator API key            | —                                          |
| `ADR_AGGREGATOR_URL`     | ADR Aggregator endpoint           | `https://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

```bash
EXECUTION_MODE=prompt-only
```

### full

Executes prompts via OpenRouter API. Requires `OPENROUTER_API_KEY`.

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

```bash
EXECUTION_MODE=ce-mcp
```

### hybrid

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

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

---

## AI Model Selection

Set `AI_MODEL` to any model supported by OpenRouter:

| Model           | Identifier                        | Best For                   |
| --------------- | --------------------------------- | -------------------------- |
| Claude 3 Sonnet | `anthropic/claude-3-sonnet`       | General analysis (default) |
| Claude 3 Haiku  | `anthropic/claude-3-haiku`        | Fast, cost-effective       |
| Claude 3 Opus   | `anthropic/claude-3-opus`         | Complex reasoning          |
| GPT-4 Turbo     | `openai/gpt-4-turbo`              | Alternative to Claude      |
| Llama 3 70B     | `meta-llama/llama-3-70b-instruct` | Open-source alternative    |

Example:

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

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

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

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

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

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

```bash
# 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](https://openrouter.ai/keys)
2. Set the environment variable:
   ```bash
   OPENROUTER_API_KEY=sk-or-v1-xxxxx
   EXECUTION_MODE=full
   ```

### Cache corruption

Clear the cache and restart:

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

---

## Related Documentation

- **[Architecture Overview](./explanation/architecture-overview.md)** — System design
- **[AI Architecture](./explanation/ai-architecture-concepts.md)** — AI integration details
- **[API Reference](./reference/api-reference.md)** — Tool documentation
- **[Troubleshooting](./how-to-guides/troubleshooting.md)** — Common issues

---

**Questions about configuration?** → **[Open an Issue](https://github.com/tosin2013/mcp-adr-analysis-server/issues)**
