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

package/src/integrations/mcpintegration/README.md

@@ -0,0 +1,147 @@
+# MCP Server Client
+
+Call tools on a remote Model Context Protocol (MCP) server through an MCP Server integration. The worker plugin runs the MCP handshake and session for every call; the SDK shapes the request and interprets the result.
+
+## Methods
+
+| Method                            | Description                                                                                   |
+| --------------------------------- | --------------------------------------------------------------------------------------------- |
+| `callTool(name, args?, options?)` | Call a tool. Returns the raw `CallToolResult`, or the validated value when `schema` is given  |
+| `listTools(options?)`             | Return every tool the server advertises, following `nextCursor` until the catalog is complete |
+
+Both methods accept `options.label` (shown in the Trace View) and `options.headers` (extra HTTP headers for that one request).
+
+## Usage
+
+### Call a tool and validate the result
+
+```typescript
+import { api, z, mcpIntegration } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const GITHUB_MCP = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+const IssueSchema = z.object({
+  number: z.number(),
+  title: z.string(),
+  state: z.string(),
+});
+
+export default api({
+  name: "SearchIssues",
+  integrations: {
+    github: mcpIntegration(GITHUB_MCP),
+  },
+  input: z.object({
+    query: z.string(),
+  }),
+  output: z.object({
+    issues: z.array(IssueSchema),
+  }),
+  async run(ctx, { query }) {
+    const result = await ctx.integrations.github.callTool(
+      "search_issues",
+      { query },
+      {
+        schema: z.object({ items: z.array(IssueSchema) }),
+        label: "Search open issues",
+      },
+    );
+
+    return { issues: result.items };
+  },
+});
+```
+
+When `schema` is given, the value validated is `structuredContent` if the server returns an object, otherwise the first `text` content block. Text that is JSON is validated as the parsed value first and as the raw string second, so `z.object(...)` works for JSON output and `z.string()` still accepts text such as `12345` or `true` as a string. Text that is not JSON is validated as a plain string. Only the first text block is used; tools that return several blocks should expose `structuredContent` or be read through the raw result.
+
+The options always go in the third argument. A call like `callTool("x", { schema })` would otherwise ship the schema to the server as tool arguments, so the client rejects a Zod schema found inside `args` with a `TypeError`.
+
+### Call a tool and read the raw result
+
+```typescript
+const result = await ctx.integrations.github.callTool("get_me");
+
+// result: { content: [{ type: "text", text: "..." }], structuredContent?, isError? }
+const text = result.content
+  .filter((block) => block.type === "text")
+  .map((block) => block.text)
+  .join("\n");
+```
+
+### List the server's tools
+
+```typescript
+const tools = await ctx.integrations.github.listTools();
+
+for (const tool of tools) {
+  console.log(tool.name, tool.description, tool.inputSchema);
+}
+```
+
+`listTools()` pages through `tools/list` until the server stops returning `nextCursor`. It throws an `IntegrationError` if a cursor repeats or the catalog does not finish within 50 pages.
+
+### Tools depend on the user
+
+The server decides which tools a user can call, from that user's credentials. The catalog seen while building the app is the builder's; an end user may have fewer tools.
+
+- Before showing a feature that needs a specific tool, call `listTools()` at runtime and show a "not available for your account" state when the tool is missing.
+- Still catch `McpToolUnavailableError` on `callTool`: the catalog can change after `listTools()`. It covers a tool the server rejects as unknown; a tool the server lists but refuses for missing permissions throws a plain `IntegrationError`.
+- In a view that combines several tools, a missing tool hides its own panel, not the whole page.
+- Results belong to the user who made the call. Cache `listTools()` and tool results per user only, never across users.
+
+```typescript
+import { McpToolUnavailableError } from "@superblocksteam/sdk-api";
+
+try {
+  return await ctx.integrations.github.callTool("list_pull_requests", {
+    state: "open",
+  });
+} catch (error) {
+  if (error instanceof McpToolUnavailableError) {
+    return { unavailable: true };
+  }
+  throw error;
+}
+```
+
+### Choosing and calling tools
+
+- Treat the integration like a REST API: call any tool the builder asks for, including tools that write.
+- Pick tools by name and description. Gateway servers namespace their tools, for example `jira_search` or `salesforce_query`.
+- Agent tools take a natural-language prompt and return markdown. Render the markdown and show a loading state, because the response arrives only when the tool finishes.
+- For chat apps, make one call per message, pass the history in, and keep the history in app storage.
+- For dashboards, call independent tools in parallel and show partial results when one source fails.
+- For search tools, keep the source links in the result and use the tool's own pagination arguments.
+
+### Per-request headers
+
+```typescript
+await ctx.integrations.github.callTool(
+  "list_repos",
+  { owner: "superblocksteam" },
+  { headers: { "Mcp-Param-Org": "superblocksteam" } },
+);
+```
+
+Headers passed here are sent in addition to the headers configured on the integration. Authentication headers come from the integration's auth settings; do not pass credentials from API code.
+
+### Sessions
+
+Some MCP servers require a handshake and a session (`Mcp-Session-Id`). The worker plugin runs that handshake and returns the session it opened; the client sends it back as headers on every later call made through the same client instance, so a run that calls several tools, or pages through `listTools()`, handshakes once. The plugin's `sessionId` and `protocolVersion` fields are removed from results before they reach API code. A header you pass yourself with the same name wins.
+
+## Errors
+
+| Situation                                             | Error thrown                                                                    |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Server rejects the tool as unknown                    | `McpToolUnavailableError` (an `IntegrationError`) with `toolName`               |
+| Server returns `isError: true`                        | `IntegrationError`; `details.cause` has `tool`, `message` and the full `result` |
+| Result does not match `schema`                        | `RestApiValidationError` with the Zod error and the data                        |
+| Result has no `structuredContent` and no `text` block | `IntegrationError` (only when a `schema` is given)                              |
+| A Zod schema is passed inside `args`                  | `TypeError`, nothing is sent                                                    |
+| `tools/list` repeats a cursor or exceeds 50 pages     | `IntegrationError`                                                              |
+| The plugin or server fails the request                | `IntegrationError` wrapping the underlying error                                |
+
+## Not supported yet
+
+Resources (`resources/list`, `resources/read`) and prompts (`prompts/list`, `prompts/get`) are not exposed by this client.

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

@@ -0,0 +1,550 @@
+/**
+ * Tests for McpClientImpl.
+ *
+ * Validates:
+ * - callTool() builds the MCP step request: a tools/call JSON-RPC request
+ *   with a params object, a per-call id, optional headers as Property
+ *   entries, and the label as trace metadata.
+ * - The session the plugin returns is sent back as headers on later calls
+ *   and on later tools/list pages, and never reaches API code.
+ * - callTool() returns the CallToolResult without a schema, validates
+ *   structuredContent or the first text block with one, and maps isError
+ *   results to IntegrationError.
+ * - listTools() follows nextCursor, rejects malformed entries, and gives up
+ *   on a repeated cursor or too many pages.
+ */
+
+import { describe, it, expect, expectTypeOf, vi } from "vitest";
+import { z } from "zod";
+
+import { RestApiValidationError } from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import type { IntegrationConfig } from "../types.js";
+import { McpClientImpl, McpToolUnavailableError } from "./client.js";
+import type { CallToolResult, McpClient } from "./types.js";
+
+const TEST_CONFIG: IntegrationConfig = {
+  id: "mcpintegration-test-id",
+  name: "Test MCP",
+  pluginId: "mcpintegration",
+  configuration: {},
+};
+
+function createClient(...results: unknown[]) {
+  const executeQuery = vi.fn();
+  for (const result of results) {
+    executeQuery.mockResolvedValueOnce(result);
+  }
+  const client = new McpClientImpl(TEST_CONFIG, executeQuery);
+  return { client, executeQuery };
+}
+
+function textResult(text: string, extra: Record<string, unknown> = {}) {
+  return { content: [{ type: "text", text }], ...extra };
+}
+
+function toolsPage(names: string[], nextCursor?: string) {
+  return {
+    tools: names.map((name) => ({ name, inputSchema: { type: "object" } })),
+    ...(nextCursor ? { nextCursor } : {}),
+  };
+}
+
+const StepHeadersSchema = z
+  .object({
+    headers: z
+      .array(z.object({ key: z.string(), value: z.string() }))
+      .optional(),
+  })
+  .passthrough();
+
+function headersOf(call: unknown[]): Record<string, string> | undefined {
+  const { headers } = StepHeadersSchema.parse(call[0]);
+  return headers
+    ? Object.fromEntries(headers.map((h) => [h.key, h.value]))
+    : undefined;
+}
+
+function integrationError(error: unknown): IntegrationError {
+  if (!(error instanceof IntegrationError)) {
+    throw error;
+  }
+  return error;
+}
+
+describe("McpClientImpl", () => {
+  describe("callTool()", () => {
+    it("sends proxied tool arguments as cloneable data", async () => {
+      const { client, executeQuery } = createClient(textResult("ok"));
+
+      await client.callTool("echo", new Proxy({ message: "hi" }, {}));
+
+      const [request] = executeQuery.mock.calls[0];
+      expect(structuredClone(request).request.params.arguments).toEqual({
+        message: "hi",
+      });
+    });
+
+    it("rejects circular tool arguments with an IntegrationError", async () => {
+      const { client, executeQuery } = createClient();
+      const args: Record<string, unknown> = {};
+      args.self = args;
+
+      const error = await client
+        .callTool("echo", args)
+        .catch((e: unknown) => e);
+
+      expect(integrationError(error).details).toMatchObject({
+        cause:
+          'Tool "echo" arguments are not JSON-serializable: the arguments object contains a circular reference',
+      });
+      expect(executeQuery).not.toHaveBeenCalled();
+    });
+
+    it("builds a tools/call request with params, headers, and label", async () => {
+      const { client, executeQuery } = createClient(
+        textResult("ok"),
+        textResult("ok"),
+      );
+
+      await client.callTool(
+        "echo",
+        { message: "hi" },
+        { label: "Echo it", headers: { "Mcp-Param-Org": "acme" } },
+      );
+      await client.callTool("echo");
+
+      const [firstRequest, firstBindings, firstMetadata] =
+        executeQuery.mock.calls[0];
+      expect(firstRequest.request.method).toBe("tools/call");
+      expect(firstRequest.request.params).toEqual({
+        name: "echo",
+        arguments: { message: "hi" },
+      });
+      expect(firstRequest.headers).toEqual([
+        { key: "Mcp-Param-Org", value: "acme" },
+      ]);
+      expect(firstRequest.clientCapabilities).toBeUndefined();
+      expect(firstBindings).toBeUndefined();
+      expect(firstMetadata).toEqual({ label: "Echo it" });
+
+      const [secondRequest, , secondMetadata] = executeQuery.mock.calls[1];
+      expect(secondRequest.request.params).toEqual({
+        name: "echo",
+        arguments: {},
+      });
+      expect(secondRequest).not.toHaveProperty("headers");
+      expect(secondMetadata).toBeUndefined();
+      expect(secondRequest.request.id).not.toEqual(firstRequest.request.id);
+    });
+
+    it("types the return as T with a schema and CallToolResult without", () => {
+      // Wrapped in arrows so the overloads resolve at compile time without
+      // invoking callTool (an unawaited call would reject and leak).
+      const { client } = createClient();
+      const viaInterface: McpClient = client;
+      const schema = z.object({ count: z.number() });
+
+      expectTypeOf(() =>
+        viaInterface.callTool("echo", {}, { schema }),
+      ).returns.resolves.toEqualTypeOf<{ count: number }>();
+      expectTypeOf(() =>
+        viaInterface.callTool("echo"),
+      ).returns.resolves.toEqualTypeOf<CallToolResult>();
+      expectTypeOf(() =>
+        client.callTool("echo", {}, { schema }),
+      ).returns.resolves.toEqualTypeOf<{ count: number }>();
+      expectTypeOf(() =>
+        client.callTool("echo"),
+      ).returns.resolves.toEqualTypeOf<CallToolResult>();
+      expectTypeOf(() =>
+        client.callTool("echo", {}, { label: "x" }),
+      ).returns.resolves.toEqualTypeOf<CallToolResult>();
+    });
+
+    it("rejects a schema passed inside the tool arguments before sending", async () => {
+      const { client, executeQuery } = createClient();
+
+      await expect(
+        client.callTool("echo", { schema: z.string() }),
+      ).rejects.toBeInstanceOf(TypeError);
+      expect(executeQuery).not.toHaveBeenCalled();
+    });
+
+    it("returns the CallToolResult without a schema, minus the plugin's session fields", async () => {
+      const { client } = createClient(
+        textResult('{"a":1}', {
+          structuredContent: { a: 1 },
+          _meta: { trace: "t1" },
+          resultType: "string",
+          sessionId: "s-1",
+          protocolVersion: "2025-06-18",
+        }),
+      );
+
+      const result = await client.callTool("echo", {});
+
+      expect(result).toEqual({
+        content: [{ type: "text", text: '{"a":1}' }],
+        structuredContent: { a: 1 },
+        _meta: { trace: "t1" },
+        resultType: "string",
+      });
+      expect(result).not.toHaveProperty("sessionId");
+      expect(result).not.toHaveProperty("protocolVersion");
+    });
+
+    it("sends the session the plugin returned back on later calls unless the caller sets one", async () => {
+      const { client, executeQuery } = createClient(
+        textResult("one", { sessionId: "s-1", protocolVersion: "2025-06-18" }),
+        textResult("two"),
+        textResult("three"),
+        textResult("four", { sessionId: "s-2" }),
+        textResult("five"),
+      );
+
+      await client.callTool("a");
+      await client.callTool("b");
+      await client.callTool("c", {}, { headers: { "mcp-session-id": "mine" } });
+      await client.callTool("d");
+      await client.callTool("e");
+
+      expect(headersOf(executeQuery.mock.calls[0])).toBeUndefined();
+      expect(headersOf(executeQuery.mock.calls[1])).toEqual({
+        "Mcp-Session-Id": "s-1",
+        "MCP-Protocol-Version": "2025-06-18",
+      });
+      expect(headersOf(executeQuery.mock.calls[2])).toEqual({
+        "mcp-session-id": "mine",
+      });
+      expect(headersOf(executeQuery.mock.calls[4])).toEqual({
+        "Mcp-Session-Id": "s-2",
+      });
+    });
+
+    it("validates structuredContent over text when both are present", async () => {
+      const { client } = createClient(
+        textResult('{"a":"text wins"}', { structuredContent: { a: "struct" } }),
+      );
+
+      const result = await client.callTool("echo", undefined, {
+        schema: z.object({ a: z.string() }),
+      });
+
+      expect(result).toEqual({ a: "struct" });
+    });
+
+    it("falls through to the text block when structuredContent is null", async () => {
+      const { client } = createClient(
+        textResult('{"a":"from text"}', { structuredContent: null }),
+      );
+
+      const result = await client.callTool("echo", undefined, {
+        schema: z.object({ a: z.string() }),
+      });
+
+      expect(result).toEqual({ a: "from text" });
+    });
+
+    it("validates the first text block parsed as JSON when there is no structuredContent", async () => {
+      const { client } = createClient({
+        content: [
+          { type: "image", data: "...", mimeType: "image/png" },
+          { type: "text", text: '{"count":2}' },
+          { type: "text", text: '{"count":"ignored"}' },
+        ],
+      });
+
+      const result = await client.callTool("echo", undefined, {
+        schema: z.object({ count: z.number() }),
+      });
+
+      expect(result).toEqual({ count: 2 });
+    });
+
+    it("validates non-JSON text as a plain string", async () => {
+      const { client } = createClient(textResult("hello world"));
+
+      const result = await client.callTool("echo", undefined, {
+        schema: z.string(),
+      });
+
+      expect(result).toBe("hello world");
+    });
+
+    it("keeps JSON-looking text as a string when the schema wants a string", async () => {
+      const { client } = createClient(textResult("12345"), textResult("12345"));
+
+      const asString = await client.callTool("echo", undefined, {
+        schema: z.string(),
+      });
+      const asNumber = await client.callTool("echo", undefined, {
+        schema: z.number(),
+      });
+
+      expect(asString).toBe("12345");
+      expect(asNumber).toBe(12345);
+    });
+
+    it("throws RestApiValidationError when the result does not match the schema", async () => {
+      const { client } = createClient(textResult('{"count":"two"}'));
+
+      await expect(
+        client.callTool("echo", undefined, {
+          schema: z.object({ count: z.number() }),
+        }),
+      ).rejects.toBeInstanceOf(RestApiValidationError);
+    });
+
+    it("throws IntegrationError when a schema is given but the result has nothing to validate", async () => {
+      const { client } = createClient({
+        content: [{ type: "image", data: "...", mimeType: "image/png" }],
+      });
+
+      const error = await client
+        .callTool("echo", undefined, { schema: z.string() })
+        .catch((e: unknown) => e);
+
+      expect(error).toBeInstanceOf(IntegrationError);
+      expect(integrationError(error).details).toMatchObject({
+        cause: expect.stringContaining('Tool "echo"'),
+      });
+    });
+
+    it("throws IntegrationError naming the tool and carrying the result when isError is set", async () => {
+      const { client } = createClient({
+        content: [
+          { type: "text", text: "rate limited" },
+          { type: "image", data: "...", mimeType: "image/png" },
+          { type: "text", text: "retry later" },
+        ],
+        isError: true,
+      });
+
+      const error = await client
+        .callTool("echo", {}, { schema: z.string() })
+        .catch((e: unknown) => e);
+
+      expect(error).toBeInstanceOf(IntegrationError);
+      expect(integrationError(error).operation).toBe("callTool");
+      expect(integrationError(error).details).toMatchObject({
+        cause: {
+          tool: "echo",
+          message: 'Tool "echo" failed: rate limited\nretry later',
+          result: { isError: true, content: expect.any(Array) },
+        },
+      });
+      const details = z
+        .object({
+          cause: z.object({
+            result: z.object({ content: z.array(z.unknown()) }),
+          }),
+        })
+        .parse(integrationError(error).details);
+      expect(details.cause.result.content).toHaveLength(3);
+    });
+
+    it("throws IntegrationError when the response is not a CallToolResult", async () => {
+      const { client } = createClient({ tools: [] });
+
+      await expect(client.callTool("echo")).rejects.toBeInstanceOf(
+        IntegrationError,
+      );
+    });
+
+    it("wraps executeQuery failures in IntegrationError", async () => {
+      const executeQuery = vi.fn().mockRejectedValue(new Error("boom"));
+      const client = new McpClientImpl(TEST_CONFIG, executeQuery);
+
+      const error = await client.callTool("echo").catch((e: unknown) => e);
+
+      expect(error).toBeInstanceOf(IntegrationError);
+      expect(integrationError(error).details).toMatchObject({
+        operation: "callTool",
+        cause: new Error("boom"),
+      });
+    });
+
+    it.each([
+      "MCP server returned error -32602 for tools/call: MCP error -32602: Tool create_issue not found",
+      "MCP server returned error -32602 for tools/call: Unknown tool: create_issue",
+      "MCP server returned error -32601 for tools/call: MCP error -32601: Unknown tool: create_issue",
+    ])(
+      "throws McpToolUnavailableError when the server rejects the tool: %s",
+      async (message) => {
+        const executeQuery = vi.fn().mockRejectedValue(new Error(message));
+        const client = new McpClientImpl(TEST_CONFIG, executeQuery);
+
+        const error = await client
+          .callTool("create_issue")
+          .catch((e: unknown) => e);
+
+        expect(error).toBeInstanceOf(McpToolUnavailableError);
+        expect(error).toBeInstanceOf(IntegrationError);
+        expect(error).toMatchObject({
+          name: "McpToolUnavailableError",
+          message:
+            'Tool "create_issue" is not available on integration "Test MCP"',
+          toolName: "create_issue",
+          integrationName: "Test MCP",
+        });
+      },
+    );
+
+    it("throws McpToolUnavailableError when an isError result names an unknown tool", async () => {
+      const { client } = createClient(
+        textResult("Unknown tool: create_issue", { isError: true }),
+      );
+
+      await expect(client.callTool("create_issue")).rejects.toBeInstanceOf(
+        McpToolUnavailableError,
+      );
+    });
+
+    it.each([
+      "Tool execution failed: issue not found",
+      "Unknown tool: other_tool",
+    ])(
+      "keeps an isError result that does not name the called tool as IntegrationError: %s",
+      async (text) => {
+        const { client } = createClient(textResult(text, { isError: true }));
+
+        const error = await client
+          .callTool("get_issue")
+          .catch((e: unknown) => e);
+
+        expect(error).toBeInstanceOf(IntegrationError);
+        expect(error).not.toBeInstanceOf(McpToolUnavailableError);
+      },
+    );
+
+    it("keeps other -32602 errors as IntegrationError", async () => {
+      const executeQuery = vi
+        .fn()
+        .mockRejectedValue(
+          new Error(
+            "MCP server returned error -32602 for tools/call: Invalid arguments for tool create_issue",
+          ),
+        );
+      const client = new McpClientImpl(TEST_CONFIG, executeQuery);
+
+      const error = await client
+        .callTool("create_issue")
+        .catch((e: unknown) => e);
+
+      expect(error).toBeInstanceOf(IntegrationError);
+      expect(error).not.toBeInstanceOf(McpToolUnavailableError);
+    });
+  });
+
+  describe("listTools()", () => {
+    it("follows nextCursor, concatenates every page, and reuses the session from page 1", async () => {
+      const { client, executeQuery } = createClient(
+        { ...toolsPage(["a"], "c1"), sessionId: "s-1" },
+        toolsPage(["b"], "c2"),
+        toolsPage(["c"]),
+      );
+
+      const tools = await client.listTools({ headers: { "X-Org": "acme" } });
+
+      expect(tools.map((t) => t.name)).toEqual(["a", "b", "c"]);
+      expect(executeQuery).toHaveBeenCalledTimes(3);
+      const params = executeQuery.mock.calls.map(
+        (call) => call[0].request.params,
+      );
+      expect(params).toEqual([{}, { cursor: "c1" }, { cursor: "c2" }]);
+      for (const call of executeQuery.mock.calls) {
+        expect(call[0].request.method).toBe("tools/list");
+      }
+      expect(headersOf(executeQuery.mock.calls[0])).toEqual({
+        "X-Org": "acme",
+      });
+      expect(headersOf(executeQuery.mock.calls[1])).toEqual({
+        "Mcp-Session-Id": "s-1",
+        "X-Org": "acme",
+      });
+    });
+
+    it("throws IntegrationError when the server repeats a cursor", async () => {
+      const { client, executeQuery } = createClient(
+        toolsPage([], "loop"),
+        toolsPage([], "loop"),
+      );
+
+      await expect(client.listTools()).rejects.toBeInstanceOf(IntegrationError);
+      expect(executeQuery).toHaveBeenCalledTimes(2);
+    });
+
+    it("gives up after 50 pages of fresh cursors", async () => {
+      let page = 0;
+      const executeQuery = vi
+        .fn()
+        .mockImplementation(async () => toolsPage([`t${page}`], `c${++page}`));
+      const client = new McpClientImpl(TEST_CONFIG, executeQuery);
+
+      const error = await client.listTools().catch((e: unknown) => e);
+
+      expect(error).toBeInstanceOf(IntegrationError);
+      expect(integrationError(error).details).toMatchObject({
+        cause: expect.stringContaining("50 pages"),
+      });
+      expect(executeQuery).toHaveBeenCalledTimes(50);
+    });
+
+    it("treats optional fields sent as null like absent ones", async () => {
+      const { client } = createClient(
+        {
+          tools: [
+            {
+              name: "a",
+              description: null,
+              title: null,
+              inputSchema: { type: "object", properties: null, required: null },
+              annotations: null,
+              _meta: null,
+            },
+          ],
+          nextCursor: null,
+        },
+        {
+          content: [
+            { type: "text", text: "ok" },
+            { type: "image", text: null },
+          ],
+          structuredContent: null,
+          isError: null,
+          _meta: null,
+          sessionId: null,
+          protocolVersion: null,
+        },
+      );
+
+      const tools = await client.listTools();
+      const result = await client.callTool("a");
+
+      expect(tools).toEqual([{ name: "a", inputSchema: { type: "object" } }]);
+      expect(result).toEqual({
+        content: [{ type: "text", text: "ok" }, { type: "image" }],
+      });
+    });
+
+    it("throws IntegrationError when a tool entry is malformed", async () => {
+      const { client } = createClient({
+        tools: [{ name: "ok", inputSchema: { type: "object" } }, { name: 42 }],
+      });
+
+      const error = await client.listTools().catch((e: unknown) => e);
+
+      expect(error).toBeInstanceOf(IntegrationError);
+      expect(integrationError(error).details).toMatchObject({
+        cause: expect.stringContaining("tools.1.name"),
+      });
+    });
+
+    it("throws IntegrationError when the response has no tools array", async () => {
+      const { client } = createClient(textResult("not a list"));
+
+      await expect(client.listTools()).rejects.toBeInstanceOf(IntegrationError);
+    });
+  });
+});