Context
Epic #10822 aims to establish clear environment variable vs configuration priority. We identified a systemic priority inversion where Config.load() (Neo.merge) inadvertently overwrote environment variable defaults with JSON config values across multiple MCP servers.
The Problem
Fragmented, one-off "normalizer" helpers (e.g., in DeploymentConfig.mjs and EmbeddingProviderConfig.mjs) failed to address the core priority inversion. These helpers were ad-hoc and did not natively support nested keys, strict validation safety, or empty-string preservation.
The Architectural Reality
The triad swarm reached consensus in Discussion #10840: we must shift to a single source-of-truth applyEnv() reflex. This pattern uses a flat, dot-path ledger (envBindings) mapping environment variables to configuration keys, combined with explicit parsing functions (e.g., parsePort, parseBool) to guarantee runtime safety.
The Fix
Implement the new EnvConfig.mjs utility and strict parsers, migrate all MCP server config.template.mjs files to use the envBindings map, and completely deprecate the legacy helper files.
Acceptance Criteria
Origin Session ID
88a6ed3a-b1b9-461a-aaf3-7c9984bd12e7
Context Epic #10822 aims to establish clear environment variable vs configuration priority. We identified a systemic priority inversion where
Config.load()(Neo.merge) inadvertently overwrote environment variable defaults with JSON config values across multiple MCP servers.The Problem Fragmented, one-off "normalizer" helpers (e.g., in
DeploymentConfig.mjsandEmbeddingProviderConfig.mjs) failed to address the core priority inversion. These helpers were ad-hoc and did not natively support nested keys, strict validation safety, or empty-string preservation.The Architectural Reality The triad swarm reached consensus in Discussion #10840: we must shift to a single source-of-truth
applyEnv()reflex. This pattern uses a flat, dot-path ledger (envBindings) mapping environment variables to configuration keys, combined with explicit parsing functions (e.g.,parsePort,parseBool) to guarantee runtime safety.The Fix Implement the new
EnvConfig.mjsutility and strict parsers, migrate all MCP serverconfig.template.mjsfiles to use theenvBindingsmap, and completely deprecate the legacy helper files.Acceptance Criteria
EnvConfig.mjshelper (applyEnvBindings+setDeep+ parsers) created inai/mcp/server/shared/helpers/.ai/config.template.mjsmigrates toenvBindings(noprocess.envin defaults).config.template.mjsmigrate toenvBindings.DeploymentConfig.mjs5 helpers +EmbeddingProviderConfig.mjsentire file.process.env.Xreads in config templates for env-bound keys (or explicit justification).Origin Session ID
88a6ed3a-b1b9-461a-aaf3-7c9984bd12e7