codex-plugin-doctor 1.65.0 → 1.67.0

package/README.md

@@ -121,8 +121,9 @@ This reports added, removed, and structurally changed definitions using numeric
 locations, and labels each change `breaking`, `compatible`, or `unclassified`
 with fixed reason codes. Add `--fail-on breaking` to fail CI only on breaking or
 unclassified changes. Incomplete inputs, invalid definitions, or duplicate names
-prevent a comparison. Impact labels are root-level schema heuristics, not proof
-of compatibility.
+prevent a comparison. Impact labels follow nested object properties, array
+items, and common length and range bounds, but remain heuristics, not proof of
+compatibility.
 See [Offline MCP Tool Diff](docs/guides/offline-tool-diff.md) for matching rules,
 privacy, limits, and exit codes.
 
@@ -138,6 +139,10 @@ This opt-in command performs discovery and bounded `tools/list` pagination. It
 reports tool-definition and root-schema shape findings, explicit completion state,
 and partial inspection limits. It does not claim full schema validation, tool
 execution, or client compatibility. Existing `doctor discover` behavior is unchanged.
+Add `--save-response <path>` to record a completely enumerated catalog as a
+`tools/list` response for `tools-file` and `tools-diff`; nothing is written when
+enumeration is incomplete. The GitHub Action can compare saved responses with
+`tools-diff-before`, `tools-diff-after`, and `tools-diff-fail-on`.
 See [HTTP MCP Tool Catalog](docs/guides/mcp-tool-catalog.md).
 
 ### Remote MCP Readiness
@@ -558,9 +563,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.65.0
+      - uses: Esquetta/CodexPluginDoctor@v1.67.0
         with:
-          version: "1.65.0"
+          version: "1.67.0"
           path: .
           runtime: "true"
           policy: codex-publish

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

@@ -32,5 +32,15 @@ export interface McpToolCatalogReport {
     };
     findings: CatalogFinding[];
 }
+export interface McpToolCatalogCache {
+    ttlMs: number;
+    cacheScope: "public" | "private";
+}
+export interface McpToolCatalogSnapshot {
+    report: McpToolCatalogReport;
+    tools: unknown[] | null;
+    cache: McpToolCatalogCache | null;
+}
 export declare function inspectMcpToolCatalog(rawUrl: string, options?: McpToolCatalogOptions): Promise<McpToolCatalogReport>;
+export declare function captureMcpToolCatalog(rawUrl: string, options?: McpToolCatalogOptions): Promise<McpToolCatalogSnapshot>;
 export {};

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

@@ -39,7 +39,11 @@ function parseToolsResult(message, requestId) {
     if (Object.hasOwn(message.result, "nextCursor") && typeof message.result.nextCursor !== "string") {
         return null;
     }
-    return { tools: message.result.tools, cursor: message.result.nextCursor };
+    return {
+        tools: message.result.tools,
+        cursor: message.result.nextCursor,
+        cache: { ttlMs: message.result.ttlMs, cacheScope: message.result.cacheScope }
+    };
 }
 function catalogReport(discovery, status, catalog, catalogEnumeration, findings) {
     return {
@@ -85,6 +89,10 @@ function requestBody(id, cursor) {
     });
 }
 export async function inspectMcpToolCatalog(rawUrl, options = {}) {
+    return (await captureMcpToolCatalog(rawUrl, options)).report;
+}
+// Tools and cache metadata are returned only for a complete enumeration.
+export async function captureMcpToolCatalog(rawUrl, options = {}) {
     const request = options.request ?? requestBoundedHttp;
     const now = options.now ?? (() => performance.now());
     const deadline = now() + TOTAL_TIMEOUT_MS;
@@ -126,25 +134,26 @@ export async function inspectMcpToolCatalog(rawUrl, options = {}) {
             return response;
         }
     });
+    const partial = (report) => ({ report, tools: null, cache: null });
     const emptyCatalog = { complete: false, pagesRead: 0, toolsChecked: 0, reason: null };
     if (discovery.status === "blocked") {
-        return catalogReport(discovery, "blocked", { ...emptyCatalog, reason: "network-blocked" }, "not-tested", []);
+        return partial(catalogReport(discovery, "blocked", { ...emptyCatalog, reason: "network-blocked" }, "not-tested", []));
     }
     if (isAuthorizationFinding(discovery)) {
-        return catalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "authorization-required" }, "not-tested", []);
+        return partial(catalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "authorization-required" }, "not-tested", []));
     }
     if (discovery.status === "unsupported") {
-        return catalogReport(discovery, "unsupported", { ...emptyCatalog, reason: "discovery-unsupported" }, "not-tested", []);
+        return partial(catalogReport(discovery, "unsupported", { ...emptyCatalog, reason: "discovery-unsupported" }, "not-tested", []));
     }
     if (discovery.status !== "discovered") {
-        return catalogReport(discovery, "incomplete", { ...emptyCatalog, reason: budgetReason ?? "discovery-failed" }, "not-tested", []);
+        return partial(catalogReport(discovery, "incomplete", { ...emptyCatalog, reason: budgetReason ?? "discovery-failed" }, "not-tested", []));
     }
     const capabilities = discoveryResponse === null ? null : discoverMcpCapabilities(discoveryResponse);
     if (capabilities === null) {
-        return catalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "discovery-response-unavailable" }, "not-tested", []);
+        return partial(catalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "discovery-response-unavailable" }, "not-tested", []));
     }
     if (!Object.hasOwn(capabilities, "tools")) {
-        return catalogReport(discovery, "not-applicable", emptyCatalog, "not-tested", []);
+        return partial(catalogReport(discovery, "not-applicable", emptyCatalog, "not-tested", []));
     }
     const findings = [];
     const names = new Map();
@@ -154,6 +163,8 @@ export async function inspectMcpToolCatalog(rawUrl, options = {}) {
     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));
@@ -225,12 +236,17 @@ export async function inspectMcpToolCatalog(rawUrl, options = {}) {
             break;
         }
         pagesRead += 1;
+        cache = cache === null ? page.cache : {
+            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;
@@ -264,13 +280,17 @@ export async function inspectMcpToolCatalog(rawUrl, options = {}) {
         cursor = page.cursor;
     }
     if (blocked) {
-        return catalogReport(discovery, "blocked", { complete: false, pagesRead, toolsChecked, reason: "network-blocked" }, "incomplete", findings);
+        return partial(catalogReport(discovery, "blocked", { complete: false, pagesRead, toolsChecked, reason: "network-blocked" }, "incomplete", findings));
     }
     if (incompleteReason !== null) {
-        return catalogReport(discovery, "incomplete", { complete: false, pagesRead, toolsChecked, reason: incompleteReason }, "incomplete", findings);
+        return partial(catalogReport(discovery, "incomplete", { complete: false, pagesRead, toolsChecked, reason: incompleteReason }, "incomplete", findings));
     }
     if (deadline - now() <= 0) {
-        return catalogReport(discovery, "incomplete", { complete: false, pagesRead, toolsChecked, reason: "total-time-limit" }, "incomplete", findings);
+        return partial(catalogReport(discovery, "incomplete", { complete: false, pagesRead, toolsChecked, reason: "total-time-limit" }, "incomplete", findings));
     }
-    return catalogReport(discovery, finalStatus(findings), { complete: true, pagesRead, toolsChecked, reason: null }, "complete", findings);
+    return {
+        report: catalogReport(discovery, finalStatus(findings), { complete: true, pagesRead, toolsChecked, reason: null }, "complete", findings),
+        tools,
+        cache
+    };
 }

package/dist/core/mcp-tool-file.d.ts

@@ -1,4 +1,5 @@
 import type { CatalogFinding } from "./mcp-tool-definition.js";
+export declare const MAX_TOOL_FILE_BYTES: number;
 export interface McpToolFileReport {
     schemaVersion: 1;
     scope: "tool-definitions-file";
@@ -28,5 +29,6 @@ export interface McpToolFileSnapshot {
     report: McpToolFileReport;
     tools: unknown[] | null;
 }
+export declare function isBlockedOfflinePath(filePath: string): boolean;
 export declare function loadMcpToolFileSnapshot(filePath: string): Promise<McpToolFileSnapshot>;
 export declare function inspectMcpToolFile(filePath: string): Promise<McpToolFileReport>;

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

@@ -1,7 +1,7 @@
 import { constants } from "node:fs";
 import { lstat, open } from "node:fs/promises";
 import { inspectMcpToolDefinition } from "./mcp-tool-definition.js";
-const MAX_FILE_BYTES = 1024 * 1024;
+export const MAX_TOOL_FILE_BYTES = 1024 * 1024;
 const MAX_TOOLS = 500;
 const MAX_FINDINGS = 100;
 function snapshot(report, tools = null) {
@@ -22,7 +22,7 @@ function sameSnapshot(left, right) {
         && left.mtimeMs === right.mtimeMs
         && left.ctimeMs === right.ctimeMs;
 }
-function isBlockedOfflinePath(filePath) {
+export function isBlockedOfflinePath(filePath) {
     return /^[A-Za-z][A-Za-z0-9+.-]+:/u.test(filePath)
         || /^[A-Za-z]:\/\//u.test(filePath)
         || /^[\\/]{2}/u.test(filePath);
@@ -102,7 +102,7 @@ async function readBoundedRegularFile(filePath) {
         return { kind: "symlink", bytesRead: 0 };
     if (!initial.isFile())
         return { kind: "not-regular", bytesRead: 0 };
-    if (!Number.isSafeInteger(initial.size) || initial.size < 0 || initial.size > MAX_FILE_BYTES) {
+    if (!Number.isSafeInteger(initial.size) || initial.size < 0 || initial.size > MAX_TOOL_FILE_BYTES) {
         return { kind: "too-large", bytesRead: 0 };
     }
     const flags = process.platform === "win32"
@@ -117,7 +117,7 @@ async function readBoundedRegularFile(filePath) {
         if (!opened.isFile() || current.isSymbolicLink() || !current.isFile() || !sameSnapshot(initial, opened) || !sameSnapshot(opened, current)) {
             return { kind: "changed", bytesRead };
         }
-        if (!Number.isSafeInteger(opened.size) || opened.size < 0 || opened.size > MAX_FILE_BYTES) {
+        if (!Number.isSafeInteger(opened.size) || opened.size < 0 || opened.size > MAX_TOOL_FILE_BYTES) {
             return { kind: "too-large", bytesRead };
         }
         const content = Buffer.alloc(opened.size);

package/dist/core/mcp-tool-impact.d.ts

@@ -1,6 +1,6 @@
 type JsonObject = Record<string, unknown>;
 export type ToolChangeImpact = "breaking" | "compatible" | "unclassified";
-export declare const TOOL_CHANGE_REASONS: readonly ["tool-removed", "input-type-narrowed", "input-required-added", "input-property-removed", "input-property-type-narrowed", "input-property-enum-narrowed", "input-additional-properties-closed", "input-schema-unclassified", "output-schema-removed", "output-type-widened", "output-property-removed", "output-guarantee-removed", "output-property-type-widened", "output-property-enum-widened", "output-schema-unclassified", "annotation-safety-reduced", "other-fields-unclassified"];
+export declare const TOOL_CHANGE_REASONS: readonly ["tool-removed", "input-type-narrowed", "input-required-added", "input-property-removed", "input-property-type-narrowed", "input-property-enum-narrowed", "input-constraint-tightened", "input-additional-properties-closed", "input-schema-unclassified", "output-schema-removed", "output-type-widened", "output-property-removed", "output-guarantee-removed", "output-property-type-widened", "output-property-enum-widened", "output-constraint-loosened", "output-schema-unclassified", "annotation-safety-reduced", "other-fields-unclassified"];
 export type ToolChangeReason = (typeof TOOL_CHANGE_REASONS)[number];
 export interface ToolChangeClassification {
     impact: ToolChangeImpact;

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

@@ -5,6 +5,7 @@ export const TOOL_CHANGE_REASONS = [
     "input-property-removed",
     "input-property-type-narrowed",
     "input-property-enum-narrowed",
+    "input-constraint-tightened",
     "input-additional-properties-closed",
     "input-schema-unclassified",
     "output-schema-removed",
@@ -13,6 +14,7 @@ export const TOOL_CHANGE_REASONS = [
     "output-guarantee-removed",
     "output-property-type-widened",
     "output-property-enum-widened",
+    "output-constraint-loosened",
     "output-schema-unclassified",
     "annotation-safety-reduced",
     "other-fields-unclassified"
@@ -25,7 +27,33 @@ const UNCLASSIFIED_REASONS = new Set([
 // Keywords that document a schema without constraining accepted or produced values.
 const DOCUMENTATION_KEYWORDS = new Set(["title", "description", "examples", "default", "deprecated", "$comment"]);
 const ROOT_STRUCTURAL_KEYWORDS = new Set(["type", "properties", "required", "additionalProperties", "$schema"]);
-const PROPERTY_STRUCTURAL_KEYWORDS = new Set(["type", "enum"]);
+const LOWER_BOUND_KEYWORDS = ["minimum", "minLength", "minItems"];
+const UPPER_BOUND_KEYWORDS = ["maximum", "maxLength", "maxItems"];
+const NESTED_STRUCTURAL_KEYWORDS = new Set([
+    "type", "enum", "properties", "required", "additionalProperties", "items", ...LOWER_BOUND_KEYWORDS, ...UPPER_BOUND_KEYWORDS
+]);
+// Subschemas nested deeper than this below the root are not compared and stay unclassified.
+const MAX_NESTED_DEPTH = 8;
+const CODES = {
+    input: {
+        unclassified: "input-schema-unclassified",
+        rootType: "input-type-narrowed",
+        propertyType: "input-property-type-narrowed",
+        enumChanged: "input-property-enum-narrowed",
+        constraint: "input-constraint-tightened",
+        required: "input-required-added",
+        propertyRemoved: "input-property-removed"
+    },
+    output: {
+        unclassified: "output-schema-unclassified",
+        rootType: "output-type-widened",
+        propertyType: "output-property-type-widened",
+        enumChanged: "output-property-enum-widened",
+        constraint: "output-constraint-loosened",
+        required: "output-guarantee-removed",
+        propertyRemoved: "output-property-removed"
+    }
+};
 // MCP tool annotation defaults, oriented so `true` is the safer reading.
 const SAFETY_HINTS = [
     { key: "readOnlyHint", absent: false, safe: true },
@@ -91,62 +119,104 @@ function keywordsOutside(schema, allowed) {
     }
     return rest;
 }
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+/** Flags bounds of `outer` that `inner` does not satisfy, so `inner` values may fall outside `outer`. */
+function compareBounds(inner, outer, codes, reasons) {
+    for (const [keywords, covered] of [
+        [LOWER_BOUND_KEYWORDS, (innerBound, outerBound) => innerBound >= outerBound],
+        [UPPER_BOUND_KEYWORDS, (innerBound, outerBound) => innerBound <= outerBound]
+    ]) {
+        for (const keyword of keywords) {
+            const outerBound = outer[keyword];
+            const innerBound = inner[keyword];
+            if ((outerBound !== undefined && !isFiniteNumber(outerBound)) || (innerBound !== undefined && !isFiniteNumber(innerBound))) {
+                reasons.add(codes.unclassified);
+            }
+            else if (outerBound !== undefined && (innerBound === undefined || !covered(innerBound, outerBound))) {
+                reasons.add(codes.constraint);
+            }
+        }
+    }
+}
 /**
- * Compares one property subschema. `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).
+ * 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 compareProperty(before, after, direction, equal, reasons) {
+function compareSchema(before, after, direction, depth, equal, reasons) {
     if (equal(before, after))
         return;
-    const unclassified = direction === "input" ? "input-schema-unclassified" : "output-schema-unclassified";
-    if (!isJsonObject(before) || !isJsonObject(after)
-        || !equal(keywordsOutside(before, PROPERTY_STRUCTURAL_KEYWORDS), keywordsOutside(after, PROPERTY_STRUCTURAL_KEYWORDS))) {
-        reasons.add(unclassified);
+    const codes = CODES[direction];
+    const root = depth === 0;
+    const structural = root ? ROOT_STRUCTURAL_KEYWORDS : NESTED_STRUCTURAL_KEYWORDS;
+    if (depth > MAX_NESTED_DEPTH || !isJsonObject(before) || !isJsonObject(after)
+        || !equal(keywordsOutside(before, structural), keywordsOutside(after, structural))
+        || !equal(before.$schema, after.$schema)) {
+        reasons.add(codes.unclassified);
         return;
     }
     const [inner, outer] = direction === "input" ? [before, after] : [after, before];
-    if (!typesCovered(typeSet(inner), typeSet(outer))) {
-        reasons.add(direction === "input" ? "input-property-type-narrowed" : "output-property-type-widened");
+    // unevaluatedItems/unevaluatedProperties apply to whatever items/additionalProperties leave
+    // uncovered, so a change in either cannot be judged on its own.
+    const unevaluated = ["unevaluatedItems", "unevaluatedProperties"].some((key) => before[key] !== undefined || after[key] !== undefined);
+    if (!typesCovered(typeSet(inner), typeSet(outer)))
+        reasons.add(root ? codes.rootType : codes.propertyType);
+    if (!root) {
+        const enumResult = enumCovered(inner.enum, outer.enum, 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)) {
+            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);
+        }
     }
-    const enumResult = enumCovered(inner.enum, outer.enum, equal);
-    if (enumResult === null)
-        reasons.add(unclassified);
-    else if (!enumResult)
-        reasons.add(direction === "input" ? "input-property-enum-narrowed" : "output-property-enum-widened");
-}
-function classifyInputSchema(before, after, equal, reasons) {
-    if (!isJsonObject(before) || !isJsonObject(after)
-        || !equal(keywordsOutside(before, ROOT_STRUCTURAL_KEYWORDS), keywordsOutside(after, ROOT_STRUCTURAL_KEYWORDS))
-        || !equal(before.$schema, after.$schema)) {
-        reasons.add("input-schema-unclassified");
-        return;
-    }
-    if (!typesCovered(typeSet(before), typeSet(after)))
-        reasons.add("input-type-narrowed");
-    const beforeRequired = stringSet(before.required);
-    const afterRequired = stringSet(after.required);
+    const innerRequired = stringSet(inner.required);
+    const outerRequired = stringSet(outer.required);
     const beforeProperties = objectMap(before.properties);
     const afterProperties = objectMap(after.properties);
-    if (beforeRequired === null || afterRequired === null || beforeProperties === null || afterProperties === null) {
-        reasons.add("input-schema-unclassified");
+    if (innerRequired === null || outerRequired === null || beforeProperties === null || afterProperties === null) {
+        reasons.add(codes.unclassified);
         return;
     }
-    for (const key of afterRequired) {
-        if (!beforeRequired.has(key))
-            reasons.add("input-required-added");
+    for (const key of outerRequired) {
+        if (!innerRequired.has(key))
+            reasons.add(codes.required);
     }
     for (const key of Object.keys(beforeProperties)) {
         if (!Object.hasOwn(afterProperties, key))
-            reasons.add("input-property-removed");
+            reasons.add(codes.propertyRemoved);
         else
-            compareProperty(beforeProperties[key], afterProperties[key], "input", equal, reasons);
+            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).
+    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 (governed || (direction === "input" && open))
+            reasons.add(codes.unclassified);
+    }
+    // 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 (after.additionalProperties === false)
+        if (unevaluated)
+            reasons.add(codes.unclassified);
+        else if (direction === "input" && after.additionalProperties === false)
             reasons.add("input-additional-properties-closed");
-        else if (!(after.additionalProperties === undefined || after.additionalProperties === true))
-            reasons.add("input-schema-unclassified");
+        else if (direction === "output" || !(after.additionalProperties === undefined || after.additionalProperties === true))
+            reasons.add(codes.unclassified);
     }
 }
 function classifyOutputSchema(before, after, equal, reasons) {
@@ -156,34 +226,7 @@ function classifyOutputSchema(before, after, equal, reasons) {
         reasons.add("output-schema-removed");
         return;
     }
-    if (!isJsonObject(before) || !isJsonObject(after)
-        || !equal(keywordsOutside(before, ROOT_STRUCTURAL_KEYWORDS), keywordsOutside(after, ROOT_STRUCTURAL_KEYWORDS))
-        || !equal(before.$schema, after.$schema)) {
-        reasons.add("output-schema-unclassified");
-        return;
-    }
-    if (!typesCovered(typeSet(after), typeSet(before)))
-        reasons.add("output-type-widened");
-    const beforeRequired = stringSet(before.required);
-    const afterRequired = stringSet(after.required);
-    const beforeProperties = objectMap(before.properties);
-    const afterProperties = objectMap(after.properties);
-    if (beforeRequired === null || afterRequired === null || beforeProperties === null || afterProperties === null) {
-        reasons.add("output-schema-unclassified");
-        return;
-    }
-    for (const key of beforeRequired) {
-        if (!afterRequired.has(key))
-            reasons.add("output-guarantee-removed");
-    }
-    for (const key of Object.keys(beforeProperties)) {
-        if (!Object.hasOwn(afterProperties, key))
-            reasons.add("output-property-removed");
-        else
-            compareProperty(beforeProperties[key], afterProperties[key], "output", equal, reasons);
-    }
-    if (!equal(before.additionalProperties, after.additionalProperties))
-        reasons.add("output-schema-unclassified");
+    compareSchema(before, after, "output", 0, equal, reasons);
 }
 function hint(annotations, key, absent) {
     if (annotations === undefined)
@@ -219,7 +262,7 @@ export function classifyAddedTool() {
 export function classifyChangedTool(before, after, fields, equal) {
     const reasons = new Set();
     if (fields.includes("inputSchema"))
-        classifyInputSchema(before.inputSchema, after.inputSchema, equal, reasons);
+        compareSchema(before.inputSchema, after.inputSchema, "input", 0, equal, reasons);
     if (fields.includes("outputSchema"))
         classifyOutputSchema(before.outputSchema, after.outputSchema, equal, reasons);
     if (fields.includes("annotations"))

package/dist/core/mcp-tool-response-file.d.ts

@@ -0,0 +1,10 @@
+import type { McpToolCatalogCache } from "./mcp-tool-catalog.js";
+export type McpToolResponseSaveResult = {
+    kind: "saved";
+    bytes: number;
+    tools: number;
+} | {
+    kind: "path-blocked" | "not-regular" | "too-large" | "write-failed";
+};
+export declare function serializeMcpToolsListResponse(tools: unknown[], cache: McpToolCatalogCache): string;
+export declare function saveMcpToolsListResponse(filePath: string, tools: unknown[], cache: McpToolCatalogCache): Promise<McpToolResponseSaveResult>;

package/dist/core/mcp-tool-response-file.js

@@ -0,0 +1,52 @@
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { isBlockedOfflinePath, MAX_TOOL_FILE_BYTES } from "./mcp-tool-file.js";
+// Serializes an enumerated catalog as one complete tools/list response that doctor tools-file and tools-diff accept.
+export function serializeMcpToolsListResponse(tools, cache) {
+    return `${JSON.stringify({
+        jsonrpc: "2.0",
+        id: "tools-list",
+        result: { resultType: "complete", tools, ttlMs: cache.ttlMs, cacheScope: cache.cacheScope }
+    }, null, 2)}\n`;
+}
+export async function saveMcpToolsListResponse(filePath, tools, cache) {
+    if (isBlockedOfflinePath(filePath))
+        return { kind: "path-blocked" };
+    let content;
+    let bytes;
+    try {
+        content = serializeMcpToolsListResponse(tools, cache);
+        bytes = Buffer.byteLength(content);
+    }
+    catch {
+        return { kind: "write-failed" };
+    }
+    if (bytes > MAX_TOOL_FILE_BYTES)
+        return { kind: "too-large" };
+    let existingMode = null;
+    try {
+        const existing = await lstat(filePath);
+        if (existing.isSymbolicLink() || !existing.isFile())
+            return { kind: "not-regular" };
+        existingMode = existing.mode & 0o777;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            return { kind: "write-failed" };
+    }
+    // Write beside the target and rename so a failed write never leaves a partial response file.
+    const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        // Create with the replaced baseline's permission bits, which may protect private tool definitions.
+        await writeFile(tempPath, content, { encoding: "utf8", flag: "wx", mode: existingMode ?? 0o666 });
+        if (existingMode !== null)
+            await chmod(tempPath, existingMode);
+        await rename(tempPath, filePath);
+    }
+    catch {
+        await rm(tempPath, { force: true }).catch(() => undefined);
+        return { kind: "write-failed" };
+    }
+    return { kind: "saved", bytes, tools: tools.length };
+}

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

@@ -19,7 +19,7 @@ export function renderMcpToolDiffReport(report) {
         `Server catalog: ${report.coverage.serverCatalog}`,
         `Tool execution: ${report.coverage.toolExecution}`,
         `Impact classification: ${report.coverage.impactClassification}`,
-        "Only the supplied responses are compared. Impact labels are root-level schema heuristics: a compatible label or an unchanged result does not establish compatibility.",
+        "Only the supplied responses are compared. Impact labels are schema heuristics: a compatible label or an unchanged result does not establish compatibility.",
         ...["before", "after"].flatMap((side) => {
             const source = report[side];
             const label = side === "before" ? "Before" : "After";

package/dist/run-cli.d.ts

@@ -1,5 +1,5 @@
 import { discoverMcpServer } from "./core/mcp-discovery.js";
-import { inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
+import { captureMcpToolCatalog, inspectMcpToolCatalog } from "./core/mcp-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";
@@ -20,6 +20,7 @@ export interface RunCliOptions {
     compareMcpToolFilesImpl?: typeof compareMcpToolFiles;
     inspectMcpToolFileImpl?: typeof inspectMcpToolFile;
     inspectMcpToolCatalogImpl?: typeof inspectMcpToolCatalog;
+    captureMcpToolCatalogImpl?: typeof captureMcpToolCatalog;
     discoverMcpServerImpl?: typeof discoverMcpServer;
     terminalContext?: CliTerminalContext;
     runCheckImpl?: typeof runCheck;

package/dist/run-cli.js

@@ -22,8 +22,9 @@ import { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutp
 import { buildSubmissionArchivePreflight, submissionArchiveExitCode } from "./core/submission-archive-preflight.js";
 import { buildSubmissionPreflight } from "./core/submission-preflight.js";
 import { discoverMcpServer } from "./core/mcp-discovery.js";
-import { inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
-import { inspectMcpToolFile } from "./core/mcp-tool-file.js";
+import { captureMcpToolCatalog, inspectMcpToolCatalog } from "./core/mcp-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";
 import { renderMcpToolDiffReport } from "./reporting/render-mcp-tool-diff-report.js";
 import { renderMcpToolFileReport } from "./reporting/render-mcp-tool-file-report.js";
@@ -109,7 +110,7 @@ class CliUsageError extends Error {
 }
 const toolsDiffUsage = "Usage: codex-plugin-doctor doctor tools-diff --before <path> --after <path> [--json] [--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]";
+const toolsUsage = "Usage: codex-plugin-doctor doctor tools <url> --allow-network [--allow-local-network] [--json] [--save-response <path>]";
 const discoveryUsage = "Usage: codex-plugin-doctor doctor discover <url> --allow-network [--allow-local-network] [--json]";
 function parseRuntimeSandbox(flags, options = { requireRuntime: true }) {
     const index = flags.indexOf("--sandbox");
@@ -1280,7 +1281,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.`);
+                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.`);
                 return 0;
             }
             const [url, ...flags] = remainingArgs;
@@ -1289,23 +1290,68 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 return 2;
             }
             const allowedFlags = new Set(["--allow-network", "--allow-local-network", "--json"]);
-            if (flags.some((flag) => !allowedFlags.has(flag)) || new Set(flags).size !== flags.length) {
+            const switches = [];
+            let savePath;
+            let invalid = false;
+            for (let index = 0; index < flags.length; index += 1) {
+                const flag = flags[index];
+                if (flag === "--save-response" && savePath === undefined) {
+                    const value = flags[index + 1];
+                    if (!value || value.startsWith("-")) {
+                        invalid = true;
+                        break;
+                    }
+                    savePath = value;
+                    index += 1;
+                }
+                else if (allowedFlags.has(flag) && !switches.includes(flag)) {
+                    switches.push(flag);
+                }
+                else {
+                    invalid = true;
+                    break;
+                }
+            }
+            if (invalid) {
                 io.writeStderr(`Invalid or duplicate tool catalog arguments. ${toolsUsage}`);
                 return 2;
             }
-            if (!flags.includes("--allow-network")) {
+            if (!switches.includes("--allow-network")) {
                 io.writeStderr("doctor tools requires explicit --allow-network consent.");
                 return 2;
             }
-            const report = await (options.inspectMcpToolCatalogImpl ?? inspectMcpToolCatalog)(url, {
-                allowNetwork: true,
-                allowLocalNetwork: flags.includes("--allow-local-network")
-            });
-            io.writeStdout(flags.includes("--json")
+            if (savePath !== undefined && isBlockedOfflinePath(savePath)) {
+                io.writeStderr("doctor tools --save-response requires a local file path.");
+                return 2;
+            }
+            const catalogOptions = { allowNetwork: true, allowLocalNetwork: switches.includes("--allow-local-network") };
+            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));
-            return report.status === "pass" ? 0
+            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;
         }
         if (maybePath === "discover") {
             if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {

package/package.json

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