@cursor/july 0.1.1

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

@@ -0,0 +1,472 @@
+/**
+ * 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 } from "../../types.js";
+import { isCursorAccountTransport } from "../../types.js";
+import { handleStatelessMcpRequest } from "../mcp-endpoint.js";
+import { isLoopbackAddress } from "../net.js";
+import type { EngineResolvedConnection } from "../session-engine.js";
+import type {
+  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;
+/** MCP clients commonly enforce `^[a-zA-Z0-9_-]{1,128}$` for tool names. */
+const MAX_TOOL_NAME_LENGTH = 128;
+
+// ============================================================================
+// 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) {
+      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>;
+}
+
+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 secretPolicy: AuthPolicy;
+  private readonly allowRemoteCallers: boolean;
+  private readonly catalogs = new Map<string, CatalogEntry>();
+
+  constructor(args: {
+    client: CursorBackendClient;
+    logger?: (line: string) => void;
+    /**
+     * 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.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): Promise<Response> {
+    return handleStatelessMcpRequest({
+      request,
+      buildServer: () => this.buildServer(ref),
+      label: "cursor account bridge",
+      logger: this.logger,
+    });
+  }
+
+  /**
+   * Startup DX: log the account's connector statuses for `refs` without
+   * blocking serve startup. Surfaces "needsAuth" connectors (authorize in
+   * Cursor) and filters that matched nothing (typo'd connector names).
+   */
+  logPreflight(refs: CursorAccountConnectionRef[]): void {
+    for (const ref of refs) {
+      void this.getCatalog(ref)
+        .then((catalog) => {
+          const summary = catalog.servers
+            .map(
+              (server) =>
+                `${server.serverIdentifier} (${
+                  server.status === "connected"
+                    ? `${server.tools.length} tools`
+                    : server.status
+                })`
+            )
+            .join(", ");
+          this.logger(
+            `[agent-serve] Cursor account MCP connection "${ref.name}": ${
+              catalog.servers.length === 0
+                ? "no matching connectors on this account — connect servers in Cursor (dashboard → MCP) or fix the `servers` filter"
+                : summary
+            }`
+          );
+          const needsAuth = catalog.servers.filter(
+            (server) => server.status === "needsAuth"
+          );
+          if (needsAuth.length > 0) {
+            this.logger(
+              `[agent-serve] Cursor account MCP connection "${ref.name}": ${needsAuth
+                .map((server) => server.serverIdentifier)
+                .join(
+                  ", "
+                )} need re-authorization in Cursor before their tools appear`
+            );
+          }
+        })
+        .catch((error: unknown) => {
+          this.logger(
+            `[agent-serve] Cursor account MCP connection "${ref.name}" preflight failed: ${describeError(error)}`
+          );
+        });
+    }
+  }
+
+  private buildServer(ref: CursorAccountConnectionRef): 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,
+        })),
+      };
+    });
+
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const tool = await this.findTool(ref, request.params.name);
+      if (tool === undefined) {
+        const catalog = await this.getCatalog(ref);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Unknown tool "${request.params.name}". Available: ${
+                catalog.tools.map((t) => t.exposedName).join(", ") || "(none)"
+              }.`,
+            },
+          ],
+          isError: true,
+        };
+      }
+      try {
+        const result = await this.client.executeAccountMcpTool({
+          serverIdentifier: tool.serverIdentifier,
+          toolName: tool.backendName,
+          args: request.params.arguments ?? {},
+        });
+        return {
+          content: result.content,
+          ...(result.isError ? { isError: true } : {}),
+          ...(result.structuredContent === undefined
+            ? {}
+            : { structuredContent: result.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 = sanitizeToolName(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 = suffixToolName(base, suffixIndex);
+      while (byExposedName.has(exposedName)) {
+        suffixIndex++;
+        exposedName = suffixToolName(base, suffixIndex);
+      }
+      const entry: CatalogTool = {
+        exposedName,
+        backendName: tool.name,
+        serverIdentifier,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      };
+      tools.push(entry);
+      byExposedName.set(entry.exposedName, entry);
+    });
+  }
+  return { servers, tools, byExposedName };
+}
+
+/** Connector display names can contain anything (spaces, dots, emoji). */
+function sanitizeToolName(name: string): string {
+  const cleaned = name
+    .replace(/[^a-zA-Z0-9_-]/g, "_")
+    .slice(0, MAX_TOOL_NAME_LENGTH);
+  return cleaned === "" ? "tool" : cleaned;
+}
+
+/** `base` for the first claimant, `base_2` / `base_3` … for colliders. */
+function suffixToolName(base: string, index: number): string {
+  if (index === 0) {
+    return base;
+  }
+  const suffix = `_${index + 1}`;
+  return `${base.slice(0, MAX_TOOL_NAME_LENGTH - suffix.length)}${suffix}`;
+}
+
+function trimTrailingSlash(url: string): string {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}