codex-plugin-doctor 1.69.1 → 1.70.0

package/README.md

@@ -127,7 +127,7 @@ 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:
 
@@ -148,7 +148,20 @@ approved loopback endpoint; it is never printed or saved. The GitHub Action can
 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.
-See [HTTP MCP Tool Catalog](docs/guides/mcp-tool-catalog.md).
+
+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
 
@@ -568,9 +581,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.69.1
+      - uses: Esquetta/CodexPluginDoctor@v1.70.0
         with:
-          version: "1.69.1"
+          version: "1.70.0"
           path: .
           runtime: "true"
           policy: codex-publish

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

@@ -26,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,11 +139,7 @@ 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, {

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>;