@illuma-ai/agents 1.3.1 → 1.4.0-alpha.0

package/src/providers/mcp/__tests__/MCPCapabilityProvider.integration.spec.ts

@@ -0,0 +1,386 @@
+/**
+ * Integration test — exercises MCPCapabilityProvider against a local HTTP
+ * server that speaks the MCP Streamable HTTP protocol.
+ *
+ * The server is a minimal pure-http harness implementing just the subset of
+ * JSON-RPC methods the test needs (`initialize`, `tools/list`, `tools/call`).
+ * We deliberately avoid importing the MCP SDK's server module here because
+ * (a) the SDK's server-side depends on ajv validation which clashes with
+ * the project-wide ajv@6 override, and (b) the integration surface we care
+ * about is the CLIENT path — connecting, listing, invoking. The client
+ * doesn't know whether the server is built on the SDK or not.
+ *
+ * This exercises:
+ *   - transport selection (streamable-http)
+ *   - initialize → listTools → callTool flow through our provider
+ *   - auth header forwarding from getAuthHeaders
+ *   - the three config-source patterns (direct / YAML-derived / marketplace)
+ *     producing equivalent capability behavior
+ */
+
+import { createServer, type Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+import {
+  MCPCapabilityProvider,
+  formatCapabilityName,
+} from '../MCPCapabilityProvider';
+import { CapabilityKind } from '../../types';
+import type { MCPServerSpec } from '../types';
+
+// ---------------------------------------------------------------------------
+// Minimal MCP HTTP harness — dispatches JSON-RPC requests synchronously.
+// ---------------------------------------------------------------------------
+
+interface Harness {
+  url: string;
+  httpServer: HttpServer;
+  lastHeaders: Record<string, string>;
+  close: () => Promise<void>;
+}
+
+interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id: string | number;
+  method: string;
+  params?: unknown;
+}
+
+interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  result?: unknown;
+  error?: { code: number; message: string };
+}
+
+const TOOLS_FIXTURE = [
+  {
+    name: 'echo',
+    description: 'Return the input string back.',
+    inputSchema: {
+      type: 'object',
+      properties: { message: { type: 'string' } },
+      required: ['message'],
+    },
+  },
+  {
+    name: 'fail',
+    description: 'Always returns an error result.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+function handleRpc(req: JsonRpcRequest): JsonRpcResponse {
+  const base = { jsonrpc: '2.0' as const, id: req.id };
+
+  switch (req.method) {
+    case 'initialize':
+      return {
+        ...base,
+        result: {
+          protocolVersion: '2024-11-05',
+          capabilities: { tools: {} },
+          serverInfo: { name: 'test-server', version: '0.0.1' },
+        },
+      };
+
+    case 'tools/list':
+      return { ...base, result: { tools: TOOLS_FIXTURE } };
+
+    case 'tools/call': {
+      const params = req.params as {
+        name: string;
+        arguments?: Record<string, unknown>;
+      };
+      if (params.name === 'echo') {
+        const message = (params.arguments?.message as string) ?? '';
+        return {
+          ...base,
+          result: { content: [{ type: 'text', text: message }] },
+        };
+      }
+      if (params.name === 'fail') {
+        return {
+          ...base,
+          result: {
+            content: [{ type: 'text', text: 'intentional failure' }],
+            isError: true,
+          },
+        };
+      }
+      return {
+        ...base,
+        error: { code: -32601, message: `Unknown tool: ${params.name}` },
+      };
+    }
+
+    default:
+      // Notifications (e.g., notifications/initialized) have no `id`;
+      // per JSON-RPC we return no response for those. Here we always have
+      // an id because we only dispatch regular requests.
+      return {
+        ...base,
+        error: { code: -32601, message: `Method not found: ${req.method}` },
+      };
+  }
+}
+
+async function startLocalMCPServer(
+  opts: { requireAuth?: boolean } = {}
+): Promise<Harness> {
+  const lastHeaders: Record<string, string> = {};
+
+  const httpServer = createServer(async (req, res) => {
+    // Capture headers for auth-forwarding assertions.
+    for (const [k, v] of Object.entries(req.headers)) {
+      if (typeof v === 'string') lastHeaders[k.toLowerCase()] = v;
+    }
+
+    if (req.method !== 'POST') {
+      res.writeHead(405);
+      res.end();
+      return;
+    }
+
+    if (opts.requireAuth) {
+      const auth = req.headers['authorization'];
+      if (typeof auth !== 'string' || !auth.startsWith('Bearer ')) {
+        res.writeHead(401, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: 'unauthorized' }));
+        return;
+      }
+    }
+
+    const chunks: Buffer[] = [];
+    for await (const chunk of req) chunks.push(chunk as Buffer);
+    const body = Buffer.concat(chunks).toString('utf8');
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      res.writeHead(400, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: 'invalid JSON' }));
+      return;
+    }
+
+    // Handle either a single request or a batch (always a single for our client).
+    const reqs = Array.isArray(parsed)
+      ? (parsed as JsonRpcRequest[])
+      : [parsed as JsonRpcRequest];
+
+    // Notifications (no id) get no response
+    const responses: JsonRpcResponse[] = [];
+    for (const r of reqs) {
+      if (r.id === undefined) continue;
+      responses.push(handleRpc(r));
+    }
+
+    if (responses.length === 0) {
+      res.writeHead(202);
+      res.end();
+      return;
+    }
+
+    const payload = Array.isArray(parsed) ? responses : responses[0];
+    res.writeHead(200, {
+      'content-type': 'application/json',
+      // Streamable HTTP transport requires a session id header.
+      'mcp-session-id': 'test-session',
+    });
+    res.end(JSON.stringify(payload));
+  });
+
+  await new Promise<void>((resolve) =>
+    httpServer.listen(0, '127.0.0.1', resolve)
+  );
+  const port = (httpServer.address() as AddressInfo).port;
+  const url = `http://127.0.0.1:${port}/mcp`;
+
+  return {
+    url,
+    httpServer,
+    lastHeaders,
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        httpServer.close((err) => (err ? reject(err) : resolve()));
+      }),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('MCPCapabilityProvider (live streamable-http)', () => {
+  let harness: Harness;
+  let provider: MCPCapabilityProvider;
+
+  beforeAll(async () => {
+    harness = await startLocalMCPServer();
+  });
+
+  afterAll(async () => {
+    await provider?.close();
+    await harness.close();
+  });
+
+  it('connects and discovers tools from a live server', async () => {
+    const spec: MCPServerSpec = {
+      type: 'streamable-http',
+      url: harness.url,
+    };
+
+    provider = new MCPCapabilityProvider({
+      servers: { test: spec },
+    });
+
+    const capabilities = await provider.fetchManifest();
+    const names = capabilities.map((c) => c.name).sort();
+    expect(names).toEqual([
+      formatCapabilityName('test', 'echo'),
+      formatCapabilityName('test', 'fail'),
+    ]);
+    expect(capabilities[0].kind).toBe(CapabilityKind.MCP);
+  });
+
+  it('invokes a tool end-to-end and returns text', async () => {
+    const caps = await provider.fetchManifest({
+      names: [formatCapabilityName('test', 'echo')],
+    });
+    expect(caps).toHaveLength(1);
+
+    const [runnable] = await provider.createRunnables(caps, {});
+    const result = await runnable.invoke({ message: 'hello world' });
+    expect(result).toBe('hello world');
+  });
+
+  it('surfaces isError from the server as a thrown error', async () => {
+    const caps = await provider.fetchManifest({
+      names: [formatCapabilityName('test', 'fail')],
+    });
+    const [runnable] = await provider.createRunnables(caps, {});
+    await expect(runnable.invoke({})).rejects.toThrow(
+      /test:fail.*intentional failure/
+    );
+  });
+});
+
+describe('MCPCapabilityProvider — auth header forwarding', () => {
+  let harness: Harness;
+  let provider: MCPCapabilityProvider;
+
+  beforeAll(async () => {
+    harness = await startLocalMCPServer({ requireAuth: true });
+  });
+
+  afterAll(async () => {
+    await provider?.close();
+    await harness.close();
+  });
+
+  it('rejects without auth (server returns 401 → empty manifest)', async () => {
+    provider = new MCPCapabilityProvider({
+      servers: { secure: { type: 'streamable-http', url: harness.url } },
+    });
+    const caps = await provider.fetchManifest();
+    expect(caps).toEqual([]);
+  });
+
+  it('succeeds when getAuthHeaders supplies a Bearer token', async () => {
+    provider = new MCPCapabilityProvider({
+      servers: { secure: { type: 'streamable-http', url: harness.url } },
+      getAuthHeaders: () => ({ Authorization: 'Bearer test-token-123' }),
+    });
+    const caps = await provider.fetchManifest();
+    expect(caps.length).toBeGreaterThan(0);
+    expect(harness.lastHeaders['authorization']).toBe('Bearer test-token-123');
+  });
+});
+
+describe('MCPCapabilityProvider — config-source patterns', () => {
+  let harness: Harness;
+
+  beforeAll(async () => {
+    harness = await startLocalMCPServer();
+  });
+
+  afterAll(async () => {
+    await harness.close();
+  });
+
+  const verifyProviderWorks = async (
+    p: MCPCapabilityProvider
+  ): Promise<void> => {
+    const caps = await p.fetchManifest();
+    expect(caps.length).toBeGreaterThan(0);
+    const echoCap = caps.find((c) => c.name.endsWith('echo'));
+    expect(echoCap).toBeDefined();
+    const [runnable] = await p.createRunnables([echoCap!], {});
+    const result = await runnable.invoke({ message: 'ok' });
+    expect(result).toBe('ok');
+    await p.close();
+  };
+
+  it('direct programmatic spec', async () => {
+    const p = new MCPCapabilityProvider({
+      servers: {
+        mine: { type: 'streamable-http', url: harness.url },
+      },
+    });
+    await verifyProviderWorks(p);
+  });
+
+  it('YAML-derived spec (simulated)', async () => {
+    // The host parses YAML and normalizes entries into the spec shape
+    // before constructing the provider.
+    const yamlLike = {
+      mcp_servers: [
+        {
+          name: 'from-yaml',
+          type: 'streamable-http',
+          url: harness.url,
+        },
+      ],
+    };
+
+    const servers: Record<string, MCPServerSpec> = {};
+    for (const entry of yamlLike.mcp_servers) {
+      servers[entry.name] = {
+        type: entry.type as 'streamable-http',
+        url: entry.url,
+      };
+    }
+
+    const p = new MCPCapabilityProvider({ servers });
+    await verifyProviderWorks(p);
+  });
+
+  it('marketplace-catalog-derived spec (simulated)', async () => {
+    // The host fetched a catalog entry, populated auth via its own token
+    // store, and assembled the spec.
+    const marketplaceEntry = {
+      id: 'market-echo',
+      name: 'Market Echo',
+      transport: 'streamable-http' as const,
+      url: harness.url,
+      authConfig: [{ authField: 'MCP_MARKET_TOKEN', required: true }],
+    };
+
+    const servers: Record<string, MCPServerSpec> = {
+      [marketplaceEntry.id]: {
+        type: marketplaceEntry.transport,
+        url: marketplaceEntry.url,
+      },
+    };
+
+    const p = new MCPCapabilityProvider({
+      servers,
+      getAuthHeaders: () => ({
+        // Host injected from its credential store — the library doesn't know.
+        'x-market-token': 'resolved-by-host',
+      }),
+    });
+    await verifyProviderWorks(p);
+  });
+});