codex-plugin-doctor 1.75.0 → 1.77.0

package/dist/core/output-contract.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { packageVersion } from "../version.js";
-import { TOOL_CHANGE_REASONS } from "./mcp-tool-impact.js";
+import { MAX_PROMPT_CHANGE_LOCATIONS, PROMPT_CHANGE_REASONS } from "./mcp-prompt-impact.js";
+import { MAX_TOOL_CHANGE_LOCATIONS, MAX_TOOL_CHANGE_POINTER_LENGTH, TOOL_CHANGE_REASONS } from "./mcp-tool-impact.js";
 import { ruleCatalog } from "../rules/rule-catalog.js";
 const runtimeCapabilityStatusSchema = {
     type: "string",
@@ -836,7 +837,193 @@ publicSchemaDefinitions.push({
                     afterToolIndex: { type: ["integer", "null"], minimum: 1, maximum: 500 },
                     fields: { type: "array", maxItems: 6, uniqueItems: true, items: { enum: ["inputSchema", "outputSchema", "description", "title", "annotations", "other"] } },
                     impact: { enum: ["breaking", "compatible", "unclassified"] },
-                    reasons: { type: "array", maxItems: TOOL_CHANGE_REASONS.length, uniqueItems: true, items: { enum: [...TOOL_CHANGE_REASONS] } }
+                    reasons: { type: "array", maxItems: TOOL_CHANGE_REASONS.length, uniqueItems: true, items: { enum: [...TOOL_CHANGE_REASONS] } },
+                    // Only with --show-names.
+                    name: { type: "string" },
+                    locations: {
+                        type: "array", maxItems: MAX_TOOL_CHANGE_LOCATIONS,
+                        items: {
+                            type: "object", required: ["reason", "pointer"],
+                            properties: { reason: { enum: [...TOOL_CHANGE_REASONS] }, pointer: { type: "string", maxLength: MAX_TOOL_CHANGE_POINTER_LENGTH } },
+                            additionalProperties: false
+                        }
+                    }
+                }, additionalProperties: false
+            }
+        }
+    }
+});
+// The prompt catalog shares discovery, protocol, and execution evidence with the tool catalog.
+const toolCatalogProperties = publicSchemaDefinitions.find((definition) => definition.id === "doctor.tools.json").properties;
+publicSchemaDefinitions.push({
+    id: "doctor.prompts.json",
+    command: "codex-plugin-doctor doctor prompts <url> --allow-network --json",
+    required: ["schemaVersion", "scope", "status", "discovery", "catalog", "coverage", "findings"],
+    properties: {
+        schemaVersion: { const: 1 },
+        scope: { const: "prompt-catalog-structure" },
+        // transport, protocol, and execution appear only on reports from `doctor prompts <path> --server <name> --runtime`.
+        transport: { const: "stdio" },
+        status: toolCatalogProperties.status,
+        protocol: toolCatalogProperties.protocol,
+        execution: toolCatalogProperties.execution,
+        discovery: toolCatalogProperties.discovery,
+        catalog: {
+            type: "object", required: ["complete", "pagesRead", "promptsChecked", "reason"],
+            properties: {
+                complete: { type: "boolean" },
+                pagesRead: { type: "integer", minimum: 0, maximum: 5 },
+                promptsChecked: { type: "integer", minimum: 0, maximum: 500 },
+                reason: { type: ["string", "null"] }
+            },
+            additionalProperties: false
+        },
+        coverage: {
+            type: "object", required: ["discovery", "catalogEnumeration", "definitions", "promptRetrieval", "fullConformance"],
+            properties: {
+                discovery: { enum: ["pass", "fail", "skipped"] },
+                catalogEnumeration: { enum: ["complete", "incomplete", "not-tested"] },
+                definitions: { const: "shape-only" },
+                promptRetrieval: { const: "not-tested" },
+                fullConformance: { const: "not-tested" }
+            },
+            additionalProperties: false
+        },
+        findings: {
+            type: "array", maxItems: 100,
+            items: {
+                type: "object", required: ["id", "severity", "message", "impact", "suggestedFix"],
+                properties: {
+                    id: { type: "string", pattern: "^plugin\\.catalog\\." },
+                    severity: { enum: ["warn", "fail"] },
+                    message: { type: "string" }, impact: { type: "string" }, suggestedFix: { type: "string" },
+                    location: {
+                        type: "object", required: ["page", "promptIndex"],
+                        properties: {
+                            page: { type: "integer", minimum: 1, maximum: 5 },
+                            promptIndex: { type: "integer", minimum: 1, maximum: 500 },
+                            argumentIndex: { type: "integer", minimum: 1 },
+                            relatedPromptIndex: { type: "integer", minimum: 1, maximum: 500 },
+                            relatedArgumentIndex: { type: "integer", minimum: 1 }
+                        },
+                        additionalProperties: false
+                    }
+                },
+                additionalProperties: false
+            }
+        }
+    }
+});
+const promptFileReportDefinition = {
+    id: "doctor.prompts.file.json",
+    command: "codex-plugin-doctor doctor prompts-file <path> --json",
+    required: ["schemaVersion", "scope", "status", "source", "inspection", "coverage", "findings"],
+    properties: {
+        schemaVersion: { const: 1 },
+        scope: { const: "prompt-definitions-file" },
+        status: { enum: ["pass", "warn", "fail", "incomplete", "blocked"] },
+        source: {
+            type: "object", required: ["kind", "format", "bytesRead"],
+            properties: {
+                kind: { const: "file" }, format: { const: "mcp-prompts-list-response" },
+                bytesRead: { type: "integer", minimum: 0, maximum: 1048577 }
+            }, additionalProperties: false
+        },
+        inspection: {
+            type: "object", required: ["complete", "promptsChecked", "hasNextCursor", "reason"],
+            properties: {
+                complete: { type: "boolean" }, promptsChecked: { type: "integer", minimum: 0, maximum: 500 },
+                hasNextCursor: { type: ["boolean", "null"] }, reason: { type: ["string", "null"] }
+            }, additionalProperties: false
+        },
+        coverage: {
+            type: "object", required: ["definitions", "discovery", "serverCatalog", "promptRetrieval", "fullConformance"],
+            properties: {
+                definitions: { const: "shape-only" }, discovery: { const: "not-tested" },
+                serverCatalog: { const: "not-tested" }, promptRetrieval: { const: "not-tested" },
+                fullConformance: { const: "not-tested" }
+            }, additionalProperties: false
+        },
+        findings: {
+            type: "array", maxItems: 100,
+            items: {
+                type: "object", required: ["id", "severity", "message", "impact", "suggestedFix"],
+                properties: {
+                    id: { type: "string", pattern: "^plugin\\.(catalog|prompts_file)\\." },
+                    severity: { enum: ["warn", "fail"] },
+                    message: { type: "string" }, impact: { type: "string" }, suggestedFix: { type: "string" },
+                    location: {
+                        type: "object", required: ["page", "promptIndex"],
+                        properties: {
+                            page: { const: 1 }, promptIndex: { type: "integer", minimum: 1, maximum: 500 },
+                            argumentIndex: { type: "integer", minimum: 1 },
+                            relatedPromptIndex: { type: "integer", minimum: 1, maximum: 500 },
+                            relatedArgumentIndex: { type: "integer", minimum: 1 }
+                        }, additionalProperties: false
+                    }
+                }, additionalProperties: false
+            }
+        }
+    }
+};
+const embeddedPromptFileReportSchema = {
+    type: "object",
+    required: promptFileReportDefinition.required,
+    properties: promptFileReportDefinition.properties,
+    additionalProperties: true
+};
+publicSchemaDefinitions.push(promptFileReportDefinition, {
+    id: "doctor.prompts.diff.json",
+    command: "codex-plugin-doctor doctor prompts-diff --before <path> --after <path> --json",
+    required: ["schemaVersion", "scope", "status", "before", "after", "comparison", "coverage", "changes"],
+    properties: {
+        schemaVersion: { const: 1 },
+        scope: { const: "prompt-definitions-diff" },
+        status: { enum: ["pass", "warn", "incomplete", "blocked"] },
+        before: embeddedPromptFileReportSchema,
+        after: embeddedPromptFileReportSchema,
+        comparison: {
+            type: "object", required: ["complete", "reason", "added", "removed", "changed", "unchanged", "breaking", "unclassified"],
+            properties: {
+                complete: { type: "boolean" },
+                reason: { enum: [null, "input-blocked", "input-incomplete", "invalid-definitions", "ambiguous-names"] },
+                added: { type: ["integer", "null"], minimum: 0, maximum: 500 },
+                removed: { type: ["integer", "null"], minimum: 0, maximum: 500 },
+                changed: { type: ["integer", "null"], minimum: 0, maximum: 500 },
+                unchanged: { type: ["integer", "null"], minimum: 0, maximum: 500 },
+                breaking: { type: ["integer", "null"], minimum: 0, maximum: 1000 },
+                unclassified: { type: ["integer", "null"], minimum: 0, maximum: 1000 }
+            }, additionalProperties: false
+        },
+        coverage: {
+            type: "object", required: ["comparison", "definitions", "compatibility", "serverCatalog", "promptRetrieval", "impactClassification"],
+            properties: {
+                comparison: { const: "structural-only" }, definitions: { const: "shape-only" },
+                compatibility: { const: "not-tested" }, serverCatalog: { const: "not-tested" },
+                promptRetrieval: { const: "not-tested" }, impactClassification: { const: "heuristic" }
+            }, additionalProperties: false
+        },
+        changes: {
+            type: "array", maxItems: 1000,
+            items: {
+                type: "object", required: ["kind", "beforePromptIndex", "afterPromptIndex", "fields", "impact", "reasons"],
+                properties: {
+                    kind: { enum: ["added", "removed", "changed"] },
+                    beforePromptIndex: { type: ["integer", "null"], minimum: 1, maximum: 500 },
+                    afterPromptIndex: { type: ["integer", "null"], minimum: 1, maximum: 500 },
+                    fields: { type: "array", maxItems: 4, uniqueItems: true, items: { enum: ["arguments", "description", "title", "other"] } },
+                    impact: { enum: ["breaking", "compatible", "unclassified"] },
+                    reasons: { type: "array", maxItems: PROMPT_CHANGE_REASONS.length, uniqueItems: true, items: { enum: [...PROMPT_CHANGE_REASONS] } },
+                    // Only with --show-names.
+                    name: { type: "string" },
+                    locations: {
+                        type: "array", maxItems: MAX_PROMPT_CHANGE_LOCATIONS,
+                        items: {
+                            type: "object", required: ["reason", "argument"],
+                            properties: { reason: { enum: [...PROMPT_CHANGE_REASONS] }, argument: { type: ["string", "null"] } },
+                            additionalProperties: false
+                        }
+                    }
                 }, additionalProperties: false
             }
         }

package/dist/reporting/quote-server-text.d.ts

@@ -0,0 +1,3 @@
+/** Quotes server-supplied text, such as a tool name or a JSON Pointer, as a JSON string that only holds printable characters. */
+export declare function quoteServerText(text: string): string;
+export declare function markdownCodeSpan(text: string): string;

package/dist/reporting/quote-server-text.js

@@ -0,0 +1,20 @@
+// Control, format, and line or paragraph separator characters, which can drive a terminal, end a line,
+// reorder text, or hide in it; JSON escapes only the C0 controls among them.
+const UNSAFE_TEXT = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
+/** Quotes server-supplied text, such as a tool name or a JSON Pointer, as a JSON string that only holds printable characters. */
+export function quoteServerText(text) {
+    return JSON.stringify(text).replace(UNSAFE_TEXT, (character) => Array.from({ length: character.length }, (_, index) => `\\u${character.charCodeAt(index).toString(16).padStart(4, "0")}`).join(""));
+}
+// Names and pointers come from the server, so they are quoted and put in a code span, where Markdown,
+// HTML, mentions, and links stay inert; the fence outgrows any backtick run, and pipes are escaped for the table.
+export function markdownCodeSpan(text) {
+    const quoted = quoteServerText(text);
+    let run = 0;
+    let longest = 0;
+    for (const character of quoted) {
+        run = character === "`" ? run + 1 : 0;
+        longest = Math.max(longest, run);
+    }
+    const fence = "`".repeat(longest + 1);
+    return `${fence}${quoted.replace(/\|/gu, "\\|")}${fence}`;
+}

package/dist/reporting/render-mcp-prompt-catalog-report.d.ts

@@ -0,0 +1,2 @@
+import type { McpPromptCatalogReport } from "../core/mcp-prompt-catalog.js";
+export declare function renderMcpPromptCatalogReport(report: McpPromptCatalogReport): string;

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

@@ -0,0 +1,31 @@
+import { describePromptLocation } from "./render-mcp-prompt-file-report.js";
+export function renderMcpPromptCatalogReport(report) {
+    return [
+        "MCP Prompt Catalog",
+        "==================",
+        `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}`,
+        `Prompts checked: ${report.catalog.promptsChecked}`,
+        ...(report.catalog.reason === null ? [] : [`Reason: ${report.catalog.reason}`]),
+        `Enumeration: ${report.coverage.catalogEnumeration}`,
+        `Definition coverage: ${report.coverage.definitions}`,
+        `Prompt retrieval: ${report.coverage.promptRetrieval}`,
+        `Full conformance: ${report.coverage.fullConformance}`,
+        "Counts describe inspected content, not a guaranteed server-wide inventory.",
+        ...report.discovery.findings.map((finding) => `${finding.severity.toUpperCase()} ${finding.id}: ${finding.message}\n  ${finding.suggestedFix}`),
+        ...report.findings.map((finding) => {
+            const locator = finding.location ? ` [page ${finding.location.page}, ${describePromptLocation(finding.location)}]` : "";
+            return `${finding.severity.toUpperCase()} ${finding.id}${locator}: ${finding.message}\n  ${finding.suggestedFix}`;
+        })
+    ].join("\n");
+}

package/dist/reporting/render-mcp-prompt-diff-markdown.d.ts

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

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

@@ -0,0 +1,39 @@
+import { markdownCodeSpan } from "./quote-server-text.js";
+import { describePromptLocation } from "./render-mcp-prompt-file-report.js";
+function count(value) {
+    return value === null || value === undefined ? "not compared" : String(value);
+}
+function promptIndex(value) {
+    return value === null ? "-" : String(value);
+}
+export function renderMcpPromptDiffMarkdown(report) {
+    const comparison = report.comparison;
+    const named = report.changes.some((change) => change.name !== undefined);
+    const lines = [
+        "## MCP Prompt 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", "", named ? "| Change | Prompt | Before prompt | After prompt | Fields | Impact | Reasons |" : "| Change | Before prompt | After prompt | Fields | Impact | Reasons |", named ? "| --- | --- | --- | --- | --- | --- | --- |" : "| --- | --- | --- | --- | --- | --- |", ...report.changes.map((change) => `| ${change.kind}${named ? ` | ${change.name === undefined ? "-" : markdownCodeSpan(change.name)}` : ""} | ${promptIndex(change.beforePromptIndex)} | ${promptIndex(change.afterPromptIndex)} | ${change.fields.map((field) => `\`${field}\``).join(", ") || "-"} | **${change.impact}** | ${change.reasons.map((reason) => `\`${reason}\``).join(", ") || "-"} |`));
+    }
+    const located = report.changes.flatMap((change) => (change.locations ?? []).map((location) => `| ${change.name === undefined ? "-" : markdownCodeSpan(change.name)} | \`${location.reason}\` | ${location.argument === null ? "-" : markdownCodeSpan(location.argument)} |`));
+    if (located.length > 0) {
+        lines.push("", "### Locations", "", "| Prompt | Reason | Argument |", "| --- | --- | --- |", ...located);
+    }
+    const findings = ["before", "after"].flatMap((side) => report[side].findings.map((finding) => {
+        const locator = finding.location ? `${side} ${describePromptLocation(finding.location)}` : side;
+        return `| ${finding.severity} | \`${finding.id}\` | ${locator} | ${finding.message} |`;
+    }));
+    if (findings.length > 0) {
+        lines.push("", "### Input Findings", "", "| Severity | Finding | Location | Message |", "| --- | --- | --- | --- |", ...findings);
+    }
+    lines.push("", named
+        ? `Prompt and argument names are shown because --show-names was used; descriptions and other values are not reported. Impact labels are ${report.coverage.impactClassification} argument checks, not proof of compatibility.`
+        : `Prompt numbers are one-based positions in the before and after files; names and descriptions are not reported. Impact labels are ${report.coverage.impactClassification} argument checks, not proof of compatibility.`);
+    return lines.join("\n");
+}

package/dist/reporting/render-mcp-prompt-diff-report.d.ts

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

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

@@ -0,0 +1,48 @@
+import { describePromptLocation } from "./render-mcp-prompt-file-report.js";
+import { quoteServerText } from "./quote-server-text.js";
+export function renderMcpPromptDiffReport(report) {
+    const comparison = report.comparison;
+    return [
+        "Offline MCP Prompt Diff",
+        "=======================",
+        `Status: ${report.status}`,
+        `Scope: ${report.scope}`,
+        `Comparison complete: ${comparison.complete}`,
+        ...(comparison.reason === null ? [] : [`Reason: ${comparison.reason}`]),
+        `Added: ${comparison.added ?? "not compared"}`,
+        `Removed: ${comparison.removed ?? "not compared"}`,
+        `Changed: ${comparison.changed ?? "not compared"}`,
+        `Unchanged: ${comparison.unchanged ?? "not compared"}`,
+        `Breaking: ${comparison.breaking ?? "not compared"}`,
+        `Unclassified: ${comparison.unclassified ?? "not compared"}`,
+        `Comparison coverage: ${report.coverage.comparison}`,
+        `Definition coverage: ${report.coverage.definitions}`,
+        `Compatibility: ${report.coverage.compatibility}`,
+        `Server catalog: ${report.coverage.serverCatalog}`,
+        `Prompt retrieval: ${report.coverage.promptRetrieval}`,
+        `Impact classification: ${report.coverage.impactClassification}`,
+        "Only the supplied responses are compared. Impact labels are argument 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";
+            return [
+                `${label} input: ${source.status}; prompts checked: ${source.inspection.promptsChecked}; bytes read: ${source.source.bytesRead}`,
+                ...(source.inspection.reason === null ? [] : [`${label} reason: ${source.inspection.reason}`]),
+                ...source.findings.map((finding) => {
+                    const locator = finding.location ? ` [${side} ${describePromptLocation(finding.location)}]` : "";
+                    return `${label} ${finding.severity.toUpperCase()} ${finding.id}${locator}: ${finding.message}\n  ${finding.suggestedFix}`;
+                })
+            ];
+        }),
+        ...report.changes.map((change) => {
+            const locations = [
+                ...(change.beforePromptIndex === null ? [] : [`before prompt ${change.beforePromptIndex}`]),
+                ...(change.afterPromptIndex === null ? [] : [`after prompt ${change.afterPromptIndex}`])
+            ];
+            const impact = `${change.impact}${change.reasons.length ? ` (${change.reasons.join(", ")})` : ""}`;
+            const name = change.name === undefined ? "" : ` ${quoteServerText(change.name)}`;
+            const at = (change.locations ?? []).map((location) => `\n  At ${location.argument === null ? "(prompt)" : `argument ${quoteServerText(location.argument)}`}: ${location.reason}`).join("");
+            return `${change.kind.toUpperCase()}${name} [${locations.join(" -> ")}]${change.fields.length ? `: ${change.fields.join(", ")}` : ""}\n  Impact: ${impact}${at}`;
+        })
+    ].join("\n");
+}

package/dist/reporting/render-mcp-prompt-file-report.d.ts

@@ -0,0 +1,5 @@
+import type { PromptCatalogLocation } from "../core/mcp-prompt-definition.js";
+import type { McpPromptFileReport } from "../core/mcp-prompt-file.js";
+/** Describes a finding location by one-based positions only, such as "prompt 2, argument 1, related argument 3". */
+export declare function describePromptLocation(location: PromptCatalogLocation): string;
+export declare function renderMcpPromptFileReport(report: McpPromptFileReport): string;

package/dist/reporting/render-mcp-prompt-file-report.js

@@ -0,0 +1,33 @@
+/** Describes a finding location by one-based positions only, such as "prompt 2, argument 1, related argument 3". */
+export function describePromptLocation(location) {
+    return [
+        `prompt ${location.promptIndex}`,
+        ...(location.argumentIndex === undefined ? [] : [`argument ${location.argumentIndex}`]),
+        ...(location.relatedPromptIndex === undefined ? [] : [`related prompt ${location.relatedPromptIndex}`]),
+        ...(location.relatedArgumentIndex === undefined ? [] : [`related argument ${location.relatedArgumentIndex}`])
+    ].join(", ");
+}
+export function renderMcpPromptFileReport(report) {
+    return [
+        "Offline MCP Prompt Definitions",
+        "==============================",
+        `Status: ${report.status}`,
+        `Scope: ${report.scope}`,
+        `Source: ${report.source.kind} (${report.source.format})`,
+        `Bytes read: ${report.source.bytesRead}`,
+        `Inspection complete: ${report.inspection.complete}`,
+        `Prompts checked: ${report.inspection.promptsChecked}`,
+        `More pages advertised: ${report.inspection.hasNextCursor ?? "unknown"}`,
+        ...(report.inspection.reason === null ? [] : [`Reason: ${report.inspection.reason}`]),
+        `Definition coverage: ${report.coverage.definitions}`,
+        `Discovery: ${report.coverage.discovery}`,
+        `Server catalog: ${report.coverage.serverCatalog}`,
+        `Prompt retrieval: ${report.coverage.promptRetrieval}`,
+        `Full conformance: ${report.coverage.fullConformance}`,
+        "Only the supplied file was inspected. Its provenance and server completeness are not established.",
+        ...report.findings.map((finding) => {
+            const locator = finding.location ? ` [${describePromptLocation(finding.location)}]` : "";
+            return `${finding.severity.toUpperCase()} ${finding.id}${locator}: ${finding.message}\n  ${finding.suggestedFix}`;
+        })
+    ].join("\n");
+}

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

@@ -1,3 +1,4 @@
+import { markdownCodeSpan } from "./quote-server-text.js";
 function count(value) {
     return value === null || value === undefined ? "not compared" : String(value);
 }
@@ -6,6 +7,7 @@ function toolIndex(value) {
 }
 export function renderMcpToolDiffMarkdown(report) {
     const comparison = report.comparison;
+    const named = report.changes.some((change) => change.name !== undefined);
     const lines = [
         "## MCP Tool Definition Diff",
         "",
@@ -16,7 +18,11 @@ export function renderMcpToolDiffMarkdown(report) {
         `| ${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(", ") || "-"} |`));
+        lines.push("", "### Changes", "", named ? "| Change | Tool | Before tool | After tool | Fields | Impact | Reasons |" : "| Change | Before tool | After tool | Fields | Impact | Reasons |", named ? "| --- | --- | --- | --- | --- | --- | --- |" : "| --- | --- | --- | --- | --- | --- |", ...report.changes.map((change) => `| ${change.kind}${named ? ` | ${change.name === undefined ? "-" : markdownCodeSpan(change.name)}` : ""} | ${toolIndex(change.beforeToolIndex)} | ${toolIndex(change.afterToolIndex)} | ${change.fields.map((field) => `\`${field}\``).join(", ") || "-"} | **${change.impact}** | ${change.reasons.map((reason) => `\`${reason}\``).join(", ") || "-"} |`));
+    }
+    const located = report.changes.flatMap((change) => (change.locations ?? []).map((location) => `| ${change.name === undefined ? "-" : markdownCodeSpan(change.name)} | \`${location.reason}\` | ${location.pointer === "" ? "(tool)" : markdownCodeSpan(location.pointer)} |`));
+    if (located.length > 0) {
+        lines.push("", "### Locations", "", "| Tool | Reason | Location |", "| --- | --- | --- |", ...located);
     }
     const findings = ["before", "after"].flatMap((side) => report[side].findings.map((finding) => {
         const location = finding.location;
@@ -28,6 +34,8 @@ export function renderMcpToolDiffMarkdown(report) {
     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.`);
+    lines.push("", named
+        ? `Tool names and schema locations are shown because --show-names was used; schema values are not reported. Impact labels are ${report.coverage.impactClassification} schema checks, not proof of compatibility.`
+        : `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/reporting/render-mcp-tool-diff-report.js

@@ -1,3 +1,4 @@
+import { quoteServerText } from "./quote-server-text.js";
 export function renderMcpToolDiffReport(report) {
     const comparison = report.comparison;
     return [
@@ -39,7 +40,9 @@ export function renderMcpToolDiffReport(report) {
                 ...(change.afterToolIndex === null ? [] : [`after tool ${change.afterToolIndex}`])
             ];
             const impact = `${change.impact}${change.reasons.length ? ` (${change.reasons.join(", ")})` : ""}`;
-            return `${change.kind.toUpperCase()} [${locations.join(" -> ")}]${change.fields.length ? `: ${change.fields.join(", ")}` : ""}\n  Impact: ${impact}`;
+            const name = change.name === undefined ? "" : ` ${quoteServerText(change.name)}`;
+            const at = (change.locations ?? []).map((location) => `\n  At ${location.pointer === "" ? "(tool)" : quoteServerText(location.pointer)}: ${location.reason}`).join("");
+            return `${change.kind.toUpperCase()}${name} [${locations.join(" -> ")}]${change.fields.length ? `: ${change.fields.join(", ")}` : ""}\n  Impact: ${impact}${at}`;
         })
     ].join("\n");
 }

package/dist/run-cli.d.ts

@@ -1,6 +1,9 @@
 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 { captureMcpPromptCatalog, captureStdioMcpPromptCatalog } from "./core/mcp-prompt-catalog.js";
+import { compareMcpPromptFiles } from "./core/mcp-prompt-diff.js";
+import { inspectMcpPromptFile } from "./core/mcp-prompt-file.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";
@@ -23,6 +26,10 @@ export interface RunCliOptions {
     inspectMcpToolCatalogImpl?: typeof inspectMcpToolCatalog;
     captureMcpToolCatalogImpl?: typeof captureMcpToolCatalog;
     captureStdioMcpToolCatalogImpl?: typeof captureStdioMcpToolCatalog;
+    compareMcpPromptFilesImpl?: typeof compareMcpPromptFiles;
+    inspectMcpPromptFileImpl?: typeof inspectMcpPromptFile;
+    captureMcpPromptCatalogImpl?: typeof captureMcpPromptCatalog;
+    captureStdioMcpPromptCatalogImpl?: typeof captureStdioMcpPromptCatalog;
     discoverMcpServerImpl?: typeof discoverMcpServer;
     terminalContext?: CliTerminalContext;
     runCheckImpl?: typeof runCheck;