codex-plugin-doctor 1.61.0 → 1.62.0

package/README.md

@@ -96,6 +96,20 @@ response, not full protocol conformance, tool behavior, or compatibility with a
 particular client. Existing `check --runtime` remains on its 2025-11-25 baseline.
 See [MCP Discovery](docs/guides/mcp-discovery.md) for consent, scope, and exit codes.
 
+### HTTP MCP Tool Catalog
+
+Inspect a modern HTTP MCP server's tool definitions without invoking them:
+
+```bash
+codex-plugin-doctor doctor tools https://mcp.example.com/mcp --allow-network --json
+```
+
+This opt-in command performs discovery and bounded `tools/list` pagination. It
+reports tool-definition and root-schema shape findings, explicit completion state,
+and partial inspection limits. It does not claim full schema validation, tool
+execution, or client compatibility. Existing `doctor discover` behavior is unchanged.
+See [HTTP MCP Tool Catalog](docs/guides/mcp-tool-catalog.md).
+
 ### Remote MCP Readiness
 
 Remote MCP runtime probing is disabled until you explicitly pass `--runtime --allow-network`. Loopback endpoints also require `--allow-local-network`:
@@ -514,9 +528,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.61.0
+      - uses: Esquetta/CodexPluginDoctor@v1.62.0
         with:
-          version: "1.61.0"
+          version: "1.62.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/mcp-discovery.d.ts

@@ -1,6 +1,8 @@
+import { type BoundedHttpResponse } from "./bounded-http-client.js";
 import { type RemoteLookup } from "./remote-network-policy.js";
 import type { RemoteMcpRequest } from "./remote-mcp-probe.js";
 import type { Finding } from "../domain/types.js";
+export type McpJsonObject = Record<string, unknown>;
 export interface McpDiscoveryOptions {
     allowNetwork?: boolean;
     allowLocalNetwork?: boolean;
@@ -20,4 +22,7 @@ export interface McpDiscoveryReport {
         runtime: "not-tested";
     };
 }
+export declare function findMcpSseResponse(body: Buffer, requestId?: string): McpJsonObject | null;
+export declare function parseMcpResponse(response: BoundedHttpResponse, requestId?: string): McpJsonObject | null;
+export declare function discoverMcpCapabilities(response: BoundedHttpResponse, requestId?: string): McpJsonObject | null;
 export declare function discoverMcpServer(rawUrl: string, options?: McpDiscoveryOptions): Promise<McpDiscoveryReport>;

package/dist/core/mcp-discovery.js

@@ -27,7 +27,7 @@ function mediaType(response) {
     const value = Array.isArray(contentType) ? contentType[0] : contentType;
     return typeof value === "string" ? value.split(";", 1)[0]?.trim().toLowerCase() ?? null : null;
 }
-function findSseResponse(body) {
+export function findMcpSseResponse(body, requestId = REQUEST_ID) {
     const text = body.toString("utf8").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
     let offset = 0;
     while (offset < text.length) {
@@ -38,16 +38,16 @@ function findSseResponse(body) {
             .filter((line) => line.startsWith("data:"))
             .map((line) => line.slice(5).replace(/^ /, ""));
         const candidate = data.length === 0 ? null : parseJsonObject(data.join("\n"));
-        if (candidate?.id === REQUEST_ID)
+        if (candidate?.id === requestId)
             return candidate;
         offset = boundary + 2;
     }
     return null;
 }
-function parseResponse(response) {
+export function parseMcpResponse(response, requestId = REQUEST_ID) {
     const contentType = mediaType(response);
     return contentType === "application/json" ? parseJsonObject(response.body.toString("utf8"))
-        : contentType === "text/event-stream" ? findSseResponse(response.body)
+        : contentType === "text/event-stream" ? findMcpSseResponse(response.body, requestId)
             : null;
 }
 function isValidVersion(value) {
@@ -60,8 +60,8 @@ function isValidVersion(value) {
 function validVersions(value) {
     return Array.isArray(value) && value.length > 0 && value.length <= 32 && value.every(isValidVersion) && new Set(value).size === value.length;
 }
-function hasMatchingResponseEnvelope(message) {
-    return message.jsonrpc === "2.0" && message.id === REQUEST_ID
+function hasMatchingResponseEnvelope(message, requestId = REQUEST_ID) {
+    return message.jsonrpc === "2.0" && message.id === requestId
         && Object.hasOwn(message, "result") !== Object.hasOwn(message, "error");
 }
 function validDiscoverResult(value) {
@@ -89,6 +89,19 @@ function unsupportedVersions(error) {
         return null;
     return error.data.requested === REQUESTED_VERSION && validVersions(error.data.supported) ? error.data.supported : null;
 }
+export function discoverMcpCapabilities(response, requestId = REQUEST_ID) {
+    const message = parseMcpResponse(response, requestId);
+    if (!message || !hasMatchingResponseEnvelope(message, requestId) || !Object.hasOwn(message, "result")) {
+        return null;
+    }
+    const result = message.result;
+    if (!validDiscoverResult(result))
+        return null;
+    const capabilities = result.capabilities;
+    if (!isPlainObject(capabilities))
+        return null;
+    return result.supportedVersions.includes(REQUESTED_VERSION) ? capabilities : null;
+}
 function failureReport(id, message) {
     return report("failed", "fail", [finding(id, "fail", message, "The discovery response cannot safely establish modern MCP discovery support.", "Verify the endpoint returns a valid server/discover response for the requested protocol version.")]);
 }
@@ -114,7 +127,7 @@ export async function discoverMcpServer(rawUrl, options = {}) {
             allowLocalNetwork: options.allowLocalNetwork, lookup: options.lookup, timeoutMs: options.requestTimeoutMs,
             method: "POST", body,
             headers: { Accept: "application/json, text/event-stream", "Content-Type": "application/json", "MCP-Protocol-Version": REQUESTED_VERSION, "Mcp-Method": "server/discover" },
-            stopAfter: (received) => findSseResponse(received) !== null
+            stopAfter: (received) => findMcpSseResponse(received) !== null
         });
     }
     catch (error) {
@@ -126,7 +139,7 @@ export async function discoverMcpServer(rawUrl, options = {}) {
     if (response.statusCode === 401 || response.statusCode === 403) {
         return unsupportedReport("plugin.discovery.authorization.required", "The MCP endpoint requires authorization before discovery can be assessed.");
     }
-    const message = parseResponse(response);
+    const message = parseMcpResponse(response);
     if (!message || !hasMatchingResponseEnvelope(message))
         return failureReport("plugin.discovery.response.invalid", "The MCP endpoint returned an invalid discovery response.");
     if (Object.hasOwn(message, "error")) {

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

@@ -0,0 +1,36 @@
+import { type McpDiscoveryReport } 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";
+type CatalogStatus = "pass" | "warn" | "fail" | "unsupported" | "not-applicable" | "incomplete" | "blocked";
+type EnumerationCoverage = "complete" | "incomplete" | "not-tested";
+export interface McpToolCatalogOptions {
+    allowNetwork?: boolean;
+    allowLocalNetwork?: boolean;
+    lookup?: RemoteLookup;
+    request?: RemoteMcpRequest;
+    now?: () => number;
+}
+export interface McpToolCatalogReport {
+    schemaVersion: 1;
+    scope: "tool-catalog-structure";
+    status: CatalogStatus;
+    discovery: McpDiscoveryReport;
+    catalog: {
+        complete: boolean;
+        pagesRead: number;
+        toolsChecked: number;
+        reason: string | null;
+    };
+    coverage: {
+        discovery: "pass" | "fail" | "skipped";
+        catalogEnumeration: EnumerationCoverage;
+        schema: "root-shape-only";
+        toolExecution: "not-tested";
+        fullConformance: "not-tested";
+        customHeaderAnnotations: "not-tested";
+    };
+    findings: CatalogFinding[];
+}
+export declare function inspectMcpToolCatalog(rawUrl: string, options?: McpToolCatalogOptions): Promise<McpToolCatalogReport>;
+export {};

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

@@ -0,0 +1,276 @@
+import { BoundedHttpError, requestBoundedHttp } from "./bounded-http-client.js";
+import { discoverMcpCapabilities, discoverMcpServer, findMcpSseResponse, parseMcpResponse } from "./mcp-discovery.js";
+import { inspectMcpToolDefinition } from "./mcp-tool-definition.js";
+import { RemoteNetworkPolicyError } from "./remote-network-policy.js";
+import { packageVersion } from "../version.js";
+const REQUESTED_VERSION = "2026-07-28";
+const MAX_PAGES = 5;
+const MAX_TOOLS = 500;
+const MAX_FINDINGS = 100;
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+const MAX_TOTAL_RESPONSE_BYTES = 4 * 1024 * 1024;
+const REQUEST_TIMEOUT_MS = 3_000;
+const TOTAL_TIMEOUT_MS = 15_000;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function finding(id, severity, message, impact, suggestedFix) {
+    return { id, severity, message, impact, suggestedFix };
+}
+function validError(value) {
+    return isPlainObject(value) && typeof value.code === "number" && Number.isFinite(value.code) && typeof value.message === "string";
+}
+function validCacheMetadata(value) {
+    return value.resultType === "complete"
+        && typeof value.ttlMs === "number" && Number.isFinite(value.ttlMs) && value.ttlMs >= 0
+        && (value.cacheScope === "public" || value.cacheScope === "private");
+}
+function hasMatchingEnvelope(message, requestId) {
+    return message.jsonrpc === "2.0" && message.id === requestId
+        && Object.hasOwn(message, "result") !== Object.hasOwn(message, "error");
+}
+function parseToolsResult(message, requestId) {
+    if (!hasMatchingEnvelope(message, requestId)) {
+        return null;
+    }
+    if (!Object.hasOwn(message, "result") || !isPlainObject(message.result) || !validCacheMetadata(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 };
+}
+function catalogReport(discovery, status, catalog, catalogEnumeration, findings) {
+    return {
+        schemaVersion: 1,
+        scope: "tool-catalog-structure",
+        status,
+        discovery,
+        catalog,
+        coverage: {
+            discovery: discovery.coverage.discovery,
+            catalogEnumeration,
+            schema: "root-shape-only",
+            toolExecution: "not-tested",
+            fullConformance: "not-tested",
+            customHeaderAnnotations: "not-tested"
+        },
+        findings
+    };
+}
+function finalStatus(findings) {
+    return findings.some((item) => item.severity === "fail")
+        ? "fail"
+        : findings.some((item) => item.severity === "warn")
+            ? "warn"
+            : "pass";
+}
+function isAuthorizationFinding(discovery) {
+    return discovery.findings.some((item) => item.id === "plugin.discovery.authorization.required");
+}
+function requestBody(id, cursor) {
+    return JSON.stringify({
+        jsonrpc: "2.0",
+        id,
+        method: "tools/list",
+        params: {
+            ...(cursor === undefined ? {} : { cursor }),
+            _meta: {
+                "io.modelcontextprotocol/protocolVersion": REQUESTED_VERSION,
+                "io.modelcontextprotocol/clientInfo": { name: "Codex Plugin Doctor", version: packageVersion },
+                "io.modelcontextprotocol/clientCapabilities": {}
+            }
+        }
+    });
+}
+export async function inspectMcpToolCatalog(rawUrl, options = {}) {
+    const request = options.request ?? requestBoundedHttp;
+    const now = options.now ?? (() => performance.now());
+    const deadline = now() + TOTAL_TIMEOUT_MS;
+    let receivedBytes = 0;
+    let budgetReason = null;
+    const requestWithinBudget = async (url, requestOptions = {}) => {
+        const remainingTime = deadline - now();
+        const remainingBytes = MAX_TOTAL_RESPONSE_BYTES - receivedBytes;
+        const timeoutMs = Math.floor(Math.min(REQUEST_TIMEOUT_MS, remainingTime));
+        if (timeoutMs < 1) {
+            budgetReason = "total-time-limit";
+            throw new BoundedHttpError("REMOTE_HTTP_TIMEOUT", "Catalog time budget exhausted.");
+        }
+        if (remainingBytes <= 0) {
+            budgetReason = "total-response-byte-limit";
+            throw new BoundedHttpError("REMOTE_HTTP_RESPONSE_TOO_LARGE", "Catalog response byte budget exhausted.");
+        }
+        const maxResponseBytes = Math.min(MAX_RESPONSE_BYTES, remainingBytes);
+        const response = await request(url, {
+            ...requestOptions,
+            timeoutMs,
+            maxResponseBytes
+        });
+        receivedBytes += response.body.length;
+        if (response.body.length > maxResponseBytes) {
+            budgetReason = receivedBytes > MAX_TOTAL_RESPONSE_BYTES ? "total-response-byte-limit" : "response-byte-limit";
+            throw new BoundedHttpError("REMOTE_HTTP_RESPONSE_TOO_LARGE", "Catalog response exceeded the byte budget.");
+        }
+        return response;
+    };
+    let discoveryResponse = null;
+    const discovery = await discoverMcpServer(rawUrl, {
+        allowNetwork: options.allowNetwork,
+        allowLocalNetwork: options.allowLocalNetwork,
+        lookup: options.lookup,
+        request: async (url, requestOptions) => {
+            const response = await requestWithinBudget(url, requestOptions);
+            discoveryResponse = response;
+            return response;
+        }
+    });
+    const emptyCatalog = { complete: false, pagesRead: 0, toolsChecked: 0, reason: null };
+    if (discovery.status === "blocked") {
+        return catalogReport(discovery, "blocked", { ...emptyCatalog, reason: "network-blocked" }, "not-tested", []);
+    }
+    if (isAuthorizationFinding(discovery)) {
+        return catalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "authorization-required" }, "not-tested", []);
+    }
+    if (discovery.status === "unsupported") {
+        return catalogReport(discovery, "unsupported", { ...emptyCatalog, reason: "discovery-unsupported" }, "not-tested", []);
+    }
+    if (discovery.status !== "discovered") {
+        return catalogReport(discovery, "incomplete", { ...emptyCatalog, reason: budgetReason ?? "discovery-failed" }, "not-tested", []);
+    }
+    const capabilities = discoveryResponse === null ? null : discoverMcpCapabilities(discoveryResponse);
+    if (capabilities === null) {
+        return catalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "discovery-response-unavailable" }, "not-tested", []);
+    }
+    if (!Object.hasOwn(capabilities, "tools")) {
+        return catalogReport(discovery, "not-applicable", emptyCatalog, "not-tested", []);
+    }
+    const findings = [];
+    const names = new Map();
+    const seenCursors = new Set();
+    let pagesRead = 0;
+    let toolsChecked = 0;
+    let cursor;
+    let incompleteReason = null;
+    let blocked = false;
+    const addFindings = (items) => {
+        if (findings.length + items.length > MAX_FINDINGS) {
+            findings.push(...items.slice(0, MAX_FINDINGS - findings.length));
+            incompleteReason = "finding-limit";
+            return false;
+        }
+        findings.push(...items);
+        return true;
+    };
+    while (incompleteReason === null && !blocked) {
+        if (pagesRead >= MAX_PAGES) {
+            incompleteReason = "page-limit";
+            break;
+        }
+        if (Math.floor(deadline - now()) < 1) {
+            incompleteReason = "total-time-limit";
+            break;
+        }
+        const requestId = `tools-list-${pagesRead + 1}`;
+        let response;
+        try {
+            response = await requestWithinBudget(rawUrl, {
+                allowLocalNetwork: options.allowLocalNetwork,
+                lookup: options.lookup,
+                method: "POST",
+                body: requestBody(requestId, cursor),
+                headers: {
+                    Accept: "application/json, text/event-stream",
+                    "Content-Type": "application/json",
+                    "MCP-Protocol-Version": REQUESTED_VERSION,
+                    "Mcp-Method": "tools/list"
+                },
+                stopAfter: (received) => findMcpSseResponse(received, requestId) !== null
+            });
+        }
+        catch (error) {
+            if (error instanceof RemoteNetworkPolicyError) {
+                blocked = true;
+            }
+            else {
+                incompleteReason = budgetReason ?? (error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_TIMEOUT"
+                    ? "request-timeout"
+                    : error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_RESPONSE_TOO_LARGE"
+                        ? "response-byte-limit"
+                        : "request-failed");
+            }
+            break;
+        }
+        if (response.statusCode === 401 || response.statusCode === 403) {
+            incompleteReason = "authorization-required";
+            break;
+        }
+        const message = parseMcpResponse(response, requestId);
+        if (message !== null && hasMatchingEnvelope(message, requestId) && Object.hasOwn(message, "error")
+            && validError(message.error) && message.error.code === -32601 && (response.statusCode === 200 || response.statusCode === 404)) {
+            if (addFindings([finding("plugin.catalog.tools_list.method_unsupported", "warn", "The endpoint advertised tools but does not implement tools/list.", "Tool definitions cannot be enumerated from the advertised capability.", "Implement tools/list for the advertised modern MCP tools capability.")]))
+                incompleteReason = "tools-list-method-unsupported";
+            break;
+        }
+        if (response.statusCode !== 200) {
+            if (addFindings([finding("plugin.catalog.http_status.invalid", "fail", "The endpoint returned an unexpected tools/list HTTP status.", "The tool catalog cannot be safely enumerated from this response.", "Return HTTP 200 for a tools/list response after authorization succeeds.")]))
+                incompleteReason = "http-status-invalid";
+            break;
+        }
+        const page = message === null ? null : parseToolsResult(message, requestId);
+        if (page === null) {
+            if (addFindings([finding("plugin.catalog.response.invalid", "fail", "The endpoint returned an invalid tools/list response.", "The tool catalog cannot be safely enumerated from this response.", "Return a matching JSON-RPC complete result with valid tools and cache metadata.")]))
+                incompleteReason = "response-invalid";
+            break;
+        }
+        pagesRead += 1;
+        for (const tool of page.tools) {
+            if (toolsChecked >= MAX_TOOLS) {
+                incompleteReason = "tool-limit";
+                break;
+            }
+            toolsChecked += 1;
+            const location = { page: pagesRead, toolIndex: toolsChecked };
+            if (!addFindings(inspectMcpToolDefinition(tool, location))) {
+                break;
+            }
+            if (isPlainObject(tool) && typeof tool.name === "string") {
+                const previous = names.get(tool.name);
+                if (previous !== undefined && !addFindings([{
+                        ...finding("plugin.catalog.tool.name.duplicate", "warn", "Two enumerated tools use the same name.", "Duplicate tool names can make client selection ambiguous.", "Use a unique MCP tool name for each definition."),
+                        location: { ...location, relatedToolIndex: previous }
+                    }])) {
+                    break;
+                }
+                if (previous === undefined)
+                    names.set(tool.name, toolsChecked);
+            }
+            if (deadline - now() <= 0) {
+                incompleteReason = "total-time-limit";
+                break;
+            }
+        }
+        if (incompleteReason !== null)
+            break;
+        if (page.cursor === undefined)
+            break;
+        if (seenCursors.has(page.cursor)) {
+            if (addFindings([finding("plugin.catalog.cursor.loop", "warn", "The endpoint repeated a tools/list cursor.", "The bounded catalog enumeration cannot determine a complete result set.", "Return each continuation cursor at most once for a single enumeration.")]))
+                incompleteReason = "cursor-loop";
+            break;
+        }
+        seenCursors.add(page.cursor);
+        cursor = page.cursor;
+    }
+    if (blocked) {
+        return catalogReport(discovery, "blocked", { complete: false, pagesRead, toolsChecked, reason: "network-blocked" }, "incomplete", findings);
+    }
+    if (incompleteReason !== null) {
+        return catalogReport(discovery, "incomplete", { complete: false, pagesRead, toolsChecked, reason: incompleteReason }, "incomplete", findings);
+    }
+    if (deadline - now() <= 0) {
+        return catalogReport(discovery, "incomplete", { complete: false, pagesRead, toolsChecked, reason: "total-time-limit" }, "incomplete", findings);
+    }
+    return catalogReport(discovery, finalStatus(findings), { complete: true, pagesRead, toolsChecked, reason: null }, "complete", findings);
+}

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

@@ -0,0 +1,14 @@
+import type { Finding } from "../domain/types.js";
+export interface CatalogLocation {
+    page: number;
+    toolIndex: number;
+    schema?: "inputSchema" | "outputSchema";
+    relatedToolIndex?: number;
+}
+export interface CatalogFinding extends Finding {
+    location?: CatalogLocation;
+}
+export declare function inspectMcpToolDefinition(value: unknown, location: {
+    page: number;
+    toolIndex: number;
+}): CatalogFinding[];

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

@@ -0,0 +1,116 @@
+const CANONICAL_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+const JSON_SCHEMA_TYPES = new Set([
+    "array",
+    "boolean",
+    "integer",
+    "null",
+    "number",
+    "object",
+    "string"
+]);
+const MCP_TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOwn(object, key) {
+    return Object.prototype.hasOwnProperty.call(object, key);
+}
+function isAbsoluteUri(value) {
+    try {
+        return new URL(value).protocol.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function schemaLocation(location, schema) {
+    return { ...location, schema };
+}
+function addFinding(findings, id, message, impact, suggestedFix, location) {
+    const severity = id === "plugin.catalog.tool.name.recommended" ||
+        id === "plugin.catalog.schema.dialect.unsupported"
+        ? "warn"
+        : "fail";
+    findings.push({ id, severity, message, impact, suggestedFix, location });
+}
+function inspectRootSchema(schema, schemaSlot, location, findings) {
+    const locator = schemaLocation(location, schemaSlot);
+    const hasDialect = hasOwn(schema, "$schema");
+    const dialect = hasDialect ? schema.$schema : undefined;
+    if (hasDialect && (typeof dialect !== "string" || !isAbsoluteUri(dialect))) {
+        addFinding(findings, "plugin.catalog.schema.dialect.invalid", "The root schema dialect must be an absolute URI string when provided.", "The validator cannot reliably select a schema dialect for this tool.", "Omit $schema or provide an absolute JSON Schema dialect URI.", locator);
+    }
+    if (typeof dialect === "string" &&
+        isAbsoluteUri(dialect) &&
+        dialect !== CANONICAL_SCHEMA_DIALECT &&
+        dialect !== `${CANONICAL_SCHEMA_DIALECT}#`) {
+        addFinding(findings, "plugin.catalog.schema.dialect.unsupported", "The root schema uses a dialect outside this validator's supported baseline.", "The schema may be valid, but its root keywords are outside this validator's bounded coverage.", "Use the JSON Schema 2020-12 dialect or validate this schema with a dialect-aware validator.", locator);
+        return;
+    }
+    if (hasOwn(schema, "properties") && !isJsonObject(schema.properties)) {
+        addFinding(findings, "plugin.catalog.schema.properties.invalid", "The root schema properties keyword must be an object when provided.", "Clients cannot reliably interpret the declared object properties.", "Set properties to an object or omit it.", locator);
+    }
+    if (hasOwn(schema, "required")) {
+        const required = schema.required;
+        const isValidRequired = Array.isArray(required) &&
+            required.every((entry) => typeof entry === "string") &&
+            new Set(required).size === required.length;
+        if (!isValidRequired) {
+            addFinding(findings, "plugin.catalog.schema.required.invalid", "The root schema required keyword must be an array of unique strings when provided.", "Clients cannot reliably determine which inputs are required.", "Set required to an array of unique property names or omit it.", locator);
+        }
+    }
+    if (hasOwn(schema, "type")) {
+        const type = schema.type;
+        const isValidType = (typeof type === "string" && JSON_SCHEMA_TYPES.has(type)) ||
+            (Array.isArray(type) &&
+                type.length > 0 &&
+                type.every((entry) => typeof entry === "string" && JSON_SCHEMA_TYPES.has(entry)) &&
+                new Set(type).size === type.length);
+        if (!isValidType) {
+            addFinding(findings, "plugin.catalog.schema.type.invalid", "The root schema type keyword must be a supported type string or a non-empty array of unique supported type strings.", "Clients cannot reliably interpret the root value type.", "Use JSON Schema primitive types for type, or omit the keyword.", locator);
+        }
+    }
+    if (hasOwn(schema, "additionalProperties") &&
+        typeof schema.additionalProperties !== "boolean" &&
+        !isJsonObject(schema.additionalProperties)) {
+        addFinding(findings, "plugin.catalog.schema.additional_properties.invalid", "The root schema additionalProperties keyword must be a boolean or object when provided.", "Clients cannot reliably interpret whether additional object properties are allowed.", "Set additionalProperties to a boolean or object, or omit it.", locator);
+    }
+}
+export function inspectMcpToolDefinition(value, location) {
+    const findings = [];
+    const baseLocation = { page: location.page, toolIndex: location.toolIndex };
+    if (!isJsonObject(value)) {
+        addFinding(findings, "plugin.catalog.tool.invalid_object", "A catalog tool entry must be an object.", "The validator cannot inspect a tool definition that is not an object.", "Return each tools/list entry as an object.", baseLocation);
+        return findings;
+    }
+    const name = hasOwn(value, "name") ? value.name : undefined;
+    if (typeof name !== "string") {
+        addFinding(findings, "plugin.catalog.tool.name.invalid", "A catalog tool name must be a string.", "Clients cannot identify or invoke a tool without a string name.", "Provide a string name for the tool.", baseLocation);
+    }
+    else if (!MCP_TOOL_NAME.test(name)) {
+        addFinding(findings, "plugin.catalog.tool.name.recommended", "The tool name does not meet the MCP recommended ASCII length and character constraints.", "Some clients may not accept or consistently display this tool name.", "Use 1 to 128 ASCII letters, digits, dots, underscores, or hyphens for the tool name.", baseLocation);
+    }
+    if (hasOwn(value, "title") && typeof value.title !== "string") {
+        addFinding(findings, "plugin.catalog.tool.title.invalid", "A catalog tool title must be a string when provided.", "Clients cannot reliably display a non-string tool title.", "Provide a string title or omit the title field.", baseLocation);
+    }
+    if (hasOwn(value, "description") && typeof value.description !== "string") {
+        addFinding(findings, "plugin.catalog.tool.description.invalid", "A catalog tool description must be a string when provided.", "Clients cannot reliably display a non-string tool description.", "Provide a string description or omit the description field.", baseLocation);
+    }
+    const inputSchema = hasOwn(value, "inputSchema") ? value.inputSchema : undefined;
+    if (!isJsonObject(inputSchema)) {
+        addFinding(findings, "plugin.catalog.schema.input.invalid", "A catalog tool inputSchema must be a non-null object.", "Clients cannot reliably construct valid tool inputs without an object schema.", "Provide inputSchema as an object.", schemaLocation(baseLocation, "inputSchema"));
+    }
+    else {
+        inspectRootSchema(inputSchema, "inputSchema", baseLocation, findings);
+    }
+    if (hasOwn(value, "outputSchema")) {
+        const outputSchema = value.outputSchema;
+        if (!isJsonObject(outputSchema)) {
+            addFinding(findings, "plugin.catalog.schema.output.invalid", "A catalog tool outputSchema must be an object when provided.", "Clients cannot reliably interpret tool outputs without an object schema.", "Provide outputSchema as an object or omit it.", schemaLocation(baseLocation, "outputSchema"));
+        }
+        else {
+            inspectRootSchema(outputSchema, "outputSchema", baseLocation, findings);
+        }
+    }
+    return findings;
+}

package/dist/core/output-contract.js

@@ -641,6 +641,79 @@ const publicSchemaDefinitions = [
         id: "doctor.snapshot.json",
         command: "codex-plugin-doctor doctor snapshot --json",
         required: ["schemaVersion", "generatedAt", "version", "environment", "clients", "installedPlugins", "nextCommands"]
+    },
+    {
+        id: "doctor.tools.json",
+        command: "codex-plugin-doctor doctor tools <url> --allow-network --json",
+        required: ["schemaVersion", "scope", "status", "discovery", "catalog", "coverage", "findings"],
+        properties: {
+            schemaVersion: { const: 1 },
+            scope: { const: "tool-catalog-structure" },
+            status: { enum: ["pass", "warn", "fail", "unsupported", "not-applicable", "incomplete", "blocked"] },
+            discovery: {
+                type: "object",
+                required: ["schemaVersion", "requestedVersion", "scope", "status", "supportedVersions", "findings", "coverage"],
+                properties: {
+                    schemaVersion: { const: 1 },
+                    requestedVersion: { const: "2026-07-28" },
+                    scope: { const: "discovery-only" },
+                    status: { enum: ["discovered", "unsupported", "blocked", "failed"] },
+                    supportedVersions: { type: "array", maxItems: 32, uniqueItems: true, items: { type: "string", pattern: "^\\d{4}-\\d{2}-\\d{2}$" } },
+                    findings: { type: "array" },
+                    coverage: {
+                        type: "object", required: ["discovery", "runtime"],
+                        properties: { discovery: { enum: ["pass", "fail", "skipped"] }, runtime: { const: "not-tested" } },
+                        additionalProperties: false
+                    }
+                },
+                additionalProperties: false
+            },
+            catalog: {
+                type: "object", required: ["complete", "pagesRead", "toolsChecked", "reason"],
+                properties: {
+                    complete: { type: "boolean" },
+                    pagesRead: { type: "integer", minimum: 0, maximum: 5 },
+                    toolsChecked: { type: "integer", minimum: 0, maximum: 500 },
+                    reason: { type: ["string", "null"] }
+                },
+                additionalProperties: false
+            },
+            coverage: {
+                type: "object",
+                required: ["discovery", "catalogEnumeration", "schema", "toolExecution", "fullConformance", "customHeaderAnnotations"],
+                properties: {
+                    discovery: { enum: ["pass", "fail", "skipped"] },
+                    catalogEnumeration: { enum: ["complete", "incomplete", "not-tested"] },
+                    schema: { const: "root-shape-only" },
+                    toolExecution: { const: "not-tested" },
+                    fullConformance: { const: "not-tested" },
+                    customHeaderAnnotations: { 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", "toolIndex"],
+                            properties: {
+                                page: { type: "integer", minimum: 1, maximum: 5 },
+                                toolIndex: { type: "integer", minimum: 1, maximum: 500 },
+                                schema: { enum: ["inputSchema", "outputSchema"] },
+                                relatedToolIndex: { type: "integer", minimum: 1, maximum: 500 }
+                            },
+                            additionalProperties: false
+                        }
+                    },
+                    additionalProperties: false
+                }
+            }
+        }
     }
 ];
 function sha256(value) {

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

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

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

@@ -0,0 +1,25 @@
+export function renderMcpToolCatalogReport(report) {
+    return [
+        "MCP Tool Catalog",
+        "================",
+        `Status: ${report.status}`,
+        `Scope: ${report.scope}`,
+        `Discovery: ${report.discovery.status}`,
+        `Catalog complete: ${report.catalog.complete}`,
+        `Pages read: ${report.catalog.pagesRead}`,
+        `Tools checked: ${report.catalog.toolsChecked}`,
+        ...(report.catalog.reason === null ? [] : [`Reason: ${report.catalog.reason}`]),
+        `Enumeration: ${report.coverage.catalogEnumeration}`,
+        `Schema coverage: ${report.coverage.schema}`,
+        `Tool execution: ${report.coverage.toolExecution}`,
+        `Custom header annotations: ${report.coverage.customHeaderAnnotations}`,
+        `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 location = finding.location;
+            const locator = location ? ` [page ${location.page}, tool ${location.toolIndex}${location.schema ? `, ${location.schema}` : ""}${location.relatedToolIndex ? `, related tool ${location.relatedToolIndex}` : ""}]` : "";
+            return `${finding.severity.toUpperCase()} ${finding.id}${locator}: ${finding.message}\n  ${finding.suggestedFix}`;
+        })
+    ].join("\n");
+}

package/dist/run-cli.d.ts

@@ -1,4 +1,5 @@
 import { discoverMcpServer } from "./core/mcp-discovery.js";
+import { inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
 import { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport } from "./core/corpus-quality-metrics.js";
 import { runCheck } from "./index.js";
 import { writeRawDoctorConfig } from "./index.js";
@@ -14,6 +15,7 @@ export interface CliTerminalContext {
     platform?: NodeJS.Platform;
 }
 export interface RunCliOptions {
+    inspectMcpToolCatalogImpl?: typeof inspectMcpToolCatalog;
     discoverMcpServerImpl?: typeof discoverMcpServer;
     terminalContext?: CliTerminalContext;
     runCheckImpl?: typeof runCheck;

package/dist/run-cli.js

@@ -22,6 +22,8 @@ import { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutp
 import { buildSubmissionArchivePreflight, submissionArchiveExitCode } from "./core/submission-archive-preflight.js";
 import { buildSubmissionPreflight } from "./core/submission-preflight.js";
 import { discoverMcpServer } from "./core/mcp-discovery.js";
+import { inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
+import { renderMcpToolCatalogReport } from "./reporting/render-mcp-tool-catalog-report.js";
 import { renderMcpDiscoveryReport } from "./reporting/render-mcp-discovery-report.js";
 import { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport } from "./core/validation-corpus.js";
 import { buildExternalValidationCorpusReport, ExternalCorpusManifestError } from "./core/external-validation-corpus.js";
@@ -101,6 +103,7 @@ function writeExactStdout(io, message) {
 }
 class CliUsageError extends Error {
 }
+const toolsUsage = "Usage: codex-plugin-doctor doctor tools <url> --allow-network [--allow-local-network] [--json]";
 const discoveryUsage = "Usage: codex-plugin-doctor doctor discover <url> --allow-network [--allow-local-network] [--json]";
 function parseRuntimeSandbox(flags, options = { requireRuntime: true }) {
     const index = flags.indexOf("--sandbox");
@@ -185,6 +188,7 @@ function parseRemoteNetworkFlags(flags, runtime) {
 function printUsage(io) {
     io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii] [--changed-since <ref>] [--fail-on <rule-id>]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--policy codex-publish|mcp-strict|security] [--recommend] [--json|--sarif] [--output <path>]\n       codex-plugin-doctor mcp <path> [--runtime [--allow-network [--allow-local-network]]] [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]\n       codex-plugin-doctor suppress list <path> [--config <path>] [--json]\n       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>] [--max-iterations <n>] [--fail-fast] [--accumulate-json <path>]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus [--manifest <corpus.json>] [--json] [--output <path>]|corpus metrics --manifest <corpus.json> [--json|--markdown] [--output <path>] [--min-precision <0..1>] [--min-recall <0..1>] [--max-false-positive-rate <0..1>]|runtime-plan <path> [--sandbox docker] [--json|--markdown] [--output <path>]|runtime-policy <path> [--sandbox docker] [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>] [--upload]|mcp <path> [--runtime [--allow-network [--allow-local-network]]]|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor init-git-hooks [path] [--force] [--json]\n       codex-plugin-doctor init-git-hooks [path] --remove [--json]\n       codex-plugin-doctor completion bash|zsh|fish\n       codex-plugin-doctor config validate <path> [--json]\n       codex-plugin-doctor release check <path> [--json] [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
     io.writeStderr(discoveryUsage);
+    io.writeStderr(toolsUsage);
     io.writeStderr("Registry readiness: codex-plugin-doctor registry check <server.json|directory> [--json] [--output <path>] [--require-registry-readiness]\n"
         + "       codex-plugin-doctor registry inspect <server-name> --allow-network [--json] [--output <path>] [--require-registry-readiness]\n"
         + "Registry publication preflight: codex-plugin-doctor registry preflight <server.json|directory> [--allow-network] [--json] [--output <path>] [--require-publish-ready]");
@@ -1195,6 +1199,35 @@ export async function runCli(args, io = defaultIo, options = {}) {
         return 0;
     }
     if (command === "doctor") {
+        if (maybePath === "tools") {
+            if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
+                io.writeStdout(`${toolsUsage}\nHTTP tool catalog structure only; tools are not executed.`);
+                return 0;
+            }
+            const [url, ...flags] = remainingArgs;
+            if (!url || url.startsWith("-")) {
+                io.writeStderr(toolsUsage);
+                return 2;
+            }
+            const allowedFlags = new Set(["--allow-network", "--allow-local-network", "--json"]);
+            if (flags.some((flag) => !allowedFlags.has(flag)) || new Set(flags).size !== flags.length) {
+                io.writeStderr(`Invalid or duplicate tool catalog arguments. ${toolsUsage}`);
+                return 2;
+            }
+            if (!flags.includes("--allow-network")) {
+                io.writeStderr("doctor tools requires explicit --allow-network consent.");
+                return 2;
+            }
+            const report = await (options.inspectMcpToolCatalogImpl ?? inspectMcpToolCatalog)(url, {
+                allowNetwork: true,
+                allowLocalNetwork: flags.includes("--allow-local-network")
+            });
+            io.writeStdout(flags.includes("--json")
+                ? JSON.stringify(report, null, 2)
+                : renderMcpToolCatalogReport(report));
+            return report.status === "pass" ? 0
+                : report.status === "incomplete" || report.status === "blocked" ? 2 : 1;
+        }
         if (maybePath === "discover") {
             if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
                 io.writeStdout(`${discoveryUsage}\nHTTP discovery only; runtime behavior is not tested.`);

package/package.json

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