@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/cursor/account-mcp.ts

@@ -1,692 +0,0 @@
-/**
- * The Cursor account MCP bridge: `defineConnection({ cursorAccount: true })`
- * resolved for local turns.
- *
- * The serve host mounts one loopback-only streamable-HTTP MCP route per
- * authored account MCP connection (`<base>/v1/cursor-account/<name>/mcp`,
- * guarded by a per-boot bearer secret). The bridge lists and executes the
- * account's connector tools through the Cursor backend
- * (`DashboardService.ListSandMcpTools` / `ExecuteSandMcpTool`), which owns
- * the OAuth credentials — **raw MCP tokens never enter this process**.
- *
- * Cloud-runtime turns reach the same bridge through the serve `publicUrl`
- * (so `servers` filters apply there too); without one they omit the bridge
- * and fall back to the account's natively hydrated connectors.
- */
-
-import { randomBytes } from "node:crypto";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { bearerAuth } from "../../channels.js";
-import type { AgentProject, AuthPolicy, McpToolAnnotations } from "../../types.js";
-import { isCursorAccountTransport } from "../../types.js";
-import { probeConnectorAuthUrls } from "../cursor-account-mcp-auth.js";
-import { describeError } from "../describe-error.js";
-import { LOG_PREFIX } from "../distribution.js";
-import { handleStatelessMcpRequest } from "../mcp-endpoint.js";
-import { isLoopbackAddress } from "../net.js";
-import { sanitizeMcpToolName, suffixMcpToolName } from "../sanitize-mcp-tool-name.js";
-import type { EngineResolvedConnection } from "../session-engine.js";
-import {
-  colorEnabledFor,
-  formatTerminalBox,
-  stdoutPalette,
-  type TerminalPalette,
-  terminalHyperlink,
-} from "../terminal-style.js";
-import type {
-  AccountMcpCallResult,
-  AccountMcpServer,
-  CursorBackendClient,
-} from "./backend-client.js";
-
-/** Catalog freshness window; a miss inside it re-uses the cached listing. */
-const CATALOG_TTL_MS = 60_000;
-/**
- * Unknown-tool lookups force a refresh, but never more often than this —
- * a model hallucinating tool names cannot turn into a backend hot loop.
- */
-const FORCE_REFRESH_MIN_INTERVAL_MS = 5_000;
-
-/** Dashboard Integrations & MCP — reconnect team / account connectors. */
-export const CURSOR_ACCOUNT_MCP_DASHBOARD_URL = "https://cursor.com/dashboard/integrations";
-/** Cursor app Settings → MCP (Connect / Authenticate on the named row). */
-export const CURSOR_ACCOUNT_MCP_SETTINGS_DEEPLINK =
-  "cursor://anysphere.cursor-deeplink/customize?tab=mcp";
-
-// ============================================================================
-// Authored account MCP connections (validated refs, mirroring peer MCP connections)
-// ============================================================================
-
-export interface CursorAccountConnectionRef {
-  /** Connection (MCP server) name — the filename under `agent/mcp-connections/`. */
-  name: string;
-  /** Connector-name filter, or undefined for every connected server. */
-  servers?: string[];
-}
-
-/**
- * Collect `cursorAccount` connections across `mounts`, grouped by mount
- * slug. Purely structural — per-connector validation happens live against
- * the account (see {@link CursorAccountMcpBridge.logPreflight}).
- */
-export function collectCursorAccountConnections(
-  mounts: Array<{ slug: string; project: AgentProject }>,
-): Map<string, CursorAccountConnectionRef[]> {
-  const bySlug = new Map<string, CursorAccountConnectionRef[]>();
-  for (const { slug, project } of mounts) {
-    const refs: CursorAccountConnectionRef[] = [];
-    for (const connection of [
-      ...project.agent.connections,
-      ...(project.agent.hostConnections ?? []),
-    ]) {
-      if (!isCursorAccountTransport(connection.transport)) {
-        continue;
-      }
-      refs.push({
-        name: connection.name,
-        ...(connection.transport.servers === undefined
-          ? {}
-          : { servers: [...connection.transport.servers] }),
-      });
-    }
-    if (refs.length > 0) {
-      bySlug.set(slug, refs);
-    }
-  }
-  return bySlug;
-}
-
-/** Bridge mount path for one account MCP connection, relative to the agent base. */
-export function cursorAccountMcpPath(connectionName: string): string {
-  return `/v1/cursor-account/${connectionName}/mcp`;
-}
-
-/**
- * Resolve account refs to engine connections once the server is listening.
- * Local turns and host-side `ctx.host.mcp` reach the loopback bridge with
- * the per-boot secret. When `publicUrl` is configured, cloud turns use the
- * same bridge route so `servers` filters apply there too.
- */
-export function resolveCursorAccountConnections(args: {
-  refs: CursorAccountConnectionRef[];
-  /** Serve bind URL (`http://<host>:<port>`). */
-  serverUrl: string;
-  basePath: string;
-  bridgeSecret: string;
-  publicUrl?: string;
-}): EngineResolvedConnection[] {
-  const serverBase = trimTrailingSlash(args.serverUrl);
-  const publicBase = args.publicUrl === undefined ? undefined : trimTrailingSlash(args.publicUrl);
-  const headers = { authorization: `Bearer ${args.bridgeSecret}` };
-  return args.refs.map(ref => ({
-    name: ref.name,
-    localUrl: `${serverBase}${args.basePath}${cursorAccountMcpPath(ref.name)}`,
-    ...(publicBase === undefined
-      ? {}
-      : {
-          cloudUrl: `${publicBase}${args.basePath}${cursorAccountMcpPath(ref.name)}`,
-        }),
-    headers,
-    ...(ref.servers === undefined ? {} : { accountServersFilter: ref.servers }),
-  }));
-}
-
-// ============================================================================
-// Bridge
-// ============================================================================
-
-interface CatalogTool {
-  /** Name exposed to MCP clients (sanitized, collision-free). */
-  exposedName: string;
-  /** Fully-qualified backend tool name (`<server>-<tool>`), the execution key. */
-  backendName: string;
-  serverIdentifier: string;
-  description: string;
-  inputSchema: Record<string, unknown>;
-  /** Present only when the connector's server declares one. */
-  outputSchema?: Record<string, unknown>;
-  /** MCP spec annotations, present only when the server declared them. */
-  annotations?: McpToolAnnotations;
-}
-
-interface Catalog {
-  servers: AccountMcpServer[];
-  tools: CatalogTool[];
-  byExposedName: Map<string, CatalogTool>;
-}
-
-/**
- * One in-flight-or-settled catalog fetch. In-flight entries omit
- * {@link CatalogEntry.freshAtMs}; readers join {@link CatalogEntry.promise}
- * synchronously so concurrent stale lookups converge on one refresh.
- */
-interface CatalogEntry {
-  /** When the list call finished successfully; TTL counts from here. */
-  freshAtMs?: number;
-  promise: Promise<Catalog>;
-}
-
-export class CursorAccountMcpBridge {
-  /** Per-boot shared secret; resolved connections carry it as a bearer. */
-  readonly secret: string = randomBytes(32).toString("hex");
-  private readonly client: CursorBackendClient;
-  private readonly logger: (line: string) => void;
-  private readonly palette: TerminalPalette;
-  private readonly secretPolicy: AuthPolicy;
-  private readonly allowRemoteCallers: boolean;
-  private readonly catalogs = new Map<string, CatalogEntry>();
-
-  constructor(args: {
-    client: CursorBackendClient;
-    logger?: (line: string) => void;
-    /** Defaults to stdout; tests pass `makePalette(false)` for a plain box. */
-    palette?: TerminalPalette;
-    /**
-     * Admit non-loopback callers presenting the secret. Only set when the
-     * serve host configured a `publicUrl` (cloud turns reach the bridge
-     * through it); otherwise the bridge stays strictly loopback-only.
-     */
-    allowRemoteCallers?: boolean;
-  }) {
-    this.client = args.client;
-    this.logger = args.logger ?? (() => {});
-    this.palette = args.palette ?? stdoutPalette();
-    this.secretPolicy = bearerAuth(this.secret);
-    this.allowRemoteCallers = args.allowRemoteCallers === true;
-  }
-
-  /**
-   * Route auth for the bridge: the per-boot bearer secret, from a loopback
-   * TCP peer — or from anywhere when the serve host exposed the bridge via
-   * `publicUrl` (cloud turns arrive through that ingress with the secret).
-   */
-  authPolicy(): AuthPolicy {
-    return async (request, info) => {
-      const loopback = info.requestIp !== null && isLoopbackAddress(info.requestIp);
-      if (!loopback && !this.allowRemoteCallers) {
-        return null;
-      }
-      if ((await this.secretPolicy(request, info)) === null) {
-        return null;
-      }
-      return {
-        authenticator: "cursor-account-bridge",
-        principalId: "cursor-account-bridge",
-        principalType: "runtime",
-      };
-    };
-  }
-
-  /**
-   * Handle one streamable-HTTP MCP request for the connection described by
-   * `ref` (stateless: fresh server per POST, like the per-agent endpoint).
-   */
-  handle(
-    request: Request,
-    ref: CursorAccountConnectionRef,
-    decorate?: (sessionId: string, result: AccountMcpCallResult) => AccountMcpCallResult,
-  ): Promise<Response> {
-    const sessionId = new URL(request.url).searchParams.get("agentkitSessionId") ?? "";
-    return handleStatelessMcpRequest({
-      request,
-      buildServer: () => this.buildServer(ref, sessionId, decorate),
-      label: "cursor account bridge",
-      logger: this.logger,
-    });
-  }
-
-  /**
-   * Startup DX: log the account's connector statuses for `refs` without
-   * blocking serve startup. Healthy catalogs stay a one-line summary;
-   * `needsAuth` / `error` / empty catalogs render a yellow warning box with
-   * reconnect URLs.
-   *
-   * Returns a promise that settles when every ref's log lines are written —
-   * callers may ignore it; tests can await it.
-   */
-  async probeAuthUrl(ref: CursorAccountConnectionRef): Promise<string | undefined> {
-    const identifiers =
-      ref.servers !== undefined && ref.servers.length > 0
-        ? [...ref.servers]
-        : (await this.client.getAvailableMcpServers()).map(
-            server => server.serverIdentifier ?? server.name,
-          );
-    const urls = await probeConnectorAuthUrls({
-      client: this.client,
-      identifiers,
-    });
-    for (const url of urls.values()) {
-      if (url !== "") {
-        return url;
-      }
-    }
-    return undefined;
-  }
-
-  logPreflight(refs: CursorAccountConnectionRef[]): Promise<void> {
-    return Promise.all(refs.map(ref => this.runPreflight(ref))).then(() => undefined);
-  }
-
-  private async runPreflight(ref: CursorAccountConnectionRef): Promise<void> {
-    try {
-      const catalog = await this.getCatalog(ref);
-      const errorDetails = new Map<string, string>();
-      const needsAuthNames = catalog.servers
-        .filter(server => server.status === "needsAuth")
-        .map(server => server.serverIdentifier);
-      const [authUrls] = await Promise.all([
-        probeConnectorAuthUrls({
-          client: this.client,
-          identifiers: needsAuthNames,
-        }),
-        Promise.all(
-          catalog.servers
-            .filter(server => server.status === "error")
-            .map(async server => {
-              const detail = await diagnoseConnectorError(this.client, server.serverIdentifier);
-              if (detail !== undefined) {
-                errorDetails.set(server.serverIdentifier, detail);
-              }
-            }),
-        ),
-      ]);
-
-      const unhealthy = catalog.servers.some(
-        server => server.status === "needsAuth" || server.status === "error",
-      );
-      if (catalog.servers.length === 0 || unhealthy) {
-        this.logger(
-          formatCursorAccountMcpWarningBox({
-            connectionName: ref.name,
-            servers: catalog.servers.map(server => ({
-              serverIdentifier: server.serverIdentifier,
-              status: server.status,
-              toolCount: server.tools.length,
-              errorDetail: errorDetails.get(server.serverIdentifier),
-              authUrl: authUrls.get(server.serverIdentifier),
-            })),
-            palette: this.palette,
-          }),
-        );
-        return;
-      }
-
-      const summary = catalog.servers
-        .map(server => formatServerStatusSummary(server, errorDetails.get(server.serverIdentifier)))
-        .join(", ");
-      this.logger(`${LOG_PREFIX} Cursor account MCP connection "${ref.name}": ${summary}`);
-    } catch (error: unknown) {
-      this.logger(
-        `${LOG_PREFIX} Cursor account MCP connection "${ref.name}" preflight failed: ${describeError(error)}`,
-      );
-    }
-  }
-
-  private buildServer(
-    ref: CursorAccountConnectionRef,
-    sessionId: string,
-    decorate?: (sessionId: string, result: AccountMcpCallResult) => AccountMcpCallResult,
-  ): Server {
-    const server = new Server(
-      { name: `cursor-account:${ref.name}`, version: "0.1.0" },
-      {
-        capabilities: { tools: {} },
-        instructions:
-          "Tools from the Cursor account's MCP connectors. Every call executes on the Cursor backend with the account's stored credentials.",
-      },
-    );
-
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
-      const catalog = await this.getCatalog(ref);
-      return {
-        tools: catalog.tools.map(tool => ({
-          name: tool.exposedName,
-          description: tool.description,
-          inputSchema: tool.inputSchema,
-          ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
-          // Already bounded to the MCP-spec fields at the backend-client
-          // parse; absent stays absent so classifiers fail closed.
-          ...(tool.annotations === undefined ? {} : { annotations: tool.annotations }),
-        })),
-      };
-    });
-
-    server.setRequestHandler(CallToolRequestSchema, async request => {
-      const tool = await this.findTool(ref, request.params.name);
-      if (tool === undefined) {
-        const catalog = await this.getCatalog(ref);
-        const unhealthy = catalog.servers.filter(server => server.status !== "connected");
-        const statusHint =
-          unhealthy.length === 0
-            ? ""
-            : ` Unhealthy connectors: ${unhealthy
-                .map(server => `${server.serverIdentifier}=${server.status}`)
-                .join(", ")}.`;
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Unknown tool "${request.params.name}". Available: ${
-                catalog.tools.map(t => t.exposedName).join(", ") || "(none)"
-              }.${statusHint}`,
-            },
-          ],
-          isError: true,
-        };
-      }
-      try {
-        const executed = await this.client.executeAccountMcpTool({
-          serverIdentifier: tool.serverIdentifier,
-          toolName: tool.backendName,
-          args: request.params.arguments ?? {},
-        });
-        const decorated = decorate === undefined ? executed : decorate(sessionId, executed);
-        return {
-          content: decorated.content,
-          isError: decorated.isError === true ? true : undefined,
-          structuredContent: decorated.structuredContent,
-        };
-      } catch (error) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Account connector tool failed: ${describeError(error)}`,
-            },
-          ],
-          isError: true,
-        };
-      }
-    });
-
-    return server;
-  }
-
-  /** Resolve a tool by exposed name, refreshing once when it is unknown. */
-  private async findTool(
-    ref: CursorAccountConnectionRef,
-    exposedName: string,
-  ): Promise<CatalogTool | undefined> {
-    const catalog = await this.getCatalog(ref);
-    const hit = catalog.byExposedName.get(exposedName);
-    if (hit !== undefined) {
-      return hit;
-    }
-    const fresh = await this.getCatalog(ref, { forceRefresh: true });
-    return fresh.byExposedName.get(exposedName);
-  }
-
-  /**
-   * Fetch (or join) the catalog for `ref`'s server filter. Staleness and
-   * joining are decided synchronously: in-flight entries always join their
-   * promise; fresh entries use {@link CatalogEntry.freshAtMs} for TTL.
-   */
-  private getCatalog(
-    ref: CursorAccountConnectionRef,
-    options?: { forceRefresh?: boolean },
-  ): Promise<Catalog> {
-    const key = ref.servers === undefined ? "*" : [...ref.servers].sort().join("\n");
-    const entry = this.catalogs.get(key);
-    if (entry !== undefined) {
-      if (entry.freshAtMs === undefined) {
-        return entry.promise;
-      }
-      const age = Date.now() - entry.freshAtMs;
-      const maxAge =
-        options?.forceRefresh === true ? FORCE_REFRESH_MIN_INTERVAL_MS : CATALOG_TTL_MS;
-      if (age < maxAge) {
-        return entry.promise;
-      }
-    }
-    const fresh: CatalogEntry = {
-      promise: this.client
-        .listAccountMcpTools(ref.servers ?? [])
-        .then(servers => {
-          const catalog = buildCatalog(servers);
-          fresh.freshAtMs = Date.now();
-          return catalog;
-        })
-        .catch((error: unknown) => {
-          // Never cache a failure — but only evict our own entry, so a slow
-          // failing fetch cannot delete a newer, healthy refresh.
-          if (this.catalogs.get(key) === fresh) {
-            this.catalogs.delete(key);
-          }
-          throw error;
-        }),
-    };
-    this.catalogs.set(key, fresh);
-    return fresh.promise;
-  }
-}
-
-/**
- * Build the exposed-tool catalog. Collision suffixes are assigned after
- * sorting the colliding group by backend identity, so the exposed-name →
- * backend-tool mapping is stable across refreshes even when the backend
- * enumerates servers in a different order.
- */
-function buildCatalog(servers: AccountMcpServer[]): Catalog {
-  const byBase = new Map<
-    string,
-    Array<{ serverIdentifier: string; tool: AccountMcpServer["tools"][number] }>
-  >();
-  for (const server of servers) {
-    for (const tool of server.tools) {
-      const base = sanitizeMcpToolName(tool.name);
-      const group = byBase.get(base);
-      const item = { serverIdentifier: server.serverIdentifier, tool };
-      if (group === undefined) {
-        byBase.set(base, [item]);
-      } else {
-        group.push(item);
-      }
-    }
-  }
-
-  const tools: CatalogTool[] = [];
-  const byExposedName = new Map<string, CatalogTool>();
-  // Process sanitize bases in deterministic order so cross-group exposed-name
-  // reservation does not depend on backend server listing order.
-  const sortedBases = [...byBase.keys()].sort((left, right) =>
-    left < right ? -1 : left > right ? 1 : 0,
-  );
-  for (const base of sortedBases) {
-    const group = byBase.get(base)!;
-    // Codepoint comparison (not localeCompare): the suffix assignment must
-    // be identical on every host and across refreshes.
-    group.sort((a, b) => {
-      const left = `${a.serverIdentifier}\n${a.tool.name}`;
-      const right = `${b.serverIdentifier}\n${b.tool.name}`;
-      return left < right ? -1 : left > right ? 1 : 0;
-    });
-    group.forEach(({ serverIdentifier, tool }, index) => {
-      let suffixIndex = index;
-      let exposedName = suffixMcpToolName(base, suffixIndex);
-      while (byExposedName.has(exposedName)) {
-        suffixIndex++;
-        exposedName = suffixMcpToolName(base, suffixIndex);
-      }
-      const entry: CatalogTool = {
-        exposedName,
-        backendName: tool.name,
-        serverIdentifier,
-        description: tool.description,
-        inputSchema: tool.inputSchema,
-        ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
-        ...(tool.annotations === undefined ? {} : { annotations: tool.annotations }),
-      };
-      tools.push(entry);
-      byExposedName.set(entry.exposedName, entry);
-    });
-  }
-  return { servers, tools, byExposedName };
-}
-
-function trimTrailingSlash(url: string): string {
-  return url.endsWith("/") ? url.slice(0, -1) : url;
-}
-
-export interface CursorAccountMcpWarningServer {
-  serverIdentifier: string;
-  status: string;
-  toolCount: number;
-  errorDetail?: string;
-  /** Minted OAuth URL for a `needsAuth` connector, when the probe succeeded. */
-  authUrl?: string;
-}
-
-const MAX_ERROR_DETAIL_CHARS = 72;
-
-function truncateDetail(detail: string): string {
-  const trimmed = detail.trim();
-  if (trimmed.length <= MAX_ERROR_DETAIL_CHARS) {
-    return trimmed;
-  }
-  return `${trimmed.slice(0, MAX_ERROR_DETAIL_CHARS - 1)}…`;
-}
-
-function formatWarningStatusRow(
-  server: CursorAccountMcpWarningServer,
-  nameWidth: number,
-  hyperlinks: boolean,
-): string {
-  const name = server.serverIdentifier.padEnd(nameWidth);
-  switch (server.status) {
-    case "needsAuth":
-      return `${name}  ${terminalHyperlink(connectUrl(server.authUrl), "Connect", hyperlinks)}`;
-    case "connected":
-      return `${name}  ${server.toolCount} tools`;
-    case "error": {
-      const detail =
-        server.errorDetail === undefined || server.errorDetail.trim() === ""
-          ? "backend could not reach connector"
-          : truncateDetail(server.errorDetail);
-      return `${name}  error: ${detail}`;
-    }
-    default:
-      return `${name}  ${server.status}`;
-  }
-}
-
-function connectUrl(authUrl: string | undefined): string {
-  const minted = authUrl?.trim() ?? "";
-  if (minted.startsWith("https://") && !minted.includes("\u001b") && !minted.includes("\u0007")) {
-    return minted;
-  }
-  return CURSOR_ACCOUNT_MCP_DASHBOARD_URL;
-}
-
-/**
- * Yellow warning panel for unhealthy / missing Cursor-account connectors.
- * One box replaces the old stacked `[agent-sdk]` log lines.
- */
-export function formatCursorAccountMcpWarningBox(args: {
-  connectionName: string;
-  servers: readonly CursorAccountMcpWarningServer[];
-  palette?: TerminalPalette;
-  hyperlinks?: boolean;
-}): string {
-  const palette = args.palette ?? stdoutPalette();
-  const hyperlinks = args.hyperlinks ?? colorEnabledFor();
-  const copy = warningCopy({ ...args, hyperlinks });
-  return `\n${formatTerminalBox([copy.title, "", ...copy.intro, ...copy.actions], {
-    color: palette.yellow,
-    padding: 2,
-  })}`;
-}
-
-function warningCopy(args: {
-  connectionName: string;
-  servers: readonly CursorAccountMcpWarningServer[];
-  hyperlinks: boolean;
-}): { title: string; intro: string[]; actions: string[] } {
-  const empty = args.servers.length === 0;
-  const hasAuth = args.servers.some(server => server.status === "needsAuth");
-  const hasError = args.servers.some(server => server.status === "error");
-  const nameWidth = Math.max(0, ...args.servers.map(server => server.serverIdentifier.length));
-  const statusRows = args.servers.map(server =>
-    formatWarningStatusRow(server, nameWidth, args.hyperlinks),
-  );
-  const links = [
-    `  ${CURSOR_ACCOUNT_MCP_SETTINGS_DEEPLINK}`,
-    `  ${CURSOR_ACCOUNT_MCP_DASHBOARD_URL}`,
-  ];
-  const restart = "Then press Enter to restart this serve.";
-
-  if (empty) {
-    return {
-      title: "No matching MCP connectors",
-      intro: [`No matching connectors on this account ("${args.connectionName}").`],
-      actions: ["", "Connect servers in Cursor, or fix the `servers` filter.", ...links],
-    };
-  }
-  if (hasAuth && !hasError) {
-    return {
-      title: "MCP authorization needed",
-      intro: statusRows,
-      actions: ["", restart, "", "Or reconnect at:", ...links],
-    };
-  }
-  return {
-    title: hasAuth ? "MCP authorization needed" : "MCP connector error",
-    intro: statusRows,
-    actions: ["", "Re-check the server URL is healthy, then reconnect at:", ...links, "", restart],
-  };
-}
-
-/** One-line status for the preflight summary (`name (12 tools)` / `name (error: …)`). */
-export function formatServerStatusSummary(server: AccountMcpServer, errorDetail?: string): string {
-  switch (server.status) {
-    case "connected":
-      return `${server.serverIdentifier} (${server.tools.length} tools)`;
-    case "needsAuth":
-      return `${server.serverIdentifier} (needsAuth — re-authorize in Cursor)`;
-    case "loading":
-      return `${server.serverIdentifier} (loading)`;
-    case "error": {
-      const detail =
-        errorDetail === undefined || errorDetail.trim() === ""
-          ? "backend could not reach connector"
-          : errorDetail.trim();
-      return `${server.serverIdentifier} (error: ${detail})`;
-    }
-    default:
-      return `${server.serverIdentifier} (${server.status})`;
-  }
-}
-
-/**
- * Best-effort detail for an `error`-status connector. ListSandMcpTools only
- * returns the status enum today, so probe ExecuteSandMcpTool (ping) and surface
- * the backend failure text (e.g. `HTTP MCP tool execution failed: fetch failed`).
- */
-export async function diagnoseConnectorError(
-  client: Pick<CursorBackendClient, "executeAccountMcpTool">,
-  serverIdentifier: string,
-): Promise<string | undefined> {
-  try {
-    const result = await client.executeAccountMcpTool({
-      serverIdentifier,
-      // Conventional health tool; even a tool-not-found path usually still
-      // surfaces the same transport failure when the connector is down.
-      toolName: `${serverIdentifier}-ping`,
-      args: {},
-    });
-    const text = result.content
-      .filter((part): part is { type: "text"; text: string } => part.type === "text")
-      .map(part => part.text.trim())
-      .filter(part => part.length > 0)
-      .join(" ");
-    if (result.isError) {
-      return text.length > 0 ? text : "backend reported an error with no detail";
-    }
-    // Listing said error but ping succeeded — surface that inconsistency.
-    return text.length > 0
-      ? `listing reported error but probe succeeded: ${text}`
-      : "listing reported error but probe succeeded";
-  } catch (error: unknown) {
-    return describeError(error);
-  }
-}