fix(cli): support MCP doctor help

src/mcpDoctor.ts

@@ -11,6 +11,17 @@ import { MCP_STARTUP_POLICY } from "./mcpStartupPolicy.js";
 
 const OUTPUT_FORMATS = ["toon", "json", "yaml", "md", "jsonl"] as const;
 type OutputFormat = (typeof OUTPUT_FORMATS)[number];
+const MCP_DOCTOR_HELP = `Usage: rea mcp doctor [options]
+
+Validate MCP server startup, tool and prompt inventories, identity, and request flow.
+
+Options:
+  --json                   Output JSON
+  --format <format>        Output format: ${OUTPUT_FORMATS.join(", ")}
+  --format=<format>        Set the output format
+  --full-output            Include complete diagnostic details
+  -h, --help               Show this help
+`;
 
 interface McpDoctorOptions {
   readonly command: string;
@@ -172,6 +183,8 @@ export const runProductionMcpDoctorCli = async (
   arguments_: readonly string[],
   input: { readonly dispatcherPath: string; readonly packageRoot: string },
 ): Promise<{ readonly output: string; readonly exitCode: number }> => {
+  if (arguments_.includes("--help") || arguments_.includes("-h"))
+    return { output: MCP_DOCTOR_HELP, exitCode: 0 };
   const parsed = parseOutputArguments(arguments_);
   if (!parsed.ok)
     return {

tests/boundary/cli/mcpDoctorHelp.test.ts

@@ -0,0 +1,50 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import { expect, it } from "vitest";
+
+const execute = promisify(execFile);
+
+const runCli = async (arguments_: readonly string[]) => {
+  try {
+    const result = await execute(process.execPath, ["scripts/rea.mjs", ...arguments_], {
+      cwd: process.cwd(),
+      env: { ...process.env, REA_LOG_LEVEL: "silent" },
+      timeout: 15_000,
+    });
+    return { exitCode: 0, ...result };
+  } catch (cause: unknown) {
+    if (
+      typeof cause === "object" &&
+      cause !== null &&
+      "code" in cause &&
+      typeof cause.code === "number" &&
+      "stdout" in cause &&
+      typeof cause.stdout === "string" &&
+      "stderr" in cause &&
+      typeof cause.stderr === "string"
+    )
+      return {
+        exitCode: cause.code,
+        stdout: cause.stdout,
+        stderr: cause.stderr,
+      };
+    throw cause;
+  }
+};
+
+it("shows MCP doctor help without starting a server and keeps option errors actionable", async () => {
+  const parentHelp = await runCli(["mcp", "--help"]);
+  expect(parentHelp.exitCode).toBe(0);
+  expect(parentHelp.stdout).toContain("doctor");
+
+  const help = await runCli(["mcp", "doctor", "--help"]);
+  expect(help.exitCode).toBe(0);
+  expect(help.stdout).toContain("Usage: rea mcp doctor [options]");
+  expect(help.stdout).toContain("--format <format>");
+  expect(help.stdout).toContain("--full-output");
+
+  const invalid = await runCli(["mcp", "doctor", "--not-an-option"]);
+  expect(invalid.exitCode).toBe(1);
+  expect(invalid.stdout).toContain("Unknown mcp doctor option: --not-an-option");
+});