mcp-server-framework 1.0.0

package/build/config/env.d.ts

@@ -0,0 +1,476 @@
+/**
+ * Framework Environment Configuration
+ *
+ * Environment variables for the generic MCP server framework.
+ * These settings are NOT application-specific and apply to any MCP server
+ * built with this framework.
+ *
+ * @module config/env
+ */
+import { z } from "zod";
+/**
+ * Framework environment schema - application-agnostic settings.
+ *
+ * Includes:
+ * - Application metadata (version, environment)
+ * - MCP Transport settings (host, port, transport mode)
+ * - Security settings (DNS rebinding protection, rate limiting)
+ * - Logging configuration
+ * - OpenTelemetry settings
+ */
+export declare const frameworkEnvSchema: z.ZodEffects<z.ZodObject<{
+    /**
+     * Application version (resolved at module load).
+     *
+     * Source of Truth: package.json
+     * - Docker: build/VERSION file (baked in during build)
+     * - npm run: npm_package_version environment variable
+     */
+    VERSION: z.ZodDefault<z.ZodString>;
+    /** Node environment (development, production, test) */
+    NODE_ENV: z.ZodDefault<z.ZodEnum<["development", "production", "test"]>>;
+    /** Host to bind the MCP server to (default: 127.0.0.1) */
+    MCP_BIND_HOST: z.ZodDefault<z.ZodString>;
+    /** Port to listen on (default: 8000) */
+    MCP_PORT: z.ZodDefault<z.ZodNumber>;
+    /** Transport mode: 'stdio' for CLI, 'http' for HTTP, 'https' for HTTPS with TLS (default: http) */
+    MCP_TRANSPORT: z.ZodDefault<z.ZodEnum<["stdio", "http", "https"]>>;
+    /**
+     * Enable Legacy SSE Transport (deprecated HTTP+SSE from protocol 2024-11-05)
+     * Default: false (only Streamable HTTP Transport enabled)
+     * Set to 'true' to enable backwards compatibility with older MCP clients
+     */
+    MCP_LEGACY_SSE_ENABLED: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodEffects<z.ZodString, boolean, string>]>>;
+    /**
+     * Operate in stateless mode (no session IDs).
+     *
+     * Each request gets a fresh McpSession and SDK transport.
+     * No Mcp-Session-Id headers are set. GET and DELETE return 405.
+     *
+     * @default false (stateful mode)
+     */
+    MCP_STATELESS: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodEffects<z.ZodString, boolean, string>]>>;
+    /**
+     * Prefer JSON responses over SSE streams for simple request-response.
+     *
+     * When enabled, the SDK returns `application/json` for non-streaming
+     * responses (e.g. tools/list, resources/list) instead of wrapping them
+     * in a `text/event-stream` SSE envelope.
+     *
+     * The MCP specification recommends: "If the server is only sending one
+     * response with no notifications, it SHOULD prefer application/json."
+     *
+     * Streaming responses (progress, notifications) always use SSE regardless.
+     *
+     * @default true (spec-compliant JSON responses)
+     */
+    MCP_JSON_RESPONSE: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodEffects<z.ZodString, boolean, string>]>>;
+    /** Path to TLS certificate file (PEM format). Required when MCP_TRANSPORT='https'. */
+    MCP_TLS_CERT_PATH: z.ZodOptional<z.ZodString>;
+    /** Path to TLS private key file (PEM format). Required when MCP_TRANSPORT='https'. */
+    MCP_TLS_KEY_PATH: z.ZodOptional<z.ZodString>;
+    /** Path to CA certificate file (PEM format). Optional for custom CA chains. */
+    MCP_TLS_CA_PATH: z.ZodOptional<z.ZodString>;
+    /** Allowed hosts for DNS rebinding protection (comma-separated) */
+    MCP_ALLOWED_HOSTS: z.ZodOptional<z.ZodEffects<z.ZodString, string[] | undefined, string>>;
+    /** Rate limit window in milliseconds (default: 900000 = 15 minutes) */
+    MCP_RATE_LIMIT_WINDOW_MS: z.ZodDefault<z.ZodNumber>;
+    /** Maximum requests per rate limit window (default: 1000) */
+    MCP_RATE_LIMIT_MAX: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Maximum request body size for `express.json()` middleware.
+     *
+     * Accepts Express size strings (e.g. `'1mb'`, `'500kb'`, `'2mb'`)
+     * or plain byte counts (e.g. `'1048576'`).
+     *
+     * Validated against the `bytes` library format used by Express/body-parser.
+     * Invalid values are rejected at config time to prevent silent limit bypass.
+     *
+     * @default '1mb'
+     */
+    MCP_BODY_SIZE_LIMIT: z.ZodDefault<z.ZodString>;
+    /**
+     * Trust proxy setting for Express.
+     *
+     * Required when running behind a reverse proxy (nginx, Traefik, cloud LB)
+     * to correctly resolve client IPs, protocol, and host from proxy headers
+     * (`X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host`).
+     *
+     * Values:
+     * - Hop count (`'1'`, `'2'`) — Trust N hops from the front-facing proxy
+     * - Express keyword (`'loopback'`, `'linklocal'`, `'uniquelocal'`)
+     * - IP address (`'10.0.0.1'`, `'::1'`)
+     * - CIDR range (`'10.0.0.0/8'`, `'172.16.0.0/12'`)
+     * - DNS hostname (`'proxy.example.com'`) — resolved at startup
+     * - Comma-separated list (`'loopback, 10.0.0.1'`)
+     *
+     * Omit or leave unset to disable trust proxy.
+     *
+     * @see https://expressjs.com/en/guide/behind-proxies.html
+     */
+    MCP_TRUST_PROXY: z.ZodOptional<z.ZodString>;
+    /**
+     * CORS allowed origins (comma-separated).
+     *
+     * When set, the CORS middleware is mounted globally and allows requests
+     * from the listed origins. When unset, CORS is disabled (no CORS headers).
+     *
+     * Use `'*'` to allow all origins (not recommended for production).
+     *
+     * @example 'https://app.example.com,https://admin.example.com'
+     */
+    MCP_CORS_ORIGIN: z.ZodOptional<z.ZodEffects<z.ZodString, string[] | undefined, string>>;
+    /**
+     * Allow credentials in CORS requests (cookies, auth headers).
+     *
+     * Only effective when MCP_CORS_ORIGIN is set.
+     * Cannot be used with `origin: '*'`.
+     *
+     * @default false
+     */
+    MCP_CORS_CREDENTIALS: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodEffects<z.ZodString, boolean, string>]>>;
+    /**
+     * Enable HTTP Strict Transport Security (HSTS) header.
+     *
+     * When true, Helmet sets `Strict-Transport-Security` with `max-age=15552000`
+     * (180 days) and `includeSubDomains`. Only enable when serving over HTTPS.
+     *
+     * @default false (managed by reverse proxy in production)
+     */
+    MCP_HELMET_HSTS: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodEffects<z.ZodString, boolean, string>]>>;
+    /**
+     * Content Security Policy configuration.
+     *
+     * - Omit or leave unset: Helmet default CSP applies
+     * - `'false'`: Disable CSP entirely
+     * - Custom string: Used as CSP directives (e.g. `"default-src 'self'"`).
+     *   Parsed as directive-name + values separated by semicolons.
+     */
+    MCP_HELMET_CSP: z.ZodOptional<z.ZodString>;
+    /**
+     * X-Frame-Options header value.
+     *
+     * Controls whether the server can be embedded in frames.
+     * - `'DENY'`: Never allow framing (most secure)
+     * - `'SAMEORIGIN'`: Allow framing from same origin
+     * - `'false'`: Disable X-Frame-Options header
+     *
+     * @default 'DENY'
+     */
+    MCP_HELMET_FRAME_OPTIONS: z.ZodDefault<z.ZodEnum<["DENY", "SAMEORIGIN", "false"]>>;
+    /**
+     * Required OAuth scopes for the `/mcp` endpoint (comma-separated).
+     *
+     * When set, all requests to `/mcp` must carry tokens with these scopes.
+     * Per-tool scopes can be configured via `ToolDefinition.auth.requiredScopes`.
+     *
+     * @example 'mcp:read,mcp:write'
+     */
+    MCP_AUTH_REQUIRED_SCOPES: z.ZodOptional<z.ZodEffects<z.ZodString, string[] | undefined, string>>;
+    /**
+     * Protected Resource Metadata URL (RFC 9728).
+     *
+     * When set, included in `WWW-Authenticate` headers for 401 responses,
+     * allowing clients to discover the authorization server.
+     *
+     * @example 'https://api.example.com/.well-known/oauth-protected-resource'
+     */
+    MCP_AUTH_RESOURCE_METADATA_URL: z.ZodOptional<z.ZodString>;
+    /** Maximum total concurrent sessions across all transports (default: 200) */
+    MCP_MAX_SESSIONS: z.ZodDefault<z.ZodNumber>;
+    /** Maximum concurrent Streamable HTTP sessions (default: 100) */
+    MCP_MAX_STREAMABLE_HTTP_SESSIONS: z.ZodDefault<z.ZodNumber>;
+    /** Maximum concurrent SSE sessions (default: 50) */
+    MCP_MAX_SSE_SESSIONS: z.ZodDefault<z.ZodNumber>;
+    /** Log level (trace, debug, info, warn, error) */
+    LOG_LEVEL: z.ZodDefault<z.ZodEnum<["trace", "debug", "info", "warn", "error"]>>;
+    /** Log format (text, json) */
+    LOG_FORMAT: z.ZodDefault<z.ZodEnum<["text", "json"]>>;
+    /** Include RFC 3339 timestamps in text log output (default: false) */
+    LOG_TIMESTAMP: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodEffects<z.ZodString, boolean, string>]>>;
+    /** Include component name (e.g. [server-runtime]) in text log output (default: false) */
+    LOG_COMPONENT: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodEffects<z.ZodString, boolean, string>]>>;
+    /** Directory to store logs (optional) */
+    LOG_DIR: z.ZodOptional<z.ZodString>;
+    /**
+     * Maximum size of a single log file before rotation.
+     *
+     * Accepts human-readable size strings (e.g. `'10mb'`, `'500kb'`, `'1gb'`)
+     * or plain byte counts (e.g. `'1048576'`). Parsed to bytes at config time.
+     *
+     * @default '10mb'
+     */
+    LOG_MAX_FILE_SIZE: z.ZodPipeline<z.ZodDefault<z.ZodEffects<z.ZodString, number, string>>, z.ZodNumber>;
+    /** Maximum number of rotated log files to keep (default: 3) */
+    LOG_MAX_FILES: z.ZodDefault<z.ZodNumber>;
+    /** Log file retention in days. Files older than this are deleted. 0 = disabled (default: 0) */
+    LOG_RETENTION_DAYS: z.ZodDefault<z.ZodNumber>;
+    /** Enable OpenTelemetry (default: false). Master toggle for all OTEL features. */
+    OTEL_ENABLED: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodEffects<z.ZodString, boolean, string>]>>;
+    /**
+     * OpenTelemetry service name.
+     *
+     * When not set, defaults to the MCP server name from `createServer({ name })`.
+     * Can be overridden via env var or config file to distinguish deployments
+     * (e.g. 'app-mcp-prod' vs 'app-mcp-staging').
+     *
+     * Also read natively by the SDK's resource detector via OTEL_SERVICE_NAME.
+     */
+    OTEL_SERVICE_NAME: z.ZodOptional<z.ZodString>;
+    /**
+     * OTLP exporter endpoint URL (e.g. http://localhost:4318).
+     *
+     * Used by both trace and metric OTLP exporters.
+     * Standard OTEL env var — also read natively by exporters,
+     * but parsed here to enable config file support.
+     */
+    OTEL_EXPORTER_OTLP_ENDPOINT: z.ZodOptional<z.ZodString>;
+    /**
+     * Trace exporter selection.
+     *
+     * Standard OTEL env var. When set, the framework builds the
+     * trace exporter explicitly instead of leaving it to SDK auto-config.
+     * Supported: 'otlp' , 'console', 'none' (default).
+     */
+    OTEL_TRACES_EXPORTER: z.ZodOptional<z.ZodString>;
+    /**
+     * Log exporter selection.
+     *
+     * Standard OTEL env var. Controls whether the NodeSDK auto-configures
+     * an OTLP log exporter. The framework uses its own logging system
+     * (see {@link Logger | framework logger}), so OTEL log export is disabled
+     * by default to prevent unwanted OTLP connections.
+     *
+     * Supported: 'otlp', 'console', 'none' (default).
+     */
+    OTEL_LOGS_EXPORTER: z.ZodDefault<z.ZodString>;
+    /**
+     * SDK diagnostic log level.
+     *
+     * Standard OTEL env var. Activates diag logging on the OTEL SDK.
+     * Values: 'NONE', 'ERROR', 'WARN', 'INFO', 'DEBUG', 'VERBOSE', 'ALL'.
+     */
+    OTEL_LOG_LEVEL: z.ZodOptional<z.ZodString>;
+    /**
+     * Periodic metric export interval in milliseconds.
+     *
+     * Standard OTEL env var name. Controls how often PeriodicExportingMetricReader
+     * pushes metrics to the OTLP endpoint or console.
+     */
+    OTEL_METRIC_EXPORT_INTERVAL: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Metric exporters to activate (comma-separated).
+     *
+     * Standard OTEL env var name. Supported values:
+     * - `otlp` — Push metrics to OTLP endpoint (reads OTEL_EXPORTER_OTLP_ENDPOINT natively)
+     * - `prometheus` — Prometheus scrape endpoint at /metrics on the MCP server
+     * - `console` — Log metrics to console (useful for debugging)
+     * - `none` — Disable all metric export
+     *
+     * Default: 'otlp,prometheus' (both OTLP push + Prometheus pull)
+     */
+    OTEL_METRICS_EXPORTER: z.ZodDefault<z.ZodEffects<z.ZodString, string[], string>>;
+}, "strip", z.ZodTypeAny, {
+    NODE_ENV: "production" | "development" | "test";
+    LOG_LEVEL: "error" | "trace" | "debug" | "info" | "warn";
+    LOG_FORMAT: "text" | "json";
+    MCP_TRANSPORT: "http" | "stdio" | "https";
+    LOG_MAX_FILE_SIZE: number;
+    LOG_MAX_FILES: number;
+    LOG_RETENTION_DAYS: number;
+    LOG_TIMESTAMP: boolean;
+    LOG_COMPONENT: boolean;
+    OTEL_ENABLED: boolean;
+    OTEL_METRICS_EXPORTER: string[];
+    OTEL_LOGS_EXPORTER: string;
+    VERSION: string;
+    MCP_BIND_HOST: string;
+    MCP_PORT: number;
+    MCP_LEGACY_SSE_ENABLED: boolean;
+    MCP_STATELESS: boolean;
+    MCP_JSON_RESPONSE: boolean;
+    MCP_RATE_LIMIT_WINDOW_MS: number;
+    MCP_RATE_LIMIT_MAX: number;
+    MCP_BODY_SIZE_LIMIT: string;
+    MCP_CORS_CREDENTIALS: boolean;
+    MCP_HELMET_HSTS: boolean;
+    MCP_HELMET_FRAME_OPTIONS: "DENY" | "SAMEORIGIN" | "false";
+    MCP_MAX_SESSIONS: number;
+    MCP_MAX_STREAMABLE_HTTP_SESSIONS: number;
+    MCP_MAX_SSE_SESSIONS: number;
+    LOG_DIR?: string | undefined;
+    OTEL_SERVICE_NAME?: string | undefined;
+    OTEL_EXPORTER_OTLP_ENDPOINT?: string | undefined;
+    OTEL_TRACES_EXPORTER?: string | undefined;
+    OTEL_LOG_LEVEL?: string | undefined;
+    OTEL_METRIC_EXPORT_INTERVAL?: number | undefined;
+    MCP_TLS_CERT_PATH?: string | undefined;
+    MCP_TLS_KEY_PATH?: string | undefined;
+    MCP_TLS_CA_PATH?: string | undefined;
+    MCP_ALLOWED_HOSTS?: string[] | undefined;
+    MCP_TRUST_PROXY?: string | undefined;
+    MCP_CORS_ORIGIN?: string[] | undefined;
+    MCP_HELMET_CSP?: string | undefined;
+    MCP_AUTH_REQUIRED_SCOPES?: string[] | undefined;
+    MCP_AUTH_RESOURCE_METADATA_URL?: string | undefined;
+}, {
+    NODE_ENV?: "production" | "development" | "test" | undefined;
+    LOG_LEVEL?: "error" | "trace" | "debug" | "info" | "warn" | undefined;
+    LOG_FORMAT?: "text" | "json" | undefined;
+    MCP_TRANSPORT?: "http" | "stdio" | "https" | undefined;
+    LOG_DIR?: string | undefined;
+    LOG_MAX_FILE_SIZE?: string | undefined;
+    LOG_MAX_FILES?: number | undefined;
+    LOG_RETENTION_DAYS?: number | undefined;
+    LOG_TIMESTAMP?: string | boolean | undefined;
+    LOG_COMPONENT?: string | boolean | undefined;
+    OTEL_ENABLED?: string | boolean | undefined;
+    OTEL_SERVICE_NAME?: string | undefined;
+    OTEL_METRICS_EXPORTER?: string | undefined;
+    OTEL_EXPORTER_OTLP_ENDPOINT?: string | undefined;
+    OTEL_TRACES_EXPORTER?: string | undefined;
+    OTEL_LOGS_EXPORTER?: string | undefined;
+    OTEL_LOG_LEVEL?: string | undefined;
+    OTEL_METRIC_EXPORT_INTERVAL?: number | undefined;
+    VERSION?: string | undefined;
+    MCP_BIND_HOST?: string | undefined;
+    MCP_PORT?: number | undefined;
+    MCP_LEGACY_SSE_ENABLED?: string | boolean | undefined;
+    MCP_STATELESS?: string | boolean | undefined;
+    MCP_JSON_RESPONSE?: string | boolean | undefined;
+    MCP_TLS_CERT_PATH?: string | undefined;
+    MCP_TLS_KEY_PATH?: string | undefined;
+    MCP_TLS_CA_PATH?: string | undefined;
+    MCP_ALLOWED_HOSTS?: string | undefined;
+    MCP_RATE_LIMIT_WINDOW_MS?: number | undefined;
+    MCP_RATE_LIMIT_MAX?: number | undefined;
+    MCP_BODY_SIZE_LIMIT?: string | undefined;
+    MCP_TRUST_PROXY?: string | undefined;
+    MCP_CORS_ORIGIN?: string | undefined;
+    MCP_CORS_CREDENTIALS?: string | boolean | undefined;
+    MCP_HELMET_HSTS?: string | boolean | undefined;
+    MCP_HELMET_CSP?: string | undefined;
+    MCP_HELMET_FRAME_OPTIONS?: "DENY" | "SAMEORIGIN" | "false" | undefined;
+    MCP_AUTH_REQUIRED_SCOPES?: string | undefined;
+    MCP_AUTH_RESOURCE_METADATA_URL?: string | undefined;
+    MCP_MAX_SESSIONS?: number | undefined;
+    MCP_MAX_STREAMABLE_HTTP_SESSIONS?: number | undefined;
+    MCP_MAX_SSE_SESSIONS?: number | undefined;
+}>, {
+    NODE_ENV: "production" | "development" | "test";
+    LOG_LEVEL: "error" | "trace" | "debug" | "info" | "warn";
+    LOG_FORMAT: "text" | "json";
+    MCP_TRANSPORT: "http" | "stdio" | "https";
+    LOG_MAX_FILE_SIZE: number;
+    LOG_MAX_FILES: number;
+    LOG_RETENTION_DAYS: number;
+    LOG_TIMESTAMP: boolean;
+    LOG_COMPONENT: boolean;
+    OTEL_ENABLED: boolean;
+    OTEL_METRICS_EXPORTER: string[];
+    OTEL_LOGS_EXPORTER: string;
+    VERSION: string;
+    MCP_BIND_HOST: string;
+    MCP_PORT: number;
+    MCP_LEGACY_SSE_ENABLED: boolean;
+    MCP_STATELESS: boolean;
+    MCP_JSON_RESPONSE: boolean;
+    MCP_RATE_LIMIT_WINDOW_MS: number;
+    MCP_RATE_LIMIT_MAX: number;
+    MCP_BODY_SIZE_LIMIT: string;
+    MCP_CORS_CREDENTIALS: boolean;
+    MCP_HELMET_HSTS: boolean;
+    MCP_HELMET_FRAME_OPTIONS: "DENY" | "SAMEORIGIN" | "false";
+    MCP_MAX_SESSIONS: number;
+    MCP_MAX_STREAMABLE_HTTP_SESSIONS: number;
+    MCP_MAX_SSE_SESSIONS: number;
+    LOG_DIR?: string | undefined;
+    OTEL_SERVICE_NAME?: string | undefined;
+    OTEL_EXPORTER_OTLP_ENDPOINT?: string | undefined;
+    OTEL_TRACES_EXPORTER?: string | undefined;
+    OTEL_LOG_LEVEL?: string | undefined;
+    OTEL_METRIC_EXPORT_INTERVAL?: number | undefined;
+    MCP_TLS_CERT_PATH?: string | undefined;
+    MCP_TLS_KEY_PATH?: string | undefined;
+    MCP_TLS_CA_PATH?: string | undefined;
+    MCP_ALLOWED_HOSTS?: string[] | undefined;
+    MCP_TRUST_PROXY?: string | undefined;
+    MCP_CORS_ORIGIN?: string[] | undefined;
+    MCP_HELMET_CSP?: string | undefined;
+    MCP_AUTH_REQUIRED_SCOPES?: string[] | undefined;
+    MCP_AUTH_RESOURCE_METADATA_URL?: string | undefined;
+}, {
+    NODE_ENV?: "production" | "development" | "test" | undefined;
+    LOG_LEVEL?: "error" | "trace" | "debug" | "info" | "warn" | undefined;
+    LOG_FORMAT?: "text" | "json" | undefined;
+    MCP_TRANSPORT?: "http" | "stdio" | "https" | undefined;
+    LOG_DIR?: string | undefined;
+    LOG_MAX_FILE_SIZE?: string | undefined;
+    LOG_MAX_FILES?: number | undefined;
+    LOG_RETENTION_DAYS?: number | undefined;
+    LOG_TIMESTAMP?: string | boolean | undefined;
+    LOG_COMPONENT?: string | boolean | undefined;
+    OTEL_ENABLED?: string | boolean | undefined;
+    OTEL_SERVICE_NAME?: string | undefined;
+    OTEL_METRICS_EXPORTER?: string | undefined;
+    OTEL_EXPORTER_OTLP_ENDPOINT?: string | undefined;
+    OTEL_TRACES_EXPORTER?: string | undefined;
+    OTEL_LOGS_EXPORTER?: string | undefined;
+    OTEL_LOG_LEVEL?: string | undefined;
+    OTEL_METRIC_EXPORT_INTERVAL?: number | undefined;
+    VERSION?: string | undefined;
+    MCP_BIND_HOST?: string | undefined;
+    MCP_PORT?: number | undefined;
+    MCP_LEGACY_SSE_ENABLED?: string | boolean | undefined;
+    MCP_STATELESS?: string | boolean | undefined;
+    MCP_JSON_RESPONSE?: string | boolean | undefined;
+    MCP_TLS_CERT_PATH?: string | undefined;
+    MCP_TLS_KEY_PATH?: string | undefined;
+    MCP_TLS_CA_PATH?: string | undefined;
+    MCP_ALLOWED_HOSTS?: string | undefined;
+    MCP_RATE_LIMIT_WINDOW_MS?: number | undefined;
+    MCP_RATE_LIMIT_MAX?: number | undefined;
+    MCP_BODY_SIZE_LIMIT?: string | undefined;
+    MCP_TRUST_PROXY?: string | undefined;
+    MCP_CORS_ORIGIN?: string | undefined;
+    MCP_CORS_CREDENTIALS?: string | boolean | undefined;
+    MCP_HELMET_HSTS?: string | boolean | undefined;
+    MCP_HELMET_CSP?: string | undefined;
+    MCP_HELMET_FRAME_OPTIONS?: "DENY" | "SAMEORIGIN" | "false" | undefined;
+    MCP_AUTH_REQUIRED_SCOPES?: string | undefined;
+    MCP_AUTH_RESOURCE_METADATA_URL?: string | undefined;
+    MCP_MAX_SESSIONS?: number | undefined;
+    MCP_MAX_STREAMABLE_HTTP_SESSIONS?: number | undefined;
+    MCP_MAX_SSE_SESSIONS?: number | undefined;
+}>;
+/**
+ * Constraint violation from cross-field validation.
+ */
+export interface ConfigConstraintViolation {
+    readonly message: string;
+    readonly path: readonly string[];
+}
+/**
+ * Validate cross-field constraints on the framework configuration.
+ *
+ * Extracted as a standalone function so it can be called:
+ * 1. By the Zod schema's `superRefine` (env-only parsing)
+ * 2. By the config cache after merging all sources (env + file + overrides)
+ *
+ * @param config - The (potentially merged) configuration to validate
+ * @returns Array of constraint violations (empty = valid)
+ */
+export declare function validateConfigConstraints(config: Pick<FrameworkEnvConfig, "MCP_TRANSPORT" | "MCP_TLS_CERT_PATH" | "MCP_TLS_KEY_PATH" | "MCP_TLS_CA_PATH" | "MCP_MAX_SESSIONS" | "MCP_MAX_STREAMABLE_HTTP_SESSIONS" | "MCP_MAX_SSE_SESSIONS">): ConfigConstraintViolation[];
+/**
+ * Framework environment configuration type.
+ */
+export type FrameworkEnvConfig = z.infer<typeof frameworkEnvSchema>;
+/**
+ * Parse and validate an environment source against the framework schema.
+ *
+ * @param envSource - Key-value object to parse (defaults to `process.env`)
+ * @returns Validated framework configuration
+ * @internal Used only by config-cache.ts — consumers should use `getFrameworkConfig()`
+ */
+export declare function parseFrameworkEnv(envSource?: Record<string, string | undefined>): FrameworkEnvConfig;
+//# sourceMappingURL=env.d.ts.map

package/build/config/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiDxB;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB;IAM3B;;;;;;OAMG;;IAGH,uDAAuD;;IAOvD,0DAA0D;;IAG1D,wCAAwC;;IAGxC,mGAAmG;;IAGnG;;;;OAIG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;;;;;;;OAaG;;IAOH,sFAAsF;;IAGtF,sFAAsF;;IAGtF,+EAA+E;;IAO/E,mEAAmE;;IAGnE,uEAAuE;;IAGvE,6DAA6D;;IAG7D;;;;;;;;;;OAUG;;IASH;;;;;;;;;;;;;;;;;;OAkBG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;;;OASG;;IAOH;;;;;;;OAOG;;IAGH;;;;;;;OAOG;;IAOH,6EAA6E;;IAG7E,iEAAiE;;IAGjE,oDAAoD;;IAOpD,kDAAkD;;IAGlD,8BAA8B;;IAG9B,sEAAsE;;IAGtE,yFAAyF;;IAGzF,yCAAyC;;IAGzC;;;;;;;OAOG;;IAGH,+DAA+D;;IAG/D,+FAA+F;;IAa/F,kFAAkF;;IAGlF;;;;;;;;OAQG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;;;;;;OAUG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAeH,CAAC;AAML;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,IAAI,CACV,kBAAkB,EAChB,eAAe,GACf,mBAAmB,GACnB,kBAAkB,GAClB,iBAAiB,GACjB,kBAAkB,GAClB,kCAAkC,GAClC,sBAAsB,CACzB,GACA,yBAAyB,EAAE,CAgE7B;AAMD;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,kBAAkB,CAEjH"}