metheus-governance-mcp-cli 0.2.1 → 0.2.3

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,10 +36,49 @@ 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.
 
+Local bootstrap tools exposed by proxy:
+
+- `project.summary`
+- `project.describe` (alias)
+- `project.get` (alias)
+
+These tools accept `project_id` and return:
+
+- access state (`granted`, `unauthorized`, `denied`, `not_found`)
+- project metadata (name, org, template, owners, visibility)
+- agenda preview from ctxpack (when available)
+
+`project.summary` automatically syncs ctxpack to local cache:
+- missing local cache -> download
+- same version -> keep current
+- newer server version -> update local cache
+
+Manual ctxpack pull/update:
+
+```bash
+metheus-governance-mcp ctxpack pull --project-id <project_uuid> --base-url https://metheus.gesiaplatform.com
+```
+
+When `workitem.list` returns empty, proxy appends a hint to call `project.summary` first.
+
 ## Auth flow (recommended)
 
 1. Auto login and save token once (default flow: `device -> callback -> manual hint`):

package/cli.mjs

@@ -14,6 +14,8 @@ const DEFAULT_SITE_URL = "https://metheus.gesiaplatform.com";
 const DEFAULT_BASE_URL = `${DEFAULT_SITE_URL}/governance/mcp`;
 const DEFAULT_SERVER_NAME = "metheus-governance-mcp";
 const AUTH_STORE_RELATIVE_PATH = path.join(".metheus", "governance-mcp-auth.json");
+const CTXPACK_CACHE_RELATIVE_DIR = path.join(".metheus", "ctxpack-cache");
+const CTXPACK_META_FILENAME = ".metheus_ctxpack_sync.json";
 const CLI_META = loadCLIMeta();
 const CLI_NAME = CLI_META.name || "metheus-governance-mcp-cli";
 const CLI_VERSION = CLI_META.version || "0.0.0";
@@ -27,7 +29,9 @@ 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",
       "  metheus-governance-mcp auth login [--base-url <url>] [--flow <auto|device|callback|manual>] [--keycloak-url <url>] [--realm <name>] [--client-id <id>] [--open-browser <true|false>] [--callback-port <n>] [--timeout-seconds <n>] [--manual <true|false>]",
       "  metheus-governance-mcp auth set --token <jwt> [--refresh-token <token>] [--base-url <url>]",
@@ -97,6 +101,14 @@ function authStoreFilePath() {
   return path.join(home, AUTH_STORE_RELATIVE_PATH);
 }
 
+function ctxpackCacheRootDir() {
+  const home = String(process.env.USERPROFILE || process.env.HOME || "").trim();
+  if (!home) {
+    return path.resolve(process.cwd(), CTXPACK_CACHE_RELATIVE_DIR);
+  }
+  return path.join(home, CTXPACK_CACHE_RELATIVE_DIR);
+}
+
 function ensureParentDir(filePath) {
   const parent = path.dirname(filePath);
   fs.mkdirSync(parent, { recursive: true });
@@ -857,6 +869,11 @@ function intFromRaw(raw, fallback) {
   return n;
 }
 
+function isUUID(raw) {
+  const value = String(raw || "").trim();
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+}
+
 async function runAuthStatus() {
   const resolved = resolveCurrentAccessToken();
   const token = resolved.token;
@@ -1207,6 +1224,330 @@ async function runAuth(argv) {
   process.exitCode = 1;
 }
 
+async function resolveAccessTokenForCommand(baseURL, timeoutSeconds) {
+  let resolved = resolveCurrentAccessToken();
+  if (resolved.token) return resolved;
+
+  const refreshed = await tryRefreshStoredAccessToken({
+    baseURL,
+    timeoutSeconds,
+  });
+  if (refreshed.ok) {
+    resolved = resolveCurrentAccessToken();
+  }
+  return resolved;
+}
+
+async function runCtxpackPull(flags) {
+  const workspaceMeta = loadWorkspaceMeta(process.cwd());
+  const projectID = String(flags["project-id"] || workspaceMeta.project_id || "").trim();
+  if (!projectID) {
+    process.stderr.write("Missing project_id. Use --project-id <uuid> or run inside a synced ctxpack workspace.\n");
+    process.exitCode = 1;
+    return;
+  }
+  if (!isUUID(projectID)) {
+    process.stderr.write("project_id must be a valid UUID.\n");
+    process.exitCode = 1;
+    return;
+  }
+
+  const siteBaseURL = normalizeSiteBaseURL(flags["base-url"] || DEFAULT_SITE_URL);
+  const timeoutSeconds = intFromRaw(flags["timeout-seconds"], 30);
+  const resolved = await resolveAccessTokenForCommand(siteBaseURL, timeoutSeconds);
+  const token = resolved.token;
+  if (!token) {
+    process.stderr.write(
+      `Missing auth token. Run: metheus-governance-mcp auth login --base-url ${siteBaseURL}\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const summary = await loadProjectSummaryForTool({
+    siteBaseURL,
+    projectID,
+    token,
+    timeoutSeconds,
+    includeCtxpack: true,
+    syncCtxpackLocal: true,
+  });
+  process.stdout.write(`${buildProjectSummaryText(summary)}\n`);
+
+  if (String(summary.access || "") !== "granted") {
+    process.exitCode = 1;
+    return;
+  }
+  const syncStatus = String(summary.ctxpack_sync_status || "").trim();
+  if (syncStatus === "error" || syncStatus === "not_available") {
+    process.exitCode = 1;
+  }
+}
+
+async function runCtxpack(argv) {
+  const { subcommand, flags } = parseCommandAndFlags(argv);
+  if (!subcommand || subcommand === "pull") {
+    await runCtxpackPull(flags);
+    return;
+  }
+  process.stderr.write(`Unknown ctxpack subcommand: ${subcommand}\n`);
+  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);
@@ -1259,6 +1600,592 @@ function postJSON(urlText, timeoutSeconds, token, payload) {
   });
 }
 
+function getJSONWithAuth(urlText, timeoutSeconds, token) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(urlText);
+    const transport = url.protocol === "http:" ? http : https;
+    const req = transport.request(
+      {
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port || (url.protocol === "http:" ? 80 : 443),
+        path: `${url.pathname}${url.search}`,
+        method: "GET",
+        headers: {
+          accept: "application/json",
+          authorization: `Bearer ${token}`,
+        },
+        timeout: Math.max(3, timeoutSeconds) * 1000,
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+        res.on("end", () => {
+          const text = Buffer.concat(chunks).toString("utf8");
+          const statusCode = Number(res.statusCode || 0);
+          if (statusCode >= 200 && statusCode < 300) {
+            try {
+              resolve(JSON.parse(text));
+            } catch {
+              reject(new Error("invalid json response"));
+            }
+            return;
+          }
+          const err = new Error(text.trim() || `http ${statusCode}`);
+          err.statusCode = statusCode;
+          err.responseBody = text;
+          reject(err);
+        });
+      },
+    );
+    req.on("timeout", () => {
+      req.destroy(new Error("http timeout"));
+    });
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+function safeObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return value;
+}
+
+function extractToolCall(requestObj) {
+  const params = safeObject(requestObj?.params);
+  const rawName = params.name ?? params.tool_name ?? params.toolName;
+  const name = String(rawName || "").trim();
+  const rawArgs = params.arguments ?? params.args ?? {};
+  const args = safeObject(rawArgs);
+  return { name, args };
+}
+
+function isJsonRpcMethod(requestObj, expected) {
+  return String(requestObj?.method || "").trim() === expected;
+}
+
+function jsonRpcResult(requestObj, result) {
+  const out = { jsonrpc: "2.0", result };
+  if (Object.prototype.hasOwnProperty.call(requestObj || {}, "id")) {
+    out.id = requestObj.id;
+  }
+  return out;
+}
+
+const LOCAL_PROJECT_TOOL_NAMES = ["project.summary", "project.describe", "project.get"];
+
+function buildProjectSummaryInputSchema() {
+  return {
+    type: "object",
+    properties: {
+      project_id: {
+        type: "string",
+        description: "Project UUID. If omitted, current configured project_id is used.",
+      },
+      include_ctxpack: {
+        type: "boolean",
+        description: "If true, include ctxpack file/agenda preview when available.",
+      },
+      sync_ctxpack_local: {
+        type: "boolean",
+        description:
+          "If true (default), auto-download/update ctxpack files into local cache when project.summary is called.",
+      },
+    },
+    additionalProperties: false,
+  };
+}
+
+function buildLocalToolSpecs() {
+  return [
+    {
+      name: "project.summary",
+      description:
+        "Get project summary and access status for a project ID. Includes agenda preview and auto-syncs local ctxpack cache when available.",
+      inputSchema: buildProjectSummaryInputSchema(),
+    },
+    {
+      name: "project.describe",
+      description:
+        "Alias of project.summary. Use when user asks to describe/explain a project by Project ID.",
+      inputSchema: buildProjectSummaryInputSchema(),
+    },
+    {
+      name: "project.get",
+      description:
+        "Alias of project.summary. Returns project metadata and access status for the given project_id.",
+      inputSchema: buildProjectSummaryInputSchema(),
+    },
+  ];
+}
+
+function normalizeTemplateLabel(rawTemplate) {
+  const value = String(rawTemplate || "").trim().toLowerCase();
+  if (value === "standard") return "Standard Governance";
+  if (value === "agile") return "Agile Workflow";
+  if (value === "blank") return "Blank Project";
+  return value || "Unknown";
+}
+
+function extractAgendaFromFiles(files) {
+  const list = Array.isArray(files) ? files : [];
+  if (!list.length) {
+    return { agenda: "", agendaSource: "", ctxpackFileCount: 0 };
+  }
+  const byPathPriority = [
+    "agenda.md",
+    "readme.md",
+    "docs/agenda.md",
+    "docs/readme.md",
+  ];
+  const normalized = list
+    .map((file) => ({
+      path: String(file?.path || "").trim(),
+      docType: String(file?.doc_type || "").trim().toLowerCase(),
+      content: String(file?.content || "").trim(),
+    }))
+    .filter((file) => file.path && file.content);
+  let selected = normalized.find((file) => byPathPriority.includes(file.path.toLowerCase()));
+  if (!selected) {
+    selected = normalized.find((file) => file.docType === "agenda" || file.docType === "readme");
+  }
+  if (!selected) {
+    selected = normalized[0];
+  }
+  if (!selected) {
+    return { agenda: "", agendaSource: "", ctxpackFileCount: list.length };
+  }
+
+  const lines = selected.content.split(/\r?\n/);
+  let start = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (/^\s{0,3}#{1,6}\s*agenda\b/i.test(lines[i])) {
+      start = i + 1;
+      break;
+    }
+  }
+  let agendaText = "";
+  if (start >= 0) {
+    const picked = [];
+    for (let i = start; i < lines.length; i += 1) {
+      if (/^\s{0,3}#{1,6}\s+/.test(lines[i])) break;
+      picked.push(lines[i]);
+    }
+    agendaText = picked.join("\n").trim();
+  }
+  if (!agendaText) {
+    agendaText = selected.content.slice(0, 700).trim();
+  }
+  if (agendaText.length > 700) {
+    agendaText = `${agendaText.slice(0, 700)}...`;
+  }
+  return {
+    agenda: agendaText,
+    agendaSource: selected.path,
+    ctxpackFileCount: list.length,
+  };
+}
+
+function sanitizeCtxpackRelativePath(rawPath) {
+  const input = String(rawPath || "").trim().replace(/\\/g, "/");
+  if (!input) return "";
+  const withoutLeadingSlash = input.replace(/^\/+/, "");
+  const normalized = path.posix.normalize(withoutLeadingSlash);
+  if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+    return "";
+  }
+  return normalized;
+}
+
+function normalizeCtxpackFiles(files) {
+  const list = Array.isArray(files) ? files : [];
+  const out = [];
+  for (const file of list) {
+    const relPath = sanitizeCtxpackRelativePath(file?.path);
+    if (!relPath) continue;
+    out.push({
+      path: relPath,
+      docType: String(file?.doc_type || "").trim(),
+      content: String(file?.content || ""),
+    });
+  }
+  return out;
+}
+
+function loadCtxpackMeta(metaPath) {
+  try {
+    if (!fs.existsSync(metaPath)) return null;
+    const raw = fs.readFileSync(metaPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function hasAllCtxpackFiles(baseDir, files) {
+  for (const file of files) {
+    const target = path.join(baseDir, file.path);
+    if (!fs.existsSync(target)) return false;
+  }
+  return true;
+}
+
+function syncCtxpackToLocalCache({ siteBaseURL, projectID, ctxpack }) {
+  const ctxpackID = String(ctxpack?.ctxpack_id || "").trim();
+  const version = String(ctxpack?.version || "").trim();
+  const status = String(ctxpack?.status || "").trim() || "draft";
+  const files = normalizeCtxpackFiles(ctxpack?.files);
+  const cacheDir = path.join(ctxpackCacheRootDir(), projectID);
+  const metaPath = path.join(cacheDir, CTXPACK_META_FILENAME);
+
+  if (!ctxpackID || !version || files.length === 0) {
+    return {
+      sync_status: "not_available",
+      sync_message: "Ctxpack is missing or has no files on server.",
+      local_path: cacheDir,
+      local_file_count: 0,
+    };
+  }
+
+  const remoteSig = `${ctxpackID}|${version}|${status}|${files.length}`;
+  const previousMeta = loadCtxpackMeta(metaPath);
+  const previousSig = previousMeta
+    ? `${String(previousMeta.ctxpack_id || "").trim()}|${String(previousMeta.version || "").trim()}|${String(previousMeta.status || "").trim()}|${Number.parseInt(String(previousMeta.files_count || 0), 10) || 0}`
+    : "";
+
+  if (previousSig === remoteSig && hasAllCtxpackFiles(cacheDir, files)) {
+    return {
+      sync_status: "current",
+      sync_message: "Local ctxpack cache is up to date.",
+      local_path: cacheDir,
+      local_file_count: files.length,
+    };
+  }
+
+  try {
+    fs.rmSync(cacheDir, { recursive: true, force: true });
+    fs.mkdirSync(cacheDir, { recursive: true });
+
+    for (const file of files) {
+      const target = path.join(cacheDir, file.path);
+      ensureParentDir(target);
+      fs.writeFileSync(target, file.content, "utf8");
+    }
+
+    const payload = {
+      project_id: projectID,
+      ctxpack_id: ctxpackID,
+      version,
+      status,
+      files_count: files.length,
+      files: files.map((f) => ({ path: f.path, doc_type: f.docType || "" })),
+      source: `${String(siteBaseURL || "").replace(/\/+$/, "")}/api/v1/projects/${encodeURIComponent(projectID)}/ctxpack`,
+      synced_at: new Date().toISOString(),
+    };
+    fs.writeFileSync(metaPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+
+    return {
+      sync_status: previousMeta ? "updated" : "downloaded",
+      sync_message: previousMeta
+        ? "Ctxpack updated to latest server version."
+        : "Ctxpack downloaded to local cache.",
+      local_path: cacheDir,
+      local_file_count: files.length,
+    };
+  } catch (err) {
+    return {
+      sync_status: "error",
+      sync_message: String(err?.message || err),
+      local_path: cacheDir,
+      local_file_count: 0,
+    };
+  }
+}
+
+async function loadProjectSummaryForTool({
+  siteBaseURL,
+  projectID,
+  token,
+  timeoutSeconds,
+  includeCtxpack,
+  syncCtxpackLocal,
+}) {
+  const encodedProjectID = encodeURIComponent(projectID);
+  let projectRaw = null;
+  try {
+    projectRaw = await getJSONWithAuth(`${siteBaseURL}/api/v1/projects/${encodedProjectID}`, timeoutSeconds, token);
+  } catch (err) {
+    const statusCode = Number(err?.statusCode || 0);
+    const access =
+      statusCode === 401
+        ? "unauthorized"
+        : statusCode === 403
+          ? "denied"
+          : statusCode === 404
+            ? "not_found"
+            : "error";
+    const message =
+      access === "unauthorized"
+        ? "Token is invalid or expired. Please run auth login again."
+        : access === "denied"
+          ? "Your token account has no access to this project."
+          : access === "not_found"
+            ? "Project not found or not visible with current permissions."
+            : "Failed to read project summary from server.";
+    return {
+      project_id: projectID,
+      access,
+      status_code: statusCode || 500,
+      message,
+      can_access: false,
+    };
+  }
+  const project = safeObject(projectRaw);
+
+  let agenda = "";
+  let agendaSource = "";
+  let ctxpackID = "";
+  let ctxpackVersion = "";
+  let ctxpackFileCount = 0;
+  let ctxpackSyncStatus = includeCtxpack && syncCtxpackLocal ? "not_attempted" : "disabled";
+  let ctxpackSyncMessage = "";
+  let ctxpackLocalPath = "";
+  let ctxpackLocalFileCount = 0;
+  if (includeCtxpack) {
+    try {
+      const ctxpackRaw = await getJSONWithAuth(`${siteBaseURL}/api/v1/projects/${encodedProjectID}/ctxpack`, timeoutSeconds, token);
+      const ctxpack = safeObject(ctxpackRaw);
+      const extracted = extractAgendaFromFiles(ctxpack.files);
+      agenda = extracted.agenda;
+      agendaSource = extracted.agendaSource;
+      ctxpackFileCount = extracted.ctxpackFileCount;
+      ctxpackID = String(ctxpack.ctxpack_id || "").trim();
+      ctxpackVersion = String(ctxpack.version || "").trim();
+      if (syncCtxpackLocal) {
+        const syncResult = syncCtxpackToLocalCache({
+          siteBaseURL,
+          projectID,
+          ctxpack,
+        });
+        ctxpackSyncStatus = syncResult.sync_status || "error";
+        ctxpackSyncMessage = String(syncResult.sync_message || "").trim();
+        ctxpackLocalPath = String(syncResult.local_path || "").trim();
+        ctxpackLocalFileCount = Number(syncResult.local_file_count || 0);
+      }
+    } catch {
+      // ctxpack may be missing; keep project summary anyway.
+      if (syncCtxpackLocal) {
+        ctxpackSyncStatus = "not_available";
+        ctxpackSyncMessage = "Ctxpack is not available for this project.";
+      }
+    }
+  }
+
+  return {
+    project_id: String(project.id || projectID),
+    access: "granted",
+    status_code: 200,
+    message: "Project access granted",
+    can_access: true,
+    name: String(project.name || "").trim(),
+    org_id: String(project.org_id || "").trim(),
+    org_name: String(project.org_name || "").trim(),
+    visibility: String(project.visibility || "").trim() || "private",
+    template: String(project.template || "").trim() || "blank",
+    template_label: normalizeTemplateLabel(project.template),
+    owner_name: String(project.owner_name || "").trim(),
+    program_owner_name: String(project.program_owner_name || "").trim(),
+    tech_owner_name: String(project.tech_owner_name || "").trim(),
+    governance_owner_name: String(project.governance_owner_name || "").trim(),
+    member_count: Number(project.member_count || 0),
+    created_at: String(project.created_at || "").trim(),
+    ctxpack_id: ctxpackID,
+    ctxpack_version: ctxpackVersion,
+    ctxpack_file_count: ctxpackFileCount,
+    ctxpack_sync_status: ctxpackSyncStatus,
+    ctxpack_sync_message: ctxpackSyncMessage,
+    ctxpack_local_path: ctxpackLocalPath,
+    ctxpack_local_file_count: ctxpackLocalFileCount,
+    agenda,
+    agenda_source: agendaSource,
+  };
+}
+
+function buildProjectSummaryText(summary) {
+  if (String(summary?.access || "") !== "granted") {
+    return [
+      `Project ID: ${summary?.project_id || "-"}`,
+      `Access: ${summary?.access || "error"}`,
+      `Status: ${summary?.status_code || "-"}`,
+      `${summary?.message || "Unable to access project summary."}`,
+    ].join("\n");
+  }
+
+  const lines = [
+    `Project ID: ${summary.project_id || "-"}`,
+    `Name: ${summary.name || "-"}`,
+    `Organization: ${summary.org_name || summary.org_id || "-"}`,
+    `Visibility: ${summary.visibility || "-"}`,
+    `Template: ${summary.template_label || summary.template || "-"}`,
+    `Owner: ${summary.owner_name || "-"}`,
+    `Program Owner: ${summary.program_owner_name || "-"}`,
+    `Tech Owner: ${summary.tech_owner_name || "-"}`,
+    `Governance Owner: ${summary.governance_owner_name || "-"}`,
+    `Member Count: ${Number(summary.member_count || 0)}`,
+  ];
+  if (summary.ctxpack_id) {
+    lines.push(`Ctxpack: ${summary.ctxpack_id}${summary.ctxpack_version ? ` (v${summary.ctxpack_version})` : ""}`);
+  }
+  if (summary.ctxpack_sync_status && summary.ctxpack_sync_status !== "disabled") {
+    lines.push(
+      `Ctxpack Sync: ${summary.ctxpack_sync_status}${summary.ctxpack_local_path ? ` (${summary.ctxpack_local_path})` : ""}`,
+    );
+    if (summary.ctxpack_sync_message) {
+      lines.push(`Ctxpack Sync Message: ${summary.ctxpack_sync_message}`);
+    }
+  }
+  if (summary.agenda) {
+    lines.push("");
+    lines.push(`Agenda (${summary.agenda_source || "ctxpack"}):`);
+    lines.push(summary.agenda);
+  }
+  return lines.join("\n");
+}
+
+function parseGatewayResponseText(text) {
+  try {
+    const obj = JSON.parse(String(text || ""));
+    return safeObject(obj);
+  } catch {
+    return null;
+  }
+}
+
+function ensureArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function appendLocalToolToToolsList(responseObj) {
+  const result = safeObject(responseObj.result);
+  const tools = ensureArray(result.tools);
+  const localSpecs = buildLocalToolSpecs();
+  const localNames = new Set(localSpecs.map((spec) => spec.name));
+  const filtered = tools.filter((tool) => !localNames.has(String(tool?.name || "").trim()));
+  result.tools = [...localSpecs, ...filtered];
+  responseObj.result = result;
+  return responseObj;
+}
+
+function appendProjectHintToInitialize(responseObj, args) {
+  const result = safeObject(responseObj.result);
+  const hintLines = [
+    "High-priority project bootstrap rule:",
+    "- MUST call `project.summary` first when the user provides only a Project ID or asks project overview/agenda.",
+    "- `project.describe` and `project.get` are aliases of `project.summary`.",
+    "- After project summary, use workitem/evidence/decision tools as follow-up.",
+  ];
+  if (args.projectID) {
+    hintLines.splice(1, 0, `- Default project_id is ${args.projectID}.`);
+  }
+  const hint = `${hintLines.join("\n")}\n`;
+  const current = String(result.instructions || "").trimEnd();
+  result.instructions = current ? `${hint}\n${current}` : hint;
+  responseObj.result = result;
+  return responseObj;
+}
+
+async function appendWorkitemListHints(responseObj, args, toolArgs, token) {
+  const result = safeObject(responseObj.result);
+  const content = ensureArray(result.content);
+  if (!content.length) return responseObj;
+
+  const first = safeObject(content[0]);
+  if (String(first.type || "") !== "text") return responseObj;
+
+  const text = String(first.text || "");
+  if (!text) return responseObj;
+  if (text.includes("Call `project.summary`")) return responseObj;
+
+  const parsed = parseGatewayResponseText(text);
+  if (!parsed) return responseObj;
+
+  const tool = String(parsed.tool || "").trim();
+  const status = Number(parsed.status || 0);
+  const ok = Boolean(parsed.ok);
+  const body = Array.isArray(parsed.body) ? parsed.body : [];
+  const isEmptyBody = body.length === 0;
+  if (tool !== "workitem.list" || status !== 200 || !ok) {
+    return responseObj;
+  }
+
+  const nextLines = [""];
+  if (isEmptyBody) {
+    nextLines.push("No work items found for this project.");
+    nextLines.push("- Call `project.summary` to confirm project context/agenda and access state first.");
+  }
+
+  let responseProjectID = "";
+  try {
+    const responseURL = String(parsed.url || "").trim();
+    if (responseURL) {
+      responseProjectID = String(new URL(responseURL).searchParams.get("project_id") || "").trim();
+    }
+  } catch {
+    // ignore malformed URL in text payload
+  }
+
+  const projectID = String(
+    toolArgs?.project_id || toolArgs?.projectID || responseProjectID || args.projectID || "",
+  ).trim();
+
+  if (projectID && isUUID(projectID)) {
+    try {
+      const summary = await loadProjectSummaryForTool({
+        siteBaseURL: normalizeSiteBaseURL(args.baseURL),
+        projectID,
+        token,
+        timeoutSeconds: args.timeoutSeconds,
+        includeCtxpack: isEmptyBody,
+        syncCtxpackLocal: isEmptyBody,
+      });
+      if (String(summary.access || "") === "granted") {
+        nextLines.push("Project context:");
+        nextLines.push(`- Name: ${summary.name || "-"}`);
+        nextLines.push(`- Organization: ${summary.org_name || summary.org_id || "-"}`);
+        nextLines.push(`- Visibility: ${summary.visibility || "-"}`);
+        nextLines.push(`- Template: ${summary.template_label || summary.template || "-"}`);
+        if (isEmptyBody && summary.ctxpack_sync_status) {
+          nextLines.push(`- Ctxpack Sync: ${summary.ctxpack_sync_status}`);
+          if (summary.ctxpack_sync_message) {
+            nextLines.push(`- Ctxpack Sync Message: ${summary.ctxpack_sync_message}`);
+          }
+        }
+      } else {
+        nextLines.push("Project access status:");
+        nextLines.push(`- Access: ${summary.access || "error"}`);
+        nextLines.push(`- Status: ${summary.status_code || "-"}`);
+      }
+    } catch {
+      // keep gateway response even when side lookup fails
+    }
+  } else if (projectID) {
+    nextLines.push(`Current project_id: ${projectID}`);
+    nextLines.push("- project_id format is invalid. Expected UUID.");
+  }
+
+  if (nextLines.length <= 1) return responseObj;
+
+  content[0] = {
+    ...first,
+    text: `${text}\n${nextLines.join("\n")}`,
+  };
+  result.content = content;
+  responseObj.result = result;
+  return responseObj;
+}
+
 async function runProxy(flags) {
   const workspaceMeta = loadWorkspaceMeta(process.cwd());
   const args = {
@@ -1327,14 +2254,80 @@ async function runProxy(flags) {
       return;
     }
 
+    const { name: toolName, args: toolArgs } = extractToolCall(requestObj);
+    if (isJsonRpcMethod(requestObj, "tools/call") && LOCAL_PROJECT_TOOL_NAMES.includes(toolName)) {
+      const projectID = String(toolArgs.project_id || toolArgs.projectID || args.projectID || "").trim();
+      if (!projectID) {
+        process.stdout.write(
+          `${JSON.stringify(jsonRpcError(requestObj, -32001, "project_id is required (or set --project-id during setup)"))}\n`,
+        );
+        return;
+      }
+      if (!isUUID(projectID)) {
+        process.stdout.write(
+          `${JSON.stringify(jsonRpcError(requestObj, -32001, "project_id must be a valid UUID"))}\n`,
+        );
+        return;
+      }
+      try {
+        const includeCtxpack = boolFromRaw(
+          Object.prototype.hasOwnProperty.call(toolArgs, "include_ctxpack")
+            ? toolArgs.include_ctxpack
+            : toolArgs.includeCtxpack,
+          true,
+        );
+        const syncCtxpackLocal = boolFromRaw(
+          Object.prototype.hasOwnProperty.call(toolArgs, "sync_ctxpack_local")
+            ? toolArgs.sync_ctxpack_local
+            : toolArgs.syncCtxpackLocal,
+          true,
+        );
+        const summary = await loadProjectSummaryForTool({
+          siteBaseURL: normalizeSiteBaseURL(args.baseURL),
+          projectID,
+          token,
+          timeoutSeconds: args.timeoutSeconds,
+          includeCtxpack,
+          syncCtxpackLocal,
+        });
+        const text = buildProjectSummaryText(summary);
+        process.stdout.write(
+          `${JSON.stringify(
+            jsonRpcResult(requestObj, {
+              content: [
+                {
+                  type: "text",
+                  text,
+                },
+              ],
+              structuredContent: summary,
+            }),
+          )}\n`,
+        );
+      } catch (err) {
+        process.stdout.write(
+          `${JSON.stringify(jsonRpcError(requestObj, -32001, String(err?.message || err)))}\n`,
+        );
+      }
+      return;
+    }
+
     try {
-      const responseText = await postJSON(
-        gatewayURL,
-        args.timeoutSeconds,
-        token,
-        requestObj,
-      );
+      const responseText = await postJSON(gatewayURL, args.timeoutSeconds, token, requestObj);
       if (responseText) {
+        const parsed = parseGatewayResponseText(responseText);
+        if (parsed && !parsed.error) {
+          let patched = parsed;
+          if (isJsonRpcMethod(requestObj, "tools/list")) {
+            patched = appendLocalToolToToolsList(patched);
+          } else if (isJsonRpcMethod(requestObj, "initialize")) {
+            patched = appendProjectHintToInitialize(patched, args);
+          } else if (isJsonRpcMethod(requestObj, "tools/call") && toolName === "workitem.list") {
+            patched = await appendWorkitemListHints(patched, args, toolArgs, token);
+          }
+          process.stdout.write(`${JSON.stringify(patched)}\n`);
+          return;
+        }
         process.stdout.write(`${responseText}\n`);
         return;
       }
@@ -1517,10 +2510,18 @@ async function main() {
     runSetup(flags);
     return;
   }
+  if (command === "doctor") {
+    await runDoctor(flags);
+    return;
+  }
   if (command === "auth") {
     await runAuth(rest);
     return;
   }
+  if (command === "ctxpack") {
+    await runCtxpack(rest);
+    return;
+  }
   if (command === "proxy") {
     await runProxy(flags);
     return;

package/package.json

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