codex-plugin-doctor 1.51.0 → 1.53.0

package/dist/reporting/render-text-report.js

@@ -38,17 +38,39 @@ function appendRuntimeScorecard(lines, result) {
     lines.push(`prompts/list: ${result.runtimeScorecard.promptsList}`);
     lines.push(`prompts/get: ${result.runtimeScorecard.promptGet}`);
     const conformance = result.runtimeScorecard.conformance;
-    if (!conformance) {
-        return;
+    if (conformance) {
+        lines.push("", "MCP Conformance", "---------------");
+        lines.push(`Protocol version: ${conformance.protocolVersion ?? "unavailable"}`);
+        lines.push(`Profile: ${conformance.profile ?? "unavailable"}`);
+        lines.push(`Capability consistency: ${conformance.capabilityConsistency}`);
+        lines.push(`Task declarations: ${conformance.taskDeclarations}`);
+        lines.push(`Tasks list: ${conformance.tasksList}`);
+        lines.push(`Schema dialect: ${conformance.schemaDialect}`);
+        lines.push(`Overall: ${conformance.overall}`);
+    }
+    const remote = result.runtimeScorecard.remote;
+    if (remote) {
+        lines.push("", "Remote MCP Scorecard", "--------------------");
+        lines.push(`transport: ${remote.transport}`);
+        lines.push(`network safety: ${remote.networkSafety}`);
+        lines.push(`initialize: ${remote.initialize}`);
+        lines.push(`content type: ${remote.contentType}`);
+        lines.push(`session: ${remote.session}`);
+        lines.push(`protocol headers: ${remote.protocolHeaders}`);
+        lines.push(`authorization: ${remote.authorization}`);
+        lines.push(`overall: ${remote.overall}`);
+        if (remote.reliability) {
+            const reliability = remote.reliability;
+            lines.push("", "Remote Transport Reliability", "----------------------------");
+            lines.push(`GET SSE: ${reliability.getSse}`);
+            lines.push(`Session propagation: ${reliability.sessionPropagation}`);
+            lines.push(`Resumability: ${reliability.resumability}`);
+            lines.push(`Disconnect safety: ${reliability.disconnectSafety}`);
+            lines.push(`Session restart: ${reliability.sessionRestart}`);
+            lines.push(`Termination: ${reliability.termination}`);
+            lines.push(`Overall: ${reliability.overall}`);
+        }
     }
-    lines.push("", "MCP Conformance", "---------------");
-    lines.push(`Protocol version: ${conformance.protocolVersion ?? "unavailable"}`);
-    lines.push(`Profile: ${conformance.profile ?? "unavailable"}`);
-    lines.push(`Capability consistency: ${conformance.capabilityConsistency}`);
-    lines.push(`Task declarations: ${conformance.taskDeclarations}`);
-    lines.push(`Tasks list: ${conformance.tasksList}`);
-    lines.push(`Schema dialect: ${conformance.schemaDialect}`);
-    lines.push(`Overall: ${conformance.overall}`);
 }
 export function renderTextReport(result, options = {}) {
     const ascii = options.ascii ?? false;

package/dist/rules/rule-catalog.js

@@ -161,6 +161,24 @@ export const ruleCatalog = [
         fix: "Add `command` for stdio servers or `url` for remote servers.",
         example: '{ "command": "node", "args": ["server.js"] }'
     },
+    {
+        id: "mcp.server.transport.conflict",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "An MCP server defines both command and URL transports.",
+        why: "Clients cannot select a transport deterministically when a server defines both process and remote connection settings.",
+        fix: "Keep either command for stdio or url for remote MCP, but not both.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
+    {
+        id: "plugin.mcp.server.transport.conflict",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "A bundled MCP server defines both command and URL transports.",
+        why: "Codex cannot select a transport deterministically when a bundled server defines both process and remote connection settings.",
+        fix: "Keep either command for stdio or url for remote MCP, but not both.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
     {
         id: "plugin.security.path_traversal",
         category: "security",
@@ -245,12 +263,66 @@ export const ruleCatalog = [
     {
         id: "plugin.security.insecure_http_url",
         category: "security",
-        defaultSeverity: "warn",
+        defaultSeverity: "fail",
         summary: "An MCP server uses a plain HTTP URL.",
         why: "Plain HTTP can expose MCP traffic and does not verify endpoint identity on non-local networks.",
         fix: "Use HTTPS for remote MCP servers; reserve HTTP for explicit localhost development endpoints.",
         example: '{ "url": "https://example.com/mcp" }'
     },
+    {
+        id: "plugin.security.remote_mcp_url.invalid",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server URL is not an absolute HTTP or HTTPS URL.",
+        why: "Clients cannot reliably connect to malformed or relative remote MCP endpoints.",
+        fix: "Use an absolute HTTPS URL, or an explicit localhost HTTP development URL.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
+    {
+        id: "plugin.security.remote_mcp_url.unsupported_scheme",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server URL uses an unsupported scheme.",
+        why: "Remote MCP transport supports only HTTP and HTTPS endpoints.",
+        fix: "Use an HTTPS URL, or an explicit localhost HTTP development URL.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
+    {
+        id: "plugin.security.remote_mcp_url.credentials",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server URL embeds credentials.",
+        why: "URL credentials can leak through configuration, logs, reports, and package artifacts.",
+        fix: "Remove URL credentials and configure authentication outside the endpoint URL.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
+    {
+        id: "plugin.security.remote_mcp_url.query",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server URL contains a query string.",
+        why: "Query strings can carry secrets and make endpoint configuration ambiguous.",
+        fix: "Remove the query string from the MCP endpoint URL.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
+    {
+        id: "plugin.security.remote_mcp_url.fragment",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server URL contains a fragment.",
+        why: "Fragments are not sent to servers and can hide misleading endpoint configuration.",
+        fix: "Remove the fragment from the MCP endpoint URL.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
+    {
+        id: "plugin.security.remote_mcp_url.ip_literal",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server URL uses a numeric IP literal.",
+        why: "Numeric IP endpoints bypass hostname-based endpoint review and are not an accepted remote MCP shape.",
+        fix: "Use a reviewed hostname; use localhost only for local development.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
     {
         id: "plugin.security.mcp_binds_all_interfaces",
         category: "security",
@@ -376,6 +448,222 @@ export const ruleCatalog = [
         why: "MCP stdio transport requires newline-delimited JSON-RPC messages on stdout.",
         fix: "Send logs to stderr and reserve stdout for JSON-RPC protocol messages only.",
         example: "Use `console.error` for diagnostics in Node stdio servers."
+    },
+    {
+        id: "plugin.runtime.remote.network_not_approved",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "Remote MCP probing was not explicitly approved.",
+        why: "Remote initialization creates outbound network traffic.",
+        fix: "Review the plan, then use --runtime --allow-network; add --allow-local-network only for localhost HTTP.",
+        example: "codex-plugin-doctor mcp . --runtime --allow-network"
+    },
+    {
+        id: "plugin.runtime.remote.url.invalid",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "A remote MCP endpoint URL is unsafe or unsupported.",
+        why: "Credentials, queries, fragments, IP literals, and unsupported schemes bypass the remote probe boundary.",
+        fix: "Use an absolute HTTPS URL without credentials, query parameters, fragments, or IP literals.",
+        example: "https://mcp.example/mcp"
+    },
+    {
+        id: "plugin.runtime.remote.transport.timeout",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP initialize request timed out.",
+        why: "A bounded probe cannot safely negotiate an unavailable endpoint.",
+        fix: "Make the endpoint reachable and complete initialize within the configured timeout.",
+        example: "Return a valid initialize response promptly."
+    },
+    {
+        id: "plugin.runtime.remote.transport.response_too_large",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP response exceeded the bounded probe limit.",
+        why: "Unbounded remote responses can exhaust local resources.",
+        fix: "Return a compact initialize response and keep discovery metadata bounded.",
+        example: "Return only the MCP initialize result."
+    },
+    {
+        id: "plugin.runtime.remote.transport.failed",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP transport request failed.",
+        why: "Protocol negotiation cannot proceed without a safe bounded connection.",
+        fix: "Verify endpoint reachability, TLS, and remote network policy eligibility.",
+        example: "Use a public HTTPS endpoint or explicitly approved localhost HTTP."
+    },
+    {
+        id: "plugin.runtime.remote.http_status.invalid",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP initialize response used an unexpected HTTP status.",
+        why: "Streamable HTTP initialization requires a successful response before negotiation.",
+        fix: "Return HTTP 200 for initialize or publish valid OAuth discovery metadata for protected endpoints.",
+        example: "HTTP/1.1 200 OK"
+    },
+    {
+        id: "plugin.runtime.remote.content_type.invalid",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP initialize response used an unsupported content type.",
+        why: "The probe can only validate JSON or Server-Sent Events protocol responses.",
+        fix: "Return application/json or text/event-stream with a JSON-RPC response.",
+        example: "Content-Type: application/json"
+    },
+    {
+        id: "plugin.runtime.remote.session.invalid",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP session header is invalid.",
+        why: "An invalid session identifier cannot be safely replayed on the initialized notification.",
+        fix: "Return MCP-Session-Id only as visible ASCII characters.",
+        example: "MCP-Session-Id: session-123"
+    },
+    {
+        id: "plugin.runtime.remote.initialize.invalid",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP initialize JSON-RPC result is invalid.",
+        why: "Invalid negotiation results leave capabilities and protocol version unknown.",
+        fix: "Return a JSON-RPC 2.0 initialize result for protocol version 2025-11-25.",
+        example: '{ "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-11-25" } }'
+    },
+    {
+        id: "plugin.runtime.remote.initialized.failed",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP server did not acknowledge notifications/initialized.",
+        why: "The session may not be ready for subsequent protocol traffic.",
+        fix: "Accept a successful initialized notification at the configured MCP endpoint.",
+        example: "Return HTTP 204 to notifications/initialized."
+    },
+    {
+        id: "plugin.runtime.remote.authorization.metadata.invalid",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "Remote OAuth discovery metadata is invalid.",
+        why: "Protected MCP endpoints cannot be assessed safely without valid authorization metadata.",
+        fix: "Publish valid HTTPS protected-resource and authorization-server metadata.",
+        example: "https://mcp.example/.well-known/oauth-protected-resource"
+    },
+    {
+        id: "plugin.runtime.remote.authorization.metadata.unavailable",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "Remote OAuth discovery metadata is unavailable.",
+        why: "Authorization readiness cannot be confirmed without bounded metadata responses.",
+        fix: "Make protected-resource and authorization-server metadata available over HTTPS.",
+        example: "Return application/json discovery metadata."
+    },
+    {
+        id: "plugin.runtime.remote.reliability.get.status",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP endpoint rejected the SSE transport request.",
+        why: "Clients cannot rely on server-to-client streaming when an accepted SSE request does not return the expected status.",
+        fix: "Return HTTP 200 with a valid SSE response, or HTTP 405 when GET streaming is not supported.",
+        example: "HTTP/1.1 405 Method Not Allowed"
+    },
+    {
+        id: "plugin.runtime.remote.reliability.get.content_type",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP endpoint returned a non-SSE media type for GET streaming.",
+        why: "Clients cannot interpret a successful streaming response unless it is declared as Server-Sent Events.",
+        fix: "Return Content-Type: text/event-stream for accepted GET streaming requests.",
+        example: "Content-Type: text/event-stream"
+    },
+    {
+        id: "plugin.runtime.remote.reliability.get.inconclusive",
+        category: "runtime",
+        defaultSeverity: "warn",
+        summary: "The remote MCP GET streaming check was inconclusive.",
+        why: "A bounded probe could not observe a complete SSE event, so streaming reliability remains uncertain.",
+        fix: "Emit complete SSE event frames promptly when server-to-client streaming is supported.",
+        example: "id: event-1\n\ndata: {}\n\n"
+    },
+    {
+        id: "plugin.runtime.remote.reliability.get.failed",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP GET streaming request could not be completed.",
+        why: "Clients cannot rely on server-to-client streaming when a bounded transport request fails.",
+        fix: "Keep the Streamable HTTP transport reachable within the configured request bounds.",
+        example: "Complete the GET request before the runtime timeout."
+    },
+    {
+        id: "plugin.runtime.remote.reliability.get.malformed",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP endpoint emitted malformed SSE framing.",
+        why: "Malformed event framing prevents clients from safely processing stream progress or reconnecting.",
+        fix: "Return complete SSE events with valid id and retry fields.",
+        example: "id: event-1\n\nevent: message\n\ndata: {}\n\n"
+    },
+    {
+        id: "plugin.runtime.remote.reliability.resume.status",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP endpoint rejected the SSE resume request.",
+        why: "Clients cannot resume a dropped stream when the reconnect response has an unexpected status.",
+        fix: "Return HTTP 200 for an accepted Last-Event-ID reconnect request.",
+        example: "HTTP/1.1 200 OK"
+    },
+    {
+        id: "plugin.runtime.remote.reliability.resume.content_type",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP endpoint returned a non-SSE media type for a resume request.",
+        why: "Clients cannot process a resumed stream unless it is declared as Server-Sent Events.",
+        fix: "Return Content-Type: text/event-stream after accepting a Last-Event-ID reconnect request.",
+        example: "Content-Type: text/event-stream"
+    },
+    {
+        id: "plugin.runtime.remote.reliability.resume.inconclusive",
+        category: "runtime",
+        defaultSeverity: "warn",
+        summary: "The remote MCP SSE resume check was inconclusive.",
+        why: "A bounded probe could not confirm a complete resumed event, so reconnect reliability remains uncertain.",
+        fix: "Emit complete SSE event frames after accepting a reconnect.",
+        example: "Return one complete SSE event after a Last-Event-ID request."
+    },
+    {
+        id: "plugin.runtime.remote.reliability.resume.failed",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP SSE resume request could not be completed.",
+        why: "Clients cannot recover from a dropped stream when a bounded reconnect fails.",
+        fix: "Accept one bounded SSE reconnect using Last-Event-ID.",
+        example: "Honor the Last-Event-ID header on one reconnect."
+    },
+    {
+        id: "plugin.runtime.remote.reliability.resume.malformed",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP endpoint emitted malformed SSE framing after reconnecting.",
+        why: "Malformed resumed events prevent clients from safely continuing stream processing.",
+        fix: "Return complete SSE events with valid id and retry fields after reconnecting.",
+        example: "Return a complete event frame after reconnecting."
+    },
+    {
+        id: "plugin.runtime.remote.reliability.session_restart.failed",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP session could not be restarted.",
+        why: "Clients cannot recover from an expired MCP session when a fresh initialization sequence fails.",
+        fix: "Accept a fresh initialize sequence after an expired MCP session.",
+        example: "Return a valid initialize response after HTTP 404 for a session-bound request."
+    },
+    {
+        id: "plugin.runtime.remote.reliability.termination.failed",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP session could not be terminated.",
+        why: "A server that advertises session lifecycle support must safely handle the approved termination request.",
+        fix: "Return a successful response or HTTP 405 for a bounded MCP session DELETE request.",
+        example: "HTTP/1.1 204 No Content"
     }
 ];
 export function findRuleDefinition(id) {