codex-plugin-doctor 1.75.0 → 1.77.0

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

@@ -29,18 +29,18 @@ export function hasMatchingEnvelope(message, requestId) {
     return message.jsonrpc === "2.0" && message.id === requestId
         && Object.hasOwn(message, "result") !== Object.hasOwn(message, "error");
 }
-export function parseToolsResult(message, requestId) {
+export function parseListResult(message, requestId, resultKey) {
     if (!hasMatchingEnvelope(message, requestId)) {
         return null;
     }
-    if (!Object.hasOwn(message, "result") || !isPlainObject(message.result) || !validCacheMetadata(message.result) || !Array.isArray(message.result.tools)) {
+    if (!Object.hasOwn(message, "result") || !isPlainObject(message.result) || !validCacheMetadata(message.result) || !Array.isArray(message.result[resultKey])) {
         return null;
     }
     if (Object.hasOwn(message.result, "nextCursor") && typeof message.result.nextCursor !== "string") {
         return null;
     }
     return {
-        tools: message.result.tools,
+        items: message.result[resultKey],
         cursor: message.result.nextCursor,
         cache: { ttlMs: message.result.ttlMs, cacheScope: message.result.cacheScope }
     };
@@ -70,6 +70,18 @@ export function finalCatalogStatus(findings) {
             ? "warn"
             : "pass";
 }
+export function listMethodUnsupported(list, server) {
+    return catalogFinding(`plugin.catalog.${list.capability}_list.method_unsupported`, "warn", `The ${server} advertised ${list.capability} but does not implement ${list.method}.`, `${list.noun === "tool" ? "Tool" : "Prompt"} definitions cannot be enumerated from the advertised capability.`, `Implement ${list.method} for the advertised ${server === "endpoint" ? "modern " : ""}MCP ${list.capability} capability.`);
+}
+export function modernInvalidFix(list) {
+    return `Return a matching JSON-RPC complete result with valid ${list.capability} and cache metadata.`;
+}
+export function listResponseInvalid(list, server, suggestedFix) {
+    return catalogFinding("plugin.catalog.response.invalid", "fail", `The ${server} returned an invalid ${list.method} response.`, `The ${list.noun} catalog cannot be safely enumerated from this response.`, suggestedFix);
+}
+export function listCursorLoop(list, server) {
+    return catalogFinding("plugin.catalog.cursor.loop", "warn", `The ${server} repeated a ${list.method} cursor.`, "The bounded catalog enumeration cannot determine a complete result set.", "Return each continuation cursor at most once for a single enumeration.");
+}
 function isAuthorizationFinding(discovery) {
     return discovery.findings.some((item) => item.id === "plugin.discovery.authorization.required" || item.id === "plugin.discovery.authorization.rejected");
 }
@@ -124,11 +136,36 @@ export function createMcpToolCatalogInspector() {
         }
     };
 }
-export function serializeToolsListRequest(id, cursor) {
+export const MCP_TOOLS_LIST = {
+    method: "tools/list",
+    capability: "tools",
+    noun: "tool",
+    createInspector() {
+        const inspector = createMcpToolCatalogInspector();
+        return {
+            findings: inspector.findings,
+            items: inspector.tools,
+            get checked() {
+                return inspector.toolsChecked;
+            },
+            addFindings: inspector.addFindings,
+            inspectPage: inspector.inspectPage
+        };
+    }
+};
+function toolCatalogSnapshot(capture) {
+    const { complete, pagesRead, checked, reason } = capture.catalog;
+    return {
+        report: buildMcpToolCatalogReport(capture.discovery, capture.status, { complete, pagesRead, toolsChecked: checked, reason }, capture.enumeration, capture.findings),
+        tools: capture.items,
+        cache: capture.cache
+    };
+}
+export function serializeListRequest(method, id, cursor) {
     return JSON.stringify({
         jsonrpc: "2.0",
         id,
-        method: "tools/list",
+        method,
         params: {
             ...(cursor === undefined ? {} : { cursor }),
             _meta: {
@@ -144,6 +181,10 @@ export async function inspectMcpToolCatalog(rawUrl, options = {}) {
 }
 // Tools and cache metadata are returned only for a complete enumeration.
 export async function captureMcpToolCatalog(rawUrl, options = {}) {
+    return toolCatalogSnapshot(await captureMcpCatalog(rawUrl, MCP_TOOLS_LIST, options));
+}
+// Definitions and cache metadata are returned only for a complete enumeration.
+export async function captureMcpCatalog(rawUrl, list, options = {}) {
     const request = options.request ?? requestBoundedHttp;
     const now = options.now ?? (() => performance.now());
     const deadline = now() + TOTAL_TIMEOUT_MS;
@@ -186,31 +227,31 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
             return response;
         }
     });
-    const partial = (report) => ({ report, tools: null, cache: null });
-    const emptyCatalog = { complete: false, pagesRead: 0, toolsChecked: 0, reason: null };
+    const partial = (status, catalog, enumeration, findings) => ({ discovery, status, catalog, enumeration, findings, items: null, cache: null });
+    const emptyCatalog = { complete: false, pagesRead: 0, checked: 0, reason: null };
     if (discovery.status === "blocked") {
         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", []));
+        return partial("blocked", { ...emptyCatalog, reason }, "not-tested", []);
     }
     if (isAuthorizationFinding(discovery)) {
-        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "authorization-required" }, "not-tested", []));
+        return partial("incomplete", { ...emptyCatalog, reason: "authorization-required" }, "not-tested", []);
     }
     if (discovery.status === "unsupported") {
-        return partial(buildMcpToolCatalogReport(discovery, "unsupported", { ...emptyCatalog, reason: "discovery-unsupported" }, "not-tested", []));
+        return partial("unsupported", { ...emptyCatalog, reason: "discovery-unsupported" }, "not-tested", []);
     }
     if (discovery.status !== "discovered") {
-        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { ...emptyCatalog, reason: budgetReason ?? "discovery-failed" }, "not-tested", []));
+        return partial("incomplete", { ...emptyCatalog, reason: budgetReason ?? "discovery-failed" }, "not-tested", []);
     }
     const capabilities = discoveryResponse === null ? null : discoverMcpCapabilities(discoveryResponse);
     if (capabilities === null) {
-        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "discovery-response-unavailable" }, "not-tested", []));
+        return partial("incomplete", { ...emptyCatalog, reason: "discovery-response-unavailable" }, "not-tested", []);
     }
-    if (!Object.hasOwn(capabilities, "tools")) {
-        return partial(buildMcpToolCatalogReport(discovery, "not-applicable", emptyCatalog, "not-tested", []));
+    if (!Object.hasOwn(capabilities, list.capability)) {
+        return partial("not-applicable", emptyCatalog, "not-tested", []);
     }
-    const inspector = createMcpToolCatalogInspector();
+    const inspector = list.createInspector();
     const findings = inspector.findings;
     const seenCursors = new Set();
     let pagesRead = 0;
@@ -233,7 +274,7 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
             incompleteReason = "total-time-limit";
             break;
         }
-        const requestId = `tools-list-${pagesRead + 1}`;
+        const requestId = `${list.capability}-list-${pagesRead + 1}`;
         let response;
         try {
             response = await requestWithinBudget(rawUrl, {
@@ -241,12 +282,12 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
                 lookup: options.lookup,
                 bearerToken: options.bearerToken,
                 method: "POST",
-                body: serializeToolsListRequest(requestId, cursor),
+                body: serializeListRequest(list.method, requestId, cursor),
                 headers: {
                     Accept: "application/json, text/event-stream",
                     "Content-Type": "application/json",
                     "MCP-Protocol-Version": REQUESTED_VERSION,
-                    "Mcp-Method": "tools/list"
+                    "Mcp-Method": list.method
                 },
                 stopAfter: (received) => findMcpSseResponse(received, requestId) !== null
             });
@@ -273,18 +314,18 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
         const message = parseMcpResponse(response, requestId);
         if (message !== null && hasMatchingEnvelope(message, requestId) && Object.hasOwn(message, "error")
             && 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";
+            if (addFindings([listMethodUnsupported(list, "endpoint")]))
+                incompleteReason = `${list.capability}-list-method-unsupported`;
             break;
         }
         if (response.statusCode !== 200) {
-            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.")]))
+            if (addFindings([catalogFinding("plugin.catalog.http_status.invalid", "fail", `The endpoint returned an unexpected ${list.method} HTTP status.`, `The ${list.noun} catalog cannot be safely enumerated from this response.`, `Return HTTP 200 for a ${list.method} response after authorization succeeds.`)]))
                 incompleteReason = "http-status-invalid";
             break;
         }
-        const page = message === null ? null : parseToolsResult(message, requestId);
+        const page = message === null ? null : parseListResult(message, requestId, list.capability);
         if (page === null) {
-            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.")]))
+            if (addFindings([listResponseInvalid(list, "endpoint", modernInvalidFix(list))]))
                 incompleteReason = "response-invalid";
             break;
         }
@@ -293,32 +334,36 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
             ttlMs: Math.min(cache.ttlMs, page.cache.ttlMs),
             cacheScope: cache.cacheScope === "private" ? "private" : page.cache.cacheScope
         };
-        incompleteReason = inspector.inspectPage(page.tools, pagesRead, () => deadline - now() <= 0);
+        incompleteReason = inspector.inspectPage(page.items, pagesRead, () => deadline - now() <= 0);
         if (incompleteReason !== null)
             break;
         if (page.cursor === undefined)
             break;
         if (seenCursors.has(page.cursor)) {
-            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.")]))
+            if (addFindings([listCursorLoop(list, "endpoint")]))
                 incompleteReason = "cursor-loop";
             break;
         }
         seenCursors.add(page.cursor);
         cursor = page.cursor;
     }
-    const toolsChecked = inspector.toolsChecked;
+    const checked = inspector.checked;
     if (blocked) {
-        return partial(buildMcpToolCatalogReport(discovery, "blocked", { complete: false, pagesRead, toolsChecked, reason: "network-blocked" }, "incomplete", findings));
+        return partial("blocked", { complete: false, pagesRead, checked, reason: "network-blocked" }, "incomplete", findings);
     }
     if (incompleteReason !== null) {
-        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { complete: false, pagesRead, toolsChecked, reason: incompleteReason }, "incomplete", findings));
+        return partial("incomplete", { complete: false, pagesRead, checked, reason: incompleteReason }, "incomplete", findings);
     }
     if (deadline - now() <= 0) {
-        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { complete: false, pagesRead, toolsChecked, reason: "total-time-limit" }, "incomplete", findings));
+        return partial("incomplete", { complete: false, pagesRead, checked, reason: "total-time-limit" }, "incomplete", findings);
     }
     return {
-        report: buildMcpToolCatalogReport(discovery, finalCatalogStatus(findings), { complete: true, pagesRead, toolsChecked, reason: null }, "complete", findings),
-        tools: inspector.tools,
+        discovery,
+        status: finalCatalogStatus(findings),
+        catalog: { complete: true, pagesRead, checked, reason: null },
+        enumeration: "complete",
+        findings,
+        items: inspector.items,
         cache
     };
 }

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

@@ -1,4 +1,4 @@
-import { type ToolChangeImpact, type ToolChangeReason } from "./mcp-tool-impact.js";
+import { type ToolChangeImpact, type ToolChangeLocation, type ToolChangeReason } from "./mcp-tool-impact.js";
 import { type McpToolFileReport } from "./mcp-tool-file.js";
 type DiffField = "inputSchema" | "outputSchema" | "description" | "title" | "annotations" | "other";
 export interface McpToolDiffReport {
@@ -32,7 +32,13 @@ export interface McpToolDiffReport {
         fields: DiffField[];
         impact: ToolChangeImpact;
         reasons: ToolChangeReason[];
+        name?: string;
+        locations?: ToolChangeLocation[];
     }>;
 }
-export declare function compareMcpToolFiles(beforePath: string, afterPath: string): Promise<McpToolDiffReport>;
+export interface McpToolDiffOptions {
+    showNames?: boolean;
+}
+export declare function structurallyEqual(left: unknown, right: unknown): boolean;
+export declare function compareMcpToolFiles(beforePath: string, afterPath: string, options?: McpToolDiffOptions): Promise<McpToolDiffReport>;
 export {};

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

@@ -11,7 +11,7 @@ const EXCLUDED_OTHER_FIELDS = new Set(["name", ...FIXED_FIELDS]);
 function isJsonObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function structurallyEqual(left, right) {
+export function structurallyEqual(left, right) {
     const pending = [[left, right]];
     while (pending.length > 0) {
         const [currentLeft, currentRight] = pending.pop();
@@ -85,7 +85,7 @@ function incompleteReport(before, after, status, reason) {
         changes: []
     };
 }
-export async function compareMcpToolFiles(beforePath, afterPath) {
+export async function compareMcpToolFiles(beforePath, afterPath, options = {}) {
     const [beforeSnapshot, afterSnapshot] = await Promise.all([
         loadMcpToolFileSnapshot(beforePath),
         loadMcpToolFileSnapshot(afterPath)
@@ -106,6 +106,7 @@ export async function compareMcpToolFiles(beforePath, afterPath) {
     if (beforeDefinitions === null || afterDefinitions === null) {
         return incompleteReport(before, after, "incomplete", "ambiguous-names");
     }
+    const named = (name) => (options.showNames === true ? { name } : {});
     const changes = [];
     let added = 0;
     let removed = 0;
@@ -115,7 +116,7 @@ export async function compareMcpToolFiles(beforePath, afterPath) {
         const afterDefinition = afterDefinitions.get(name);
         if (afterDefinition === undefined) {
             removed += 1;
-            changes.push({ kind: "removed", beforeToolIndex: beforeDefinition.index, afterToolIndex: null, fields: [], ...classifyRemovedTool() });
+            changes.push({ kind: "removed", ...named(name), beforeToolIndex: beforeDefinition.index, afterToolIndex: null, fields: [], ...classifyRemovedTool() });
             continue;
         }
         const fields = changedFields(beforeDefinition.value, afterDefinition.value);
@@ -126,17 +127,18 @@ export async function compareMcpToolFiles(beforePath, afterPath) {
             changed += 1;
             changes.push({
                 kind: "changed",
+                ...named(name),
                 beforeToolIndex: beforeDefinition.index,
                 afterToolIndex: afterDefinition.index,
                 fields,
-                ...classifyChangedTool(beforeDefinition.value, afterDefinition.value, fields, structurallyEqual)
+                ...classifyChangedTool(beforeDefinition.value, afterDefinition.value, fields, structurallyEqual, { locate: options.showNames === true })
             });
         }
     }
     for (const [name, afterDefinition] of afterDefinitions) {
         if (!beforeDefinitions.has(name)) {
             added += 1;
-            changes.push({ kind: "added", beforeToolIndex: null, afterToolIndex: afterDefinition.index, fields: [], ...classifyAddedTool() });
+            changes.push({ kind: "added", ...named(name), beforeToolIndex: null, afterToolIndex: afterDefinition.index, fields: [], ...classifyAddedTool() });
         }
     }
     return {

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

@@ -30,5 +30,25 @@ export interface McpToolFileSnapshot {
     tools: unknown[] | null;
 }
 export declare function isBlockedOfflinePath(filePath: string): boolean;
+export declare function readBoundedRegularFile(filePath: string): Promise<{
+    kind: "content";
+    content: Buffer;
+    bytesRead: number;
+} | {
+    kind: "unavailable";
+    bytesRead: number;
+} | {
+    kind: "too-large";
+    bytesRead: number;
+} | {
+    kind: "changed";
+    bytesRead: number;
+} | {
+    kind: "symlink";
+    bytesRead: number;
+} | {
+    kind: "not-regular";
+    bytesRead: number;
+}>;
 export declare function loadMcpToolFileSnapshot(filePath: string): Promise<McpToolFileSnapshot>;
 export declare function inspectMcpToolFile(filePath: string): Promise<McpToolFileReport>;

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

@@ -90,7 +90,7 @@ function parseToolsResult(value) {
         return null;
     return { tools: value.result.tools, hasNextCursor };
 }
-async function readBoundedRegularFile(filePath) {
+export async function readBoundedRegularFile(filePath) {
     let initial;
     try {
         initial = await lstat(filePath);

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

@@ -2,12 +2,21 @@ 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-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 ToolChangeLocation {
+    reason: ToolChangeReason;
+    pointer: string;
+}
 export interface ToolChangeClassification {
     impact: ToolChangeImpact;
     reasons: ToolChangeReason[];
+    locations?: ToolChangeLocation[];
 }
+export declare const MAX_TOOL_CHANGE_LOCATIONS = 100;
+export declare const MAX_TOOL_CHANGE_POINTER_LENGTH = 1000;
 type Equal = (left: unknown, right: unknown) => boolean;
 export declare function classifyRemovedTool(): ToolChangeClassification;
 export declare function classifyAddedTool(): ToolChangeClassification;
-export declare function classifyChangedTool(before: JsonObject, after: JsonObject, fields: readonly string[], equal: Equal): ToolChangeClassification;
+export declare function classifyChangedTool(before: JsonObject, after: JsonObject, fields: readonly string[], equal: Equal, options?: {
+    locate?: boolean;
+}): ToolChangeClassification;
 export {};

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

@@ -19,6 +19,59 @@ export const TOOL_CHANGE_REASONS = [
     "annotation-safety-reduced",
     "other-fields-unclassified"
 ];
+export const MAX_TOOL_CHANGE_LOCATIONS = 100;
+// Longer pointers are not recorded, so a long property name cannot make locating costly or the report large.
+export const MAX_TOOL_CHANGE_POINTER_LENGTH = 1_000;
+/**
+ * A reason set that also records, for each reason, the JSON Pointer of the schema position being
+ * compared when it was added. A shared definition is compared once, so it is located at the first
+ * reference that reached it.
+ */
+class LocatingReasons extends Set {
+    locations = [];
+    // Escaped pointer segments of the position being compared, and the pointer length at each one;
+    // a segment that would pass the length limit is left empty, with an infinite length.
+    segments = [];
+    lengths = [0];
+    seen = new Set();
+    enter(tokens) {
+        for (const token of tokens) {
+            const previous = this.lengths[this.lengths.length - 1];
+            const segment = previous + 1 + token.length > MAX_TOOL_CHANGE_POINTER_LENGTH ? "" : `/${token.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+            this.segments.push(segment);
+            this.lengths.push(segment === "" || previous + segment.length > MAX_TOOL_CHANGE_POINTER_LENGTH ? Infinity : previous + segment.length);
+        }
+    }
+    leave(count) {
+        this.segments.length -= count;
+        this.lengths.length -= count;
+    }
+    add(reason) {
+        if (this.locations.length < MAX_TOOL_CHANGE_LOCATIONS && this.lengths[this.lengths.length - 1] !== Infinity) {
+            const pointer = this.segments.join("");
+            const key = `${reason} ${pointer}`;
+            if (!this.seen.has(key)) {
+                this.seen.add(key);
+                this.locations.push({ reason, pointer });
+            }
+        }
+        return super.add(reason);
+    }
+}
+/** Runs `compare` with `tokens` appended to the recorded location, when locations are recorded. */
+function within(reasons, tokens, compare) {
+    if (!(reasons instanceof LocatingReasons)) {
+        compare();
+        return;
+    }
+    reasons.enter(tokens);
+    try {
+        compare();
+    }
+    finally {
+        reasons.leave(tokens.length);
+    }
+}
 const UNCLASSIFIED_REASONS = new Set([
     "input-schema-unclassified",
     "output-schema-unclassified",
@@ -752,12 +805,14 @@ function compareSchema(before, after, direction, depth, equal, reasons, scope) {
         compareNumericAndArrayConstraints(inner, outer, codes, reasons);
         compareStringConstraints(inner, outer, codes, reasons);
         if (!sameMeaning(before.items, after.items, equal, scope)) {
-            if (unevaluated)
-                reasons.add(codes.unclassified);
-            else if (outer.items !== undefined && inner.items === undefined)
-                reasons.add(codes.constraint);
-            else if (outer.items !== undefined)
-                compareSchema(before.items, after.items, direction, depth + 1, equal, reasons, scope);
+            within(reasons, ["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, scope);
+            });
         }
     }
     const innerRequired = stringSet(inner.required);
@@ -770,13 +825,15 @@ function compareSchema(before, after, direction, depth, equal, reasons, scope) {
     }
     for (const key of outerRequired) {
         if (!innerRequired.has(key))
-            reasons.add(codes.required);
+            within(reasons, ["properties", key], () => reasons.add(codes.required));
     }
     for (const key of Object.keys(beforeProperties)) {
-        if (!Object.hasOwn(afterProperties, key))
-            reasons.add(codes.propertyRemoved);
-        else
-            compareSchema(beforeProperties[key], afterProperties[key], direction, depth + 1, equal, reasons, scope);
+        within(reasons, ["properties", key], () => {
+            if (!Object.hasOwn(afterProperties, key))
+                reasons.add(codes.propertyRemoved);
+            else
+                compareSchema(beforeProperties[key], afterProperties[key], direction, depth + 1, equal, reasons, scope);
+        });
     }
     // In an object whose undeclared keys were governed by other keywords, or a nested input object
     // that left them open, a newly declared property can reject values callers send (input) or
@@ -834,7 +891,7 @@ function result(reasons) {
     const impact = ordered.some((reason) => !UNCLASSIFIED_REASONS.has(reason))
         ? "breaking"
         : ordered.length > 0 ? "unclassified" : "compatible";
-    return { impact, reasons: ordered };
+    return reasons instanceof LocatingReasons ? { impact, reasons: ordered, locations: reasons.locations } : { impact, reasons: ordered };
 }
 export function classifyRemovedTool() {
     return { impact: "breaking", reasons: ["tool-removed"] };
@@ -842,15 +899,15 @@ export function classifyRemovedTool() {
 export function classifyAddedTool() {
     return { impact: "compatible", reasons: [] };
 }
-export function classifyChangedTool(before, after, fields, equal) {
-    const reasons = new Set();
+export function classifyChangedTool(before, after, fields, equal, options = {}) {
+    const reasons = options.locate ? new LocatingReasons() : new Set();
     if (fields.includes("inputSchema")) {
-        compareSchema(before.inputSchema, after.inputSchema, "input", 0, equal, reasons, referenceScope(before.inputSchema, after.inputSchema));
+        within(reasons, ["inputSchema"], () => compareSchema(before.inputSchema, after.inputSchema, "input", 0, equal, reasons, referenceScope(before.inputSchema, after.inputSchema)));
     }
     if (fields.includes("outputSchema"))
-        classifyOutputSchema(before.outputSchema, after.outputSchema, equal, reasons);
+        within(reasons, ["outputSchema"], () => classifyOutputSchema(before.outputSchema, after.outputSchema, equal, reasons));
     if (fields.includes("annotations"))
-        classifyAnnotations(before.annotations, after.annotations, reasons);
+        within(reasons, ["annotations"], () => classifyAnnotations(before.annotations, after.annotations, reasons));
     if (fields.includes("other"))
         reasons.add("other-fields-unclassified");
     return result(reasons);

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

@@ -1,10 +1,12 @@
 import type { McpToolCatalogCache } from "./mcp-tool-catalog.js";
-export type McpToolResponseSaveResult = {
+export type McpListResponseSaveResult = {
     kind: "saved";
     bytes: number;
-    tools: number;
+    count: 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>;
+type ListKey = "tools" | "prompts";
+export declare function serializeMcpListResponse(key: ListKey, items: unknown[], cache: McpToolCatalogCache): string;
+export declare function saveMcpListResponse(filePath: string, key: ListKey, items: unknown[], cache: McpToolCatalogCache): Promise<McpListResponseSaveResult>;
+export {};

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

@@ -2,21 +2,21 @@ 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) {
+// Serializes an enumerated catalog as one complete tools/list or prompts/list response that the offline file and diff commands accept.
+export function serializeMcpListResponse(key, items, cache) {
     return `${JSON.stringify({
         jsonrpc: "2.0",
-        id: "tools-list",
-        result: { resultType: "complete", tools, ttlMs: cache.ttlMs, cacheScope: cache.cacheScope }
+        id: `${key}-list`,
+        result: { resultType: "complete", [key]: items, ttlMs: cache.ttlMs, cacheScope: cache.cacheScope }
     }, null, 2)}\n`;
 }
-export async function saveMcpToolsListResponse(filePath, tools, cache) {
+export async function saveMcpListResponse(filePath, key, items, cache) {
     if (isBlockedOfflinePath(filePath))
         return { kind: "path-blocked" };
     let content;
     let bytes;
     try {
-        content = serializeMcpToolsListResponse(tools, cache);
+        content = serializeMcpListResponse(key, items, cache);
         bytes = Buffer.byteLength(content);
     }
     catch {
@@ -38,7 +38,7 @@ export async function saveMcpToolsListResponse(filePath, tools, cache) {
     // 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.
+        // Create with the replaced baseline's permission bits, which may protect private definitions.
         await writeFile(tempPath, content, { encoding: "utf8", flag: "wx", mode: existingMode ?? 0o666 });
         if (existingMode !== null)
             await chmod(tempPath, existingMode);
@@ -48,5 +48,5 @@ export async function saveMcpToolsListResponse(filePath, tools, cache) {
         await rm(tempPath, { force: true }).catch(() => undefined);
         return { kind: "write-failed" };
     }
-    return { kind: "saved", bytes, tools: tools.length };
+    return { kind: "saved", bytes, count: items.length };
 }