@contractspec/lib.ai-agent 2.6.0 → 2.7.0

package/dist/tools/mcp-client.d.ts

@@ -1,17 +1,58 @@
+import { type OAuthClientProvider } from '@ai-sdk/mcp';
 import type { Tool } from 'ai';
 /**
- * Configuration for connecting to an MCP server.
+ * Supported transport types for MCP clients.
+ */
+export type McpTransportType = 'stdio' | 'sse' | 'http';
+/**
+ * Shared configuration for all MCP server transports.
  */
-export interface McpClientConfig {
+interface McpClientBaseConfig {
     /** Display name for the MCP server */
     name: string;
+    /** Optional prefix applied to every imported tool name */
+    toolPrefix?: string;
+    /** Optional MCP client name override */
+    clientName?: string;
+    /** Optional MCP client version override */
+    clientVersion?: string;
+}
+/**
+ * Configuration for stdio MCP servers.
+ */
+export interface McpStdioClientConfig extends McpClientBaseConfig {
+    /** Transport type (defaults to "stdio" when omitted) */
+    transport?: 'stdio';
     /** Command to spawn the MCP server process */
     command: string;
     /** Arguments to pass to the command */
     args?: string[];
     /** Environment variables for the process */
     env?: Record<string, string>;
+    /** Working directory for spawned process */
+    cwd?: string;
 }
+/**
+ * Configuration for remote MCP servers (SSE / Streamable HTTP).
+ */
+export interface McpRemoteClientConfig extends McpClientBaseConfig {
+    /** Transport type */
+    transport: 'sse' | 'http';
+    /** MCP endpoint URL */
+    url: string;
+    /** Optional static headers */
+    headers?: Record<string, string>;
+    /** Optional OAuth provider for MCP auth flow */
+    authProvider?: OAuthClientProvider;
+    /** Optional bearer token injected into Authorization header */
+    accessToken?: string;
+    /** Optional env var name containing bearer token */
+    accessTokenEnvVar?: string;
+}
+/**
+ * Configuration for connecting to an MCP server.
+ */
+export type McpClientConfig = McpStdioClientConfig | McpRemoteClientConfig;
 /**
  * Result of creating an MCP client with tools.
  */
@@ -20,6 +61,15 @@ export interface McpClientResult {
     tools: Record<string, Tool<unknown, unknown>>;
     /** Cleanup function to close the connection */
     cleanup: () => Promise<void>;
+    /** Tool names grouped by source server name */
+    serverToolNames: Record<string, string[]>;
+}
+/**
+ * Options for combining multiple MCP toolsets.
+ */
+export interface CreateMcpToolsetsOptions {
+    /** Strategy used when two MCP servers expose the same tool name */
+    onNameCollision?: 'overwrite' | 'error';
 }
 /**
  * Create AI SDK tools from an MCP server.
@@ -48,6 +98,8 @@ export declare function mcpServerToTools(config: McpClientConfig): Promise<McpCl
  * Create multiple MCP tool sets from configurations.
  *
  * @param configs - Array of MCP server configurations
+ * @param options - Merge options for conflicts
  * @returns Combined tools and cleanup function
  */
-export declare function createMcpToolsets(configs: McpClientConfig[]): Promise<McpClientResult>;
+export declare function createMcpToolsets(configs: McpClientConfig[], options?: CreateMcpToolsetsOptions): Promise<McpClientResult>;
+export {};

package/dist/tools/mcp-client.js

@@ -12,35 +12,172 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = import.meta.require;
 
-// src/tools/mcp-client.ts
-import { experimental_createMCPClient } from "@ai-sdk/mcp";
-import { Experimental_StdioMCPTransport as StdioClientTransport } from "@ai-sdk/mcp/mcp-stdio";
-async function mcpServerToTools(config) {
-  const transport = new StdioClientTransport({
-    command: config.command,
-    args: config.args,
-    env: config.env
-  });
-  const client = await experimental_createMCPClient({ transport });
-  const tools = await client.tools();
+// src/tools/mcp-client-helpers.ts
+import {
+  Experimental_StdioMCPTransport as StdioClientTransport
+} from "@ai-sdk/mcp/mcp-stdio";
+function buildMcpTransport(config) {
+  const transport = resolveTransportType(config);
+  if (transport === "stdio") {
+    const stdioConfig = resolveStdioConfig(config);
+    return new StdioClientTransport(stdioConfig);
+  }
+  const remoteConfig = config;
+  const headers = resolveRemoteHeaders(remoteConfig);
+  const remoteTransport = {
+    type: transport,
+    url: requireNonEmptyString(remoteConfig.url, "url", config.name)
+  };
+  if (headers) {
+    remoteTransport.headers = headers;
+  }
+  if (remoteConfig.authProvider) {
+    remoteTransport.authProvider = remoteConfig.authProvider;
+  }
+  return remoteTransport;
+}
+function prefixToolNames(config, tools) {
+  const prefix = config.toolPrefix?.trim();
+  if (!prefix) {
+    return tools;
+  }
+  const prefixedTools = {};
+  for (const [toolName, tool] of Object.entries(tools)) {
+    prefixedTools[`${prefix}_${toolName}`] = tool;
+  }
+  return prefixedTools;
+}
+function getErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function resolveTransportType(config) {
+  return config.transport ?? "stdio";
+}
+function resolveStdioConfig(config) {
+  const stdioConfig = config;
   return {
-    tools,
-    cleanup: () => client.close()
+    command: requireNonEmptyString(stdioConfig.command, "command", config.name),
+    args: stdioConfig.args,
+    env: stdioConfig.env,
+    cwd: stdioConfig.cwd
   };
 }
-async function createMcpToolsets(configs) {
-  const results = await Promise.all(configs.map(mcpServerToTools));
+function resolveRemoteHeaders(config) {
+  const headers = {
+    ...config.headers ?? {}
+  };
+  const accessToken = config.accessToken ?? resolveEnvToken(config.accessTokenEnvVar);
+  if (accessToken && headers.Authorization === undefined) {
+    headers.Authorization = `Bearer ${accessToken}`;
+  }
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+function resolveEnvToken(envVarName) {
+  if (!envVarName) {
+    return;
+  }
+  const value = process.env[envVarName];
+  if (!value) {
+    return;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+function requireNonEmptyString(value, field, serverName) {
+  if (!value) {
+    throw new Error(`MCP server "${serverName}" is missing required "${field}".`);
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`MCP server "${serverName}" has an empty "${field}".`);
+  }
+  return trimmed;
+}
+var init_mcp_client_helpers = () => {};
+
+// src/tools/mcp-client.ts
+import {
+  experimental_createMCPClient
+} from "@ai-sdk/mcp";
+async function mcpServerToTools(config) {
+  let client = null;
+  try {
+    const transport = buildMcpTransport(config);
+    client = await experimental_createMCPClient({
+      transport,
+      name: config.clientName,
+      version: config.clientVersion
+    });
+    const tools = await client.tools();
+    const prefixedTools = prefixToolNames(config, tools);
+    const connectedClient = client;
+    return {
+      tools: prefixedTools,
+      cleanup: () => connectedClient.close(),
+      serverToolNames: {
+        [config.name]: Object.keys(prefixedTools)
+      }
+    };
+  } catch (error) {
+    if (client) {
+      await client.close().catch(() => {
+        return;
+      });
+    }
+    throw new Error(`[MCP:${config.name}] Failed to connect tools: ${getErrorMessage(error)}`);
+  }
+}
+async function createMcpToolsets(configs, options = {}) {
+  const connected = [];
+  try {
+    for (const config of configs) {
+      const result = await mcpServerToTools(config);
+      connected.push(result);
+    }
+  } catch (error) {
+    await Promise.allSettled(connected.map((result) => result.cleanup()));
+    throw error;
+  }
   const combinedTools = {};
-  for (const result of results) {
-    Object.assign(combinedTools, result.tools);
+  const serverToolNames = {};
+  const collisionStrategy = options.onNameCollision ?? "overwrite";
+  try {
+    for (const result of connected) {
+      for (const [serverName, toolNames] of Object.entries(result.serverToolNames)) {
+        serverToolNames[serverName] = toolNames;
+      }
+      for (const [toolName, tool] of Object.entries(result.tools)) {
+        const hasCollision = combinedTools[toolName] !== undefined;
+        if (hasCollision && collisionStrategy === "error") {
+          throw new Error(`Duplicate MCP tool name "${toolName}" detected. Use "toolPrefix" or set onNameCollision to "overwrite".`);
+        }
+        combinedTools[toolName] = tool;
+      }
+    }
+  } catch (error) {
+    await Promise.allSettled(connected.map((result) => result.cleanup()));
+    throw error;
   }
   return {
     tools: combinedTools,
+    serverToolNames,
     cleanup: async () => {
-      await Promise.all(results.map((r) => r.cleanup()));
+      const cleanupResults = await Promise.allSettled(connected.map((result) => result.cleanup()));
+      const failures = cleanupResults.filter((result) => result.status === "rejected");
+      if (failures.length > 0) {
+        throw new Error(`Failed to cleanup ${failures.length} MCP client connection(s).`);
+      }
     }
   };
 }
+var init_mcp_client = __esm(() => {
+  init_mcp_client_helpers();
+});
+init_mcp_client();
+
 export {
   mcpServerToTools,
   createMcpToolsets

package/dist/tools/mcp-client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.ai-agent",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "AI agent orchestration with MCP and tool support",
   "keywords": [
     "contractspec",
@@ -33,18 +33,18 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "ai": "6.0.86",
+    "ai": "6.0.97",
     "@ai-sdk/mcp": "1.0.21",
-    "@ai-sdk/anthropic": "3.0.44",
-    "@ai-sdk/google": "3.0.29",
+    "@ai-sdk/anthropic": "3.0.46",
+    "@ai-sdk/google": "3.0.30",
     "@ai-sdk/mistral": "3.0.20",
-    "@ai-sdk/openai": "3.0.29",
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "@posthog/react": "^1.7.1",
+    "@ai-sdk/openai": "3.0.31",
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "@posthog/react": "^1.8.0",
     "@posthog/ai": "latest",
-    "@contractspec/lib.contracts-spec": "2.6.0",
-    "@contractspec/lib.ai-providers": "2.6.0",
-    "@contractspec/lib.knowledge": "2.6.0",
+    "@contractspec/lib.contracts-spec": "2.7.0",
+    "@contractspec/lib.ai-providers": "2.7.0",
+    "@contractspec/lib.knowledge": "2.7.0",
     "compare-versions": "^6.1.1",
     "zod": "^4.3.5"
   },
@@ -68,9 +68,9 @@
     }
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "2.6.0",
+    "@contractspec/tool.typescript": "2.7.0",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "2.6.0"
+    "@contractspec/tool.bun": "2.7.0"
   },
   "exports": {
     ".": {
@@ -499,6 +499,12 @@
       "node": "./dist/node/tools/mcp-client.js",
       "default": "./dist/tools/mcp-client.js"
     },
+    "./tools/mcp-client-helpers": {
+      "types": "./dist/tools/mcp-client-helpers.d.ts",
+      "bun": "./dist/tools/mcp-client-helpers.js",
+      "node": "./dist/node/tools/mcp-client-helpers.js",
+      "default": "./dist/tools/mcp-client-helpers.js"
+    },
     "./tools/mcp-server": {
       "types": "./dist/tools/mcp-server.d.ts",
       "bun": "./dist/tools/mcp-server.js",
@@ -947,6 +953,12 @@
         "node": "./dist/node/tools/mcp-client.js",
         "default": "./dist/tools/mcp-client.js"
       },
+      "./tools/mcp-client-helpers": {
+        "types": "./dist/tools/mcp-client-helpers.d.ts",
+        "bun": "./dist/tools/mcp-client-helpers.js",
+        "node": "./dist/node/tools/mcp-client-helpers.js",
+        "default": "./dist/tools/mcp-client-helpers.js"
+      },
       "./tools/mcp-server": {
         "types": "./dist/tools/mcp-server.d.ts",
         "bun": "./dist/tools/mcp-server.js",