config.yaml.template

# MagicTunnel Configuration Template
# Copy this file to config.yaml and customize for your environment
# All settings can be overridden via environment variables
#
# IMPORTANT: Legacy mcp_proxy, mcp_servers, and remote_mcp configurations have been removed.
# Use the new external_mcp system for connecting to external MCP servers.

# =============================================================================
# SERVER CONFIGURATION
# =============================================================================
server:
  host: "127.0.0.1"        # Server bind address (env: MCP_HOST)
  port: 3000               # Server port 1-65535 (env: MCP_PORT)
                           # Note: gRPC server automatically runs on port + 1000 (e.g., 4000)
  websocket: true          # Enable WebSocket support (env: MCP_WEBSOCKET)
  timeout: 30              # Request timeout in seconds (env: MCP_TIMEOUT)

  # TLS/SSL Configuration (Optional)
  tls:
    mode: "disabled"       # TLS mode: disabled|application|behind_proxy|auto
    cert_file: null        # Path to certificate file (PEM format)
    key_file: null         # Path to private key file (PEM format)
    ca_file: null          # Path to CA certificate file (optional)
    behind_proxy: false    # Whether running behind a reverse proxy
    trusted_proxies:       # List of trusted proxy IP ranges (CIDR notation)
      - "10.0.0.0/8"
      - "172.16.0.0/12"
      - "192.168.0.0/16"
      - "127.0.0.1/32"
    min_tls_version: "1.2" # Minimum TLS version (1.2, 1.3)
    cipher_suites: null    # Custom cipher suites (optional)
    hsts_enabled: true     # Enable HTTP Strict Transport Security (HSTS)
    hsts_max_age: 31536000 # HSTS max age in seconds (1 year)
    hsts_include_subdomains: false
    hsts_preload: false
    require_forwarded_proto: false
    require_forwarded_for: false
    auto_detect_headers:   # Auto-detection headers to check
      - "X-Forwarded-Proto"
      - "X-Forwarded-For"
      - "X-Real-IP"
    fallback_mode: "application"

# =============================================================================
# CAPABILITY REGISTRY CONFIGURATION
# =============================================================================
registry:
  type: "file"             # Registry type: "file" (env: MCP_REGISTRY_TYPE)
  paths:                   # Paths to scan for capability files (env: MCP_REGISTRY_PATHS)
    - "./capabilities"     # Default capabilities directory
                           # Note: External capabilities are auto-generated by external_mcp discovery
  hot_reload: true         # Enable file watching for changes (env: MCP_HOT_RELOAD)
  validation:
    strict: true           # Strict validation mode
    allow_unknown_fields: false



# =============================================================================
# AUTHENTICATION CONFIGURATION (Optional)
# =============================================================================
# Uncomment and configure one of the following authentication methods:

# API Key Authentication
# auth:
#   enabled: true
#   type: "api_key"
#   api_keys:
#     keys:
#       - key: "your_secure_api_key_here_min_16_chars"
#         name: "Admin Key"
#         description: "Administrative access"
#         permissions: ["read", "write", "admin"]
#         active: true
#         expires_at: "2025-12-31T23:59:59Z"  # Optional ISO 8601 format
#       - key: "readonly_key_here_min_16_chars"
#         name: "Read Only Key"
#         description: "Read-only access"
#         permissions: ["read"]
#         active: true
#     require_header: true
#     header_name: "Authorization"
#     header_format: "Bearer {key}"

# OAuth Authentication
# auth:
#   enabled: true
#   type: "oauth"
#   oauth:
#     provider: "google"    # or "github", "microsoft", "custom"
#     client_id: "your-oauth-client-id"
#     client_secret: "your-oauth-client-secret"
#     auth_url: "https://accounts.google.com/oauth/authorize"
#     token_url: "https://oauth2.googleapis.com/token"

# JWT Authentication
# auth:
#   enabled: true
#   type: "jwt"
#   jwt:
#     secret: "your_jwt_secret_key_at_least_32_characters_long"
#     algorithm: "HS256"     # HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384
#     expiration: 3600       # Token expiration in seconds
#     issuer: "magictunnel"  # Optional JWT issuer
#     audience: "mcp-clients" # Optional JWT audience

# =============================================================================
# MCP CLIENT CONFIGURATION
# =============================================================================
# Configuration for MCP client connections (used when connecting to external MCP servers)
mcp_client:
  connect_timeout_secs: 30      # Connection timeout in seconds
  request_timeout_secs: 60      # Request timeout in seconds
  max_reconnect_attempts: 5     # Maximum reconnection attempts
  reconnect_delay_secs: 5       # Delay between reconnection attempts
  auto_reconnect: true          # Enable automatic reconnection
  protocol_version: "2025-03-26" # MCP protocol version to use
  client_name: "magictunnel"    # Client name for MCP handshake (defaults to package name)
  client_version: "0.2.49"      # Client version for MCP handshake (defaults to package version)

# =============================================================================
# EXTERNAL MCP CONFIGURATION (Claude Desktop Format)
# =============================================================================
# Enable discovery and integration of external MCP servers using Claude Desktop's
# exact configuration format for maximum compatibility.
#
# MIGRATION NOTE: The legacy mcp_proxy, mcp_servers, and remote_mcp configurations
# have been removed. Use this external_mcp system instead.
external_mcp:
  enabled: false                    # Enable external MCP discovery (env: EXTERNAL_MCP_ENABLED)
  config_file: "./external-mcp-servers.yaml"  # Path to external MCP servers config file
  capabilities_output_dir: "./capabilities/external-mcp"  # Where to generate capability files
  refresh_interval_minutes: 60      # How often to refresh capabilities (env: EXTERNAL_MCP_REFRESH_INTERVAL)

  # Container Configuration (for Docker/Podman MCP servers)
  containers:
    runtime: "docker"               # Container runtime: docker|podman (env: CONTAINER_RUNTIME)
    node_image: "node:18-alpine"    # Default Node.js image for MCP servers
    python_image: "python:3.11-alpine"  # Default Python image for MCP servers
    network_mode: "bridge"          # Container network mode
    run_args: ["--rm", "-i"]        # Additional container run arguments

  # Note: External MCP uses the global conflict_resolution configuration below

# =============================================================================
# GLOBAL CONFLICT RESOLUTION CONFIGURATION
# =============================================================================
# Configuration for resolving conflicts when tools from different sources have the same name
# This applies to conflicts between local tools and external MCP tools

conflict_resolution:
  # Strategy for resolving tool name conflicts
  # Options: local_first, proxy_first, first_found, reject, prefix
  strategy: "LocalFirst"         # Strategy: LocalFirst|ProxyFirst|FirstFound|Reject|Prefix (env: CONFLICT_RESOLUTION_STRATEGY)

  # Prefix for local tools when using prefix strategy
  local_prefix: "local"           # Prefix for local tools (env: CONFLICT_RESOLUTION_LOCAL_PREFIX)

  # Format for external/proxy tool prefixes when using prefix strategy
  # Use {server} placeholder for server name
  proxy_prefix_format: "{server}" # Format for external tool prefixes (env: CONFLICT_RESOLUTION_PROXY_PREFIX_FORMAT)

  # Whether to log conflict resolutions
  log_conflicts: true             # Log conflicts (env: CONFLICT_RESOLUTION_LOG_CONFLICTS)

  # Whether to include conflict metadata in tool definitions
  include_conflict_metadata: true # Include metadata (env: CONFLICT_RESOLUTION_INCLUDE_METADATA)

# =============================================================================
# SMART DISCOVERY CONFIGURATION
# =============================================================================
# Configuration for the Smart Tool Discovery system that provides intelligent
# tool selection based on natural language requests

smart_discovery:
  enabled: true                           # Enable smart discovery (env: SMART_DISCOVERY_ENABLED)
  tool_selection_mode: "rule_based"       # Tool selection mode: rule_based|llm_based|semantic_based|hybrid (env: SMART_DISCOVERY_MODE)
  default_confidence_threshold: 0.7       # Default confidence threshold for tool matching (env: SMART_DISCOVERY_THRESHOLD)
  max_tools_to_consider: 10               # Maximum number of tools to consider for matching (env: SMART_DISCOVERY_MAX_TOOLS)
  max_high_quality_matches: 5             # Maximum high-quality matches to collect before stopping processing (env: SMART_DISCOVERY_MAX_HIGH_QUALITY_MATCHES)
  high_quality_threshold: 0.95            # Confidence threshold for considering a match as high-quality (env: SMART_DISCOVERY_HIGH_QUALITY_THRESHOLD)
  use_fuzzy_matching: true                # Enable fuzzy matching for tool names (env: SMART_DISCOVERY_FUZZY)
  enable_sequential_mode: true            # Enable sequential mode for multi-step workflows (default: true) (env: SMART_DISCOVERY_SEQUENTIAL_MODE)

  # LLM Tool Selection Configuration (for llm_based mode)
  llm_tool_selection:
    enabled: false                        # Enable LLM-based tool selection (env: SMART_DISCOVERY_LLM_ENABLED)
    provider: "openai"                    # LLM provider: openai|anthropic|ollama (env: SMART_DISCOVERY_LLM_PROVIDER)
    model: "gpt-4o-mini"                  # Model name to use (env: SMART_DISCOVERY_LLM_MODEL)
    api_key: null                         # API key (set via api_key_env)
    api_key_env: "OPENAI_API_KEY"         # Environment variable for API key (env: SMART_DISCOVERY_LLM_API_KEY_ENV)
    base_url: null                        # Custom base URL (env: SMART_DISCOVERY_LLM_BASE_URL)
    timeout: 30                           # Request timeout in seconds (env: SMART_DISCOVERY_LLM_TIMEOUT)
    max_retries: 3                        # Maximum retries for failed requests (env: SMART_DISCOVERY_LLM_MAX_RETRIES)
    batch_size: 15                        # Batch size for processing tools (env: SMART_DISCOVERY_LLM_BATCH_SIZE)
    max_context_tokens: 4000              # Maximum context tokens to use (env: SMART_DISCOVERY_LLM_MAX_TOKENS)

  # LLM Parameter Mapping Configuration
  llm_mapper:
    enabled: true                         # Enable LLM parameter mapping (env: SMART_DISCOVERY_MAPPER_ENABLED)
    provider: "openai"                    # LLM provider: openai|anthropic|ollama (env: SMART_DISCOVERY_MAPPER_PROVIDER)
    model: "gpt-4o-mini"                  # Model name to use (env: SMART_DISCOVERY_MAPPER_MODEL)
    api_key_env: "OPENAI_API_KEY"         # Environment variable for API key (env: SMART_DISCOVERY_MAPPER_API_KEY_ENV)
    base_url: null                        # Custom base URL (env: SMART_DISCOVERY_MAPPER_BASE_URL)
    timeout: 30                           # Request timeout in seconds (env: SMART_DISCOVERY_MAPPER_TIMEOUT)
    max_retries: 3                        # Maximum retries for failed requests (env: SMART_DISCOVERY_MAPPER_MAX_RETRIES)

  # Cache Configuration
  cache:
    enabled: true                         # Enable caching (env: SMART_DISCOVERY_CACHE_ENABLED)
    max_tool_matches: 1000               # Maximum number of entries in tool matching cache
    tool_match_ttl: 3600                 # TTL for tool matching cache entries (seconds)
    max_llm_responses: 500               # Maximum number of entries in LLM response cache
    llm_response_ttl: 1800               # TTL for LLM response cache entries (seconds)
    max_registry_entries: 100            # Maximum number of entries in registry cache
    registry_ttl: 300                    # TTL for registry cache entries (seconds)

  # Fallback Configuration
  fallback:
    enabled: true                         # Enable fallback suggestions (env: SMART_DISCOVERY_FALLBACK_ENABLED)
    min_confidence_threshold: 0.3         # Minimum confidence for fallback suggestions (env: SMART_DISCOVERY_FALLBACK_MIN_CONFIDENCE)
    max_fallback_suggestions: 5           # Maximum number of fallback suggestions (env: SMART_DISCOVERY_FALLBACK_MAX_SUGGESTIONS)
    enable_fuzzy_fallback: true           # Enable fuzzy matching fallback (env: SMART_DISCOVERY_FALLBACK_FUZZY)
    enable_keyword_fallback: true         # Enable keyword-based fallback (env: SMART_DISCOVERY_FALLBACK_KEYWORDS)
    enable_category_fallback: true        # Enable category-based fallback (env: SMART_DISCOVERY_FALLBACK_CATEGORIES)
    enable_partial_match_fallback: true   # Enable partial match fallback (env: SMART_DISCOVERY_FALLBACK_PARTIAL)

  # Semantic Search Configuration
  semantic_search:
    enabled: false                        # Enable semantic search (env: SMART_DISCOVERY_SEMANTIC_ENABLED)
    model_name: "all-MiniLM-L6-v2"        # Embedding model name (env: SMART_DISCOVERY_SEMANTIC_MODEL)
    similarity_threshold: 0.7             # Minimum similarity threshold for semantic matches (env: SMART_DISCOVERY_SEMANTIC_THRESHOLD)
    max_results: 10                       # Maximum number of semantic search results (env: SMART_DISCOVERY_SEMANTIC_MAX_RESULTS)
    
    # Persistent Storage Configuration
    storage:
      embeddings_file: "./data/embeddings/tool_embeddings.bin"  # Binary file for embeddings storage
      metadata_file: "./data/embeddings/tool_metadata.json"     # JSON file for tool metadata
      hash_file: "./data/embeddings/content_hashes.json"        # JSON file for content hash validation
      backup_count: 3                     # Number of backup files to maintain
      auto_backup: true                   # Automatically backup embeddings on updates
      compression: false                  # Enable compression for storage files (not yet implemented)
    
    # Model Configuration
    model:
      cache_dir: "./data/models"          # Directory to cache downloaded models (env: SMART_DISCOVERY_SEMANTIC_CACHE_DIR)
      device: "cpu"                       # Device to use: cpu|cuda|mps (env: SMART_DISCOVERY_SEMANTIC_DEVICE)
      max_sequence_length: 512            # Maximum sequence length for embeddings
      batch_size: 32                      # Batch size for embedding generation
      normalize_embeddings: true          # Normalize embeddings to unit vectors
      
    # Performance Configuration
    performance:
      lazy_loading: true                  # Load embeddings only when needed
      embedding_cache_size: 1000          # In-memory cache size for embeddings
      parallel_processing: true           # Enable parallel embedding generation
      worker_threads: 4                   # Number of worker threads for parallel processing

# =============================================================================
# TOOL VISIBILITY CONFIGURATION (Smart Tool Discovery)
# =============================================================================
# Configuration for managing tool visibility and Smart Tool Discovery system
# This enables hiding individual tools while keeping them available for discovery

visibility:
  # Hide individual tools when smart discovery is enabled (default: false)
  # When true, only smart_tool_discovery tool is exposed to MCP clients
  hide_individual_tools: false   # Hide individual tools (env: VISIBILITY_HIDE_INDIVIDUAL_TOOLS)

  # Only expose smart_tool_discovery tool (default: false)
  # This is the ultimate Smart Tool Discovery mode - single tool interface
  expose_smart_discovery_only: false # Smart discovery only (env: VISIBILITY_EXPOSE_SMART_DISCOVERY_ONLY)

  # Allow individual tools to override hidden setting (default: true)
  # When false, global settings take precedence over tool-level hidden flags
  allow_override: true            # Allow tool-level overrides (env: VISIBILITY_ALLOW_OVERRIDE)

  # Default hidden state for new tools (default: false)
  # When true, new tools are hidden by default and must be explicitly shown
  default_hidden: false          # Default hidden state (env: VISIBILITY_DEFAULT_HIDDEN)


# =============================================================================
# EXTERNAL MCP SERVERS (Claude Desktop Format)
# =============================================================================
# LEGACY mcp_servers, mcp_proxy, and remote_mcp configurations have been REMOVED.
# Use the external_mcp system above instead.
#
# Create separate configuration files for external MCP servers:
#
# Copy external-mcp-servers.yaml.template to external-mcp-servers.yaml
# The template includes comprehensive documentation and examples for:
# - Claude Desktop compatible configuration format
# - Process spawning (npx, uv run, docker run, etc.)
# - Environment variable configuration
# - Working directory settings
# - Real working examples for popular MCP servers
#
# Benefits of the new external_mcp approach:
# - Claude Desktop compatibility (exact same format)
# - Automatic process management and lifecycle
# - Automatic capability file generation
# - Hot-reload support for configuration changes
# - Container support (Docker/Podman)
# - Built-in conflict resolution
#
# To get started with external MCP servers:
# 1. Set external_mcp.enabled: true above
# 2. Copy external-mcp-servers.yaml.template to external-mcp-servers.yaml
# 3. Configure your MCP servers in the new file (same format as Claude Desktop)
# 4. Set required environment variables for authentication
# 5. The system will automatically spawn processes and discover capabilities
# 6. Tool conflicts are resolved automatically (local tools take precedence)
#
# IMPORTANT: External MCP servers do NOT support 'enabled' or 'hidden' flags.
# To enable/disable a server: include/exclude it from the external-mcp-servers.yaml file.
# The 'enabled' and 'hidden' flags only apply to individual tools in capability files.

# =============================================================================
# ENVIRONMENT MONITORING CONFIGURATION
# =============================================================================
# Configuration for monitoring environment variables on the dashboard
# This section defines which environment variables are tracked and displayed
# in the web dashboard for system health monitoring
environment_monitoring:
  enabled: true                         # Enable environment variable monitoring (env: ENV_MONITORING_ENABLED)
  
  # API Keys to monitor (will be masked for security)
  api_keys:
    - name: "OpenAI API Key"
      env_var: "OPENAI_API_KEY"
      description: "OpenAI API key for LLM-based tool selection and parameter mapping"
      required_for: ["smart_discovery_llm", "smart_discovery_mapper"]
      category: "llm"
    - name: "Anthropic API Key"
      env_var: "ANTHROPIC_API_KEY"
      description: "Anthropic Claude API key for LLM-based tool selection and parameter mapping"
      required_for: ["smart_discovery_llm", "smart_discovery_mapper"]
      category: "llm"
    - name: "Smart Discovery LLM API Key"
      env_var: "SMART_DISCOVERY_LLM_API_KEY"
      description: "Dedicated API key for smart discovery LLM operations"
      required_for: ["smart_discovery_llm"]
      category: "llm"
      
  # System environment variables to monitor
  system_vars:
    # Environment Detection
    - name: "MagicTunnel Environment"
      env_var: "MAGICTUNNEL_ENV"
      description: "Current environment (development/production/staging)"
      category: "environment"
      default_value: "development"
      expected_values: ["development", "production", "staging", "test"]
    - name: "Node Environment"
      env_var: "NODE_ENV"
      description: "Node.js environment setting"
      category: "environment"
      default_value: "development"
      expected_values: ["development", "production", "staging", "test"]
    - name: "General Environment"
      env_var: "ENV"
      description: "General environment setting"
      category: "environment"
      default_value: "development"
      
    # Server Configuration
    - name: "Server Host"
      env_var: "MCP_HOST"
      description: "Server bind address override"
      category: "server"
      default_value: "0.0.0.0"
    - name: "Server Port"
      env_var: "MCP_PORT"
      description: "Server port override"
      category: "server"
      default_value: "3001"
    - name: "WebSocket Support"
      env_var: "MCP_WEBSOCKET"
      description: "Enable WebSocket support"
      category: "server"
      default_value: "true"
      expected_values: ["true", "false"]
    - name: "Request Timeout"
      env_var: "MCP_TIMEOUT"
      description: "Request timeout in seconds"
      category: "server"
      default_value: "30"
      
    # External MCP Configuration
    - name: "External MCP Enabled"
      env_var: "EXTERNAL_MCP_ENABLED"
      description: "Enable external MCP server integration"
      category: "integration"
      default_value: "true"
      expected_values: ["true", "false"]
    - name: "Container Runtime"
      env_var: "CONTAINER_RUNTIME"
      description: "Container runtime for external MCP servers"
      category: "integration"
      default_value: "docker"
      expected_values: ["docker", "podman"]
      
    # Smart Discovery Configuration
    - name: "Smart Discovery Enabled"
      env_var: "SMART_DISCOVERY_ENABLED"
      description: "Enable smart tool discovery system"
      category: "smart_discovery"
      default_value: "true"
      expected_values: ["true", "false"]
    - name: "Smart Discovery Mode"
      env_var: "SMART_DISCOVERY_MODE"
      description: "Tool selection mode for smart discovery"
      category: "smart_discovery"
      default_value: "hybrid"
      expected_values: ["rule_based", "llm_based", "semantic_based", "hybrid"]
      
    # External Services Configuration
    - name: "Ollama Base URL"
      env_var: "OLLAMA_BASE_URL"
      description: "Base URL for Ollama local LLM server"
      category: "external_services"
      default_value: "http://localhost:11434"
      
    # Logging Configuration
    - name: "Log Level"
      env_var: "RUST_LOG"
      description: "Rust logging level configuration"
      category: "logging"
      default_value: "info"
      expected_values: ["trace", "debug", "info", "warn", "error"]
    - name: "MCP Log Level"
      env_var: "MCP_LOG_LEVEL"
      description: "MCP-specific log level override"
      category: "logging"
      default_value: "info"
      expected_values: ["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"]
    - name: "Log Format"
      env_var: "MCP_LOG_FORMAT"
      description: "Log output format"
      category: "logging"
      default_value: "text"
      expected_values: ["json", "text"]

# =============================================================================
# LOGGING CONFIGURATION
# =============================================================================
logging:
  level: "info"            # Log level: debug|info|notice|warning|error|critical|alert|emergency (env: MCP_LOG_LEVEL)
  format: "text"           # Log format: json|text (env: MCP_LOG_FORMAT)
  file: null               # Optional: log to file instead of stdout

# =============================================================================
# ADVANCED CONFIGURATION OPTIONS (Optional)
# =============================================================================
# Note: The following advanced features have implementations in the codebase but are not yet
# exposed through the main configuration system. They are available for future integration:
#
# - Security Headers: Implemented in src/tls/security_headers.rs (integrated with TLS config)
# - Rate Limiting: Implemented in src/tls/rate_limiting.rs (not yet config-exposed)
# - Certificate Monitoring: Implemented in src/tls/cert_monitoring.rs (not yet config-exposed)
#
# The following features are NOT implemented and should not be configured:
# - CORS: No implementation found
# - Monitoring/Metrics: Only middleware exists, no full implementation
# - Development Settings: No implementation found
#
# If you need these features, please check the current implementation status or
# contribute to the project: https://github.com/MagicBeansAI/magictunnel

# =============================================================================
# ENVIRONMENT VARIABLE EXAMPLES
# =============================================================================
# You can override any configuration value using environment variables:
#
# # Server configuration
# export MCP_HOST="0.0.0.0"
# export MCP_PORT="8080"
# export MCP_WEBSOCKET="true"
# export MCP_TIMEOUT="60"
#
# # TLS configuration
# export MCP_TLS_MODE="application"
# export MCP_TLS_CERT_FILE="/path/to/cert.pem"
# export MCP_TLS_KEY_FILE="/path/to/key.pem"
#
# # Registry configuration
# export MCP_REGISTRY_TYPE="file"
# export MCP_REGISTRY_PATHS="./capabilities,./custom-tools"
# export MCP_HOT_RELOAD="true"
#
# # Authentication
# export MCP_AUTH_ENABLED="true"
# export MCP_AUTH_TYPE="api_key"
#
# # External MCP Discovery
# export EXTERNAL_MCP_ENABLED="true"
# export EXTERNAL_MCP_CONFIG_FILE="./external-mcp-servers.yaml"
# export EXTERNAL_MCP_REFRESH_INTERVAL="60"
#
# # Tool Conflict Resolution
# export CONFLICT_RESOLUTION_STRATEGY="LocalFirst"  # LocalFirst|ProxyFirst|FirstFound|Reject|Prefix
#
# # Smart Discovery Configuration
# export SMART_DISCOVERY_ENABLED="true"
# export SMART_DISCOVERY_MODE="llm_based"  # rule_based|llm_based
# export SMART_DISCOVERY_THRESHOLD="0.7"
# export SMART_DISCOVERY_LLM_ENABLED="true"
# export SMART_DISCOVERY_LLM_PROVIDER="openai"  # openai|anthropic|ollama
# export SMART_DISCOVERY_LLM_MODEL="gpt-4o-mini"
# export SMART_DISCOVERY_LLM_API_KEY="your-api-key-here"
# export SMART_DISCOVERY_MAPPER_ENABLED="true"
# export OPENAI_API_KEY="your-openai-api-key"  # For LLM parameter mapping
#
# # Logging
# export MCP_LOG_LEVEL="debug"
# export MCP_LOG_FORMAT="json"

# =============================================================================
# QUICK START EXAMPLES
# =============================================================================
#
# 1. Basic setup (local tools only):
#    - Copy this file to config.yaml
#    - Ensure ./capabilities directory exists with your tool definitions
#    - Run: cargo run --release
#
# 2. With authentication:
#    - Uncomment the auth section above
#    - Set your API keys, OAuth, or JWT credentials
#    - Restart the proxy
#
# 3. With external MCP servers (RECOMMENDED):
#    - Set external_mcp.enabled: true
#    - Copy external-mcp-servers.yaml.template to external-mcp-servers.yaml
#    - Configure your MCP servers and set environment variables
#    - Restart the proxy to enable automatic capability discovery
#

#
# 4. Production deployment:
#    - Enable TLS with proper certificates
#    - Configure authentication (API keys recommended)
#    - Set up monitoring and logging
#    - Use environment variables for secrets
#    - Enable rate limiting and security headers
#    - Configure hybrid routing for conflict resolution

# =============================================================================
# CAPABILITY FILE EXAMPLES
# =============================================================================
#
# Create YAML files in ./capabilities/ directory with your tool definitions:
#
# Example: ./capabilities/weather.yaml
# ---
# tools:
#   - name: "get_weather"
#     description: "Get current weather for a location"
#     input_schema:
#       type: "object"
#       properties:
#         location:
#           type: "string"
#           description: "City name or coordinates"
#       required: ["location"]
#     routing:
#       type: "rest"
#       url: "https://api.weather.com/v1/current"
#       method: "GET"
#       headers:
#         "X-API-Key": "${WEATHER_API_KEY}"
#       query_params:
#         q: "${location}"
#     # Optional: hide this tool from main tool lists (for Smart Tool Discovery)
#     # Hidden tools are still available for discovery and execution but not exposed in tools/list
#     hidden: false
#
#   - name: "internal_weather_cache"
#     description: "Internal weather caching tool (hidden from main interface)"
#     input_schema:
#       type: "object"
#       properties:
#         action:
#           type: "string"
#           enum: ["clear", "stats"]
#     routing:
#       type: "subprocess"
#       config:
#         command: "weather-cache"
#         args: ["{action}"]
#     # This tool is hidden - available for Smart Tool Discovery but not in main tool list
#     hidden: true
#
# Tool Visibility Management:
# - Use the magictunnel-visibility CLI to manage tool visibility:
#   - magictunnel-visibility status                    # Show visibility status
#   - magictunnel-visibility hide-tool get_weather     # Hide specific tool
#   - magictunnel-visibility show-tool get_weather     # Show specific tool
#   - magictunnel-visibility hide-file weather.yaml --confirm  # Hide all tools in file
#   - magictunnel-visibility show-all --confirm        # Show all tools globally

# =============================================================================
# TROUBLESHOOTING
# =============================================================================
#
# Common issues and solutions:
#
# 1. "Permission denied" errors:
#    - Check file permissions on capability directories
#    - Ensure the user has read access to config files
#    - Verify TLS certificate file permissions
#
# 2. "Connection refused" to external MCP servers:
#    - Verify MCP server processes can be spawned correctly
#    - Check that required commands (npx, uv, docker) are available
#    - Ensure MCP server packages are installed
#    - Verify environment variables are set correctly
#    - Check that external_mcp.enabled is set to true
#
# 3. "No capabilities loaded":
#    - Check that capability files exist in configured paths
#    - Verify YAML syntax in capability files
#    - Enable debug logging to see detailed error messages
#    - Check registry validation settings
#
# 4. Authentication failures:
#    - Verify API keys are correct and have minimum 16 characters
#    - Check OAuth configuration and credentials
#    - Ensure JWT secrets are at least 32 characters long
#    - Verify authentication is enabled in config
#
# 5. External MCP discovery issues:
#    - Check external MCP server configuration files exist
#    - Verify MCP server commands are available (npx, uv, docker)
#    - Check environment variables and working directory settings
#    - Enable debug logging for detailed discovery information
#
# 6. Tool conflicts between local and external sources:
#    - Review external_mcp.conflict_resolution strategy settings
#    - Check tool name prefixes and mappings in external MCP config
#    - Enable debug logging for conflict resolution details
#
# 7. TLS/SSL issues:
#    - Verify certificate and key file paths
#    - Check certificate validity and expiration
#    - Ensure proper TLS mode configuration
#    - Verify trusted proxy settings if behind reverse proxy
#
# For more help, see: https://github.com/MagicBeansAI/magictunnel/docs