.env.example

# =============================================================================
# IBM i MCP Server - Environment Configuration
# =============================================================================
# Copy this file to .env and configure with your settings:
#   cp .env.example .env
#
# See full documentation: https://github.com/IBM/ibmi-mcp-server#configuration
# =============================================================================

# -----------------------------------------------------------------------------
# 🗄️ IBM i Database Connection
# -----------------------------------------------------------------------------
# Required for SQL tools to connect to IBM i Db2 for i via Mapepire

# IBM i system hostname or IP address (REQUIRED)
DB2i_HOST=

# IBM i user profile for database connections (REQUIRED)
DB2i_USER=

# Password for IBM i user profile (REQUIRED)
DB2i_PASS=

# Mapepire daemon/gateway port
# Default: 8076
DB2i_PORT=8076

# Skip TLS certificate verification (for self-signed certs)
# Default: true
# ⚠️ SECURITY: Set to false in production with valid SSL certificates
DB2i_IGNORE_UNAUTHORIZED=true

# Mapepire JDBC connection options (optional)
# Format: semicolon-separated key=value pairs (matches DB2 JDBC URL syntax)
# - Keys with spaces are allowed (e.g., "date format")
# - The "libraries" value is comma-separated (the only array-valued option)
# - All other values are forwarded as strings to the JDBC driver
# - Overrides any jdbc-options set in YAML sources
# Example: DB2i_JDBC_OPTIONS='naming=system;date format=iso;libraries=MYLIB,DEVDATA'
DB2i_JDBC_OPTIONS=

# -----------------------------------------------------------------------------
# 🧩 YAML Tool Configuration
# -----------------------------------------------------------------------------

# Path to YAML tool configurations (file, directory, or glob pattern)
# Examples:
#   - File: tools/performance.yaml
#   - Directory: tools/ (loads all .yaml/.yml files)
#   - Glob: tools/**/*.yaml
# Default: none (no tools loaded)
TOOLS_YAML_PATH=

# Comma-separated list of toolsets to load (filters available tools)
# Leave empty to load all tools
# Example: performance,monitoring,diagnostics
# Default: none (load all)
SELECTED_TOOLSETS=

# Automatically reload tools when YAML files change
# Default: true
YAML_AUTO_RELOAD=true

# --- Configuration Merging (when loading multiple YAML files) ---

# Merge arrays from multiple files (true) or replace them (false)
# Default: true
YAML_MERGE_ARRAYS=true

# Allow duplicate tool names across files
# Default: false
YAML_ALLOW_DUPLICATE_TOOLS=false

# Allow duplicate source names across files
# Default: false
YAML_ALLOW_DUPLICATE_SOURCES=true

# Validate merged configuration before loading tools
# Default: true
YAML_VALIDATE_MERGED=true

# -----------------------------------------------------------------------------
# 🛠️ Built-in Tools Configuration
# -----------------------------------------------------------------------------

# Enable the default text-to-SQL toolset (list_schemas, list_tables_in_schema,
# get_table_columns, get_related_objects, validate_query)
# Default: false
# CLI equivalent: --builtin-tools
# These are read-only schema discovery tools that query IBM i catalog views.
IBMI_ENABLE_DEFAULT_TOOLS=false

# Enable the built-in execute_sql tool for ad-hoc SQL queries
# Default: false
# CLI equivalent: --execute-sql
# ⚠️ SECURITY: This tool allows clients to run arbitrary SQL queries.
#              Enable only in development or trusted environments.
#              Consider using YAML-defined tools in production for better control.
# See: https://github.com/IBM/ibmi-mcp-server#built-in-tools-configuration
IBMI_ENABLE_EXECUTE_SQL=false

# Control readonly mode for execute_sql tool
# When true (default), only SELECT/QUERY statements are allowed
# When false, allows INSERT, UPDATE, DELETE, and other write operations
# Default: true
# ⚠️ SECURITY: Write operations are blocked by default for safety.
#              Set to false only when write access is explicitly required.
#              All queries are validated using IBM i's PARSE_STATEMENT for defense-in-depth.
IBMI_EXECUTE_SQL_READONLY=true

# -----------------------------------------------------------------------------
# 🖥️ MCP Server Settings
# -----------------------------------------------------------------------------
# Core server configuration

# Server name identifier (optional, defaults to package name)
# MCP_SERVER_NAME=ibmi-mcp-server

# Server version (optional, defaults to package version)
# MCP_SERVER_VERSION=1.9.1

# Transport protocol: "stdio" (local) or "http" (remote)
# Default: stdio
MCP_TRANSPORT_TYPE=http

# Logging verbosity: "error", "warn", "info", "debug"
# Default: debug
MCP_LOG_LEVEL=debug

# Directory for log files (relative to project root)
# Default: logs
LOGS_DIR=logs

# Node environment: "development", "production", "test"
# Default: development
NODE_ENV=development

# -----------------------------------------------------------------------------
# 🌐 HTTP Transport Settings
# -----------------------------------------------------------------------------
# Only used when MCP_TRANSPORT_TYPE=http

# HTTP server port
# Default: 3010
MCP_HTTP_PORT=3010

# HTTP server bind address
# Default: 127.0.0.1 (localhost only)
# Use 0.0.0.0 to listen on all interfaces
MCP_HTTP_HOST=0.0.0.0

# MCP endpoint path
# Default: /mcp
MCP_HTTP_ENDPOINT_PATH=/mcp

# Session mode: "stateless", "stateful", or "auto"
# - auto: Automatically detects client capabilities (recommended)
# - stateful: Maintains persistent sessions with connection state
# - stateless: Each request is independent
# Default: auto
MCP_SESSION_MODE=auto

# Timeout for idle stateful sessions (milliseconds)
# Default: 1800000 (30 minutes)
MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS=1800000

# Max attempts to find available port if default is in use
# Default: 15
MCP_HTTP_MAX_PORT_RETRIES=15

# Delay between port retry attempts (milliseconds)
# Default: 50
MCP_HTTP_PORT_RETRY_DELAY_MS=50

# Comma-separated CORS allowed origins (leave empty to block all origins)
# Example: http://localhost:3000,https://app.example.com
MCP_ALLOWED_ORIGINS=

# -----------------------------------------------------------------------------
# 🛡️ Rate Limiting (HTTP Only)
# -----------------------------------------------------------------------------
# Controls request rate limiting for the HTTP transport.
# Disable or increase limits for agentic workflows with parallel tool calls.

# Enable or disable rate limiting
# Default: true
MCP_RATE_LIMIT_ENABLED=true

# Maximum requests allowed per window
# Default: 100
# Tip: Increase for AI agent workflows that make many parallel tool calls
MCP_RATE_LIMIT_MAX_REQUESTS=100

# Rate limit window duration in milliseconds
# Default: 900000 (15 minutes)
MCP_RATE_LIMIT_WINDOW_MS=900000

# Skip rate limiting in development (NODE_ENV=development)
# Default: false
MCP_RATE_LIMIT_SKIP_DEV=false

# -----------------------------------------------------------------------------
# 🔄 Connection Pool Timeouts
# -----------------------------------------------------------------------------
# Controls automatic cleanup of idle Mapepire connection pools and query timeouts.
# Essential for cloud deployments (Railway, Heroku, etc.) where proxies kill idle connections.

# Idle timeout for Mapepire connection pools (ms). Pools closed after inactivity.
# Fresh connections established automatically on next request.
# Set to 0 to disable. Default: 300000 (5 minutes)
MCP_POOL_IDLE_TIMEOUT_MS=300000

# Query execution timeout (ms). Queries aborted after this period.
# Pool re-initialized on next request after timeout.
# Set to 0 to disable. Default: 30000 (30 seconds)
MCP_POOL_QUERY_TIMEOUT_MS=30000

# -----------------------------------------------------------------------------
# 📄 Pagination
# -----------------------------------------------------------------------------
# Controls the fetch size and safety ceiling used by SQL tools that paginate
# large result sets (fetchAllRows: true or the built-in execute_sql tool).

# Default rows per fetchMore call when a tool paginates without specifying
# its own page size. Tools can override by setting rowsToFetch in YAML.
# Default: 1000
IBMI_PAGINATION_DEFAULT_PAGE_SIZE=1000

# Hard upper bound on total rows returned by a single paginated tool call.
# Pagination stops and flags the result as truncated once this is reached.
# Default: 30000
IBMI_PAGINATION_MAX_ROWS=30000

# -----------------------------------------------------------------------------
# 🔐 Authentication & Authorization
# -----------------------------------------------------------------------------

# Authentication mode: "none", "jwt", "oauth", "ibmi"
# Default: none
# ⚠️ IMPORTANT: Use "none" only in development environments
MCP_AUTH_MODE=none

# --- JWT Authentication ---
# Required when MCP_AUTH_MODE=jwt
# Secret key for signing/verifying JWT tokens (minimum 32 characters)
# MCP_AUTH_SECRET_KEY=your-very-secret-key-at-least-32-characters-long

# --- OAuth Authentication ---
# Required when MCP_AUTH_MODE=oauth
# OAUTH_ISSUER_URL=https://auth.example.com
# OAUTH_JWKS_URI=https://auth.example.com/.well-known/jwks.json
# OAUTH_AUDIENCE=https://api.example.com/mcp

# --- IBM i HTTP Authentication ---
# Required when MCP_AUTH_MODE=ibmi

# Enable IBM i authentication endpoints (required for ibmi mode)
# Default: false
IBMI_HTTP_AUTH_ENABLED=false

# Allow HTTP (non-HTTPS) authentication requests
# Default: false
# ⚠️ SECURITY: Set to false in production (requires HTTPS)
IBMI_AUTH_ALLOW_HTTP=false

# Token lifetime in seconds
# Default: 3600 (1 hour)
IBMI_AUTH_TOKEN_EXPIRY_SECONDS=3600

# How often to clean up expired tokens (seconds)
# Default: 300 (5 minutes)
IBMI_AUTH_CLEANUP_INTERVAL_SECONDS=300

# Maximum concurrent authenticated sessions
# Default: 100
IBMI_AUTH_MAX_CONCURRENT_SESSIONS=100

# RSA key configuration for IBM i authentication
# Generate keys with:
#   mkdir -p secrets
#   openssl genpkey -algorithm RSA -out secrets/private.pem -pkeyopt rsa_keygen_bits:2048
#   openssl rsa -pubout -in secrets/private.pem -out secrets/public.pem
IBMI_AUTH_KEY_ID=development
IBMI_AUTH_PRIVATE_KEY_PATH=secrets/private.pem
IBMI_AUTH_PUBLIC_KEY_PATH=secrets/public.pem

# -----------------------------------------------------------------------------
# 📊 OpenTelemetry (Observability)
# -----------------------------------------------------------------------------
# Distributed tracing and metrics using OpenTelemetry

# Enable OpenTelemetry instrumentation
# Default: false
OTEL_ENABLED=false

# Service name for telemetry data
# Default: MCP_SERVER_NAME or package name
# OTEL_SERVICE_NAME=ibmi-mcp-server

# Service version for telemetry data
# Default: MCP_SERVER_VERSION or package version
# OTEL_SERVICE_VERSION=1.9.1

# OTLP endpoint for trace export
# Default: none (logs to file)
# Examples:
#   - Jaeger: http://jaeger:4318/v1/traces
#   - Cloud: https://otlp.example.com/v1/traces
# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=

# OTLP endpoint for metrics export
# Default: none (not exported)
# OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=

# Trace sampling ratio (0.0 to 1.0, where 1.0 = sample all traces)
# Default: 1.0 (100%)
OTEL_TRACES_SAMPLER_ARG=1.0

# OpenTelemetry internal diagnostic log level
# Options: NONE, ERROR, WARN, INFO, DEBUG, VERBOSE, ALL
# Default: INFO
OTEL_LOG_LEVEL=INFO

# -----------------------------------------------------------------------------
# 🤖 LLM Provider Integration (Optional)
# -----------------------------------------------------------------------------

# --- OpenRouter ---
# API key for OpenRouter.ai service
OPENROUTER_API_KEY=

# Application URL for OpenRouter dashboard
# Default: http://localhost:3000
OPENROUTER_APP_URL=http://localhost:3000

# Application name for OpenRouter identification
# Default: package name
OPENROUTER_APP_NAME=ibmi-mcp-server

# --- LLM Defaults ---
# Default parameters for LLM requests (applied when not specified)

# Default model identifier
# Default: google/gemini-2.5-flash
LLM_DEFAULT_MODEL=google/gemini-2.5-flash

# Sampling temperature (randomness): 0.0 (deterministic) to 2.0 (creative)
# Default: none (provider default)
LLM_DEFAULT_TEMPERATURE=0.7

# Nucleus sampling threshold: 0.0 to 1.0
# Default: none (provider default)
# LLM_DEFAULT_TOP_P=0.9

# Maximum tokens in response
# Default: none (provider default)
# LLM_DEFAULT_MAX_TOKENS=2000

# Top-K sampling (number of candidates)
# Default: none (provider default)
# LLM_DEFAULT_TOP_K=40

# Minimum probability threshold: 0.0 to 1.0
# Default: none (provider default)
# LLM_DEFAULT_MIN_P=0.05

# -----------------------------------------------------------------------------
# 🔌 OAuth Proxy (Advanced - Optional)
# -----------------------------------------------------------------------------
# OAuth proxy endpoints for advanced integration scenarios
# Most users should use standard OAuth authentication via MCP_AUTH_MODE=oauth

# OAUTH_PROXY_AUTHORIZATION_URL=https://auth.example.com/oauth/authorize
# OAUTH_PROXY_TOKEN_URL=https://auth.example.com/oauth/token
# OAUTH_PROXY_REVOCATION_URL=https://auth.example.com/oauth/revoke
# OAUTH_PROXY_ISSUER_URL=https://auth.example.com
# OAUTH_PROXY_SERVICE_DOCUMENTATION_URL=https://docs.example.com/oauth
# OAUTH_PROXY_DEFAULT_CLIENT_REDIRECT_URIS=http://localhost:3000/callback

# -----------------------------------------------------------------------------
# 💾 Additional Database Integrations (Optional)
# -----------------------------------------------------------------------------

# --- Supabase ---
# Uncomment to enable Supabase integration
# SUPABASE_URL=https://your-project.supabase.co
# SUPABASE_ANON_KEY=your-anon-key
# SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# =============================================================================
# Quick Start Examples
# =============================================================================

# --- Development Configuration ---
# MCP_TRANSPORT_TYPE=http
# MCP_HTTP_PORT=3010
# MCP_SESSION_MODE=auto
# MCP_LOG_LEVEL=debug
# MCP_AUTH_MODE=none
# NODE_ENV=development
#
# DB2i_HOST=ibmi-dev.local
# DB2i_USER=DEVUSER
# DB2i_PASS=devpass
# DB2i_IGNORE_UNAUTHORIZED=true
#
# TOOLS_YAML_PATH=tools/
# YAML_AUTO_RELOAD=true
# OTEL_ENABLED=true

# --- Production Configuration ---
# MCP_TRANSPORT_TYPE=http
# MCP_HTTP_PORT=3010
# MCP_SESSION_MODE=auto
# MCP_LOG_LEVEL=warn
# MCP_AUTH_MODE=ibmi
# NODE_ENV=production
#
# DB2i_HOST=ibmi-prod.example.com
# DB2i_USER=PRODUSER
# DB2i_PASS=${SECURE_PASSWORD_FROM_VAULT}
# DB2i_IGNORE_UNAUTHORIZED=false
#
# TOOLS_YAML_PATH=/opt/mcp-tools/production.yaml
# YAML_AUTO_RELOAD=false
#
# IBMI_HTTP_AUTH_ENABLED=true
# IBMI_AUTH_ALLOW_HTTP=false
# IBMI_AUTH_PRIVATE_KEY_PATH=/opt/secrets/private.pem
# IBMI_AUTH_PUBLIC_KEY_PATH=/opt/secrets/public.pem
#
# OTEL_ENABLED=true
# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp.example.com/v1/traces

# =============================================================================
# Security Checklist
# =============================================================================
# ✅ Never commit .env files to version control
# ✅ Use secrets management in production (Vault, AWS Secrets Manager, etc.)
# ✅ Rotate credentials and keys regularly
# ✅ Use HTTPS/TLS in production (IBMI_AUTH_ALLOW_HTTP=false)
# ✅ Enable authentication (MCP_AUTH_MODE != none)
# ✅ Use strong passwords (12+ characters, mixed case, numbers, symbols)
# ✅ Restrict MCP_ALLOWED_ORIGINS to known domains
# ✅ Set appropriate IBMI_AUTH_MAX_CONCURRENT_SESSIONS limits
# =============================================================================