codex-plugin-doctor 1.71.0 → 1.72.0

package/README.md

@@ -148,7 +148,8 @@ approved loopback endpoint; it is never printed or saved. The GitHub Action can
 live list with `tools-capture-url` (and `tools-capture-token-env`) or, for a local
 stdio server with `runtime: "true"`, `tools-capture-server`, and skip the
 plugin package check with `check: "false"` in repositories that only ship an MCP
-server.
+server. With `tools-diff-comment: "true"` it also posts the comparison as one
+pull request comment that later runs update.
 
 Local stdio servers from a package's MCP configuration can be cataloged too.
 `--runtime` is required because this starts package code; the server is stopped
@@ -161,7 +162,9 @@ codex-plugin-doctor doctor tools ./my-plugin --server my-server --runtime --save
 Doctor tries `server/discover` (`2026-07-28`) first and falls back to the
 `initialize` handshake for older stdio servers, so the saved list works with
 `tools-file` and `tools-diff` either way. `--sandbox docker` and
-`--require-runtime-approval` work as they do for `check --runtime`.
+`--require-runtime-approval` work as they do for `check --runtime`; add
+`--env <NAME>` to pass a host variable such as an API key into the Docker
+container by name.
 See [MCP Tool Catalog](docs/guides/mcp-tool-catalog.md).
 
 ### Remote MCP Readiness
@@ -582,9 +585,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.71.0
+      - uses: Esquetta/CodexPluginDoctor@v1.72.0
         with:
-          version: "1.71.0"
+          version: "1.72.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/mcp-stdio-tool-catalog.d.ts

@@ -17,6 +17,7 @@ export type McpStdioServerResolution = {
 };
 export interface McpStdioToolCatalogOptions {
     sandbox?: RuntimeSandboxMode;
+    environment?: readonly string[];
     now?: () => number;
     spawnImpl?: typeof spawn;
     removeContainerImpl?: (containerName: string) => Promise<boolean>;

package/dist/core/mcp-stdio-tool-catalog.js

@@ -390,7 +390,8 @@ export async function captureStdioMcpToolCatalog(server, options = {}) {
             command: server.command,
             args: server.args,
             cwd: server.cwd,
-            containerName: `codex-doctor-${randomUUID()}`
+            containerName: `codex-doctor-${randomUUID()}`,
+            environment: options.environment
         })
         : {
             command: server.command,

package/dist/core/mcp-tool-impact.js

@@ -29,14 +29,31 @@ const DOCUMENTATION_KEYWORDS = new Set(["title", "description", "examples", "def
 const ROOT_STRUCTURAL_KEYWORDS = new Set(["type", "properties", "required", "additionalProperties", "$schema"]);
 const LOWER_BOUND_KEYWORDS = ["minimum", "minLength", "minItems"];
 const UPPER_BOUND_KEYWORDS = ["maximum", "maxLength", "maxItems"];
+// String keywords that can only be introduced or removed with a known effect; a changed value is unclassified.
+const STRING_CONSTRAINT_KEYWORDS = ["pattern", "format"];
 const NESTED_STRUCTURAL_KEYWORDS = new Set([
-    "type", "enum", "properties", "required", "additionalProperties", "items", ...LOWER_BOUND_KEYWORDS, ...UPPER_BOUND_KEYWORDS
+    "type", "enum", "const", "properties", "required", "additionalProperties", "items",
+    ...LOWER_BOUND_KEYWORDS, ...UPPER_BOUND_KEYWORDS, ...STRING_CONSTRAINT_KEYWORDS
 ]);
+// When every reference is a same-document fragment, definition containers are compared only
+// where a resolved `$ref` reaches into them; otherwise they are compared as written.
+const DEFINITION_CONTAINERS = ["$defs", "definitions"];
+const ROOT_STRUCTURAL_WITH_DEFINITIONS = new Set([...ROOT_STRUCTURAL_KEYWORDS, ...DEFINITION_CONTAINERS]);
+const NESTED_STRUCTURAL_WITH_DEFINITIONS = new Set([...NESTED_STRUCTURAL_KEYWORDS, ...DEFINITION_CONTAINERS]);
+// Keywords whose values are data rather than subschemas, so reference-like keys inside them are ignored.
+// `example` is the OpenAPI spelling that generated MCP schemas often carry.
+const DATA_KEYWORDS = new Set(["enum", "const", "examples", "example", "default"]);
+// Keywords whose values map names to subschemas; their keys are names, never keywords.
+const NAME_MAP_KEYWORDS = new Set(["properties", "patternProperties", "$defs", "definitions", "dependentSchemas", "dependencies"]);
 // Subschemas nested deeper than this below the root are not compared and stay unclassified.
 const MAX_NESTED_DEPTH = 8;
 // Keywords that only hold or name subschemas and never validate the object's own keys, so a
 // new property beside them stays compatible. Any other unclassified keyword may govern keys.
 const DEFINITION_KEYWORDS = new Set(["$defs", "definitions", "$id", "$anchor", "$dynamicAnchor"]);
+// A `$ref` chain longer than this, such as an alias cycle, is not resolved.
+const MAX_REFERENCE_HOPS = 8;
+// Schema comparisons allowed per tool field; a schema that needs more is unclassified.
+const MAX_COMPARISONS = 10_000;
 const CODES = {
     input: {
         unclassified: "input-schema-unclassified",
@@ -91,6 +108,14 @@ function typesCovered(inner, outer) {
     }
     return true;
 }
+/** The values `enum` and `const` together admit; `const` behaves as a single-value `enum`. */
+function allowedValues(schema, equal) {
+    if (!Object.hasOwn(schema, "const"))
+        return schema.enum;
+    if (schema.enum === undefined)
+        return [schema.const];
+    return Array.isArray(schema.enum) ? schema.enum.filter((value) => equal(value, schema.const)) : schema.enum;
+}
 function enumCovered(inner, outer, equal) {
     if (outer === undefined)
         return true;
@@ -143,19 +168,267 @@ function compareBounds(inner, outer, codes, reasons) {
         }
     }
 }
+/** Flags a `pattern` or `format` that `outer` adds and `inner` lacks; a changed value cannot be compared. */
+function compareStringConstraints(inner, outer, codes, reasons) {
+    for (const keyword of STRING_CONSTRAINT_KEYWORDS) {
+        const outerValue = outer[keyword];
+        const innerValue = inner[keyword];
+        if ((outerValue !== undefined && typeof outerValue !== "string") || (innerValue !== undefined && typeof innerValue !== "string")) {
+            reasons.add(codes.unclassified);
+        }
+        else if (outerValue !== undefined && innerValue !== outerValue) {
+            reasons.add(innerValue === undefined ? codes.constraint : codes.unclassified);
+        }
+    }
+}
+/** Resolves an RFC 6901 JSON Pointer fragment such as `#/$defs/Item` against a root schema. */
+function pointerTarget(document, pointer) {
+    if (pointer === "#")
+        return document;
+    if (!pointer.startsWith("#/"))
+        return undefined;
+    // RFC 6901 section 6: the fragment is percent-decoded as a whole before it is split into tokens.
+    let decoded;
+    try {
+        decoded = decodeURIComponent(pointer.slice(2));
+    }
+    catch {
+        return undefined;
+    }
+    let current = document;
+    for (const escaped of decoded.split("/")) {
+        const token = escaped.replace(/~1/gu, "/").replace(/~0/gu, "~");
+        if (Array.isArray(current) && /^(0|[1-9]\d*)$/u.test(token))
+            current = current[Number(token)];
+        else if (isJsonObject(current) && Object.hasOwn(current, token))
+            current = current[token];
+        else
+            return undefined;
+    }
+    return current;
+}
+/**
+ * Visits every schema position below `value`. It walks with an explicit stack, because tool files may
+ * nest JSON far deeper than the call stack allows, and skips data values but not names in name maps.
+ */
+function collect(value, visit) {
+    const pending = [{ value, names: false }];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (Array.isArray(current.value)) {
+            for (const entry of current.value)
+                pending.push({ value: entry, names: false });
+        }
+        else if (current.names && isJsonObject(current.value)) {
+            for (const entry of Object.values(current.value))
+                pending.push({ value: entry, names: false });
+        }
+        else if (isJsonObject(current.value)) {
+            visit(current.value);
+            for (const [key, entry] of Object.entries(current.value)) {
+                if (!DATA_KEYWORDS.has(key))
+                    pending.push({ value: entry, names: NAME_MAP_KEYWORDS.has(key) });
+            }
+        }
+    }
+}
+const nestedIdCache = new WeakMap();
+/** A nested `$id` starts a new base URI, so fragments below it no longer point into the root. */
+function hasNestedId(document) {
+    if (!isJsonObject(document))
+        return false;
+    const cached = nestedIdCache.get(document);
+    if (cached !== undefined)
+        return cached;
+    let found = false;
+    collect(document, (schema) => {
+        // Draft-04 names a resource with `id`.
+        if (schema !== document && (typeof schema.$id === "string" || typeof schema.id === "string"))
+            found = true;
+    });
+    nestedIdCache.set(document, found);
+    return found;
+}
+const opaqueCache = new WeakMap();
+/**
+ * True when a reference target holds a reference that is not a same-document fragment, or a
+ * resource identifier. Whole-document scans skip data values, so a `$ref` that points into one
+ * could otherwise reach references those scans never saw.
+ */
+function opaqueTarget(target, document) {
+    if (!isJsonObject(target) && !Array.isArray(target))
+        return false;
+    const cached = opaqueCache.get(target);
+    if (cached !== undefined)
+        return cached;
+    let opaque = false;
+    collect(target, (schema) => {
+        if (schema.$dynamicRef !== undefined || schema.$recursiveRef !== undefined
+            || (typeof schema.$ref === "string" && !schema.$ref.startsWith("#"))
+            || (schema !== document && (typeof schema.$id === "string" || typeof schema.id === "string")))
+            opaque = true;
+    });
+    opaqueCache.set(target, opaque);
+    return opaque;
+}
+/**
+ * False when a definition may be reached other than through a same-document `$ref` fragment:
+ * through `$dynamicRef` or `$recursiveRef`, a URI reference, or a nested `$id` resource.
+ */
+function reachesDefinitionsOnlyThroughFragments(document) {
+    let fragmentsOnly = !hasNestedId(document);
+    collect(document, (schema) => {
+        if (schema.$dynamicRef !== undefined || schema.$recursiveRef !== undefined
+            || (typeof schema.$ref === "string" && !schema.$ref.startsWith("#")))
+            fragmentsOnly = false;
+    });
+    return fragmentsOnly;
+}
+function referenceScope(before, after) {
+    return {
+        before,
+        after,
+        fragmentsOnly: reachesDefinitionsOnlyThroughFragments(before) && reachesDefinitionsOnlyThroughFragments(after),
+        active: new Set(),
+        completed: new Map(),
+        same: new Map(),
+        pointers: new Map(),
+        remaining: MAX_COMPARISONS
+    };
+}
+/** Records a resolved pair as compared at this depth; returns false when it already was. */
+function markCompleted(scope, before, after, depth) {
+    let byAfter = scope.completed.get(before);
+    if (byAfter === undefined)
+        scope.completed.set(before, byAfter = new Map());
+    let depths = byAfter.get(after);
+    if (depths === undefined)
+        byAfter.set(after, depths = new Set());
+    if (depths.has(depth))
+        return false;
+    depths.add(depth);
+    return true;
+}
+/**
+ * Follows same-document `$ref` pointers. Returns the referenced schema and the last pointer, the
+ * schema itself when it is not a reference, or null when a reference cannot be resolved safely.
+ */
+function resolveReferences(schema, document) {
+    let current = schema;
+    let ref;
+    for (let hop = 0; isJsonObject(current) && current.$ref !== undefined; hop += 1) {
+        const pointer = current.$ref;
+        // Siblings other than documentation would validate alongside the target.
+        if (hop === MAX_REFERENCE_HOPS || typeof pointer !== "string" || hasNestedId(document)
+            || Object.keys(current).some((key) => key !== "$ref" && !DOCUMENTATION_KEYWORDS.has(key)))
+            return null;
+        const target = pointerTarget(document, pointer);
+        if (target === undefined || opaqueTarget(target, document))
+            return null;
+        ref = pointer;
+        current = target;
+    }
+    return { schema: current, ref };
+}
+/** True when the schemas are equal and every same-document schema they reach is equal in both roots. */
+function sameMeaning(before, after, equal, scope) {
+    if (typeof before !== "object" || before === null || typeof after !== "object" || after === null) {
+        return computeSameMeaning(before, after, equal, scope);
+    }
+    let byAfter = scope.same.get(before);
+    if (byAfter === undefined)
+        scope.same.set(before, byAfter = new Map());
+    let result = byAfter.get(after);
+    if (result === undefined)
+        byAfter.set(after, result = computeSameMeaning(before, after, equal, scope));
+    return result;
+}
+function fragmentPointers(value) {
+    const pointers = [];
+    collect(value, (schema) => {
+        if (typeof schema.$ref === "string" && schema.$ref.startsWith("#"))
+            pointers.push(schema.$ref);
+    });
+    return pointers;
+}
+/** Compares a pointer's targets once per scope, so a large shared definition is walked once. */
+function pointerInfo(pointer, equal, scope) {
+    let info = scope.pointers.get(pointer);
+    if (info === undefined) {
+        const target = pointerTarget(scope.before, pointer);
+        const afterTarget = pointerTarget(scope.after, pointer);
+        info = target === undefined || !equal(target, afterTarget)
+            || opaqueTarget(target, scope.before) || opaqueTarget(afterTarget, scope.after)
+            ? { same: false, inner: [] }
+            : { same: true, inner: fragmentPointers(target) };
+        scope.pointers.set(pointer, info);
+    }
+    return info;
+}
+function computeSameMeaning(before, after, equal, scope) {
+    if (!equal(before, after))
+        return false;
+    const pending = fragmentPointers(before);
+    if (pending.length > 0 && (hasNestedId(scope.before) || hasNestedId(scope.after)))
+        return false;
+    const seen = new Set();
+    while (pending.length > 0) {
+        const pointer = pending.pop();
+        if (seen.has(pointer))
+            continue;
+        seen.add(pointer);
+        const info = pointerInfo(pointer, equal, scope);
+        if (!info.same)
+            return false;
+        for (const inner of info.inner)
+            pending.push(inner);
+    }
+    return true;
+}
 /**
  * Compares one schema and its object and array subschemas. `direction` is "input" when callers
  * must keep being accepted (after must cover before) and "output" when consumers must keep
  * understanding results (before must cover after). Depth 0 is the tool's root schema.
  */
-function compareSchema(before, after, direction, depth, equal, reasons) {
-    if (equal(before, after))
-        return;
+function compareSchema(before, after, direction, depth, equal, reasons, scope) {
     const codes = CODES[direction];
+    if (scope.remaining <= 0) {
+        reasons.add(codes.unclassified);
+        return;
+    }
+    scope.remaining -= 1;
+    if (sameMeaning(before, after, equal, scope))
+        return;
+    const resolvedBefore = resolveReferences(before, scope.before);
+    const resolvedAfter = resolveReferences(after, scope.after);
+    if (resolvedBefore === null || resolvedAfter === null) {
+        reasons.add(codes.unclassified);
+        return;
+    }
+    if (resolvedBefore.ref !== undefined || resolvedAfter.ref !== undefined) {
+        // A reference pair already being compared further up is assumed to hold, so recursive
+        // definitions terminate; a pair with one inline side is bounded by the depth limit. A pair
+        // already compared at this depth added its reasons then.
+        const pair = resolvedBefore.ref !== undefined && resolvedAfter.ref !== undefined
+            ? JSON.stringify([resolvedBefore.ref, resolvedAfter.ref])
+            : undefined;
+        if (pair !== undefined && scope.active.has(pair))
+            return;
+        if (!markCompleted(scope, resolvedBefore.schema, resolvedAfter.schema, depth))
+            return;
+        if (pair !== undefined)
+            scope.active.add(pair);
+        compareSchema(resolvedBefore.schema, resolvedAfter.schema, direction, depth, equal, reasons, scope);
+        if (pair !== undefined)
+            scope.active.delete(pair);
+        return;
+    }
     const root = depth === 0;
-    const structural = root ? ROOT_STRUCTURAL_KEYWORDS : NESTED_STRUCTURAL_KEYWORDS;
+    const structural = scope.fragmentsOnly
+        ? root ? ROOT_STRUCTURAL_WITH_DEFINITIONS : NESTED_STRUCTURAL_WITH_DEFINITIONS
+        : root ? ROOT_STRUCTURAL_KEYWORDS : NESTED_STRUCTURAL_KEYWORDS;
     if (depth > MAX_NESTED_DEPTH || !isJsonObject(before) || !isJsonObject(after)
-        || !equal(keywordsOutside(before, structural), keywordsOutside(after, structural))
+        || !sameMeaning(keywordsOutside(before, structural), keywordsOutside(after, structural), equal, scope)
         || !equal(before.$schema, after.$schema)) {
         reasons.add(codes.unclassified);
         return;
@@ -167,19 +440,20 @@ function compareSchema(before, after, direction, depth, equal, reasons) {
     if (!typesCovered(typeSet(inner), typeSet(outer)))
         reasons.add(root ? codes.rootType : codes.propertyType);
     if (!root) {
-        const enumResult = enumCovered(inner.enum, outer.enum, equal);
+        const enumResult = enumCovered(allowedValues(inner, equal), allowedValues(outer, equal), equal);
         if (enumResult === null)
             reasons.add(codes.unclassified);
         else if (!enumResult)
             reasons.add(codes.enumChanged);
         compareBounds(inner, outer, codes, reasons);
-        if (!equal(before.items, after.items)) {
+        compareStringConstraints(inner, outer, codes, reasons);
+        if (!sameMeaning(before.items, after.items, equal, scope)) {
             if (unevaluated)
                 reasons.add(codes.unclassified);
             else if (outer.items !== undefined && inner.items === undefined)
                 reasons.add(codes.constraint);
             else if (outer.items !== undefined)
-                compareSchema(before.items, after.items, direction, depth + 1, equal, reasons);
+                compareSchema(before.items, after.items, direction, depth + 1, equal, reasons, scope);
         }
     }
     const innerRequired = stringSet(inner.required);
@@ -198,14 +472,15 @@ function compareSchema(before, after, direction, depth, equal, reasons) {
         if (!Object.hasOwn(afterProperties, key))
             reasons.add(codes.propertyRemoved);
         else
-            compareSchema(beforeProperties[key], afterProperties[key], direction, depth + 1, equal, reasons);
+            compareSchema(beforeProperties[key], afterProperties[key], direction, depth + 1, equal, reasons, scope);
     }
     // In an object whose undeclared keys were governed by other keywords, or a nested input object
     // that left them open, a newly declared property can reject values callers send (input) or
     // produce values consumers did not expect (output).
     const addedKeys = Object.keys(afterProperties).filter((key) => !Object.hasOwn(beforeProperties, key));
     if (addedKeys.length > 0) {
-        const governed = isJsonObject(before.additionalProperties)
+        // A `const` object fixes every key, so it governs undeclared keys too.
+        const governed = isJsonObject(before.additionalProperties) || Object.hasOwn(before, "const")
             || Object.keys(keywordsOutside(before, structural)).some((key) => !DEFINITION_KEYWORDS.has(key));
         const open = !root && Object.keys(beforeProperties).length === 0 && before.additionalProperties !== false;
         if (governed || (direction === "input" && open))
@@ -214,7 +489,7 @@ function compareSchema(before, after, direction, depth, equal, reasons) {
     // Callers already send a key that was required before it was declared, with any value.
     if (direction === "input" && addedKeys.some((key) => innerRequired.has(key)))
         reasons.add(codes.unclassified);
-    if (!equal(before.additionalProperties, after.additionalProperties)) {
+    if (!sameMeaning(before.additionalProperties, after.additionalProperties, equal, scope)) {
         if (unevaluated)
             reasons.add(codes.unclassified);
         else if (direction === "input" && after.additionalProperties === false)
@@ -230,7 +505,7 @@ function classifyOutputSchema(before, after, equal, reasons) {
         reasons.add("output-schema-removed");
         return;
     }
-    compareSchema(before, after, "output", 0, equal, reasons);
+    compareSchema(before, after, "output", 0, equal, reasons, referenceScope(before, after));
 }
 function hint(annotations, key, absent) {
     if (annotations === undefined)
@@ -265,8 +540,9 @@ export function classifyAddedTool() {
 }
 export function classifyChangedTool(before, after, fields, equal) {
     const reasons = new Set();
-    if (fields.includes("inputSchema"))
-        compareSchema(before.inputSchema, after.inputSchema, "input", 0, equal, reasons);
+    if (fields.includes("inputSchema")) {
+        compareSchema(before.inputSchema, after.inputSchema, "input", 0, equal, reasons, referenceScope(before.inputSchema, after.inputSchema));
+    }
     if (fields.includes("outputSchema"))
         classifyOutputSchema(before.outputSchema, after.outputSchema, equal, reasons);
     if (fields.includes("annotations"))

package/dist/core/runtime-sandbox.d.ts

@@ -6,6 +6,7 @@ export interface RuntimeLaunchInput {
     command: string;
     args: string[];
     containerName: string;
+    environment?: readonly string[];
 }
 export interface RuntimeLaunchSpec {
     command: string;

package/dist/core/runtime-sandbox.js

@@ -19,6 +19,10 @@ export function buildRuntimeLaunch(input) {
     if (input.packageRoot.includes(",")) {
         throw new RuntimeSandboxError("Docker sandbox does not support commas in package paths.");
     }
+    const environment = input.environment ?? [];
+    if (environment.some((name) => !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name))) {
+        throw new RuntimeSandboxError("Invalid environment variable name.");
+    }
     const workdir = relativeCwd
         ? `/workspace/${relativeCwd.split(path.sep).join("/")}`
         : "/workspace";
@@ -52,6 +56,7 @@ export function buildRuntimeLaunch(input) {
             `type=bind,source=${input.packageRoot},target=/workspace,readonly`,
             "--workdir",
             workdir,
+            ...environment.flatMap((name) => ["-e", name]),
             DOCKER_RUNTIME_IMAGE,
             "node",
             ...input.args

package/dist/run-cli.js

@@ -113,10 +113,12 @@ class CliUsageError extends Error {
 }
 const toolsDiffUsage = "Usage: codex-plugin-doctor doctor tools-diff --before <path> --after <path> [--json|--markdown] [--fail-on any|breaking]";
 const toolsFileUsage = "Usage: codex-plugin-doctor doctor tools-file <path> [--json]";
-const toolsUsage = "Usage: codex-plugin-doctor doctor tools <url> --allow-network [--allow-local-network] [--json] [--save-response <path>] [--bearer-token-env <NAME>]\n       codex-plugin-doctor doctor tools <path> --server <name> --runtime [--sandbox docker] [--require-runtime-approval [--runtime-approval-digest <digest>]] [--json] [--save-response <path>]";
+const toolsUsage = "Usage: codex-plugin-doctor doctor tools <url> --allow-network [--allow-local-network] [--json] [--save-response <path>] [--bearer-token-env <NAME>]\n       codex-plugin-doctor doctor tools <path> --server <name> --runtime [--sandbox docker [--env <NAME>]...] [--require-runtime-approval [--runtime-approval-digest <digest>]] [--json] [--save-response <path>]";
 const discoveryUsage = "Usage: codex-plugin-doctor doctor discover <url> --allow-network [--allow-local-network] [--json] [--bearer-token-env <NAME>]";
 const bearerTokenHelp = "--bearer-token-env reads a bearer token from the named environment variable and sends it only over HTTPS or to an approved loopback target; the token is never printed or saved.";
 const ENVIRONMENT_VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+const MAX_FORWARDED_ENVIRONMENT_VARIABLES = 32;
+const forwardedEnvironmentHelp = "--env forwards the named host environment variable into the Docker sandbox by name; Doctor never prints its value, writes it to a report, or passes it as a command argument. Native servers already inherit Doctor's environment.";
 function resolveBearerToken(name, env) {
     if (name === undefined)
         return {};
@@ -155,14 +157,24 @@ async function finishToolCatalogCommand(io, snapshot, json, savePath) {
     io.writeStderr(`Saved a complete tools/list response with ${saved.tools} tools (${saved.bytes} bytes).`);
     return exitCode;
 }
-async function runStdioToolCatalogCommand(targetPath, flags, io, options) {
+async function runStdioToolCatalogCommand(targetPath, flags, io, options, env) {
     const allowedSwitches = new Set(["--runtime", "--json", "--require-runtime-approval"]);
     const switches = [];
     const values = new Map();
+    const environment = [];
     let invalid = false;
     for (let index = 0; index < flags.length; index += 1) {
         const flag = flags[index];
-        if (["--server", "--save-response", "--sandbox", "--runtime-approval-digest"].includes(flag) && !values.has(flag)) {
+        if (flag === "--env") {
+            const value = flags[index + 1];
+            if (!value || value.startsWith("-") || environment.includes(value)) {
+                invalid = true;
+                break;
+            }
+            environment.push(value);
+            index += 1;
+        }
+        else if (["--server", "--save-response", "--sandbox", "--runtime-approval-digest"].includes(flag) && !values.has(flag)) {
             const value = flags[index + 1];
             if (!value || value.startsWith("-")) {
                 invalid = true;
@@ -196,6 +208,25 @@ async function runStdioToolCatalogCommand(targetPath, flags, io, options) {
         io.writeStderr("--runtime-approval-digest requires --require-runtime-approval.");
         return 2;
     }
+    if (environment.length > 0 && sandbox !== "docker") {
+        io.writeStderr("--env requires --sandbox docker; native servers already inherit Doctor's environment.");
+        return 2;
+    }
+    if (environment.length > MAX_FORWARDED_ENVIRONMENT_VARIABLES) {
+        io.writeStderr(`At most ${MAX_FORWARDED_ENVIRONMENT_VARIABLES} --env variables can be forwarded.`);
+        return 2;
+    }
+    for (const name of environment) {
+        if (!ENVIRONMENT_VARIABLE_NAME.test(name)) {
+            io.writeStderr("--env requires an environment variable name.");
+            return 2;
+        }
+        // Docker silently skips an unset name, which would start the server without it.
+        if (env[name] === undefined || env[name] === "") {
+            io.writeStderr(`Environment variable is not set: ${name}`);
+            return 2;
+        }
+    }
     if (isBlockedOfflinePath(targetPath)) {
         io.writeStderr("doctor tools --server requires a local package path.");
         return 2;
@@ -225,7 +256,7 @@ async function runStdioToolCatalogCommand(targetPath, flags, io, options) {
             return 1;
         }
     }
-    const snapshot = await (options.captureStdioMcpToolCatalogImpl ?? captureStdioMcpToolCatalog)(resolved.server, sandbox === "docker" ? { sandbox: "docker" } : {});
+    const snapshot = await (options.captureStdioMcpToolCatalogImpl ?? captureStdioMcpToolCatalog)(resolved.server, sandbox !== "docker" ? {} : environment.length > 0 ? { sandbox: "docker", environment } : { sandbox: "docker" });
     return finishToolCatalogCommand(io, snapshot, switches.includes("--json"), savePath);
 }
 function parseRuntimeSandbox(flags, options = { requireRuntime: true }) {
@@ -1400,7 +1431,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
         }
         if (maybePath === "tools") {
             if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
-                io.writeStdout(`${toolsUsage}\nTool catalog structure only; tools are not executed.\n--server starts the named stdio server from the package MCP configuration after explicit --runtime consent and stops it after reading the tool list.\n--save-response writes a complete enumeration as one tools/list response for doctor tools-file and tools-diff; nothing is written when enumeration is incomplete.\n${bearerTokenHelp}`);
+                io.writeStdout(`${toolsUsage}\nTool catalog structure only; tools are not executed.\n--server starts the named stdio server from the package MCP configuration after explicit --runtime consent and stops it after reading the tool list.\n${forwardedEnvironmentHelp}\n--save-response writes a complete enumeration as one tools/list response for doctor tools-file and tools-diff; nothing is written when enumeration is incomplete.\n${bearerTokenHelp}`);
                 return 0;
             }
             const [url, ...flags] = remainingArgs;
@@ -1409,7 +1440,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 return 2;
             }
             if (flags.includes("--server")) {
-                return runStdioToolCatalogCommand(url, flags, io, options);
+                return runStdioToolCatalogCommand(url, flags, io, options, terminalContext.env);
             }
             const allowedFlags = new Set(["--allow-network", "--allow-local-network", "--json"]);
             const switches = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "1.71.0",
+  "version": "1.72.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",