@cursor/bdk 0.2.2 → 0.2.4

package/src/internal/cli-mcp.ts

@@ -1,808 +0,0 @@
-/**
- * `agent-sdk mcp` — stdio ↔ streamable-HTTP proxy for an agent's MCP endpoint.
- *
- * Every served agent is an MCP server at `<base>/v1/mcp` (hosted deployments
- * run in single mode, so the endpoint sits directly on the engine base URL).
- * MCP clients that spawn stdio servers (Cursor, Claude Code, …) can reach it
- * through this command: newline-delimited JSON-RPC on stdin/stdout, one POST
- * per message to the remote endpoint.
- *
- * Targets:
- * - `--prod [--slug <slug>]` — the team's hosted deployment. Short-lived
- *   `engineAccess` credentials are minted through the management API with the
- *   signed-in Cursor account, re-minted near expiry and once on auth-shaped
- *   failures. No durable secret ever lands in a config file.
- * - `--url <baseUrl>` — a running server (local `serve` mount or self-hosted
- *   base URL), with optional `--bearer-token`.
- *
- * `agent-sdk mcp install` writes the matching entry into `~/.cursor/mcp.json`
- * so the agent shows up as an MCP server in Cursor:
- *
- *   { "mcpServers": { "weather-agent": {
- *       "command": "agent-sdk",
- *       "args": ["mcp", "--prod", "--slug", "weather-agent"] } } }
- *
- * stdout is reserved for the MCP wire in serve mode; all logging goes to
- * stderr.
- */
-
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { resolveDeployAuth } from "./cli-deploy.js";
-import { DeployApiError } from "./deploy-client.js";
-import { CLI_COMMAND_NAME as CLI, LOG_PREFIX } from "./distribution.js";
-import { rejectV2ForLegacyCommand } from "./legacy-command-guard.js";
-import { ProdTargetError, resolveProdSlug, resolveProdTarget } from "./resolve-prod-target.js";
-import { sleep as defaultSleep } from "./sleep.js";
-
-/** Mount path of the MCP surface relative to an agent base URL. */
-const MCP_PATH = "/v1/mcp";
-
-/** Re-mint engineAccess when within this window of `expiresAt`. */
-const ACCESS_EXPIRY_LEEWAY_MS = 5 * 60 * 1000;
-
-/**
- * Upper bound per POST. The remote endpoint bounds `ask`/`check` waits at
- * ~55s, so a healthy turn always responds well inside this; past it the
- * engine is unreachable or hung.
- */
-const REQUEST_TIMEOUT_MS = 120_000;
-
-/** Attempts per message (initial + retries after refresh/backoff). */
-const FORWARD_ATTEMPTS = 3;
-
-/**
- * Statuses that cannot have reached the agent's tool logic, so retrying
- * cannot double-run a turn: auth/routing rejections (401/403/404), a
- * hibernated engine (417), and proxy-unreachable errors (502/503/504).
- * A plain 500 is ambiguous and is surfaced to the client instead.
- */
-const RETRYABLE_STATUSES = new Set([401, 403, 404, 417, 502, 503, 504]);
-
-export interface McpCliOptions {
-  dir: string;
-  cwd?: string;
-  /** Hosted deployment slug (with `--prod`); defaults to the `--dir` basename. */
-  slug?: string;
-  team?: string;
-  apiKey?: string;
-  /** Base URL of a running agent (mutually exclusive with `--prod`). */
-  url?: string;
-  prod?: boolean;
-  bearerToken?: string;
-  /** `install`: server name for the mcp.json entry (defaults to the slug). */
-  name?: string;
-  /** `install`: print the entry instead of writing ~/.cursor/mcp.json. */
-  print?: boolean;
-  /** `install`: machine-readable output. */
-  json?: boolean;
-  /**
-   * `install --prod`: write a REMOTE HTTP entry pointing at the stable Cursor
-   * MCP gateway (`<api>/…/mcp/<team>/<slug>`) instead of the local stdio
-   * proxy. For remote-only MCP hosts (Glass) that cannot spawn stdio.
-   */
-  remote?: boolean;
-  /** Injected seams for tests. */
-  fetchImpl?: typeof fetch;
-  resolveProdTargetImpl?: typeof resolveProdTarget;
-  resolveDeployAuthImpl?: typeof resolveDeployAuth;
-  stdin?: NodeJS.ReadableStream;
-  stdout?: { write(chunk: string): unknown };
-  err?: (text: string) => void;
-  now?: () => number;
-  sleep?: (ms: number) => Promise<void>;
-}
-
-export async function cmdMcp(
-  subcommand: string | undefined,
-  options: McpCliOptions & {
-    oauthConnection?: string;
-    store?: boolean;
-  },
-): Promise<number> {
-  const err = options.err ?? defaultErr;
-  if (subcommand === undefined) {
-    return cmdMcpServe(options);
-  }
-  if (subcommand === "install") {
-    return cmdMcpInstall(options);
-  }
-  if (subcommand === "oauth") {
-    const connection = options.oauthConnection;
-    if (connection === undefined || connection.trim() === "") {
-      err(
-        `Usage: ${CLI} mcp oauth <connection> [--dir .] [--store] [--slug <slug>] [--team <id>]\n` +
-          `Authorize defineConnection({ url, oauth: true }) (host PKCE).\n` +
-          `--store upserts MCP_OAUTH_<NAME>_* secrets on the hosted deployment.\n`,
-      );
-      return 1;
-    }
-    const { cmdMcpOauth } = await import("./cli-mcp-oauth.js");
-    return cmdMcpOauth({
-      dir: options.dir,
-      connection,
-      store: options.store,
-      slug: options.slug,
-      team: options.team,
-      apiKey: options.apiKey,
-    });
-  }
-  err(
-    `Unknown mcp subcommand "${subcommand}".\n` +
-      `Usage: ${CLI} mcp [install|oauth <connection>] --prod [--slug <slug>] | --url <baseUrl>\n`,
-  );
-  return 1;
-}
-
-// ============================================================================
-// serve mode: stdio ↔ /v1/mcp
-// ============================================================================
-
-export async function cmdMcpServe(options: McpCliOptions): Promise<number> {
-  const err = options.err ?? defaultErr;
-  const source = buildTargetSource(options, err);
-  if (typeof source === "string") {
-    err(`${source}\n`);
-    return 1;
-  }
-
-  // Resolve eagerly: a bad slug / signed-out host / stopped deployment fails
-  // fast in the client's MCP server logs instead of on the first tool call.
-  let initial: McpTarget;
-  try {
-    initial = await source.get();
-  } catch (error) {
-    err(`${describeError(error)}\n`);
-    return 1;
-  }
-  err(`${LOG_PREFIX} mcp: proxying stdio <-> ${initial.mcpUrl}\n`);
-
-  const stdin = options.stdin ?? process.stdin;
-  const stdout = options.stdout ?? process.stdout;
-  const fetchImpl = options.fetchImpl ?? fetch;
-  const sleep = options.sleep ?? defaultSleep;
-  const pending = new Set<Promise<void>>();
-
-  const handleLine = async (line: string): Promise<void> => {
-    const outcome = await forwardMessage({ source, fetchImpl, sleep, line });
-    if (outcome.kind === "empty") {
-      return;
-    }
-    if (outcome.kind === "json") {
-      writeWireBody(stdout, outcome.body, line, err);
-      return;
-    }
-    emitFailure(stdout, line, outcome.message, err);
-  };
-
-  await new Promise<void>(done => {
-    let buffer = "";
-    const enqueueLine = (raw: string): void => {
-      const line = raw.trim();
-      if (line === "") {
-        return;
-      }
-      const task = handleLine(line)
-        .catch((error: unknown) => {
-          err(`${LOG_PREFIX} mcp: ${describeError(error)}\n`);
-        })
-        .finally(() => {
-          pending.delete(task);
-        });
-      pending.add(task);
-    };
-    const onChunk = (chunk: string | Buffer): void => {
-      buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
-      let newline = buffer.indexOf("\n");
-      while (newline !== -1) {
-        const line = buffer.slice(0, newline);
-        buffer = buffer.slice(newline + 1);
-        newline = buffer.indexOf("\n");
-        enqueueLine(line);
-      }
-    };
-    let finished = false;
-    const finish = (): void => {
-      if (finished) {
-        return;
-      }
-      finished = true;
-      enqueueLine(buffer);
-      buffer = "";
-      done();
-    };
-    stdin.on("data", onChunk);
-    stdin.once("end", finish);
-    stdin.once("close", finish);
-    stdin.once("error", finish);
-  });
-
-  // Drain in-flight turns so piped one-shot usage still sees its replies.
-  await Promise.allSettled([...pending]);
-  return 0;
-}
-
-interface McpTarget {
-  mcpUrl: string;
-  headers: Record<string, string>;
-  expiresAtMs?: number;
-}
-
-interface TargetSource {
-  /** Cached target, re-resolved near expiry (single-flighted). */
-  get(): Promise<McpTarget>;
-  /** Drop the cache so the next get() re-resolves. */
-  invalidate(): void;
-  /** True when invalidate() can actually mint fresh credentials. */
-  canRefresh: boolean;
-}
-
-/** Returns a usage error string when the target flags are invalid. */
-function buildTargetSource(
-  options: McpCliOptions,
-  err: (text: string) => void,
-): TargetSource | string {
-  if (options.prod === true && options.url !== undefined) {
-    return "--prod and --url are mutually exclusive";
-  }
-  if (options.url !== undefined) {
-    const base = normalizeBaseUrl(options.url);
-    if (typeof base !== "string") {
-      return base.error;
-    }
-    return createStaticTargetSource(base, options.bearerToken);
-  }
-  if (options.prod === true) {
-    return createProdTargetSource(options, err);
-  }
-  return `${CLI} mcp requires --prod (hosted deployment) or --url <baseUrl>`;
-}
-
-function createStaticTargetSource(baseUrl: string, bearerToken: string | undefined): TargetSource {
-  const headers: Record<string, string> = {};
-  if (bearerToken !== undefined && bearerToken.trim() !== "") {
-    headers.authorization = `Bearer ${bearerToken.trim()}`;
-  }
-  const target: McpTarget = { mcpUrl: joinMcpPath(baseUrl), headers };
-  return {
-    canRefresh: false,
-    get: () => Promise.resolve(target),
-    invalidate: () => {},
-  };
-}
-
-function createProdTargetSource(options: McpCliOptions, err: (text: string) => void): TargetSource {
-  const resolveImpl = options.resolveProdTargetImpl ?? resolveProdTarget;
-  const now = options.now ?? Date.now;
-  let cached: McpTarget | undefined;
-  let inFlight: Promise<McpTarget> | undefined;
-
-  const resolveFresh = async (): Promise<McpTarget> => {
-    const prod = await resolveImpl({
-      dir: options.dir,
-      cwd: options.cwd,
-      slug: options.slug,
-      team: options.team,
-      apiKey: options.apiKey,
-      fetchImpl: options.fetchImpl,
-      err,
-    });
-    const target: McpTarget = {
-      mcpUrl: joinMcpPath(prod.agentUrl),
-      headers: prod.headers,
-    };
-    const expiresAtMs = Date.parse(prod.expiresAt);
-    if (Number.isFinite(expiresAtMs)) {
-      target.expiresAtMs = expiresAtMs;
-    }
-    return target;
-  };
-
-  return {
-    canRefresh: true,
-    invalidate() {
-      cached = undefined;
-    },
-    get() {
-      const current = cached;
-      const fresh =
-        current !== undefined &&
-        (current.expiresAtMs === undefined ||
-          now() < current.expiresAtMs - ACCESS_EXPIRY_LEEWAY_MS);
-      if (fresh) {
-        return Promise.resolve(current);
-      }
-      if (inFlight === undefined) {
-        inFlight = resolveFresh()
-          .then(target => {
-            cached = target;
-            return target;
-          })
-          .finally(() => {
-            inFlight = undefined;
-          });
-      }
-      return inFlight;
-    },
-  };
-}
-
-type ForwardOutcome =
-  | { kind: "json"; body: string }
-  | { kind: "empty" }
-  | { kind: "failed"; message: string };
-
-async function forwardMessage(args: {
-  source: TargetSource;
-  fetchImpl: typeof fetch;
-  sleep: (ms: number) => Promise<void>;
-  line: string;
-}): Promise<ForwardOutcome> {
-  const { source, fetchImpl, sleep, line } = args;
-  let lastFailure = "request failed";
-
-  for (let attempt = 0; attempt < FORWARD_ATTEMPTS; attempt++) {
-    if (attempt > 0) {
-      await sleep(500 * attempt);
-    }
-
-    let target: McpTarget;
-    try {
-      target = await source.get();
-    } catch (error) {
-      lastFailure = describeError(error);
-      continue;
-    }
-
-    let response: Response;
-    try {
-      response = await fetchImpl(target.mcpUrl, {
-        method: "POST",
-        headers: {
-          ...target.headers,
-          "content-type": "application/json",
-          // The streamable-HTTP server transport 406s unless the client
-          // accepts both, even in JSON response mode.
-          accept: "application/json, text/event-stream",
-        },
-        body: line,
-        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-      });
-    } catch (error) {
-      source.invalidate();
-      if (isTimeoutError(error)) {
-        // The turn may have started; retrying could double-send it.
-        return {
-          kind: "failed",
-          message: `no response within ${REQUEST_TIMEOUT_MS / 1000}s (the agent may still be processing; check its sessions)`,
-        };
-      }
-      lastFailure = `request failed: ${describeError(error)}`;
-      continue;
-    }
-
-    if (response.status === 202) {
-      // Notification/response-only message: nothing to relay.
-      await response.text().catch(() => "");
-      return { kind: "empty" };
-    }
-    const text = await response.text().catch(() => "");
-    if (response.ok) {
-      if (text.trim() === "") {
-        return { kind: "empty" };
-      }
-      return { kind: "json", body: text };
-    }
-
-    lastFailure = `upstream HTTP ${response.status}${
-      text.trim() === "" ? "" : `: ${truncateForLog(text)}`
-    }`;
-    if (RETRYABLE_STATUSES.has(response.status)) {
-      // Auth/expiry/hibernation shaped: re-mint credentials and retry.
-      source.invalidate();
-      continue;
-    }
-    return { kind: "failed", message: lastFailure };
-  }
-
-  return { kind: "failed", message: lastFailure };
-}
-
-/**
- * Relay an upstream JSON body onto the stdio wire. The body is re-serialized
- * so output is always one message per line, and batch responses are split
- * into individual lines (the stdio transport has no batch framing).
- */
-function writeWireBody(
-  stdout: { write(chunk: string): unknown },
-  body: string,
-  inboundLine: string,
-  err: (text: string) => void,
-): void {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(body);
-  } catch {
-    emitFailure(
-      stdout,
-      inboundLine,
-      `upstream returned a non-JSON payload: ${truncateForLog(body)}`,
-      err,
-    );
-    return;
-  }
-  const messages = Array.isArray(parsed) ? parsed : [parsed];
-  for (const message of messages) {
-    stdout.write(`${JSON.stringify(message)}\n`);
-  }
-}
-
-/**
- * Answer every request id in the inbound message with a JSON-RPC error so
- * the client fails the call instead of hanging on a lost response.
- * Notification-only failures are stderr-logged.
- */
-function emitFailure(
-  stdout: { write(chunk: string): unknown },
-  inboundLine: string,
-  message: string,
-  err: (text: string) => void,
-): void {
-  err(`${LOG_PREFIX} mcp: ${message}\n`);
-  for (const id of requestIdsOf(inboundLine)) {
-    stdout.write(
-      `${JSON.stringify({
-        jsonrpc: "2.0",
-        id,
-        error: { code: -32000, message },
-      })}\n`,
-    );
-  }
-}
-
-/** Ids of JSON-RPC *requests* (has `method` + `id`) in a raw wire line. */
-function requestIdsOf(line: string): Array<string | number> {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(line);
-  } catch {
-    return [];
-  }
-  const messages = Array.isArray(parsed) ? parsed : [parsed];
-  const ids: Array<string | number> = [];
-  for (const message of messages) {
-    if (message !== null && typeof message === "object" && "method" in message && "id" in message) {
-      const id = (message as { id: unknown }).id;
-      if (typeof id === "string" || typeof id === "number") {
-        ids.push(id);
-      }
-    }
-  }
-  return ids;
-}
-
-// ============================================================================
-// install: write the entry into ~/.cursor/mcp.json
-// ============================================================================
-
-type McpJsonEntry =
-  | { command: string; args: string[] }
-  | { url: string; headers?: Record<string, string> };
-
-export async function cmdMcpInstall(options: McpCliOptions): Promise<number> {
-  const err = options.err ?? defaultErr;
-  const stdout = options.stdout ?? process.stdout;
-  if (options.prod === true && options.url !== undefined) {
-    err("--prod and --url are mutually exclusive\n");
-    return 1;
-  }
-  if (options.remote === true) {
-    if (options.prod !== true) {
-      err("--remote requires --prod (the hosted deployment MCP gateway)\n");
-      return 1;
-    }
-    return cmdMcpInstallRemote(options);
-  }
-
-  let name: string;
-  let entry: { command: string; args: string[] };
-  if (options.prod === true) {
-    let slug: string;
-    try {
-      slug = resolveProdSlug({
-        dir: options.dir,
-        cwd: options.cwd,
-        slug: options.slug,
-      });
-    } catch (error) {
-      err(`${describeError(error)}\n`);
-      return 1;
-    }
-    // Verify the deployment resolves before writing config that cannot work.
-    const resolveImpl = options.resolveProdTargetImpl ?? resolveProdTarget;
-    try {
-      await resolveImpl({
-        dir: options.dir,
-        cwd: options.cwd,
-        slug,
-        team: options.team,
-        apiKey: options.apiKey,
-        fetchImpl: options.fetchImpl,
-        err,
-      });
-    } catch (error) {
-      err(`${describeError(error)}\n`);
-      if (error instanceof ProdTargetError && error.notFound) {
-        err(`Deploy it first: ${CLI} deploy --slug ${slug}\n`);
-      }
-      return 1;
-    }
-    name = resolveServerName(options.name, slug);
-    const args = ["mcp", "--prod", "--slug", slug];
-    if (options.team !== undefined && options.team !== "") {
-      args.push("--team", options.team);
-    }
-    entry = { command: CLI, args };
-  } else if (options.url !== undefined) {
-    const base = normalizeBaseUrl(options.url);
-    if (typeof base !== "string") {
-      err(`${base.error}\n`);
-      return 1;
-    }
-    const derived = options.name ?? deriveNameFromUrl(base);
-    if (derived === undefined) {
-      err(`Could not derive a server name from ${base}; pass --name <serverName>.\n`);
-      return 1;
-    }
-    name = resolveServerName(derived, derived);
-    const args = ["mcp", "--url", base];
-    if (options.bearerToken !== undefined && options.bearerToken !== "") {
-      args.push("--bearer-token", options.bearerToken);
-      err(
-        "note: --bearer-token is written to mcp.json in plain text; prefer --prod for hosted agents\n",
-      );
-    }
-    entry = { command: CLI, args };
-  } else {
-    err(`${CLI} mcp install requires --prod (hosted deployment) or --url <baseUrl>\n`);
-    return 1;
-  }
-
-  if (options.print === true) {
-    stdout.write(`${JSON.stringify({ mcpServers: { [name]: entry } }, null, 2)}\n`);
-    return 0;
-  }
-
-  const path = cursorMcpJsonPath();
-  try {
-    await upsertMcpJsonEntry(path, name, entry);
-  } catch (error) {
-    err(`${describeError(error)}\n`);
-    return 1;
-  }
-
-  if (options.json === true) {
-    stdout.write(`${JSON.stringify({ ok: true, path, name, entry })}\n`);
-    return 0;
-  }
-  stdout.write(
-    `Installed MCP server "${name}" in ${path}\n` +
-      `  ${entry.command} ${entry.args.join(" ")}\n` +
-      "Cursor watches this file; the server appears without a restart.\n",
-  );
-  return 0;
-}
-
-/**
- * `mcp install --prod --remote` — write a REMOTE HTTP entry pointing at the
- * stable Cursor MCP gateway for the hosted deployment, for MCP hosts that
- * cannot spawn the stdio proxy (Glass / Sand). The gateway mints/refreshes
- * engineAccess server-side, so the entry never carries a pod hostname or a
- * short-lived port token — only the durable, stable gateway URL.
- *
- * Auth: this headless/CLI entry sends the `agent-sdk login` API key as a
- * bearer against the user-API-key gateway surface. That key is written to
- * `mcp.json` in plain text (flagged below); a signed-in Cursor client
- * (Glass) can instead use the session gateway surface with no header at all
- * once first-party session attachment ships (see PR follow-ups).
- */
-async function cmdMcpInstallRemote(options: McpCliOptions): Promise<number> {
-  const err = options.err ?? defaultErr;
-  const stdout = options.stdout ?? process.stdout;
-
-  let slug: string;
-  try {
-    slug = resolveProdSlug({
-      dir: options.dir,
-      cwd: options.cwd,
-      slug: options.slug,
-    });
-  } catch (error) {
-    err(`${describeError(error)}\n`);
-    return 1;
-  }
-
-  const resolveAuthImpl = options.resolveDeployAuthImpl ?? resolveDeployAuth;
-  const auth = await resolveAuthImpl({
-    team: options.team,
-    apiKey: options.apiKey,
-    fetchImpl: options.fetchImpl,
-    err,
-  });
-  if (typeof auth === "number") {
-    return auth;
-  }
-  try {
-    await rejectV2ForLegacyCommand({
-      client: auth.client,
-      teamId: auth.teamId,
-      slug,
-    });
-  } catch (error) {
-    err(`${describeError(error)}\n`);
-    return 1;
-  }
-
-  // Verify the deployment resolves before writing config that cannot work.
-  // A 403 here is team membership or cloud-agent entitlement, not an
-  // admin-tier read. Still write the entry: calling the gateway only
-  // needs the API key.
-  try {
-    await auth.client.getDeployment({ teamId: auth.teamId, slug });
-  } catch (error) {
-    if (error instanceof DeployApiError && error.status === 403) {
-      err(
-        `Could not verify deployment "${slug}" (not authorized for this team); writing the entry anyway.\n`,
-      );
-    } else {
-      err(`${describeError(error)}\n`);
-      if (error instanceof DeployApiError && error.status === 404) {
-        err(`Deploy it first: ${CLI} deploy --slug ${slug}\n`);
-      }
-      return 1;
-    }
-  }
-
-  const name = resolveServerName(options.name, slug);
-  const url = auth.client.mcpGatewayUrl(auth.teamId, slug);
-  const entry: { url: string; headers?: Record<string, string> } = {
-    url,
-    headers: { Authorization: `Bearer ${auth.apiKey}` },
-  };
-
-  if (options.print === true) {
-    stdout.write(`${JSON.stringify({ mcpServers: { [name]: entry } }, null, 2)}\n`);
-    return 0;
-  }
-
-  const path = cursorMcpJsonPath();
-  try {
-    await upsertMcpJsonEntry(path, name, entry);
-  } catch (error) {
-    err(`${describeError(error)}\n`);
-    return 1;
-  }
-
-  err(
-    "note: the API key is written to mcp.json in plain text; it is a durable " +
-      "credential for a remote MCP host that cannot spawn the stdio proxy.\n",
-  );
-  if (options.json === true) {
-    stdout.write(`${JSON.stringify({ ok: true, path, name, entry })}\n`);
-    return 0;
-  }
-  stdout.write(
-    `Installed remote MCP server "${name}" in ${path}\n` +
-      `  ${url}\n` +
-      "Cursor watches this file; the server appears without a restart.\n",
-  );
-  return 0;
-}
-
-/** `~/.cursor/mcp.json` — the user-level Cursor MCP config. */
-export function cursorMcpJsonPath(home: string = process.env.HOME ?? homedir()): string {
-  const resolved = home.trim() === "" ? homedir() : home;
-  return join(resolved, ".cursor", "mcp.json");
-}
-
-async function upsertMcpJsonEntry(path: string, name: string, entry: McpJsonEntry): Promise<void> {
-  let root: Record<string, unknown> = {};
-  let raw: string | undefined;
-  try {
-    raw = await readFile(path, "utf8");
-  } catch {
-    raw = undefined;
-  }
-  if (raw !== undefined && raw.trim() !== "") {
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(raw);
-    } catch (error) {
-      throw new Error(`${path} is not valid JSON (${describeError(error)}); fix it and re-run.`);
-    }
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-      throw new Error(`${path} must contain a JSON object; fix it and re-run.`);
-    }
-    root = parsed as Record<string, unknown>;
-  }
-
-  const existing = root.mcpServers;
-  const servers: Record<string, unknown> =
-    existing !== null && typeof existing === "object" && !Array.isArray(existing)
-      ? (existing as Record<string, unknown>)
-      : {};
-  servers[name] = entry;
-  root.mcpServers = servers;
-
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, `${JSON.stringify(root, null, 2)}\n`, "utf8");
-}
-
-function resolveServerName(name: string | undefined, fallback: string): string {
-  const trimmed = name?.trim();
-  if (trimmed !== undefined && trimmed !== "") {
-    return trimmed;
-  }
-  return fallback;
-}
-
-/** Last path segment of the agent base URL (the mount slug), if any. */
-function deriveNameFromUrl(baseUrl: string): string | undefined {
-  const segments = new URL(baseUrl).pathname.split("/").filter(s => s !== "");
-  const last = segments.at(-1);
-  if (last === undefined || last === "") {
-    return undefined;
-  }
-  return last;
-}
-
-// ============================================================================
-// Shared helpers
-// ============================================================================
-
-/** Agent base URL → MCP endpoint URL (idempotent when already pointed at it). */
-export function joinMcpPath(baseUrl: string): string {
-  const parsed = new URL(baseUrl);
-  let pathname = parsed.pathname.replace(/\/+$/, "");
-  if (!pathname.endsWith(MCP_PATH)) {
-    pathname = `${pathname}${MCP_PATH}`;
-  }
-  parsed.pathname = pathname;
-  return parsed.toString();
-}
-
-function normalizeBaseUrl(raw: string): string | { error: string } {
-  let parsed: URL;
-  try {
-    parsed = new URL(raw);
-  } catch {
-    return { error: `invalid --url: ${raw}` };
-  }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    return { error: `unsupported --url protocol: ${parsed.protocol}` };
-  }
-  return raw.replace(/\/+$/, "");
-}
-
-function isTimeoutError(error: unknown): boolean {
-  return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
-}
-
-function truncateForLog(text: string): string {
-  const flat = text.replace(/\s+/g, " ").trim();
-  return flat.length > 300 ? `${flat.slice(0, 300)}…` : flat;
-}
-
-function describeError(error: unknown): string {
-  if (error instanceof Error) {
-    const cause =
-      error.cause instanceof Error && error.cause.message !== "" ? ` (${error.cause.message})` : "";
-    return `${error.message}${cause}`;
-  }
-  return String(error);
-}
-
-function defaultErr(text: string): void {
-  process.stderr.write(text);
-}