codex-plugin-doctor 1.69.1 → 1.70.0

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

@@ -4,20 +4,20 @@ import { inspectMcpToolDefinition } from "./mcp-tool-definition.js";
 import { RemoteNetworkPolicyError } from "./remote-network-policy.js";
 import { packageVersion } from "../version.js";
 const REQUESTED_VERSION = "2026-07-28";
-const MAX_PAGES = 5;
+export const MAX_CATALOG_PAGES = 5;
 const MAX_TOOLS = 500;
 const MAX_FINDINGS = 100;
-const MAX_RESPONSE_BYTES = 1024 * 1024;
-const MAX_TOTAL_RESPONSE_BYTES = 4 * 1024 * 1024;
+export const MAX_CATALOG_RESPONSE_BYTES = 1024 * 1024;
+export const MAX_CATALOG_TOTAL_RESPONSE_BYTES = 4 * 1024 * 1024;
 const REQUEST_TIMEOUT_MS = 3_000;
 const TOTAL_TIMEOUT_MS = 15_000;
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function finding(id, severity, message, impact, suggestedFix) {
+export function catalogFinding(id, severity, message, impact, suggestedFix) {
     return { id, severity, message, impact, suggestedFix };
 }
-function validError(value) {
+export function validJsonRpcError(value) {
     return isPlainObject(value) && typeof value.code === "number" && Number.isFinite(value.code) && typeof value.message === "string";
 }
 function validCacheMetadata(value) {
@@ -25,11 +25,11 @@ function validCacheMetadata(value) {
         && typeof value.ttlMs === "number" && Number.isFinite(value.ttlMs) && value.ttlMs >= 0
         && (value.cacheScope === "public" || value.cacheScope === "private");
 }
-function hasMatchingEnvelope(message, requestId) {
+export function hasMatchingEnvelope(message, requestId) {
     return message.jsonrpc === "2.0" && message.id === requestId
         && Object.hasOwn(message, "result") !== Object.hasOwn(message, "error");
 }
-function parseToolsResult(message, requestId) {
+export function parseToolsResult(message, requestId) {
     if (!hasMatchingEnvelope(message, requestId)) {
         return null;
     }
@@ -45,7 +45,7 @@ function parseToolsResult(message, requestId) {
         cache: { ttlMs: message.result.ttlMs, cacheScope: message.result.cacheScope }
     };
 }
-function catalogReport(discovery, status, catalog, catalogEnumeration, findings) {
+export function buildMcpToolCatalogReport(discovery, status, catalog, catalogEnumeration, findings) {
     return {
         schemaVersion: 1,
         scope: "tool-catalog-structure",
@@ -63,7 +63,7 @@ function catalogReport(discovery, status, catalog, catalogEnumeration, findings)
         findings
     };
 }
-function finalStatus(findings) {
+export function finalCatalogStatus(findings) {
     return findings.some((item) => item.severity === "fail")
         ? "fail"
         : findings.some((item) => item.severity === "warn")
@@ -73,7 +73,58 @@ function finalStatus(findings) {
 function isAuthorizationFinding(discovery) {
     return discovery.findings.some((item) => item.id === "plugin.discovery.authorization.required" || item.id === "plugin.discovery.authorization.rejected");
 }
-function requestBody(id, cursor) {
+// Shared by the HTTP and stdio catalogs so both apply the same tool, finding, and duplicate-name rules.
+export function createMcpToolCatalogInspector() {
+    const findings = [];
+    const tools = [];
+    const names = new Map();
+    let toolsChecked = 0;
+    const addFindings = (items) => {
+        if (findings.length + items.length > MAX_FINDINGS) {
+            findings.push(...items.slice(0, MAX_FINDINGS - findings.length));
+            return false;
+        }
+        findings.push(...items);
+        return true;
+    };
+    return {
+        findings,
+        tools,
+        get toolsChecked() {
+            return toolsChecked;
+        },
+        addFindings,
+        inspectPage(pageTools, page, timeExpired) {
+            for (const tool of pageTools) {
+                if (toolsChecked >= MAX_TOOLS) {
+                    return "tool-limit";
+                }
+                toolsChecked += 1;
+                tools.push(tool);
+                const location = { page, toolIndex: toolsChecked };
+                if (!addFindings(inspectMcpToolDefinition(tool, location))) {
+                    return "finding-limit";
+                }
+                if (isPlainObject(tool) && typeof tool.name === "string") {
+                    const previous = names.get(tool.name);
+                    if (previous !== undefined && !addFindings([{
+                            ...catalogFinding("plugin.catalog.tool.name.duplicate", "warn", "Two enumerated tools use the same name.", "Duplicate tool names can make client selection ambiguous.", "Use a unique MCP tool name for each definition."),
+                            location: { ...location, relatedToolIndex: previous }
+                        }])) {
+                        return "finding-limit";
+                    }
+                    if (previous === undefined)
+                        names.set(tool.name, toolsChecked);
+                }
+                if (timeExpired()) {
+                    return "total-time-limit";
+                }
+            }
+            return null;
+        }
+    };
+}
+export function serializeToolsListRequest(id, cursor) {
     return JSON.stringify({
         jsonrpc: "2.0",
         id,
@@ -100,7 +151,7 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
     let budgetReason = null;
     const requestWithinBudget = async (url, requestOptions = {}) => {
         const remainingTime = deadline - now();
-        const remainingBytes = MAX_TOTAL_RESPONSE_BYTES - receivedBytes;
+        const remainingBytes = MAX_CATALOG_TOTAL_RESPONSE_BYTES - receivedBytes;
         const timeoutMs = Math.floor(Math.min(REQUEST_TIMEOUT_MS, remainingTime));
         if (timeoutMs < 1) {
             budgetReason = "total-time-limit";
@@ -110,7 +161,7 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
             budgetReason = "total-response-byte-limit";
             throw new BoundedHttpError("REMOTE_HTTP_RESPONSE_TOO_LARGE", "Catalog response byte budget exhausted.");
         }
-        const maxResponseBytes = Math.min(MAX_RESPONSE_BYTES, remainingBytes);
+        const maxResponseBytes = Math.min(MAX_CATALOG_RESPONSE_BYTES, remainingBytes);
         const response = await request(url, {
             ...requestOptions,
             timeoutMs,
@@ -118,7 +169,7 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
         });
         receivedBytes += response.body.length;
         if (response.body.length > maxResponseBytes) {
-            budgetReason = receivedBytes > MAX_TOTAL_RESPONSE_BYTES ? "total-response-byte-limit" : "response-byte-limit";
+            budgetReason = receivedBytes > MAX_CATALOG_TOTAL_RESPONSE_BYTES ? "total-response-byte-limit" : "response-byte-limit";
             throw new BoundedHttpError("REMOTE_HTTP_RESPONSE_TOO_LARGE", "Catalog response exceeded the byte budget.");
         }
         return response;
@@ -141,45 +192,40 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
         const reason = discovery.findings.some((item) => item.id === "plugin.discovery.credentials.insecure_transport")
             ? "credentials-insecure-transport"
             : "network-blocked";
-        return partial(catalogReport(discovery, "blocked", { ...emptyCatalog, reason }, "not-tested", []));
+        return partial(buildMcpToolCatalogReport(discovery, "blocked", { ...emptyCatalog, reason }, "not-tested", []));
     }
     if (isAuthorizationFinding(discovery)) {
-        return partial(catalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "authorization-required" }, "not-tested", []));
+        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "authorization-required" }, "not-tested", []));
     }
     if (discovery.status === "unsupported") {
-        return partial(catalogReport(discovery, "unsupported", { ...emptyCatalog, reason: "discovery-unsupported" }, "not-tested", []));
+        return partial(buildMcpToolCatalogReport(discovery, "unsupported", { ...emptyCatalog, reason: "discovery-unsupported" }, "not-tested", []));
     }
     if (discovery.status !== "discovered") {
-        return partial(catalogReport(discovery, "incomplete", { ...emptyCatalog, reason: budgetReason ?? "discovery-failed" }, "not-tested", []));
+        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { ...emptyCatalog, reason: budgetReason ?? "discovery-failed" }, "not-tested", []));
     }
     const capabilities = discoveryResponse === null ? null : discoverMcpCapabilities(discoveryResponse);
     if (capabilities === null) {
-        return partial(catalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "discovery-response-unavailable" }, "not-tested", []));
+        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "discovery-response-unavailable" }, "not-tested", []));
     }
     if (!Object.hasOwn(capabilities, "tools")) {
-        return partial(catalogReport(discovery, "not-applicable", emptyCatalog, "not-tested", []));
+        return partial(buildMcpToolCatalogReport(discovery, "not-applicable", emptyCatalog, "not-tested", []));
     }
-    const findings = [];
-    const names = new Map();
+    const inspector = createMcpToolCatalogInspector();
+    const findings = inspector.findings;
     const seenCursors = new Set();
     let pagesRead = 0;
-    let toolsChecked = 0;
     let cursor;
     let incompleteReason = null;
     let blocked = false;
-    const tools = [];
     let cache = null;
     const addFindings = (items) => {
-        if (findings.length + items.length > MAX_FINDINGS) {
-            findings.push(...items.slice(0, MAX_FINDINGS - findings.length));
-            incompleteReason = "finding-limit";
-            return false;
-        }
-        findings.push(...items);
-        return true;
+        if (inspector.addFindings(items))
+            return true;
+        incompleteReason = "finding-limit";
+        return false;
     };
     while (incompleteReason === null && !blocked) {
-        if (pagesRead >= MAX_PAGES) {
+        if (pagesRead >= MAX_CATALOG_PAGES) {
             incompleteReason = "page-limit";
             break;
         }
@@ -195,7 +241,7 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
                 lookup: options.lookup,
                 bearerToken: options.bearerToken,
                 method: "POST",
-                body: requestBody(requestId, cursor),
+                body: serializeToolsListRequest(requestId, cursor),
                 headers: {
                     Accept: "application/json, text/event-stream",
                     "Content-Type": "application/json",
@@ -226,19 +272,19 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
         }
         const message = parseMcpResponse(response, requestId);
         if (message !== null && hasMatchingEnvelope(message, requestId) && Object.hasOwn(message, "error")
-            && validError(message.error) && message.error.code === -32601 && (response.statusCode === 200 || response.statusCode === 404)) {
-            if (addFindings([finding("plugin.catalog.tools_list.method_unsupported", "warn", "The endpoint advertised tools but does not implement tools/list.", "Tool definitions cannot be enumerated from the advertised capability.", "Implement tools/list for the advertised modern MCP tools capability.")]))
+            && validJsonRpcError(message.error) && message.error.code === -32601 && (response.statusCode === 200 || response.statusCode === 404)) {
+            if (addFindings([catalogFinding("plugin.catalog.tools_list.method_unsupported", "warn", "The endpoint advertised tools but does not implement tools/list.", "Tool definitions cannot be enumerated from the advertised capability.", "Implement tools/list for the advertised modern MCP tools capability.")]))
                 incompleteReason = "tools-list-method-unsupported";
             break;
         }
         if (response.statusCode !== 200) {
-            if (addFindings([finding("plugin.catalog.http_status.invalid", "fail", "The endpoint returned an unexpected tools/list HTTP status.", "The tool catalog cannot be safely enumerated from this response.", "Return HTTP 200 for a tools/list response after authorization succeeds.")]))
+            if (addFindings([catalogFinding("plugin.catalog.http_status.invalid", "fail", "The endpoint returned an unexpected tools/list HTTP status.", "The tool catalog cannot be safely enumerated from this response.", "Return HTTP 200 for a tools/list response after authorization succeeds.")]))
                 incompleteReason = "http-status-invalid";
             break;
         }
         const page = message === null ? null : parseToolsResult(message, requestId);
         if (page === null) {
-            if (addFindings([finding("plugin.catalog.response.invalid", "fail", "The endpoint returned an invalid tools/list response.", "The tool catalog cannot be safely enumerated from this response.", "Return a matching JSON-RPC complete result with valid tools and cache metadata.")]))
+            if (addFindings([catalogFinding("plugin.catalog.response.invalid", "fail", "The endpoint returned an invalid tools/list response.", "The tool catalog cannot be safely enumerated from this response.", "Return a matching JSON-RPC complete result with valid tools and cache metadata.")]))
                 incompleteReason = "response-invalid";
             break;
         }
@@ -247,57 +293,32 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
             ttlMs: Math.min(cache.ttlMs, page.cache.ttlMs),
             cacheScope: cache.cacheScope === "private" ? "private" : page.cache.cacheScope
         };
-        for (const tool of page.tools) {
-            if (toolsChecked >= MAX_TOOLS) {
-                incompleteReason = "tool-limit";
-                break;
-            }
-            toolsChecked += 1;
-            tools.push(tool);
-            const location = { page: pagesRead, toolIndex: toolsChecked };
-            if (!addFindings(inspectMcpToolDefinition(tool, location))) {
-                break;
-            }
-            if (isPlainObject(tool) && typeof tool.name === "string") {
-                const previous = names.get(tool.name);
-                if (previous !== undefined && !addFindings([{
-                        ...finding("plugin.catalog.tool.name.duplicate", "warn", "Two enumerated tools use the same name.", "Duplicate tool names can make client selection ambiguous.", "Use a unique MCP tool name for each definition."),
-                        location: { ...location, relatedToolIndex: previous }
-                    }])) {
-                    break;
-                }
-                if (previous === undefined)
-                    names.set(tool.name, toolsChecked);
-            }
-            if (deadline - now() <= 0) {
-                incompleteReason = "total-time-limit";
-                break;
-            }
-        }
+        incompleteReason = inspector.inspectPage(page.tools, pagesRead, () => deadline - now() <= 0);
         if (incompleteReason !== null)
             break;
         if (page.cursor === undefined)
             break;
         if (seenCursors.has(page.cursor)) {
-            if (addFindings([finding("plugin.catalog.cursor.loop", "warn", "The endpoint repeated a tools/list cursor.", "The bounded catalog enumeration cannot determine a complete result set.", "Return each continuation cursor at most once for a single enumeration.")]))
+            if (addFindings([catalogFinding("plugin.catalog.cursor.loop", "warn", "The endpoint repeated a tools/list cursor.", "The bounded catalog enumeration cannot determine a complete result set.", "Return each continuation cursor at most once for a single enumeration.")]))
                 incompleteReason = "cursor-loop";
             break;
         }
         seenCursors.add(page.cursor);
         cursor = page.cursor;
     }
+    const toolsChecked = inspector.toolsChecked;
     if (blocked) {
-        return partial(catalogReport(discovery, "blocked", { complete: false, pagesRead, toolsChecked, reason: "network-blocked" }, "incomplete", findings));
+        return partial(buildMcpToolCatalogReport(discovery, "blocked", { complete: false, pagesRead, toolsChecked, reason: "network-blocked" }, "incomplete", findings));
     }
     if (incompleteReason !== null) {
-        return partial(catalogReport(discovery, "incomplete", { complete: false, pagesRead, toolsChecked, reason: incompleteReason }, "incomplete", findings));
+        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { complete: false, pagesRead, toolsChecked, reason: incompleteReason }, "incomplete", findings));
     }
     if (deadline - now() <= 0) {
-        return partial(catalogReport(discovery, "incomplete", { complete: false, pagesRead, toolsChecked, reason: "total-time-limit" }, "incomplete", findings));
+        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { complete: false, pagesRead, toolsChecked, reason: "total-time-limit" }, "incomplete", findings));
     }
     return {
-        report: catalogReport(discovery, finalStatus(findings), { complete: true, pagesRead, toolsChecked, reason: null }, "complete", findings),
-        tools,
+        report: buildMcpToolCatalogReport(discovery, finalCatalogStatus(findings), { complete: true, pagesRead, toolsChecked, reason: null }, "complete", findings),
+        tools: inspector.tools,
         cache
     };
 }

package/dist/core/output-contract.js

@@ -650,7 +650,27 @@ const publicSchemaDefinitions = [
         properties: {
             schemaVersion: { const: 1 },
             scope: { const: "tool-catalog-structure" },
+            // transport, protocol, and execution appear only on reports from `doctor tools <path> --server <name> --runtime`.
+            transport: { const: "stdio" },
             status: { enum: ["pass", "warn", "fail", "unsupported", "not-applicable", "incomplete", "blocked"] },
+            protocol: {
+                type: "object", required: ["era", "version"],
+                properties: {
+                    era: { enum: ["modern", "legacy", null] },
+                    version: { type: ["string", "null"], pattern: "^\\d{4}-\\d{2}-\\d{2}$" }
+                },
+                additionalProperties: false
+            },
+            execution: {
+                type: ["object", "null"], required: ["backend", "image", "network", "packageMount"],
+                properties: {
+                    backend: { enum: ["native", "docker"] },
+                    image: { type: ["string", "null"] },
+                    network: { enum: ["host", "none"] },
+                    packageMount: { enum: ["host", "read_only"] }
+                },
+                additionalProperties: false
+            },
             discovery: {
                 type: "object",
                 required: ["schemaVersion", "requestedVersion", "scope", "status", "supportedVersions", "findings", "coverage"],

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

@@ -1,6 +1,8 @@
-import type { DiscoveredPackage, RuntimeProbeResult, RuntimeSandboxMode, RuntimeScorecard } from "../domain/types.js";
+import type { DiscoveredPackage, Finding, RuntimeProbeResult, RuntimeSandboxMode, RuntimeScorecard } from "../domain/types.js";
 import { type RemoteMcpRequest } from "./remote-mcp-probe.js";
 import type { RemoteLookup } from "./remote-network-policy.js";
+export declare function cleanupDockerContainer(containerName: string): Promise<Finding | null>;
+export declare function resolveRuntimeCwd(rootPath: string, configuredCwd: unknown): Promise<string | null>;
 export declare function probeRuntime(discoveredPackage: DiscoveredPackage, options?: RuntimeProbeOptions): Promise<RuntimeProbeResult>;
 export interface RuntimeProbeOptions {
     startupTimeoutMs?: number;

package/dist/core/runtime-probe.js

@@ -110,7 +110,7 @@ function withRuntimeEvidence(finding, serverName) {
         }
     };
 }
-function cleanupDockerContainer(containerName) {
+export function cleanupDockerContainer(containerName) {
     return new Promise((resolve) => {
         execFile("docker", ["rm", "-f", containerName], {
             encoding: "utf8",
@@ -588,7 +588,7 @@ function findCallableTool(tools) {
 function hasValidToolInputSchemas(tools) {
     return tools.every((tool) => isPlainObject(tool.inputSchema) && tool.inputSchema.type === "object");
 }
-async function resolveRuntimeCwd(rootPath, configuredCwd) {
+export async function resolveRuntimeCwd(rootPath, configuredCwd) {
     const resolvedCwd = typeof configuredCwd === "string"
         ? path.resolve(rootPath, configuredCwd)
         : rootPath;

package/dist/reporting/render-mcp-tool-catalog-report.js

@@ -4,6 +4,13 @@ export function renderMcpToolCatalogReport(report) {
         "================",
         `Status: ${report.status}`,
         `Scope: ${report.scope}`,
+        ...(report.transport === "stdio"
+            ? [
+                "Transport: stdio",
+                `Protocol: ${report.protocol?.era ?? "not established"}${report.protocol?.version ? ` (${report.protocol.version})` : ""}`,
+                `Execution: ${report.execution?.backend ?? "not started"}`
+            ]
+            : []),
         `Discovery: ${report.discovery.status}`,
         `Catalog complete: ${report.catalog.complete}`,
         `Pages read: ${report.catalog.pagesRead}`,

package/dist/run-cli.d.ts

@@ -1,5 +1,6 @@
 import { discoverMcpServer } from "./core/mcp-discovery.js";
 import { captureMcpToolCatalog, inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
+import { captureStdioMcpToolCatalog } from "./core/mcp-stdio-tool-catalog.js";
 import { inspectMcpToolFile } from "./core/mcp-tool-file.js";
 import { compareMcpToolFiles } from "./core/mcp-tool-diff.js";
 import { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport } from "./core/corpus-quality-metrics.js";
@@ -21,6 +22,7 @@ export interface RunCliOptions {
     inspectMcpToolFileImpl?: typeof inspectMcpToolFile;
     inspectMcpToolCatalogImpl?: typeof inspectMcpToolCatalog;
     captureMcpToolCatalogImpl?: typeof captureMcpToolCatalog;
+    captureStdioMcpToolCatalogImpl?: typeof captureStdioMcpToolCatalog;
     discoverMcpServerImpl?: typeof discoverMcpServer;
     terminalContext?: CliTerminalContext;
     runCheckImpl?: typeof runCheck;

package/dist/run-cli.js

@@ -24,6 +24,7 @@ import { buildSubmissionPreflight } from "./core/submission-preflight.js";
 import { isValidBearerToken } from "./core/bounded-http-client.js";
 import { discoverMcpServer } from "./core/mcp-discovery.js";
 import { captureMcpToolCatalog, inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
+import { captureStdioMcpToolCatalog, resolveMcpStdioServer } from "./core/mcp-stdio-tool-catalog.js";
 import { inspectMcpToolFile, isBlockedOfflinePath } from "./core/mcp-tool-file.js";
 import { saveMcpToolsListResponse } from "./core/mcp-tool-response-file.js";
 import { compareMcpToolFiles } from "./core/mcp-tool-diff.js";
@@ -112,7 +113,7 @@ 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>]";
+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 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;
@@ -128,6 +129,105 @@ function resolveBearerToken(name, env) {
         return { error: `Bearer token environment variable does not hold a valid bearer token: ${name}` };
     return { token };
 }
+async function finishToolCatalogCommand(io, snapshot, json, savePath) {
+    const report = snapshot.report;
+    io.writeStdout(json
+        ? JSON.stringify(report, null, 2)
+        : renderMcpToolCatalogReport(report));
+    const exitCode = report.status === "pass" ? 0
+        : report.status === "incomplete" || report.status === "blocked" ? 2 : 1;
+    if (savePath === undefined)
+        return exitCode;
+    if (snapshot.tools === null || snapshot.cache === null) {
+        io.writeStderr("Tool catalog response was not saved because enumeration did not complete.");
+        return 2;
+    }
+    const saved = await saveMcpToolsListResponse(savePath, snapshot.tools, snapshot.cache);
+    if (saved.kind !== "saved") {
+        io.writeStderr({
+            "path-blocked": "Tool catalog response was not saved because the path is not a local file path.",
+            "not-regular": "Tool catalog response was not saved because the existing target is not a regular file.",
+            "too-large": "Tool catalog response was not saved because it exceeds the one MiB tools-file limit.",
+            "write-failed": "Tool catalog response could not be written."
+        }[saved.kind]);
+        return 2;
+    }
+    io.writeStderr(`Saved a complete tools/list response with ${saved.tools} tools (${saved.bytes} bytes).`);
+    return exitCode;
+}
+async function runStdioToolCatalogCommand(targetPath, flags, io, options) {
+    const allowedSwitches = new Set(["--runtime", "--json", "--require-runtime-approval"]);
+    const switches = [];
+    const values = new Map();
+    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)) {
+            const value = flags[index + 1];
+            if (!value || value.startsWith("-")) {
+                invalid = true;
+                break;
+            }
+            values.set(flag, value);
+            index += 1;
+        }
+        else if (allowedSwitches.has(flag) && !switches.includes(flag)) {
+            switches.push(flag);
+        }
+        else {
+            invalid = true;
+            break;
+        }
+    }
+    const serverName = values.get("--server");
+    const savePath = values.get("--save-response");
+    const sandbox = values.get("--sandbox");
+    const approvalDigest = values.get("--runtime-approval-digest");
+    const requireApproval = switches.includes("--require-runtime-approval");
+    if (invalid || serverName === undefined || (sandbox !== undefined && sandbox !== "docker")) {
+        io.writeStderr(`Invalid or duplicate tool catalog arguments. ${toolsUsage}`);
+        return 2;
+    }
+    if (!switches.includes("--runtime")) {
+        io.writeStderr("doctor tools --server starts a local MCP server and requires explicit --runtime consent.");
+        return 2;
+    }
+    if (approvalDigest !== undefined && !requireApproval) {
+        io.writeStderr("--runtime-approval-digest requires --require-runtime-approval.");
+        return 2;
+    }
+    if (isBlockedOfflinePath(targetPath)) {
+        io.writeStderr("doctor tools --server requires a local package path.");
+        return 2;
+    }
+    if (savePath !== undefined && isBlockedOfflinePath(savePath)) {
+        io.writeStderr("doctor tools --save-response requires a local file path.");
+        return 2;
+    }
+    const resolved = await resolveMcpStdioServer(targetPath, serverName);
+    if (!resolved.ok) {
+        io.writeStderr(resolved.message);
+        return 2;
+    }
+    if (requireApproval) {
+        // Runtime plan digests cover only the manifest mcpServers file, so .mcp.json servers cannot be approved.
+        if (resolved.server.source !== "manifest") {
+            io.writeStderr("Runtime approval covers servers from the plugin manifest mcpServers file; this server comes from .mcp.json.");
+            return 2;
+        }
+        const runtimePlan = await buildDoctorRuntimePlan(targetPath, new Date().toISOString(), sandbox === "docker" ? { sandbox: "docker" } : {});
+        const approval = evaluateRuntimeApproval(runtimePlan, {
+            required: true,
+            approvedDigest: approvalDigest ?? null
+        });
+        if (!runtimeApprovalPassed(approval)) {
+            io.writeStderr(`${approval.message}\nCurrent runtime plan digest: ${runtimePlan.digest}`);
+            return 1;
+        }
+    }
+    const snapshot = await (options.captureStdioMcpToolCatalogImpl ?? captureStdioMcpToolCatalog)(resolved.server, sandbox === "docker" ? { sandbox: "docker" } : {});
+    return finishToolCatalogCommand(io, snapshot, switches.includes("--json"), savePath);
+}
 function parseRuntimeSandbox(flags, options = { requireRuntime: true }) {
     const index = flags.indexOf("--sandbox");
     if (index === -1) {
@@ -1176,9 +1276,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
         (command === "release" && maybePath === "check") ||
         (command === "doctor" &&
             (["runtime-plan", "runtime-policy"].includes(maybePath ?? "") ||
-                (maybePath === "release-evidence" && remainingArgs[0] !== "verify")));
+                (maybePath === "release-evidence" && remainingArgs[0] !== "verify") ||
+                (maybePath === "tools" && remainingArgs.includes("--server"))));
     if (args.includes("--sandbox") && !runtimeSandboxSupported) {
-        io.writeStderr("--sandbox is supported only by single-package check, release check, runtime-plan, runtime-policy, and release-evidence.");
+        io.writeStderr("--sandbox is supported only by single-package check, release check, runtime-plan, runtime-policy, release-evidence, and doctor tools --server.");
         return 2;
     }
     if (command === "--version" || command === "-v" || command === "version") {
@@ -1299,7 +1400,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
         }
         if (maybePath === "tools") {
             if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
-                io.writeStdout(`${toolsUsage}\nHTTP tool catalog structure only; tools are not executed.\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--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;
@@ -1307,6 +1408,9 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 io.writeStderr(toolsUsage);
                 return 2;
             }
+            if (flags.includes("--server")) {
+                return runStdioToolCatalogCommand(url, flags, io, options);
+            }
             const allowedFlags = new Set(["--allow-network", "--allow-local-network", "--json"]);
             const switches = [];
             let savePath;
@@ -1359,30 +1463,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
             const snapshot = savePath === undefined
                 ? { report: await (options.inspectMcpToolCatalogImpl ?? inspectMcpToolCatalog)(url, catalogOptions), tools: null, cache: null }
                 : await (options.captureMcpToolCatalogImpl ?? captureMcpToolCatalog)(url, catalogOptions);
-            const report = snapshot.report;
-            io.writeStdout(switches.includes("--json")
-                ? JSON.stringify(report, null, 2)
-                : renderMcpToolCatalogReport(report));
-            const exitCode = report.status === "pass" ? 0
-                : report.status === "incomplete" || report.status === "blocked" ? 2 : 1;
-            if (savePath === undefined)
-                return exitCode;
-            if (snapshot.tools === null || snapshot.cache === null) {
-                io.writeStderr("Tool catalog response was not saved because enumeration did not complete.");
-                return 2;
-            }
-            const saved = await saveMcpToolsListResponse(savePath, snapshot.tools, snapshot.cache);
-            if (saved.kind !== "saved") {
-                io.writeStderr({
-                    "path-blocked": "Tool catalog response was not saved because the path is not a local file path.",
-                    "not-regular": "Tool catalog response was not saved because the existing target is not a regular file.",
-                    "too-large": "Tool catalog response was not saved because it exceeds the one MiB tools-file limit.",
-                    "write-failed": "Tool catalog response could not be written."
-                }[saved.kind]);
-                return 2;
-            }
-            io.writeStderr(`Saved a complete tools/list response with ${saved.tools} tools (${saved.bytes} bytes).`);
-            return exitCode;
+            return finishToolCatalogCommand(io, snapshot, switches.includes("--json"), savePath);
         }
         if (maybePath === "discover") {
             if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {

package/package.json

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