@superblocksteam/sdk-api 2.0.170 → 2.0.171-next.1

package/src/integrations/mcpintegration/client.ts

@@ -0,0 +1,544 @@
+/**
+ * MCP Server client implementation.
+ *
+ * Builds the JSON-RPC request carried by the MCP step and sends it through
+ * the orchestrator. The worker plugin owns the MCP handshake and session; the
+ * SDK shapes the request, hands the plugin's session back to it on later
+ * calls, and interprets the result.
+ */
+
+import type { PartialMessage } from "@bufbuild/protobuf";
+import { z } from "zod";
+
+import type {
+  JsonRpcRequest as McpJsonRpcRequestMessage,
+  Plugin as McpPlugin,
+} from "@superblocksteam/types/dist/src/plugins/mcpintegration/v1/plugin_pb";
+
+import {
+  RestApiValidationError,
+  restApiValidationErrorFromZodError,
+} from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import { describeJsonSerializationFailure } from "../base/request-body.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import { describeType } from "../utils.js";
+import type {
+  CallToolResult,
+  McpCallToolOptions,
+  McpClient,
+  McpContentBlock,
+  McpRequestOptions,
+  Tool,
+} from "./types.js";
+
+/**
+ * JSON-RPC request carried by the MCP step.
+ *
+ * Derived from the generated `plugins.mcpintegration.v1.JsonRpcRequest`. Its
+ * `params` and `id` fields are `google.protobuf.Value` messages in the
+ * generated type, but the request travels to the orchestrator as JSON, where
+ * a Value is the bare JSON value. The two fields are therefore re-typed to
+ * their wire form: `params` is the params object (the proto also accepts the
+ * JSON text of that object; the SDK always sends the object) and `id` is a
+ * string, number or null.
+ */
+type McpJsonRpcRequest = Omit<
+  PartialMessage<McpJsonRpcRequestMessage>,
+  "params" | "id"
+> & {
+  params?: Record<string, unknown>;
+  id?: string | number | null;
+};
+
+/**
+ * MCP step request. The generated `Plugin` type with the request re-typed as
+ * above. `clientCapabilities` is never set by the SDK. The server URL and auth
+ * come from the datasource configuration the orchestrator passes to the
+ * plugin, not from the step.
+ */
+type McpRequest = Omit<PartialMessage<McpPlugin>, "request"> & {
+  request: McpJsonRpcRequest;
+};
+
+const METHOD_CALL_TOOL = "tools/call";
+const METHOD_LIST_TOOLS = "tools/list";
+
+/**
+ * Upper bound on `tools/list` pages. A server that hands out a fresh cursor
+ * on every page would otherwise keep the API step running until it times out.
+ */
+const MAX_LIST_TOOLS_PAGES = 50;
+
+/**
+ * Headers the plugin reads (case-insensitively) to reuse the MCP session it
+ * opened on an earlier call instead of running the handshake again.
+ */
+const SESSION_ID_HEADER = "Mcp-Session-Id";
+const PROTOCOL_VERSION_HEADER = "MCP-Protocol-Version";
+
+/**
+ * An optional MCP field. Servers built on Python's pydantic serialize an
+ * absent optional as `null`, so both `undefined` and `null` mean absent and
+ * both come out as `undefined`.
+ */
+function absent<T extends z.ZodTypeAny>(schema: T) {
+  return schema.nullish().transform((value) => value ?? undefined);
+}
+
+/**
+ * The plugin adds these keys to a result when the call opened a session with
+ * a handshake-era server. They are the plugin's to reuse, not the caller's.
+ */
+const SessionFieldsSchema = z.object({
+  sessionId: absent(z.string()),
+  protocolVersion: absent(z.string()),
+});
+
+const ContentBlockSchema = z
+  .object({ type: z.string(), text: absent(z.string()) })
+  .passthrough();
+
+const CallToolResultSchema = z
+  .object({
+    content: z.array(ContentBlockSchema),
+    structuredContent: absent(z.record(z.unknown())),
+    isError: absent(z.boolean()),
+    _meta: absent(z.record(z.unknown())),
+  })
+  .passthrough();
+
+const ToolSchema = z
+  .object({
+    name: z.string().min(1),
+    title: absent(z.string()),
+    description: absent(z.string()),
+    inputSchema: z
+      .object({
+        type: z.literal("object"),
+        properties: absent(z.record(z.unknown())),
+        required: absent(z.array(z.string())),
+      })
+      .passthrough(),
+    outputSchema: absent(z.record(z.unknown())),
+    annotations: absent(
+      z
+        .object({
+          title: absent(z.string()),
+          readOnlyHint: absent(z.boolean()),
+          destructiveHint: absent(z.boolean()),
+          idempotentHint: absent(z.boolean()),
+          openWorldHint: absent(z.boolean()),
+        })
+        .passthrough(),
+    ),
+    _meta: absent(z.record(z.unknown())),
+  })
+  .passthrough();
+
+const ListToolsResultSchema = z
+  .object({
+    tools: z.array(ToolSchema),
+    nextCursor: absent(z.string()),
+  })
+  .passthrough();
+
+interface McpSession {
+  sessionId: string;
+  protocolVersion?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isTextBlock(
+  block: McpContentBlock,
+): block is McpContentBlock & { text: string } {
+  return block.type === "text" && typeof block.text === "string";
+}
+
+/**
+ * True for anything that behaves like a Zod schema, whichever zod copy built
+ * it. Used to catch a schema passed where tool arguments belong.
+ */
+function looksLikeSchema(value: unknown): boolean {
+  return (
+    value instanceof z.ZodType ||
+    (isRecord(value) &&
+      typeof value.safeParse === "function" &&
+      typeof value.parse === "function")
+  );
+}
+
+function hasHeader(headers: Record<string, string>, name: string): boolean {
+  const wanted = name.toLowerCase();
+  return Object.keys(headers).some((key) => key.toLowerCase() === wanted);
+}
+
+/**
+ * Concatenates the text of every `text` content block.
+ */
+function textContent(content: McpContentBlock[]): string {
+  return content
+    .filter(isTextBlock)
+    .map((block) => block.text)
+    .join("\n");
+}
+
+/**
+ * Thrown by `callTool` when the server rejects the tool as unknown or not
+ * available to the caller, so API code can tell it apart from a failed call.
+ */
+export class McpToolUnavailableError extends IntegrationError {
+  readonly toolName: string;
+
+  constructor(integrationName: string, toolName: string, cause?: unknown) {
+    super(integrationName, "callTool", cause);
+    this.message = `Tool "${toolName}" is not available on integration "${integrationName}"`;
+    this.name = "McpToolUnavailableError";
+    this.toolName = toolName;
+  }
+}
+
+// The spec answers an unknown tool with -32602; some servers use -32601 or an isError result.
+function namesUnknownTool(text: string, tool: string): boolean {
+  const name = tool.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(
+    `unknown tool:?\\s*["'\`]?${name}(?![\\w.-])|tool\\s+["'\`]?${name}["'\`]?\\s+not found`,
+    "i",
+  ).test(text);
+}
+
+function describeIssues(error: z.ZodError): string {
+  return error.issues
+    .slice(0, 3)
+    .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+    .join("; ");
+}
+
+/**
+ * Internal implementation of McpClient.
+ */
+export class McpClientImpl implements McpClient, IntegrationClientImpl {
+  readonly name: string;
+  readonly pluginId: string;
+  readonly config: IntegrationConfig;
+
+  private readonly executeQuery: QueryExecutor;
+  private nextRequestId = 1;
+  /** Session the plugin opened on an earlier call, sent back on later ones. */
+  private session: McpSession | undefined;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.name = config.name;
+    this.pluginId = config.pluginId;
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  callTool<T>(
+    name: string,
+    args: Record<string, unknown> | undefined,
+    options: McpCallToolOptions<T> & { schema: z.ZodSchema<T> },
+  ): Promise<T>;
+  callTool(
+    name: string,
+    args?: Record<string, unknown>,
+    options?: McpRequestOptions,
+  ): Promise<CallToolResult>;
+  callTool<T>(
+    name: string,
+    args?: Record<string, unknown>,
+    options?: McpCallToolOptions<T>,
+  ): Promise<CallToolResult | T>;
+  async callTool<T>(
+    name: string,
+    args?: Record<string, unknown>,
+    options?: McpCallToolOptions<T>,
+  ): Promise<CallToolResult | T> {
+    if (args && looksLikeSchema(args.schema)) {
+      throw new TypeError(
+        `callTool("${name}"): a Zod schema was passed inside the tool arguments; ` +
+          "pass it as the third argument instead: callTool(name, args, { schema })",
+      );
+    }
+
+    const result = await this.send(
+      METHOD_CALL_TOOL,
+      { name, arguments: this.toPlainArguments(name, args) },
+      options,
+      "callTool",
+    );
+
+    const toolResult = this.toCallToolResult(result, name);
+
+    if (toolResult.isError) {
+      const text = textContent(toolResult.content);
+      if (namesUnknownTool(text, name)) {
+        throw new McpToolUnavailableError(this.config.name, name, {
+          tool: name,
+          message: text,
+          result: toolResult,
+        });
+      }
+      throw new IntegrationError(this.config.name, "callTool", {
+        tool: name,
+        message: text
+          ? `Tool "${name}" failed: ${text}`
+          : `Tool "${name}" reported an error without text content`,
+        result: toolResult,
+      });
+    }
+
+    if (!options?.schema) {
+      return toolResult;
+    }
+
+    return this.validate(toolResult, options.schema, name);
+  }
+
+  async listTools(options?: McpRequestOptions): Promise<Tool[]> {
+    const tools: Tool[] = [];
+    const seenCursors = new Set<string>();
+    let cursor: string | undefined;
+
+    for (let page = 1; page <= MAX_LIST_TOOLS_PAGES; page++) {
+      const result = await this.send(
+        METHOD_LIST_TOOLS,
+        cursor === undefined ? {} : { cursor },
+        options,
+        "listTools",
+      );
+
+      const parsed = ListToolsResultSchema.safeParse(result);
+      if (!parsed.success) {
+        throw new IntegrationError(
+          this.config.name,
+          "listTools",
+          `tools/list returned something other than a tools array (${describeType(result)}): ${describeIssues(parsed.error)}`,
+        );
+      }
+
+      this.rememberSession(SessionFieldsSchema.parse(parsed.data));
+      tools.push(...parsed.data.tools);
+
+      const next = parsed.data.nextCursor;
+      if (!next) {
+        return tools;
+      }
+      if (seenCursors.has(next)) {
+        throw new IntegrationError(
+          this.config.name,
+          "listTools",
+          `tools/list repeated a cursor on page ${page}`,
+        );
+      }
+      seenCursors.add(next);
+      cursor = next;
+    }
+
+    throw new IntegrationError(
+      this.config.name,
+      "listTools",
+      `tools/list did not finish within ${MAX_LIST_TOOLS_PAGES} pages`,
+    );
+  }
+
+  /**
+   * Builds the MCP step request for one JSON-RPC call.
+   *
+   * The session the plugin returned on an earlier call is sent back as
+   * headers so the plugin reuses it. Headers the caller passes win.
+   */
+  private buildRequest(
+    method: string,
+    params: Record<string, unknown>,
+    headers: Record<string, string> | undefined,
+  ): McpRequest {
+    const merged: Record<string, string> = {};
+    if (this.session && !hasHeader(headers ?? {}, SESSION_ID_HEADER)) {
+      merged[SESSION_ID_HEADER] = this.session.sessionId;
+      if (this.session.protocolVersion) {
+        merged[PROTOCOL_VERSION_HEADER] = this.session.protocolVersion;
+      }
+    }
+    Object.assign(merged, headers);
+
+    const request: McpRequest = {
+      request: {
+        method,
+        params,
+        id: this.nextRequestId++,
+      },
+    };
+
+    const entries = Object.entries(merged);
+    if (entries.length > 0) {
+      request.headers = entries.map(([key, value]) => ({ key, value }));
+    }
+
+    return request;
+  }
+
+  /**
+   * Sends one JSON-RPC request through the orchestrator and returns the
+   * server's result untyped.
+   */
+  private async send(
+    method: string,
+    params: Record<string, unknown>,
+    options: McpRequestOptions | undefined,
+    operation: string,
+  ): Promise<unknown> {
+    const request = this.buildRequest(method, params, options?.headers);
+    const metadata: TraceMetadata | undefined = options?.label
+      ? { label: options.label }
+      : undefined;
+
+    try {
+      return await this.executeQuery({ ...request }, undefined, metadata);
+    } catch (error) {
+      if (
+        error instanceof IntegrationError ||
+        error instanceof RestApiValidationError
+      ) {
+        throw error;
+      }
+      if (method === METHOD_CALL_TOOL && error instanceof Error) {
+        const tool = String(params.name);
+        if (
+          /error -3260[12] for tools\/call/.test(error.message) &&
+          namesUnknownTool(error.message, tool)
+        ) {
+          throw new McpToolUnavailableError(this.config.name, tool, error);
+        }
+      }
+      throw new IntegrationError(this.config.name, operation, error);
+    }
+  }
+
+  // Sandbox args can be proxies, which the worker cannot structured-clone.
+  private toPlainArguments(
+    tool: string,
+    args: Record<string, unknown> | undefined,
+  ): Record<string, unknown> {
+    if (!args) {
+      return {};
+    }
+    try {
+      return JSON.parse(JSON.stringify(args));
+    } catch (error) {
+      throw new IntegrationError(
+        this.config.name,
+        "callTool",
+        `Tool "${tool}" arguments are not JSON-serializable: ${describeJsonSerializationFailure(error, "the arguments object")}`,
+      );
+    }
+  }
+
+  private rememberSession(result: z.infer<typeof SessionFieldsSchema>): void {
+    if (result.sessionId) {
+      this.session = {
+        sessionId: result.sessionId,
+        protocolVersion: result.protocolVersion,
+      };
+    }
+  }
+
+  /**
+   * Checks the shape of a `tools/call` result, records the session the
+   * plugin may have opened, and drops the plugin's session fields so they
+   * never reach API code. Optional fields sent as `null` count as absent.
+   */
+  private toCallToolResult(raw: unknown, tool: string): CallToolResult {
+    const parsed = CallToolResultSchema.safeParse(raw);
+    if (!parsed.success) {
+      throw new IntegrationError(
+        this.config.name,
+        "callTool",
+        `Tool "${tool}" returned something other than a CallToolResult (${describeType(raw)}): ${describeIssues(parsed.error)}`,
+      );
+    }
+
+    this.rememberSession(SessionFieldsSchema.parse(parsed.data));
+
+    const { sessionId, protocolVersion, structuredContent, ...rest } =
+      parsed.data;
+    void sessionId;
+    void protocolVersion;
+
+    return {
+      ...rest,
+      structuredContent: isRecord(structuredContent)
+        ? structuredContent
+        : undefined,
+    };
+  }
+
+  /**
+   * Validates a tool result against the caller's schema.
+   *
+   * Uses `structuredContent` when the server returned an object. Otherwise
+   * takes the first `text` block: if the text is JSON, the parsed value is
+   * validated first and the raw string second, so a schema that wants a
+   * string still gets "12345" as a string; text that is not JSON is validated
+   * as a string.
+   */
+  private validate<T>(
+    result: CallToolResult,
+    schema: z.ZodSchema<T>,
+    tool: string,
+  ): T {
+    const candidates: unknown[] = [];
+
+    if (result.structuredContent !== undefined) {
+      candidates.push(result.structuredContent);
+    } else {
+      const firstText = result.content.find(isTextBlock);
+      if (!firstText) {
+        throw new IntegrationError(
+          this.config.name,
+          "callTool",
+          `Tool "${tool}" returned no structuredContent and no text block to validate against the schema`,
+        );
+      }
+      const parsedJson = tryParseJson(firstText.text);
+      if (parsedJson.ok && parsedJson.value !== firstText.text) {
+        candidates.push(parsedJson.value);
+      }
+      candidates.push(firstText.text);
+    }
+
+    let firstFailure: { error: z.ZodError; candidate: unknown } | undefined;
+    for (const candidate of candidates) {
+      const parsed = schema.safeParse(candidate);
+      if (parsed.success) {
+        return parsed.data;
+      }
+      firstFailure ??= { error: parsed.error, candidate };
+    }
+
+    // candidates is never empty, so firstFailure is set when we get here.
+    const failure = firstFailure ?? {
+      error: new z.ZodError([]),
+      candidate: undefined,
+    };
+    throw restApiValidationErrorFromZodError(
+      `Tool "${tool}" result validation failed`,
+      failure.error,
+      failure.candidate,
+    );
+  }
+}
+
+function tryParseJson(
+  text: string,
+): { ok: true; value: unknown } | { ok: false } {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false };
+  }
+}

package/src/integrations/mcpintegration/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "mcpintegration",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/mcpintegration/index.ts

@@ -0,0 +1,16 @@
+/**
+ * MCP Server integration client.
+ *
+ * @module
+ */
+
+export type {
+  McpClient,
+  McpCallToolOptions,
+  McpRequestOptions,
+  CallToolResult,
+  McpContentBlock,
+  Tool,
+  ToolAnnotations,
+} from "./types.js";
+export { McpClientImpl, McpToolUnavailableError } from "./client.js";