@contractspec/lib.ai-agent 2.5.0 → 2.7.0

package/dist/agent/unified-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({
@@ -3375,6 +3575,8 @@ function summarizeSession(session) {
 }
 
 // src/providers/claude-agent-sdk/adapter.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
 class ClaudeAgentSDKProvider {
   name = "claude-agent-sdk";
   version = "1.0.0";
@@ -3407,11 +3609,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 tool3 of spec.tools) {
         toolSet[tool3.name] = specToolToExternalTool(tool3);
       }
+      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 = {
@@ -3419,6 +3633,7 @@ class ClaudeAgentSDKProvider {
         extendedThinkingEnabled: this.config.extendedThinking ?? false,
         mcpServerIds: this.config.mcpServers?.map((s) => s.name) ?? []
       };
+      const cleanupMcp = mcpToolset?.cleanup;
       return {
         id: contextId,
         spec: {
@@ -3427,9 +3642,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);
@@ -3444,7 +3668,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,
@@ -3500,7 +3724,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,
@@ -3583,30 +3807,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 tool3 of context.spec.tools) {
-      const externalTool = context.tools[tool3.name];
-      if (externalTool?.execute) {
-        handlers.set(tool3.name, async (input) => {
-          if (!externalTool.execute) {
-            throw new Error(createAgentI18n(this.config.locale).t("error.toolNoExecuteHandler", {
-              name: tool3.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, tool3) {
+    return {
+      name: toolName,
+      description: tool3.description ?? createAgentI18n(this.config.locale).t("tool.fallbackDescription", {
+        name: toolName
+      }),
+      inputSchema: this.normalizeExternalInputSchema(tool3.inputSchema),
+      execute: async (input) => {
+        if (!tool3.execute) {
+          throw new Error(createAgentI18n(this.config.locale).t("error.toolNoExecuteHandler", {
+            name: toolName
+          }));
+        }
+        return tool3.execute(input, {
+          toolCallId: `mcp-${randomUUID2()}`,
+          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 tool3 = context.tools[toolCall.toolName];
@@ -3662,6 +3933,7 @@ var init_adapter2 = __esm(() => {
   init_types();
   init_tool_bridge();
   init_injector();
+  init_mcp_client();
   init_i18n();
 });
 
@@ -4320,6 +4592,7 @@ class UnifiedAgent {
     } catch (error) {
       this.state.lastError = error instanceof Error ? error : new Error(String(error));
       if (this.config.fallbackBackend && this.config.fallbackBackend !== backend) {
+        await this.cleanupProviderContext();
         console.warn(this.i18n().t("log.unifiedAgent.fallback", {
           backend: String(backend),
           fallback: String(this.config.fallbackBackend)
@@ -4390,16 +4663,24 @@ class UnifiedAgent {
   }
   async runWithAISDK(message, options) {
     const { ContractSpecAgent: ContractSpecAgent2 } = await Promise.resolve().then(() => (init_contract_spec_agent(), exports_contract_spec_agent));
+    const backendConfig = this.getAISDKConfig();
     const model = await this.resolveAISDKModel();
     const agent = await ContractSpecAgent2.create({
       spec: this.spec,
       model,
-      toolHandlers: this.tools
-    });
-    return await agent.generate({
-      prompt: message,
-      options
+      toolHandlers: this.tools,
+      mcpServers: backendConfig?.mcpServers
     });
+    try {
+      return await agent.generate({
+        prompt: message,
+        options
+      });
+    } finally {
+      await agent.cleanup().catch(() => {
+        return;
+      });
+    }
   }
   async runWithExternalProvider(message, options) {
     if (!this.provider || !this.context) {
@@ -4507,6 +4788,7 @@ class UnifiedAgent {
     if (backend === this.state.backend) {
       return;
     }
+    await this.cleanupProviderContext();
     this.state.backend = backend;
     this.state.isReady = false;
     this.provider = undefined;
@@ -4517,8 +4799,20 @@ class UnifiedAgent {
     this.state.messageCount = 0;
     this.state.sessionId = undefined;
     this.state.lastError = undefined;
+    this.cleanupProviderContext().catch(() => {
+      return;
+    });
     this.context = undefined;
   }
+  async cleanupProviderContext() {
+    const context = this.context;
+    this.context = undefined;
+    if (context) {
+      await context.cleanup().catch(() => {
+        return;
+      });
+    }
+  }
   addTool(name, handler) {
     this.tools.set(name, handler);
   }
@@ -4538,7 +4832,8 @@ function createAISDKAgent(spec, options) {
       modelInstance: options?.modelInstance,
       provider: options?.provider,
       temperature: options?.temperature,
-      maxTokens: options?.maxTokens
+      maxTokens: options?.maxTokens,
+      mcpServers: options?.mcpServers
     }
   });
 }

package/dist/exporters/claude-agent-exporter.d.ts

@@ -46,6 +46,7 @@ export declare class ClaudeAgentExporter implements Exporter<ClaudeAgentExportOp
      * Generate CLAUDE.md content for Claude Code CLI integration.
      */
     private generateClaudeMd;
+    private formatMcpServer;
 }
 /**
  * Export an AgentSpec to Claude Agent SDK format.

package/dist/exporters/claude-agent-exporter.js

@@ -2366,7 +2366,7 @@ class ClaudeAgentExporter {
       lines.push(i18n.t("export.mcpServers"));
       lines.push("");
       for (const server of options.mcpServers) {
-        lines.push(`- **${server.name}**: \`${server.command}${server.args ? " " + server.args.join(" ") : ""}\``);
+        lines.push(`- **${server.name}**: \`${this.formatMcpServer(server)}\``);
       }
       lines.push("");
     }
@@ -2376,6 +2376,16 @@ class ClaudeAgentExporter {
     return lines.join(`
 `);
   }
+  formatMcpServer(server) {
+    if ("command" in server) {
+      const args = server.args ? ` ${server.args.join(" ")}` : "";
+      return `${server.command}${args}`;
+    }
+    if (server.transport === "http" || server.transport === "sse") {
+      return `${server.transport} ${server.url}`;
+    }
+    return server.url;
+  }
 }
 function exportToClaudeAgent(spec, options) {
   const exporter = new ClaudeAgentExporter;

package/dist/exporters/index.js

@@ -2652,7 +2652,7 @@ class ClaudeAgentExporter {
       lines.push(i18n.t("export.mcpServers"));
       lines.push("");
       for (const server of options.mcpServers) {
-        lines.push(`- **${server.name}**: \`${server.command}${server.args ? " " + server.args.join(" ") : ""}\``);
+        lines.push(`- **${server.name}**: \`${this.formatMcpServer(server)}\``);
       }
       lines.push("");
     }
@@ -2662,6 +2662,16 @@ class ClaudeAgentExporter {
     return lines.join(`
 `);
   }
+  formatMcpServer(server) {
+    if ("command" in server) {
+      const args = server.args ? ` ${server.args.join(" ")}` : "";
+      return `${server.command}${args}`;
+    }
+    if (server.transport === "http" || server.transport === "sse") {
+      return `${server.transport} ${server.url}`;
+    }
+    return server.url;
+  }
 }
 function exportToClaudeAgent(spec, options) {
   const exporter = new ClaudeAgentExporter;

package/dist/exporters/types.d.ts

@@ -6,6 +6,7 @@
  */
 import type { AgentSpec } from '../spec/spec';
 import type { OpenCodeAgentType } from '../providers/types';
+import type { McpClientConfig } from '../tools/mcp-client';
 /**
  * Base export options.
  */
@@ -36,11 +37,7 @@ export interface ClaudeAgentExportOptions extends ExportOptions {
     /** Enable extended thinking in exported config */
     extendedThinking?: boolean;
     /** MCP servers to include */
-    mcpServers?: {
-        name: string;
-        command: string;
-        args?: string[];
-    }[];
+    mcpServers?: McpClientConfig[];
 }
 /**
  * Claude Agent SDK export result.
@@ -67,11 +64,7 @@ export interface ClaudeAgentConfig {
     max_turns?: number;
     computer_use?: boolean;
     extended_thinking?: boolean;
-    mcp_servers?: {
-        name: string;
-        command: string;
-        args?: string[];
-    }[];
+    mcp_servers?: McpClientConfig[];
 }
 /**
  * Claude Agent SDK tool definition.