@contractspec/lib.ai-agent 2.5.0 → 2.7.0

package/dist/node/agent/agent-factory.js

@@ -2400,6 +2400,171 @@ var init_knowledge_tool = __esm(() => {
   init_i18n();
 });
 
+// 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, tool3] of Object.entries(tools)) {
+    prefixedTools[`${prefix}_${toolName}`] = tool3;
+  }
+  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 {
+    command: requireNonEmptyString(stdioConfig.command, "command", config.name),
+    args: stdioConfig.args,
+    env: stdioConfig.env,
+    cwd: stdioConfig.cwd
+  };
+}
+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 = {};
+  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, tool3] 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] = tool3;
+      }
+    }
+  } catch (error) {
+    await Promise.allSettled(connected.map((result) => result.cleanup()));
+    throw error;
+  }
+  return {
+    tools: combinedTools,
+    serverToolNames,
+    cleanup: async () => {
+      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();
+});
+
 // src/knowledge/injector.ts
 async function injectStaticKnowledge(instructions, knowledgeRefs, retriever, locale) {
   if (!retriever)
@@ -2909,25 +3074,59 @@ class ContractSpecAgent {
   tools;
   config;
   instructions;
+  mcpCleanup;
   activeStepContexts = new Map;
-  constructor(config, instructions, tools) {
+  constructor(config, instructions, tools, mcpCleanup) {
     this.config = config;
     this.spec = config.spec;
     this.id = agentKey(config.spec.meta);
     this.tools = tools;
     this.instructions = instructions;
+    this.mcpCleanup = mcpCleanup;
   }
   static async create(config) {
     const effectiveConfig = config;
-    const instructions = await injectStaticKnowledge(effectiveConfig.spec.instructions, effectiveConfig.spec.knowledge ?? [], effectiveConfig.knowledgeRetriever);
-    const specTools = specToolsToAISDKTools(effectiveConfig.spec.tools, effectiveConfig.toolHandlers, { agentId: agentKey(effectiveConfig.spec.meta) });
-    const knowledgeTool = effectiveConfig.knowledgeRetriever ? createKnowledgeQueryTool(effectiveConfig.knowledgeRetriever, effectiveConfig.spec.knowledge ?? []) : null;
-    const tools = {
-      ...specTools,
-      ...knowledgeTool ? { query_knowledge: knowledgeTool } : {},
-      ...effectiveConfig.additionalTools ?? {}
-    };
-    return new ContractSpecAgent(effectiveConfig, instructions, tools);
+    let mcpToolset = null;
+    if ((effectiveConfig.mcpServers?.length ?? 0) > 0) {
+      mcpToolset = await createMcpToolsets(effectiveConfig.mcpServers ?? [], {
+        onNameCollision: "error"
+      });
+    }
+    try {
+      const instructions = await injectStaticKnowledge(effectiveConfig.spec.instructions, effectiveConfig.spec.knowledge ?? [], effectiveConfig.knowledgeRetriever);
+      const specTools = specToolsToAISDKTools(effectiveConfig.spec.tools, effectiveConfig.toolHandlers, { agentId: agentKey(effectiveConfig.spec.meta) });
+      const knowledgeTool = effectiveConfig.knowledgeRetriever ? createKnowledgeQueryTool(effectiveConfig.knowledgeRetriever, effectiveConfig.spec.knowledge ?? []) : null;
+      const reservedToolNames = new Set(Object.keys(specTools));
+      if (knowledgeTool) {
+        reservedToolNames.add("query_knowledge");
+      }
+      const conflictingMcpTools = Object.keys(mcpToolset?.tools ?? {}).filter((toolName) => reservedToolNames.has(toolName));
+      if (conflictingMcpTools.length > 0) {
+        throw new Error(`MCP tools conflict with agent tools: ${conflictingMcpTools.join(", ")}. Configure MCP toolPrefix values to avoid collisions.`);
+      }
+      const tools = {
+        ...specTools,
+        ...knowledgeTool ? { query_knowledge: knowledgeTool } : {},
+        ...mcpToolset?.tools ?? {},
+        ...effectiveConfig.additionalTools ?? {}
+      };
+      return new ContractSpecAgent(effectiveConfig, instructions, tools, mcpToolset?.cleanup);
+    } catch (error) {
+      if (mcpToolset) {
+        await mcpToolset.cleanup().catch(() => {
+          return;
+        });
+      }
+      throw error;
+    }
+  }
+  async cleanup() {
+    if (!this.mcpCleanup) {
+      return;
+    }
+    const cleanup = this.mcpCleanup;
+    this.mcpCleanup = undefined;
+    await cleanup();
   }
   async generate(params) {
     const sessionId = params.options?.sessionId ?? generateSessionId();
@@ -3102,6 +3301,7 @@ var init_contract_spec_agent = __esm(() => {
   init_spec();
   init_tool_adapter();
   init_knowledge_tool();
+  init_mcp_client();
   init_injector();
   init_adapter();
   ContractSpecCallOptionsSchema = z3.object({
@@ -3136,6 +3336,10 @@ class AgentFactory {
       ...this.config.additionalTools,
       ...options?.additionalTools
     };
+    const mergedMcpServers = [
+      ...this.config.mcpServers ?? [],
+      ...options?.mcpServers ?? []
+    ];
     return ContractSpecAgent.create({
       spec,
       model: options?.model ?? this.config.defaultModel,
@@ -3144,7 +3348,8 @@ class AgentFactory {
       sessionStore: this.config.sessionStore,
       telemetryCollector: this.config.telemetryCollector,
       posthogConfig: this.config.posthogConfig,
-      additionalTools: mergedTools
+      additionalTools: mergedTools,
+      mcpServers: mergedMcpServers.length > 0 ? mergedMcpServers : undefined
     });
   }
   async getOrCreate(name, version) {
@@ -3158,6 +3363,11 @@ class AgentFactory {
     return agent;
   }
   clearCache() {
+    for (const agent of this.cache.values()) {
+      agent.cleanup().catch(() => {
+        return;
+      });
+    }
     this.cache.clear();
   }
   listAvailable() {

package/dist/node/agent/contract-spec-agent.js

@@ -2400,6 +2400,171 @@ var init_knowledge_tool = __esm(() => {
   init_i18n();
 });
 
+// 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, tool3] of Object.entries(tools)) {
+    prefixedTools[`${prefix}_${toolName}`] = tool3;
+  }
+  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 {
+    command: requireNonEmptyString(stdioConfig.command, "command", config.name),
+    args: stdioConfig.args,
+    env: stdioConfig.env,
+    cwd: stdioConfig.cwd
+  };
+}
+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 = {};
+  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, tool3] 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] = tool3;
+      }
+    }
+  } catch (error) {
+    await Promise.allSettled(connected.map((result) => result.cleanup()));
+    throw error;
+  }
+  return {
+    tools: combinedTools,
+    serverToolNames,
+    cleanup: async () => {
+      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();
+});
+
 // src/knowledge/injector.ts
 async function injectStaticKnowledge(instructions, knowledgeRefs, retriever, locale) {
   if (!retriever)
@@ -2909,25 +3074,59 @@ class ContractSpecAgent {
   tools;
   config;
   instructions;
+  mcpCleanup;
   activeStepContexts = new Map;
-  constructor(config, instructions, tools) {
+  constructor(config, instructions, tools, mcpCleanup) {
     this.config = config;
     this.spec = config.spec;
     this.id = agentKey(config.spec.meta);
     this.tools = tools;
     this.instructions = instructions;
+    this.mcpCleanup = mcpCleanup;
   }
   static async create(config) {
     const effectiveConfig = config;
-    const instructions = await injectStaticKnowledge(effectiveConfig.spec.instructions, effectiveConfig.spec.knowledge ?? [], effectiveConfig.knowledgeRetriever);
-    const specTools = specToolsToAISDKTools(effectiveConfig.spec.tools, effectiveConfig.toolHandlers, { agentId: agentKey(effectiveConfig.spec.meta) });
-    const knowledgeTool = effectiveConfig.knowledgeRetriever ? createKnowledgeQueryTool(effectiveConfig.knowledgeRetriever, effectiveConfig.spec.knowledge ?? []) : null;
-    const tools = {
-      ...specTools,
-      ...knowledgeTool ? { query_knowledge: knowledgeTool } : {},
-      ...effectiveConfig.additionalTools ?? {}
-    };
-    return new ContractSpecAgent(effectiveConfig, instructions, tools);
+    let mcpToolset = null;
+    if ((effectiveConfig.mcpServers?.length ?? 0) > 0) {
+      mcpToolset = await createMcpToolsets(effectiveConfig.mcpServers ?? [], {
+        onNameCollision: "error"
+      });
+    }
+    try {
+      const instructions = await injectStaticKnowledge(effectiveConfig.spec.instructions, effectiveConfig.spec.knowledge ?? [], effectiveConfig.knowledgeRetriever);
+      const specTools = specToolsToAISDKTools(effectiveConfig.spec.tools, effectiveConfig.toolHandlers, { agentId: agentKey(effectiveConfig.spec.meta) });
+      const knowledgeTool = effectiveConfig.knowledgeRetriever ? createKnowledgeQueryTool(effectiveConfig.knowledgeRetriever, effectiveConfig.spec.knowledge ?? []) : null;
+      const reservedToolNames = new Set(Object.keys(specTools));
+      if (knowledgeTool) {
+        reservedToolNames.add("query_knowledge");
+      }
+      const conflictingMcpTools = Object.keys(mcpToolset?.tools ?? {}).filter((toolName) => reservedToolNames.has(toolName));
+      if (conflictingMcpTools.length > 0) {
+        throw new Error(`MCP tools conflict with agent tools: ${conflictingMcpTools.join(", ")}. Configure MCP toolPrefix values to avoid collisions.`);
+      }
+      const tools = {
+        ...specTools,
+        ...knowledgeTool ? { query_knowledge: knowledgeTool } : {},
+        ...mcpToolset?.tools ?? {},
+        ...effectiveConfig.additionalTools ?? {}
+      };
+      return new ContractSpecAgent(effectiveConfig, instructions, tools, mcpToolset?.cleanup);
+    } catch (error) {
+      if (mcpToolset) {
+        await mcpToolset.cleanup().catch(() => {
+          return;
+        });
+      }
+      throw error;
+    }
+  }
+  async cleanup() {
+    if (!this.mcpCleanup) {
+      return;
+    }
+    const cleanup = this.mcpCleanup;
+    this.mcpCleanup = undefined;
+    await cleanup();
   }
   async generate(params) {
     const sessionId = params.options?.sessionId ?? generateSessionId();
@@ -3102,6 +3301,7 @@ var init_contract_spec_agent = __esm(() => {
   init_spec();
   init_tool_adapter();
   init_knowledge_tool();
+  init_mcp_client();
   init_injector();
   init_adapter();
   ContractSpecCallOptionsSchema = z3.object({