codex-plugin-doctor 1.61.0 → 1.63.0

package/README.md

@@ -81,21 +81,48 @@ Runtime MCP validation with `--runtime`:
 - optional runtime approval gating with a precomputed `doctor runtime-plan` digest
 - optional Docker isolation for local Node.js stdio servers with `--sandbox docker`
 
-### MCP Protocol Discovery
-
-Inspect an HTTP MCP endpoint's advertised protocol versions using a bounded MCP
-2026-07-28 `server/discover` request:
-
-```bash
-codex-plugin-doctor doctor discover https://mcp.example.com/mcp --allow-network
-codex-plugin-doctor doctor discover https://mcp.example.com/mcp --allow-network --json
-```
-
-This is an opt-in discovery-only check. A successful result validates the discovery
-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.
-
+### MCP Protocol Discovery
+
+Inspect an HTTP MCP endpoint's advertised protocol versions using a bounded MCP
+2026-07-28 `server/discover` request:
+
+```bash
+codex-plugin-doctor doctor discover https://mcp.example.com/mcp --allow-network
+codex-plugin-doctor doctor discover https://mcp.example.com/mcp --allow-network --json
+```
+
+This is an opt-in discovery-only check. A successful result validates the discovery
+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.
+
+### Offline MCP Tool Definitions
+
+Inspect a saved MCP 2026-07-28 `tools/list` response without contacting a server:
+
+```bash
+codex-plugin-doctor doctor tools-file ./tools-list.json --json
+```
+
+This checks the supplied tool definitions and root-schema shapes within fixed file,
+tool, and finding limits. It does not establish server inventory completeness or
+execute tools. See [Offline MCP Tool Definitions](docs/guides/offline-tool-definitions.md)
+for the accepted input format, coverage, 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 +541,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.61.0
+      - uses: Esquetta/CodexPluginDoctor@v1.63.0
         with:
-          version: "1.61.0"
+          version: "1.63.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/mcp-tool-file.d.ts

@@ -0,0 +1,27 @@
+import type { CatalogFinding } from "./mcp-tool-definition.js";
+export interface McpToolFileReport {
+    schemaVersion: 1;
+    scope: "tool-definitions-file";
+    status: "pass" | "warn" | "fail" | "incomplete" | "blocked";
+    source: {
+        kind: "file";
+        format: "mcp-tools-list-response";
+        bytesRead: number;
+    };
+    inspection: {
+        complete: boolean;
+        toolsChecked: number;
+        hasNextCursor: boolean | null;
+        reason: string | null;
+    };
+    coverage: {
+        schema: "root-shape-only";
+        discovery: "not-tested";
+        serverCatalog: "not-tested";
+        toolExecution: "not-tested";
+        fullConformance: "not-tested";
+        customHeaderAnnotations: "not-tested";
+    };
+    findings: CatalogFinding[];
+}
+export declare function inspectMcpToolFile(filePath: string): Promise<McpToolFileReport>;

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

@@ -0,0 +1,241 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { inspectMcpToolDefinition } from "./mcp-tool-definition.js";
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_TOOLS = 500;
+const MAX_FINDINGS = 100;
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOwn(object, key) {
+    return Object.hasOwn(object, key);
+}
+function sameFile(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function sameSnapshot(left, right) {
+    return sameFile(left, right)
+        && left.size === right.size
+        && left.mtimeMs === right.mtimeMs
+        && left.ctimeMs === right.ctimeMs;
+}
+function isBlockedOfflinePath(filePath) {
+    return /^[A-Za-z][A-Za-z0-9+.-]+:/u.test(filePath)
+        || /^[A-Za-z]:\/\//u.test(filePath)
+        || /^[\\/]{2}/u.test(filePath);
+}
+function baseReport(bytesRead) {
+    return {
+        schemaVersion: 1,
+        scope: "tool-definitions-file",
+        source: { kind: "file", format: "mcp-tools-list-response", bytesRead },
+        coverage: {
+            schema: "root-shape-only",
+            discovery: "not-tested",
+            serverCatalog: "not-tested",
+            toolExecution: "not-tested",
+            fullConformance: "not-tested",
+            customHeaderAnnotations: "not-tested"
+        }
+    };
+}
+function report(bytesRead, status, inspection, findings) {
+    return { ...baseReport(bytesRead), status, inspection, findings };
+}
+function fileFinding(id, severity, message, impact, suggestedFix) {
+    return { id, severity, message, impact, suggestedFix };
+}
+function incompleteFileReport(bytesRead, reason, finding) {
+    return report(bytesRead, "incomplete", {
+        complete: false,
+        toolsChecked: 0,
+        hasNextCursor: null,
+        reason
+    }, [finding]);
+}
+function blockedFileReport(reason, finding) {
+    return report(0, "blocked", {
+        complete: false,
+        toolsChecked: 0,
+        hasNextCursor: null,
+        reason
+    }, [finding]);
+}
+function finalStatus(findings) {
+    if (findings.some((finding) => finding.severity === "fail"))
+        return "fail";
+    return findings.some((finding) => finding.severity === "warn") ? "warn" : "pass";
+}
+function parseToolsResult(value) {
+    if (!isJsonObject(value)
+        || value.jsonrpc !== "2.0"
+        || !hasOwn(value, "id")
+        || !(typeof value.id === "string" || (typeof value.id === "number" && Number.isFinite(value.id)))
+        || !hasOwn(value, "result")
+        || hasOwn(value, "error")
+        || !isJsonObject(value.result)
+        || value.result.resultType !== "complete"
+        || !Array.isArray(value.result.tools)
+        || typeof value.result.ttlMs !== "number"
+        || !Number.isFinite(value.result.ttlMs)
+        || value.result.ttlMs < 0
+        || (value.result.cacheScope !== "public" && value.result.cacheScope !== "private")) {
+        return null;
+    }
+    const hasNextCursor = hasOwn(value.result, "nextCursor");
+    if (hasNextCursor && typeof value.result.nextCursor !== "string")
+        return null;
+    return { tools: value.result.tools, hasNextCursor };
+}
+async function readBoundedRegularFile(filePath) {
+    let initial;
+    try {
+        initial = await lstat(filePath);
+    }
+    catch {
+        return { kind: "unavailable", bytesRead: 0 };
+    }
+    if (initial.isSymbolicLink())
+        return { kind: "symlink", bytesRead: 0 };
+    if (!initial.isFile())
+        return { kind: "not-regular", bytesRead: 0 };
+    if (!Number.isSafeInteger(initial.size) || initial.size < 0 || initial.size > MAX_FILE_BYTES) {
+        return { kind: "too-large", bytesRead: 0 };
+    }
+    const flags = process.platform === "win32"
+        ? constants.O_RDONLY
+        : constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+    let fileHandle = null;
+    let bytesRead = 0;
+    try {
+        fileHandle = await open(filePath, flags);
+        const opened = await fileHandle.stat();
+        const current = await lstat(filePath);
+        if (!opened.isFile() || current.isSymbolicLink() || !current.isFile() || !sameSnapshot(initial, opened) || !sameSnapshot(opened, current)) {
+            return { kind: "changed", bytesRead };
+        }
+        if (!Number.isSafeInteger(opened.size) || opened.size < 0 || opened.size > MAX_FILE_BYTES) {
+            return { kind: "too-large", bytesRead };
+        }
+        const content = Buffer.alloc(opened.size);
+        while (bytesRead < content.length) {
+            const read = await fileHandle.read(content, bytesRead, content.length - bytesRead, bytesRead);
+            if (read.bytesRead === 0)
+                return { kind: "changed", bytesRead };
+            bytesRead += read.bytesRead;
+        }
+        const probe = Buffer.alloc(1);
+        const extra = await fileHandle.read(probe, 0, 1, bytesRead);
+        bytesRead += extra.bytesRead;
+        if (extra.bytesRead !== 0)
+            return { kind: "changed", bytesRead };
+        const completed = await fileHandle.stat();
+        const final = await lstat(filePath);
+        if (!final.isFile() || final.isSymbolicLink() || !sameSnapshot(opened, completed) || !sameSnapshot(completed, final)) {
+            return { kind: "changed", bytesRead };
+        }
+        return { kind: "content", content, bytesRead };
+    }
+    catch {
+        return { kind: "unavailable", bytesRead };
+    }
+    finally {
+        await fileHandle?.close().catch(() => undefined);
+    }
+}
+export async function inspectMcpToolFile(filePath) {
+    if (isBlockedOfflinePath(filePath)) {
+        return blockedFileReport("offline-path-blocked", fileFinding("plugin.tools_file.path.blocked", "fail", "The local tool definition path is not permitted for offline inspection.", "The offline tool definition inspection does not access remote or device paths.", "Provide a local regular file path."));
+    }
+    const file = await readBoundedRegularFile(filePath);
+    if (file.kind === "unavailable") {
+        return incompleteFileReport(file.bytesRead, "file-unavailable", fileFinding("plugin.tools_file.file.unavailable", "fail", "The local tool definition file could not be read.", "The offline tool definition inspection could not start.", "Provide a readable local regular file."));
+    }
+    if (file.kind === "too-large") {
+        return incompleteFileReport(file.bytesRead, "file-size-limit", fileFinding("plugin.tools_file.file.too_large", "fail", "The local tool definition file exceeds the one MiB inspection limit.", "The offline tool definition inspection cannot safely read this file within its byte limit.", "Provide a tool definition file no larger than one MiB."));
+    }
+    if (file.kind === "changed") {
+        return incompleteFileReport(file.bytesRead, "file-changed", fileFinding("plugin.tools_file.file.changed", "fail", "The local tool definition file changed during inspection.", "The offline tool definition inspection cannot rely on an inconsistent file snapshot.", "Retry after the file is stable."));
+    }
+    if (file.kind === "symlink") {
+        return blockedFileReport("final-symlink", fileFinding("plugin.tools_file.file.symlink", "fail", "The local tool definition target is a symbolic link.", "The offline tool definition inspection does not follow final symbolic links.", "Provide a regular file directly."));
+    }
+    if (file.kind === "not-regular") {
+        return blockedFileReport("non-regular-file", fileFinding("plugin.tools_file.file.not_regular", "fail", "The local tool definition target is not a regular file.", "The offline tool definition inspection reads only bounded regular files.", "Provide a regular file directly."));
+    }
+    let decoded;
+    try {
+        decoded = new TextDecoder("utf-8", { fatal: true }).decode(file.content);
+    }
+    catch {
+        return incompleteFileReport(file.bytesRead, "invalid-utf8", fileFinding("plugin.tools_file.encoding.invalid", "fail", "The local tool definition file is not valid UTF-8.", "The offline tool definition inspection cannot parse the file safely.", "Save the tools/list response as UTF-8 JSON."));
+    }
+    let value;
+    try {
+        value = JSON.parse(decoded);
+    }
+    catch {
+        return incompleteFileReport(file.bytesRead, "invalid-json", fileFinding("plugin.tools_file.json.invalid", "fail", "The local tool definition file is not valid JSON.", "The offline tool definition inspection cannot parse the file safely.", "Provide one UTF-8 JSON-RPC tools/list response."));
+    }
+    const parsed = parseToolsResult(value);
+    if (parsed === null) {
+        return incompleteFileReport(file.bytesRead, "response-invalid", fileFinding("plugin.tools_file.response.invalid", "fail", "The local JSON value is not a supported complete tools/list response.", "The offline tool definition inspection cannot identify a valid tool list.", "Provide one JSON-RPC 2.0 complete tools/list result with valid cache metadata."));
+    }
+    const findings = [];
+    const names = new Map();
+    let reason = null;
+    let toolsChecked = 0;
+    const addFindings = (items) => {
+        const remaining = MAX_FINDINGS - findings.length;
+        if (items.length > remaining) {
+            findings.push(...items.slice(0, remaining));
+            reason = "finding-limit";
+            return false;
+        }
+        findings.push(...items);
+        return true;
+    };
+    for (const tool of parsed.tools) {
+        if (toolsChecked >= MAX_TOOLS) {
+            reason = "tool-limit";
+            break;
+        }
+        toolsChecked += 1;
+        const location = { page: 1, toolIndex: toolsChecked };
+        if (!addFindings(inspectMcpToolDefinition(tool, location)))
+            break;
+        if (isJsonObject(tool) && typeof tool.name === "string") {
+            const previous = names.get(tool.name);
+            if (previous !== undefined && !addFindings([fileFinding("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.")])) {
+                break;
+            }
+            if (previous !== undefined) {
+                findings[findings.length - 1] = {
+                    ...findings[findings.length - 1],
+                    location: { ...location, relatedToolIndex: previous }
+                };
+            }
+            else {
+                names.set(tool.name, toolsChecked);
+            }
+        }
+    }
+    if (reason === null && parsed.tools.length > MAX_TOOLS)
+        reason = "tool-limit";
+    if (reason === null && parsed.hasNextCursor)
+        reason = "more-pages-present";
+    if (reason !== null) {
+        return report(file.bytesRead, "incomplete", {
+            complete: false,
+            toolsChecked,
+            hasNextCursor: parsed.hasNextCursor,
+            reason
+        }, findings);
+    }
+    return report(file.bytesRead, finalStatus(findings), {
+        complete: true,
+        toolsChecked,
+        hasNextCursor: false,
+        reason: null
+    }, findings);
+}

package/dist/core/output-contract.js

@@ -641,6 +641,130 @@ 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
+                }
+            }
+        }
+    },
+    {
+        id: "doctor.tools.file.json",
+        command: "codex-plugin-doctor doctor tools-file <path> --json",
+        required: ["schemaVersion", "scope", "status", "source", "inspection", "coverage", "findings"],
+        properties: {
+            schemaVersion: { const: 1 },
+            scope: { const: "tool-definitions-file" },
+            status: { enum: ["pass", "warn", "fail", "incomplete", "blocked"] },
+            source: {
+                type: "object", required: ["kind", "format", "bytesRead"],
+                properties: {
+                    kind: { const: "file" }, format: { const: "mcp-tools-list-response" },
+                    bytesRead: { type: "integer", minimum: 0, maximum: 1048577 }
+                }, additionalProperties: false
+            },
+            inspection: {
+                type: "object", required: ["complete", "toolsChecked", "hasNextCursor", "reason"],
+                properties: {
+                    complete: { type: "boolean" }, toolsChecked: { type: "integer", minimum: 0, maximum: 500 },
+                    hasNextCursor: { type: ["boolean", "null"] }, reason: { type: ["string", "null"] }
+                }, additionalProperties: false
+            },
+            coverage: {
+                type: "object", required: ["schema", "discovery", "serverCatalog", "toolExecution", "fullConformance", "customHeaderAnnotations"],
+                properties: {
+                    schema: { const: "root-shape-only" }, discovery: { const: "not-tested" },
+                    serverCatalog: { const: "not-tested" }, 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\\.(tools_file|catalog)\\." },
+                        severity: { enum: ["warn", "fail"] },
+                        message: { type: "string" }, impact: { type: "string" }, suggestedFix: { type: "string" },
+                        location: {
+                            type: "object", required: ["page", "toolIndex"],
+                            properties: {
+                                page: { const: 1 }, 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/reporting/render-mcp-tool-file-report.d.ts

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

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

@@ -0,0 +1,26 @@
+export function renderMcpToolFileReport(report) {
+    return [
+        "Offline MCP Tool Definitions",
+        "============================",
+        `Status: ${report.status}`,
+        `Scope: ${report.scope}`,
+        `Source: ${report.source.kind} (${report.source.format})`,
+        `Bytes read: ${report.source.bytesRead}`,
+        `Inspection complete: ${report.inspection.complete}`,
+        `Tools checked: ${report.inspection.toolsChecked}`,
+        `More pages advertised: ${report.inspection.hasNextCursor ?? "unknown"}`,
+        ...(report.inspection.reason === null ? [] : [`Reason: ${report.inspection.reason}`]),
+        `Schema coverage: ${report.coverage.schema}`,
+        `Discovery: ${report.coverage.discovery}`,
+        `Server catalog: ${report.coverage.serverCatalog}`,
+        `Tool execution: ${report.coverage.toolExecution}`,
+        `Full conformance: ${report.coverage.fullConformance}`,
+        `Custom header annotations: ${report.coverage.customHeaderAnnotations}`,
+        "Only the supplied file was inspected. Its provenance and server completeness are not established.",
+        ...report.findings.map((finding) => {
+            const location = finding.location;
+            const locator = location ? ` [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,6 @@
 import { discoverMcpServer } from "./core/mcp-discovery.js";
+import { inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
+import { inspectMcpToolFile } from "./core/mcp-tool-file.js";
 import { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport } from "./core/corpus-quality-metrics.js";
 import { runCheck } from "./index.js";
 import { writeRawDoctorConfig } from "./index.js";
@@ -14,6 +16,8 @@ export interface CliTerminalContext {
     platform?: NodeJS.Platform;
 }
 export interface RunCliOptions {
+    inspectMcpToolFileImpl?: typeof inspectMcpToolFile;
+    inspectMcpToolCatalogImpl?: typeof inspectMcpToolCatalog;
     discoverMcpServerImpl?: typeof discoverMcpServer;
     terminalContext?: CliTerminalContext;
     runCheckImpl?: typeof runCheck;

package/dist/run-cli.js

@@ -22,6 +22,10 @@ import { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutp
 import { buildSubmissionArchivePreflight, submissionArchiveExitCode } from "./core/submission-archive-preflight.js";
 import { buildSubmissionPreflight } from "./core/submission-preflight.js";
 import { discoverMcpServer } from "./core/mcp-discovery.js";
+import { inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
+import { inspectMcpToolFile } from "./core/mcp-tool-file.js";
+import { renderMcpToolFileReport } from "./reporting/render-mcp-tool-file-report.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 +105,8 @@ function writeExactStdout(io, message) {
 }
 class CliUsageError extends Error {
 }
+const toolsFileUsage = "Usage: codex-plugin-doctor doctor tools-file <path> [--json]";
+const toolsUsage = "Usage: codex-plugin-doctor doctor tools <url> --allow-network [--allow-local-network] [--json]";
 const 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 +191,8 @@ 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(toolsFileUsage);
     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 +1203,52 @@ export async function runCli(args, io = defaultIo, options = {}) {
         return 0;
     }
     if (command === "doctor") {
+        if (maybePath === "tools-file") {
+            if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
+                io.writeStdout(`${toolsFileUsage}\nInspects one saved UTF-8 MCP tools/list response. No server connection or tool execution.`);
+                return 0;
+            }
+            const [filePath, ...flags] = remainingArgs;
+            if (!filePath || filePath.startsWith("-") || flags.some((flag) => flag !== "--json") || flags.length > 1) {
+                io.writeStderr(`Invalid file inspection arguments. ${toolsFileUsage}`);
+                return 2;
+            }
+            const report = await (options.inspectMcpToolFileImpl ?? inspectMcpToolFile)(filePath);
+            io.writeStdout(flags.includes("--json")
+                ? JSON.stringify(report, null, 2)
+                : renderMcpToolFileReport(report));
+            return report.status === "pass" ? 0
+                : report.status === "warn" || report.status === "fail" ? 1 : 2;
+        }
+        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.63.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",