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

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

@@ -0,0 +1,588 @@
+/**
+ * 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: expect.stringContaining("create_issue"),
+          toolName: "create_issue",
+          integrationName: "Test MCP",
+        });
+        expect(error).toHaveProperty(
+          "message",
+          expect.stringContaining("Test MCP"),
+        );
+      },
+    );
+
+    it("throws McpToolUnavailableError when an isError result names an unknown tool", async () => {
+      const { client } = createClient(
+        textResult("Unknown tool: create_issue", { isError: true }),
+      );
+
+      const error = await client
+        .callTool("create_issue")
+        .catch((e: unknown) => e);
+
+      expect(error).toBeInstanceOf(McpToolUnavailableError);
+      expect(integrationError(error).details).toMatchObject({
+        cause: {
+          tool: "create_issue",
+          message: "Unknown tool: create_issue",
+          result: { isError: true, content: expect.any(Array) },
+        },
+      });
+    });
+
+    it.each([
+      "Tool execution failed: issue not found",
+      "Unknown tool: other_tool",
+      "Unknown tool: get_issue-v2",
+      "Unknown tool: get_issue.v2",
+    ])(
+      "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.each([
+      [
+        "create_issue",
+        "MCP server returned error -32602 for tools/call: Invalid arguments for tool create_issue",
+      ],
+      [
+        "create_issue",
+        "MCP server returned error -32603 for tools/call: Unknown tool: create_issue",
+      ],
+      [
+        "search.v2",
+        "MCP server returned error -32602 for tools/call: Unknown tool: search_v2",
+      ],
+    ])(
+      "keeps other tools/call errors for %s as IntegrationError: %s",
+      async (tool, message) => {
+        const executeQuery = vi.fn().mockRejectedValue(new Error(message));
+        const client = new McpClientImpl(TEST_CONFIG, executeQuery);
+
+        const error = await client.callTool(tool).catch((e: unknown) => e);
+
+        expect(error).toBeInstanceOf(IntegrationError);
+        expect(error).not.toBeInstanceOf(McpToolUnavailableError);
+      },
+    );
+
+    it("keeps a listTools failure with unknown-tool wording as IntegrationError", async () => {
+      const executeQuery = vi
+        .fn()
+        .mockRejectedValue(
+          new Error(
+            "MCP server returned error -32602 for tools/call: Unknown tool: x",
+          ),
+        );
+      const client = new McpClientImpl(TEST_CONFIG, executeQuery);
+
+      const error = await client.listTools().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);
+    });
+  });
+});