codex-plugin-doctor 1.59.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`:
@@ -131,21 +146,27 @@ codex-plugin-doctor registry preflight path/to/server.json --allow-network --req
 Preflight checks the exact npm package version, then the exact Registry version
 and latest Registry record on fixed public hosts. An existing exact Registry
 version is an immutable collision and must be replaced by a version bump. The
-command is advisory: it never authenticates, publishes, or changes npm or
-Registry records. See [MCP Registry Publication Preflight](./docs/architecture/mcp-registry-publication-preflight.md).
-
-### Public Directory Submission Preflight
-
-Check a plugin package for deterministic public-directory submission issues without contacting a portal:
-
-```bash
-codex-plugin-doctor doctor submission <path>
-codex-plugin-doctor doctor submission <path> --json
-codex-plugin-doctor doctor submission <path> --markdown
-codex-plugin-doctor doctor submission <path> --require-ready
-```
-
-The preflight is offline and non-executing: it does not submit a package, make network requests, start MCP servers, verify domains, or handle OAuth credentials. Its automatic `status` is `pass` or `fail`; a passing automatic result remains `manual_review_required` until portal-only review is complete. It never claims directory acceptance. See [Public Directory Submission Preflight](./docs/architecture/public-directory-submission-preflight.md).
+command is advisory: it never authenticates, publishes, or changes npm or
+Registry records. See [MCP Registry Publication Preflight](./docs/architecture/mcp-registry-publication-preflight.md).
+
+### Public Directory Submission Preflight
+
+Check a plugin package for deterministic public-directory submission issues without contacting a portal:
+
+```bash
+codex-plugin-doctor doctor submission <path>
+codex-plugin-doctor doctor submission <path> --json
+codex-plugin-doctor doctor submission <path> --markdown
+codex-plugin-doctor doctor submission <path> --require-ready
+codex-plugin-doctor doctor submission archive <zip>
+codex-plugin-doctor doctor submission archive <zip> --json --output submission-archive.json
+codex-plugin-doctor doctor submission archive <zip> --markdown --output submission-archive.md
+codex-plugin-doctor doctor submission archive <zip> --require-ready
+```
+
+The preflight is offline and non-executing: it does not submit a package, make network requests, start MCP servers, verify domains, or handle OAuth credentials. Its automatic `status` is `pass` or `fail`; a passing automatic result remains `manual_review_required` until portal-only review is complete. It never claims directory acceptance. See [Public Directory Submission Preflight](./docs/architecture/public-directory-submission-preflight.md).
+
+The archive variant accepts an existing skills-only ZIP and does not extract archive entries to disk, execute package code, or repair the archive. It reports malformed ZIP structures and deterministic package blockers; unsupported portal rules remain manual or `coverage: unavailable` rather than an automatic pass.
 
 Output formats:
 
@@ -493,9 +514,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.59.0
-        with:
-          version: "1.59.0"
+      - uses: Esquetta/CodexPluginDoctor@v1.61.0
+        with:
+          version: "1.61.0"
           path: .
           runtime: "true"
           policy: codex-publish
@@ -507,7 +528,7 @@ jobs:
           review-bundle-verify: "true"
 ```
 
-The action writes `codex-plugin-doctor-summary.md`, `codex-plugin-doctor-report.json`, `codex-plugin-doctor-action-manifest.json`, optional `codex-plugin-doctor.sarif`, optional validation corpus and quality metrics reports, optional `output-contract.json`, and optional signed `review-bundle/` files to `codex-plugin-doctor-reports`, appends the Markdown report to the GitHub Actions step summary, uploads the report directory as an artifact, and then returns the real validation exit code. Set `submission: "true"` to add offline submission preflight reports; set `require-submission-ready: "true"` only with that opt-in to make automatic blockers fail the job. Review bundle generation requires a signing key environment variable such as `CODEX_PLUGIN_DOCTOR_SIGNING_KEY`. For runtime probing, SARIF output, corpus quality regression gates, corpus and contract artifacts, review bundle artifacts, installed plugin cache checks, CI policy presets, and pinned release examples, see [GitHub Action Usage](./docs/guides/github-action.md).
+The action writes `codex-plugin-doctor-summary.md`, `codex-plugin-doctor-report.json`, `codex-plugin-doctor-action-manifest.json`, optional `codex-plugin-doctor.sarif`, optional validation corpus and quality metrics reports, optional `output-contract.json`, and optional signed `review-bundle/` files to `codex-plugin-doctor-reports`, appends the Markdown report to the GitHub Actions step summary, uploads the report directory as an artifact, and then returns the real validation exit code. Set `submission: "true"` to add offline submission preflight reports; set `require-submission-ready: "true"` only with that opt-in to make automatic blockers fail the job. Review bundle generation requires a signing key environment variable such as `CODEX_PLUGIN_DOCTOR_SIGNING_KEY`. For runtime probing, SARIF output, corpus quality regression gates, corpus and contract artifacts, review bundle artifacts, installed plugin cache checks, CI policy presets, and pinned release examples, see [GitHub Action Usage](./docs/guides/github-action.md).
 
 To self-test this repository after cloning it:
 

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/core/output-contract.js

@@ -262,6 +262,68 @@ const publicSchemaDefinitions = [
             }
         }
     },
+    {
+        id: "doctor.submission.archive.json",
+        command: "codex-plugin-doctor doctor submission archive <zip> --json",
+        required: [
+            "schemaVersion",
+            "rulesetVersion",
+            "status",
+            "readiness",
+            "archive",
+            "summary",
+            "archiveChecks",
+            "submission",
+            "findings",
+            "coverage",
+            "manualChecklist"
+        ],
+        properties: {
+            rulesetVersion: { const: "openai-directory-archive-2026-08-23" },
+            status: { type: "string", enum: ["pass", "fail"] },
+            readiness: { type: "string", enum: ["blocked", "manual_review_required"] },
+            archive: {
+                type: "object",
+                required: ["fileName", "compressedBytes", "uncompressedBytes", "entryCount", "rootLayout"],
+                properties: {
+                    fileName: { type: "string" },
+                    compressedBytes: { type: "integer", minimum: 0 },
+                    uncompressedBytes: { type: "integer", minimum: 0 },
+                    entryCount: { type: "integer", minimum: 0 },
+                    rootLayout: { type: "string", enum: ["archive-root", "single-top-level-directory", "unavailable"] }
+                },
+                additionalProperties: false
+            },
+            summary: {
+                type: "object",
+                required: ["passed", "warnings", "blockers", "manualChecks"],
+                properties: {
+                    passed: { type: "integer", minimum: 0 },
+                    warnings: { type: "integer", minimum: 0 },
+                    blockers: { type: "integer", minimum: 0 },
+                    manualChecks: { type: "integer", minimum: 0 }
+                },
+                additionalProperties: false
+            },
+            archiveChecks: { type: "array" },
+            submission: { type: ["object", "null"] },
+            findings: { type: "array" },
+            coverage: {
+                type: "array",
+                items: {
+                    type: "object",
+                    required: ["id", "status", "reason"],
+                    properties: {
+                        id: { type: "string", pattern: "^plugin\\.submission\\.archive\\." },
+                        status: { type: "string", enum: ["automatic", "manual", "unavailable"] },
+                        reason: { type: "string" }
+                    },
+                    additionalProperties: false
+                }
+            },
+            manualChecklist: { type: "array" }
+        }
+    },
     {
         id: "doctor.installed.check.json",
         command: "codex-plugin-doctor check --installed --json",

package/dist/core/shell-completion.js

@@ -18,6 +18,7 @@ const topLevelCommands = [
     "config"
 ];
 const doctorCommands = ["submission"];
+const submissionTargets = ["archive"];
 const submissionFlags = ["--json", "--markdown", "--output", "--require-ready"];
 const fishSubmissionCondition = "__fish_seen_subcommand_from doctor; and __fish_seen_subcommand_from submission";
 function bashCompletion() {
@@ -30,6 +31,7 @@ function bashCompletion() {
         "",
         `  local commands="${topLevelCommands.join(" ")}"`,
         `  local doctor_commands="${doctorCommands.join(" ")}"`,
+        `  local submission_targets="${submissionTargets.join(" ")}"`,
         `  local submission_flags="${submissionFlags.join(" ")}"`,
         "",
         "  case \"${prev}\" in",
@@ -41,8 +43,25 @@ function bashCompletion() {
         "      COMPREPLY=( $(compgen -W \"${doctor_commands}\" -- \"${cur}\") )",
         "      return 0",
         "      ;;",
+        "    submission)",
+        "      COMPREPLY=( $(compgen -W \"${submission_targets}\" -- \"${cur}\") )",
+        "      return 0",
+        "      ;;",
         "  esac",
         "",
+        "  if [[ ${COMP_WORDS[1]} == \"doctor\" && ${COMP_WORDS[2]} == \"submission\" && ${COMP_WORDS[3]} == \"archive\" ]]; then",
+        "    case \"${cur}\" in",
+        "      --*)",
+        "        COMPREPLY=( $(compgen -W \"${submission_flags}\" -- \"${cur}\") )",
+        "        return 0",
+        "        ;;",
+        "      *)",
+        "        COMPREPLY=( $(compgen -f -- \"${cur}\") )",
+        "        return 0",
+        "        ;;",
+        "    esac",
+        "  fi",
+        "",
         "  case \"${cur}\" in",
         "    --*)",
         "      if [[ ${COMP_WORDS[1]} == \"doctor\" && ${COMP_WORDS[2]} == \"submission\" ]]; then",
@@ -77,6 +96,8 @@ function zshCompletion() {
         "",
         "  if [[ \"$words[2]\" == \"doctor\" && \"$words[3]\" == \"submission\" ]]; then",
         "    _arguments -C \\",
+        "      '3:archive target:(archive)' \\",
+        "      '4:ZIP archive:_files' \\",
         "      '*--json[Output as JSON]' \\",
         "      '*--markdown[Output as Markdown]' \\",
         "      '*--output[Write to file]:file:_files' \\",
@@ -108,6 +129,8 @@ function fishCompletion() {
         `complete -c codex-plugin-doctor -n "${fishSubmissionCondition}" -l markdown -d 'Output as Markdown'`,
         `complete -c codex-plugin-doctor -n "${fishSubmissionCondition}" -l output -d 'Write to file' -r`,
         `complete -c codex-plugin-doctor -n "${fishSubmissionCondition}" -l require-ready -d 'Fail when automatic checks are blocked'`,
+        `complete -c codex-plugin-doctor -n "${fishSubmissionCondition}; and __fish_seen_subcommand_from archive" -F`,
+        `complete -c codex-plugin-doctor -n "${fishSubmissionCondition}; and not __fish_seen_subcommand_from archive" -a "${submissionTargets.join(" ")}" -d 'ZIP archive'`,
         `complete -c codex-plugin-doctor -n "__fish_seen_subcommand_from doctor; and not __fish_seen_subcommand_from ${doctorCommands.join(" ")}" -a "${doctorCommands.join(" ")}"`,
         "complete -c codex-plugin-doctor -l runtime -d 'Enable runtime probes'",
         "complete -c codex-plugin-doctor -l policy -d 'Apply policy' -x -a 'codex-publish mcp-strict security'",

package/dist/core/submission-archive-preflight.d.ts

@@ -0,0 +1,24 @@
+import { type SubmissionArchiveCoverage, type SubmissionArchiveFinding } from "./submission-archive-reader.js";
+import { type SubmissionCheck, type SubmissionFinding, type SubmissionManualCheck, type SubmissionPreflightReport } from "./submission-preflight.js";
+export type SubmissionArchiveRootLayout = "archive-root" | "single-top-level-directory" | "unavailable";
+export interface SubmissionArchivePreflightReport {
+    schemaVersion: "1.0.0";
+    rulesetVersion: "openai-directory-archive-2026-08-23";
+    status: "pass" | "fail";
+    readiness: "blocked" | "manual_review_required";
+    archive: {
+        fileName: string;
+        compressedBytes: number;
+        uncompressedBytes: number;
+        entryCount: number;
+        rootLayout: SubmissionArchiveRootLayout;
+    };
+    summary: SubmissionPreflightReport["summary"];
+    archiveChecks: readonly SubmissionCheck[];
+    submission: SubmissionPreflightReport | null;
+    findings: readonly SubmissionArchiveFinding[] | readonly (SubmissionArchiveFinding | SubmissionFinding)[];
+    coverage: readonly SubmissionArchiveCoverage[];
+    manualChecklist: readonly SubmissionManualCheck[];
+}
+export declare function submissionArchiveExitCode(report: SubmissionArchivePreflightReport, requireReady: boolean): 0 | 1;
+export declare function buildSubmissionArchivePreflight(archivePath: string): Promise<SubmissionArchivePreflightReport>;