refactor(env): extract MCP env vars into per-var modules under src/env

cmd-mcp was reading 7 environment variables directly via process env
lookups. Move each to its own module under src/env, exposing a getter
that reads at call time so tests that mutate process env between
invocations see the latest value.

New modules:
- mcp-http-mode.mts          → getMcpHttpMode()
- mcp-port.mts               → getMcpPort()
- socket-oauth-issuer.mts    → getSocketOauthIssuer()
- socket-oauth-introspection-client-id.mts     → getSocketOauthIntrospectionClientId()
- socket-oauth-introspection-client-secret.mts → getSocketOauthIntrospectionClientSecret()
- socket-oauth-required-scopes.mts             → getSocketOauthRequiredScopes()
- trust-proxy.mts            → getTrustProxy()

cmd-mcp now imports the typed getters instead of poking process env
directly. All 269 existing mcp unit tests still pass; the load-time
constant pattern would have broken the runtime mutation tests rely on.

Author: jdalton

packages/cli/src/commands/mcp/cmd-mcp.mts

@@ -1,4 +1,11 @@
 import { handleMcp } from './handle-mcp.mts'
+import { getMcpHttpMode } from '../../env/mcp-http-mode.mts'
+import { getMcpPort } from '../../env/mcp-port.mts'
+import { getSocketOauthIntrospectionClientId } from '../../env/socket-oauth-introspection-client-id.mts'
+import { getSocketOauthIntrospectionClientSecret } from '../../env/socket-oauth-introspection-client-secret.mts'
+import { getSocketOauthIssuer } from '../../env/socket-oauth-issuer.mts'
+import { getSocketOauthRequiredScopes } from '../../env/socket-oauth-required-scopes.mts'
+import { getTrustProxy } from '../../env/trust-proxy.mts'
 import { commonFlags } from '../../flags.mts'
 import { defineFlags } from '../../meow.mts'
 import { meowOrExit } from '../../utils/cli/with-subcommands.mjs'
@@ -130,38 +137,31 @@ export async function run(
     parentName,
   })
 
-  const envHttp = process.env['MCP_HTTP_MODE'] === 'true'
-  const http = cli.flags.http || envHttp
+  const http = cli.flags.http || getMcpHttpMode()
 
   const portFlag = cli.flags.port
   const portRaw =
     portFlag && portFlag > 0
       ? portFlag
-      : Number.parseInt(process.env['MCP_PORT'] || `${DEFAULT_PORT}`, 10)
+      : Number.parseInt(getMcpPort() || `${DEFAULT_PORT}`, 10)
   const port = Number.isFinite(portRaw) && portRaw > 0 ? portRaw : DEFAULT_PORT
 
-  const oauthIssuer =
-    cli.flags['oauth-issuer'] ||
-    process.env['SOCKET_OAUTH_ISSUER'] ||
-    ''
+  const oauthIssuer = cli.flags['oauth-issuer'] || getSocketOauthIssuer() || ''
   const oauthClientId =
     cli.flags['oauth-client-id'] ||
-    process.env['SOCKET_OAUTH_INTROSPECTION_CLIENT_ID'] ||
+    getSocketOauthIntrospectionClientId() ||
     ''
   const oauthClientSecret =
     cli.flags['oauth-client-secret'] ||
-    process.env['SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET'] ||
+    getSocketOauthIntrospectionClientSecret() ||
     ''
   const oauthRequiredScopesRaw =
-    cli.flags['oauth-required-scopes'] ||
-    process.env['SOCKET_OAUTH_REQUIRED_SCOPES'] ||
-    ''
+    cli.flags['oauth-required-scopes'] || getSocketOauthRequiredScopes() || ''
   const oauthRequiredScopes = oauthRequiredScopesRaw
     ? parseRequiredScopes(oauthRequiredScopesRaw)
     : undefined
 
-  const trustProxy =
-    cli.flags['trust-proxy'] || process.env['TRUST_PROXY'] === 'true'
+  const trustProxy = cli.flags['trust-proxy'] || getTrustProxy()
 
   await handleMcp({
     http,

packages/cli/src/env/mcp-http-mode.mts

@@ -0,0 +1,16 @@
+/**
+ * MCP_HTTP_MODE environment variable.
+ *
+ * When set to the literal string "true", forces the `socket mcp` command to
+ * serve over HTTP instead of stdio. Useful in container / CI setups where
+ * stdio binding isn't available.
+ *
+ * Read lazily so tests that mutate process.env after module load see the
+ * latest value.
+ */
+
+import process from 'node:process'
+
+export function getMcpHttpMode(): boolean {
+  return process.env['MCP_HTTP_MODE'] === 'true'
+}

packages/cli/src/env/mcp-port.mts

@@ -0,0 +1,15 @@
+/**
+ * MCP_PORT environment variable.
+ *
+ * Port the `socket mcp` HTTP server should listen on when running in HTTP
+ * mode. Empty string when unset; the caller decides the default.
+ *
+ * Read lazily so tests that mutate process.env after module load see the
+ * latest value.
+ */
+
+import process from 'node:process'
+
+export function getMcpPort(): string {
+  return process.env['MCP_PORT'] ?? ''
+}

packages/cli/src/env/socket-oauth-introspection-client-id.mts

@@ -0,0 +1,15 @@
+/**
+ * SOCKET_OAUTH_INTROSPECTION_CLIENT_ID environment variable.
+ *
+ * Client ID used by the `socket mcp` HTTP server when calling the OAuth
+ * introspection endpoint. Empty string when unset.
+ *
+ * Read lazily so tests that mutate process.env after module load see the
+ * latest value.
+ */
+
+import process from 'node:process'
+
+export function getSocketOauthIntrospectionClientId(): string {
+  return process.env['SOCKET_OAUTH_INTROSPECTION_CLIENT_ID'] ?? ''
+}

packages/cli/src/env/socket-oauth-introspection-client-secret.mts

@@ -0,0 +1,15 @@
+/**
+ * SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET environment variable.
+ *
+ * Client secret paired with SOCKET_OAUTH_INTROSPECTION_CLIENT_ID for the
+ * `socket mcp` OAuth introspection call. Empty string when unset.
+ *
+ * Read lazily so tests that mutate process.env after module load see the
+ * latest value.
+ */
+
+import process from 'node:process'
+
+export function getSocketOauthIntrospectionClientSecret(): string {
+  return process.env['SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET'] ?? ''
+}

packages/cli/src/env/socket-oauth-issuer.mts

@@ -0,0 +1,15 @@
+/**
+ * SOCKET_OAUTH_ISSUER environment variable.
+ *
+ * Issuer URL the `socket mcp` HTTP server uses to validate inbound OAuth
+ * tokens. Empty string when unset.
+ *
+ * Read lazily so tests that mutate process.env after module load see the
+ * latest value.
+ */
+
+import process from 'node:process'
+
+export function getSocketOauthIssuer(): string {
+  return process.env['SOCKET_OAUTH_ISSUER'] ?? ''
+}

packages/cli/src/env/socket-oauth-required-scopes.mts

@@ -0,0 +1,15 @@
+/**
+ * SOCKET_OAUTH_REQUIRED_SCOPES environment variable.
+ *
+ * Whitespace-separated list of OAuth scopes the `socket mcp` HTTP server
+ * requires on every inbound token. Empty string when unset (no scope check).
+ *
+ * Read lazily so tests that mutate process.env after module load see the
+ * latest value.
+ */
+
+import process from 'node:process'
+
+export function getSocketOauthRequiredScopes(): string {
+  return process.env['SOCKET_OAUTH_REQUIRED_SCOPES'] ?? ''
+}

packages/cli/src/env/trust-proxy.mts

@@ -0,0 +1,16 @@
+/**
+ * TRUST_PROXY environment variable.
+ *
+ * When set to the literal string "true", the `socket mcp` HTTP server trusts
+ * X-Forwarded-* headers from upstream proxies (e.g., when running behind a
+ * load balancer that terminates TLS).
+ *
+ * Read lazily so tests that mutate process.env after module load see the
+ * latest value.
+ */
+
+import process from 'node:process'
+
+export function getTrustProxy(): boolean {
+  return process.env['TRUST_PROXY'] === 'true'
+}