@superblocksteam/sdk-api 0.0.14 → 0.0.15-mcp.2

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/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);