.env.example

# Mittwald MCP Server – Environment Example
#
# All variables are annotated as REQUIRED or OPTIONAL.
# Replace placeholder values before deploying to production.

# ====================
# Core Application
# ====================

# REQUIRED: Node environment used for conditional logic (production|development|test).
NODE_ENV=development

# REQUIRED: HTTP port the MCP server listens on.
PORT=3000

# OPTIONAL: Alias used by some integration scripts. Keep in sync with PORT.
MCP_SERVER_PORT=3000

# OPTIONAL: Transport mode for MCP clients. Use `stdio` for ChatGPT/Claude, `http` for local HTTP testing.
MCP_TRANSPORT=stdio

# REQUIRED in production: Comma-separated list of allowed CORS origins.
# Server will refuse to start in production without this setting.
# CORS_ORIGIN=https://claude.ai,https://chatgpt.com


# ====================
# Logging & Diagnostics
# ====================

# REQUIRED: Base log level for server logging (debug|info|warn|error).
LOG_LEVEL=info

# OPTIONAL: Enable verbose debug logging (`true` or `false`).
DEBUG=false


# ====================
# Redis Session Store
# ====================

# REQUIRED: Redis connection URL used to persist MCP sessions and OAuth state.
REDIS_URL=redis://localhost:6379

# OPTIONAL: TTL (seconds) for stored MCP sessions (default 28800 = 8 hours).
REDIS_TTL=28800

# OPTIONAL: OAuth state TTL for legacy flows (seconds, default 600).
STATE_TTL=600


# ====================
# OAuth Bridge Integration
# ====================

# REQUIRED: Shared secret used to verify bridge-issued JWTs.
# Generate with: openssl rand -hex 32
OAUTH_BRIDGE_JWT_SECRET=REPLACE_WITH_GENERATED_SECRET_MINIMUM_64_HEX_CHARS

# OPTIONAL: Expected metadata for the OAuth bridge (override defaults when deploying a custom bridge).
# OAUTH_BRIDGE_ISSUER=https://mittwald-oauth-server.fly.dev
# OAUTH_BRIDGE_AUDIENCE=https://mittwald-mcp.fly.dev
# OAUTH_BRIDGE_BASE_URL=https://mittwald-oauth-server.fly.dev
# OAUTH_BRIDGE_AUTHORIZATION_URL=https://mittwald-oauth-server.fly.dev/authorize
# OAUTH_BRIDGE_TOKEN_URL=https://mittwald-oauth-server.fly.dev/token

# OPTIONAL: Bridge session storage overrides surfaced to the MCP server.
OAUTH_BRIDGE_SESSION_TTL=28800
OAUTH_BRIDGE_REDIS_URL=redis://localhost:6379
OAUTH_BRIDGE_LOG_LEVEL=info

# OPTIONAL: Runtime port for the standalone OAuth bridge service (see packages/oauth-bridge/.env.example).
OAUTH_BRIDGE_PORT=3001


# ====================
# JWT Issued By MCP Server
# ====================

# REQUIRED: Signing key for JWTs minted by the MCP server (base64, ≥32 bytes).
# Generate with: openssl rand -base64 32
JWT_SIGNING_KEY=REPLACE_WITH_GENERATED_KEY_MINIMUM_32_BYTES

# OPTIONAL: Override default JWT expiry duration (examples: 1h, 30m, 7200s).
JWT_EXPIRY=1h


# ====================
# Mittwald OAuth Client
# ====================

# REQUIRED: Mittwald OAuth authorization endpoint for your tenant.
MITTWALD_AUTHORIZATION_URL=https://api.mittwald.de/oauth2/authorize

# REQUIRED: Mittwald OAuth token endpoint (used for refresh flows).
MITTWALD_TOKEN_URL=https://api.mittwald.de/oauth2/token

# REQUIRED: Registered Mittwald OAuth client ID (public PKCE client).
MITTWALD_OAUTH_CLIENT_ID=mittwald-mcp-server

# OPTIONAL: Mittwald OAuth client secret (only set for confidential clients/tests).
MITTWALD_OAUTH_CLIENT_SECRET=mock-client-secret

# OPTIONAL: Base URL for Mittwald's REST API used by CLI tooling.
MITTWALD_API_BASE_URL=https://api.mittwald.de/v2


# ====================
# Mittwald CLI Execution (Optional)
# ====================

# OPTIONAL: Maximum stdout the mw CLI may emit before the MCP server aborts the call (in MB, default 20).
# MCP_CLI_MAX_BUFFER_MB=20

# OPTIONAL: Upper bound for tool payloads returned to clients (in MB, default 12; capped by MCP_CLI_MAX_BUFFER_MB).
# MCP_TOOL_MAX_PAYLOAD_MB=12

# OPTIONAL: Node.js max-old-space-size (MB) injected for mw CLI processes. Set to 0 to disable override (default 384).
# MCP_CLI_MAX_HEAP_MB=384

# OPTIONAL: Additional NODE_OPTIONS appended when invoking the mw CLI (e.g., diagnostics flags).
# MCP_CLI_NODE_OPTIONS=--trace-warnings --no-deprecation

# ====================
# Direct Bearer Tokens (Optional)
# ====================

# ENABLE_DIRECT_BEARER_TOKENS=false
# DIRECT_TOKEN_CACHE_TTL_MS=60000
# DIRECT_TOKEN_SESSION_TTL_SECONDS=1800
# DIRECT_TOKEN_VALIDATION_TIMEOUT_MS=15000


# ====================
# MCP OAuth Redirects
# ====================

# REQUIRED: Redirect URI registered with Mittwald for the MCP server.
OAUTH_REDIRECT_URI=http://localhost:3000/auth/callback

# OPTIONAL: Issuer used to derive development redirect URIs.
OAUTH_ISSUER=http://localhost:8080/default


# ====================
# Tool Filtering (Optional)
# ====================

TOOL_FILTER_ENABLED=false
MAX_TOOLS_PER_RESPONSE=50
# ALLOWED_TOOL_CATEGORIES=project,app,database


# ====================
# Prometheus Metrics
# ====================

# OPTIONAL: Enable/disable Prometheus metrics (default: true).
# Set to 'false' to completely disable metrics collection and the /metrics endpoint.
# METRICS_ENABLED=true

# OPTIONAL: Basic auth credentials for the /metrics endpoint.
# When both are set, authentication is required to access Prometheus metrics.
# When not set, the /metrics endpoint is publicly accessible.
# METRICS_USER=prometheus
# METRICS_PASS=your-secret-password


# ====================
# Matomo Analytics (Optional)
# ====================

# OPTIONAL: Enable Matomo event tracking for tool invocations.
# MATOMO_ENABLED=true

# REQUIRED when MATOMO_ENABLED=true: Matomo Tracking API endpoint.
# Example: https://matomo.example.com/matomo.php
# MATOMO_URL=https://your-matomo-instance.com/matomo.php

# REQUIRED when MATOMO_ENABLED=true: Matomo site ID.
# MATOMO_SITE_ID=1

# OPTIONAL: Matomo auth token for advanced tracking features (e.g., user attribution).
# Generate in Matomo: Administration > Personal > Security > Auth Tokens
# MATOMO_AUTH_TOKEN=your-auth-token

# OPTIONAL: Custom dimension ID for tracking the invoking AI agent (1-999).
# Create the dimension in Matomo first: Administration > Websites > Custom Dimensions
# MATOMO_AGENT_DIMENSION_ID=1

# OPTIONAL: Custom dimension ID for tracking tool domains (1-999).
# MATOMO_DOMAIN_DIMENSION_ID=2


# ====================
# Test Harness Values (Optional)
# ====================

# TEST_SERVER_ID=your_mittwald_server_id_here
# TEST_ADMIN_EMAIL=test@example.com
# SKIP_TEST_CLEANUP=false
# TEST_PARALLEL=true