@superblocksteam/sdk-api 0.0.13 → 0.0.15-mcp.1

package/src/integrations/mcpintegration/types.ts

@@ -0,0 +1,185 @@
+/**
+ * MCP Server client types.
+ *
+ * An MCP Server integration points at a remote Model Context Protocol server.
+ * The client exposes the tools surface of that server: list the tools it
+ * advertises and call one of them. Resources and prompts are not exposed yet.
+ */
+
+import type { z } from "zod";
+
+import type { BaseIntegrationClient } from "../../types.js";
+
+/**
+ * One block of a tool result's `content` array.
+ *
+ * MCP defines text, image, audio, resource link and embedded resource blocks.
+ * Only `type` is guaranteed; the remaining fields depend on the block type.
+ */
+export interface McpContentBlock {
+  type: string;
+  /** Present on `text` blocks. */
+  text?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * The result of a `tools/call` request, as returned by the MCP server.
+ */
+export interface CallToolResult {
+  /** Unstructured result blocks. */
+  content: McpContentBlock[];
+  /** Structured result, present when the tool declares an output schema. */
+  structuredContent?: Record<string, unknown>;
+  /** True when the tool itself failed; `content` then carries the error text. */
+  isError?: boolean;
+  _meta?: Record<string, unknown>;
+}
+
+/**
+ * Behavioral hints a server attaches to a tool. All hints are advisory.
+ */
+export interface ToolAnnotations {
+  title?: string;
+  readOnlyHint?: boolean;
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
+  [key: string]: unknown;
+}
+
+/**
+ * One tool advertised by the MCP server through `tools/list`.
+ */
+export interface Tool {
+  name: string;
+  title?: string;
+  description?: string;
+  /** JSON Schema describing the tool's `arguments` object. */
+  inputSchema: {
+    type: "object";
+    properties?: Record<string, unknown>;
+    required?: string[];
+    [key: string]: unknown;
+  };
+  /** JSON Schema describing `structuredContent`, when the tool declares one. */
+  outputSchema?: Record<string, unknown>;
+  annotations?: ToolAnnotations;
+  _meta?: Record<string, unknown>;
+}
+
+/**
+ * Options shared by every MCP request.
+ *
+ * **Security:** `label` is trace metadata and may be stored in logs; do not put
+ * secrets in it. Headers are sent to the MCP server as-is.
+ */
+export interface McpRequestOptions {
+  /** Short human-readable label shown in the Trace View for this call. */
+  label?: string;
+  /**
+   * Extra HTTP headers for this request, on top of the headers configured on
+   * the integration. Use this for per-call values such as `Mcp-Param-*`.
+   */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Options for {@link McpClient.callTool}. Always the third argument: a schema
+ * placed inside `args` is rejected with a `TypeError` instead of being sent to
+ * the server as tool arguments.
+ */
+export interface McpCallToolOptions<T = unknown> extends McpRequestOptions {
+  /**
+   * Zod schema for the tool result. When given, the call returns the validated
+   * value instead of the `CallToolResult`. The value validated is
+   * `structuredContent` when the server returns an object; otherwise the first
+   * `text` block. Text that is JSON is validated as the parsed value first and
+   * as the raw string second, so a string schema still accepts text such as
+   * "12345". Text that is not JSON is validated as a string.
+   */
+  schema?: z.ZodSchema<T>;
+}
+
+/**
+ * MCP Server client for listing and calling tools.
+ *
+ * When the server needs an MCP session (handshake-era servers), the plugin
+ * opens one on the first call and the client sends it back on every later
+ * call of the same API run, so the handshake runs once per client instance.
+ *
+ * @example
+ * ```typescript
+ * const mcp = ctx.integrations.github;
+ *
+ * // Discover the server's tools
+ * const tools = await mcp.listTools();
+ *
+ * // Call a tool and get the raw CallToolResult
+ * const raw = await mcp.callTool("search_issues", { query: "is:open" });
+ *
+ * // Call a tool and validate the result
+ * const issues = await mcp.callTool(
+ *   "search_issues",
+ *   { query: "is:open" },
+ *   { schema: z.object({ items: z.array(IssueSchema) }) },
+ * );
+ * ```
+ */
+export interface McpClient extends BaseIntegrationClient {
+  /**
+   * Call a tool and validate its result against `schema`.
+   *
+   * @param name - Tool name as advertised by `tools/list`
+   * @param args - Tool arguments; sent as `{}` when omitted
+   * @param options - Request options with a required `schema`
+   * @returns The validated result
+   * @throws IntegrationError when the server reports `isError: true`
+   * @throws RestApiValidationError when the result does not match `schema`
+   */
+  callTool<T>(
+    name: string,
+    args: Record<string, unknown> | undefined,
+    options: McpCallToolOptions<T> & { schema: z.ZodSchema<T> },
+  ): Promise<T>;
+
+  /**
+   * Call a tool and return the server's `CallToolResult`, with the plugin's
+   * session bookkeeping fields removed and a `null` `structuredContent`
+   * normalized to absent.
+   *
+   * @param name - Tool name as advertised by `tools/list`
+   * @param args - Tool arguments; sent as `{}` when omitted
+   * @param options - Request options
+   * @returns The `CallToolResult`
+   * @throws IntegrationError when the server reports `isError: true`; the
+   *   error's `details.cause` carries the tool name, the text and the result
+   */
+  callTool(
+    name: string,
+    args?: Record<string, unknown>,
+    options?: McpRequestOptions,
+  ): Promise<CallToolResult>;
+
+  /**
+   * Call a tool. Returns the validated value when `options.schema` is set,
+   * otherwise the `CallToolResult`.
+   */
+  callTool<T>(
+    name: string,
+    args?: Record<string, unknown>,
+    options?: McpCallToolOptions<T>,
+  ): Promise<CallToolResult | T>;
+
+  /**
+   * List every tool the server advertises.
+   *
+   * Follows `nextCursor` until the server stops paginating, so the returned
+   * array is the complete catalog. Gives up with an `IntegrationError` after
+   * 50 pages or when a cursor repeats.
+   *
+   * @param options - Request options
+   * @returns All tools, in server order
+   */
+  listTools(options?: McpRequestOptions): Promise<Tool[]>;
+}

package/src/integrations/postgres/README.md

@@ -292,9 +292,7 @@ The `query()` method requires a Zod schema for runtime validation. This is by de
 // WRONG - Missing schema parameter
 const users = await ctx.integrations.db.query(
   "SELECT * FROM users",
-  [
-    /* params */
-  ], // This is wrong - params are 3rd argument
+  [/* params */], // This is wrong - params are 3rd argument
 );
 
 // CORRECT - Schema is the second parameter

package/src/integrations/registry.ts

@@ -28,6 +28,7 @@ import { HubSpotClientImpl } from "./hubspot/index.js";
 import { IntercomClientImpl } from "./intercom/index.js";
 import { JiraClientImpl } from "./jira/index.js";
 import { LaunchDarklyClientImpl } from "./launchdarkly/index.js";
+import { McpClientImpl } from "./mcpintegration/index.js";
 import { MistralClientImpl } from "./mistral/index.js";
 import { NotionClientImpl } from "./notion/index.js";
 import { OpenAIClientImpl } from "./openai_v2/index.js";
@@ -137,6 +138,8 @@ export const SUPPORTED_PLUGINS = {
   snowflakepostgres: "snowflakepostgres",
   // Email
   smtp: "smtp",
+  // MCP servers
+  mcpintegration: "mcpintegration",
   // REST API plugins
   restapiintegration: "restapiintegration",
 } as const;
@@ -406,6 +409,9 @@ export function createClient(
     case SUPPORTED_PLUGINS.smtp:
       return new SmtpClientImpl(config, executeQuery);
 
+    case SUPPORTED_PLUGINS.mcpintegration:
+      return new McpClientImpl(config, executeQuery);
+
     case SUPPORTED_PLUGINS.restapiintegration:
       return new RestApiIntegrationPluginClientImpl(config, executeQuery);
 

package/src/integrations/restapiintegration/client.test.ts

@@ -227,50 +227,55 @@ describe("RestApiIntegrationPluginClientImpl", () => {
       expect(executeQuery).toHaveBeenCalled();
     });
 
-    it("accepts response schemas that transform bytes to bytes", async () => {
+    it("returns decoded bytes and ignores a response schema passed at runtime", async () => {
+      // Models sandboxed API code: its Uint8Array is a different constructor,
+      // so a caller's z.instanceof(Uint8Array) rejects every SDK-decoded body.
+      const crossRealmInstanceof = z.custom<Uint8Array>(() => false);
       const { client } = createClient(workerBufferPayload(PDF_BYTES));
 
-      const result = await client.apiRequest(
+      const result = await callApiRequest(
+        client,
         { method: "GET", path: "/file.pdf", responseType: "binary" },
-        {
-          response: z
-            .instanceof(Uint8Array)
-            .refine((bytes) => bytes[0] === 0x25)
-            .transform((bytes) => bytes.slice(1)),
-        },
+        { response: crossRealmInstanceof },
       );
 
-      expect(Array.from(result)).toEqual(PDF_BYTES.slice(1));
+      expect(result).toBeInstanceOf(Uint8Array);
+      expect(result instanceof Uint8Array && Array.from(result)).toEqual(
+        PDF_BYTES,
+      );
     });
 
-    it("throws RestApiValidationError when the schema rejects normalized bytes", async () => {
-      const { client } = createClient(workerBufferPayload(PDF_BYTES));
+    it("still validates the request body for binary responses", async () => {
+      const { client, executeQuery } = createClient(
+        workerBufferPayload(PDF_BYTES),
+      );
+
+      const dynamicBody: unknown = JSON.parse('{"pages":"many"}');
 
       await expect(
         client.apiRequest(
-          { method: "GET", path: "/file.pdf", responseType: "binary" },
           {
-            response: z
-              .instanceof(Uint8Array)
-              .refine((bytes) => bytes.byteLength > 64),
+            method: "POST",
+            path: "/render.pdf",
+            body: dynamicBody,
+            responseType: "binary",
           },
+          { body: z.object({ pages: z.number() }) },
         ),
       ).rejects.toThrow(RestApiValidationError);
+      expect(executeQuery).not.toHaveBeenCalled();
     });
 
-    it("redacts binary data from response validation errors", async () => {
-      const bytes = Array.from({ length: 4096 }, () => 0);
+    it("redacts binary data from malformed-body errors", async () => {
+      const bytes = [...Array.from({ length: 4096 }, () => 0), 256];
       const { client } = createClient(workerBufferPayload(bytes));
 
       try {
-        await client.apiRequest(
-          { method: "GET", path: "/file.pdf", responseType: "binary" },
-          {
-            response: z
-              .instanceof(Uint8Array)
-              .refine((value) => value.byteLength < 1024),
-          },
-        );
+        await client.apiRequest({
+          method: "GET",
+          path: "/file.pdf",
+          responseType: "binary",
+        });
       } catch (error) {
         expect(error).toBeInstanceOf(RestApiValidationError);
         if (!(error instanceof RestApiValidationError)) {
@@ -282,20 +287,20 @@ describe("RestApiIntegrationPluginClientImpl", () => {
         });
         return;
       }
-      throw new Error("Expected binary response validation to fail");
+      throw new Error("Expected malformed binary decoding to fail");
     });
 
     it("keeps binary bytes out of the thrown message, not just details.zodError", async () => {
-      const bytes = [137, 80, 78, 71];
+      const bytes = [137, 80, 78, 71, 256];
       const { client } = createClient(workerBufferPayload(bytes));
 
       let caught: unknown;
       try {
-        await callApiRequest(
-          client,
-          { method: "GET", path: "/file.png", responseType: "binary" },
-          { response: z.literal("unexpected") },
-        );
+        await client.apiRequest({
+          method: "GET",
+          path: "/file.png",
+          responseType: "binary",
+        });
       } catch (error) {
         caught = error;
       }
@@ -461,24 +466,32 @@ describe("RestApiIntegrationPluginClientImpl", () => {
       await wrongBinary;
     });
 
-    it("rejects binary response schemas that transform bytes to another type", () => {
+    it("rejects response schemas on binary requests but accepts body schemas", async () => {
       const { client: binaryClient } = createClient(
         workerBufferPayload(PDF_BYTES),
       );
 
-      // @ts-expect-error binary response schemas must output Uint8Array
-      binaryClient.apiRequest(
+      // @ts-expect-error binary responses do not take a response schema
+      const withResponse = binaryClient.apiRequest(
         {
           method: "GET",
           path: "/file.pdf",
           responseType: "binary",
         },
+        { response: z.instanceof(Uint8Array) },
+      );
+      await withResponse;
+
+      const withBody: Promise<Uint8Array> = binaryClient.apiRequest(
         {
-          response: z
-            .instanceof(Uint8Array)
-            .transform((bytes) => bytes.byteLength),
+          method: "POST",
+          path: "/render.pdf",
+          body: { pages: 1 },
+          responseType: "binary",
         },
+        { body: z.object({ pages: z.number() }) },
       );
+      expect(Array.from(await withBody)).toEqual(PDF_BYTES);
     });
 
     it("rejects response types outside the public SDK contract", async () => {

package/src/integrations/restapiintegration/overlays/response-types-binary.md

@@ -5,7 +5,7 @@
 - `"binary"` for PDFs and other byte payloads. The result is a `Uint8Array`
 - `"text"` for XML, CSV, HTML, and other decoded strings
 
-With `responseType: "text"` or `responseType: "binary"` the response schema may be omitted. Text returns the raw string typed `unknown`. Binary returns a `Uint8Array`:
+With `responseType: "text"` the response schema may be omitted, and the raw string is returned typed `unknown`. With `responseType: "binary"` never pass a response schema. The SDK decodes and validates the bytes and returns a `Uint8Array`:
 
 ```typescript
 const xml = await ctx.integrations.legacyApi.apiRequest({
@@ -23,7 +23,7 @@ const pdf = await ctx.integrations.legacyApi.apiRequest({
 // pdf is a Uint8Array
 ```
 
-To validate after decoding, pass a schema that matches the decoded value:
+To validate a text response after decoding, pass a schema that matches the decoded string:
 
 ```typescript
 const xml = await ctx.integrations.legacyApi.apiRequest(
@@ -31,14 +31,10 @@ const xml = await ctx.integrations.legacyApi.apiRequest(
   { response: z.string() },
 );
 // xml is typed string
-
-const pdf = await ctx.integrations.legacyApi.apiRequest(
-  { method: "GET", path: "/file.pdf", responseType: "binary" },
-  { response: z.instanceof(Uint8Array) },
-);
-// pdf is typed Uint8Array
 ```
 
+Do not use `z.instanceof(Uint8Array)` anywhere in an API, including the response or output schema. API code runs in a sandbox where the bytes the SDK returns are not instances of the API code's `Uint8Array`, so that check always fails. Check binary content directly in `run()` instead, for example `if (pdf.byteLength === 0) throw new Error("Empty PDF")`.
+
 Convert binary data to a JSON-safe representation before returning it from an SDK API:
 
 ```typescript

package/src/integrations/snowflakepostgres/README.md

@@ -137,9 +137,7 @@ The `query()` method requires a Zod schema for runtime validation:
 // WRONG - Missing schema parameter
 const users = await ctx.integrations.db.query(
   "SELECT * FROM users",
-  [
-    /* params */
-  ], // This is wrong - params are 3rd argument
+  [/* params */], // This is wrong - params are 3rd argument
 );
 
 // CORRECT - Schema is the second parameter