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

package/src/providers/mcp/MCPCapabilityProvider.ts

@@ -0,0 +1,345 @@
+/**
+ * MCPCapabilityProvider — connects to MCP servers via the official MCP SDK
+ * and exposes their tools as `Capability` / `StructuredToolInterface`.
+ *
+ * Mirrors the pattern of `ToolsServerCapabilityProvider`: thin adapter,
+ * protocol-specific transport, stateless as far as tokens/OAuth are
+ * concerned (all auth is host-resolved and forwarded via `getAuthHeaders`).
+ *
+ * What the host supplies:
+ *   - `servers`: unified spec map (normalized from whatever source:
+ *     programmatic, YAML, DB, marketplace catalog).
+ *   - `getAuthHeaders?`: per-server header resolver. Called at connect
+ *     time. OAuth orchestration / token refresh happens in the host.
+ *
+ * What the library does:
+ *   - Picks the right SDK transport per spec.
+ *   - Connects, calls `listTools()`, wraps each tool as a `Capability`.
+ *   - `createRunnables()` returns `StructuredTool`s that invoke the
+ *     server's tools on demand, streaming the string result back to the
+ *     agent.
+ *   - Caches open connections per-instance so repeated `fetchManifest` /
+ *     `createRunnables` calls reuse them.
+ */
+
+import { tool, type StructuredToolInterface } from '@langchain/core/tools';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+
+import {
+  CapabilityKind,
+  type Capability,
+  type CapabilityFilter,
+  type CapabilityProvider,
+  type CredentialMap,
+} from '@/providers/types';
+import {
+  CAPABILITY_NAME_SEPARATOR,
+  formatCapabilityName,
+  parseCapabilityName,
+} from '@/providers/capabilityNaming';
+import { createTransport } from './transport';
+import { consoleLogger, getMCPEnvDefaults } from './config';
+import type {
+  MCPLogger,
+  MCPProviderConfig,
+  MCPServerSpec,
+  MCPToolCallResult,
+  MCPToolDescriptor,
+} from './types';
+
+/**
+ * Per-server connection state kept inside the provider. Reused across
+ * manifest fetches and tool invocations.
+ */
+interface ServerConnection {
+  serverName: string;
+  spec: MCPServerSpec;
+  client: Client;
+  transport: Transport;
+  tools: MCPToolDescriptor[];
+}
+
+export class MCPCapabilityProvider implements CapabilityProvider {
+  readonly providerId: string;
+  private readonly config: Required<
+    Pick<
+      MCPProviderConfig,
+      'connectTimeoutMs' | 'requestTimeoutMs' | 'clientInfo'
+    >
+  > &
+    Pick<MCPProviderConfig, 'servers' | 'getAuthHeaders'>;
+  private readonly logger: MCPLogger;
+  private readonly connections = new Map<string, ServerConnection>();
+
+  constructor(config: MCPProviderConfig) {
+    if (!config.servers || Object.keys(config.servers).length === 0) {
+      throw new Error('MCPCapabilityProvider: at least one server is required');
+    }
+    const env = getMCPEnvDefaults();
+    this.config = {
+      servers: config.servers,
+      getAuthHeaders: config.getAuthHeaders,
+      clientInfo: config.clientInfo ?? {
+        name: env.clientName,
+        version: env.clientVersion,
+      },
+      connectTimeoutMs: config.connectTimeoutMs ?? env.connectTimeoutMs,
+      requestTimeoutMs: config.requestTimeoutMs ?? env.requestTimeoutMs,
+    };
+    this.logger = config.logger ?? consoleLogger;
+    const names = Object.keys(config.servers).sort().join(',');
+    this.providerId = `mcp:${names}`;
+  }
+
+  async fetchManifest(filter?: CapabilityFilter): Promise<Capability[]> {
+    // MCP only emits kind='mcp' — short-circuit if filter excludes us.
+    if (filter?.kind && filter.kind !== CapabilityKind.MCP) return [];
+
+    const capabilities: Capability[] = [];
+
+    for (const serverName of Object.keys(this.config.servers)) {
+      try {
+        const conn = await this.ensureConnection(serverName);
+        for (const toolDesc of conn.tools) {
+          const cap = this.toolToCapability(serverName, toolDesc);
+          if (this.capabilityMatchesFilter(cap, filter)) {
+            capabilities.push(cap);
+          }
+        }
+      } catch (err) {
+        // One server failing should not block the others — log and continue.
+        this.logger.warn(
+          `[mcp] failed to fetch manifest for server "${serverName}":`,
+          err instanceof Error ? err.message : err
+        );
+      }
+    }
+
+    this.logger.debug(
+      `[mcp] manifest assembled — ${capabilities.length} capabilities across ${this.connections.size}/${Object.keys(this.config.servers).length} connected servers`
+    );
+
+    return capabilities;
+  }
+
+  async createRunnables(
+    capabilities: Capability[],
+    _credentials: CredentialMap
+  ): Promise<StructuredToolInterface[]> {
+    const runnables: StructuredToolInterface[] = [];
+
+    for (const cap of capabilities) {
+      if (cap.kind !== CapabilityKind.MCP) continue;
+
+      const parsed = parseCapabilityName(cap.name);
+      const serverName = parsed?.sourceName;
+      const toolName = parsed?.itemName;
+      if (!serverName || !toolName) {
+        this.logger.warn(
+          `[mcp] skipping capability "${cap.name}" — unparseable`
+        );
+        continue;
+      }
+
+      const runnable = this.buildProxyTool(serverName, toolName, cap);
+      runnables.push(runnable);
+    }
+
+    return runnables;
+  }
+
+  /**
+   * Disconnect all open MCP client connections. Callers should invoke this
+   * on shutdown to release transports and child processes (for stdio).
+   */
+  async close(): Promise<void> {
+    for (const [serverName, conn] of this.connections.entries()) {
+      try {
+        await conn.client.close();
+      } catch (err) {
+        this.logger.warn(
+          `[mcp] error closing connection to "${serverName}":`,
+          err instanceof Error ? err.message : err
+        );
+      }
+    }
+    this.connections.clear();
+  }
+
+  // --- internals ---------------------------------------------------------
+
+  private async ensureConnection(
+    serverName: string
+  ): Promise<ServerConnection> {
+    const existing = this.connections.get(serverName);
+    if (existing) return existing;
+
+    const spec = this.config.servers[serverName];
+    if (!spec) {
+      throw new Error(`[mcp] server "${serverName}" not in config`);
+    }
+
+    const authHeaders = await this.resolveAuthHeaders(serverName);
+    const transport = createTransport(spec, authHeaders);
+    const client = new Client(this.config.clientInfo, {
+      capabilities: {},
+    });
+
+    this.logger.debug(`[mcp] connecting to "${serverName}" (${spec.type})`);
+    await client.connect(transport);
+
+    const { tools } = await client.listTools();
+    this.logger.debug(
+      `[mcp] connected to "${serverName}" — ${tools.length} tools discovered`
+    );
+
+    const conn: ServerConnection = {
+      serverName,
+      spec,
+      client,
+      transport,
+      tools: tools as MCPToolDescriptor[],
+    };
+    this.connections.set(serverName, conn);
+    return conn;
+  }
+
+  private async resolveAuthHeaders(
+    serverName: string
+  ): Promise<Record<string, string> | undefined> {
+    if (!this.config.getAuthHeaders) return undefined;
+    try {
+      return await this.config.getAuthHeaders(serverName);
+    } catch (err) {
+      this.logger.warn(
+        `[mcp] getAuthHeaders("${serverName}") threw:`,
+        err instanceof Error ? err.message : err
+      );
+      return undefined;
+    }
+  }
+
+  private toolToCapability(
+    serverName: string,
+    toolDesc: MCPToolDescriptor
+  ): Capability {
+    return {
+      kind: CapabilityKind.MCP,
+      name: formatCapabilityName(serverName, toolDesc.name),
+      description:
+        toolDesc.description ?? `${toolDesc.name} (via ${serverName})`,
+      schema: toolDesc.inputSchema ?? {
+        type: 'object',
+        properties: {},
+      },
+      authConfig: [],
+      metadata: {
+        category: 'mcp',
+        tags: [serverName],
+      },
+    };
+  }
+
+  private capabilityMatchesFilter(
+    cap: Capability,
+    filter?: CapabilityFilter
+  ): boolean {
+    if (!filter) return true;
+    if (filter.kind && cap.kind !== filter.kind) return false;
+    if (filter.names && !filter.names.includes(cap.name)) return false;
+    if (filter.tags?.length) {
+      const capTags = new Set(cap.metadata.tags ?? []);
+      if (!filter.tags.some((t) => capTags.has(t))) return false;
+    }
+    return true;
+  }
+
+  private buildProxyTool(
+    serverName: string,
+    toolName: string,
+    cap: Capability
+  ): StructuredToolInterface {
+    // Arrow-function closures would capture `this` correctly but LangChain's
+    // `tool()` helper expects a plain async function; bind the methods we
+    // need up-front so the closure body stays clean and strict-lint-friendly.
+    const logger = this.logger;
+    const ensureConnection = this.ensureConnection.bind(this);
+    return tool(
+      async (input: unknown): Promise<string> => {
+        // DEBUG: log tool invocation (remove after POC stabilizes)
+        logger.debug(
+          `[mcp] invoking ${serverName}:${toolName}`,
+          input && typeof input === 'object'
+            ? `inputKeys=${Object.keys(input as object).length}`
+            : ''
+        );
+
+        const conn = await ensureConnection(serverName);
+        const response = await conn.client.callTool({
+          name: toolName,
+          arguments: (input as Record<string, unknown>) ?? {},
+        });
+
+        const result = flattenToolCallResponse(response);
+        if (result.isError) {
+          throw new Error(
+            `MCP tool "${serverName}:${toolName}" failed: ${result.text}`
+          );
+        }
+        return result.text;
+      },
+      {
+        name: cap.name,
+        description: cap.description,
+        schema: (cap.schema as object) ?? { type: 'object', properties: {} },
+        responseFormat: 'content',
+      }
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers exported for testing
+// ---------------------------------------------------------------------------
+
+// CAPABILITY_NAME_SEPARATOR + formatCapabilityName live in the shared
+// `@/providers/capabilityNaming` module so MCP and A2A providers stay in
+// lockstep on name encoding. Re-exported here for callers that already
+// import from the MCP barrel.
+export { CAPABILITY_NAME_SEPARATOR, formatCapabilityName };
+
+/**
+ * Flatten the MCP SDK's callTool response into a plain text + error flag.
+ * Concatenates any `text`-type content parts; non-text parts are
+ * JSON-stringified so the LLM sees something rather than silently
+ * dropping output.
+ */
+export function flattenToolCallResponse(response: unknown): MCPToolCallResult {
+  const resp = response as {
+    content?: Array<{ type?: string; text?: string; [k: string]: unknown }>;
+    isError?: boolean;
+  } | null;
+
+  const rawContent = resp?.content ?? [];
+  const isError = resp?.isError === true;
+
+  if (!Array.isArray(rawContent) || rawContent.length === 0) {
+    return {
+      text: isError ? '(error with no content)' : '(empty response)',
+      rawContent,
+      isError,
+    };
+  }
+
+  const parts = rawContent.map((item) => {
+    if (item.type === 'text' && typeof item.text === 'string') return item.text;
+    try {
+      return JSON.stringify(item);
+    } catch {
+      return '[unserializable content part]';
+    }
+  });
+
+  return { text: parts.join('\n\n'), rawContent, isError };
+}