codex-plugin-doctor 1.60.0 → 1.61.0

package/README.md

@@ -81,6 +81,21 @@ 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.
+
 ### Remote MCP Readiness
 
 Remote MCP runtime probing is disabled until you explicitly pass `--runtime --allow-network`. Loopback endpoints also require `--allow-local-network`:
@@ -499,9 +514,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.60.0
+      - uses: Esquetta/CodexPluginDoctor@v1.61.0
         with:
-          version: "1.60.0"
+          version: "1.61.0"
           path: .
           runtime: "true"
           policy: codex-publish

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

@@ -8,6 +8,7 @@ const allowedRequestHeaders = new Set([
     "accept",
     "content-type",
     "last-event-id",
+    "mcp-method",
     "mcp-protocol-version",
     "mcp-session-id",
     "user-agent"

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

@@ -0,0 +1,23 @@
+import { type RemoteLookup } from "./remote-network-policy.js";
+import type { RemoteMcpRequest } from "./remote-mcp-probe.js";
+import type { Finding } from "../domain/types.js";
+export interface McpDiscoveryOptions {
+    allowNetwork?: boolean;
+    allowLocalNetwork?: boolean;
+    requestTimeoutMs?: number;
+    lookup?: RemoteLookup;
+    request?: RemoteMcpRequest;
+}
+export interface McpDiscoveryReport {
+    schemaVersion: 1;
+    requestedVersion: "2026-07-28";
+    scope: "discovery-only";
+    status: "discovered" | "unsupported" | "blocked" | "failed";
+    supportedVersions: string[];
+    findings: Finding[];
+    coverage: {
+        discovery: "pass" | "fail" | "skipped";
+        runtime: "not-tested";
+    };
+}
+export declare function discoverMcpServer(rawUrl: string, options?: McpDiscoveryOptions): Promise<McpDiscoveryReport>;

package/dist/core/mcp-discovery.js

@@ -0,0 +1,148 @@
+import { BoundedHttpError, requestBoundedHttp } from "./bounded-http-client.js";
+import { RemoteNetworkPolicyError } from "./remote-network-policy.js";
+import { inspectRemoteMcpUrl } from "./remote-url-policy.js";
+import { packageVersion } from "../version.js";
+const REQUESTED_VERSION = "2026-07-28";
+const REQUEST_ID = "discover-1";
+function finding(id, severity, message, impact, suggestedFix) {
+    return { id, severity, message, impact, suggestedFix };
+}
+function report(status, discovery, findings = [], supportedVersions = []) {
+    return { schemaVersion: 1, requestedVersion: REQUESTED_VERSION, scope: "discovery-only", status, supportedVersions, findings, coverage: { discovery, runtime: "not-tested" } };
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseJsonObject(source) {
+    try {
+        const parsed = JSON.parse(source);
+        return isPlainObject(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function mediaType(response) {
+    const contentType = response.headers["content-type"];
+    const value = Array.isArray(contentType) ? contentType[0] : contentType;
+    return typeof value === "string" ? value.split(";", 1)[0]?.trim().toLowerCase() ?? null : null;
+}
+function findSseResponse(body) {
+    const text = body.toString("utf8").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    let offset = 0;
+    while (offset < text.length) {
+        const boundary = text.indexOf("\n\n", offset);
+        if (boundary === -1)
+            return null;
+        const data = text.slice(offset, boundary).split("\n")
+            .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)
+            return candidate;
+        offset = boundary + 2;
+    }
+    return null;
+}
+function parseResponse(response) {
+    const contentType = mediaType(response);
+    return contentType === "application/json" ? parseJsonObject(response.body.toString("utf8"))
+        : contentType === "text/event-stream" ? findSseResponse(response.body)
+            : null;
+}
+function isValidVersion(value) {
+    if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const [year, month, day] = value.split("-").map(Number);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+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
+        && Object.hasOwn(message, "result") !== Object.hasOwn(message, "error");
+}
+function validDiscoverResult(value) {
+    return isPlainObject(value) && value.resultType === "complete" && validVersions(value.supportedVersions)
+        && validCapabilities(value.capabilities) && typeof value.ttlMs === "number" && Number.isFinite(value.ttlMs) && value.ttlMs >= 0
+        && (value.cacheScope === "public" || value.cacheScope === "private") && validOptionalServerInfo(value);
+}
+function validCapabilities(value) {
+    return isPlainObject(value) && ["tools", "resources", "prompts", "completions", "logging", "tasks", "extensions"]
+        .every((name) => !Object.hasOwn(value, name) || isPlainObject(value[name]));
+}
+function validOptionalServerInfo(value) {
+    if (!Object.hasOwn(value, "_meta"))
+        return true;
+    if (!isPlainObject(value._meta))
+        return false;
+    const serverInfo = value._meta["io.modelcontextprotocol/serverInfo"];
+    return serverInfo === undefined || (isPlainObject(serverInfo) && typeof serverInfo.name === "string" && typeof serverInfo.version === "string");
+}
+function validError(value) {
+    return isPlainObject(value) && typeof value.code === "number" && Number.isFinite(value.code) && typeof value.message === "string";
+}
+function unsupportedVersions(error) {
+    if (!validError(error) || error.code !== -32022 || !isPlainObject(error.data))
+        return null;
+    return error.data.requested === REQUESTED_VERSION && validVersions(error.data.supported) ? error.data.supported : 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.")]);
+}
+function unsupportedReport(id, message, versions = []) {
+    return report("unsupported", "skipped", [finding(id, "warn", message, "Discovery-only probing cannot establish support for the requested MCP protocol version.", "Configure a server that supports the requested protocol version, then run discovery again.")], versions);
+}
+export async function discoverMcpServer(rawUrl, options = {}) {
+    if (!options.allowNetwork) {
+        return report("blocked", "skipped", [finding("plugin.discovery.network_not_approved", "warn", "Remote MCP discovery was not contacted because network access is not approved.", "Discovery would create outbound network traffic without explicit approval.", "Enable network access only after reviewing the endpoint.")]);
+    }
+    if (inspectRemoteMcpUrl(rawUrl).issues.length > 0) {
+        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": {}
+            } } });
+    let response;
+    try {
+        response = await request(rawUrl, {
+            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
+        });
+    }
+    catch (error) {
+        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.")]);
+        }
+        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.");
+    }
+    const message = parseResponse(response);
+    if (!message || !hasMatchingResponseEnvelope(message))
+        return failureReport("plugin.discovery.response.invalid", "The MCP endpoint returned an invalid discovery response.");
+    if (Object.hasOwn(message, "error")) {
+        if (!validError(message.error))
+            return failureReport("plugin.discovery.response.error", "The MCP endpoint returned an invalid discovery error.");
+        const versions = unsupportedVersions(message.error);
+        if (versions !== null && response.statusCode === 400)
+            return unsupportedReport("plugin.discovery.protocol_version.unsupported", "The MCP endpoint does not support the requested protocol version.", versions);
+        if (message.error.code === -32601 && (response.statusCode === 200 || response.statusCode === 404))
+            return unsupportedReport("plugin.discovery.method.unsupported", "The MCP endpoint does not implement server discovery for this protocol version.");
+        return failureReport("plugin.discovery.response.error", "The MCP endpoint returned an unrecognized discovery error.");
+    }
+    if (response.statusCode !== 200 || !validDiscoverResult(message.result))
+        return failureReport("plugin.discovery.result.invalid", "The MCP endpoint returned an invalid discovery result.");
+    const versions = message.result.supportedVersions;
+    if (!versions.includes(REQUESTED_VERSION))
+        return unsupportedReport("plugin.discovery.protocol_version.inconsistent", "The MCP endpoint completed discovery without listing the requested protocol version.", versions);
+    return report("discovered", "pass", [], versions);
+}

package/dist/reporting/render-mcp-discovery-report.d.ts

@@ -0,0 +1,2 @@
+import type { McpDiscoveryReport } from "../core/mcp-discovery.js";
+export declare function renderMcpDiscoveryReport(report: McpDiscoveryReport): string;

package/dist/reporting/render-mcp-discovery-report.js

@@ -0,0 +1,14 @@
+export function renderMcpDiscoveryReport(report) {
+    return [
+        "MCP Discovery",
+        "=============",
+        `Status: ${report.status}`,
+        `Scope: ${report.scope}`,
+        `Requested protocol: ${report.requestedVersion}`,
+        `Advertised versions: ${report.supportedVersions.join(", ") || "not available"}`,
+        `Discovery response: ${report.coverage.discovery}`,
+        `Runtime: ${report.coverage.runtime}`,
+        "Discovery does not establish full protocol conformance or client compatibility.",
+        ...report.findings.map((finding) => `${finding.severity.toUpperCase()} ${finding.id}: ${finding.message}\n  ${finding.suggestedFix}`)
+    ].join("\n");
+}

package/dist/run-cli.d.ts

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

package/dist/run-cli.js

@@ -21,6 +21,8 @@ import { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestatio
 import { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson } from "./core/output-contract.js";
 import { buildSubmissionArchivePreflight, submissionArchiveExitCode } from "./core/submission-archive-preflight.js";
 import { buildSubmissionPreflight } from "./core/submission-preflight.js";
+import { discoverMcpServer } from "./core/mcp-discovery.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";
 import { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport, CorpusMetricsDiffError, CorpusMetricsManifestError, renderCorpusQualityMetricsDiffJson, renderCorpusQualityMetricsDiffMarkdown, renderCorpusQualityMetricsDiffText, renderCorpusQualityMetricsJson, renderCorpusQualityMetricsMarkdown, renderCorpusQualityMetricsText } from "./core/corpus-quality-metrics.js";
@@ -99,6 +101,7 @@ function writeExactStdout(io, message) {
 }
 class CliUsageError extends Error {
 }
+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");
     if (index === -1) {
@@ -181,6 +184,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("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]");
@@ -1191,6 +1195,34 @@ export async function runCli(args, io = defaultIo, options = {}) {
         return 0;
     }
     if (command === "doctor") {
+        if (maybePath === "discover") {
+            if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
+                io.writeStdout(`${discoveryUsage}\nHTTP discovery only; runtime behavior is not tested.`);
+                return 0;
+            }
+            const [url, ...flags] = remainingArgs;
+            if (!url || url.startsWith("-")) {
+                io.writeStderr(discoveryUsage);
+                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 discovery arguments. ${discoveryUsage}`);
+                return 2;
+            }
+            if (!flags.includes("--allow-network")) {
+                io.writeStderr("doctor discover requires explicit --allow-network consent.");
+                return 2;
+            }
+            const report = await (options.discoverMcpServerImpl ?? discoverMcpServer)(url, {
+                allowNetwork: true,
+                allowLocalNetwork: flags.includes("--allow-local-network")
+            });
+            io.writeStdout(flags.includes("--json")
+                ? JSON.stringify(report, null, 2)
+                : renderMcpDiscoveryReport(report));
+            return report.status === "discovered" ? 0 : report.status === "unsupported" ? 1 : 2;
+        }
         const doctorFlags = maybePath?.startsWith("--")
             ? [maybePath, ...remainingArgs]
             : remainingArgs;

package/package.json

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