metheus-governance-mcp-cli 0.2.24 → 0.2.26

package/README.md

@@ -7,9 +7,9 @@ Compatibility note: legacy command alias `metheus-governance-mcp` is still suppo
 - `metheus-governance-mcp-cli` (no args): bootstrap mode
   - checks auth token
   - if token is missing/expired, starts `auth login`
-  - checks Codex/Claude MCP registration
+  - checks Codex/Claude/Gemini/Antigravity/Cursor MCP registration
   - registers only missing clients
-- `setup`: register `metheus-governance-mcp` into Codex/Claude (if installed)
+- `setup`: register `metheus-governance-mcp` into Codex/Claude/Gemini/Antigravity/Cursor (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
@@ -40,12 +40,15 @@ metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctx
 `setup` defaults to `--workspace-dir auto` (dynamic workspace detection).
 Use an explicit path only when you intentionally want a fixed workspace.
 
-Recommended for Codex/Claude multi-workspace sessions:
+Recommended for Codex/Claude/Gemini/Antigravity/Cursor multi-workspace sessions:
 
 ```bash
 metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctxpack_key>" --base-url https://metheus.gesiaplatform.com --workspace-dir auto
 ```
 
+Gemini CLI note:
+- `gemini mcp` commands require Gemini auth to be configured first (`GEMINI_API_KEY` or `~/.gemini/settings.json` auth).
+
 When a client does not send workspace metadata (for example some Codex sessions),
 set a stable fallback root once:
 
@@ -53,7 +56,9 @@ set a stable fallback root once:
 metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctxpack_key>" --base-url https://metheus.gesiaplatform.com --workspace-dir auto --workspace-fallback-dir C:\code_test
 ```
 
-This registers `METHEUS_WORKSPACE_DIR` for Codex MCP so ctxpack sync still resolves safely.
+This sets fallback workspace context for clients that do not pass workspace metadata:
+- Codex/Antigravity/Cursor: `METHEUS_WORKSPACE_DIR` env
+- Gemini: pinned `--workspace-dir <fallback>` in registered MCP command
 
 Guardrail note:
 - By default, CLI blocks reading/writing ctxpack sync metadata when workspace root resolves to the home directory.
@@ -76,7 +81,7 @@ metheus-governance-mcp-cli doctor --project-id <project_uuid> --base-url https:/
 
 Checks:
 - auth token status (+ auto refresh attempt)
-- codex/claude registration state
+- codex/claude/gemini/antigravity/cursor registration state
 - gateway `tools/list` reachability
 - `project.summary` access
 - ctxpack auto sync status
@@ -84,7 +89,13 @@ Checks:
 
 ## Use in MCP
 
-`setup` auto-registers this server for `codex` and `claude` when those CLIs are available.
+`setup` auto-registers this server for `codex`, `claude`, `gemini`, `antigravity`, and `cursor` when those CLIs are available.
+
+Antigravity note:
+- this CLI manages MCP registration via Antigravity local config file (`mcp.json`) because Antigravity does not provide full `mcp list/get/remove` subcommands.
+
+Cursor note:
+- this CLI manages MCP registration via Cursor global MCP config (`~/.cursor/mcp.json`).
 
 Local bootstrap tools exposed by proxy:
 

package/cli.mjs

@@ -27,6 +27,7 @@ const SELF_UPDATE_ENV_KEY = "METHEUS_CLI_AUTO_UPDATE";
 const SELF_UPDATE_GUARD_ENV_KEY = "METHEUS_CLI_SELF_UPDATE_ATTEMPTED";
 const ALLOW_HOME_WORKSPACE_ENV_KEY = "METHEUS_ALLOW_HOME_WORKSPACE";
 const AUTO_CTXPACK_SYNC_INTERVAL_MS = 60 * 1000;
+const MCP_CLIENTS = ["codex", "claude", "gemini", "antigravity", "cursor"];
 const autoCtxpackSyncTracker = new Map();
 
 function printUsage() {
@@ -85,6 +86,113 @@ function resolveHomeFilePath(relativePath) {
   return path.join(home, relativePath);
 }
 
+function antigravityMcpConfigFilePath() {
+  const home = String(process.env.USERPROFILE || process.env.HOME || "").trim();
+  if (process.platform === "win32") {
+    const appData = String(process.env.APPDATA || "").trim();
+    if (appData) {
+      return path.join(appData, "Antigravity", "User", "mcp.json");
+    }
+    if (home) {
+      return path.join(home, "AppData", "Roaming", "Antigravity", "User", "mcp.json");
+    }
+  }
+  if (process.platform === "darwin" && home) {
+    return path.join(home, "Library", "Application Support", "Antigravity", "User", "mcp.json");
+  }
+  const xdgConfig = String(process.env.XDG_CONFIG_HOME || "").trim();
+  if (xdgConfig) {
+    return path.join(xdgConfig, "Antigravity", "User", "mcp.json");
+  }
+  if (home) {
+    return path.join(home, ".config", "Antigravity", "User", "mcp.json");
+  }
+  return path.resolve(process.cwd(), ".antigravity", "mcp.json");
+}
+
+function loadAntigravityMcpConfig() {
+  const filePath = antigravityMcpConfigFilePath();
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = tryJsonParse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return { filePath, config: parsed };
+    }
+  } catch {
+    // no-op
+  }
+  return {
+    filePath,
+    config: {
+      servers: {},
+      inputs: [],
+    },
+  };
+}
+
+function saveAntigravityMcpConfig(filePath, config) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(config, null, "\t")}\n`, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getAntigravityServerEntry(serverName) {
+  const { config } = loadAntigravityMcpConfig();
+  const servers = safeObject(config?.servers);
+  const entry = safeObject(servers[serverName]);
+  if (!entry.command && !entry.url) return null;
+  return entry;
+}
+
+function cursorMcpConfigFilePath() {
+  const home = String(process.env.USERPROFILE || process.env.HOME || "").trim();
+  if (home) {
+    return path.join(home, ".cursor", "mcp.json");
+  }
+  return path.resolve(process.cwd(), ".cursor", "mcp.json");
+}
+
+function loadCursorMcpConfig() {
+  const filePath = cursorMcpConfigFilePath();
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = tryJsonParse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return { filePath, config: parsed };
+    }
+  } catch {
+    // no-op
+  }
+  return {
+    filePath,
+    config: {
+      mcpServers: {},
+    },
+  };
+}
+
+function saveCursorMcpConfig(filePath, config) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getCursorServerEntry(serverName) {
+  const { config } = loadCursorMcpConfig();
+  const servers = safeObject(config?.mcpServers);
+  const entry = safeObject(servers[serverName]);
+  if (!entry.command && !entry.url) return null;
+  return entry;
+}
+
 function updateStateFilePath() {
   return resolveHomeFilePath(SELF_UPDATE_STATE_RELATIVE_PATH);
 }
@@ -1392,7 +1500,7 @@ async function runAuthLoginManual(flags) {
   if (exp) {
     process.stdout.write(`Token expires: ${exp}\n`);
   }
-  process.stdout.write("Restart Codex/Claude session to apply new token to MCP proxy.\n");
+  process.stdout.write("Restart Codex/Claude/Gemini/Antigravity/Cursor session to apply new token to MCP proxy.\n");
 }
 
 async function runAuthLoginCallback(flags, baseURL, oidc) {
@@ -1474,7 +1582,7 @@ async function runAuthLoginCallback(flags, baseURL, oidc) {
     process.stdout.write("Refresh token saved.\n");
   }
   process.stdout.write("Auth login complete (callback flow).\n");
-  process.stdout.write("Restart Codex/Claude session to apply new token to MCP proxy.\n");
+  process.stdout.write("Restart Codex/Claude/Gemini/Antigravity/Cursor session to apply new token to MCP proxy.\n");
 }
 
 async function runAuthLoginDevice(flags, baseURL, oidc) {
@@ -1541,7 +1649,7 @@ async function runAuthLoginDevice(flags, baseURL, oidc) {
     process.stdout.write("Refresh token saved.\n");
   }
   process.stdout.write("Auth login complete (device flow).\n");
-  process.stdout.write("Restart Codex/Claude session to apply new token to MCP proxy.\n");
+  process.stdout.write("Restart Codex/Claude/Gemini/Antigravity/Cursor session to apply new token to MCP proxy.\n");
 }
 
 async function runAuthLogin(flags) {
@@ -1825,7 +1933,7 @@ async function runDoctor(flags) {
     );
   }
 
-  for (const cliBin of ["codex", "claude"]) {
+  for (const cliBin of MCP_CLIENTS) {
     if (!commandExists(cliBin)) {
       addDoctorCheck(rows, "warn", `${cliBin} CLI`, "not installed; registration check skipped");
       continue;
@@ -3288,13 +3396,32 @@ function ensureArray(value) {
   return Array.isArray(value) ? value : [];
 }
 
+function injectWorkspaceDirIntoToolSchemas(tools) {
+  const workspaceDirProp = {
+    type: "string",
+    description: "Current working directory / project folder path. Include this so ctxpack files sync to the correct workspace.",
+  };
+  for (const tool of tools) {
+    if (!tool || typeof tool !== "object") continue;
+    if (!tool.inputSchema || typeof tool.inputSchema !== "object") continue;
+    const schema = tool.inputSchema;
+    if (!schema.properties || typeof schema.properties !== "object") {
+      schema.properties = {};
+    }
+    if (!schema.properties.workspace_dir) {
+      schema.properties.workspace_dir = workspaceDirProp;
+    }
+  }
+  return tools;
+}
+
 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];
+  result.tools = injectWorkspaceDirIntoToolSchemas([...localSpecs, ...filtered]);
   responseObj.result = result;
   return responseObj;
 }
@@ -3307,6 +3434,7 @@ function appendProjectHintToInitialize(responseObj, args) {
     "- `project.describe` and `project.get` are aliases of `project.summary`.",
     "- After project summary, use workitem/evidence/decision tools as follow-up.",
     "- Before any ctxpack merge, call `ctxpack.merge.brief` first, share recommendation to owner, get explicit owner confirmation, then call `ctxpack.merge.execute`.",
+    "- IMPORTANT: When calling ANY tool, always include your current working directory / project folder path as the `workspace_dir` argument. This enables ctxpack files to be synced to the correct workspace location.",
   ];
   if (args.projectID) {
     hintLines.splice(1, 0, `- Default project_id is ${args.projectID}.`);
@@ -3563,6 +3691,19 @@ function appendCtxpackEnsureSyncHints(responseObj, args, toolArgs, requestObj, w
   return responseObj;
 }
 
+function stripLocalOnlyToolArgs(requestObj) {
+  if (!isJsonRpcMethod(requestObj, "tools/call")) return requestObj;
+  const params = safeObject(requestObj.params);
+  const rawArgs = safeObject(params.arguments ?? params.args);
+  if (!rawArgs.workspace_dir && !rawArgs.workspaceDir) return requestObj;
+  const nextArgs = { ...rawArgs };
+  delete nextArgs.workspace_dir;
+  delete nextArgs.workspaceDir;
+  const nextParams = { ...params };
+  nextParams.arguments = nextArgs;
+  return { ...requestObj, params: nextParams };
+}
+
 function injectCtxpackPushDefaults(requestObj, toolName, workspaceDir) {
   if (!isJsonRpcMethod(requestObj, "tools/call")) return requestObj;
   const normalizedTool = String(toolName || "").trim().toLowerCase();
@@ -4031,13 +4172,15 @@ async function runProxy(flags) {
 
     try {
       const requestWithDefaults = injectCtxpackPushDefaults(requestObj, toolName, requestWorkspaceDir);
-      const outboundRequestObj = await injectCtxpackPreflightToken(
-        requestWithDefaults,
-        toolName,
-        toolArgs,
-        args,
-        token,
-        requestWorkspaceDir,
+      const outboundRequestObj = stripLocalOnlyToolArgs(
+        await injectCtxpackPreflightToken(
+          requestWithDefaults,
+          toolName,
+          toolArgs,
+          args,
+          token,
+          requestWorkspaceDir,
+        ),
       );
       const responseText = await postJSON(gatewayURL, args.timeoutSeconds, token, outboundRequestObj);
       if (responseText) {
@@ -4105,7 +4248,7 @@ function runCLICommand(cliBin, args, options = {}) {
     return direct;
   }
   // On Windows, npm global CLIs are often .cmd wrappers.
-  // Fallback through cmd.exe so tools like "claude" are discoverable.
+  // Fallback through cmd.exe so tools like "claude"/"gemini"/"antigravity"/"cursor" are discoverable.
   return spawnSync("cmd.exe", ["/d", "/s", "/c", cliBin, ...args], execOptions);
 }
 
@@ -4114,21 +4257,112 @@ function commandExists(bin) {
   return check.status === 0;
 }
 
+function escapeRegExp(value) {
+  return String(value || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function hasServerNameInListJSON(value, serverName) {
+  if (Array.isArray(value)) {
+    return value.some((entry) => hasServerNameInListJSON(entry, serverName));
+  }
+  if (!value || typeof value !== "object") return false;
+  if (String(value.name || "").trim() === serverName) return true;
+  return Object.values(value).some((entry) => hasServerNameInListJSON(entry, serverName));
+}
+
 function tryRegister(cliBin, serverName, proxyArgs, options = {}) {
   const selfPath = fileURLToPath(import.meta.url);
-  const baseAddArgs =
-    cliBin === "claude"
-      ? ["mcp", "add", "--scope", "user", serverName]
-      : ["mcp", "add", serverName];
   const workspaceEnv = String(options.workspaceDir || "").trim();
-  const codexEnvArgs =
+  if (cliBin === "cursor") {
+    const { filePath, config } = loadCursorMcpConfig();
+    const nextConfig = safeObject(config);
+    const nextServers = safeObject(nextConfig.mcpServers);
+    const existing = safeObject(nextServers[serverName]);
+    const args = [selfPath, "proxy", ...proxyArgs];
+    const entry = {
+      ...existing,
+      command: process.execPath,
+      args,
+    };
+    const existingEnv = safeObject(existing.env);
+    if (workspaceEnv) {
+      entry.env = {
+        ...existingEnv,
+        METHEUS_WORKSPACE_DIR: workspaceEnv,
+      };
+    } else if (existingEnv.METHEUS_WORKSPACE_DIR) {
+      const nextEnv = { ...existingEnv };
+      delete nextEnv.METHEUS_WORKSPACE_DIR;
+      if (Object.keys(nextEnv).length > 0) {
+        entry.env = nextEnv;
+      } else {
+        delete entry.env;
+      }
+    }
+    nextServers[serverName] = entry;
+    nextConfig.mcpServers = nextServers;
+    return saveCursorMcpConfig(filePath, nextConfig);
+  }
+  if (cliBin === "antigravity") {
+    const { filePath, config } = loadAntigravityMcpConfig();
+    const nextConfig = safeObject(config);
+    const nextServers = safeObject(nextConfig.servers);
+    const existing = safeObject(nextServers[serverName]);
+    const args = [selfPath, "proxy", ...proxyArgs];
+    const entry = {
+      ...existing,
+      command: process.execPath,
+      args,
+    };
+    const existingEnv = safeObject(existing.env);
+    if (workspaceEnv) {
+      entry.env = {
+        ...existingEnv,
+        METHEUS_WORKSPACE_DIR: workspaceEnv,
+      };
+    } else if (existingEnv.METHEUS_WORKSPACE_DIR) {
+      const nextEnv = { ...existingEnv };
+      delete nextEnv.METHEUS_WORKSPACE_DIR;
+      if (Object.keys(nextEnv).length > 0) {
+        entry.env = nextEnv;
+      } else {
+        delete entry.env;
+      }
+    }
+    nextServers[serverName] = entry;
+    nextConfig.servers = nextServers;
+    if (!Array.isArray(nextConfig.inputs)) {
+      nextConfig.inputs = [];
+    }
+    return saveAntigravityMcpConfig(filePath, nextConfig);
+  }
+  if (cliBin === "gemini") {
+    // Gemini CLI (0.31.x) currently supports:
+    // gemini mcp add <name> <commandOrUrl> [args...]
+    // It does not expose --env for MCP registration, so pin workspace-dir directly.
+    const geminiProxyArgs = workspaceEnv
+      ? withWorkspaceDirArg(proxyArgs, workspaceEnv)
+      : [...proxyArgs];
+    const run = runCLICommand(
+      cliBin,
+      ["mcp", "add", serverName, process.execPath, selfPath, "proxy", ...geminiProxyArgs],
+      { stdio: "inherit" },
+    );
+    return run.status === 0;
+  }
+
+  const baseAddArgs = (() => {
+    if (cliBin === "claude") return ["mcp", "add", "--scope", "user", serverName];
+    return ["mcp", "add", serverName];
+  })();
+  const envArgs =
     cliBin === "codex" && workspaceEnv
       ? ["--env", `METHEUS_WORKSPACE_DIR=${workspaceEnv}`]
       : [];
-  if (codexEnvArgs.length > 0) {
+  if (envArgs.length > 0) {
     const envAttempts = [];
-    envAttempts.push([...baseAddArgs, ...codexEnvArgs, "--", process.execPath, selfPath, "proxy", ...proxyArgs]);
-    envAttempts.push([...baseAddArgs, ...codexEnvArgs, process.execPath, selfPath, "proxy", ...proxyArgs]);
+    envAttempts.push([...baseAddArgs, ...envArgs, "--", process.execPath, selfPath, "proxy", ...proxyArgs]);
+    envAttempts.push([...baseAddArgs, ...envArgs, process.execPath, selfPath, "proxy", ...proxyArgs]);
     for (const args of envAttempts) {
       const run = runCLICommand(cliBin, args, { stdio: "inherit" });
       if (run.status === 0) return true;
@@ -4147,6 +4381,31 @@ function tryRegister(cliBin, serverName, proxyArgs, options = {}) {
 }
 
 function runRemove(cliBin, serverName) {
+  if (cliBin === "cursor") {
+    const { filePath, config } = loadCursorMcpConfig();
+    const nextConfig = safeObject(config);
+    const nextServers = safeObject(nextConfig.mcpServers);
+    if (Object.prototype.hasOwnProperty.call(nextServers, serverName)) {
+      delete nextServers[serverName];
+      nextConfig.mcpServers = nextServers;
+      saveCursorMcpConfig(filePath, nextConfig);
+    }
+    return;
+  }
+  if (cliBin === "antigravity") {
+    const { filePath, config } = loadAntigravityMcpConfig();
+    const nextConfig = safeObject(config);
+    const nextServers = safeObject(nextConfig.servers);
+    if (Object.prototype.hasOwnProperty.call(nextServers, serverName)) {
+      delete nextServers[serverName];
+      nextConfig.servers = nextServers;
+      if (!Array.isArray(nextConfig.inputs)) {
+        nextConfig.inputs = [];
+      }
+      saveAntigravityMcpConfig(filePath, nextConfig);
+    }
+    return;
+  }
   if (cliBin === "claude") {
     runCLICommand(cliBin, ["mcp", "remove", serverName, "-s", "user"], {
       stdio: "ignore",
@@ -4156,10 +4415,27 @@ function runRemove(cliBin, serverName) {
     });
     return;
   }
+  if (cliBin === "gemini") {
+    runCLICommand(cliBin, ["mcp", "remove", serverName], { stdio: "ignore" });
+    return;
+  }
   runCLICommand(cliBin, ["mcp", "remove", serverName], { stdio: "ignore" });
 }
 
 function isRegistered(cliBin, serverName) {
+  if (cliBin === "cursor") {
+    return Boolean(getCursorServerEntry(serverName));
+  }
+  if (cliBin === "antigravity") {
+    return Boolean(getAntigravityServerEntry(serverName));
+  }
+  if (cliBin === "gemini") {
+    const listRun = runCLICommand(cliBin, ["mcp", "list"], { stdio: "pipe" });
+    if (listRun.status !== 0) return false;
+    const text = `${String(listRun.stdout || "")}\n${String(listRun.stderr || "")}`;
+    const pattern = new RegExp(`(^|[\\s"'])${escapeRegExp(serverName)}([\\s"':]|$)`, "m");
+    return pattern.test(text);
+  }
   const args =
     cliBin === "claude"
       ? ["mcp", "get", serverName]
@@ -4169,6 +4445,26 @@ function isRegistered(cliBin, serverName) {
 }
 
 function getRegisteredTransport(cliBin, serverName) {
+  if (cliBin === "cursor") {
+    const entry = getCursorServerEntry(serverName);
+    if (!entry) return null;
+    return {
+      type: "stdio",
+      command: String(entry.command || "").trim(),
+      args: Array.isArray(entry.args) ? entry.args : [],
+      env: safeObject(entry.env),
+    };
+  }
+  if (cliBin === "antigravity") {
+    const entry = getAntigravityServerEntry(serverName);
+    if (!entry) return null;
+    return {
+      type: "stdio",
+      command: String(entry.command || "").trim(),
+      args: Array.isArray(entry.args) ? entry.args : [],
+      env: safeObject(entry.env),
+    };
+  }
   if (cliBin !== "codex") return null;
   const run = runCLICommand(cliBin, ["mcp", "get", serverName, "--json"], { stdio: "pipe" });
   if (run.status !== 0) return null;
@@ -4254,7 +4550,7 @@ function resolveSetupContext(flags) {
 function runSetupInternal(flags, options = {}) {
   const ensureOnly = Boolean(options.ensureOnly);
   const context = resolveSetupContext(flags);
-  const clients = ["codex", "claude"];
+  const clients = [...MCP_CLIENTS];
   const results = [];
 
   for (const cliBin of clients) {
@@ -4270,7 +4566,7 @@ function runSetupInternal(flags, options = {}) {
       ? context.workspaceDir
       : context.workspaceFallbackDir;
 
-    if (cliBin === "codex" && !context.hasWorkspaceDirFlag && !context.hasWorkspaceFallbackDirFlag) {
+    if ((cliBin === "codex" || cliBin === "cursor" || cliBin === "antigravity") && !context.hasWorkspaceDirFlag && !context.hasWorkspaceFallbackDirFlag) {
       const transport = getRegisteredTransport(cliBin, context.serverName);
       if (transport) {
         const existingWorkspaceDir = extractWorkspaceDirArg(transport.args);
@@ -4313,7 +4609,7 @@ function runSetupInternal(flags, options = {}) {
     process.stdout.write(`Ctxpack:   ${context.ctxpackKey}\n`);
   }
   if (results.length === 0) {
-    process.stdout.write("No codex/claude CLI found. Registration skipped.\n");
+    process.stdout.write("No codex/claude/gemini/antigravity/cursor CLI found. Registration skipped.\n");
     return;
   }
   for (const row of results) {

package/package.json

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