codex-plugin-doctor 1.68.0 → 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")
@@ -71,9 +71,60 @@ function finalStatus(findings) {
             : "pass";
 }
 function isAuthorizationFinding(discovery) {
-    return discovery.findings.some((item) => item.id === "plugin.discovery.authorization.required");
+    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;
@@ -128,6 +179,7 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
         allowNetwork: options.allowNetwork,
         allowLocalNetwork: options.allowLocalNetwork,
         lookup: options.lookup,
+        bearerToken: options.bearerToken,
         request: async (url, requestOptions) => {
             const response = await requestWithinBudget(url, requestOptions);
             discoveryResponse = response;
@@ -137,45 +189,43 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
     const partial = (report) => ({ report, tools: null, cache: null });
     const emptyCatalog = { complete: false, pagesRead: 0, toolsChecked: 0, reason: null };
     if (discovery.status === "blocked") {
-        return partial(catalogReport(discovery, "blocked", { ...emptyCatalog, reason: "network-blocked" }, "not-tested", []));
+        const reason = discovery.findings.some((item) => item.id === "plugin.discovery.credentials.insecure_transport")
+            ? "credentials-insecure-transport"
+            : "network-blocked";
+        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;
         }
@@ -189,8 +239,9 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
             response = await requestWithinBudget(rawUrl, {
                 allowLocalNetwork: options.allowLocalNetwork,
                 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",
@@ -205,11 +256,13 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
                 blocked = true;
             }
             else {
-                incompleteReason = budgetReason ?? (error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_TIMEOUT"
-                    ? "request-timeout"
-                    : error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_RESPONSE_TOO_LARGE"
-                        ? "response-byte-limit"
-                        : "request-failed");
+                incompleteReason = budgetReason ?? (error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_INSECURE_CREDENTIALS"
+                    ? "credentials-insecure-transport"
+                    : error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_TIMEOUT"
+                        ? "request-timeout"
+                        : error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_RESPONSE_TOO_LARGE"
+                            ? "response-byte-limit"
+                            : "request-failed");
             }
             break;
         }
@@ -219,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;
         }
@@ -240,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/mcp-tool-impact.js

@@ -34,6 +34,9 @@ const NESTED_STRUCTURAL_KEYWORDS = new Set([
 ]);
 // 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"]);
 const CODES = {
     input: {
         unclassified: "input-schema-unclassified",
@@ -197,13 +200,14 @@ function compareSchema(before, after, direction, depth, equal, reasons) {
         else
             compareSchema(beforeProperties[key], afterProperties[key], direction, depth + 1, equal, reasons);
     }
-    // In a nested object whose undeclared keys were open or governed by other keywords, a newly
-    // declared property can reject values callers send (input) or produce values consumers did
-    // not expect (output).
+    // 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 (!root && addedKeys.length > 0) {
-        const governed = isJsonObject(before.additionalProperties) || Object.keys(keywordsOutside(before, structural)).length > 0;
-        const open = Object.keys(beforeProperties).length === 0 && before.additionalProperties !== false;
+    if (addedKeys.length > 0) {
+        const governed = isJsonObject(before.additionalProperties)
+            || 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))
             reasons.add(codes.unclassified);
     }

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/reporting/render-mcp-tool-diff-markdown.d.ts

@@ -0,0 +1,2 @@
+import type { McpToolDiffReport } from "../core/mcp-tool-diff.js";
+export declare function renderMcpToolDiffMarkdown(report: McpToolDiffReport): string;

package/dist/reporting/render-mcp-tool-diff-markdown.js

@@ -0,0 +1,33 @@
+function count(value) {
+    return value === null || value === undefined ? "not compared" : String(value);
+}
+function toolIndex(value) {
+    return value === null ? "-" : String(value);
+}
+export function renderMcpToolDiffMarkdown(report) {
+    const comparison = report.comparison;
+    const lines = [
+        "## MCP Tool Definition Diff",
+        "",
+        `**Status:** \`${report.status}\` · **Comparison complete:** ${comparison.complete ? "yes" : "no"}${comparison.reason === null ? "" : ` · **Reason:** \`${comparison.reason}\``}`,
+        "",
+        "| Added | Removed | Changed | Unchanged | Breaking | Unclassified |",
+        "| --- | --- | --- | --- | --- | --- |",
+        `| ${count(comparison.added)} | ${count(comparison.removed)} | ${count(comparison.changed)} | ${count(comparison.unchanged)} | ${count(comparison.breaking)} | ${count(comparison.unclassified)} |`
+    ];
+    if (report.changes.length > 0) {
+        lines.push("", "### Changes", "", "| Change | Before tool | After tool | Fields | Impact | Reasons |", "| --- | --- | --- | --- | --- | --- |", ...report.changes.map((change) => `| ${change.kind} | ${toolIndex(change.beforeToolIndex)} | ${toolIndex(change.afterToolIndex)} | ${change.fields.map((field) => `\`${field}\``).join(", ") || "-"} | **${change.impact}** | ${change.reasons.map((reason) => `\`${reason}\``).join(", ") || "-"} |`));
+    }
+    const findings = ["before", "after"].flatMap((side) => report[side].findings.map((finding) => {
+        const location = finding.location;
+        const locator = location
+            ? `${side} tool ${location.toolIndex}${location.schema ? `, ${location.schema}` : ""}${location.relatedToolIndex ? `, related tool ${location.relatedToolIndex}` : ""}`
+            : side;
+        return `| ${finding.severity} | \`${finding.id}\` | ${locator} | ${finding.message} |`;
+    }));
+    if (findings.length > 0) {
+        lines.push("", "### Input Findings", "", "| Severity | Finding | Location | Message |", "| --- | --- | --- | --- |", ...findings);
+    }
+    lines.push("", `Tool numbers are one-based positions in the before and after files; names and schema values are not reported. Impact labels are ${report.coverage.impactClassification} schema checks, not proof of compatibility.`);
+    return lines.join("\n");
+}

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;