# Configuration Reference

> Complete reference for foundry-mcp configuration options.

## Overview

foundry-mcp can be configured through:
1. **TOML file**: `foundry-mcp.toml` in workspace root
2. **Environment variables**: Prefixed with `FOUNDRY_MCP_`
3. **Default values**: Built-in defaults for all options

Priority: Environment variables > TOML file > Defaults

## Configuration File

Create `foundry-mcp.toml` in your workspace root:

```toml
[workspace]
specs_dir = "./specs"

[logging]
level = "INFO"
structured = true

[research]
deep_research_digest_policy = "auto"
deep_research_digest_min_chars = 10000
```

## Research Configuration

### Deep Research Settings

Core settings for the deep research workflow:

| Setting | Default | Description |
|---------|---------|-------------|
| `deep_research_max_iterations` | `3` | Maximum refinement iterations |
| `deep_research_max_sub_queries` | `5` | Max sub-queries to generate |
| `deep_research_max_sources_per_query` | `5` | Max sources per sub-query |
| `deep_research_follow_links` | `true` | Follow and extract linked content |
| `deep_research_timeout` | `600` | Overall research timeout (seconds) |

### Document Digest Settings

Settings for the document digest phase that compresses source content:

| Setting | Type | Default | Valid Values | Description |
|---------|------|---------|--------------|-------------|
| `deep_research_digest_policy` | string | `"auto"` | `"off"`, `"auto"`, `"always"` | Controls when digest is applied |
| `deep_research_digest_min_chars` | int | `10000` | ≥0 | Minimum source chars for auto-policy eligibility |
| `deep_research_digest_max_sources` | int | `8` | ≥1 | Maximum sources to digest per batch |
| `deep_research_digest_timeout` | float | `120.0` | >0 | Timeout per digest operation (seconds) |
| `deep_research_digest_max_concurrent` | int | `3` | ≥1 | Maximum concurrent digest operations |
| `deep_research_digest_include_evidence` | bool | `true` | `true`, `false` | Include evidence snippets in output |
| `deep_research_digest_evidence_max_chars` | int | `400` | 1-500 | Maximum characters per evidence snippet |
| `deep_research_digest_max_evidence_snippets` | int | `5` | 1-10 | Maximum evidence snippets per digest |
| `deep_research_digest_fetch_pdfs` | bool | `false` | `true`, `false` | Fetch and extract PDF content |
| `deep_research_digest_provider` | string | `null` | provider spec | Primary LLM provider for digest (uses analysis provider if not set) |
| `deep_research_digest_providers` | list | `[]` | provider specs | Fallback providers for digest (tried in order if primary fails) |

Note: Evidence snippet limits are clamped to schema caps (500 chars, 10 snippets) to prevent validation errors.

#### Digest Policy Details

**`off`**: Digest is completely disabled. All sources pass through with original content unchanged. Use when you want maximum fidelity and have sufficient context budget.

**`auto`** (default): Intelligent digestion based on:
- Source must exceed `min_chars` threshold (default 10,000)
- Source quality must be HIGH or MEDIUM
- Low quality and unknown quality sources are skipped
- Recommended for most use cases

**`always`**: Digest all sources with content regardless of size or quality. Use for aggressive compression when context budget is tight.

#### Evidence Snippet Configuration

Evidence snippets preserve query-relevant excerpts with position locators for citation:

```toml
[research]
# Include evidence snippets (recommended for citations)
deep_research_digest_include_evidence = true

# Maximum chars per snippet (truncation applied at render time)
deep_research_digest_evidence_max_chars = 400

# Maximum snippets per digest (top-scoring by relevance)
deep_research_digest_max_evidence_snippets = 5
```

#### Performance Tuning

For large research jobs, tune concurrency and timeouts:

```toml
[research]
# Increase concurrent digests for faster processing
deep_research_digest_max_concurrent = 5

# Increase timeout for complex documents
deep_research_digest_timeout = 180.0

# Process more sources per batch
deep_research_digest_max_sources = 12
```

#### PDF Processing

Enable PDF extraction for research involving PDF documents:

```toml
[research]
# Enable PDF fetching and text extraction
deep_research_digest_fetch_pdfs = true
```

When enabled:
- PDF URLs are fetched and text is extracted
- Page boundaries are tracked for locators
- Evidence locators include page references (e.g., `page:3:char:200-450`)

### Content Archival Settings

Settings for archiving original source content:

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `deep_research_archive_content` | bool | `false` | Archive canonical text before digest |
| `deep_research_archive_retention_days` | int | `30` | Days to retain archived content (0 = keep indefinitely) |

When archival is enabled:
- Canonical (normalized) text is stored before compression
- Path: `~/.foundry-mcp/research_archives/{source_id}/{hash}.txt`
- Evidence locators can be verified against archived content

### Provider Settings

Configure LLM providers for research phases:

| Setting | Default | Description |
|---------|---------|-------------|
| `deep_research_analysis_provider` | `"claude"` | Provider for analysis phase |
| `deep_research_synthesis_provider` | `"claude"` | Provider for synthesis/report |
| `summarization_provider` | `"claude"` | Provider for digest summarization |

## Example Configurations

### Minimal (defaults)

```toml
# Use all defaults - digest enabled with auto policy
[research]
```

### High Fidelity (digest off)

```toml
[research]
# Disable digest for maximum source fidelity
deep_research_digest_policy = "off"
```

### Aggressive Compression

```toml
[research]
# Digest everything for tight context budgets
deep_research_digest_policy = "always"
deep_research_digest_min_chars = 1000
deep_research_digest_max_sources = 15
deep_research_digest_max_concurrent = 5
```

### Research with PDFs

```toml
[research]
# Enable PDF processing with archival
deep_research_digest_fetch_pdfs = true
deep_research_archive_content = true
deep_research_archive_retention_days = 60
```

### Citation-Focused

```toml
[research]
# Maximize evidence for citation support
deep_research_digest_include_evidence = true
deep_research_digest_max_evidence_snippets = 10
deep_research_digest_evidence_max_chars = 500
```

## Environment Variables

All settings can be set via environment variables with `FOUNDRY_MCP_` prefix and uppercase:

```bash
# Set digest policy
export FOUNDRY_MCP_DEEP_RESEARCH_DIGEST_POLICY=auto

# Set minimum chars
export FOUNDRY_MCP_DEEP_RESEARCH_DIGEST_MIN_CHARS=10000

# Enable PDF processing
export FOUNDRY_MCP_DEEP_RESEARCH_DIGEST_FETCH_PDFS=true
```

## Validation

Invalid configuration values produce clear error messages:

```
Invalid deep_research_digest_policy: 'invalid'. Must be one of: off, auto, always
Invalid deep_research_digest_min_chars: -100. Must be >= 0
Invalid deep_research_digest_timeout: 0. Must be > 0
```

Configuration is validated at startup. The server will fail to start with invalid configuration.
