@illuma-ai/agents 1.3.2 → 1.4.0-alpha.1

package/src/providers/mcp/__tests__/MCPCapabilityProvider.test.ts

@@ -0,0 +1,371 @@
+/**
+ * Unit tests for MCPCapabilityProvider.
+ *
+ * Uses mocked MCP SDK clients + transports so the provider can be exercised
+ * without spinning up a real server. The integration test file covers the
+ * live streamable-HTTP path.
+ */
+
+import {
+  CAPABILITY_NAME_SEPARATOR,
+  formatCapabilityName,
+  flattenToolCallResponse,
+  MCPCapabilityProvider,
+} from '../MCPCapabilityProvider';
+import { CapabilityKind } from '../../types';
+
+// ---------------------------------------------------------------------------
+// SDK mocks — jest.mock replaces the MCP SDK with lightweight stubs so we
+// can script connect() / listTools() / callTool() behavior per test.
+// ---------------------------------------------------------------------------
+
+const clientConnect = jest.fn();
+const clientListTools = jest.fn();
+const clientCallTool = jest.fn();
+const clientClose = jest.fn();
+
+jest.mock('@modelcontextprotocol/sdk/client/index.js', () => ({
+  Client: jest.fn().mockImplementation(() => ({
+    connect: clientConnect,
+    listTools: clientListTools,
+    callTool: clientCallTool,
+    close: clientClose,
+  })),
+}));
+
+jest.mock('../transport', () => ({
+  createTransport: jest
+    .fn()
+    .mockImplementation(() => ({ __stub: 'transport' })),
+}));
+
+const resetMocks = (): void => {
+  clientConnect.mockReset();
+  clientListTools.mockReset();
+  clientCallTool.mockReset();
+  clientClose.mockReset();
+  clientConnect.mockResolvedValue(undefined);
+  clientClose.mockResolvedValue(undefined);
+};
+
+beforeEach(resetMocks);
+
+// ---------------------------------------------------------------------------
+// Helpers exported from the provider
+// ---------------------------------------------------------------------------
+
+describe('helpers', () => {
+  it('formatCapabilityName joins server + tool with separator', () => {
+    expect(formatCapabilityName('gh', 'list_repos')).toBe(
+      `gh${CAPABILITY_NAME_SEPARATOR}list_repos`
+    );
+  });
+
+  describe('flattenToolCallResponse', () => {
+    it('concatenates text content parts', () => {
+      const r = flattenToolCallResponse({
+        content: [
+          { type: 'text', text: 'hello' },
+          { type: 'text', text: 'world' },
+        ],
+      });
+      expect(r.text).toBe('hello\n\nworld');
+      expect(r.isError).toBe(false);
+    });
+
+    it('serializes non-text parts as JSON', () => {
+      const r = flattenToolCallResponse({
+        content: [
+          { type: 'text', text: 'x' },
+          { type: 'image', data: 'abc', mimeType: 'image/png' },
+        ],
+      });
+      expect(r.text).toContain('x');
+      expect(r.text).toContain('"image"');
+    });
+
+    it('reports isError when the SDK flags it', () => {
+      const r = flattenToolCallResponse({
+        content: [{ type: 'text', text: 'boom' }],
+        isError: true,
+      });
+      expect(r.isError).toBe(true);
+      expect(r.text).toBe('boom');
+    });
+
+    it('handles empty / missing content', () => {
+      expect(flattenToolCallResponse({}).text).toBe('(empty response)');
+      expect(flattenToolCallResponse(null).text).toBe('(empty response)');
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Construction
+// ---------------------------------------------------------------------------
+
+describe('MCPCapabilityProvider construction', () => {
+  it('rejects empty server map', () => {
+    expect(() => new MCPCapabilityProvider({ servers: {} })).toThrow(
+      /at least one server/
+    );
+  });
+
+  it('providerId includes sorted server names', () => {
+    const p = new MCPCapabilityProvider({
+      servers: {
+        zeta: { type: 'stdio', command: 'x' },
+        alpha: { type: 'stdio', command: 'y' },
+      },
+    });
+    expect(p.providerId).toBe('mcp:alpha,zeta');
+  });
+
+  it('applies env-var defaults when clientInfo omitted', () => {
+    const prev = process.env.MCP_CLIENT_NAME;
+    process.env.MCP_CLIENT_NAME = 'from-env';
+    try {
+      const p = new MCPCapabilityProvider({
+        servers: { s: { type: 'stdio', command: 'echo' } },
+      });
+      // Exposing this via constructor args is sufficient — we tested the
+      // env read path in getMCPEnvDefaults indirectly.
+      expect(p.providerId).toContain('s');
+    } finally {
+      if (prev === undefined) delete process.env.MCP_CLIENT_NAME;
+      else process.env.MCP_CLIENT_NAME = prev;
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// fetchManifest
+// ---------------------------------------------------------------------------
+
+describe('fetchManifest', () => {
+  it('returns capabilities for all tools from a single server', async () => {
+    clientListTools.mockResolvedValue({
+      tools: [
+        { name: 'search', description: 'Search docs' },
+        {
+          name: 'get',
+          description: 'Get a doc',
+          inputSchema: { type: 'object' },
+        },
+      ],
+    });
+
+    const p = new MCPCapabilityProvider({
+      servers: { docs: { type: 'streamable-http', url: 'http://x' } },
+    });
+    const caps = await p.fetchManifest();
+
+    expect(caps).toHaveLength(2);
+    expect(caps[0].kind).toBe(CapabilityKind.MCP);
+    expect(caps[0].name).toBe(formatCapabilityName('docs', 'search'));
+    expect(caps[0].metadata.tags).toEqual(['docs']);
+    expect(caps[1].schema).toEqual({ type: 'object' });
+  });
+
+  it('merges tools from multiple servers', async () => {
+    clientListTools
+      .mockResolvedValueOnce({ tools: [{ name: 't1' }] })
+      .mockResolvedValueOnce({ tools: [{ name: 't2' }] });
+
+    const p = new MCPCapabilityProvider({
+      servers: {
+        a: { type: 'stdio', command: 'x' },
+        b: { type: 'stdio', command: 'y' },
+      },
+    });
+    const caps = await p.fetchManifest();
+
+    const names = caps.map((c) => c.name).sort();
+    expect(names).toEqual([
+      formatCapabilityName('a', 't1'),
+      formatCapabilityName('b', 't2'),
+    ]);
+  });
+
+  it('continues when one server fails', async () => {
+    clientListTools
+      .mockRejectedValueOnce(new Error('boom'))
+      .mockResolvedValueOnce({ tools: [{ name: 'ok' }] });
+
+    const p = new MCPCapabilityProvider({
+      servers: {
+        broken: { type: 'stdio', command: 'x' },
+        good: { type: 'stdio', command: 'y' },
+      },
+    });
+    const caps = await p.fetchManifest();
+
+    expect(caps).toHaveLength(1);
+    expect(caps[0].name).toBe(formatCapabilityName('good', 'ok'));
+  });
+
+  it('short-circuits when filter excludes mcp kind', async () => {
+    const p = new MCPCapabilityProvider({
+      servers: { s: { type: 'stdio', command: 'x' } },
+    });
+    const caps = await p.fetchManifest({ kind: CapabilityKind.TOOL });
+    expect(caps).toEqual([]);
+    expect(clientConnect).not.toHaveBeenCalled();
+  });
+
+  it('applies name filter', async () => {
+    clientListTools.mockResolvedValue({
+      tools: [{ name: 't1' }, { name: 't2' }, { name: 't3' }],
+    });
+
+    const p = new MCPCapabilityProvider({
+      servers: { s: { type: 'stdio', command: 'x' } },
+    });
+    const caps = await p.fetchManifest({
+      names: [formatCapabilityName('s', 't2')],
+    });
+    expect(caps).toHaveLength(1);
+    expect(caps[0].name).toContain('t2');
+  });
+
+  it('calls getAuthHeaders once per server before connect', async () => {
+    clientListTools.mockResolvedValue({ tools: [] });
+    const getAuthHeaders = jest
+      .fn()
+      .mockResolvedValue({ Authorization: 'Bearer xyz' });
+
+    const p = new MCPCapabilityProvider({
+      servers: { s: { type: 'streamable-http', url: 'http://x' } },
+      getAuthHeaders,
+    });
+    await p.fetchManifest();
+
+    expect(getAuthHeaders).toHaveBeenCalledTimes(1);
+    expect(getAuthHeaders).toHaveBeenCalledWith('s');
+  });
+
+  it('caches connections across fetchManifest calls', async () => {
+    clientListTools.mockResolvedValue({ tools: [{ name: 't' }] });
+
+    const p = new MCPCapabilityProvider({
+      servers: { s: { type: 'stdio', command: 'x' } },
+    });
+    await p.fetchManifest();
+    await p.fetchManifest();
+
+    expect(clientConnect).toHaveBeenCalledTimes(1);
+    expect(clientListTools).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createRunnables
+// ---------------------------------------------------------------------------
+
+describe('createRunnables', () => {
+  it('builds one StructuredTool per MCP capability', async () => {
+    clientListTools.mockResolvedValue({
+      tools: [{ name: 'a' }, { name: 'b' }],
+    });
+
+    const p = new MCPCapabilityProvider({
+      servers: { s: { type: 'stdio', command: 'x' } },
+    });
+    const caps = await p.fetchManifest();
+    const runnables = await p.createRunnables(caps, {});
+
+    expect(runnables).toHaveLength(2);
+    expect(runnables[0].name).toBe(formatCapabilityName('s', 'a'));
+    expect(runnables[1].name).toBe(formatCapabilityName('s', 'b'));
+  });
+
+  it('skips non-MCP capabilities', async () => {
+    clientListTools.mockResolvedValue({ tools: [] });
+    const p = new MCPCapabilityProvider({
+      servers: { s: { type: 'stdio', command: 'x' } },
+    });
+    const runnables = await p.createRunnables(
+      [
+        {
+          kind: CapabilityKind.TOOL,
+          name: 'not_mine',
+          description: 'other',
+          authConfig: [],
+          metadata: {},
+        },
+      ],
+      {}
+    );
+    expect(runnables).toHaveLength(0);
+  });
+
+  it('proxy tool invokes client.callTool with the parsed tool name', async () => {
+    clientListTools.mockResolvedValue({ tools: [{ name: 'search' }] });
+    clientCallTool.mockResolvedValue({
+      content: [{ type: 'text', text: 'found 3 results' }],
+    });
+
+    const p = new MCPCapabilityProvider({
+      servers: { docs: { type: 'streamable-http', url: 'http://x' } },
+    });
+    const caps = await p.fetchManifest();
+    const [runnable] = await p.createRunnables(caps, {});
+
+    const result = await runnable.invoke({ query: 'hello' });
+    expect(result).toBe('found 3 results');
+    expect(clientCallTool).toHaveBeenCalledWith({
+      name: 'search',
+      arguments: { query: 'hello' },
+    });
+  });
+
+  it('proxy tool throws when MCP returns isError=true', async () => {
+    clientListTools.mockResolvedValue({ tools: [{ name: 'fail' }] });
+    clientCallTool.mockResolvedValue({
+      content: [{ type: 'text', text: 'nope' }],
+      isError: true,
+    });
+
+    const p = new MCPCapabilityProvider({
+      servers: { s: { type: 'stdio', command: 'x' } },
+    });
+    const [runnable] = await p.createRunnables(await p.fetchManifest(), {});
+    await expect(runnable.invoke({})).rejects.toThrow(/s:fail.*nope/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// close
+// ---------------------------------------------------------------------------
+
+describe('close', () => {
+  it('closes all open connections', async () => {
+    clientListTools.mockResolvedValue({ tools: [] });
+
+    const p = new MCPCapabilityProvider({
+      servers: {
+        a: { type: 'stdio', command: 'x' },
+        b: { type: 'stdio', command: 'y' },
+      },
+    });
+    await p.fetchManifest();
+    await p.close();
+
+    expect(clientClose).toHaveBeenCalledTimes(2);
+  });
+
+  it('is idempotent if a close throws', async () => {
+    clientListTools.mockResolvedValue({ tools: [] });
+    clientClose.mockRejectedValueOnce(new Error('bad close'));
+    clientClose.mockResolvedValueOnce(undefined);
+
+    const p = new MCPCapabilityProvider({
+      servers: {
+        a: { type: 'stdio', command: 'x' },
+        b: { type: 'stdio', command: 'y' },
+      },
+    });
+    await p.fetchManifest();
+    await expect(p.close()).resolves.toBeUndefined();
+  });
+});

package/src/providers/mcp/config.ts

@@ -0,0 +1,45 @@
+/**
+ * Environment-driven configuration defaults for the MCP capability provider.
+ *
+ * Hosts can override any of these via the provider config object. Env vars
+ * exist so deployments can brand or tune the library without code changes.
+ */
+
+import type { MCPLogger } from './types';
+
+/**
+ * Read env values with fallbacks. Kept as a function (not a constant) so
+ * tests and hosts that mutate process.env after import get the current
+ * value on each call.
+ */
+export function getMCPEnvDefaults(): {
+  clientName: string;
+  clientVersion: string;
+  connectTimeoutMs: number;
+  requestTimeoutMs: number;
+} {
+  return {
+    /**
+     * Identity sent to MCP servers on handshake. Precedence:
+     *   1. explicit `clientInfo.name` on the provider config
+     *   2. `MCP_CLIENT_NAME` env var
+     *   3. library fallback identity
+     */
+    clientName: process.env.MCP_CLIENT_NAME ?? 'illuma-agents',
+    clientVersion: process.env.MCP_CLIENT_VERSION ?? '1.0.0',
+    connectTimeoutMs: Number(process.env.MCP_CONNECT_TIMEOUT_MS ?? 30_000),
+    requestTimeoutMs: Number(process.env.MCP_REQUEST_TIMEOUT_MS ?? 30_000),
+  };
+}
+
+/** Console-routed default logger. */
+export const consoleLogger: MCPLogger = {
+  // eslint-disable-next-line no-console
+  debug: (...args) => console.debug('[mcp]', ...args),
+  // eslint-disable-next-line no-console
+  info: (...args) => console.info('[mcp]', ...args),
+  // eslint-disable-next-line no-console
+  warn: (...args) => console.warn('[mcp]', ...args),
+  // eslint-disable-next-line no-console
+  error: (...args) => console.error('[mcp]', ...args),
+};

package/src/providers/mcp/index.ts

@@ -0,0 +1,21 @@
+export { MCPCapabilityProvider } from './MCPCapabilityProvider';
+export {
+  CAPABILITY_NAME_SEPARATOR,
+  formatCapabilityName,
+  flattenToolCallResponse,
+} from './MCPCapabilityProvider';
+export { createTransport } from './transport';
+export { consoleLogger as mcpConsoleLogger, getMCPEnvDefaults } from './config';
+export type {
+  MCPLogger,
+  MCPProviderConfig,
+  MCPServerSpec,
+  MCPTransportKind,
+  StdioSpec,
+  SSESpec,
+  StreamableHTTPSpec,
+  WebSocketSpec,
+  MCPToolDescriptor,
+  MCPToolCallResult,
+  MCPStructuredTool,
+} from './types';

package/src/providers/mcp/transport.ts

@@ -0,0 +1,76 @@
+/**
+ * Transport factory — turns an `MCPServerSpec` into a configured
+ * MCP SDK transport. One switch statement per kind.
+ *
+ * Each transport is constructed with the merged header map (spec headers
+ * plus any `getAuthHeaders`-resolved additions) for HTTP-based kinds.
+ * Stdio uses `env` + `command` + `args` directly.
+ */
+
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { WebSocketClientTransport } from '@modelcontextprotocol/sdk/client/websocket.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+
+import type { MCPServerSpec } from './types';
+
+/**
+ * Build a Transport from a spec + resolved auth headers.
+ *
+ * @param spec - the server spec (one of stdio / sse / streamable-http / websocket)
+ * @param authHeaders - headers merged over `spec.headers` at connect time
+ * @returns a configured Transport ready to be passed to `Client.connect()`
+ */
+export function createTransport(
+  spec: MCPServerSpec,
+  authHeaders?: Record<string, string>
+): Transport {
+  switch (spec.type) {
+    case 'stdio':
+      return new StdioClientTransport({
+        command: spec.command,
+        args: spec.args,
+        env: spec.env,
+        cwd: spec.cwd,
+      });
+
+    case 'sse': {
+      const headers = mergeHeaders(spec.headers, authHeaders);
+      return new SSEClientTransport(new URL(spec.url), {
+        requestInit: headers ? { headers } : undefined,
+      });
+    }
+
+    case 'streamable-http': {
+      const headers = mergeHeaders(spec.headers, authHeaders);
+      return new StreamableHTTPClientTransport(new URL(spec.url), {
+        requestInit: headers ? { headers } : undefined,
+      });
+    }
+
+    case 'websocket':
+      // Node's WebSocket doesn't natively accept arbitrary headers; the MCP
+      // SDK's transport ignores them. We keep the param for future support
+      // but log a warning elsewhere if headers are provided with websocket.
+      return new WebSocketClientTransport(new URL(spec.url));
+
+    default: {
+      // Exhaustiveness check — TypeScript errors here if a new spec kind
+      // is added without being handled in the switch.
+      const _exhaustive: never = spec;
+      throw new Error(
+        `Unknown MCP transport spec: ${JSON.stringify(_exhaustive)}`
+      );
+    }
+  }
+}
+
+/** Merge headers from two sources, with the second taking precedence. */
+function mergeHeaders(
+  base: Record<string, string> | undefined,
+  overrides: Record<string, string> | undefined
+): Record<string, string> | undefined {
+  if (!base && !overrides) return undefined;
+  return { ...(base ?? {}), ...(overrides ?? {}) };
+}

package/src/providers/mcp/types.ts

@@ -0,0 +1,139 @@
+/**
+ * Types for the MCP capability provider.
+ *
+ * Design notes:
+ *   - `MCPServerSpec` is a unified, minimal shape describing an MCP server
+ *     the library can connect to. All config sources (programmatic,
+ *     YAML-derived, marketplace-derived) normalize to this before reaching
+ *     the provider.
+ *   - Auth headers are provided per-request via `getAuthHeaders` on the
+ *     provider config. The library never orchestrates OAuth — the host
+ *     resolves tokens however it sees fit and forwards the headers map.
+ */
+
+import type { StructuredToolInterface } from '@langchain/core/tools';
+
+/** Transport kinds supported by the MCP SDK. */
+export type MCPTransportKind =
+  | 'stdio'
+  | 'sse'
+  | 'streamable-http'
+  | 'websocket';
+
+/** Stdio-transport spec — spawn a local subprocess. */
+export interface StdioSpec {
+  type: 'stdio';
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  /** Working directory for the spawned process. */
+  cwd?: string;
+}
+
+/** SSE-transport spec (legacy EventSource-based transport). */
+export interface SSESpec {
+  type: 'sse';
+  url: string;
+  /** Static headers (e.g., API key). Forwarded on each HTTP request. */
+  headers?: Record<string, string>;
+}
+
+/** Streamable HTTP spec (the modern MCP HTTP transport). */
+export interface StreamableHTTPSpec {
+  type: 'streamable-http';
+  url: string;
+  headers?: Record<string, string>;
+}
+
+/** WebSocket transport spec. */
+export interface WebSocketSpec {
+  type: 'websocket';
+  url: string;
+  headers?: Record<string, string>;
+}
+
+/** Discriminated union of all supported transports. */
+export type MCPServerSpec =
+  | StdioSpec
+  | SSESpec
+  | StreamableHTTPSpec
+  | WebSocketSpec;
+
+/** Configuration for the MCP capability provider. */
+export interface MCPProviderConfig {
+  /**
+   * Map of serverName → spec. Server names are stable identifiers used
+   * downstream as the capability name prefix and as keys for
+   * `getAuthHeaders` lookups.
+   *
+   * The host is responsible for normalizing configs from multiple sources
+   * (local database, YAML, marketplace catalog) into this unified shape.
+   */
+  servers: Record<string, MCPServerSpec>;
+
+  /**
+   * Optional callback to resolve auth headers for a given server at
+   * connect-time. Returns a header map (e.g., `{ Authorization: "Bearer ..." }`)
+   * that is merged into the spec's base headers.
+   *
+   * The library never stores tokens or orchestrates OAuth — the host
+   * owns that layer and surfaces the resolved value here.
+   */
+  getAuthHeaders?: (
+    serverName: string
+  ) =>
+    | Promise<Record<string, string> | undefined>
+    | Record<string, string>
+    | undefined;
+
+  /**
+   * Client identity sent to MCP servers on handshake. Defaults to
+   * env vars (`MCP_CLIENT_NAME` / `MCP_CLIENT_VERSION`) or a library
+   * fallback if not set. Hosts typically override with their app identity.
+   */
+  clientInfo?: { name: string; version: string };
+
+  /** Connection timeout in ms. Defaults to 30_000. */
+  connectTimeoutMs?: number;
+
+  /** Tool-list / tool-call timeout in ms. Defaults to 30_000. */
+  requestTimeoutMs?: number;
+
+  /**
+   * Optional logger. When omitted, falls back to a console-based default.
+   * Implementations are expected to match the `MCPLogger` minimal shape.
+   */
+  logger?: MCPLogger;
+}
+
+/** Minimal logger interface — matches pino-style signatures. */
+export interface MCPLogger {
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+
+/**
+ * Shape returned by the MCP SDK's `listTools()`. Keeping our own narrow
+ * alias so we don't leak the full SDK types through the provider's public
+ * surface.
+ */
+export interface MCPToolDescriptor {
+  name: string;
+  description?: string;
+  inputSchema?: unknown;
+}
+
+/** Result of a tool invocation, flattened from the SDK response. */
+export interface MCPToolCallResult {
+  /** Plain-text content joined from the MCP response's content array. */
+  text: string;
+  /** Raw content array from the SDK response, for advanced consumers. */
+  rawContent: unknown;
+  /** True when the MCP server flagged the result as an error. */
+  isError: boolean;
+}
+
+/** What the provider returns from createRunnables (re-exported for clarity). */
+export type MCPStructuredTool = StructuredToolInterface;