metheus-governance-mcp-cli 0.2.0 → 0.2.1

package/README.md

@@ -2,6 +2,11 @@
 
 Metheus Governance MCP helper CLI.
 
+- `metheus-governance-mcp` (no args): bootstrap mode
+  - checks auth token
+  - if token is missing/expired, starts `auth login`
+  - checks Codex/Claude MCP registration
+  - registers only missing clients
 - `setup`: register `metheus-governance-mcp` into Codex/Claude (if installed)
 - `proxy`: stdio MCP bridge to Metheus HTTPS gateway
 - `auth`: save/check/clear local Metheus token used by proxy
@@ -12,6 +17,16 @@ Metheus Governance MCP helper CLI.
 npm install -g metheus-governance-mcp-cli
 ```
 
+## One command bootstrap (recommended)
+
+Run in your project folder:
+
+```bash
+metheus-governance-mcp --project-id <project_uuid> --ctxpack-key "<ctxpack_key>" --base-url https://metheus.gesiaplatform.com
+```
+
+If auth is not ready, login starts automatically, then MCP registration is completed.
+
 ## Setup
 
 ```bash
@@ -63,7 +78,7 @@ metheus-governance-mcp auth status
 3. If token is rotated, set directly:
 
 ```bash
-metheus-governance-mcp auth set --token "<access_token>"
+metheus-governance-mcp auth set --token "<access_token>" --refresh-token "<refresh_token>"
 ```
 
 4. Remove local token:

package/cli.mjs

@@ -14,6 +14,9 @@ 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 CLI_META = loadCLIMeta();
+const CLI_NAME = CLI_META.name || "metheus-governance-mcp-cli";
+const CLI_VERSION = CLI_META.version || "0.0.0";
 
 function printUsage() {
   process.stderr.write(
@@ -21,12 +24,15 @@ function printUsage() {
       "Metheus Governance MCP CLI",
       "",
       "Usage:",
+      "  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 proxy [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--include-drafts <true|false>] [--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> [--base-url <url>]",
+      "  metheus-governance-mcp auth set --token <jwt> [--refresh-token <token>] [--base-url <url>]",
       "  metheus-governance-mcp auth clear",
+      "  metheus-governance-mcp -v | --version",
       "",
       "Environment:",
       "  METHEUS_TOKEN or MCP_AUTH_TOKEN is used first for proxy requests.",
@@ -37,6 +43,24 @@ function printUsage() {
   );
 }
 
+function loadCLIMeta() {
+  try {
+    const dir = path.dirname(fileURLToPath(import.meta.url));
+    const raw = fs.readFileSync(path.join(dir, "package.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+function printVersion() {
+  process.stdout.write(`${CLI_NAME} ${CLI_VERSION}\n`);
+}
+
 function parseArgs(argv) {
   const out = {};
   for (let i = 0; i < argv.length; i += 1) {
@@ -82,29 +106,31 @@ function loadStoredAuth() {
   const filePath = authStoreFilePath();
   try {
     if (!fs.existsSync(filePath)) {
-      return { filePath, token: "", baseURL: "", updatedAt: "" };
+      return { filePath, token: "", refreshToken: "", baseURL: "", updatedAt: "" };
     }
     const raw = fs.readFileSync(filePath, "utf8");
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      return { filePath, token: "", baseURL: "", updatedAt: "" };
+      return { filePath, token: "", refreshToken: "", baseURL: "", updatedAt: "" };
     }
     return {
       filePath,
       token: normalizeToken(parsed.token),
+      refreshToken: normalizeToken(parsed.refresh_token),
       baseURL: String(parsed.base_url || "").trim(),
       updatedAt: String(parsed.updated_at || "").trim(),
     };
   } catch {
-    return { filePath, token: "", baseURL: "", updatedAt: "" };
+    return { filePath, token: "", refreshToken: "", baseURL: "", updatedAt: "" };
   }
 }
 
-function saveStoredAuth({ token, baseURL }) {
+function saveStoredAuth({ token, refreshToken, baseURL }) {
   const filePath = authStoreFilePath();
   ensureParentDir(filePath);
   const payload = {
     token: normalizeToken(token),
+    refresh_token: normalizeToken(refreshToken),
     base_url: String(baseURL || "").trim(),
     updated_at: new Date().toISOString(),
   };
@@ -512,6 +538,45 @@ async function exchangeAuthorizationCodeForToken({
   return parsed;
 }
 
+async function exchangeRefreshTokenForToken({
+  tokenEndpoint,
+  clientID,
+  refreshToken,
+  timeoutSeconds,
+}) {
+  const params = new URLSearchParams({
+    grant_type: "refresh_token",
+    client_id: String(clientID || "").trim(),
+    refresh_token: String(refreshToken || "").trim(),
+  });
+
+  const response = await fetch(tokenEndpoint, {
+    method: "POST",
+    headers: {
+      "content-type": "application/x-www-form-urlencoded",
+      accept: "application/json",
+    },
+    body: params.toString(),
+    redirect: "follow",
+    signal: AbortSignal.timeout(Math.max(5, intFromRaw(timeoutSeconds, 20)) * 1000),
+  });
+
+  const body = await response.text();
+  const parsed = tryJsonParse(body) || {};
+  if (!response.ok) {
+    const reason =
+      String(parsed.error_description || parsed.error || "").trim() ||
+      body.slice(0, 250) ||
+      `${response.status} ${response.statusText}`;
+    throw new Error(`refresh token exchange failed: ${reason}`);
+  }
+  const accessToken = normalizeToken(parsed.access_token);
+  if (!accessToken) {
+    throw new Error("refresh token exchange succeeded but access_token is missing");
+  }
+  return parsed;
+}
+
 async function requestDeviceAuthorization({
   deviceAuthorizationEndpoint,
   clientID,
@@ -658,6 +723,48 @@ function resolveCurrentAccessToken() {
   };
 }
 
+async function tryRefreshStoredAccessToken({ baseURL, timeoutSeconds }) {
+  const stored = loadStoredAuth();
+  const refreshCandidates = [
+    { source: "METHEUS_REFRESH_TOKEN", token: normalizeToken(process.env.METHEUS_REFRESH_TOKEN) },
+    { source: "MCP_AUTH_REFRESH_TOKEN", token: normalizeToken(process.env.MCP_AUTH_REFRESH_TOKEN) },
+    { source: `${stored.filePath}:refresh_token`, token: normalizeToken(stored.refreshToken) },
+  ];
+  const refreshRow = refreshCandidates.find((row) => Boolean(row.token));
+  if (!refreshRow) {
+    return { ok: false, error: "no refresh token configured" };
+  }
+
+  const siteBaseURL = normalizeSiteBaseURL(baseURL || stored.baseURL || DEFAULT_SITE_URL);
+  try {
+    const oidc = await discoverOIDCConfig({ siteBaseURL });
+    const payload = await exchangeRefreshTokenForToken({
+      tokenEndpoint: oidc.tokenEndpoint,
+      clientID: oidc.clientID,
+      refreshToken: refreshRow.token,
+      timeoutSeconds: intFromRaw(timeoutSeconds, 20),
+    });
+
+    const accessToken = normalizeToken(payload.access_token);
+    const nextRefreshToken = normalizeToken(payload.refresh_token) || refreshRow.token;
+    const filePath = saveStoredAuth({
+      token: accessToken,
+      refreshToken: nextRefreshToken,
+      baseURL: siteBaseURL,
+    });
+
+    return {
+      ok: true,
+      token: accessToken,
+      source: filePath,
+      refreshSource: refreshRow.source,
+      expires: tokenExpiryIso(accessToken),
+    };
+  } catch (err) {
+    return { ok: false, error: String(err?.message || err), refreshSource: refreshRow.source };
+  }
+}
+
 function currentAccessToken() {
   return resolveCurrentAccessToken().token;
 }
@@ -755,6 +862,10 @@ async function runAuthStatus() {
   const token = resolved.token;
   const source = resolved.source;
   const stored = resolved.stored;
+  const refreshToken =
+    normalizeToken(process.env.METHEUS_REFRESH_TOKEN) ||
+    normalizeToken(process.env.MCP_AUTH_REFRESH_TOKEN) ||
+    normalizeToken(stored.refreshToken);
   if (!token) {
     process.stdout.write("Auth token: missing\n");
     if (resolved.expired?.source) {
@@ -767,6 +878,7 @@ async function runAuthStatus() {
     process.stdout.write(
       "Run: metheus-governance-mcp auth login --base-url https://metheus.gesiaplatform.com\n",
     );
+    process.stdout.write(`Refresh token: ${refreshToken ? "configured" : "missing"}\n`);
     process.exitCode = 1;
     return;
   }
@@ -782,10 +894,18 @@ async function runAuthStatus() {
       process.stdout.write(`Stored at: ${stored.updatedAt}\n`);
     }
   }
+  process.stdout.write(`Refresh token: ${refreshToken ? "configured" : "missing"}\n`);
 }
 
 async function runAuthSet(flags) {
+  const stored = loadStoredAuth();
   const rawToken = normalizeToken(flags.token || flags["access-token"] || "");
+  const rawRefreshToken = normalizeToken(
+    flags["refresh-token"] ||
+      process.env.METHEUS_REFRESH_TOKEN ||
+      process.env.MCP_AUTH_REFRESH_TOKEN ||
+      "",
+  );
   let token = rawToken;
   if (!token && process.stdin.isTTY) {
     token = normalizeToken(await promptLine("Paste Metheus access token (JWT): "));
@@ -796,15 +916,20 @@ async function runAuthSet(flags) {
     return;
   }
   const baseURL = normalizeSiteBaseURL(flags["base-url"] || DEFAULT_SITE_URL);
-  const filePath = saveStoredAuth({ token, baseURL });
+  const refreshToken = rawRefreshToken || normalizeToken(stored.refreshToken);
+  const filePath = saveStoredAuth({ token, refreshToken, baseURL });
   const exp = tokenExpiryIso(token);
   process.stdout.write(`Token saved: ${filePath}\n`);
   if (exp) {
     process.stdout.write(`Token expires: ${exp}\n`);
   }
+  if (refreshToken) {
+    process.stdout.write("Refresh token saved.\n");
+  }
 }
 
 async function runAuthLoginManual(flags) {
+  const stored = loadStoredAuth();
   const baseURL = normalizeSiteBaseURL(flags["base-url"] || DEFAULT_SITE_URL);
   const loginURL = authLoginURL(baseURL);
   const shouldOpen = boolFromRaw(flags["open-browser"], true);
@@ -822,7 +947,11 @@ async function runAuthLoginManual(flags) {
     process.exitCode = 1;
     return;
   }
-  const filePath = saveStoredAuth({ token, baseURL });
+  const filePath = saveStoredAuth({
+    token,
+    refreshToken: normalizeToken(stored.refreshToken),
+    baseURL,
+  });
   const exp = tokenExpiryIso(token);
   process.stdout.write(`Token saved: ${filePath}\n`);
   if (exp) {
@@ -899,12 +1028,16 @@ async function runAuthLoginCallback(flags, baseURL, oidc) {
   }
 
   const token = normalizeToken(tokenPayload.access_token);
-  const filePath = saveStoredAuth({ token, baseURL });
+  const refreshToken = normalizeToken(tokenPayload.refresh_token);
+  const filePath = saveStoredAuth({ token, refreshToken, baseURL });
   const exp = tokenExpiryIso(token);
   process.stdout.write(`Token saved: ${filePath}\n`);
   if (exp) {
     process.stdout.write(`Token expires: ${exp}\n`);
   }
+  if (refreshToken) {
+    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");
 }
@@ -962,12 +1095,16 @@ async function runAuthLoginDevice(flags, baseURL, oidc) {
   });
 
   const token = normalizeToken(tokenPayload.access_token);
-  const filePath = saveStoredAuth({ token, baseURL });
+  const refreshToken = normalizeToken(tokenPayload.refresh_token);
+  const filePath = saveStoredAuth({ token, refreshToken, baseURL });
   const exp = tokenExpiryIso(token);
   process.stdout.write(`Token saved: ${filePath}\n`);
   if (exp) {
     process.stdout.write(`Token expires: ${exp}\n`);
   }
+  if (refreshToken) {
+    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");
 }
@@ -1132,6 +1269,8 @@ async function runProxy(flags) {
     timeoutSeconds: intFromRaw(flags["timeout-seconds"], 30),
   };
   const gatewayURL = buildGatewayURL(args);
+  let lastRefreshAttemptAtMs = 0;
+  let lastRefreshError = "";
 
   const rl = readline.createInterface({
     input: process.stdin,
@@ -1148,7 +1287,24 @@ async function runProxy(flags) {
       return;
     }
 
-    const resolved = resolveCurrentAccessToken();
+    let resolved = resolveCurrentAccessToken();
+    if (!resolved.token) {
+      const nowMs = Date.now();
+      // Throttle refresh attempts to avoid hammering token endpoint on repeated requests.
+      if (nowMs - lastRefreshAttemptAtMs > 10000) {
+        lastRefreshAttemptAtMs = nowMs;
+        const refreshed = await tryRefreshStoredAccessToken({
+          baseURL: args.baseURL,
+          timeoutSeconds: args.timeoutSeconds,
+        });
+        if (refreshed.ok) {
+          resolved = resolveCurrentAccessToken();
+          lastRefreshError = "";
+        } else {
+          lastRefreshError = String(refreshed.error || "").trim();
+        }
+      }
+    }
     const token = resolved.token;
     if (!token) {
       const helpURL = authLoginURL(args.baseURL);
@@ -1156,6 +1312,7 @@ async function runProxy(flags) {
         resolved.expired?.source
           ? `; expired token ignored: ${resolved.expired.source}${resolved.expired.expires ? ` (${resolved.expired.expires})` : ""}`
           : "";
+      const refreshHint = lastRefreshError ? `; refresh failed: ${lastRefreshError}` : "";
       process.stdout.write(
         `${JSON.stringify(
           jsonRpcError(
@@ -1163,7 +1320,7 @@ async function runProxy(flags) {
             -32001,
             `missing auth token (set METHEUS_TOKEN or run 'metheus-governance-mcp auth login --base-url ${normalizeSiteBaseURL(
               args.baseURL,
-            )}'; login: ${helpURL}${expiredHint})`,
+            )}'; login: ${helpURL}${expiredHint}${refreshHint})`,
           ),
         )}\n`,
       );
@@ -1233,10 +1390,10 @@ function tryRegister(cliBin, serverName, proxyArgs) {
 
 function runRemove(cliBin, serverName) {
   if (cliBin === "claude") {
-    runCLICommand(cliBin, ["mcp", "remove", serverName, "--scope", "user"], {
+    runCLICommand(cliBin, ["mcp", "remove", serverName, "-s", "user"], {
       stdio: "ignore",
     });
-    runCLICommand(cliBin, ["mcp", "remove", serverName, "--scope", "local"], {
+    runCLICommand(cliBin, ["mcp", "remove", serverName, "-s", "local"], {
       stdio: "ignore",
     });
     return;
@@ -1244,51 +1401,118 @@ function runRemove(cliBin, serverName) {
   runCLICommand(cliBin, ["mcp", "remove", serverName], { stdio: "ignore" });
 }
 
-function runSetup(flags) {
+function isRegistered(cliBin, serverName) {
+  const args =
+    cliBin === "claude"
+      ? ["mcp", "get", serverName]
+      : ["mcp", "get", serverName, "--json"];
+  const run = runCLICommand(cliBin, args, { stdio: "ignore" });
+  return run.status === 0;
+}
+
+function resolveSetupContext(flags) {
   const workspaceMeta = loadWorkspaceMeta(process.cwd());
   const projectID = String(flags["project-id"] || workspaceMeta.project_id || "").trim();
   const ctxpackKey = String(flags["ctxpack-key"] || buildCtxpackKeyFromMeta(workspaceMeta) || "").trim();
-  const baseURL = String(flags["base-url"] || "https://metheus.gesiaplatform.com").trim().replace(/\/+$/, "");
+  const baseURL = String(flags["base-url"] || DEFAULT_SITE_URL).trim().replace(/\/+$/, "");
   const serverName = String(flags.name || DEFAULT_SERVER_NAME).trim() || DEFAULT_SERVER_NAME;
-
   const proxyArgs = ["--base-url", `${baseURL}/governance/mcp`];
   if (projectID) proxyArgs.push("--project-id", projectID);
   if (ctxpackKey) proxyArgs.push("--ctxpack-key", ctxpackKey);
+  return { projectID, ctxpackKey, baseURL, serverName, proxyArgs };
+}
 
+function runSetupInternal(flags, options = {}) {
+  const ensureOnly = Boolean(options.ensureOnly);
+  const context = resolveSetupContext(flags);
   const clients = ["codex", "claude"];
   const results = [];
+
   for (const cliBin of clients) {
     if (!commandExists(cliBin)) continue;
-    runRemove(cliBin, serverName);
-    const ok = tryRegister(cliBin, serverName, proxyArgs);
-    results.push({ cliBin, ok });
+    const alreadyRegistered = isRegistered(cliBin, context.serverName);
+    if (ensureOnly && alreadyRegistered) {
+      results.push({ cliBin, ok: true, action: "already-registered" });
+      continue;
+    }
+    if (!ensureOnly) {
+      runRemove(cliBin, context.serverName);
+    }
+    const ok = tryRegister(cliBin, context.serverName, context.proxyArgs);
+    results.push({ cliBin, ok, action: alreadyRegistered ? "re-registered" : "registered" });
   }
 
-  process.stdout.write("\nInstall complete.\n");
-  process.stdout.write(`Server:    ${serverName}\n`);
-  process.stdout.write(`Gateway:   ${baseURL}/governance/mcp\n`);
-  process.stdout.write(`Project:   ${projectID || "auto-detect from .metheus_ctxpack_sync.json"}\n`);
-  if (ctxpackKey) {
-    process.stdout.write(`Ctxpack:   ${ctxpackKey}\n`);
+  process.stdout.write(ensureOnly ? "\nEnsure complete.\n" : "\nInstall complete.\n");
+  process.stdout.write(`Server:    ${context.serverName}\n`);
+  process.stdout.write(`Gateway:   ${context.baseURL}/governance/mcp\n`);
+  process.stdout.write(`Project:   ${context.projectID || "auto-detect from .metheus_ctxpack_sync.json"}\n`);
+  if (context.ctxpackKey) {
+    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("Set METHEUS_TOKEN, then register manually if needed.\n");
-  } else {
-    for (const row of results) {
-      process.stdout.write(`${row.cliBin}: ${row.ok ? "registered" : "registration failed"}\n`);
+    return;
+  }
+  for (const row of results) {
+    process.stdout.write(`${row.cliBin}: ${row.ok ? row.action : "registration failed"}\n`);
+  }
+}
+
+function runSetup(flags) {
+  runSetupInternal(flags, { ensureOnly: false });
+}
+
+async function runBootstrap(flags) {
+  process.stdout.write("Bootstrap start.\n");
+  let resolved = resolveCurrentAccessToken();
+  if (!resolved.token) {
+    process.stdout.write("Auth token missing/expired. Starting login flow...\n");
+    await runAuthLogin(flags);
+    resolved = resolveCurrentAccessToken();
+    if (!resolved.token) {
+      process.stderr.write("Auth login finished but token is still unavailable.\n");
+      process.exitCode = 1;
+      return;
     }
+  } else {
+    process.stdout.write(`Auth token OK (${resolved.source}).\n`);
   }
+
+  runSetupInternal(flags, { ensureOnly: true });
+  process.stdout.write("Bootstrap done.\n");
 }
 
 async function main() {
-  const [, , command, ...rest] = process.argv;
-  if (!command || command === "-h" || command === "--help") {
+  const [, , rawCommand, ...rest] = process.argv;
+  const command = String(rawCommand || "");
+
+  if (command === "-v" || command === "--version" || command === "version") {
+    printVersion();
+    return;
+  }
+
+  if (!command) {
+    await runBootstrap({});
+    return;
+  }
+
+  if (command === "-h" || command === "--help") {
     printUsage();
-    process.exit(command ? 0 : 1);
+    process.exit(0);
     return;
   }
+
+  if (command.startsWith("--")) {
+    const flags = parseArgs([command, ...rest]);
+    await runBootstrap(flags);
+    return;
+  }
+
   const flags = parseArgs(rest);
+  if (command === "init") {
+    await runBootstrap(flags);
+    return;
+  }
   if (command === "setup") {
     runSetup(flags);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metheus-governance-mcp-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [
@@ -16,7 +16,8 @@
     "publish:public": "node release.mjs"
   },
   "bin": {
-    "metheus-governance-mcp": "bin/metheus-governance-mcp.js"
+    "metheus-governance-mcp": "bin/metheus-governance-mcp.js",
+    "metheus-governance-mcp-cli": "bin/metheus-governance-mcp.js"
   },
   "engines": {
     "node": ">=18.0.0"