svcloud 0.1.0-alpha.4 → 0.1.1

package/README.md

@@ -3,24 +3,26 @@
 The command-line interface for [SV Cloud](https://cloud.sv-academy.org) — and
 the way an AI coding agent reaches the platform.
 
-> **Alpha.** Sign-in, status, app listing, the `mcp` bridge, and `init`
-> (below) are built — see Commands for the full current list. `logs`,
-> `deploy`, `secrets`, `db`, and `dev` are still on the way. Published under
-> the `alpha` dist-tag, not `latest`.
+> **Alpha.** Published under the `alpha` dist-tag, not `latest` — see
+> Commands below for what's built. `logs` and `dev` are still on the way.
 
 ## Install
 
 ```bash
-npx svcloud@alpha login
+npm install -g svcloud
+svcloud login
 ```
 
-Or install it:
+Or try it once without installing:
 
 ```bash
-npm install -g svcloud@alpha
-svcloud login
+npx svcloud login
 ```
 
+An installed `svcloud` is what every example below uses, and is what a
+coding agent's harness config should point at too — see [Connect your coding
+agent](#connect-your-coding-agent).
+
 `login` opens your browser to sign in, then stores your session in your
 system's keychain (Keychain on macOS; Secret Service on Linux; Credential
 Manager on Windows — falling back to a local file, with a warning, if none
@@ -37,7 +39,12 @@ svcloud open <app>            Open an app's web address in your browser
 svcloud projects list         List your apps
 svcloud init                  Connect a repo (defaults to the one in your working directory) as a new app
 svcloud runs <app>            Show or watch an app's provisioning run
+svcloud secrets <cmd>         Manage an app's keys & settings (list/set/remove)
+svcloud db <cmd>              Browse and edit an app's database (see `svcloud db` for subcommands)
+svcloud deploy <app>          Push the current branch and watch the build (must be the app's default branch)
 svcloud mcp                   Run the local MCP bridge (for a coding agent's harness config)
+svcloud mcp setup <harness>   Write a coding agent harness's MCP config for svcloud
+svcloud mcp check             Diagnose sign-in state, harness configs, and live tool visibility
 
 Flags:
   --json                      Machine-readable output, on every read command
@@ -49,7 +56,7 @@ to skip what it would otherwise infer or ask about; `runs` reads `--id
 (follow it to completion). Neither needs any of that in the common case:
 `cd` into your repo and run `svcloud init`.
 
-More commands (`logs`, `deploy`, `secrets`, `db`, `dev`) are on the way.
+`logs` and `dev` are still on the way.
 
 ## Connect your coding agent
 
@@ -66,7 +73,19 @@ First, sign in on your machine:
 svcloud login
 ```
 
-Then configure your agent:
+Then let the CLI write your harness's config for you:
+
+```bash
+svcloud mcp setup claude-code   # or: cursor | opencode | antigravity | gemini-cli | codex
+```
+
+That writes the one file each harness actually reads, in the shape it
+actually expects — the config blocks below are the same data, by hand, for a
+harness that isn't in the list yet, or if you'd rather see exactly what gets
+written first. If something still doesn't work after setup, run
+`svcloud mcp check` — it reports sign-in state, a live count of tools your
+token can see, and whether each known harness's config file exists and has
+the right shape.
 
 ### Antigravity
 Add to `~/.gemini/config/mcp_config.json` (global) or `.agents/mcp_config.json` (workspace):
@@ -75,8 +94,8 @@ Add to `~/.gemini/config/mcp_config.json` (global) or `.agents/mcp_config.json`
 {
   "mcpServers": {
     "svcloud": {
-      "command": "npx",
-      "args": ["-y", "svcloud@alpha", "mcp"]
+      "command": "svcloud",
+      "args": ["mcp"]
     }
   }
 }
@@ -84,7 +103,7 @@ Add to `~/.gemini/config/mcp_config.json` (global) or `.agents/mcp_config.json`
 
 ### Gemini CLI
 ```bash
-gemini mcp add svcloud -- npx -y svcloud@alpha mcp
+gemini mcp add svcloud -- svcloud mcp
 ```
 Or add the `svcloud` block under `mcpServers` in `~/.gemini/config.json` or `~/.gemini/mcp_config.json`.
 
@@ -92,36 +111,56 @@ Or add the `svcloud` block under `mcpServers` in `~/.gemini/config.json` or `~/.
 Go to **Settings** > **Features** > **MCP** > **Add New MCP Server**:
 - **Name:** `svcloud`
 - **Type:** `command`
-- **Command:** `npx -y svcloud@alpha mcp`
+- **Command:** `svcloud mcp`
 
 Or add directly to `.cursor/mcp.json`:
 ```json
 {
   "mcpServers": {
     "svcloud": {
-      "command": "npx",
-      "args": ["-y", "svcloud@alpha", "mcp"]
+      "command": "svcloud",
+      "args": ["mcp"]
     }
   }
 }
 ```
 
 ### OpenCode
-In `~/.config/opencode/mcp.json` or your OpenCode configuration:
+OpenCode does **not** read `mcpServers` — that's the Claude-style shape every
+other harness here uses, and writing it to OpenCode's config produces a file
+that looks installed but does nothing. OpenCode reads a top-level `mcp` key,
+in `~/.config/opencode/opencode.json` (global) or `opencode.json`/
+`opencode.jsonc` at your project root, and each server needs `"type":
+"local"` with `command` as an array:
+
 ```json
 {
-  "mcpServers": {
+  "mcp": {
     "svcloud": {
-      "command": "npx",
-      "args": ["-y", "svcloud@alpha", "mcp"]
+      "type": "local",
+      "command": ["svcloud", "mcp"]
     }
   }
 }
 ```
 
+`svcloud mcp setup opencode` writes exactly this, to the right file — the
+safest way to get it right by hand is still to run that.
+
 ### Claude Code
 ```bash
-claude mcp add svcloud -- npx -y svcloud@alpha mcp
+claude mcp add svcloud -- svcloud mcp
+```
+Or add directly to `.mcp.json` at your project root:
+```json
+{
+  "mcpServers": {
+    "svcloud": {
+      "command": "svcloud",
+      "args": ["mcp"]
+    }
+  }
+}
 ```
 
 ### Codex
@@ -130,8 +169,8 @@ In `~/.codex/config.json` or your Codex MCP settings:
 {
   "mcpServers": {
     "svcloud": {
-      "command": "npx",
-      "args": ["-y", "svcloud@alpha", "mcp"]
+      "command": "svcloud",
+      "args": ["mcp"]
     }
   }
 }
@@ -141,24 +180,21 @@ In `~/.codex/config.json` or your Codex MCP settings:
 In any harness or configuration file that accepts an `mcpServers` block:
 
 ```jsonc
-{ "svcloud": { "command": "npx", "args": ["-y", "svcloud@alpha", "mcp"] } }
+{ "svcloud": { "command": "svcloud", "args": ["mcp"] } }
 ```
 
+Running it through `npx` instead works too (`{ "command": "npx", "args":
+["-y", "svcloud", "mcp"] }`), but costs a network round-trip on every
+start and depends on the npm registry being up — prefer an installed
+`svcloud` for anything you use daily.
+
 Your agent never sees your token and never has to sign in on its own. Signing
 out (`svcloud logout`) cuts its access off too.
 
-For an agent you use every day, install it rather than running it through
-`npx`: an installed `svcloud` starts instantly, works offline, and only changes
-version when you ask it to.
-
-```jsonc
-{ "svcloud": { "command": "svcloud", "args": ["mcp"] } }
-```
-
 ### Upgrading
 
 ```bash
-npm install -g svcloud@alpha
+npm install -g svcloud
 ```
 
 Your agent picks up the new version the next time it starts — restart the MCP
@@ -174,7 +210,9 @@ at the moment you sign in. If we widen what the CLI can be granted, run
 list no matter how new your CLI is, since scopes are frozen at sign-in, not
 re-checked against the current defaults. (**2026-08-25:** we just did this —
 run `svcloud login` again to see the full tool list, including database and
-settings tools that were previously invisible to the bridge.)
+settings tools that were previously invisible to the bridge.) `svcloud mcp
+check` flags this for you — it warns when your session has fewer scopes than
+SV Cloud currently grants by default.
 
 A harness that can run its own OAuth flow (a hosted agent, not one running on
 your machine) can also talk to SV Cloud directly at

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svcloud",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.1",
   "description": "The SV Cloud CLI. Alpha: login, logout, status, open, projects list, mcp, init, and runs are built; see PLANNING.md for what's still missing.",
   "type": "module",
   "license": "UNLICENSED",
@@ -15,17 +15,17 @@
   "engines": {
     "node": ">=22.18.0"
   },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  },
   "dependencies": {
     "tsx": "^4.20.0"
   },
   "devDependencies": {
+    "@sv/cloud-contracts": "workspace:*",
     "@types/node": "^22.13.0",
-    "typescript": "^5.9.3",
-    "@sv/cloud-contracts": "0.0.0"
-  },
-  "scripts": {
-    "dev": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test test/*.test.ts"
+    "typescript": "^5.9.3"
   }
-}
+}

package/src/commands/db.ts

@@ -1,16 +1,16 @@
 /**
  * `svcloud db` — PLANNING.md §4 Step 5. Mirrors F8's row editor
- * (`apps/cloud/src/routes/database.ts`) plus the two DDL routes added
- * alongside this command (`create_table`/`run_migration`, previously
- * MCP-tool-only — see that file's header). Cell/column payloads are taken as
- * JSON on the command line rather than a flag-per-field grammar: the primary
+ * (`apps/cloud/src/routes/database.ts`) plus the DDL routes added
+ * alongside this command (`db_create_table`/`db_run_migration`/`db_create_index`,
+ * previously MCP-tool-only — see that file's header). Cell/column payloads are taken
+ * as JSON on the command line rather than a flag-per-field grammar: the primary
  * caller for structured data like this is a coding agent, and it goes
  * through `svcloud mcp`'s tools directly (`lib/prompt.ts`'s header), not this
  * command — this path exists for a human or a script at a real terminal.
  */
 import { apiFetch } from "../lib/api";
 import { findProjectBySlug } from "../lib/find-project";
-import { die, printJson, printTable, takeOption } from "../lib/output";
+import { die, hasFlag, printJson, printTable, takeOption } from "../lib/output";
 
 const USAGE = `Usage:
   svcloud db tables <app>
@@ -18,12 +18,14 @@ const USAGE = `Usage:
   svcloud db insert <app> <table> <cells-json>
   svcloud db update <app> <table> <row-id> <cells-json>
   svcloud db delete <app> <table> <row-id>
-  svcloud db create-table <app> <table> <columns-json> --primary-key <name>
+  svcloud db create-table <app> <table> <columns-json> --primary-key <name> [--indexes <indexes-json>]
+  svcloud db create-index <app> <table> <columns-json> [--name <name>] [--unique]
   svcloud db migrate <app> <table> <column-json> [--default <value>]
 
 <cells-json> is a JSON object, e.g. '{"title":"Hello"}'
 <columns-json> is a JSON array, e.g. '[{"name":"id","type":"uuid","nullable":false},{"name":"title","type":"text"}]'
 <column-json> is a single column, e.g. '{"name":"count","type":"number","nullable":false}'
+<indexes-json> is a JSON array of indexes, e.g. '[{"columns":["email"],"unique":true}]'
 Column types: text, number, boolean, timestamp, json, uuid`;
 
 interface DbColumn {
@@ -125,12 +127,18 @@ async function dbRows(argv: string[], json: boolean): Promise<void> {
     printJson(page);
     return;
   }
+  const hasIdColumn = page.columns.some((c) => c.name === "id");
+  const headers = hasIdColumn
+    ? page.columns.map((c) => c.name)
+    : ["id", ...page.columns.map((c) => c.name)];
   printTable(
-    page.rows.map((r) => ({
-      id: r.id,
-      ...Object.fromEntries(page.columns.map((c) => [c.name, stringifyCell(r.cells[c.name])])),
-    })),
-    ["id", ...page.columns.map((c) => c.name)],
+    page.rows.map((r) => {
+      const cells = Object.fromEntries(
+        page.columns.map((c) => [c.name, stringifyCell(r.cells[c.name])]),
+      );
+      return hasIdColumn ? cells : { id: r.id, ...cells };
+    }),
+    headers,
   );
   if (page.truncated) console.log(`(showing the first ${page.rows.length} rows — more exist)`);
   if (!page.editable) {
@@ -187,13 +195,25 @@ async function dbDelete(argv: string[], json: boolean): Promise<void> {
 
 async function dbCreateTable(argv: string[], json: boolean): Promise<void> {
   const pkOpt = takeOption(argv, "primary-key");
-  const [slug, table, columnsJson] = pkOpt.rest;
+  const indexesOpt = takeOption(pkOpt.rest, "indexes");
+  const [slug, table, columnsJson] = indexesOpt.rest;
   if (!table || !pkOpt.value) die(USAGE);
   const projectId = await resolveProjectId(slug);
   const columns = parseJsonArg<unknown[]>(columnsJson, "<columns-json>");
+  const indexes = indexesOpt.value
+    ? parseJsonArg<unknown[]>(indexesOpt.value, "<indexes-json>")
+    : undefined;
   const result = await apiFetch<{ table: string; created: boolean }>(
     `/api/v1/projects/${projectId}/database/tables`,
-    { method: "POST", body: { name: table, columns, primary_key: pkOpt.value } },
+    {
+      method: "POST",
+      body: {
+        name: table,
+        columns,
+        primary_key: pkOpt.value,
+        ...(indexes ? { indexes } : {}),
+      },
+    },
   );
   if (json) {
     printJson(result);
@@ -202,6 +222,36 @@ async function dbCreateTable(argv: string[], json: boolean): Promise<void> {
   console.log(`Created table "${result.table}".`);
 }
 
+async function dbCreateIndex(argv: string[], json: boolean): Promise<void> {
+  const nameOpt = takeOption(argv, "name");
+  const uniqueFlag = hasFlag(nameOpt.rest, "unique");
+  const [slug, table, columnsJson] = uniqueFlag.rest;
+  if (!table || !columnsJson) die(USAGE);
+  const projectId = await resolveProjectId(slug);
+  const parsedColumns = parseJsonArg<unknown>(columnsJson, "<columns-json>");
+  const columns = Array.isArray(parsedColumns)
+    ? parsedColumns
+    : typeof parsedColumns === "string"
+      ? [parsedColumns]
+      : die("<columns-json> must be a JSON array of column names or a string.");
+  const result = await apiFetch<{ table: string; index: string; created: boolean }>(
+    `/api/v1/projects/${projectId}/database/tables/${encodeURIComponent(table)}/indexes`,
+    {
+      method: "POST",
+      body: {
+        columns,
+        name: nameOpt.value,
+        unique: uniqueFlag.present ? true : undefined,
+      },
+    },
+  );
+  if (json) {
+    printJson(result);
+    return;
+  }
+  console.log(`Created index "${result.index}" on "${result.table}".`);
+}
+
 async function dbMigrate(argv: string[], json: boolean): Promise<void> {
   const defaultOpt = takeOption(argv, "default");
   const [slug, table, columnJson] = defaultOpt.rest;
@@ -235,9 +285,12 @@ export async function dbCommand(argv: string[], json: boolean): Promise<void> {
       return dbDelete(rest, json);
     case "create-table":
       return dbCreateTable(rest, json);
+    case "create-index":
+      return dbCreateIndex(rest, json);
     case "migrate":
       return dbMigrate(rest, json);
     default:
       die(USAGE);
   }
 }
+

package/src/commands/mcp-check.ts

@@ -0,0 +1,110 @@
+/**
+ * `svcloud mcp check` — one-command diagnosis for "the harness doesn't see
+ * my tools." Exists because the actual field failure (2026-08-26 report)
+ * was a config that *looked* installed — a file existed at a path that
+ * seemed right — but was the wrong shape for the harness reading it, and
+ * finding that took digging. This prints sign-in state, a live `tools/list`
+ * probe (same request the bridge itself makes — `callRemote` from
+ * `mcp.ts`), and every known harness's config file: found or not, and if
+ * found, right shape or wrong.
+ */
+import { callRemote } from "./mcp";
+import { CLI_VERSION, apiBaseUrl } from "../lib/config";
+import { loadTokens } from "../lib/credentials";
+import { HARNESSES, inspectHarness, type HarnessStatus } from "../lib/harnesses";
+import { printJson } from "../lib/output";
+
+// The scope vocabulary svcloud-cli/svcloud-mcp currently grant by default
+// (apps/cloud/src/services/oauth.ts's OAUTH_CLIENTS, widened 2026-08-25 to
+// every OAUTH_SCOPES entry except database:sql). A session with fewer
+// scopes than this predates that widening — scopes are frozen at sign-in
+// and only refreshed by signing in again, never silently upgraded.
+const EXPECTED_SCOPE_COUNT = 6;
+
+function describeStatus(status: HarnessStatus): string {
+  switch (status.state) {
+    case "not_found":
+      return "not found";
+    case "unreadable":
+      return `exists but isn't valid JSON (${status.detail})`;
+    case "missing_entry":
+      return "found, but has no svcloud entry";
+    case "wrong_shape":
+      return "found, but the svcloud entry is the wrong shape for this harness";
+    case "ok":
+      return "configured correctly";
+  }
+}
+
+export async function mcpCheckCommand(json: boolean): Promise<void> {
+  const tokens = await loadTokens();
+  const cwd = process.cwd();
+
+  const harnessResults = await Promise.all(
+    HARNESSES.map(async (h) => ({ harness: h, status: await inspectHarness(h, cwd) })),
+  );
+
+  let toolCount: number | undefined;
+  let toolsListError: string | undefined;
+  if (tokens) {
+    const result = await callRemote({
+      jsonrpc: "2.0",
+      id: "__svcloud_mcp_check__",
+      method: "tools/list",
+      params: {},
+    });
+    if (result.ok) {
+      const body = result.body as { result?: { tools?: unknown[] } };
+      toolCount = body.result?.tools?.length;
+    } else {
+      toolsListError = result.reason === "auth" ? "not signed in" : result.detail;
+    }
+  }
+
+  const scopeStale = tokens !== undefined && tokens.scopes.length < EXPECTED_SCOPE_COUNT;
+
+  if (json) {
+    printJson({
+      version: CLI_VERSION,
+      api_base_url: apiBaseUrl(),
+      signed_in: tokens !== undefined,
+      scopes: tokens?.scopes ?? [],
+      scopes_possibly_stale: scopeStale,
+      tools_visible: toolCount,
+      tools_list_error: toolsListError,
+      harnesses: harnessResults.map(({ harness, status }) => ({
+        id: harness.id,
+        path: status.path,
+        state: status.state,
+      })),
+    });
+    return;
+  }
+
+  console.log(`svcloud ${CLI_VERSION} (API: ${apiBaseUrl()})`);
+  console.log("");
+  if (!tokens) {
+    console.log("Sign-in: not signed in. Run `svcloud login`.");
+  } else {
+    console.log(`Sign-in: signed in, ${tokens.scopes.length} scopes (${tokens.scopes.join(", ")}).`);
+    if (scopeStale) {
+      console.log(
+        "  Fewer scopes than SV Cloud currently grants by default — if a tool you expect is missing, " +
+          "run `svcloud login` again. Scopes are frozen at sign-in and don't update on their own.",
+      );
+    }
+    if (toolCount !== undefined) {
+      console.log(`Live tools/list: ${toolCount} tools visible to this token.`);
+    } else if (toolsListError) {
+      console.log(`Live tools/list: failed (${toolsListError}).`);
+    }
+  }
+  console.log("");
+  console.log("Harness configs:");
+  for (const { harness, status } of harnessResults) {
+    console.log(`  ${harness.label.padEnd(14)} ${status.path}`);
+    console.log(`  ${"".padEnd(14)} ${describeStatus(status)}`);
+  }
+  console.log("");
+  console.log("Fix a missing or wrong-shaped one with: svcloud mcp setup <harness>");
+}

package/src/commands/mcp-setup.ts

@@ -0,0 +1,86 @@
+/**
+ * `svcloud mcp setup <harness>` — writes or merges the correct MCP config
+ * block for one harness, from the single table in `lib/harnesses.ts`. Exists
+ * because README.md's prose config blocks are what actually broke: an
+ * OpenCode reader followed a Claude-style `mcpServers` block written to the
+ * wrong file, ended up with a config that looked installed but was inert,
+ * and only found the mismatch by digging (2026-08-26 field report). Writing
+ * the file directly, from data instead of prose, is the fix.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { findHarness, HARNESSES, type Harness } from "../lib/harnesses";
+import { die, hasFlag } from "../lib/output";
+
+function usage(): string {
+  const ids = HARNESSES.map((h) => h.id).join(" | ");
+  return `Usage: svcloud mcp setup <harness> [--force]\n\nHarnesses: ${ids}`;
+}
+
+async function readExistingConfig(path: string, force: boolean): Promise<Record<string, unknown>> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return {};
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("not a JSON object");
+    }
+    return parsed as Record<string, unknown>;
+  } catch (err) {
+    if (!force) {
+      die(
+        `${path} exists but isn't valid JSON (${err instanceof Error ? err.message : String(err)}).\n` +
+          `Fix it by hand, or rerun with --force to overwrite it.`,
+      );
+    }
+    return {};
+  }
+}
+
+export async function mcpSetupCommand(argv: string[], json: boolean): Promise<void> {
+  const { present: force, rest } = hasFlag(argv, "force");
+  const id = rest[0];
+  if (!id) die(usage());
+  const harness: Harness | undefined = findHarness(id);
+  if (!harness) die(`Unknown harness "${id}".\n\n${usage()}`);
+
+  const path = harness.configPath(process.cwd());
+  const config = await readExistingConfig(path, force);
+
+  const servers = (config[harness.serversKey] ?? {}) as Record<string, unknown>;
+  const existing = servers.svcloud;
+  const entry = harness.buildEntry("svcloud", ["mcp"]);
+
+  if (existing !== undefined && !force) {
+    if (harness.isWellFormed(existing)) {
+      if (json) {
+        console.log(JSON.stringify({ harness: harness.id, path, status: "already_configured" }));
+      } else {
+        console.log(`${harness.label} is already configured at ${path}.`);
+      }
+      return;
+    }
+    die(
+      `${path} already has a "svcloud" entry under "${harness.serversKey}", but it doesn't look right for ${harness.label}.\n` +
+        `Rerun with --force to overwrite it.`,
+    );
+  }
+
+  servers.svcloud = entry;
+  config[harness.serversKey] = servers;
+
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+
+  if (json) {
+    console.log(JSON.stringify({ harness: harness.id, path, status: "written" }));
+    return;
+  }
+  console.log(`Wrote ${harness.label}'s MCP config to ${path}.`);
+  console.log(`Sign in first if you haven't: svcloud login`);
+  console.log(`Then restart ${harness.label} (or start a new session) to pick it up.`);
+}

package/src/commands/mcp.ts

@@ -41,6 +41,9 @@ import { createInterface } from "node:readline";
 import { AuthRequiredError, currentAccessToken, forceRefreshAccessToken } from "../lib/api";
 import { apiBaseUrl } from "../lib/config";
 import { loadTokens } from "../lib/credentials";
+import { die } from "../lib/output";
+import { mcpCheckCommand } from "./mcp-check";
+import { mcpSetupCommand } from "./mcp-setup";
 
 type JsonRpcId = string | number | null;
 
@@ -79,13 +82,18 @@ function warnNotSignedInOnce(): void {
   stderrLine(NOT_SIGNED_IN_MESSAGE);
 }
 
-type RemoteResult =
+export type RemoteResult =
   | { ok: true; body: unknown }
   | { ok: false; reason: "auth" }
   | { ok: false; reason: "transport"; detail: string };
 
-/** One request to `POST /mcp`, refreshing once on a 401, whatever the eventual status. Never throws. */
-async function callRemote(msg: unknown): Promise<RemoteResult> {
+/**
+ * One request to `POST /mcp`, refreshing once on a 401, whatever the
+ * eventual status. Never throws. Exported for `mcp-check.ts`'s live
+ * `tools/list` probe — same request the bridge itself makes, not a second
+ * implementation.
+ */
+export async function callRemote(msg: unknown): Promise<RemoteResult> {
   let accessToken: string;
   try {
     accessToken = await currentAccessToken();
@@ -156,16 +164,18 @@ async function logStartupState(): Promise<void> {
   }
 }
 
-export async function mcpCommand(): Promise<void> {
+/** The stdio bridge itself — everything rules 1-8 above govern. Only reachable as bare `svcloud mcp`. */
+export async function mcpBridgeCommand(): Promise<void> {
   // Rule 1: stdout is JSON-RPC only. Nothing in this command's own code
   // calls console.log, but rebinding here means an imported module doing
   // so can't corrupt the stream either.
   console.log = (...args: unknown[]) => stderrLine(args.map(String).join(" "));
   console.info = console.log;
 
-  await logStartupState();
-
+  // Attach to stdin synchronously before any async work so the harness's
+  // initialize handshake is never delayed or dropped on session start.
   const rl = createInterface({ input: process.stdin, terminal: false });
+  void logStartupState();
   rl.on("line", (line) => {
     const trimmed = line.trim();
     if (!trimmed) return;
@@ -183,3 +193,35 @@ export async function mcpCommand(): Promise<void> {
 
   await new Promise<void>((resolve) => rl.on("close", resolve));
 }
+
+const USAGE = `Usage:
+  svcloud mcp                    Run the local MCP bridge (for a coding agent's harness config)
+  svcloud mcp setup <harness>    Write this harness's MCP config for svcloud
+  svcloud mcp check              Diagnose sign-in state, harness configs, and live tool visibility`;
+
+/**
+ * `svcloud mcp [setup|check]` — bare `mcp` must stay the stdio bridge since
+ * every documented harness config invokes it exactly that way
+ * (`claude mcp add svcloud -- svcloud mcp`, etc.), so it's the default when
+ * `argv` has no subcommand — not a subcommand of its own.
+ */
+export async function mcpCommand(argv: string[], json: boolean): Promise<void> {
+  const [subcommand, ...rest] = argv;
+  switch (subcommand) {
+    case undefined:
+      await mcpBridgeCommand();
+      return;
+    case "setup":
+      await mcpSetupCommand(rest, json);
+      return;
+    case "check":
+      await mcpCheckCommand(json);
+      return;
+    case "-h":
+    case "--help":
+      console.log(USAGE);
+      return;
+    default:
+      die(`Unknown "svcloud mcp" subcommand: ${subcommand}\n\n${USAGE}`);
+  }
+}

package/src/index.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 /**
- * Argument parsing and command dispatch — PLANNING.md §4 Step 1:
- * `login`, `logout`, `whoami`, `status`, `open`, `projects list`.
- * Hand-rolled rather than a dependency: six commands, one global flag, no
- * subcommand ambiguity worth a parser library yet.
+ * Argument parsing and command dispatch. Hand-rolled rather than a
+ * dependency: a handful of top-level commands, one global flag, and the
+ * few that need subcommands (`secrets`, `db`, `mcp`) do their own
+ * second-level switch — no subcommand ambiguity worth a parser library yet.
  */
 import { dbCommand } from "./commands/db";
 import { deployCommand } from "./commands/deploy";
@@ -35,6 +35,8 @@ Usage:
   svcloud db <cmd>              Browse and edit an app's database (see 'svcloud db' for subcommands)
   svcloud deploy <app>          Push the current branch and watch the build (must be the app's default branch)
   svcloud mcp                   Run the local MCP bridge (for a coding agent's harness config)
+  svcloud mcp setup <harness>   Write a coding agent harness's MCP config for svcloud
+  svcloud mcp check             Diagnose sign-in state, harness configs, and live tool visibility
 
 Flags:
   --json                        Machine-readable output, on every read command
@@ -66,7 +68,7 @@ async function main(): Promise<void> {
       await projectsCommand(rest[0], json);
       return;
     case "mcp":
-      await mcpCommand();
+      await mcpCommand(rest, json);
       return;
     case "init":
       await initCommand(rest, json);

package/src/lib/config.ts

@@ -3,6 +3,7 @@
  * override, for pointing the CLI at a local `wrangler dev` instance while
  * building it — production has no reason to ever set it.
  */
+import { createRequire } from "node:module";
 
 export const CLIENT_ID = "svcloud-cli";
 
@@ -13,3 +14,6 @@ export function apiBaseUrl(): string {
 /** Service/account names the credential store (lib/credentials.ts) files this CLI's token set under. */
 export const CREDENTIAL_SERVICE = "svcloud-cli";
 export const CREDENTIAL_ACCOUNT = "default";
+
+/** This installed CLI's own version, from package.json — surfaced by `svcloud mcp check`. */
+export const CLI_VERSION: string = createRequire(import.meta.url)("../../package.json").version;

package/src/lib/harnesses.ts

@@ -0,0 +1,148 @@
+/**
+ * The harness table `svcloud mcp setup <harness>` and `svcloud mcp check`
+ * both read — previously this was six prose blocks in README.md, hand-kept
+ * in sync with nothing. That's how the OpenCode block drifted wrong
+ * (2026-08-26 field report): it told a reader to write a Claude-style
+ * `mcpServers` object to `~/.config/opencode/mcp.json`, which OpenCode
+ * never reads — OpenCode's actual config is `~/.config/opencode/opencode.json`
+ * with a `mcp` key whose entries are `{ type: "local", command: [...] }`,
+ * verified against https://opencode.ai/docs/mcp-servers/ and
+ * https://opencode.ai/docs/config/ while fixing this. One table now backs
+ * the README, `mcp setup`, and `mcp check`, so they cannot drift apart
+ * again the same way.
+ *
+ * Codex's entry is carried over from the README as it stood before this
+ * change (`~/.codex/config.json`, `mcpServers`) — not independently
+ * re-verified here; only OpenCode's shape was reported wrong.
+ */
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type HarnessId = "claude-code" | "cursor" | "opencode" | "antigravity" | "gemini-cli" | "codex";
+
+export interface HarnessEntry {
+  command: string | string[];
+  args?: string[];
+  type?: string;
+}
+
+export interface Harness {
+  id: HarnessId;
+  label: string;
+  /** Where the config file lives. "project" is relative to the current working directory. */
+  scope: "project" | "global";
+  configPath: (cwd: string) => string;
+  /** The top-level object key an entry for svcloud lives under. */
+  serversKey: string;
+  /** Build this harness's shape of the svcloud server entry. */
+  buildEntry: (command: string, args: string[]) => HarnessEntry;
+  /** True if an existing entry (already parsed as JSON) has this harness's expected shape. */
+  isWellFormed: (entry: unknown) => boolean;
+}
+
+function isStringArray(v: unknown): v is string[] {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+
+const claudeStyleEntry = (command: string, args: string[]): HarnessEntry => ({ command, args });
+const claudeStyleWellFormed = (entry: unknown): boolean =>
+  typeof entry === "object" &&
+  entry !== null &&
+  typeof (entry as Record<string, unknown>).command === "string" &&
+  isStringArray((entry as Record<string, unknown>).args ?? []);
+
+export const HARNESSES: Harness[] = [
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    scope: "project",
+    configPath: (cwd) => join(cwd, ".mcp.json"),
+    serversKey: "mcpServers",
+    buildEntry: claudeStyleEntry,
+    isWellFormed: claudeStyleWellFormed,
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    scope: "project",
+    configPath: (cwd) => join(cwd, ".cursor", "mcp.json"),
+    serversKey: "mcpServers",
+    buildEntry: claudeStyleEntry,
+    isWellFormed: claudeStyleWellFormed,
+  },
+  {
+    id: "antigravity",
+    label: "Antigravity",
+    scope: "global",
+    configPath: () => join(homedir(), ".gemini", "config", "mcp_config.json"),
+    serversKey: "mcpServers",
+    buildEntry: claudeStyleEntry,
+    isWellFormed: claudeStyleWellFormed,
+  },
+  {
+    id: "gemini-cli",
+    label: "Gemini CLI",
+    scope: "global",
+    configPath: () => join(homedir(), ".gemini", "mcp_config.json"),
+    serversKey: "mcpServers",
+    buildEntry: claudeStyleEntry,
+    isWellFormed: claudeStyleWellFormed,
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    scope: "global",
+    configPath: () => join(homedir(), ".codex", "config.json"),
+    serversKey: "mcpServers",
+    buildEntry: claudeStyleEntry,
+    isWellFormed: claudeStyleWellFormed,
+  },
+  {
+    id: "opencode",
+    label: "OpenCode",
+    scope: "global",
+    configPath: () => join(homedir(), ".config", "opencode", "opencode.json"),
+    serversKey: "mcp",
+    buildEntry: (command, args) => ({ type: "local", command: [command, ...args] }),
+    isWellFormed: (entry: unknown): boolean =>
+      typeof entry === "object" &&
+      entry !== null &&
+      (entry as Record<string, unknown>).type === "local" &&
+      isStringArray((entry as Record<string, unknown>).command) &&
+      ((entry as Record<string, unknown>).command as string[]).length > 0,
+  },
+];
+
+export function findHarness(id: string): Harness | undefined {
+  return HARNESSES.find((h) => h.id === id);
+}
+
+export type HarnessStatus =
+  | { state: "not_found"; path: string }
+  | { state: "unreadable"; path: string; detail: string }
+  | { state: "missing_entry"; path: string }
+  | { state: "wrong_shape"; path: string }
+  | { state: "ok"; path: string };
+
+/** Reads and inspects a harness's config file — never throws. */
+export async function inspectHarness(harness: Harness, cwd: string): Promise<HarnessStatus> {
+  const path = harness.configPath(cwd);
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return { state: "not_found", path };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { state: "unreadable", path, detail: err instanceof Error ? err.message : String(err) };
+  }
+  const servers = (parsed as Record<string, unknown> | null)?.[harness.serversKey];
+  const entry = (servers as Record<string, unknown> | undefined)?.svcloud;
+  if (entry === undefined) return { state: "missing_entry", path };
+  if (!harness.isWellFormed(entry)) return { state: "wrong_shape", path };
+  return { state: "ok", path };
+}