# foundry-mcp Project Configuration Sample
#
# This file is for PROJECT-LEVEL settings (./foundry-mcp.toml).
# Place in your project root directory.
#
# For USER-LEVEL defaults (API keys, preferred providers), use one of:
# - ~/.foundry-mcp.toml (legacy location)
# - ~/.config/foundry-mcp/config.toml (XDG config directory)
#
# The values shown are "good defaults" for a typical local setup.
# Leave a setting commented to use the built-in default.
# Keep secrets (API keys) in environment variables or user config.
#
# Configuration Priority (highest to lowest):
# 1. Environment variables (runtime overrides)
# 2. Project config (./foundry-mcp.toml - this file)
# 3. User config (~/.foundry-mcp.toml)
# 4. XDG config (~/.config/foundry-mcp/config.toml)
# 5. Built-in defaults
# =============================================================================
# Workspace Configuration
# =============================================================================
[workspace]
# Where your specs live (auto-detected if not set).
# Good default: keep specs in ./specs.
specs_dir = "./specs"
# Notes inbox (defaults to specs_dir/.notes)
# Env var: FOUNDRY_MCP_NOTES_DIR
notes_dir = "./specs/.notes"
# Research state storage (defaults to specs_dir/.research)
# Env var: FOUNDRY_MCP_RESEARCH_DIR
research_dir = "./specs/.research"
# =============================================================================
# Logging Configuration
# =============================================================================
[logging]
# Log level: DEBUG, INFO, WARNING, ERROR
level = "INFO"
# JSON logs are easier to ingest; set false for human-readable logs.
structured = true
# =============================================================================
# Tools Configuration
# =============================================================================
[tools]
# Disable specific tools to reduce prompt size.
# Tool descriptions are loaded into the model's context on each message.
# Good default: disable setup-only tools you do not use day-to-day.
#
# Available tools:
# health - Liveness/readiness checks (used by setup)
# plan - Plan creation and review workflows
# pr - Pull request creation
# error - Error collection and querying
# journal - Implementation journals
# authoring - Spec authoring operations
# review - Fidelity and code reviews
# spec - Spec management
# task - Task management
# provider - AI provider status
# environment - Environment setup and detection
# lifecycle - Spec lifecycle transitions
# verification - Verification workflows
# server - Server introspection
# test - Test runner integration
# research - Research workflows (chat, consensus, thinkdeep, ideate, deep)
#
# Default: disable tools not needed, or only needed during setup
disabled_tools = ["error", "health"]
# Environment variable alternative: FOUNDRY_MCP_DISABLED_TOOLS (comma-separated)
# Example: FOUNDRY_MCP_DISABLED_TOOLS=error,research
# =============================================================================
# Observability Configuration
# =============================================================================
#
# Requires optional dependencies:
# - For OpenTelemetry: pip install foundry-mcp[tracing]
# - For Prometheus: pip install foundry-mcp[metrics]
# - For both: pip install foundry-mcp[observability]
#
# When dependencies are not installed, all observability features gracefully
# degrade to no-ops with zero performance overhead.
[observability]
# Master switch for all observability features
# Set to true to enable, then configure individual providers below
enabled = false
# OpenTelemetry tracing configuration
#otel_enabled = false
#otel_endpoint = "localhost:4317" # OTLP gRPC endpoint
#otel_service_name = "foundry-mcp" # Service name in traces
#otel_sample_rate = 1.0 # Sampling rate: 0.0 (none) to 1.0 (all)
# Prometheus metrics configuration
##prometheus_enabled = false
#prometheus_port = 0 # HTTP port for /metrics (0 = no server)
#prometheus_host = "0.0.0.0" # HTTP server bind address
#prometheus_namespace = "foundry_mcp" # Metric name prefix
# =============================================================================
# Health Checks Configuration
# =============================================================================
[health]
# Health probes for liveness/readiness.
enabled = false
#liveness_timeout = 1.0
#readiness_timeout = 5.0
#health_timeout = 10.0
# Disk space thresholds (MB)
#disk_space_threshold_mb = 100
#disk_space_warning_mb = 500
# =============================================================================
# Error Collection Configuration
# =============================================================================
#
# Stores error logs for observability and debugging.
# Errors are stored in append-only JSONL format with automatic cleanup.
[error_collection]
# Enable error collection
enabled = false
# Storage path (default: ~/.foundry-mcp/errors)
# Uncomment to customize:
# storage_path = "~/.foundry-mcp/errors"
# Delete records older than this many days
#retention_days = 30
# Maximum number of error records to keep
#max_errors = 10000
# Include stack traces in error records (useful for debugging)
#include_stack_traces = true
# Redact sensitive data from input parameters
#redact_inputs = true
# =============================================================================
# Metrics Persistence Configuration
# =============================================================================
#
# Persist time-series metrics to disk so they survive restarts.
[metrics_persistence]
# Enable metrics persistence (default: false)
enabled = false
# Storage path (default: ~/.foundry-mcp/metrics)
# storage_path = "~/.foundry-mcp/metrics"
# Delete records older than this many days
#retention_days = 7
# Maximum number of metric records to keep
#max_records = 100000
# Bucket interval for aggregation (seconds)
#bucket_interval_seconds = 60
# Flush interval to disk (seconds)
#flush_interval_seconds = 30
# Persist a subset of metrics (empty list = persist all)
#persist_metrics = [
# "tool_invocations_total",
# "tool_duration_seconds",
# "tool_errors_total",
# "health_status",
#]
# =============================================================================
# Implement Command Configuration
# =============================================================================
#
# Default flags for the /implement command. These can be overridden via CLI flags.
# NOTE: Use [workflow].mode for autonomous execution control.
[implement]
# Use subagent(s) for implementation (off by default; enable for focus)
delegate = false
# Run subagents concurrently for independent tasks (implies delegate=true)
parallel = false
# =============================================================================
# Git Workflow Configuration
# =============================================================================
[git]
# Enable git-aware workflows (automatic commit prompts, commit cadence, etc.)
# Good default: false until you want automated prompts.
enabled = false
# Determine when to offer automatic commits: "manual", "task", or "phase"
commit_cadence = "phase"
# Control automated behaviors
auto_commit = false
auto_push = false
auto_pr = false
# Show staged file preview before committing (recommended)
show_before_commit = true
# =============================================================================
# Workflow Configuration
# =============================================================================
#
# This section is the SINGLE SOURCE OF TRUTH for autonomous execution mode.
# The deprecated [implement].auto setting is superseded by workflow.mode.
[workflow]
# Execution mode:
# "single" - One task at a time with user approval
# "autonomous" - Execute all tasks automatically until completion or blocker
# "batch" - Execute batch_size tasks, then pause for review
# Good default: "single"
mode = "single"
# Automatically run validation after task completion
auto_validate = true
# Enable journaling of task completions
journal_enabled = true
# Number of tasks to execute in batch mode
batch_size = 5
# Context usage threshold (%) to trigger automatic pause
# When context reaches this threshold, autonomous/batch mode pauses
context_threshold = 85
# =============================================================================
# AI Consultation Configuration
# =============================================================================
[consultation]
# Default timeout for AI provider calls in seconds
default_timeout = 600
# Number of retry attempts per provider for transient failures
max_retries = 2
# Delay between retry attempts in seconds
retry_delay = 5.0
# Enable fallback to next available provider when one fails
fallback_enabled = true
# Cache time-to-live in seconds for consultation results
cache_ttl = 3600
# Provider priority list - first available provider wins
# Update order to match your preferred providers/models.
# Note: claude-zai is available for users with a custom claude-zai alias
priority = [
"[cli]codex:gpt-5.2-codex",
"[cli]opencode:openai/gpt-5.2-codex",
"[cli]cursor-agent:gpt-5.2-codex",
"[cli]gemini:pro",
"[cli]claude:opus",
# "[cli]claude-zai:opus", # Uncomment if you have claude-zai alias configured
]
# Per-provider overrides (optional)
# [consultation.overrides]
# "[cli]opencode:openai/gpt-5.2-codex" = { timeout = 600 }
# Per-workflow overrides
[consultation.workflows.fidelity_review]
# Good default: 2 models for consensus
min_models = 2
timeout_override = 600.0
default_review_type = "full"
[consultation.workflows.plan_review]
# Good default: 2 models for consensus
min_models = 2
default_review_type = "full"
[consultation.workflows.markdown_plan_review]
# Good default: 2 models
min_models = 2
timeout_override = 600.0
default_review_type = "full"
# =============================================================================
# Research Workflow Configuration
# =============================================================================
[research]
# Enable research tools (chat, consensus, thinkdeep, ideate, deep-research)
enabled = true
# Default LLM provider for research workflows
# Supports ProviderSpec format: "[cli]gemini:pro" or simple: "gemini"
default_provider = "[cli]gemini:pro"
# Providers for CONSENSUS workflow (multi-model consultation)
# Use the providers you have installed.
# Note: claude-zai is available for users with a custom claude-zai alias
consensus_providers = [
"[cli]gemini:pro",
"[cli]codex:gpt-5.2-codex",
"[cli]opencode:openai/gpt-5.2-codex",
"[cli]cursor-agent:gpt-5.2-codex",
"[cli]claude:opus",
# "[cli]claude-zai:opus", # Uncomment if you have claude-zai alias configured
]
# State TTL in hours before cleanup
ttl_hours = 24
# Maximum messages per conversation thread
max_messages_per_thread = 100
# Default timeout for provider calls in seconds
# Minimum recommended: 600s for AI CLI providers
default_timeout = 600.0
# Maximum investigation depth for THINKDEEP workflow
thinkdeep_max_depth = 5
# Perspectives for IDEATE brainstorming
ideate_perspectives = ["technical", "creative", "practical", "visionary"]
# -----------------------------------------------------------------------------
# Deep Research Settings
# -----------------------------------------------------------------------------
# Maximum refinement iterations
deep_research_max_iterations = 3
# Maximum sub-queries per decomposition
deep_research_max_sub_queries = 5
# Maximum sources per sub-query
deep_research_max_sources = 10
# Follow and extract content from URLs
deep_research_follow_links = true
# Whole workflow timeout in seconds (recommended: 600s)
deep_research_timeout = 600.0
# Maximum parallel operations
deep_research_max_concurrent = 3
# Write audit artifacts for debugging
deep_research_audit_artifacts = true
# Research mode: controls source prioritization
# - "general" : No domain preferences (default)
# - "academic" : Prioritizes journals, publishers, preprints
# - "technical" : Prioritizes official docs, arxiv, Stack Overflow
deep_research_mode = "technical"
# Search providers (in priority order)
# Available: tavily, perplexity, google, semantic_scholar
deep_research_providers = [
"tavily",
#"perplexity",
"semantic_scholar"
]
# -----------------------------------------------------------------------------
# Per-Phase Timeouts (override deep_research_timeout)
# Minimum recommended: 600s per operation for AI CLI providers
# -----------------------------------------------------------------------------
deep_research_planning_timeout = 600.0 # Query decomposition
deep_research_analysis_timeout = 600.0 # Finding extraction
deep_research_synthesis_timeout = 600.0 # Report generation (may take longer)
deep_research_refinement_timeout = 600.0 # Gap identification
# -----------------------------------------------------------------------------
# Per-Phase Providers (override default_provider)
# -----------------------------------------------------------------------------
# Supports ProviderSpec format for model selection:
# "[cli]gemini:pro"
# "[cli]claude:opus"
# "[cli]claude-zai:opus" # If you have claude-zai alias configured
# "[cli]opencode:openai/gpt-5.2-codex"
# "[cli]codex:gpt-5.2-codex"
# "[cli]cursor-agent:gpt-5.2-codex"
deep_research_planning_provider = "[cli]gemini:flash"
deep_research_analysis_provider = "[cli]gemini:pro"
deep_research_synthesis_provider = "[cli]gemini:pro"
deep_research_refinement_provider = "[cli]gemini:pro"
# -----------------------------------------------------------------------------
# Per-Phase Fallback Provider Lists (Retry & Resilience)
# -----------------------------------------------------------------------------
# Each phase can have an ordered list of fallback providers.
# On failure/timeout, the workflow retries with backoff, then tries
# the next provider in the list until success or exhaustion.
# Empty list = no fallback (use only the primary provider)
# Planning phase: query decomposition (can use faster/cheaper models)
deep_research_planning_providers = [
"[cli]gemini:flash",
"[cli]codex:gpt-5.1-codex-mini",
"[cli]cursor-agent:gpt-5.2-codex-fast",
"[cli]claude:sonnet",
"[cli]opencode:openai/gpt-5.1-codex-mini"
]
# Analysis phase: finding extraction
deep_research_analysis_providers = [
"[cli]gemini:pro",
"[cli]codex:gpt-4.1",
"[cli]opencode:openai/gpt-4.1",
"[cli]cursor-agent:gpt-4.1",
"[cli]claude:opus"
]
# Synthesis phase: report generation (may benefit from stronger models)
deep_research_synthesis_providers = [
"[cli]gemini:pro",
"[cli]codex:gpt-5.2-codex",
"[cli]opencode:openai/gpt-5.2-codex",
"[cli]cursor-agent:gpt-5.2-codex",
"[cli]claude:opus"
]
# Refinement phase: gap identification
deep_research_refinement_providers = [
"[cli]gemini:pro",
"[cli]codex:gpt-5.2-codex",
"[cli]opencode:openai/gpt-5.2-codex",
"[cli]cursor-agent:gpt-5.2-codex",
"[cli]claude:opus"
]
# Retry settings for all deep research phases
deep_research_max_retries = 2 # Retry attempts per provider before fallback
deep_research_retry_delay = 5.0 # Seconds between retries
# -----------------------------------------------------------------------------
# Search Rate Limiting
# -----------------------------------------------------------------------------
search_rate_limit = 60 # Requests per minute (global)
max_concurrent_searches = 3 # Concurrent search requests
# -----------------------------------------------------------------------------
# Token Management Configuration
# -----------------------------------------------------------------------------
# Controls token budget management for deep research workflows.
# When enabled, content is intelligently compressed or archived to fit
# within model context limits.
# Master switch for token management features
# When disabled, all token budget calculations are skipped
token_management_enabled = true
# Safety margin: fraction of budget reserved as buffer (0.0 - 1.0)
# Higher values provide more headroom but reduce usable context
# Default: 0.15 (15% buffer)
token_safety_margin = 0.15
# Runtime overhead: tokens reserved for CLI/IDE runtime context
# This accounts for system prompts, conversation history, and tool schemas
# that consume context before your research content.
#
# Recommended values by environment:
# Claude Code: 60000 (default, ~60K for system + tools + history)
# Cursor Agent: 40000 (less overhead than Claude Code)
# Codex/OpenCode: 30000 (minimal IDE integration overhead)
# Gemini CLI: 20000 (lightweight CLI)
# Direct API: 10000 (minimal overhead)
#
# Tip: If you see "context exceeded" errors, increase this value.
# If content is being dropped unnecessarily, decrease it.
runtime_overhead = 60000
# -----------------------------------------------------------------------------
# Summarization Configuration
# -----------------------------------------------------------------------------
# When content exceeds budget, summarization compresses it to fit.
# Uses LLM providers to generate condensed versions while preserving
# key information.
# Primary provider for summarization (uses default_provider if not set)
# summarization_provider = "[cli]gemini:flash"
# Fallback providers for summarization (tried in order if primary fails)
# summarization_providers = ["[cli]claude:haiku", "[cli]codex:gpt-4.1-mini"]
# Timeout per summarization request in seconds
summarization_timeout = 60.0
# Cache summarization results to avoid redundant API calls
# Caches by content hash + summarization level + provider
summarization_cache_enabled = true
# -----------------------------------------------------------------------------
# Content Dropping & Archive Configuration
# -----------------------------------------------------------------------------
# When budget is exhausted and summarization isn't sufficient,
# low-priority content can be dropped. Optionally archive dropped
# content to disk for later retrieval.
# Allow dropping low-priority content when budget is exhausted
# When false: workflow may fail if content exceeds budget
# When true: drops lowest-priority items to fit budget
allow_content_dropping = false
# Archive dropped/compressed content to disk
# Enables potential future restoration and audit trail
content_archive_enabled = false
# TTL for archived content in hours (default: 168 = 7 days)
# Older content is automatically cleaned up
content_archive_ttl_hours = 168
# Directory for content archive storage
# Default: research_dir/.archive (e.g., specs/.research/.archive)
# research_archive_dir = "~/.foundry-mcp/research-archive"
# -----------------------------------------------------------------------------
# Search Provider Rate Limits (per-provider overrides)
# -----------------------------------------------------------------------------
[research.per_provider_rate_limits]
tavily = 60
perplexity = 60
semantic_scholar = 100
# -----------------------------------------------------------------------------
# Tavily Search Provider Configuration
# -----------------------------------------------------------------------------
# Tavily is optimized for AI applications. Get API key at https://tavily.com/
# Search depth: affects result quality and API credit cost
# - "basic" : Standard search (default, 1x credits)
# - "advanced" : Deeper analysis with more content (2x credits)
# - "fast" : Reduced latency
# - "ultra_fast" : Minimal latency
tavily_search_depth = "basic"
# Search topic: "general" or "news"
tavily_topic = "general"
# Days limit for news search (1-365, only when topic="news")
# tavily_news_days = 7
# Include image results
tavily_include_images = false
# ISO 3166-1 alpha-2 country code to boost results (e.g., "US", "GB", "DE")
# tavily_country = "US"
# Chunks per source for advanced search (1-5)
tavily_chunks_per_source = 3
# Let Tavily auto-configure parameters based on query intent
tavily_auto_parameters = false
# -----------------------------------------------------------------------------
# Tavily Extract Provider Configuration
# -----------------------------------------------------------------------------
# Extract structured content from URLs for deeper analysis
# Extract depth: "basic" or "advanced"
tavily_extract_depth = "basic"
# Include images in extracted content
tavily_extract_include_images = false
# Enable extract as follow-up step in deep research workflow
# When true, deep research will extract full content from top search results
tavily_extract_in_deep_research = false
# Maximum URLs to extract per deep research run
tavily_extract_max_urls = 5
# -----------------------------------------------------------------------------
# Document Digest Configuration
# -----------------------------------------------------------------------------
# Controls automatic content compression for large research sources.
# When enabled, lengthy content is summarized into structured digests
# with key findings and evidence snippets, reducing token usage while
# preserving essential information.
# Digest policy: controls when digestion is applied
# - "off" : Never digest content (preserve raw text)
# - "auto" : Digest when content exceeds min_chars threshold (default)
# - "always" : Always digest eligible sources regardless of size
deep_research_digest_policy = "auto"
# Minimum character count before digest is applied (auto mode only)
deep_research_digest_min_chars = 10000
# Maximum sources to digest per batch
deep_research_digest_max_sources = 8
# Timeout per digest operation in seconds
deep_research_digest_timeout = 180.0
# Maximum concurrent digest operations
deep_research_digest_max_concurrent = 3
# Include evidence snippets (direct quotes) in digests
deep_research_digest_include_evidence = true
# Maximum characters per evidence snippet
deep_research_digest_evidence_max_chars = 600
# Maximum evidence snippets per digest
deep_research_digest_max_evidence_snippets = 5
# Fetch and extract PDF content from URLs
# When true, PDFs are downloaded, text extracted, and digested
# Requires additional processing time; disabled by default
deep_research_digest_fetch_pdfs = false
# Archive canonical text for digested sources
# When true, original full text is saved to disk before digesting
deep_research_archive_content = false
# Days to retain archived digest content (0 = keep indefinitely)
deep_research_archive_retention_days = 30
# Primary LLM provider for digest operations
# Uses analysis provider if not set
# deep_research_digest_provider = "[cli]gemini:flash"
# Fallback providers for digest (tried in order if primary fails)
# deep_research_digest_providers = [
# "[cli]claude:haiku",
# "[cli]codex:gpt-4.1-mini",
# ]
# -----------------------------------------------------------------------------
# Perplexity Search Provider Configuration
# -----------------------------------------------------------------------------
# Perplexity provides AI-powered search with citations.
# Get API key at https://www.perplexity.ai/settings/api
# Search context size: affects result depth and API cost
# - "low" : Minimal context, fastest responses
# - "medium" : Balanced context (default)
# - "high" : Maximum context, most comprehensive
perplexity_search_context_size = "medium"
# Maximum tokens for response
perplexity_max_tokens = 50000
# Maximum tokens per page
perplexity_max_tokens_per_page = 2048
# Time filter for results: "day", "week", "month", "year"
# perplexity_recency_filter = "week"
# ISO 3166-1 alpha-2 country code to boost results (e.g., "US", "GB", "DE")
# perplexity_country = "US"
# -----------------------------------------------------------------------------
# Model Context Overrides (per-model token limits)
# -----------------------------------------------------------------------------
# Override default context/output limits for specific models.
# Useful when you know your model has different limits than the defaults.
# Format: "provider" or "provider:model" as the key
#
# Available override fields:
# context_window - Maximum input context tokens
# max_output_tokens - Maximum output tokens
# budgeting_mode - "input_only" or "combined"
# output_reserved - Tokens reserved for output (combined mode only)
#
# Example overrides:
# [research.model_context_overrides."claude:opus"]
# context_window = 180000 # Reduce from default 200K
# max_output_tokens = 16000 # Reduce from default 32K
#
# [research.model_context_overrides."gemini"]
# context_window = 500000 # Provider-wide override for all Gemini models
# -----------------------------------------------------------------------------
# Semantic Scholar Search Provider Configuration
# -----------------------------------------------------------------------------
# Semantic Scholar provides academic paper search with TLDR summaries.
# API key is optional but recommended for higher rate limits.
# Filter by publication types (list of types)
# Valid types: Review, JournalArticle, Conference, CaseReport, ClinicalTrial,
# Dataset, Editorial, LettersAndComments, MetaAnalysis, News,
# Study, Book, BookSection
# semantic_scholar_publication_types = ["JournalArticle", "Conference"]
# Sort results by field: citationCount, publicationDate, paperId
# semantic_scholar_sort_by = "citationCount"
# Sort direction: asc or desc (default: desc)
# semantic_scholar_sort_order = "desc"
# Include TLDR and extended metadata (default: true)
# Set to false for faster responses with less metadata
# semantic_scholar_use_extended_fields = true
# -----------------------------------------------------------------------------
# Search Provider Credentials (optional, prefer env vars)
# -----------------------------------------------------------------------------
# API keys can be set here or via environment variables (preferred):
# TAVILY_API_KEY, PERPLEXITY_API_KEY, SEMANTIC_SCHOLAR_API_KEY
#
# tavily_api_key = "tvly-..."
# perplexity_api_key = "pplx-..."
# semantic_scholar_api_key = "..."
# =============================================================================
# Test Runner Configuration
# =============================================================================
#
# Configure which test runner to use and customize runner settings.
# The foundry-setup command can auto-detect and configure this section.
#
# Supported runners (built-in defaults): pytest, go, npm, jest, make
# Custom runners can be defined in [test.runners.*] sections.
[test]
# Default runner to use when running tests
# Valid values: pytest, go, npm, jest, make, or any custom runner name
default_runner = "pytest"
# Example custom runner:
# [test.runners.go]
# command = ["go", "test"]
# run_args = ["./..."]
# pattern = "*_test.go"
# timeout = 300
