codex-plugin-doctor 1.68.0 → 1.70.0

package/README.md

@@ -120,14 +120,14 @@ codex-plugin-doctor doctor tools-diff --before ./tools-old.json --after ./tools-
 This reports added, removed, and structurally changed definitions using numeric
 locations, and labels each change `breaking`, `compatible`, or `unclassified`
 with fixed reason codes. Add `--fail-on breaking` to fail CI only on breaking or
-unclassified changes. Incomplete inputs, invalid definitions, or duplicate names
+unclassified changes, and `--markdown` for pull request tables. Incomplete inputs, invalid definitions, or duplicate names
 prevent a comparison. Impact labels follow nested object properties, array
 items, and common length and range bounds, but remain heuristics, not proof of
 compatibility.
 See [Offline MCP Tool Diff](docs/guides/offline-tool-diff.md) for matching rules,
 privacy, limits, and exit codes.
 
-### HTTP MCP Tool Catalog
+### MCP Tool Catalog
 
 Inspect a modern HTTP MCP server's tool definitions without invoking them:
 
@@ -141,11 +141,27 @@ and partial inspection limits. It does not claim full schema validation, tool
 execution, or client compatibility. Existing `doctor discover` behavior is unchanged.
 Add `--save-response <path>` to record a completely enumerated catalog as a
 `tools/list` response for `tools-file` and `tools-diff`; nothing is written when
-enumeration is incomplete. The GitHub Action can compare saved responses with
+enumeration is incomplete. For protected servers, `--bearer-token-env <NAME>`
+sends a bearer token from an environment variable only over HTTPS or to an
+approved loopback endpoint; it is never printed or saved. The GitHub Action can compare saved responses with
 `tools-diff-before`, `tools-diff-after`, and `tools-diff-fail-on`, capture the
-live list with `tools-capture-url`, and skip the plugin package check with
-`check: "false"` in repositories that only ship an MCP server.
-See [HTTP MCP Tool Catalog](docs/guides/mcp-tool-catalog.md).
+live list with `tools-capture-url` (and `tools-capture-token-env`), and skip the
+plugin package check with `check: "false"` in repositories that only ship an MCP
+server.
+
+Local stdio servers from a package's MCP configuration can be cataloged too.
+`--runtime` is required because this starts package code; the server is stopped
+after its tool list is read:
+
+```bash
+codex-plugin-doctor doctor tools ./my-plugin --server my-server --runtime --save-response ./tools-current.json
+```
+
+Doctor tries `server/discover` (`2026-07-28`) first and falls back to the
+`initialize` handshake for older stdio servers, so the saved list works with
+`tools-file` and `tools-diff` either way. `--sandbox docker` and
+`--require-runtime-approval` work as they do for `check --runtime`.
+See [MCP Tool Catalog](docs/guides/mcp-tool-catalog.md).
 
 ### Remote MCP Readiness
 
@@ -565,9 +581,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.68.0
+      - uses: Esquetta/CodexPluginDoctor@v1.70.0
         with:
-          version: "1.68.0"
+          version: "1.70.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/bounded-http-client.d.ts

@@ -7,17 +7,20 @@ export interface BoundedHttpRequestOptions {
     method?: string;
     body?: string | Buffer;
     headers?: Record<string, string | undefined>;
+    bearerToken?: string;
     stopAfter?: (body: Buffer) => boolean;
 }
+/** RFC 6750 b64token syntax, which also rules out header injection. */
+export declare function isValidBearerToken(token: string): boolean;
 export interface BoundedHttpResponse {
     statusCode: number;
     headers: Record<string, string | string[]>;
     body: Buffer;
 }
 export declare class BoundedHttpError extends Error {
-    readonly code: "REMOTE_HTTP_ENCODING_UNSUPPORTED" | "REMOTE_HTTP_HEADER_FORBIDDEN" | "REMOTE_HTTP_OPTIONS_INVALID" | "REMOTE_HTTP_PEER_MISMATCH" | "REMOTE_HTTP_REDIRECT" | "REMOTE_HTTP_REQUEST_FAILED" | "REMOTE_HTTP_RESPONSE_TOO_LARGE" | "REMOTE_HTTP_STOP_CONDITION_FAILED" | "REMOTE_HTTP_TIMEOUT" | "REMOTE_HTTP_URL_CREDENTIALS" | "REMOTE_HTTP_URL_UNSUPPORTED";
+    readonly code: "REMOTE_HTTP_ENCODING_UNSUPPORTED" | "REMOTE_HTTP_HEADER_FORBIDDEN" | "REMOTE_HTTP_INSECURE_CREDENTIALS" | "REMOTE_HTTP_OPTIONS_INVALID" | "REMOTE_HTTP_PEER_MISMATCH" | "REMOTE_HTTP_REDIRECT" | "REMOTE_HTTP_REQUEST_FAILED" | "REMOTE_HTTP_RESPONSE_TOO_LARGE" | "REMOTE_HTTP_STOP_CONDITION_FAILED" | "REMOTE_HTTP_TIMEOUT" | "REMOTE_HTTP_URL_CREDENTIALS" | "REMOTE_HTTP_URL_UNSUPPORTED";
     readonly statusCode?: number | undefined;
     readonly headers?: Record<string, string | string[]> | undefined;
-    constructor(code: "REMOTE_HTTP_ENCODING_UNSUPPORTED" | "REMOTE_HTTP_HEADER_FORBIDDEN" | "REMOTE_HTTP_OPTIONS_INVALID" | "REMOTE_HTTP_PEER_MISMATCH" | "REMOTE_HTTP_REDIRECT" | "REMOTE_HTTP_REQUEST_FAILED" | "REMOTE_HTTP_RESPONSE_TOO_LARGE" | "REMOTE_HTTP_STOP_CONDITION_FAILED" | "REMOTE_HTTP_TIMEOUT" | "REMOTE_HTTP_URL_CREDENTIALS" | "REMOTE_HTTP_URL_UNSUPPORTED", message: string, statusCode?: number | undefined, headers?: Record<string, string | string[]> | undefined);
+    constructor(code: "REMOTE_HTTP_ENCODING_UNSUPPORTED" | "REMOTE_HTTP_HEADER_FORBIDDEN" | "REMOTE_HTTP_INSECURE_CREDENTIALS" | "REMOTE_HTTP_OPTIONS_INVALID" | "REMOTE_HTTP_PEER_MISMATCH" | "REMOTE_HTTP_REDIRECT" | "REMOTE_HTTP_REQUEST_FAILED" | "REMOTE_HTTP_RESPONSE_TOO_LARGE" | "REMOTE_HTTP_STOP_CONDITION_FAILED" | "REMOTE_HTTP_TIMEOUT" | "REMOTE_HTTP_URL_CREDENTIALS" | "REMOTE_HTTP_URL_UNSUPPORTED", message: string, statusCode?: number | undefined, headers?: Record<string, string | string[]> | undefined);
 }
 export declare function requestBoundedHttp(rawUrl: string, options?: BoundedHttpRequestOptions): Promise<BoundedHttpResponse>;

package/dist/core/bounded-http-client.js

@@ -20,6 +20,11 @@ const safeResponseHeaders = new Set([
     "mcp-protocol-version",
     "location"
 ]);
+const MAX_BEARER_TOKEN_LENGTH = 4_096;
+/** RFC 6750 b64token syntax, which also rules out header injection. */
+export function isValidBearerToken(token) {
+    return token.length > 0 && token.length <= MAX_BEARER_TOKEN_LENGTH && /^[A-Za-z0-9\-._~+/]+=*$/u.test(token);
+}
 export class BoundedHttpError extends Error {
     code;
     statusCode;
@@ -127,8 +132,17 @@ export async function requestBoundedHttp(rawUrl, options = {}) {
     }
     const { timeoutMs, maxResponseBytes } = validateOptions(options);
     const headers = validateHeaders(options.headers);
+    if (options.bearerToken !== undefined && !isValidBearerToken(options.bearerToken)) {
+        throw new BoundedHttpError("REMOTE_HTTP_OPTIONS_INVALID", "Remote HTTP bearer token is invalid.");
+    }
     const deadline = Date.now() + timeoutMs;
     const target = await resolveWithinDeadline(url, options, timeoutMs);
+    if (options.bearerToken !== undefined) {
+        if (url.protocol !== "https:" && !target.local) {
+            throw new BoundedHttpError("REMOTE_HTTP_INSECURE_CREDENTIALS", "Remote HTTP bearer tokens require HTTPS or an approved loopback target.");
+        }
+        headers.authorization = `Bearer ${options.bearerToken}`;
+    }
     const remainingMs = deadline - Date.now();
     if (remainingMs <= 0) {
         throw new BoundedHttpError("REMOTE_HTTP_TIMEOUT", "Remote HTTP request timed out.");

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

@@ -9,6 +9,7 @@ export interface McpDiscoveryOptions {
     requestTimeoutMs?: number;
     lookup?: RemoteLookup;
     request?: RemoteMcpRequest;
+    bearerToken?: string;
 }
 export interface McpDiscoveryReport {
     schemaVersion: 1;
@@ -25,4 +26,23 @@ export interface McpDiscoveryReport {
 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 serializeMcpDiscoverRequest(requestId?: string): string;
+export type McpDiscoverOutcome = {
+    kind: "discovered";
+    supportedVersions: string[];
+    capabilities: McpJsonObject;
+} | {
+    kind: "version-not-listed";
+    supportedVersions: string[];
+} | {
+    kind: "version-unsupported";
+    supportedVersions: string[];
+} | {
+    kind: "result-invalid";
+} | {
+    kind: "envelope-invalid";
+} | {
+    kind: "other-error";
+};
+export declare function classifyMcpDiscoverMessage(message: McpJsonObject, requestId?: string): McpDiscoverOutcome;
 export declare function discoverMcpServer(rawUrl: string, options?: McpDiscoveryOptions): Promise<McpDiscoveryReport>;

package/dist/core/mcp-discovery.js

@@ -102,6 +102,29 @@ export function discoverMcpCapabilities(response, requestId = REQUEST_ID) {
         return null;
     return result.supportedVersions.includes(REQUESTED_VERSION) ? capabilities : null;
 }
+export function serializeMcpDiscoverRequest(requestId = REQUEST_ID) {
+    return JSON.stringify({ jsonrpc: "2.0", id: requestId, method: "server/discover", params: { _meta: {
+                "io.modelcontextprotocol/protocolVersion": REQUESTED_VERSION,
+                "io.modelcontextprotocol/clientInfo": { name: "Codex Plugin Doctor", version: packageVersion },
+                "io.modelcontextprotocol/clientCapabilities": {}
+            } } });
+}
+// Classifies a transport-neutral server/discover reply. Only a valid result or a valid
+// UnsupportedProtocolVersionError identifies a modern server; other errors do not.
+export function classifyMcpDiscoverMessage(message, requestId = REQUEST_ID) {
+    if (!hasMatchingResponseEnvelope(message, requestId))
+        return { kind: "envelope-invalid" };
+    if (Object.hasOwn(message, "error")) {
+        const versions = unsupportedVersions(message.error);
+        return versions === null ? { kind: "other-error" } : { kind: "version-unsupported", supportedVersions: versions };
+    }
+    const result = message.result;
+    if (!validDiscoverResult(result))
+        return { kind: "result-invalid" };
+    return result.supportedVersions.includes(REQUESTED_VERSION)
+        ? { kind: "discovered", supportedVersions: result.supportedVersions, capabilities: result.capabilities }
+        : { kind: "version-not-listed", supportedVersions: result.supportedVersions };
+}
 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.")]);
 }
@@ -116,16 +139,12 @@ export async function discoverMcpServer(rawUrl, options = {}) {
         return report("blocked", "skipped", [finding("plugin.discovery.url.invalid", "warn", "The MCP discovery endpoint is unsafe or unsupported.", "Unsafe endpoint URLs can bypass network controls or expose credentials.", "Use an absolute HTTP or HTTPS endpoint without credentials, query parameters, fragments, or IP literals.")]);
     }
     const request = options.request ?? requestBoundedHttp;
-    const body = JSON.stringify({ jsonrpc: "2.0", id: REQUEST_ID, method: "server/discover", params: { _meta: {
-                "io.modelcontextprotocol/protocolVersion": REQUESTED_VERSION,
-                "io.modelcontextprotocol/clientInfo": { name: "Codex Plugin Doctor", version: packageVersion },
-                "io.modelcontextprotocol/clientCapabilities": {}
-            } } });
+    const body = serializeMcpDiscoverRequest();
     let response;
     try {
         response = await request(rawUrl, {
             allowLocalNetwork: options.allowLocalNetwork, lookup: options.lookup, timeoutMs: options.requestTimeoutMs,
-            method: "POST", body,
+            method: "POST", body, bearerToken: options.bearerToken,
             headers: { Accept: "application/json, text/event-stream", "Content-Type": "application/json", "MCP-Protocol-Version": REQUESTED_VERSION, "Mcp-Method": "server/discover" },
             stopAfter: (received) => findMcpSseResponse(received) !== null
         });
@@ -134,10 +153,15 @@ export async function discoverMcpServer(rawUrl, options = {}) {
         if (error instanceof RemoteNetworkPolicyError) {
             return report("blocked", "skipped", [finding("plugin.discovery.network.blocked", "warn", "The MCP discovery target is blocked by the remote network policy.", "Discovery could not safely reach the configured target.", "Use an endpoint permitted by the remote network policy.")]);
         }
+        if (error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_INSECURE_CREDENTIALS") {
+            return report("blocked", "skipped", [finding("plugin.discovery.credentials.insecure_transport", "warn", "The bearer token was not sent because the endpoint is neither HTTPS nor an approved loopback target.", "Sending a token over plain HTTP would expose it to the network.", "Use an HTTPS endpoint, or a loopback endpoint with local network access approved.")]);
+        }
         return failureReport(error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_TIMEOUT" ? "plugin.discovery.transport.timeout" : "plugin.discovery.transport.failed", "The MCP discovery request did not complete within the configured transport bounds.");
     }
     if (response.statusCode === 401 || response.statusCode === 403) {
-        return unsupportedReport("plugin.discovery.authorization.required", "The MCP endpoint requires authorization before discovery can be assessed.");
+        return options.bearerToken === undefined
+            ? unsupportedReport("plugin.discovery.authorization.required", "The MCP endpoint requires authorization before discovery can be assessed.")
+            : unsupportedReport("plugin.discovery.authorization.rejected", "The MCP endpoint rejected the supplied bearer token.");
     }
     const message = parseMcpResponse(response);
     if (!message || !hasMatchingResponseEnvelope(message))

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

@@ -0,0 +1,31 @@
+import { spawn } from "node:child_process";
+import type { RuntimeSandboxMode } from "../domain/types.js";
+import { type McpToolCatalogSnapshot } from "./mcp-tool-catalog.js";
+export interface McpStdioServer {
+    packageRoot: string;
+    command: string;
+    args: string[];
+    cwd: string;
+    source: "manifest" | "mcp-json";
+}
+export type McpStdioServerResolution = {
+    ok: true;
+    server: McpStdioServer;
+} | {
+    ok: false;
+    message: string;
+};
+export interface McpStdioToolCatalogOptions {
+    sandbox?: RuntimeSandboxMode;
+    now?: () => number;
+    spawnImpl?: typeof spawn;
+    removeContainerImpl?: (containerName: string) => Promise<boolean>;
+    timeouts?: {
+        startupMs?: number;
+        requestMs?: number;
+        totalMs?: number;
+        shutdownMs?: number;
+    };
+}
+export declare function resolveMcpStdioServer(targetPath: string, serverName: string): Promise<McpStdioServerResolution>;
+export declare function captureStdioMcpToolCatalog(server: McpStdioServer, options?: McpStdioToolCatalogOptions): Promise<McpToolCatalogSnapshot>;