@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/mcp-host.ts

@@ -1,509 +0,0 @@
-/**
- * Host-side MCP clients for authored `agent/mcp-connections/*` and
- * `agent/host-connections/*`.
- *
- * Model-visible connections (`mcp-connections/`) are available in three
- * places: SDK `mcpServers`, in-process server tools through
- * {@link HostMcpRegistry} on {@link ToolContext.host}.mcp, and channel /
- * webhook handlers through {@link HostMcpRegistry} on
- * {@link ChannelHandlerArgs.host}.mcp. Host connections skip the model
- * and stay on `host.mcp` plus `mcp oauth`.
- */
-
-import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import {
-  connectionAllowsTool,
-  type DiscoveredConnection,
-  type HostMcpCallResult,
-  type HostMcpRegistry,
-  type HostMcpToolInfo,
-  type JsonObject,
-  type McpToolAnnotations,
-} from "../types.js";
-import {
-  connectionCredentialsFingerprint,
-  resolveConnectionEnvTemplates,
-} from "./connection-env.js";
-import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
-import { createHostMcpOAuthProvider } from "./mcp-oauth.js";
-import { instrumentedMcpFetch, mcpTraceMeta, runMcpClientSpan } from "./otel/mcp.js";
-
-export class McpNeedsAuthError extends Error {
-  readonly connection: string;
-
-  constructor(connection: string, cause?: unknown) {
-    super(
-      `MCP connection "${connection}" needs authorization. Run \`${CLI} mcp oauth ${connection}\`.`,
-    );
-    this.name = "McpNeedsAuthError";
-    this.connection = connection;
-    if (cause !== undefined) {
-      this.cause = cause;
-    }
-  }
-}
-
-export function isMcpNeedsAuthError(error: unknown): error is McpNeedsAuthError {
-  return error instanceof McpNeedsAuthError;
-}
-
-export function hostMcpCallNeedsAuth(result: HostMcpCallResult): boolean {
-  if (result.isError !== true) {
-    return false;
-  }
-  const text = result.content.map(part => (part.type === "text" ? part.text : "")).join("\n");
-  return text.includes("needsAuth") || text.includes("needs authorization");
-}
-
-function throwIfCallNeedsAuth(connection: string, result: HostMcpCallResult): HostMcpCallResult {
-  if (hostMcpCallNeedsAuth(result)) {
-    throw new McpNeedsAuthError(connection);
-  }
-  return result;
-}
-
-interface OpenedConnection {
-  client: Client;
-  close: () => Promise<void>;
-}
-
-interface CachedClient {
-  /** Fingerprint of the credentials this client opened with. */
-  credentials: string;
-  opened: Promise<OpenedConnection>;
-}
-
-/**
- * A non-caching view of one connection: every operation opens a fresh
- * client and closes it afterwards. See {@link McpHost.oneOff}.
- */
-export interface HostMcpOneOff {
-  listTools(): Promise<HostMcpToolInfo[]>;
-  callTool(toolName: string, args?: Record<string, unknown>): Promise<HostMcpCallResult>;
-}
-
-export class McpHost implements HostMcpRegistry {
-  private readonly byName = new Map<string, DiscoveredConnection>();
-  private readonly clients = new Map<string, CachedClient>();
-  private oauthRedirectUrl: string | undefined;
-
-  constructor(connections: DiscoveredConnection[]) {
-    for (const connection of connections) {
-      this.byName.set(connection.name, connection);
-    }
-  }
-
-  /** Public serve callback for host OAuth (not the CLI loopback port on pods). */
-  setOAuthRedirectUrl(url: string): void {
-    this.oauthRedirectUrl = url;
-  }
-
-  /**
-   * Register a connection after construction (serve-time resolved peers).
-   * Clients open lazily on first use, so adding before first call is safe.
-   */
-  addConnection(connection: DiscoveredConnection): void {
-    this.byName.set(connection.name, connection);
-  }
-
-  names(): string[] {
-    return [...this.byName.keys()].sort();
-  }
-
-  async listTools(connectionName: string): Promise<HostMcpToolInfo[]> {
-    const connection = this.requireConnection(connectionName);
-    return runMcpClientSpan({ method: "tools/list", connection: connectionName }, () =>
-      this.withClient(connectionName, async client => {
-        const listed = await client.listTools(mcpListParams());
-        return listed.tools
-          .map(toToolInfo)
-          .filter(tool => connectionAllowsTool(connection, tool.name));
-      }),
-    );
-  }
-
-  /**
-   * A one-off view of a connection that is not (or not exactly) in the
-   * registry — e.g. a registered connection with per-session auth headers
-   * substituted in. Every operation opens a fresh client and closes it
-   * afterwards: the registry's cached per-name client would leak one
-   * session's identity into another, and stateless streamable-HTTP
-   * servers answer a fresh initialize cheaply. Results ride the same
-   * mapping as registry calls.
-   */
-  oneOff(connection: DiscoveredConnection): HostMcpOneOff {
-    const redirectUrl = this.oauthRedirectUrl;
-    const withFreshClient = async <T>(run: (client: Client) => Promise<T>): Promise<T> => {
-      const opened = await openConnection(connection, redirectUrl);
-      try {
-        return await run(opened.client);
-      } finally {
-        await opened.close();
-      }
-    };
-    return {
-      listTools: () =>
-        runMcpClientSpan({ method: "tools/list", connection: connection.name }, () =>
-          withFreshClient(async client => {
-            const listed = await client.listTools(mcpListParams());
-            return listed.tools
-              .map(toToolInfo)
-              .filter(tool => connectionAllowsTool(connection, tool.name));
-          }),
-        ),
-      callTool: (toolName, args = {}) => {
-        assertConnectionAllowsTool(connection, toolName);
-        return runMcpClientSpan(
-          {
-            method: "tools/call",
-            connection: connection.name,
-            toolName,
-          },
-          () =>
-            withFreshClient(async client => {
-              const result = await client.callTool({
-                name: toolName,
-                arguments: args,
-                ...mcpCallMeta(),
-              });
-              return throwIfCallNeedsAuth(connection.name, normalizeCallResult(result));
-            }),
-        );
-      },
-    };
-  }
-
-  async callTool(
-    connectionName: string,
-    toolName: string,
-    args: Record<string, unknown> = {},
-  ): Promise<HostMcpCallResult> {
-    const connection = this.requireConnection(connectionName);
-    assertConnectionAllowsTool(connection, toolName);
-    return runMcpClientSpan({ method: "tools/call", connection: connectionName, toolName }, () =>
-      this.withClient(connectionName, async client => {
-        const result = await client.callTool({
-          name: toolName,
-          arguments: args,
-          ...mcpCallMeta(),
-        });
-        return throwIfCallNeedsAuth(connectionName, normalizeCallResult(result));
-      }),
-    );
-  }
-
-  async dropClient(name: string): Promise<void> {
-    const cached = this.clients.get(name);
-    this.clients.delete(name);
-    if (cached === undefined) {
-      return;
-    }
-    try {
-      await (await cached.opened).close();
-    } catch {
-      // Best-effort teardown.
-    }
-  }
-
-  async close(): Promise<void> {
-    const opened = await Promise.allSettled([...this.clients.values()].map(entry => entry.opened));
-    this.clients.clear();
-    await Promise.allSettled(
-      opened.map(async settled => {
-        if (settled.status === "fulfilled") {
-          await settled.value.close();
-        }
-      }),
-    );
-  }
-
-  /**
-   * Run against a cached host MCP client, reconnecting once when the remote
-   * Streamable HTTP session is gone (`session_terminated` / HTTP 404).
-   *
-   * Anytool (and the MCP spec) return 404 for unknown/terminated
-   * `Mcp-Session-Id`s so clients can re-initialize. The SDK transport keeps
-   * the dead session id, so without this invalidation every later host.mcp
-   * call fails until the serve process restarts.
-   */
-  private async withClient<T>(name: string, run: (client: Client) => Promise<T>): Promise<T> {
-    const opened = await this.getClient(name);
-    try {
-      return await run(opened.client);
-    } catch (error) {
-      if (!isStaleMcpSessionError(error)) {
-        throw error;
-      }
-      await this.invalidateClient(name, opened);
-      const reopened = await this.getClient(name);
-      return await run(reopened.client);
-    }
-  }
-
-  /**
-   * Cached per connection, but only for as long as the credentials it opened
-   * with still apply: a hosted deployment binds its secrets per request, so a
-   * rotated (or first-ever) value would otherwise never reach a client opened
-   * on an earlier turn.
-   */
-  private getClient(name: string): Promise<OpenedConnection> {
-    const credentials = connectionCredentialsFingerprint(this.requireConnection(name).transport);
-    const cached = this.clients.get(name);
-    if (cached !== undefined) {
-      if (cached.credentials === credentials) {
-        return cached.opened;
-      }
-      void this.dropClient(name);
-    }
-    // Only evict this entry: a connect that fails after its credentials were
-    // replaced would otherwise orphan the client that replaced it.
-    const entry: CachedClient = {
-      credentials,
-      opened: this.connect(name).catch(error => {
-        if (this.clients.get(name) === entry) {
-          this.clients.delete(name);
-        }
-        throw error;
-      }),
-    };
-    this.clients.set(name, entry);
-    return entry.opened;
-  }
-
-  private async invalidateClient(name: string, opened: OpenedConnection): Promise<void> {
-    const cached = this.clients.get(name);
-    if (cached !== undefined) {
-      try {
-        if ((await cached.opened) === opened) {
-          this.clients.delete(name);
-        }
-      } catch {
-        this.clients.delete(name);
-      }
-    }
-    await opened.close();
-  }
-
-  private requireConnection(name: string): DiscoveredConnection {
-    const connection = this.byName.get(name);
-    if (connection === undefined) {
-      const known = this.names().join(", ") || "(none)";
-      throw new Error(`Unknown MCP connection "${name}". Authored MCP connections: ${known}.`);
-    }
-    return connection;
-  }
-
-  private async connect(name: string): Promise<OpenedConnection> {
-    return openConnection(this.requireConnection(name), this.oauthRedirectUrl);
-  }
-}
-
-function assertConnectionAllowsTool(connection: DiscoveredConnection, toolName: string): void {
-  if (connectionAllowsTool(connection, toolName)) {
-    return;
-  }
-  throw new Error(`MCP connection "${connection.name}" does not allow tool "${toolName}".`);
-}
-
-/** Exported for unit tests. */
-export function isStaleMcpSessionError(error: unknown): boolean {
-  if (!(error instanceof Error)) {
-    return false;
-  }
-  if (error.message.includes("session_terminated")) {
-    return true;
-  }
-  // StreamableHTTPError from the MCP SDK carries the HTTP status as `.code`.
-  const code = (error as { code?: unknown }).code;
-  return code === 404;
-}
-
-/** Longest server-supplied annotation title carried off a listing. */
-const MAX_TOOL_ANNOTATION_TITLE_LENGTH = 256;
-
-/**
- * Bound a server's `Tool.annotations` to the MCP-spec fields: the four
- * boolean hints plus a length-capped `title`. A server cannot stuff
- * arbitrary payloads into every listing, and malformed values (a non-boolean
- * hint, a non-object) behave like absent ones so consumers fail closed.
- *
- * Mirrors `@anysphere/mcp-core/mcp-tool-annotations` (`toolAnnotationsJsonField`),
- * which this package cannot import: it publishes to npm and cannot take a
- * workspace-only runtime dependency. Keep the two in sync.
- *
- * Exported for unit tests.
- */
-export function boundedToolAnnotations(annotations: unknown): McpToolAnnotations | undefined {
-  if (typeof annotations !== "object" || annotations === null || Array.isArray(annotations)) {
-    return undefined;
-  }
-  const record = annotations as Record<string, unknown>;
-  const bounded: McpToolAnnotations = {};
-  if (typeof record.title === "string" && record.title.length > 0) {
-    bounded.title = record.title.slice(0, MAX_TOOL_ANNOTATION_TITLE_LENGTH);
-  }
-  for (const key of [
-    "readOnlyHint",
-    "destructiveHint",
-    "idempotentHint",
-    "openWorldHint",
-  ] as const) {
-    const value = record[key];
-    if (typeof value === "boolean") {
-      bounded[key] = value;
-    }
-  }
-  return Object.keys(bounded).length === 0 ? undefined : bounded;
-}
-
-function toToolInfo(tool: {
-  name: string;
-  description?: string;
-  inputSchema?: unknown;
-  outputSchema?: unknown;
-  annotations?: unknown;
-}): HostMcpToolInfo {
-  const annotations = boundedToolAnnotations(tool.annotations);
-  return {
-    name: tool.name,
-    ...(tool.description === undefined ? {} : { description: tool.description }),
-    ...(tool.inputSchema === undefined ? {} : { inputSchema: tool.inputSchema as JsonObject }),
-    ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema as JsonObject }),
-    ...(annotations === undefined ? {} : { annotations }),
-  };
-}
-
-async function openConnection(
-  connection: DiscoveredConnection,
-  oauthRedirectUrl?: string,
-): Promise<OpenedConnection> {
-  const client = new Client({
-    name: "agent-serve",
-    version: "0.1.0",
-  });
-  const transport = await createTransport(connection, oauthRedirectUrl);
-  try {
-    await client.connect(transport);
-  } catch (error) {
-    if (error instanceof UnauthorizedError && isOauthHttpTransport(connection.transport)) {
-      throw new McpNeedsAuthError(connection.name, error);
-    }
-    throw error;
-  }
-
-  return {
-    client,
-    close: async () => {
-      try {
-        await client.close();
-      } catch {
-        // Best-effort teardown.
-      }
-      try {
-        await transport.close?.();
-      } catch {
-        // Best-effort teardown.
-      }
-    },
-  };
-}
-
-async function createTransport(connection: DiscoveredConnection, oauthRedirectUrl?: string) {
-  const transport = resolveConnectionEnvTemplates(connection.transport);
-  if ("agent" in transport) {
-    // Peers are resolved to concrete URLs by the serve host before any call
-    // (SessionEngine.setResolvedConnections); reaching here means the
-    // connection is being used outside a running server.
-    throw new Error(
-      `MCP connection "${connection.name}" targets peer agent "${transport.agent}" and has not been resolved; peer MCP connections are only callable on a running serve host.`,
-    );
-  }
-  if ("cursorAccount" in transport) {
-    // Same contract as peers: the serve host resolves the account bridge URL
-    // before any call (SessionEngine.setResolvedConnections).
-    throw new Error(
-      `MCP connection "${connection.name}" exposes the Cursor account's connectors and has not been resolved; Cursor account MCP connections are only callable on a running serve host.`,
-    );
-  }
-  if ("command" in transport) {
-    return new StdioClientTransport({
-      command: transport.command,
-      ...(transport.args === undefined ? {} : { args: transport.args }),
-      env: {
-        ...Object.fromEntries(
-          Object.entries(process.env).filter(
-            (entry): entry is [string, string] => entry[1] !== undefined,
-          ),
-        ),
-        ...(transport.env ?? {}),
-      },
-      ...(transport.cwd === undefined ? {} : { cwd: transport.cwd }),
-    });
-  }
-
-  const url = new URL(transport.url);
-  const requestInit = transport.headers === undefined ? undefined : { headers: transport.headers };
-  const authProvider =
-    transport.oauth === true
-      ? await createHostMcpOAuthProvider({
-          identifier: connection.name,
-          resourceUrl: transport.url,
-          redirectUrl: oauthRedirectUrl,
-        })
-      : undefined;
-
-  const fetchImpl = instrumentedMcpFetch();
-  const fetchLike = (url: string | URL, init?: RequestInit) => fetchImpl(url, init);
-  if (transport.type === "sse") {
-    return new SSEClientTransport(url, {
-      requestInit,
-      authProvider,
-      fetch: fetchLike,
-    });
-  }
-  return new StreamableHTTPClientTransport(url, {
-    requestInit,
-    authProvider,
-    fetch: fetchLike,
-  });
-}
-
-function mcpListParams(): { _meta: { traceparent: string } } | undefined {
-  const meta = mcpTraceMeta();
-  return meta === undefined ? undefined : { _meta: meta };
-}
-
-function mcpCallMeta(): { _meta: { traceparent: string } } | Record<string, never> {
-  const meta = mcpTraceMeta();
-  return meta === undefined ? {} : { _meta: meta };
-}
-
-function isOauthHttpTransport(transport: DiscoveredConnection["transport"]): boolean {
-  return "url" in transport && transport.oauth === true;
-}
-
-function normalizeCallResult(result: unknown): HostMcpCallResult {
-  if (typeof result !== "object" || result === null) {
-    return {
-      content: [{ type: "text", text: String(result) }],
-    };
-  }
-  const record = result as {
-    content?: HostMcpCallResult["content"];
-    isError?: boolean;
-    structuredContent?: JsonObject;
-  };
-  return {
-    content: Array.isArray(record.content)
-      ? record.content
-      : [{ type: "text", text: JSON.stringify(result) }],
-    ...(record.isError === undefined ? {} : { isError: record.isError }),
-    ...(record.structuredContent === undefined
-      ? {}
-      : { structuredContent: record.structuredContent }),
-  };
-}