@mcpcloud/cli 0.25.1 → 0.26.0-next-20260927194202

package/README.md

@@ -103,7 +103,7 @@ mcp servers get my-api --probe         # verify the endpoint serves what the con
 mcp invoke my-api getUser --args '{"id":"abc"}'
 ```
 
-Servers are addressable by id, name, or memorable slug throughout the CLI. Two verbs keep a server current after its API changes: `mcp servers push-spec` diffs a local spec against the stored tools (preview by default; `--apply` reconciles schemas by stable operation key, preserving curated descriptions, tags, risk classes, and enrichment), and `mcp servers regenerate` re-fetches the original source spec and rebuilds with the current codegen (`--dry-run` previews the per-tool changes first).
+Servers are addressable by id, name, or memorable slug throughout the CLI. Two verbs keep a server current after its API changes: `mcp servers push-spec` diffs a local spec against the stored tools (preview by default; `--apply` reconciles schemas by stable operation key, preserving curated descriptions, tags, risk classes, and enrichment), and `mcp servers regenerate` re-fetches the original source spec and rebuilds with the current codegen (`--dry-run` previews the per-tool changes first). To read a server from a different spec URL from now on, `mcp servers update <server> --source-url <url>` checks the new URL, shows what a regenerate from it would change, and stores it (`--dry-run` checks without storing); then regenerate and deploy. Operations a spec marks `x-mcp: false` never become tools.
 
 Neither verb renames a tool — both match tools on their stable operation key. Codegen now keeps an operationId's own case (`getRecording`); servers created before that change keep their lowercased names (`getrecording`), and both previews say how many. `mcp tools rename --from-operation-ids --server <server>` (or `push-spec --rename-to-operation-ids`) adopts the new names while keeping tool ids, access grants, and saved scenarios; `mcp tools rename <old> <new>` renames one tool. Deploy afterwards — the live server keeps the old names until then.
 
@@ -565,7 +565,7 @@ _Generated from the live command tree by `bun run docs:readme` — do not edit b
 | `mcp servers test-suites run <server>` | Run the server’s test scenarios and report the suite result |
 | `mcp servers traces <server>` | Show recent tool-call traces from the edge — what a caller sent and what came back. Pass --request to open one call in full. |
 | `mcp servers transfer <server>` | Move a server into another organization you administer, keeping its id, slug, deployment, custom domain, end-user keys and git link. Shows the plan; add --yes to execute. |
-| `mcp servers update <server>` | Update a server (name, description, tool surface, upstream key mode, runtime token TTL) |
+| `mcp servers update <server>` | Update a server (name, description, tool surface, upstream key mode, runtime token TTL, spec source URL) |
 | `mcp servers variables` | Inspect and set the sandbox variables that scenario arguments reference |
 | `mcp servers variables list <server>` | List a server’s sandbox variables and which ones still need a value |
 | `mcp servers variables set <server>` | Set or clear sandbox variables (repeat --set; an empty value clears) |

package/dist/index.js

@@ -8278,7 +8278,7 @@ async function runPushSpec(serverRef, opts) {
 
 // src/commands/servers-regenerate.ts
 function registerServerRegenerateCommand(servers) {
-  servers.command("regenerate <server>").description("Re-fetch a server's source spec and rebuild its tools with the current codegen (preserves customizations). Works for spec-URL, OpenAPI, and GraphQL sources; a pasted or manual server has nothing to re-fetch. Wraps POST /api/v1/server/regenerate.").option("--org <organizationId>", "Organization ID").option("--project <project>", "Project (id or name; defaults to the server's project)").option("--source-url <url>", "Override the stored spec source URL (needed for GraphQL servers whose introspection endpoint wasn't persisted)").option("--dry-run", "Report what would change (per tool) without writing anything").addHelpText("after", [
+  servers.command("regenerate <server>").description("Re-fetch a server's source spec and rebuild its tools with the current codegen (preserves customizations). Works for spec-URL, OpenAPI, and GraphQL sources; a pasted or manual server has nothing to re-fetch. Wraps POST /api/v1/server/regenerate.").option("--org <organizationId>", "Organization ID").option("--project <project>", "Project (id or name; defaults to the server's project)").option("--source-url <url>", "Read the spec from this URL for this run only — nothing is stored (needed for GraphQL servers whose introspection endpoint wasn't persisted). To change the stored source, use `mcp servers update <server> --source-url <url>`.").option("--dry-run", "Report what would change (per tool) without writing anything").addHelpText("after", [
     "",
     "Regenerate re-introspects/re-parses the source and rebuilds each tool with",
     "the current codegen, so codegen fixes reach existing servers. It does not",
@@ -8711,6 +8711,185 @@ function registerServerTransferCommand(servers) {
   }));
 }
 
+// src/commands/servers-update-source.ts
+async function changeServerSource(args) {
+  const data = await api.post("/api/v1/server/source", {
+    organizationId: args.orgId,
+    projectId: args.projectId,
+    serverId: args.serverId,
+    sourceUrl: args.sourceUrl,
+    ...args.dryRun ? { dryRun: true } : {}
+  });
+  return data.source;
+}
+function printSourceChange(change, serverId) {
+  printSuccess(change.applied ? `Spec source for ${c.bold(serverId)} is now ${change.sourceUrl}.` : `Spec source preview for ${c.bold(serverId)} — nothing stored.`);
+  const doc = change.document;
+  printKeyValue({
+    previous: change.previousSourceUrl ?? "— (none stored)",
+    source: change.urlChanged ? change.sourceUrl : `${change.sourceUrl} (unchanged — re-read)`,
+    type: change.sourceType,
+    document: `${doc.title ?? "Untitled"}${doc.version ? ` ${doc.version}` : ""} · ${doc.endpointCount} operation(s)`,
+    "left out (x-mcp: false)": change.excludedOperations.length > 0 ? formatNameList(change.excludedOperations) : "none",
+    "drift check": driftLine(change)
+  });
+  for (const warning of doc.warnings.slice(0, 3)) {
+    printWarn(`  ! ${warning}`);
+  }
+  const r = change.regeneration;
+  printInfo("");
+  printInfo("What a regenerate from this source would do:");
+  printKeyValue({
+    "tools that would change": String(r.updated),
+    "tools that would be added": String(r.inserted),
+    ...r.unchanged !== undefined ? { "tools unchanged": String(r.unchanged) } : {},
+    "tools dropped from spec": String(r.removed),
+    "input schemas that change": String(change.inputSchemaChanges.length)
+  });
+  for (const item of r.changes ?? []) {
+    printInfo(`  ~ ${item.name}${item.fields.length > 0 ? ` (${item.fields.join(", ")})` : ""}`);
+  }
+  for (const name of r.insertedNames ?? [])
+    printInfo(`  + ${name}`);
+  if (change.inputSchemaChanges.length > 0) {
+    printInfo(`  ~ input schema from the new document: ${formatNameList(change.inputSchemaChanges)}`);
+  }
+  if (r.removed > 0) {
+    printInfo(c.dim(`  → ${r.removed} tool(s) the new source no longer offers would be kept, not deleted (removal stays a manual action): ${formatNameList(r.removedKeys, 5)}`));
+  }
+  const drift = nameDriftWarning({
+    drift: r.nameDrift,
+    serverId,
+    offerPushSpecFlag: false
+  });
+  if (drift)
+    printWarn(`  ! ${drift}`);
+  printInfo(c.dim(change.applied ? `  → run \`mcp servers regenerate ${serverId}\`, then \`mcp servers deploy ${serverId} --wait\` to ship the new source. Nothing live changes until then.` : `  → run the same command without --dry-run to store this source.`));
+}
+function driftLine(change) {
+  if (!change.driftCheck.enabled)
+    return "not enabled for this source";
+  return change.driftCheck.reset ? "reset — the next daily check reads the new source" : "would be reset";
+}
+
+// src/commands/servers-update.ts
+function registerServerUpdateCommand(servers) {
+  servers.command("update <server>").description("Update a server (name, description, tool surface, upstream key mode, runtime token TTL, spec source URL)").option("--org <organizationId>", "Organization ID").option("--name <name>", "New display name").option("--description <text>", "New description").option("--discovery-mode <all|wrapper>", 'Tool surface: "all" registers every operation; "wrapper" registers searchTools/getToolDefinition/useTool INSTEAD (operations are called through useTool).').option("--code-mode <off|opt-in|default>", "Code Mode: expose codemode_execute so an agent can script several calls in one sandboxed run. Served by the edge, so it takes effect on the next deploy.").option("--upstream-api-key-mode <shared|perMember>", "Whose upstream credential the server uses: one shared key, or each member their own (Pro and above). perMember needs a protected access mode (privateOrg or unlisted) — refused while the active deployment is public.").option("--runtime-token-ttl <seconds|default>", 'Runtime token lifetime in seconds (60-86400; the default AND cap for minted tokens). Pass "default" to restore the 300s platform default.').option("--source-url <url>", "Read this server’s spec from a different URL from now on. The URL is fetched and parsed as the server’s source type first, and the report shows what a regenerate from it would change. Tools are not touched until you regenerate.").option("--dry-run", "With --source-url: fetch, parse and report without storing anything").addHelpText("after", [
+    "",
+    "Notes:",
+    "  Runtime defaults (oauth, deploymentDefaults, runtime bindings) are not",
+    "  v1 PATCH-able. Change them via `mcp servers deploy --upstream-*`.",
+    "  --discovery-mode and --code-mode change the server's TOOL SURFACE and",
+    "  reach clients on the next `mcp servers deploy`. Check what is live with",
+    "  `mcp servers get <server> --probe`.",
+    "",
+    "Changing the spec source (--source-url):",
+    "  Stores the URL together with the document it returns (codegen builds",
+    "  from that document) and resets the drift check so the next daily check",
+    "  reads the new source. Operations the spec marks `x-mcp: false` are left",
+    "  out. The live server changes only when you regenerate and deploy:",
+    "    $ mcp servers update srv_123 --source-url https://api.example.com/openapi.mcp.json --dry-run",
+    "    $ mcp servers update srv_123 --source-url https://api.example.com/openapi.mcp.json",
+    "    $ mcp servers regenerate srv_123 && mcp servers deploy srv_123 --wait",
+    "  `regenerate --source-url` is different: a one-run override that stores",
+    "  nothing."
+  ].join(`
+`)).action(runAction(async (serverRef, opts) => {
+    await runUpdate(serverRef, opts);
+  }));
+}
+async function runUpdate(serverRef, opts) {
+  const settings = buildSettingsPatch(opts);
+  const hasSettings = Object.keys(settings).length > 0;
+  if (opts.dryRun && opts.sourceUrl === undefined) {
+    throw new Error("--dry-run previews a --source-url change; pass --source-url <url>.");
+  }
+  if (opts.dryRun && hasSettings) {
+    throw new Error("--dry-run only previews --source-url. Run the other changes without --dry-run.");
+  }
+  if (!hasSettings && opts.sourceUrl === undefined) {
+    throw new Error("Provide at least one of --name, --description, --discovery-mode, --code-mode, --upstream-api-key-mode, --runtime-token-ttl, or --source-url.");
+  }
+  const orgId = await resolveOrgId(opts.org);
+  const serverId = await resolveServerId(serverRef, orgId);
+  const serverData = await api.get("/api/v1/server", { organizationId: orgId, serverId });
+  const projectId = serverData.server.projectId;
+  let source = null;
+  if (opts.sourceUrl !== undefined) {
+    if (!isJsonMode()) {
+      printStep(`${opts.dryRun ? "Checking" : "Reading"} ${c.bold(opts.sourceUrl)} for ${c.bold(serverId)}…`);
+    }
+    source = await changeServerSource({
+      orgId,
+      projectId,
+      serverId,
+      sourceUrl: opts.sourceUrl,
+      dryRun: Boolean(opts.dryRun)
+    });
+  }
+  let updated = null;
+  if (hasSettings) {
+    updated = await api.patch("/api/v1/server", {
+      organizationId: orgId,
+      projectId,
+      serverId,
+      ...settings
+    });
+  }
+  if (isJsonMode()) {
+    printJson({
+      ...updated ? { server: updated.server } : {},
+      ...source ? { source } : {}
+    });
+    return;
+  }
+  if (updated) {
+    const s = updated.server;
+    printSuccess(`Server ${s.id} updated.`);
+    printKeyValue({
+      id: s.id,
+      name: s.name,
+      description: s.description ?? "—",
+      status: s.status,
+      updated: formatDate(s.updatedAt)
+    });
+  }
+  if (source)
+    printSourceChange(source, serverId);
+}
+function buildSettingsPatch(opts) {
+  const body = {};
+  if (opts.name !== undefined)
+    body["name"] = opts.name;
+  if (opts.description !== undefined)
+    body["description"] = opts.description;
+  if (opts.discoveryMode !== undefined) {
+    body["discoveryMode"] = validateChoice("discovery-mode", opts.discoveryMode, ["all", "wrapper"]);
+  }
+  if (opts.codeMode !== undefined) {
+    body["codeModeMode"] = validateChoice("code-mode", opts.codeMode, [
+      "off",
+      "opt-in",
+      "default"
+    ]);
+  }
+  if (opts.upstreamApiKeyMode !== undefined) {
+    body["upstreamApiKeyMode"] = validateChoice("upstream-api-key-mode", opts.upstreamApiKeyMode, ["shared", "perMember"]);
+  }
+  if (opts.runtimeTokenTtl !== undefined) {
+    if (opts.runtimeTokenTtl === "default") {
+      body["runtimeTokenTtlSeconds"] = null;
+    } else {
+      const ttl = Number(opts.runtimeTokenTtl);
+      if (!Number.isInteger(ttl)) {
+        throw new Error('--runtime-token-ttl must be an integer number of seconds, or "default".');
+      }
+      body["runtimeTokenTtlSeconds"] = ttl;
+    }
+  }
+  return body;
+}
+
 // src/commands/servers-mutations.ts
 function registerServerMutationCommands(servers) {
   servers.command("create").description("Create an empty server skeleton in a project").requiredOption("--project <project>", "Project (id or name)").requiredOption("--name <name>", "Display name (1–100 chars)").option("--org <organizationId>", "Organization ID").option("--description <text>", "Optional description").option("--git-repo <owner/name>", "Host the generated code on this GitHub repo (links now, mirrors after first generation)").option("--git-path-prefix <prefix>", "Sync into this path inside the repo").option("--no-git-auto-sync", "Do not mirror commits automatically").addHelpText("after", [
@@ -8761,70 +8940,7 @@ function registerServerMutationCommands(servers) {
       created: formatDate(s.createdAt)
     });
   }));
-  servers.command("update <server>").description("Update a server (name, description, tool surface, upstream key mode, runtime token TTL)").option("--org <organizationId>", "Organization ID").option("--name <name>", "New display name").option("--description <text>", "New description").option("--discovery-mode <all|wrapper>", 'Tool surface: "all" registers every operation; "wrapper" registers searchTools/getToolDefinition/useTool INSTEAD (operations are called through useTool).').option("--code-mode <off|opt-in|default>", "Code Mode: expose codemode_execute so an agent can script several calls in one sandboxed run. Served by the edge, so it takes effect on the next deploy.").option("--upstream-api-key-mode <shared|perMember>", "Whose upstream credential the server uses: one shared key, or each member their own (Pro and above). perMember needs a protected access mode (privateOrg or unlisted) — refused while the active deployment is public.").option("--runtime-token-ttl <seconds|default>", 'Runtime token lifetime in seconds (60-86400; the default AND cap for minted tokens). Pass "default" to restore the 300s platform default.').addHelpText("after", [
-    "",
-    "Notes:",
-    "  Runtime defaults (oauth, deploymentDefaults, runtime bindings) are not",
-    "  v1 PATCH-able. Change them via `mcp servers deploy --upstream-*`.",
-    "  --discovery-mode and --code-mode change the server's TOOL SURFACE and",
-    "  reach clients on the next `mcp servers deploy`. Check what is live with",
-    "  `mcp servers get <server> --probe`."
-  ].join(`
-`)).action(runAction(async (serverRef, opts) => {
-    const orgId = await resolveOrgId(opts.org);
-    const serverId = await resolveServerId(serverRef, orgId);
-    const serverData = await api.get("/api/v1/server", { organizationId: orgId, serverId });
-    const body = {
-      organizationId: orgId,
-      projectId: serverData.server.projectId,
-      serverId
-    };
-    if (opts.name !== undefined)
-      body["name"] = opts.name;
-    if (opts.description !== undefined)
-      body["description"] = opts.description;
-    if (opts.discoveryMode !== undefined) {
-      body["discoveryMode"] = validateChoice("discovery-mode", opts.discoveryMode, ["all", "wrapper"]);
-    }
-    if (opts.codeMode !== undefined) {
-      body["codeModeMode"] = validateChoice("code-mode", opts.codeMode, [
-        "off",
-        "opt-in",
-        "default"
-      ]);
-    }
-    if (opts.upstreamApiKeyMode !== undefined) {
-      body["upstreamApiKeyMode"] = validateChoice("upstream-api-key-mode", opts.upstreamApiKeyMode, ["shared", "perMember"]);
-    }
-    if (opts.runtimeTokenTtl !== undefined) {
-      if (opts.runtimeTokenTtl === "default") {
-        body["runtimeTokenTtlSeconds"] = null;
-      } else {
-        const ttl = Number(opts.runtimeTokenTtl);
-        if (!Number.isInteger(ttl)) {
-          throw new Error('--runtime-token-ttl must be an integer number of seconds, or "default".');
-        }
-        body["runtimeTokenTtlSeconds"] = ttl;
-      }
-    }
-    if (Object.keys(body).length === 3) {
-      throw new Error("Provide at least one of --name, --description, --discovery-mode, --code-mode, --upstream-api-key-mode, or --runtime-token-ttl.");
-    }
-    const data = await api.patch("/api/v1/server", body);
-    if (isJsonMode()) {
-      printJson(data);
-      return;
-    }
-    const s = data.server;
-    printSuccess(`Server ${s.id} updated.`);
-    printKeyValue({
-      id: s.id,
-      name: s.name,
-      description: s.description ?? "—",
-      status: s.status,
-      updated: formatDate(s.updatedAt)
-    });
-  }));
+  registerServerUpdateCommand(servers);
   servers.command("pause <server>").description("Pause the server's latest active deployment (traffic stops; worker is preserved)").option("--org <organizationId>", "Organization ID").option("--project <project>", "Project (id or name; defaults to the server's project)").addHelpText("after", [
     "",
     "Notes:",
@@ -37337,6 +37453,11 @@ var CLI_EXAMPLES = {
     "mcp servers regenerate srv_abc --dry-run",
     "mcp servers regenerate srv_abc && mcp servers deploy srv_abc --wait"
   ],
+  "servers update": [
+    'mcp servers update srv_abc --name "Payments API"',
+    "mcp servers update srv_abc --source-url https://api.example.com/openapi.mcp.json --dry-run",
+    "mcp servers update srv_abc --source-url https://api.example.com/openapi.mcp.json"
+  ],
   "servers env list": ["mcp servers env list srv_abc"],
   "servers env set": [
     "mcp servers env set srv_abc OPENAI_API_KEY=sk-...",

package/package.json

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