Documentation update readmes

.env.example

@@ -13,7 +13,10 @@ HOST=0.0.0.0
 # Port number for the HTTP server
 PORT=4444
 
-# Runtime environment (development/production) - affects CORS, cookies, and security defaults
+# Runtime environment - affects CORS, cookies, and security defaults
+# Options: development, production
+# - development: Relaxed CORS (localhost:3000/8080), debug info, insecure cookies
+# - production: Strict CORS (APP_DOMAIN only), secure cookies, no debug info
 ENVIRONMENT=development
 
 # Domain name for CORS origins and cookie settings (use your actual domain in production)
@@ -24,7 +27,10 @@ APP_DOMAIN=localhost
 # See FastAPI docs: https://fastapi.tiangolo.com/advanced/behind-a-proxy/
 APP_ROOT_PATH=
 
-# Enable basic auth for docs endpoints
+# Enable HTTP Basic Auth for OpenAPI docs endpoints (/docs, /redoc)
+# Options: true, false (default: false)
+# When true: Allows accessing docs with BASIC_AUTH_USER/BASIC_AUTH_PASSWORD
+# When false: Only JWT Bearer token authentication is accepted
 DOCS_ALLOW_BASIC_AUTH=false
 
 # Database Configuration
@@ -59,11 +65,29 @@ DB_MAX_RETRIES=5
 # Retry interval in milliseconds (default: 2000)
 DB_RETRY_INTERVAL_MS=2000
 
-# Cache Configuration
+# Cache Backend Configuration
+# Options: database (default), memory (in-process), redis (distributed)
+# - database: Uses SQLite/PostgreSQL for persistence (good for single-node)
+# - memory: Fast in-process caching (lost on restart, not shared between workers)
+# - redis: Distributed caching for multi-node deployments
 CACHE_TYPE=database
-# CACHE_TYPE=redis
+
+# Redis connection URL (only used when CACHE_TYPE=redis)
+# Format: redis://[username:password@]host:port/database
+# Example: redis://localhost:6379/0 (local), redis://redis:6379/0 (container)
 # REDIS_URL=redis://localhost:6379/0
 
+# Cache key prefix for Redis (used to namespace keys in shared Redis instances)
+# Default: "mcpgw:"
+CACHE_PREFIX=mcpgw:
+
+# Session time-to-live in seconds (how long sessions remain valid)
+# Default: 3600 (1 hour)
+SESSION_TTL=3600
+
+# Message time-to-live in seconds (how long messages are retained)
+# Default: 600 (10 minutes)
+MESSAGE_TTL=600
 
 # Maximum number of times to boot redis connection for cold start
 REDIS_MAX_RETRIES=3
@@ -82,13 +106,19 @@ PROTOCOL_VERSION=2025-03-26
 # Authentication
 #####################################
 
-# Admin UI basic-auth credentials
+# Admin UI HTTP Basic Auth credentials
+# Used for: Admin UI login, /docs endpoint (if DOCS_ALLOW_BASIC_AUTH=true)
 # PRODUCTION: Change these to strong, unique values!
-# Authentication Configuration
 BASIC_AUTH_USER=admin
 BASIC_AUTH_PASSWORD=changeme
+
+# Global authentication requirement
+# Options: true (default), false
+# When true: All endpoints require authentication (Basic or JWT)
+# When false: Endpoints are publicly accessible (NOT RECOMMENDED)
 AUTH_REQUIRED=true
-# Content type for outgoing requests to Forge
+# Content type for outgoing HTTP requests to upstream services
+# Options: application/json (default), application/x-www-form-urlencoded, multipart/form-data
 FORGE_CONTENT_TYPE=application/json
 
 # JWT Algorithm Selection
@@ -184,9 +214,13 @@ OAUTH_MAX_RETRIES=3
 # ==============================================================================
 
 # Master SSO switch - enable Single Sign-On authentication
+# Options: true, false (default)
+# When true: Enables SSO login options alongside local auth
 SSO_ENABLED=false
 
 # GitHub OAuth Configuration
+# Options: true, false (default)
+# Requires: GitHub OAuth App (Settings > Developer settings > OAuth Apps)
 SSO_GITHUB_ENABLED=false
 # SSO_GITHUB_CLIENT_ID=your-github-client-id
 # SSO_GITHUB_CLIENT_SECRET=your-github-client-secret
@@ -247,12 +281,19 @@ REQUIRE_EMAIL_VERIFICATION_FOR_INVITES=true
 # Admin UI and API Toggles
 #####################################
 
-# Enable the visual Admin UI (true/false)
-# PRODUCTION: Set to false for security
-
-# UI/Admin Feature Flags
+# Enable the web-based Admin UI at /admin
+# Options: true (default), false
+# PRODUCTION: Set to false for security unless needed
 MCPGATEWAY_UI_ENABLED=true
+
+# Enable Admin REST API endpoints (/tools, /servers, /resources, etc.)
+# Options: true (default), false
+# Required for: Admin UI functionality, programmatic management
 MCPGATEWAY_ADMIN_API_ENABLED=true
+
+# Enable bulk import feature for mass tool/resource registration
+# Options: true (default), false
+# Allows importing multiple tools/resources in a single API call
 MCPGATEWAY_BULK_IMPORT_ENABLED=true
 
 # Maximum number of tools allowed per bulk import request
@@ -300,15 +341,22 @@ MCPGATEWAY_A2A_METRICS_ENABLED=true
 # Security and CORS
 #####################################
 
-# Skip TLS certificate checks for upstream requests (not recommended in prod)
+# Skip SSL/TLS certificate verification for upstream requests
+# Options: true, false (default)
+# WARNING: Only use in development or with self-signed certificates!
+# PRODUCTION: Must be false for security
 SKIP_SSL_VERIFY=false
 
-# CORS origin allowlist (use JSON array of URLs)
-# Example: ["http://localhost:3000"]
-# Do not quote this value. Start with [] to ensure it's valid JSON.
+# CORS allowed origins (JSON array of URLs)
+# Controls which domains can make cross-origin requests to the gateway
+# Format: JSON array starting with [ and ending with ]
+# Example: ["http://localhost:3000", "https://app.example.com"]
+# Use ["*"] to allow all origins (NOT RECOMMENDED)
 ALLOWED_ORIGINS='["http://localhost", "http://localhost:4444"]'
 
-# Enable CORS handling in the gateway
+# Enable CORS (Cross-Origin Resource Sharing) handling
+# Options: true (default), false
+# Required for: Web browser clients, cross-domain API access
 CORS_ENABLED=true
 
 # CORS allow credentials (true/false)
@@ -382,12 +430,27 @@ RETRY_JITTER_MAX=0.5
 # Logging
 #####################################
 
-# Logging verbosity level: DEBUG, INFO, WARNING, ERROR, CRITICAL
-
-# Logging Configuration
+# Logging verbosity level
+# Options: DEBUG, INFO (default), WARNING, ERROR, CRITICAL
+# DEBUG: Detailed diagnostic info (verbose)
+# INFO: General operational messages
+# WARNING: Warning messages for potential issues
+# ERROR: Error messages for failures
+# CRITICAL: Only critical failures
 LOG_LEVEL=INFO
+
+# Log output format
+# Options: json (default), text
+# json: Structured JSON logs (good for log aggregation)
+# text: Human-readable plain text
 LOG_FORMAT=json
+
+# Enable file logging (in addition to console output)
+# Options: true, false (default)
 LOG_TO_FILE=false
+
+# File write mode when LOG_TO_FILE=true
+# Options: a+ (append, default), w (overwrite on startup)
 LOG_FILEMODE=a+
 LOG_FILE=mcpgateway.log
 LOG_FOLDER=logs
@@ -396,29 +459,73 @@ LOG_MAX_SIZE_MB=1
 LOG_BACKUP_COUNT=5
 LOG_BUFFER_SIZE_MB=1.0
 
-# Transport Configuration
+# Transport Protocol Configuration
+# Options: all (default), sse, streamablehttp, http
+# - all: Enable all transport protocols
+# - sse: Server-Sent Events only
+# - streamablehttp: Streaming HTTP only
+# - http: Standard HTTP JSON-RPC only
 TRANSPORT_TYPE=all
+
+# WebSocket keepalive ping interval in seconds
+# Prevents connection timeout for idle WebSocket connections
 WEBSOCKET_PING_INTERVAL=30
+
+# SSE client retry timeout in milliseconds
+# Time client waits before reconnecting after SSE connection loss
 SSE_RETRY_TIMEOUT=5000
+
+# Enable SSE keepalive events to prevent proxy/firewall timeouts
+# Options: true (default), false
 SSE_KEEPALIVE_ENABLED=true
+
+# SSE keepalive event interval in seconds
+# How often to send keepalive events when SSE_KEEPALIVE_ENABLED=true
 SSE_KEEPALIVE_INTERVAL=30
 
 # Streaming HTTP Configuration
+# Enable stateful sessions (stores session state server-side)
+# Options: true, false (default)
+# false: Stateless mode (better for scaling)
 USE_STATEFUL_SESSIONS=false
+
+# Enable JSON response format for streaming HTTP
+# Options: true (default), false
+# true: Return JSON responses, false: Return SSE stream
 JSON_RESPONSE_ENABLED=true
 
 # Federation Configuration
+# Enable gateway federation (connect to other MCP gateways)
+# Options: true (default), false
 FEDERATION_ENABLED=true
+
+# Enable automatic peer discovery via mDNS/Zeroconf
+# Options: true, false (default)
+# Requires: python-zeroconf package
 FEDERATION_DISCOVERY=false
+
+# Static list of peer gateway URLs (JSON array)
+# Example: ["http://gateway1:4444", "https://gateway2.example.com"]
 FEDERATION_PEERS=[]
+
+# Timeout for federation requests in seconds
 FEDERATION_TIMEOUT=30
+
+# Interval between federation sync operations in seconds
 FEDERATION_SYNC_INTERVAL=300
 
 # Resource Configuration
 RESOURCE_CACHE_SIZE=1000
 RESOURCE_CACHE_TTL=3600
 MAX_RESOURCE_SIZE=10485760
 
+# Allowed MIME types for resources (JSON array)
+# Controls which content types are allowed for resource handling
+# Default includes common text, image, and data formats
+# Example: ["text/plain", "text/markdown", "application/json", "image/png"]
+# To add custom types: ["text/plain", "application/pdf", "video/mp4"]
+# ALLOWED_MIME_TYPES=["text/plain", "text/markdown", "text/html", "application/json", "application/xml", "image/png", "image/jpeg", "image/gif"]
+
 # Tool Configuration
 TOOL_TIMEOUT=60
 MAX_TOOL_RETRIES=3
@@ -437,11 +544,44 @@ HEALTH_CHECK_TIMEOUT=15
 UNHEALTHY_THRESHOLD=5
 GATEWAY_VALIDATION_TIMEOUT=10
 
-# OpenTelemetry Configuration
+# File lock name for gateway service leader election
+# Used to coordinate multiple gateway instances when running in cluster mode
+# Default: "gateway_service_leader.lock"
+FILELOCK_NAME=gateway_service_leader.lock
+
+# Default root paths (JSON array)
+# List of default root paths for resource resolution
+# Example: ["/api/v1", "/mcp"]
+# Default: []
+DEFAULT_ROOTS=[]
+
+# OpenTelemetry Observability Configuration
+# Enable distributed tracing and metrics collection
+# Options: true (default), false
 OTEL_ENABLE_OBSERVABILITY=true
+
+# Traces exporter backend
+# Options: otlp (default), jaeger, zipkin, console, none
+# - otlp: OpenTelemetry Protocol (works with many backends)
+# - jaeger: Direct Jaeger integration
+# - zipkin: Direct Zipkin integration
+# - console: Print to stdout (debugging)
+# - none: Disable tracing
 OTEL_TRACES_EXPORTER=otlp
+
+# OTLP endpoint for traces and metrics
+# Examples:
+# - Phoenix: http://localhost:4317
+# - Jaeger: http://localhost:4317
+# - Tempo: http://localhost:4317
 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+
+# OTLP protocol
+# Options: grpc (default), http
 OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+
+# Use insecure connection (no TLS) for OTLP
+# Options: true (default for localhost), false (use TLS)
 OTEL_EXPORTER_OTLP_INSECURE=true
 # OTEL_EXPORTER_OTLP_HEADERS=key1=value1,key2=value2
 # OTEL_EXPORTER_JAEGER_ENDPOINT=http://localhost:14268/api/traces
@@ -452,8 +592,15 @@ OTEL_BSP_MAX_QUEUE_SIZE=2048
 OTEL_BSP_MAX_EXPORT_BATCH_SIZE=512
 OTEL_BSP_SCHEDULE_DELAY=5000
 
-# Plugin Configuration
+# Plugin Framework Configuration
+# Enable the plugin system for extending gateway functionality
+# Options: true, false (default)
+# When true: Loads and executes plugins from PLUGIN_CONFIG_FILE
 PLUGINS_ENABLED=false
+
+# Path to the plugin configuration file
+# Contains plugin definitions, hooks, and settings
+# Default: plugins/config.yaml
 PLUGIN_CONFIG_FILE=plugins/config.yaml
 
 #####################################
@@ -497,14 +644,68 @@ WELL_KNOWN_CACHE_MAX_AGE=3600
 # Example 4: Multiple custom files
 # WELL_KNOWN_CUSTOM_FILES={"ai.txt": "# AI Usage Policy\n\nThis MCP Gateway uses AI for:\n- Tool orchestration\n- Response generation\n- Error handling\n\nWe do not use AI for:\n- User data analysis\n- Behavioral tracking\n- Decision making without human oversight", "dnt-policy.txt": "# Do Not Track Policy\n\nWe respect the DNT header.\nNo tracking cookies are used.\nOnly essential session data is stored.", "change-password": "https://mycompany.com/account/password"}
 
+#####################################
+# Validation Settings
+#####################################
+
+# These settings control input validation and security patterns
+# Most users won't need to change these defaults
+
+# HTML/JavaScript injection patterns (regex)
+# Used to detect potentially dangerous HTML/JS content
+# VALIDATION_DANGEROUS_HTML_PATTERN - Pattern to detect dangerous HTML tags
+# VALIDATION_DANGEROUS_JS_PATTERN - Pattern to detect JavaScript injection attempts
+
+# Allowed URL schemes for external requests
+# Controls which URL schemes are permitted for gateway operations
+# Default: ["http://", "https://", "ws://", "wss://"]
+# VALIDATION_ALLOWED_URL_SCHEMES=["http://", "https://", "ws://", "wss://"]
+
+# Character validation patterns (regex)
+# Used to validate various input fields
+# VALIDATION_NAME_PATTERN - Pattern for validating names (allows spaces)
+# VALIDATION_IDENTIFIER_PATTERN - Pattern for validating IDs (no spaces)
+# VALIDATION_SAFE_URI_PATTERN - Pattern for safe URI characters
+# VALIDATION_UNSAFE_URI_PATTERN - Pattern to detect unsafe URI characters
+# VALIDATION_TOOL_NAME_PATTERN - MCP tool naming pattern
+# VALIDATION_TOOL_METHOD_PATTERN - MCP tool method naming pattern
+
+# Size limits for various inputs (in characters or bytes)
+# VALIDATION_MAX_NAME_LENGTH=255
+# VALIDATION_MAX_DESCRIPTION_LENGTH=8192
+# VALIDATION_MAX_TEMPLATE_LENGTH=65536
+# VALIDATION_MAX_CONTENT_LENGTH=1048576
+# VALIDATION_MAX_JSON_DEPTH=10
+# VALIDATION_MAX_URL_LENGTH=2048
+# VALIDATION_MAX_RPC_PARAM_SIZE=262144
+# VALIDATION_MAX_METHOD_LENGTH=128
+
+# Rate limiting for validation operations
+# Maximum requests per minute for validation endpoints
+# VALIDATION_MAX_REQUESTS_PER_MINUTE=60
+
+# Allowed MIME types for validation (JSON array)
+# Controls which content types pass validation checks
+# VALIDATION_ALLOWED_MIME_TYPES=["text/plain", "text/html", "text/css", "text/markdown", "text/javascript", "application/json", "application/xml", "application/pdf", "image/png", "image/jpeg", "image/gif", "image/svg+xml", "application/octet-stream"]
+
 #####################################
 # Development Configuration
 #####################################
 
+# Enable development mode (relaxed security, verbose logging)
+# Options: true, false (default)
+# WARNING: Never use in production!
 DEV_MODE=false
+
+# Enable auto-reload on code changes (for development)
+# Options: true, false (default)
+# Requires: Running with uvicorn directly (not gunicorn)
 RELOAD=false
+
+# Enable debug mode (verbose error messages, stack traces)
+# Options: true, false (default)
+# WARNING: May expose sensitive information!
 DEBUG=false
-# SKIP_SSL_VERIFY is already defined in Security and CORS section
 
 # Header Passthrough (WARNING: Security implications)
 ENABLE_HEADER_PASSTHROUGH=false
@@ -547,5 +748,3 @@ REQUIRE_STRONG_SECRETS=false
 # Set to false to allow startup with security warnings
 # NOT RECOMMENDED for production!
 # REQUIRE_STRONG_SECRETS=false
-
-MCPCONTEXT_UI_ENABLED=true