@mcpcloud/cli 0.1.0 → 0.1.3

package/README.md

@@ -4,10 +4,14 @@ The official command-line interface for [MCPCloud](https://mcpcloud.sh) — mana
 
 ```sh
 npm install -g @mcpcloud/cli
+export MCPCLOUD_BASE_URL=https://your-deployment.example.com   # ask your admin
 mcpsh login
 mcpsh whoami
 ```
 
+> **Note**
+> MCPCloud is in private beta. The CLI does **not** ship with a default API base URL — set `MCPCLOUD_BASE_URL` (or `mcpsh config set-url <url>`) using the URL provided by your MCPCloud admin. A built-in default will be added when the platform launches publicly.
+
 The package installs two equivalent binaries: `mcpsh` (short) and `mcpcloud` (full). Use whichever you prefer.
 
 ## Requirements
@@ -27,20 +31,39 @@ npx -y @mcpcloud/cli whoami
 bunx --bun @mcpcloud/cli whoami
 ```
 
-## Authentication
+## Configuration
+
+The CLI needs **two** values to talk to your MCPCloud deployment: an API base URL and an API key. Either or both can come from environment variables, the saved config file, or per-invocation flags.
+
+### 1. Set the API base URL
 
-You can authenticate two ways. The CLI prefers the environment variable when both are set.
+The CLI does not assume any default base URL. Use whichever method fits your environment:
 
 ```sh
-# 1. Save a key to ~/.mcpcloud/config.json (mode 0600)
+# environment variable (recommended for CI / scripts)
+export MCPCLOUD_BASE_URL=https://your-deployment.example.com
+
+# persist for your user account (writes to ~/.mcpcloud/config.json)
+mcpsh config set-url https://your-deployment.example.com
+
+# one-off override
+mcpsh --base-url https://your-deployment.example.com whoami
+```
+
+The lookup order is: `--base-url` flag → `MCPCLOUD_BASE_URL` env var → saved `baseUrl` in `~/.mcpcloud/config.json`. If none are set the CLI exits with code `3` and a clear message.
+
+### 2. Authenticate
+
+```sh
+# Save a key to ~/.mcpcloud/config.json (mode 0600)
 mcpsh login                       # interactive prompt (recommended)
 mcpsh login --key mck_xxx         # non-interactive (avoid: writes to shell history)
 
-# 2. Use an environment variable (recommended for CI)
+# Or use an environment variable (recommended for CI)
 export MCPCLOUD_API_KEY=mck_xxx
 ```
 
-`mcpsh logout` removes the saved key.
+`mcpsh logout` removes the saved key. `mcpsh config show` prints the current resolved config (with the API key redacted).
 
 ## Quick start
 
@@ -75,7 +98,7 @@ Run `mcpsh <command> --help` on any command for the full option list.
 | Variable | Description |
 |---|---|
 | `MCPCLOUD_API_KEY` | API key used for authentication (overrides the saved config). |
-| `MCPCLOUD_BASE_URL` | Override the API base URL. Default: `https://mcpcloud.sh`. |
+| `MCPCLOUD_BASE_URL` | API base URL. **Required** — there is no built-in default. |
 | `MCPCLOUD_ORG_ID` | Default organization ID for commands that require one. |
 
 The organization for each command is resolved in this order:
@@ -87,12 +110,18 @@ The organization for each command is resolved in this order:
 
 ## Commands
 
-### Authentication
+### Authentication & config
 
 ```sh
 mcpsh login [--key <secret>]      # save an API key locally
 mcpsh logout                      # remove the saved key
 mcpsh whoami                      # show current key, base URL, and accessible orgs
+
+mcpsh config show                 # print resolved config (key redacted)
+mcpsh config set-url <url>        # persist the API base URL
+mcpsh config clear-url            # remove the saved base URL
+mcpsh config set-org <orgId>      # persist a default organization
+mcpsh config clear-org            # remove the saved default organization
 ```
 
 ### Projects
@@ -113,7 +142,8 @@ mcpsh servers logs <serverId> [--org <id>] [--limit <n>]
 ### Tools
 
 ```sh
-mcpsh tools list <serverId> [--org <id>]
+mcpsh tools list --project <projectId> [--org <id>]
+mcpsh tools list --server <serverId>  [--org <id>]   # looks up the project for you
 ```
 
 ### Skills
@@ -158,6 +188,7 @@ mcpsh --json skills connect skl_123 --agent cursor \
 | `0` | Success. |
 | `1` | Generic failure (API error, validation error, network error). |
 | `2` | No API key configured. Run `mcpsh login` or set `MCPCLOUD_API_KEY`. |
+| `3` | No API base URL configured. Set `MCPCLOUD_BASE_URL` or run `mcpsh config set-url <url>`. |
 
 When an API call fails, the CLI prints the response code, status, and request id (when present) to make debugging easier:
 
@@ -173,9 +204,9 @@ The CLI stores its config at `~/.mcpcloud/config.json` with mode `0600`. Recogni
 
 ```jsonc
 {
-  "apiKey": "mck_...",                      // saved by `mcpsh login`
-  "baseUrl": "https://staging.mcpcloud.sh", // overrides the default
-  "defaultOrganizationId": "org_..."        // used when --org is omitted
+  "apiKey": "mck_...",                       // saved by `mcpsh login`
+  "baseUrl": "https://your-deployment...",   // saved by `mcpsh config set-url`
+  "defaultOrganizationId": "org_..."         // saved by `mcpsh config set-org`
 }
 ```
 

package/dist/index.js

@@ -1878,7 +1878,6 @@ var {
 import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-var DEFAULT_BASE_URL = "https://mcpcloud.sh";
 function configDir() {
   return join(homedir(), ".mcpcloud");
 }
@@ -1892,6 +1891,13 @@ class MissingApiKeyError extends Error {
     this.name = "MissingApiKeyError";
   }
 }
+
+class MissingBaseUrlError extends Error {
+  constructor() {
+    super("No API base URL configured. Set MCPCLOUD_BASE_URL, pass --base-url, or save one with `mcpsh config set-url <url>`.");
+    this.name = "MissingBaseUrlError";
+  }
+}
 function readConfig() {
   if (!existsSync(configFile()))
     return {};
@@ -1923,7 +1929,10 @@ function setBaseUrlOverride(url) {
   baseUrlOverride = url;
 }
 function getBaseUrl() {
-  return baseUrlOverride ?? process.env["MCPCLOUD_BASE_URL"] ?? readConfig().baseUrl ?? DEFAULT_BASE_URL;
+  const url = baseUrlOverride ?? process.env["MCPCLOUD_BASE_URL"] ?? readConfig().baseUrl;
+  if (!url)
+    throw new MissingBaseUrlError;
+  return url;
 }
 function requireApiKey() {
   const key = getApiKey();
@@ -1968,6 +1977,9 @@ function buildUrl(path, params) {
 function shouldRetry(attempt, err) {
   if (attempt >= MAX_RETRIES)
     return false;
+  if (err instanceof Error && (err.name === "MissingApiKeyError" || err.name === "MissingBaseUrlError")) {
+    return false;
+  }
   if (err instanceof McpCloudNetworkError)
     return true;
   if (err instanceof McpCloudApiError && RETRYABLE_STATUSES.has(err.status))
@@ -2032,9 +2044,10 @@ async function performRequest(method, path, options) {
     init.body = JSON.stringify(options.body);
   }
   try {
+    const url = buildUrl(path, options.params);
     let res;
     try {
-      res = await fetch(buildUrl(path, options.params), init);
+      res = await fetch(url, init);
     } catch (err) {
       if (controller.signal.aborted && !externalSignal?.aborted) {
         throw new McpCloudNetworkError(`Request to ${path} timed out after ${timeoutMs}ms.`, err);
@@ -2144,6 +2157,9 @@ function describeError(err) {
   if (err instanceof MissingApiKeyError) {
     return { message: err.message, code: "missing_api_key" };
   }
+  if (err instanceof MissingBaseUrlError) {
+    return { message: err.message, code: "missing_base_url" };
+  }
   if (err instanceof Error) {
     return { message: err.message };
   }
@@ -2165,7 +2181,11 @@ function handleError(err) {
     if (info.docsUrl)
       console.error(`  docs:       ${info.docsUrl}`);
   }
-  process.exit(info.code === "missing_api_key" ? 2 : 1);
+  if (info.code === "missing_api_key")
+    process.exit(2);
+  if (info.code === "missing_base_url")
+    process.exit(3);
+  process.exit(1);
 }
 
 // src/lib/version.ts
@@ -2373,6 +2393,11 @@ function registerProjectCommands(program2) {
 }
 
 // src/commands/servers.ts
+function formatEventTimestamp(ms) {
+  if (typeof ms !== "number" || !Number.isFinite(ms))
+    return "—".padEnd(24);
+  return new Date(ms).toISOString();
+}
 function registerServerCommands(program2) {
   const servers = program2.command("servers").description("Manage MCP servers");
   servers.command("list").description("List servers").option("--org <organizationId>", "Organization ID").option("--project <projectId>", "Filter by project ID").option("--limit <n>", "Maximum results (default 25)", parsePositiveIntOption("limit"), "25").action(runAction(async (opts) => {
@@ -2454,20 +2479,33 @@ function registerServerCommands(program2) {
       return;
     }
     for (const event of data.events) {
-      const ts = new Date(event.createdAt).toISOString();
-      console.log(`${ts}  [${event.type}]  ${event.message}`);
+      const ts = formatEventTimestamp(event.timestamp);
+      const level = (event.level || "info").toUpperCase().padEnd(5);
+      const stage = (event.stage || "").padEnd(8);
+      console.log(`${ts}  ${level}  ${stage}  ${event.message}`);
     }
   }));
 }
 
 // src/commands/tools.ts
 function registerToolCommands(program2) {
-  const tools = program2.command("tools").description("Inspect tools on an MCP server");
-  tools.command("list <serverId>").description("List tools for a server").option("--org <organizationId>", "Organization ID").action(runAction(async (serverId, opts) => {
+  const tools = program2.command("tools").description("Inspect tools on a project or server");
+  tools.command("list").description("List tools for a project (or pass --server to look up its project automatically)").option("--org <organizationId>", "Organization ID").option("--project <projectId>", "Project ID to list tools for").option("--server <serverId>", "Server ID — the CLI fetches the server's projectId before listing tools").action(runAction(async (opts) => {
     const orgId = await resolveOrgId(opts.org);
+    if (!opts.project && !opts.server) {
+      throw new Error("Pass either --project <projectId> or --server <serverId>.");
+    }
+    let projectId = opts.project;
+    if (!projectId && opts.server) {
+      const serverData = await api.get("/api/v1/server", {
+        organizationId: orgId,
+        serverId: opts.server
+      });
+      projectId = serverData.server.projectId;
+    }
     const data = await api.get("/api/v1/project/tools", {
       organizationId: orgId,
-      serverId
+      projectId
     });
     if (isJsonMode()) {
       printJson(data);
@@ -2812,29 +2850,112 @@ function registerApiKeyCommands(program2) {
   }));
 }
 
+// src/commands/config.ts
+import { homedir as homedir2 } from "node:os";
+import { join as join3 } from "node:path";
+function configFilePath() {
+  return join3(homedir2(), ".mcpcloud", "config.json");
+}
+function previewKey2(key) {
+  if (!key)
+    return;
+  if (key.length <= 12)
+    return `${key.slice(0, 4)}…`;
+  return `${key.slice(0, 8)}…${key.slice(-4)}`;
+}
+function registerConfigCommands(program2) {
+  const config = program2.command("config").description("Manage CLI configuration in ~/.mcpcloud/config.json");
+  config.command("show").description("Print the current saved config (API key is redacted)").action(runAction(() => {
+    const c = readConfig();
+    const safe = {
+      path: configFilePath(),
+      baseUrl: c.baseUrl ?? null,
+      defaultOrganizationId: c.defaultOrganizationId ?? null,
+      apiKeyPreview: previewKey2(c.apiKey) ?? null
+    };
+    if (isJsonMode()) {
+      printJson(safe);
+      return;
+    }
+    printKeyValue({
+      path: safe.path,
+      "base url": safe.baseUrl ?? "—",
+      "default org": safe.defaultOrganizationId ?? "—",
+      "api key": safe.apiKeyPreview ?? "—"
+    });
+  }));
+  config.command("set-url <url>").description("Save the API base URL to ~/.mcpcloud/config.json").action(runAction((url) => {
+    try {
+      new URL(url);
+    } catch {
+      throw new Error(`Invalid URL: ${url}`);
+    }
+    const c = readConfig();
+    c.baseUrl = url;
+    writeConfig(c);
+    if (isJsonMode()) {
+      printJson({ baseUrl: url });
+      return;
+    }
+    printSuccess(`Saved base URL: ${url}`);
+  }));
+  config.command("clear-url").description("Remove the saved base URL (falls back to MCPCLOUD_BASE_URL)").action(runAction(() => {
+    const c = readConfig();
+    delete c.baseUrl;
+    writeConfig(c);
+    if (isJsonMode()) {
+      printJson({ baseUrl: null });
+      return;
+    }
+    printSuccess("Cleared saved base URL.");
+  }));
+  config.command("set-org <organizationId>").description("Save a default organization ID").action(runAction((organizationId) => {
+    const c = readConfig();
+    c.defaultOrganizationId = organizationId;
+    writeConfig(c);
+    if (isJsonMode()) {
+      printJson({ defaultOrganizationId: organizationId });
+      return;
+    }
+    printSuccess(`Saved default organization: ${organizationId}`);
+  }));
+  config.command("clear-org").description("Remove the saved default organization ID").action(runAction(() => {
+    const c = readConfig();
+    delete c.defaultOrganizationId;
+    writeConfig(c);
+    if (isJsonMode()) {
+      printJson({ defaultOrganizationId: null });
+      return;
+    }
+    printSuccess("Cleared saved default organization.");
+  }));
+}
+
 // src/create-program.ts
 function createProgram() {
   const program2 = new Command;
-  program2.name("mcpsh").description("The official CLI for MCPCloud — manage projects, MCP servers, skills, and API keys from the terminal").version(getCliVersion(), "-v, --version", "Print the CLI version").option("--json", "Output raw JSON (useful for scripting)").option("--base-url <url>", "Override the API base URL (defaults to MCPCLOUD_BASE_URL or https://mcpcloud.sh)").hook("preAction", (thisCommand) => {
+  program2.name("mcpsh").description("The official CLI for MCPCloud — manage projects, MCP servers, skills, and API keys from the terminal").version(getCliVersion(), "-v, --version", "Print the CLI version").option("--json", "Output raw JSON (useful for scripting)").option("--base-url <url>", "API base URL for this invocation. Falls back to MCPCLOUD_BASE_URL or `mcpsh config set-url`.").hook("preAction", (thisCommand) => {
     const opts = thisCommand.optsWithGlobals();
     setJsonMode(Boolean(opts.json));
     setBaseUrlOverride(opts.baseUrl);
   }).addHelpText("after", [
     "",
     "Environment variables:",
-    "  MCPCLOUD_API_KEY    API key used for authentication",
-    "  MCPCLOUD_BASE_URL   Override the API base URL",
+    "  MCPCLOUD_API_KEY    API key used for authentication (required)",
+    "  MCPCLOUD_BASE_URL   API base URL (required — no default is shipped)",
     "  MCPCLOUD_ORG_ID     Default organization ID",
     "",
     "Examples:",
+    "  $ export MCPCLOUD_BASE_URL=https://your-deployment.example.com",
+    "  $ mcpsh config set-url https://your-deployment.example.com   # persist it",
     "  $ mcpsh login",
     "  $ mcpsh whoami",
-    "  $ mcpsh projects list",
     "  $ mcpsh skills connect skill_123 --agent claude-code --apply",
     "  $ mcpsh --json servers list"
   ].join(`
 `));
   registerAuthCommands(program2);
+  registerConfigCommands(program2);
   registerProjectCommands(program2);
   registerServerCommands(program2);
   registerToolCommands(program2);

package/package.json

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