@illuma-ai/agents 1.4.0-alpha.5 → 1.5.0

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

@@ -1,371 +0,0 @@
-/**
- * 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

@@ -1,45 +0,0 @@
-/**
- * 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

@@ -1,21 +0,0 @@
-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

@@ -1,76 +0,0 @@
-/**
- * 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

@@ -1,139 +0,0 @@
-/**
- * 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;