@contractspec/lib.ai-agent 2.5.0 → 2.7.0

package/dist/node/providers/claude-agent-sdk/index.js

@@ -2161,6 +2161,171 @@ var init_spec = __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, 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 {
+    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, 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 () => {
+      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)
@@ -2478,6 +2643,8 @@ function summarizeSession(session) {
 }
 
 // src/providers/claude-agent-sdk/adapter.ts
+import { randomUUID } from "node:crypto";
+
 class ClaudeAgentSDKProvider {
   name = "claude-agent-sdk";
   version = "1.0.0";
@@ -2510,11 +2677,23 @@ class ClaudeAgentSDKProvider {
     if (!this.isAvailable()) {
       throw new ProviderNotAvailableError(this.name, createAgentI18n(this.config.locale).t("error.provider.sdkNotConfigured"));
     }
+    let mcpToolset = null;
     try {
       const toolSet = {};
       for (const tool of spec.tools) {
         toolSet[tool.name] = specToolToExternalTool(tool);
       }
+      if ((this.config.mcpServers?.length ?? 0) > 0) {
+        mcpToolset = await createMcpToolsets(this.config.mcpServers ?? [], {
+          onNameCollision: "error"
+        });
+        for (const [toolName, mcpTool] of Object.entries(mcpToolset.tools)) {
+          if (toolSet[toolName]) {
+            throw new Error(`MCP tool "${toolName}" collides with a ContractSpec tool. Configure MCP toolPrefix values to avoid collisions.`);
+          }
+          toolSet[toolName] = this.mcpToolToExternalTool(toolName, mcpTool);
+        }
+      }
       const instructions = await injectStaticKnowledge(spec.instructions, spec.knowledge ?? [], undefined);
       const contextId = `claude-${agentKey(spec.meta)}-${Date.now()}`;
       const metadata = {
@@ -2522,6 +2701,7 @@ class ClaudeAgentSDKProvider {
         extendedThinkingEnabled: this.config.extendedThinking ?? false,
         mcpServerIds: this.config.mcpServers?.map((s) => s.name) ?? []
       };
+      const cleanupMcp = mcpToolset?.cleanup;
       return {
         id: contextId,
         spec: {
@@ -2530,9 +2710,18 @@ class ClaudeAgentSDKProvider {
         },
         tools: toolSet,
         metadata,
-        cleanup: async () => {}
+        cleanup: async () => {
+          if (cleanupMcp) {
+            await cleanupMcp();
+          }
+        }
       };
     } catch (error) {
+      if (mcpToolset) {
+        await mcpToolset.cleanup().catch(() => {
+          return;
+        });
+      }
       throw new ContextCreationError(this.name, createAgentI18n(this.config.locale).t("error.provider.contextCreation", {
         error: error instanceof Error ? error.message : String(error)
       }), error instanceof Error ? error : undefined);
@@ -2547,7 +2736,7 @@ ${params.systemOverride}` : context.spec.instructions;
       const claudeContext = buildClaudeAgentContext(params.options);
       let session = createEmptyClaudeSession();
       session = appendUserMessage(session, params.prompt);
-      const claudeTools = this.prepareToolsForSDK(context, params);
+      const claudeTools = this.prepareToolsForSDK(context);
       const rawResponse = await sdk.execute({
         model: this.config.model,
         system: systemPrompt,
@@ -2603,7 +2792,7 @@ ${params.systemOverride}` : context.spec.instructions;
 
 ${params.systemOverride}` : context.spec.instructions;
       const claudeContext = buildClaudeAgentContext(params.options);
-      const claudeTools = this.prepareToolsForSDK(context, params);
+      const claudeTools = this.prepareToolsForSDK(context);
       const stream = await sdk.stream({
         model: this.config.model,
         system: systemPrompt,
@@ -2686,30 +2875,77 @@ ${params.systemOverride}` : context.spec.instructions;
       throw new ProviderNotAvailableError(this.name, createAgentI18n(this.config.locale).t("error.provider.claudeSdkMissing"));
     }
   }
-  prepareToolsForSDK(context, params) {
-    const handlers = new Map;
-    for (const tool of context.spec.tools) {
-      const externalTool = context.tools[tool.name];
-      if (externalTool?.execute) {
-        handlers.set(tool.name, async (input) => {
-          if (!externalTool.execute) {
-            throw new Error(createAgentI18n(this.config.locale).t("error.toolNoExecuteHandler", {
-              name: tool.name
-            }));
-          }
-          const result = await externalTool.execute(input);
+  prepareToolsForSDK(context) {
+    const i18n = createAgentI18n(this.config.locale);
+    const toolsForSdk = [];
+    for (const [toolName, externalTool] of Object.entries(context.tools)) {
+      if (!externalTool.execute) {
+        continue;
+      }
+      toolsForSdk.push({
+        name: toolName,
+        description: externalTool.description ?? i18n.t("tool.fallbackDescription", { name: toolName }),
+        input_schema: this.normalizeToolSchemaForClaude(externalTool.inputSchema),
+        requires_confirmation: externalTool.requiresApproval,
+        execute: async (input) => {
+          const result = await externalTool.execute?.(input);
           return typeof result === "string" ? result : JSON.stringify(result);
+        }
+      });
+    }
+    return toolsForSdk;
+  }
+  mcpToolToExternalTool(toolName, tool) {
+    return {
+      name: toolName,
+      description: tool.description ?? createAgentI18n(this.config.locale).t("tool.fallbackDescription", {
+        name: toolName
+      }),
+      inputSchema: this.normalizeExternalInputSchema(tool.inputSchema),
+      execute: async (input) => {
+        if (!tool.execute) {
+          throw new Error(createAgentI18n(this.config.locale).t("error.toolNoExecuteHandler", {
+            name: toolName
+          }));
+        }
+        return tool.execute(input, {
+          toolCallId: `mcp-${randomUUID()}`,
+          messages: []
         });
       }
+    };
+  }
+  normalizeExternalInputSchema(schema) {
+    if (this.isRecord(schema)) {
+      const type = schema["type"];
+      if (type === "object" || schema["properties"]) {
+        return schema;
+      }
     }
-    return specToolsToClaudeAgentTools(context.spec.tools, handlers, {
-      agentId: context.id,
-      sessionId: params.options?.sessionId,
-      tenantId: params.options?.tenantId,
-      actorId: params.options?.actorId,
-      metadata: params.options?.metadata,
-      signal: params.signal
-    });
+    return {
+      type: "object",
+      properties: {}
+    };
+  }
+  normalizeToolSchemaForClaude(schema) {
+    if (schema.type === "object") {
+      return {
+        type: "object",
+        properties: schema.properties,
+        required: schema.required,
+        additionalProperties: schema.additionalProperties
+      };
+    }
+    return {
+      type: "object",
+      properties: {
+        value: schema
+      },
+      required: ["value"]
+    };
+  }
+  isRecord(value) {
+    return typeof value === "object" && value !== null;
   }
   async executeTool(toolCall, context, _params) {
     const tool = context.tools[toolCall.toolName];
@@ -2765,6 +3001,7 @@ var init_adapter = __esm(() => {
   init_types();
   init_tool_bridge();
   init_injector();
+  init_mcp_client();
   init_i18n();
 });