codex-plugin-doctor 1.76.0 → 1.78.0

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

@@ -0,0 +1,93 @@
+export const PROMPT_CHANGE_REASONS = [
+    "prompt-removed",
+    "prompt-argument-removed",
+    "prompt-required-argument-added",
+    "prompt-argument-now-required",
+    "prompt-argument-fields-unclassified",
+    "other-fields-unclassified"
+];
+export const MAX_PROMPT_CHANGE_LOCATIONS = 100;
+const UNCLASSIFIED_REASONS = new Set(["prompt-argument-fields-unclassified", "other-fields-unclassified"]);
+// Argument fields with a classified effect; a change to any other argument field is unclassified.
+const CLASSIFIED_ARGUMENT_FIELDS = new Set(["name", "title", "description", "required"]);
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Arguments by name, in list order; null when the list is not one of uniquely named argument objects.
+function argumentsByName(value) {
+    if (value === undefined)
+        return new Map();
+    if (!Array.isArray(value))
+        return null;
+    const byName = new Map();
+    for (const argument of value) {
+        if (!isJsonObject(argument) || typeof argument.name !== "string" || byName.has(argument.name))
+            return null;
+        byName.set(argument.name, argument);
+    }
+    return byName;
+}
+function unclassifiedFields(argument) {
+    const fields = Object.create(null);
+    for (const key of Object.keys(argument)) {
+        if (!CLASSIFIED_ARGUMENT_FIELDS.has(key))
+            fields[key] = argument[key];
+    }
+    return fields;
+}
+function classifyArguments(before, after, equal, add) {
+    const beforeArguments = argumentsByName(before);
+    const afterArguments = argumentsByName(after);
+    // Inspected definitions always have readable arguments; anything else cannot be compared by name.
+    if (beforeArguments === null || afterArguments === null) {
+        add("prompt-argument-fields-unclassified", null);
+        return;
+    }
+    for (const [name, beforeArgument] of beforeArguments) {
+        const afterArgument = afterArguments.get(name);
+        if (afterArgument === undefined) {
+            add("prompt-argument-removed", name);
+            continue;
+        }
+        if (beforeArgument.required !== true && afterArgument.required === true)
+            add("prompt-argument-now-required", name);
+        if (!equal(unclassifiedFields(beforeArgument), unclassifiedFields(afterArgument)))
+            add("prompt-argument-fields-unclassified", name);
+    }
+    for (const [name, afterArgument] of afterArguments) {
+        if (!beforeArguments.has(name) && afterArgument.required === true)
+            add("prompt-required-argument-added", name);
+    }
+}
+function result(reasons, locations) {
+    const ordered = PROMPT_CHANGE_REASONS.filter((reason) => reasons.has(reason));
+    const impact = ordered.some((reason) => !UNCLASSIFIED_REASONS.has(reason))
+        ? "breaking"
+        : ordered.length > 0 ? "unclassified" : "compatible";
+    return locations === null ? { impact, reasons: ordered } : { impact, reasons: ordered, locations };
+}
+export function classifyRemovedPrompt() {
+    return { impact: "breaking", reasons: ["prompt-removed"] };
+}
+export function classifyAddedPrompt() {
+    return { impact: "compatible", reasons: [] };
+}
+export function classifyChangedPrompt(before, after, fields, equal, options = {}) {
+    const reasons = new Set();
+    // In comparison order: arguments in before order, then added arguments, then the prompt itself.
+    const locations = options.locate ? [] : null;
+    const seen = new Set();
+    const add = (reason, argument) => {
+        reasons.add(reason);
+        const key = JSON.stringify([reason, argument]);
+        if (locations !== null && locations.length < MAX_PROMPT_CHANGE_LOCATIONS && !seen.has(key)) {
+            seen.add(key);
+            locations.push({ reason, argument });
+        }
+    };
+    if (fields.includes("arguments"))
+        classifyArguments(before.arguments, after.arguments, equal, add);
+    if (fields.includes("other"))
+        add("other-fields-unclassified", null);
+    return result(reasons, locations);
+}

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

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
-import type { RuntimeSandboxMode } from "../domain/types.js";
-import { type McpToolCatalogSnapshot } from "./mcp-tool-catalog.js";
+import type { Finding, RuntimeExecutionEvidence, RuntimeSandboxMode } from "../domain/types.js";
+import { type McpCatalogCapture, type McpCatalogList, type McpToolCatalogProtocol, type McpToolCatalogSnapshot } from "./mcp-tool-catalog.js";
 export interface McpStdioServer {
     packageRoot: string;
     command: string;
@@ -28,5 +28,11 @@ export interface McpStdioToolCatalogOptions {
         shutdownMs?: number;
     };
 }
-export declare function resolveMcpStdioServer(targetPath: string, serverName: string): Promise<McpStdioServerResolution>;
+export declare function resolveMcpStdioServer(targetPath: string, serverName: string, command?: "tools" | "prompts"): Promise<McpStdioServerResolution>;
 export declare function captureStdioMcpToolCatalog(server: McpStdioServer, options?: McpStdioToolCatalogOptions): Promise<McpToolCatalogSnapshot>;
+export interface McpStdioCatalogCapture<F extends Finding> {
+    capture: McpCatalogCapture<F>;
+    protocol: McpToolCatalogProtocol;
+    execution: RuntimeExecutionEvidence | null;
+}
+export declare function captureStdioMcpCatalog<F extends Finding>(server: McpStdioServer, list: McpCatalogList<F>, options?: McpStdioToolCatalogOptions): Promise<McpStdioCatalogCapture<F>>;

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

@@ -5,7 +5,7 @@ import path from "node:path";
 import { packageVersion } from "../version.js";
 import { normalizeMcpConfig } from "./mcp-config-normalizer.js";
 import { classifyMcpDiscoverMessage, serializeMcpDiscoverRequest } from "./mcp-discovery.js";
-import { buildMcpToolCatalogReport, catalogFinding, createMcpToolCatalogInspector, finalCatalogStatus, hasMatchingEnvelope, MAX_CATALOG_PAGES, MAX_CATALOG_RESPONSE_BYTES, MAX_CATALOG_TOTAL_RESPONSE_BYTES, parseToolsResult, serializeToolsListRequest, validJsonRpcError } from "./mcp-tool-catalog.js";
+import { buildMcpToolCatalogReport, catalogFinding, finalCatalogStatus, hasMatchingEnvelope, listCursorLoop, listMethodUnsupported, listResponseInvalid, MAX_CATALOG_PAGES, MAX_CATALOG_RESPONSE_BYTES, MAX_CATALOG_TOTAL_RESPONSE_BYTES, MCP_TOOLS_LIST, modernInvalidFix, parseListResult, serializeListRequest, validJsonRpcError } from "./mcp-tool-catalog.js";
 import { resolveContainedPackagePath } from "./package-path.js";
 import { readJsonFile } from "./read-json-file.js";
 import { cleanupDockerContainer, resolveRuntimeCwd } from "./runtime-probe.js";
@@ -13,7 +13,7 @@ import { buildRuntimeLaunch, DOCKER_RUNTIME_STARTUP_TIMEOUT_MS, RuntimeSandboxEr
 const MODERN_VERSION = "2026-07-28";
 const LEGACY_REQUEST_VERSION = "2025-11-25";
 const LEGACY_VERSIONS = new Set(["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25"]);
-// Legacy tools/list results carry no cache metadata; saved responses use the most conservative values.
+// Legacy list results carry no cache metadata; saved responses use the most conservative values.
 const LEGACY_CACHE = { ttlMs: 0, cacheScope: "private" };
 const NATIVE_STARTUP_TIMEOUT_MS = 10_000;
 const REQUEST_TIMEOUT_MS = 5_000;
@@ -56,7 +56,7 @@ async function readManifestMcpServers(rootPath) {
 }
 // Reads the server the same way runtime planning does: the manifest mcpServers file first,
 // then .mcp.json for packages without one. Messages never echo paths or configured values.
-export async function resolveMcpStdioServer(targetPath, serverName) {
+export async function resolveMcpStdioServer(targetPath, serverName, command = "tools") {
     let packageRoot;
     try {
         packageRoot = await realpath(path.resolve(targetPath));
@@ -104,7 +104,7 @@ export async function resolveMcpStdioServer(targetPath, serverName) {
         return failure("The named MCP server is not in the package configuration.");
     const config = normalized.servers[serverName];
     if (typeof config.url === "string") {
-        return failure("The named MCP server uses HTTP. Run doctor tools <url> --allow-network for HTTP servers.");
+        return failure(`The named MCP server uses HTTP. Run doctor ${command} <url> --allow-network for HTTP servers.`);
     }
     if (typeof config.command !== "string" || config.command.length === 0) {
         return failure("The named MCP server has no command to start.");
@@ -312,10 +312,10 @@ const legacyImpact = "Clients that only support modern MCP versions cannot use t
 const legacyFix = "Implement server/discover and per-request metadata for MCP 2026-07-28 to support modern clients.";
 const stdoutInvalidImpact = "stdio clients cannot reliably read replies when stdout carries anything other than newline-delimited JSON-RPC messages.";
 const stdoutInvalidFix = "Write only MCP messages to stdout and send logs to stderr.";
-function stopFinding(reason, docker) {
+function stopFinding(reason, docker, noun) {
     switch (reason) {
         case "startup-failed":
-            return discoveryFinding("plugin.discovery.stdio.startup_failed", "fail", "The MCP server process could not be started.", "No tool definitions can be read from a server that does not start.", docker
+            return discoveryFinding("plugin.discovery.stdio.startup_failed", "fail", "The MCP server process could not be started.", `No ${noun} definitions can be read from a server that does not start.`, docker
                 ? "Verify Docker is installed and the Docker daemon is available."
                 : "Verify the configured command is installed and runs from the server working directory without a shell.");
         case "stdout-invalid":
@@ -327,29 +327,33 @@ function stopFinding(reason, docker) {
             return discoveryFinding("plugin.discovery.transport.timeout", "fail", "Server discovery did not complete within the inspection time limit.", "The discovery reply cannot be read within the inspection bounds.", "Reduce server startup latency, then inspect again.");
     }
 }
-const modernEra = {
-    request: serializeToolsListRequest,
-    parse: parseToolsResult,
-    invalidFix: "Return a matching JSON-RPC complete result with valid tools and cache metadata."
-};
-const legacyEra = {
-    request: (id, cursor) => JSON.stringify({
-        jsonrpc: "2.0",
-        id,
-        method: "tools/list",
-        ...(cursor === undefined ? {} : { params: { cursor } })
-    }),
-    parse: (message, id) => {
-        if (!hasMatchingEnvelope(message, id) || !Object.hasOwn(message, "result") || !isPlainObject(message.result)
-            || !Array.isArray(message.result.tools)) {
-            return null;
-        }
-        if (Object.hasOwn(message.result, "nextCursor") && typeof message.result.nextCursor !== "string")
-            return null;
-        return { tools: message.result.tools, cursor: message.result.nextCursor, cache: LEGACY_CACHE };
-    },
-    invalidFix: "Return a matching JSON-RPC result with a tools array and an optional string nextCursor."
-};
+function modernEra(list) {
+    return {
+        request: (id, cursor) => serializeListRequest(list.method, id, cursor),
+        parse: (message, id) => parseListResult(message, id, list.capability),
+        invalidFix: modernInvalidFix(list)
+    };
+}
+function legacyEra(list) {
+    return {
+        request: (id, cursor) => JSON.stringify({
+            jsonrpc: "2.0",
+            id,
+            method: list.method,
+            ...(cursor === undefined ? {} : { params: { cursor } })
+        }),
+        parse: (message, id) => {
+            if (!hasMatchingEnvelope(message, id) || !Object.hasOwn(message, "result") || !isPlainObject(message.result)
+                || !Array.isArray(message.result[list.capability])) {
+                return null;
+            }
+            if (Object.hasOwn(message.result, "nextCursor") && typeof message.result.nextCursor !== "string")
+                return null;
+            return { items: message.result[list.capability], cursor: message.result.nextCursor, cache: LEGACY_CACHE };
+        },
+        invalidFix: `Return a matching JSON-RPC result with a ${list.capability} array and an optional string nextCursor.`
+    };
+}
 function legacyInitializeRequest() {
     return JSON.stringify({
         jsonrpc: "2.0",
@@ -374,6 +378,13 @@ function validInitializeResult(message) {
 // Starts one configured stdio server, reads its tool list without calling tools, and stops it.
 // Tools and cache metadata are returned only for a complete enumeration.
 export async function captureStdioMcpToolCatalog(server, options = {}) {
+    const { capture, protocol, execution } = await captureStdioMcpCatalog(server, MCP_TOOLS_LIST, options);
+    const { complete, pagesRead, checked, reason } = capture.catalog;
+    return finish(buildMcpToolCatalogReport(capture.discovery, capture.status, { complete, pagesRead, toolsChecked: checked, reason }, capture.enumeration, capture.findings), protocol, execution, capture.items, capture.cache);
+}
+// Starts one configured stdio server, reads one definition list without using the definitions, and stops it.
+// Definitions and cache metadata are returned only for a complete enumeration.
+export async function captureStdioMcpCatalog(server, list, options = {}) {
     const docker = options.sandbox === "docker";
     const now = options.now ?? (() => performance.now());
     const startupMs = options.timeouts?.startupMs ?? (docker ? DOCKER_RUNTIME_STARTUP_TIMEOUT_MS : NATIVE_STARTUP_TIMEOUT_MS);
@@ -382,7 +393,7 @@ export async function captureStdioMcpToolCatalog(server, options = {}) {
     const deadline = now() + (options.timeouts?.totalMs ?? (docker ? DOCKER_TOTAL_TIMEOUT_MS : NATIVE_TOTAL_TIMEOUT_MS));
     const spawnImpl = options.spawnImpl ?? spawn;
     const removeContainer = options.removeContainerImpl ?? (async (containerName) => await cleanupDockerContainer(containerName) === null);
-    const emptyCatalog = { complete: false, pagesRead: 0, toolsChecked: 0, reason: null };
+    const emptyCatalog = { complete: false, pagesRead: 0, checked: 0, reason: null };
     const buildLaunch = () => docker
         ? buildRuntimeLaunch({
             sandbox: "docker",
@@ -405,8 +416,12 @@ export async function captureStdioMcpToolCatalog(server, options = {}) {
         firstLaunch = buildLaunch();
     }
     catch (error) {
-        const discovery = stdioDiscovery("blocked", "skipped", [discoveryFinding("plugin.discovery.sandbox.unsupported", "warn", error instanceof RuntimeSandboxError ? error.message : "The MCP server cannot run in the requested sandbox.", "The tool catalog was not read because the server cannot be isolated as requested.", "Use a Node.js command inside the package root with --sandbox docker, or review the command before running it without a sandbox.")]);
-        return finish(buildMcpToolCatalogReport(discovery, "blocked", { ...emptyCatalog, reason: "sandbox-unsupported" }, "not-tested", []), { era: null, version: null }, null, null, null);
+        const discovery = stdioDiscovery("blocked", "skipped", [discoveryFinding("plugin.discovery.sandbox.unsupported", "warn", error instanceof RuntimeSandboxError ? error.message : "The MCP server cannot run in the requested sandbox.", `The ${list.noun} catalog was not read because the server cannot be isolated as requested.`, "Use a Node.js command inside the package root with --sandbox docker, or review the command before running it without a sandbox.")]);
+        return {
+            capture: { discovery, status: "blocked", catalog: { ...emptyCatalog, reason: "sandbox-unsupported" }, enumeration: "not-tested", findings: [], items: null, cache: null },
+            protocol: { era: null, version: null },
+            execution: null
+        };
     }
     const started = [];
     let session;
@@ -422,7 +437,7 @@ export async function captureStdioMcpToolCatalog(server, options = {}) {
         return outcome.kind === "timeout" && remaining < timeoutMs ? { kind: "timeout", reason: "total-time-limit" } : outcome;
     };
     const enumerate = async (era, protocol, discovery) => {
-        const inspector = createMcpToolCatalogInspector();
+        const inspector = list.createInspector();
         const findings = inspector.findings;
         const seenCursors = new Set();
         let pagesRead = 0;
@@ -448,7 +463,7 @@ export async function captureStdioMcpToolCatalog(server, options = {}) {
                 reason = "page-limit";
                 break;
             }
-            const id = `tools-list-${pagesRead + 1}`;
+            const id = `${list.capability}-list-${pagesRead + 1}`;
             const outcome = await send(id, era.request(id, cursor), requestMs);
             if (outcome.kind !== "message") {
                 if (outcome.kind === "stopped")
@@ -459,13 +474,13 @@ export async function captureStdioMcpToolCatalog(server, options = {}) {
             }
             const message = outcome.message;
             if (hasMatchingEnvelope(message, id) && Object.hasOwn(message, "error") && validJsonRpcError(message.error) && message.error.code === -32601) {
-                if (addFindings([catalogFinding("plugin.catalog.tools_list.method_unsupported", "warn", "The MCP server advertised tools but does not implement tools/list.", "Tool definitions cannot be enumerated from the advertised capability.", "Implement tools/list for the advertised MCP tools capability.")]))
-                    reason = "tools-list-method-unsupported";
+                if (addFindings([listMethodUnsupported(list, "MCP server")]))
+                    reason = `${list.capability}-list-method-unsupported`;
                 break;
             }
             const page = era.parse(message, id);
             if (page === null) {
-                if (addFindings([catalogFinding("plugin.catalog.response.invalid", "fail", "The MCP server returned an invalid tools/list response.", "The tool catalog cannot be safely enumerated from this response.", era.invalidFix)]))
+                if (addFindings([listResponseInvalid(list, "MCP server", era.invalidFix)]))
                     reason = "response-invalid";
                 break;
             }
@@ -474,13 +489,13 @@ export async function captureStdioMcpToolCatalog(server, options = {}) {
                 ttlMs: Math.min(cache.ttlMs, page.cache.ttlMs),
                 cacheScope: cache.cacheScope === "private" ? "private" : page.cache.cacheScope
             };
-            reason = inspector.inspectPage(page.tools, pagesRead, () => deadline - now() <= 0);
+            reason = inspector.inspectPage(page.items, pagesRead, () => deadline - now() <= 0);
             if (reason !== null)
                 break;
             if (page.cursor === undefined)
                 break;
             if (seenCursors.has(page.cursor)) {
-                if (addFindings([catalogFinding("plugin.catalog.cursor.loop", "warn", "The MCP server 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, "MCP server")]))
                     reason = "cursor-loop";
                 break;
             }
@@ -494,13 +509,13 @@ export async function captureStdioMcpToolCatalog(server, options = {}) {
             sessionStopped(trailingStop);
         if (reason === null && deadline - now() <= 0)
             reason = "total-time-limit";
-        const catalog = { complete: reason === null, pagesRead, toolsChecked: inspector.toolsChecked, reason };
+        const catalog = { complete: reason === null, pagesRead, checked: inspector.checked, reason };
         return reason === null
-            ? { status: finalCatalogStatus(findings), protocol, discovery, catalog, enumeration: "complete", findings, tools: inspector.tools, cache }
-            : { status: "incomplete", protocol, discovery, catalog, enumeration: "incomplete", findings, tools: null, cache: null };
+            ? { status: finalCatalogStatus(findings), protocol, discovery, catalog, enumeration: "complete", findings, items: inspector.items, cache }
+            : { status: "incomplete", protocol, discovery, catalog, enumeration: "incomplete", findings, items: null, cache: null };
     };
     const notTested = (status, reason, protocol, discovery, findings = []) => ({
-        status, protocol, discovery, catalog: { ...emptyCatalog, reason }, enumeration: "not-tested", findings, tools: null, cache: null
+        status, protocol, discovery, catalog: { ...emptyCatalog, reason }, enumeration: "not-tested", findings: findings, items: null, cache: null
     });
     // answeredDiscovery is false when only silence or an exit suggested a legacy server.
     const runLegacy = async (discovery, restart, answeredDiscovery) => {
@@ -516,18 +531,18 @@ export async function captureStdioMcpToolCatalog(server, options = {}) {
         }
         const result = validInitializeResult(outcome.message);
         if (result === null) {
-            return notTested("incomplete", "initialize-failed", unestablished, discovery, [catalogFinding("plugin.catalog.initialize.invalid", "fail", "The MCP server did not complete the legacy initialize handshake.", "The tool catalog cannot be read from a legacy server that does not initialize.", "Return protocolVersion, capabilities, and serverInfo from initialize, or implement server/discover.")]);
+            return notTested("incomplete", "initialize-failed", unestablished, discovery, [catalogFinding("plugin.catalog.initialize.invalid", "fail", "The MCP server did not complete the legacy initialize handshake.", `The ${list.noun} catalog cannot be read from a legacy server that does not initialize.`, "Return protocolVersion, capabilities, and serverInfo from initialize, or implement server/discover.")]);
         }
         const version = result.protocolVersion;
         if (!LEGACY_VERSIONS.has(version)) {
-            return notTested("unsupported", "protocol-version-unsupported", unknownVersion, discovery, [catalogFinding("plugin.catalog.initialize.version_unsupported", "warn", "The MCP server negotiated a legacy protocol version this inspection does not support.", "The tool catalog was not read because the negotiated version is unknown to this inspection.", "Support MCP 2025-11-25 or MCP 2026-07-28.")]);
+            return notTested("unsupported", "protocol-version-unsupported", unknownVersion, discovery, [catalogFinding("plugin.catalog.initialize.version_unsupported", "warn", "The MCP server negotiated a legacy protocol version this inspection does not support.", `The ${list.noun} catalog was not read because the negotiated version is unknown to this inspection.`, "Support MCP 2025-11-25 or MCP 2026-07-28.")]);
         }
         const protocol = { era: "legacy", version };
         session.notify(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }));
         const capabilities = result.capabilities;
-        if (!isPlainObject(capabilities.tools))
+        if (!isPlainObject(capabilities[list.capability]))
             return notTested("not-applicable", null, protocol, discovery);
-        return enumerate(legacyEra, protocol, discovery);
+        return enumerate(legacyEra(list), protocol, discovery);
     };
     const run = async () => {
         start(firstLaunch);
@@ -539,7 +554,7 @@ export async function captureStdioMcpToolCatalog(server, options = {}) {
         }
         if (probe.kind !== "message") {
             const reason = probe.reason;
-            return notTested("incomplete", reason, undetermined, stdioDiscovery("failed", "fail", [stopFinding(reason, docker)]));
+            return notTested("incomplete", reason, undetermined, stdioDiscovery("failed", "fail", [stopFinding(reason, docker, list.noun)]));
         }
         const outcome = classifyMcpDiscoverMessage(probe.message, DISCOVER_ID);
         const modernUnknown = { era: "modern", version: null };
@@ -557,9 +572,9 @@ export async function captureStdioMcpToolCatalog(server, options = {}) {
             case "discovered": {
                 const discovery = stdioDiscovery("discovered", "pass", [], outcome.supportedVersions);
                 const protocol = { era: "modern", version: MODERN_VERSION };
-                if (!Object.hasOwn(outcome.capabilities, "tools"))
+                if (!Object.hasOwn(outcome.capabilities, list.capability))
                     return notTested("not-applicable", null, protocol, discovery);
-                return enumerate(modernEra, protocol, discovery);
+                return enumerate(modernEra(list), protocol, discovery);
             }
         }
     };
@@ -577,14 +592,18 @@ export async function captureStdioMcpToolCatalog(server, options = {}) {
             }
         }
     }
+    // Findings without a location fit every catalog finding type.
     const findings = result.findings;
     if (cleanupFailed && findings.length < 100) {
-        findings.push(catalogFinding("plugin.catalog.stdio.sandbox_cleanup_failed", "fail", "The Docker runtime container could not be removed after reading the tool list.", "A leftover runtime container weakens cleanup guarantees and may continue consuming local resources.", "Verify the Docker daemon is available, then remove the codex-doctor container."));
+        findings.push(catalogFinding("plugin.catalog.stdio.sandbox_cleanup_failed", "fail", `The Docker runtime container could not be removed after reading the ${list.noun} list.`, "A leftover runtime container weakens cleanup guarantees and may continue consuming local resources.", "Verify the Docker daemon is available, then remove the codex-doctor container."));
     }
-    const complete = result.tools !== null;
-    const status = complete ? finalCatalogStatus(findings) : result.status;
-    const execution = started.some((entry) => entry.session.spawned) ? firstLaunch.evidence : null;
-    return finish(buildMcpToolCatalogReport(result.discovery, status, result.catalog, result.enumeration, findings), result.protocol, execution, result.tools, result.cache);
+    const complete = result.items !== null;
+    const { protocol, ...capture } = result;
+    return {
+        capture: { ...capture, status: complete ? finalCatalogStatus(findings) : result.status },
+        protocol,
+        execution: started.some((entry) => entry.session.spawned) ? firstLaunch.evidence : null
+    };
 }
 function finish(report, protocol, execution, tools, cache) {
     const { schemaVersion, scope, status, discovery, catalog, coverage, findings } = report;

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

@@ -2,7 +2,7 @@ import { type McpDiscoveryReport, type McpJsonObject } from "./mcp-discovery.js"
 import { type CatalogFinding } from "./mcp-tool-definition.js";
 import { type RemoteLookup } from "./remote-network-policy.js";
 import type { RemoteMcpRequest } from "./remote-mcp-probe.js";
-import type { RuntimeExecutionEvidence } from "../domain/types.js";
+import type { Finding, RuntimeExecutionEvidence } from "../domain/types.js";
 export declare const MAX_CATALOG_PAGES = 5;
 export declare const MAX_CATALOG_RESPONSE_BYTES: number;
 export declare const MAX_CATALOG_TOTAL_RESPONSE_BYTES: number;
@@ -59,13 +59,19 @@ export declare function validJsonRpcError(value: unknown): value is McpJsonObjec
     message: string;
 };
 export declare function hasMatchingEnvelope(message: McpJsonObject, requestId: string): boolean;
-export declare function parseToolsResult(message: McpJsonObject, requestId: string): {
-    tools: unknown[];
+export declare function parseListResult(message: McpJsonObject, requestId: string, resultKey: McpCatalogList<Finding>["capability"]): {
+    items: unknown[];
     cursor: string | undefined;
     cache: McpToolCatalogCache;
 } | null;
 export declare function buildMcpToolCatalogReport(discovery: McpDiscoveryReport, status: CatalogStatus, catalog: McpToolCatalogReport["catalog"], catalogEnumeration: EnumerationCoverage, findings: CatalogFinding[]): McpToolCatalogReport;
-export declare function finalCatalogStatus(findings: CatalogFinding[]): "pass" | "warn" | "fail";
+export declare function finalCatalogStatus(findings: Finding[]): "pass" | "warn" | "fail";
+type CatalogListName = Pick<McpCatalogList<Finding>, "method" | "capability" | "noun">;
+type CatalogServer = "endpoint" | "MCP server";
+export declare function listMethodUnsupported(list: CatalogListName, server: CatalogServer): CatalogFinding;
+export declare function modernInvalidFix(list: CatalogListName): string;
+export declare function listResponseInvalid(list: CatalogListName, server: CatalogServer, suggestedFix: string): CatalogFinding;
+export declare function listCursorLoop(list: CatalogListName, server: CatalogServer): CatalogFinding;
 export interface McpToolCatalogInspector {
     readonly findings: CatalogFinding[];
     readonly tools: unknown[];
@@ -74,6 +80,39 @@ export interface McpToolCatalogInspector {
     inspectPage(pageTools: unknown[], page: number, timeExpired: () => boolean): "tool-limit" | "finding-limit" | "total-time-limit" | null;
 }
 export declare function createMcpToolCatalogInspector(): McpToolCatalogInspector;
-export declare function serializeToolsListRequest(id: string, cursor: string | undefined): string;
+/** A catalog page inspector for one kind of definition, shaped like the tool and prompt inspectors. */
+export interface McpCatalogInspector<F extends Finding> {
+    readonly findings: F[];
+    readonly items: unknown[];
+    readonly checked: number;
+    addFindings(items: Finding[]): boolean;
+    inspectPage(items: unknown[], page: number, timeExpired: () => boolean): string | null;
+}
+/** What differs between enumerating tool and prompt definitions; discovery, limits, paging, and findings are shared. */
+export interface McpCatalogList<F extends Finding> {
+    method: "tools/list" | "prompts/list";
+    capability: "tools" | "prompts";
+    noun: "tool" | "prompt";
+    createInspector(): McpCatalogInspector<F>;
+}
+export declare const MCP_TOOLS_LIST: McpCatalogList<CatalogFinding>;
+/** A capture before it is shaped into a tool or prompt catalog report. */
+export interface McpCatalogCapture<F extends Finding> {
+    discovery: McpDiscoveryReport;
+    status: CatalogStatus;
+    catalog: {
+        complete: boolean;
+        pagesRead: number;
+        checked: number;
+        reason: string | null;
+    };
+    enumeration: EnumerationCoverage;
+    findings: F[];
+    items: unknown[] | null;
+    cache: McpToolCatalogCache | null;
+}
+export declare function serializeListRequest(method: McpCatalogList<Finding>["method"], id: string, cursor: string | undefined): string;
 export declare function inspectMcpToolCatalog(rawUrl: string, options?: McpToolCatalogOptions): Promise<McpToolCatalogReport>;
 export declare function captureMcpToolCatalog(rawUrl: string, options?: McpToolCatalogOptions): Promise<McpToolCatalogSnapshot>;
+export declare function captureMcpCatalog<F extends Finding>(rawUrl: string, list: McpCatalogList<F>, options?: McpToolCatalogOptions): Promise<McpCatalogCapture<F>>;
+export {};