@mcpcloud/cli 0.11.0 → 0.12.0-next-20260721180156

package/README.md

@@ -159,6 +159,7 @@ _Generated from the live command tree by `bun run docs:readme` — do not edit b
 
 | Command | Description |
 | --- | --- |
+| `mcp analytics` | Show the workspace analytics rollup (readiness, funnel, usage) |
 | `mcp completion <shell>` | Print a shell completion script (bash, zsh, or fish) |
 | `mcp doctor` | Diagnose the CLI environment: Node, config, base URL, API key, claude CLI, and updates |
 | `mcp help [topic]` | Show extended help for a topic (auth, profiles, agents, errors) |

package/dist/index.js

@@ -4919,6 +4919,10 @@ var ERROR_REMEDIATION = {
   organization_access_required: "Not a member of that organization — a stale saved org is the usual cause after switching accounts. Run `mcp orgs list`, then `mcp config set-org <name>`.",
   organization_mismatch: "The deployment belongs to a different org. Pass --org <correct-id>.",
   insufficient_role: "Your role doesn't permit this action. Contact an org owner.",
+  insufficient_scope: "This key is scoped. Mint one with the needed scope (`mcp api-keys create --scope <scope>` or `--preset <preset>`), or rotate from a signed-in browser session to widen.",
+  scope_widening_requires_session: "Widening a key must be done from a signed-in browser session (Settings → API keys). Narrowing works from anywhere.",
+  api_key_org_mismatch: "This key is pinned to a different organization. Pass the pinned org, or mint an unpinned key.",
+  invalid_organization: "Pass an organization you belong to — check `mcp orgs list`.",
   resource_not_found: "No such resource for this org. Verify the ID with the matching `list` command.",
   project_id_required: "Pass --project <id> or look up tools via `mcp tools list --server <id>`.",
   deployment_id_required: "Pass a deploymentId. List with `mcp servers list` to find one.",
@@ -5022,6 +5026,16 @@ function handleError(err) {
     if (info.status)
       parts.push(`(status: ${info.status})`);
     printError(parts.join(" "));
+    if (info.code === "insufficient_scope" && info.details) {
+      const required = info.details["requiredScopes"];
+      const granted = info.details["grantedScopes"];
+      if (Array.isArray(required) && required.length > 0) {
+        console.error(`  this key lacks: ${required.join(" or ")}`);
+      }
+      if (Array.isArray(granted)) {
+        console.error(`  it has:         ${granted.length > 0 ? granted.join(" ") : "(no scopes)"}`);
+      }
+    }
     const remediation = getRemediation(info.code);
     if (remediation)
       console.error(`  ${remediation}`);
@@ -11380,6 +11394,26 @@ function parseExpiresInDays(raw) {
 function formatPreview(key) {
   return `${key.keyPrefix}…${key.lastFour}`;
 }
+function formatGrants(key) {
+  if (key.scopes == null)
+    return key.preset === "full" ? "full" : "full (legacy)";
+  if (key.preset && key.preset !== "custom")
+    return key.preset;
+  return `custom (${key.scopes.length})`;
+}
+function collectScope(value, previous) {
+  return [...previous, value];
+}
+function grantBodyFromOptions(opts) {
+  if (opts.preset && opts.scope && opts.scope.length > 0) {
+    throw new Error("--preset and --scope are mutually exclusive.");
+  }
+  return {
+    ...opts.preset ? { preset: opts.preset } : {},
+    ...opts.scope && opts.scope.length > 0 ? { scopes: opts.scope } : {},
+    ...opts.clearOrg ? { orgId: null } : opts.org ? { orgId: opts.org } : {}
+  };
+}
 var API_KEY_KIND = { label: "api key", listHint: "mcp api-keys list" };
 async function resolveApiKeyId(reference) {
   const ref = reference.trim();
@@ -11406,26 +11440,29 @@ function registerApiKeyCommands(program2) {
       id: k2.id,
       name: k2.name,
       preview: formatPreview(k2),
-      created: formatDate(k2.createdAt),
+      grants: formatGrants(k2),
+      org: k2.orgId ?? "—",
       "last used": k2.lastUsedAt ? formatDate(k2.lastUsedAt) : "—",
       expires: k2.expiresAt ? formatDate(k2.expiresAt) : "never"
     })), [
       { key: "id", label: "ID", width: 20 },
       { key: "name", label: "Name", width: 24 },
       { key: "preview", label: "Preview", width: 18 },
-      { key: "created", label: "Created", width: 22 },
+      { key: "grants", label: "Grants", width: 14 },
+      { key: "org", label: "Org", width: 20 },
       { key: "last used", label: "Last Used", width: 22 },
       { key: "expires", label: "Expires", width: 22 }
     ], data);
   }));
-  apiKeys.command("create").description("Create a new API key (the secret is shown once)").requiredOption("--name <name>", "Display name for the key").option("--expires-in <duration>", "Auto-expire the key after this long: 90d, 12w, 6m, or a day count (1–365). Default: never.").action(runAction(async (opts) => {
+  apiKeys.command("create").description("Create a new API key (the secret is shown once)").requiredOption("--name <name>", "Display name for the key").option("--expires-in <duration>", "Auto-expire the key after this long: 90d, 12w, 6m, or a day count (1–365). Default: never.").option("--preset <preset>", "Scope preset: full, agent, read-only, or ci-deploy. Default: full authority.").option("--scope <scope>", "Grant a single scope (repeatable, e.g. --scope servers:read --scope servers:deploy). Mutually exclusive with --preset.", collectScope, []).option("--org <orgId>", "Pin the key to one organization (must be one you belong to).").action(runAction(async (opts) => {
     const name = opts.name.trim();
     if (!name)
       throw new Error("--name must not be empty.");
     const expiresInDays = parseExpiresInDays(opts.expiresIn);
     const data = await api.post("/api/v1/api-keys", {
       name,
-      ...expiresInDays !== undefined ? { expiresInDays } : {}
+      ...expiresInDays !== undefined ? { expiresInDays } : {},
+      ...grantBodyFromOptions(opts)
     });
     if (isJsonMode()) {
       printJson(data);
@@ -11439,6 +11476,9 @@ function registerApiKeyCommands(program2) {
       key: data.apiKey,
       "key prefix": data.keyPrefix,
       "last four": data.lastFour,
+      grants: formatGrants(data),
+      scopes: data.scopes?.join(" ") ?? "all (full authority)",
+      org: data.orgId ?? "any you belong to",
       expires: data.expiresAt ? formatDate(data.expiresAt) : "never"
     });
     console.log("");
@@ -11457,27 +11497,36 @@ function registerApiKeyCommands(program2) {
       name: k2.name,
       preview: formatPreview(k2),
       status: k2.status,
+      grants: formatGrants(k2),
+      scopes: k2.scopes?.join(" ") ?? "all (full authority)",
+      org: k2.orgId ?? "any you belong to",
       created: formatDate(k2.createdAt),
       "last used": k2.lastUsedAt ? formatDate(k2.lastUsedAt) : "—",
       expires: k2.expiresAt ? formatDate(k2.expiresAt) : "never",
       revoked: k2.revokedAt ? formatDate(k2.revokedAt) : "—"
     });
   }));
-  apiKeys.command("rotate <apiKey>").description("Mint a replacement key and grace-expire the old one (24h window; accepts id or name). The new secret is shown once.").option("--expires-in <duration>", "Expiry for the NEW key: 90d, 12w, 6m, or a day count (1–365). Default: never.").addHelpText("after", [
+  apiKeys.command("rotate <apiKey>").description("Mint a replacement key and grace-expire the old one (24h window; accepts id or name). The new secret is shown once.").option("--expires-in <duration>", "Expiry for the NEW key: 90d, 12w, 6m, or a day count (1–365). Default: never.").option("--preset <preset>", "Re-scope the new key to a preset (narrowing works from anywhere; widening needs a browser session).").option("--scope <scope>", "Re-scope the new key to explicit scopes (repeatable). Mutually exclusive with --preset.", collectScope, []).option("--org <orgId>", "Pin the new key to one organization.").option("--clear-org", "Remove the organization pin (requires a browser session).").addHelpText("after", [
     "",
     "The old key keeps working for 24h so running automation can swap to the",
     "new secret before the old one stops. Update your secrets within that window.",
     "",
+    "Scopes: omitted flags inherit the old key’s grants. Narrowing (fewer",
+    "scopes, adding an org pin) works from any credential; widening (more",
+    "scopes, clearing/changing a pin) must come from a signed-in session.",
+    "",
     "Examples:",
     "  $ mcp api-keys rotate key_123",
-    '  $ mcp api-keys rotate "CI deploy key" --expires-in 90d'
+    '  $ mcp api-keys rotate "CI deploy key" --expires-in 90d',
+    "  $ mcp api-keys rotate ci --preset ci-deploy --org org_abc"
   ].join(`
 `)).action(runAction(async (apiKeyRef, opts) => {
     const apiKeyId = await resolveApiKeyId(apiKeyRef);
     const expiresInDays = parseExpiresInDays(opts.expiresIn);
     const data = await api.patch("/api/v1/api-keys", {
       apiKeyId,
-      ...expiresInDays !== undefined ? { expiresInDays } : {}
+      ...expiresInDays !== undefined ? { expiresInDays } : {},
+      ...grantBodyFromOptions(opts)
     });
     if (isJsonMode()) {
       printJson(data);
@@ -11491,6 +11540,9 @@ function registerApiKeyCommands(program2) {
       key: data.apiKey,
       "key prefix": data.keyPrefix,
       "last four": data.lastFour,
+      grants: formatGrants(data),
+      scopes: data.scopes?.join(" ") ?? "all (full authority)",
+      org: data.orgId ?? "any you belong to",
       expires: data.expiresAt ? formatDate(data.expiresAt) : "never",
       "old key": data.rotatedFrom?.apiKeyId ?? "—",
       "old key valid until": data.rotatedFrom ? formatDate(data.rotatedFrom.gracePeriodEndsAt) : "—"
@@ -32931,6 +32983,72 @@ function registerOrgCommands(program2) {
   }));
 }
 
+// src/commands/analytics.ts
+function parseWindowDays2(raw) {
+  if (!raw)
+    return;
+  const match = /^(\d{1,2})d?$/.exec(raw.trim());
+  const days = match ? Number.parseInt(match[1], 10) : Number.NaN;
+  if (!Number.isFinite(days) || days < 1 || days > 90) {
+    throw new Error("--since must be a day count between 1 and 90 (e.g. 14d).");
+  }
+  return days;
+}
+function registerAnalyticsCommands(program2) {
+  program2.command("analytics").description("Show the workspace analytics rollup (readiness, funnel, usage)").option("--org <organizationId>", "Organization ID").option("--since <window>", "Window in days over closed days (1–90, default 14)").addHelpText("after", [
+    "",
+    "Examples:",
+    "  $ mcp analytics                    # 14-day rollup",
+    "  $ mcp analytics --since 30d",
+    "  $ mcp --json analytics | jq '.summary.usage.totals'"
+  ].join(`
+`)).action(runAction(async (opts) => {
+    const orgId = await resolveOrgId(opts.org);
+    const windowDays = parseWindowDays2(opts.since);
+    const data = await api.get("/api/v1/analytics/summary", {
+      organizationId: orgId,
+      ...windowDays ? { windowDays: String(windowDays) } : {}
+    });
+    if (isJsonMode()) {
+      printJson(data);
+      return;
+    }
+    const { summary } = data;
+    printKeyValue({
+      Window: `${summary.windowDays}d (closed days)`,
+      Servers: `${summary.readiness.total} total · ${summary.readiness.built} built · ${summary.readiness.deployed} deployed · ${summary.readiness.called} called`,
+      Status: `${summary.status.live} live · ${summary.status.draft} draft · ${summary.status.needsAttention} need attention`,
+      Funnel: `imported ${summary.funnel.imported} → built ${summary.funnel.built} → deployed ${summary.funnel.deployed} → installed ${summary.funnel.installed} → first call ${summary.funnel.firstCall}`,
+      Projects: String(summary.projectsTotal)
+    });
+    if (!summary.usage) {
+      console.log(`
+Usage detail requires admin organization access.`);
+      return;
+    }
+    const { usage } = summary;
+    printKeyValue({
+      "Tool calls": `${usage.totals.toolCalls} (${usage.totals.toolErrors} errors · ${(usage.totals.errorRate * 100).toFixed(1)}%)`,
+      Latency: `p50 ${usage.latency.p50Ms ?? "—"}ms · p95 ${usage.latency.p95Ms ?? "—"}ms`,
+      Edge: `${usage.edge.requests} requests · ${usage.edge.unauthorized} unauthorized · ${usage.edge.rateLimited} rate-limited · ${usage.edge.failed} failed`,
+      "Projection savings": `${usage.projectionSavedBytes} bytes`
+    });
+    if (usage.topTools.length) {
+      printList(usage.topTools, [
+        { key: "toolName", label: "Tool", width: 36 },
+        { key: "calls", label: "Calls", width: 8 },
+        { key: "errors", label: "Errors", width: 8 }
+      ], usage.topTools);
+    }
+    if (usage.topServers.length) {
+      printList(usage.topServers, [
+        { key: "name", label: "Server", width: 36 },
+        { key: "requests", label: "Requests", width: 10 }
+      ], usage.topServers);
+    }
+  }));
+}
+
 // src/commands/connections.ts
 async function readKeyFromStdin() {
   const chunks = [];
@@ -37656,6 +37774,7 @@ function createProgram() {
   registerDeploymentCommands(program2);
   registerOrgCommands(program2);
   registerUsageCommands(program2);
+  registerAnalyticsCommands(program2);
   registerConnectionsCommands(program2);
   registerMetricsCommands(program2);
   registerDevCommand(program2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpcloud/cli",
-  "version": "0.11.0",
+  "version": "0.12.0-next-20260721180156",
   "description": "The official CLI for MCPCloud — manage projects, servers, skills, and API keys from the terminal",
   "type": "module",
   "bin": {