metheus-governance-mcp-cli 0.2.2 → 0.2.4

package/README.md

@@ -8,6 +8,7 @@ Metheus Governance MCP helper CLI.
   - checks Codex/Claude MCP registration
   - registers only missing clients
 - `setup`: register `metheus-governance-mcp` into Codex/Claude (if installed)
+- `doctor`: run end-to-end health checks (auth/registration/gateway/project/ctxpack/tools)
 - `proxy`: stdio MCP bridge to Metheus HTTPS gateway
 - `auth`: save/check/clear local Metheus token used by proxy
 
@@ -35,6 +36,20 @@ metheus-governance-mcp setup --project-id <project_uuid> --ctxpack-key "<ctxpack
 
 `project-id` can be omitted if your current folder (or parent) has `.metheus_ctxpack_sync.json`.
 
+## Doctor
+
+```bash
+metheus-governance-mcp doctor --project-id <project_uuid> --base-url https://metheus.gesiaplatform.com
+```
+
+Checks:
+- auth token status (+ auto refresh attempt)
+- codex/claude registration state
+- gateway `tools/list` reachability
+- `project.summary` access
+- ctxpack auto sync status
+- smoke calls: `workitem.list`, `evidence.list`, `decision.list`
+
 ## Use in MCP
 
 `setup` auto-registers this server for `codex` and `claude` when those CLIs are available.

package/cli.mjs

@@ -29,6 +29,7 @@ function printUsage() {
       "  metheus-governance-mcp [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--flow <auto|device|callback|manual>]",
       "  metheus-governance-mcp init [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--flow <auto|device|callback|manual>]",
       "  metheus-governance-mcp setup [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--name <server_name>]",
+      "  metheus-governance-mcp doctor [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--timeout-seconds <n>]",
       "  metheus-governance-mcp proxy [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--include-drafts <true|false>] [--timeout-seconds <n>]",
       "  metheus-governance-mcp ctxpack pull [--project-id <uuid>] [--base-url <url>] [--timeout-seconds <n>]",
       "  metheus-governance-mcp auth status",
@@ -1293,6 +1294,260 @@ async function runCtxpack(argv) {
   process.exitCode = 1;
 }
 
+function addDoctorCheck(rows, status, label, detail) {
+  rows.push({
+    status: String(status || "").trim().toLowerCase() || "warn",
+    label: String(label || "").trim() || "check",
+    detail: String(detail || "").trim(),
+  });
+}
+
+function statusIcon(status) {
+  if (status === "ok") return "OK";
+  if (status === "fail") return "FAIL";
+  return "WARN";
+}
+
+function printDoctorReport({ context, rows }) {
+  const total = rows.length;
+  const okCount = rows.filter((r) => r.status === "ok").length;
+  const warnCount = rows.filter((r) => r.status === "warn").length;
+  const failCount = rows.filter((r) => r.status === "fail").length;
+
+  process.stdout.write("Governance MCP doctor\n");
+  process.stdout.write(`Gateway: ${context.baseURL}/governance/mcp\n`);
+  process.stdout.write(`Project: ${context.projectID || "(not set)"}\n`);
+  process.stdout.write("\nChecks\n");
+  for (const row of rows) {
+    process.stdout.write(`[${statusIcon(row.status)}] ${row.label}`);
+    if (row.detail) {
+      process.stdout.write(` - ${row.detail}`);
+    }
+    process.stdout.write("\n");
+  }
+  process.stdout.write(
+    `\nSummary: total=${total}, ok=${okCount}, warn=${warnCount}, fail=${failCount}\n`,
+  );
+}
+
+function parseToolEnvelopeFromRPCResult(resultObj) {
+  const result = safeObject(resultObj);
+  const content = ensureArray(result.content);
+  if (!content.length) return null;
+  const first = safeObject(content[0]);
+  const text = String(first.text || "").trim();
+  if (!text) return null;
+  const parsed = parseGatewayResponseText(text);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  return parsed;
+}
+
+async function callGatewayRPC({ gatewayURL, timeoutSeconds, token, requestObj }) {
+  try {
+    const responseText = await postJSON(gatewayURL, timeoutSeconds, token, requestObj);
+    const parsed = parseGatewayResponseText(responseText);
+    if (!parsed) {
+      return { ok: false, error: "invalid JSON-RPC response from gateway" };
+    }
+    if (parsed.error) {
+      const errObj = safeObject(parsed.error);
+      const code = Number(errObj.code || 0);
+      const message = String(errObj.message || "").trim() || JSON.stringify(parsed.error);
+      return { ok: false, error: `rpc ${code}: ${message}`, response: parsed };
+    }
+    return { ok: true, response: parsed };
+  } catch (err) {
+    return { ok: false, error: String(err?.message || err) };
+  }
+}
+
+async function runDoctor(flags) {
+  const context = resolveSetupContext(flags);
+  const timeoutSeconds = intFromRaw(flags["timeout-seconds"], 30);
+  const gatewayURL = buildGatewayURL({
+    baseURL: `${context.baseURL}/governance/mcp`,
+    projectID: context.projectID,
+    ctxpackKey: context.ctxpackKey,
+    includeDrafts: true,
+  });
+  const rows = [];
+
+  const resolved = await resolveAccessTokenForCommand(context.baseURL, timeoutSeconds);
+  const token = resolved.token;
+  if (!token) {
+    addDoctorCheck(
+      rows,
+      "fail",
+      "auth token",
+      `missing. Run: metheus-governance-mcp auth login --base-url ${context.baseURL}`,
+    );
+  } else {
+    addDoctorCheck(
+      rows,
+      "ok",
+      "auth token",
+      `configured (${resolved.source || "unknown"}${tokenExpiryIso(token) ? `, expires ${tokenExpiryIso(token)}` : ""})`,
+    );
+  }
+
+  for (const cliBin of ["codex", "claude"]) {
+    if (!commandExists(cliBin)) {
+      addDoctorCheck(rows, "warn", `${cliBin} CLI`, "not installed; registration check skipped");
+      continue;
+    }
+    const registered = isRegistered(cliBin, context.serverName);
+    if (registered) {
+      addDoctorCheck(rows, "ok", `${cliBin} registration`, `${context.serverName} registered`);
+    } else {
+      addDoctorCheck(
+        rows,
+        "fail",
+        `${cliBin} registration`,
+        `${context.serverName} missing. Run: metheus-governance-mcp setup --base-url ${context.baseURL}`,
+      );
+    }
+  }
+
+  if (!token) {
+    printDoctorReport({ context, rows });
+    process.exitCode = 1;
+    return;
+  }
+
+  const toolsListCall = await callGatewayRPC({
+    gatewayURL,
+    timeoutSeconds,
+    token,
+    requestObj: { jsonrpc: "2.0", id: 1, method: "tools/list", params: {} },
+  });
+  if (!toolsListCall.ok) {
+    addDoctorCheck(rows, "fail", "gateway tools/list", toolsListCall.error || "unknown error");
+    printDoctorReport({ context, rows });
+    process.exitCode = 1;
+    return;
+  }
+
+  const toolsListResult = safeObject(safeObject(toolsListCall.response).result);
+  const toolsCount = ensureArray(toolsListResult.tools).length;
+  addDoctorCheck(rows, "ok", "gateway tools/list", `reachable (${toolsCount} tools)`);
+
+  if (!context.projectID) {
+    addDoctorCheck(
+      rows,
+      "warn",
+      "project summary",
+      "project_id not set. Provide --project-id to validate access and ctxpack sync.",
+    );
+    printDoctorReport({ context, rows });
+    process.exitCode = rows.some((r) => r.status === "fail") ? 1 : 0;
+    return;
+  }
+
+  if (!isUUID(context.projectID)) {
+    addDoctorCheck(rows, "fail", "project_id format", "project_id must be a valid UUID");
+    printDoctorReport({ context, rows });
+    process.exitCode = 1;
+    return;
+  }
+
+  const summary = await loadProjectSummaryForTool({
+    siteBaseURL: context.baseURL,
+    projectID: context.projectID,
+    token,
+    timeoutSeconds,
+    includeCtxpack: true,
+    syncCtxpackLocal: true,
+  });
+  if (String(summary.access || "") !== "granted") {
+    addDoctorCheck(
+      rows,
+      "fail",
+      "project.summary",
+      `${summary.message || "access denied"} (status ${summary.status_code || "-"})`,
+    );
+    printDoctorReport({ context, rows });
+    process.exitCode = 1;
+    return;
+  }
+  addDoctorCheck(
+    rows,
+    "ok",
+    "project.summary",
+    `${summary.name || context.projectID} (${summary.visibility || "-"}, ${summary.template_label || summary.template || "-"})`,
+  );
+
+  const syncStatus = String(summary.ctxpack_sync_status || "").trim();
+  if (["downloaded", "updated", "current"].includes(syncStatus)) {
+    addDoctorCheck(
+      rows,
+      "ok",
+      "ctxpack sync",
+      `${syncStatus}${summary.ctxpack_local_path ? ` (${summary.ctxpack_local_path})` : ""}`,
+    );
+  } else if (syncStatus === "not_available") {
+    addDoctorCheck(rows, "warn", "ctxpack sync", summary.ctxpack_sync_message || "ctxpack not available");
+  } else {
+    addDoctorCheck(rows, "fail", "ctxpack sync", summary.ctxpack_sync_message || "ctxpack sync failed");
+  }
+
+  const smokeCalls = [
+    {
+      tool: "workitem.list",
+      args: { project_id: context.projectID, limit: 1, offset: 0 },
+    },
+    {
+      tool: "evidence.list",
+      args: { project_id: context.projectID, limit: 1, offset: 0 },
+    },
+    {
+      tool: "decision.list",
+      args: { project_id: context.projectID, limit: 1, offset: 0 },
+    },
+  ];
+
+  for (let idx = 0; idx < smokeCalls.length; idx += 1) {
+    const row = smokeCalls[idx];
+    const rpc = await callGatewayRPC({
+      gatewayURL,
+      timeoutSeconds,
+      token,
+      requestObj: {
+        jsonrpc: "2.0",
+        id: 200 + idx,
+        method: "tools/call",
+        params: {
+          name: row.tool,
+          arguments: row.args,
+        },
+      },
+    });
+    if (!rpc.ok) {
+      addDoctorCheck(rows, "fail", `smoke ${row.tool}`, rpc.error || "rpc error");
+      continue;
+    }
+    const envelope = parseToolEnvelopeFromRPCResult(safeObject(rpc.response).result);
+    if (!envelope) {
+      addDoctorCheck(rows, "warn", `smoke ${row.tool}`, "no parsable tool envelope in response");
+      continue;
+    }
+    const status = Number(envelope.status || 0);
+    const ok = Boolean(envelope.ok);
+    if (ok && status >= 200 && status < 300) {
+      addDoctorCheck(rows, "ok", `smoke ${row.tool}`, `status ${status}`);
+    } else {
+      addDoctorCheck(
+        rows,
+        "fail",
+        `smoke ${row.tool}`,
+        `status ${status || "-"}, ok=${ok ? "true" : "false"}`,
+      );
+    }
+  }
+
+  printDoctorReport({ context, rows });
+  process.exitCode = rows.some((r) => r.status === "fail") ? 1 : 0;
+}
+
 function buildGatewayURL(args) {
   const base = String(args.baseURL || DEFAULT_BASE_URL).trim() || DEFAULT_BASE_URL;
   const url = new URL(base);
@@ -2255,6 +2510,10 @@ async function main() {
     runSetup(flags);
     return;
   }
+  if (command === "doctor") {
+    await runDoctor(flags);
+    return;
+  }
   if (command === "auth") {
     await runAuth(rest);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metheus-governance-mcp-cli",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [