@mcpcloud/cli 0.25.1 → 0.26.0-next-20260927194247

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), storing the spec document it read so the generated code and the drift check follow it. 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,11 +8278,16 @@ 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: the tools are rebuilt from it, but the stored source and its document are left as they are (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",
-    "deploy — run `mcp servers deploy` afterwards to ship the rebuilt bundle.",
+    "the current codegen, so codegen fixes AND upstream spec changes reach",
+    "existing servers. It stores the spec document it read — codegen builds",
+    "from that document and the daily drift check compares against it — and",
+    "resets the drift check. It does not deploy — run `mcp servers deploy`",
+    "afterwards to ship the rebuilt bundle.",
+    "With --source-url for a different URL, the document is NOT stored: an",
+    "override is for one run, and the stored source keeps pointing where it did.",
     "It never renames a tool: names that predate the current naming rule",
     "(getrecording vs getRecording) are reported, and",
     "`mcp tools rename --from-operation-ids` adopts the rule.",
@@ -8343,7 +8348,8 @@ function printRegeneration(r, serverId) {
     [`tools ${dryRun ? "that would be added" : "added"}`]: String(r.inserted),
     ...r.unchanged !== undefined ? { "tools unchanged": String(r.unchanged) } : {},
     "tools dropped from spec": String(r.removed),
-    generation: r.generationStatus
+    generation: r.generationStatus,
+    ...r.storedDocument ? { "spec document": storedDocumentLine(r.storedDocument) } : {}
   });
   for (const change of r.changes ?? []) {
     printInfo(`  ~ ${change.name}${change.fields.length > 0 ? ` (${change.fields.join(", ")})` : ""}`);
@@ -8360,8 +8366,21 @@ function printRegeneration(r, serverId) {
   });
   if (drift)
     printWarn(`  ! ${drift}`);
+  if (r.storedDocument === "keptForOverride") {
+    printInfo(c.dim(`  → to read ${serverId} from that URL from now on: \`mcp servers update ${serverId} --source-url <url>\`, then regenerate.`));
+  }
   printInfo(c.dim(dryRun ? `  → run \`mcp servers regenerate ${serverId}\` (without --dry-run) to apply, then \`mcp servers deploy ${serverId} --wait\`.` : `  → run \`mcp servers deploy ${serverId} --wait\` to ship the regenerated bundle.`));
 }
+function storedDocumentLine(disposition) {
+  switch (disposition) {
+    case "refreshed":
+      return "stored — codegen builds from it; drift check reset";
+    case "wouldRefresh":
+      return "would be stored (and the drift check reset)";
+    case "keptForOverride":
+      return "kept — --source-url reads another URL for this run only";
+  }
+}
 
 // src/commands/servers-lifecycle.ts
 function registerServerLifecycleCommands(servers) {
@@ -8711,6 +8730,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 +8959,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 +37472,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-20260927194247",
   "description": "The official CLI for MCPCloud — manage projects, servers, skills, and API keys from the terminal",
   "type": "module",
   "bin": {