@claude-code-kit/agent 0.2.0 → 0.3.0

package/dist/index.d.mts

@@ -73,6 +73,9 @@ interface ToolDefinition<TInput = unknown> {
     isDestructive?: boolean;
     requiresConfirmation?: boolean;
     timeout?: number;
+    /** Original JSON Schema from an MCP server, used by toolToProviderFormat() to
+     *  avoid a lossy Zod -> JSON Schema round-trip for MCP-discovered tools. */
+    rawInputSchema?: Record<string, unknown>;
 }
 type StreamChunk = {
     type: "text";
@@ -178,11 +181,34 @@ interface Session {
 interface CompactionStrategy {
     compact(messages: Message[], maxTokens: number): Message[] | Promise<Message[]>;
 }
+/** Stdio-based MCP server: spawns a subprocess. */
+interface MCPStdioServerConfig {
+    name: string;
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    /** Timeout in ms for the initial connection (default: 30000). */
+    connectTimeout?: number;
+}
+/** HTTP-based MCP server: connects via Streamable HTTP transport. */
+interface MCPHttpServerConfig {
+    name: string;
+    url: string;
+    headers?: Record<string, string>;
+    /** Timeout in ms for the initial connection (default: 30000). */
+    connectTimeout?: number;
+}
+type MCPServerConfig = MCPStdioServerConfig | MCPHttpServerConfig;
+interface MCPConfig {
+    servers: MCPServerConfig[];
+}
 interface AgentConfig {
     provider: LLMProvider;
     model: string;
     systemPrompt?: string;
     tools?: ToolDefinition[];
+    mcp?: MCPConfig;
     maxTokens?: number;
     temperature?: number;
     contextLimit?: number;
@@ -191,6 +217,33 @@ interface AgentConfig {
     permissionHandler?: PermissionHandler;
     workingDirectory?: string;
     maxTurns?: number;
+    /** Max number of tools to execute concurrently (default: 5). */
+    maxConcurrentTools?: number;
+}
+
+declare class MCPClient {
+    private config;
+    private client;
+    private transport;
+    private _tools;
+    private _connected;
+    constructor(config: MCPServerConfig);
+    get name(): string;
+    get connected(): boolean;
+    get tools(): ToolDefinition[];
+    /**
+     * Connect to the MCP server and discover available tools.
+     * Throws if the SDK is not installed or the server fails to connect.
+     */
+    connect(): Promise<void>;
+    /**
+     * Refresh the tool list from the server.
+     */
+    discoverTools(): Promise<ToolDefinition[]>;
+    /**
+     * Disconnect from the MCP server and clean up resources.
+     */
+    disconnect(): Promise<void>;
 }
 
 /**
@@ -211,7 +264,12 @@ declare class Agent {
     private contextManager;
     private permissionHandler;
     private workingDirectory;
+    private maxConcurrentTools;
     private abortController;
+    private mcpClients;
+    private mcpConfig?;
+    private mcpInitialized;
+    private mcpInitPromise?;
     constructor(config: AgentConfig);
     /**
      * Run the agent loop. Yields events as the agent processes the input.
@@ -243,7 +301,18 @@ declare class Agent {
     removeTool(name: string): boolean;
     /** Replace the permission handler at runtime. */
     setPermissionHandler(handler: PermissionHandler): void;
-    private executeToolCalls;
+    /** Get the list of active MCP clients. */
+    getMCPClients(): MCPClient[];
+    /**
+     * Disconnect all MCP servers and clean up resources.
+     * Call this when the agent is no longer needed.
+     */
+    disconnectMCP(): Promise<void>;
+    /**
+     * Connect to configured MCP servers and register their tools.
+     * Servers that fail to connect are skipped with a warning (non-fatal).
+     */
+    private initializeMCP;
 }
 
 /**
@@ -719,4 +788,4 @@ declare const PRESET_PROVIDERS: Record<string, ProviderRegistration>;
  */
 declare function createAuth(options?: AuthOptions): AuthRegistry;
 
-export { Agent, type AgentConfig, type AgentEvent, AnthropicProvider, type AssistantMessage, type AuthFlowProviderOption, type AuthFlowState, type AuthFlowStep, type AuthMethod, type AuthMethodApiKey, type AuthMethodBaseUrlKey, type AuthMethodNone, type AuthOptions, AuthRegistry, type AuthStorage, type AuthType, type ChatOptions, type CompactionResult, type CompactionStrategy, type ContentPart, ContextManager, type DoneEvent, type ErrorEvent, FileAuthStorage, FileSession, FileSessionStore, type ImageContentPart, InMemorySession, type LLMProvider, MemoryAuthStorage, type Message, MockProvider, NoopCompaction, OpenAIProvider, PRESET_PROVIDERS, type PermissionConfig, type PermissionHandler, type PermissionRequest, type PermissionResult, type ProviderInfo, type ProviderRegistration, type ProviderTool, type Session, SlidingWindowCompaction, type StreamChunk, SummarizationCompaction, type SystemMessage, type TextContentPart, type TextEvent, type ThinkingEvent, type ToolCall, type ToolCallEvent, type ToolContext, type ToolDefinition, type ToolProgress, ToolRegistry, type ToolResult, type ToolResultEvent, type ToolResultMessage, type UsageEvent, type UserMessage, allowAll, allowReadOnly, createAuth, createPermissionHandler, denyAll, estimateTokens, estimateTotalTokens };
+export { Agent, type AgentConfig, type AgentEvent, AnthropicProvider, type AssistantMessage, type AuthFlowProviderOption, type AuthFlowState, type AuthFlowStep, type AuthMethod, type AuthMethodApiKey, type AuthMethodBaseUrlKey, type AuthMethodNone, type AuthOptions, AuthRegistry, type AuthStorage, type AuthType, type ChatOptions, type CompactionResult, type CompactionStrategy, type ContentPart, ContextManager, type DoneEvent, type ErrorEvent, FileAuthStorage, FileSession, FileSessionStore, type ImageContentPart, InMemorySession, type LLMProvider, MCPClient, type MCPConfig, type MCPHttpServerConfig, type MCPServerConfig, type MCPStdioServerConfig, MemoryAuthStorage, type Message, MockProvider, NoopCompaction, OpenAIProvider, PRESET_PROVIDERS, type PermissionConfig, type PermissionHandler, type PermissionRequest, type PermissionResult, type ProviderInfo, type ProviderRegistration, type ProviderTool, type Session, SlidingWindowCompaction, type StreamChunk, SummarizationCompaction, type SystemMessage, type TextContentPart, type TextEvent, type ThinkingEvent, type ToolCall, type ToolCallEvent, type ToolContext, type ToolDefinition, type ToolProgress, ToolRegistry, type ToolResult, type ToolResultEvent, type ToolResultMessage, type UsageEvent, type UserMessage, allowAll, allowReadOnly, createAuth, createPermissionHandler, denyAll, estimateTokens, estimateTotalTokens };

package/dist/index.d.ts

@@ -73,6 +73,9 @@ interface ToolDefinition<TInput = unknown> {
     isDestructive?: boolean;
     requiresConfirmation?: boolean;
     timeout?: number;
+    /** Original JSON Schema from an MCP server, used by toolToProviderFormat() to
+     *  avoid a lossy Zod -> JSON Schema round-trip for MCP-discovered tools. */
+    rawInputSchema?: Record<string, unknown>;
 }
 type StreamChunk = {
     type: "text";
@@ -178,11 +181,34 @@ interface Session {
 interface CompactionStrategy {
     compact(messages: Message[], maxTokens: number): Message[] | Promise<Message[]>;
 }
+/** Stdio-based MCP server: spawns a subprocess. */
+interface MCPStdioServerConfig {
+    name: string;
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    /** Timeout in ms for the initial connection (default: 30000). */
+    connectTimeout?: number;
+}
+/** HTTP-based MCP server: connects via Streamable HTTP transport. */
+interface MCPHttpServerConfig {
+    name: string;
+    url: string;
+    headers?: Record<string, string>;
+    /** Timeout in ms for the initial connection (default: 30000). */
+    connectTimeout?: number;
+}
+type MCPServerConfig = MCPStdioServerConfig | MCPHttpServerConfig;
+interface MCPConfig {
+    servers: MCPServerConfig[];
+}
 interface AgentConfig {
     provider: LLMProvider;
     model: string;
     systemPrompt?: string;
     tools?: ToolDefinition[];
+    mcp?: MCPConfig;
     maxTokens?: number;
     temperature?: number;
     contextLimit?: number;
@@ -191,6 +217,33 @@ interface AgentConfig {
     permissionHandler?: PermissionHandler;
     workingDirectory?: string;
     maxTurns?: number;
+    /** Max number of tools to execute concurrently (default: 5). */
+    maxConcurrentTools?: number;
+}
+
+declare class MCPClient {
+    private config;
+    private client;
+    private transport;
+    private _tools;
+    private _connected;
+    constructor(config: MCPServerConfig);
+    get name(): string;
+    get connected(): boolean;
+    get tools(): ToolDefinition[];
+    /**
+     * Connect to the MCP server and discover available tools.
+     * Throws if the SDK is not installed or the server fails to connect.
+     */
+    connect(): Promise<void>;
+    /**
+     * Refresh the tool list from the server.
+     */
+    discoverTools(): Promise<ToolDefinition[]>;
+    /**
+     * Disconnect from the MCP server and clean up resources.
+     */
+    disconnect(): Promise<void>;
 }
 
 /**
@@ -211,7 +264,12 @@ declare class Agent {
     private contextManager;
     private permissionHandler;
     private workingDirectory;
+    private maxConcurrentTools;
     private abortController;
+    private mcpClients;
+    private mcpConfig?;
+    private mcpInitialized;
+    private mcpInitPromise?;
     constructor(config: AgentConfig);
     /**
      * Run the agent loop. Yields events as the agent processes the input.
@@ -243,7 +301,18 @@ declare class Agent {
     removeTool(name: string): boolean;
     /** Replace the permission handler at runtime. */
     setPermissionHandler(handler: PermissionHandler): void;
-    private executeToolCalls;
+    /** Get the list of active MCP clients. */
+    getMCPClients(): MCPClient[];
+    /**
+     * Disconnect all MCP servers and clean up resources.
+     * Call this when the agent is no longer needed.
+     */
+    disconnectMCP(): Promise<void>;
+    /**
+     * Connect to configured MCP servers and register their tools.
+     * Servers that fail to connect are skipped with a warning (non-fatal).
+     */
+    private initializeMCP;
 }
 
 /**
@@ -719,4 +788,4 @@ declare const PRESET_PROVIDERS: Record<string, ProviderRegistration>;
  */
 declare function createAuth(options?: AuthOptions): AuthRegistry;
 
-export { Agent, type AgentConfig, type AgentEvent, AnthropicProvider, type AssistantMessage, type AuthFlowProviderOption, type AuthFlowState, type AuthFlowStep, type AuthMethod, type AuthMethodApiKey, type AuthMethodBaseUrlKey, type AuthMethodNone, type AuthOptions, AuthRegistry, type AuthStorage, type AuthType, type ChatOptions, type CompactionResult, type CompactionStrategy, type ContentPart, ContextManager, type DoneEvent, type ErrorEvent, FileAuthStorage, FileSession, FileSessionStore, type ImageContentPart, InMemorySession, type LLMProvider, MemoryAuthStorage, type Message, MockProvider, NoopCompaction, OpenAIProvider, PRESET_PROVIDERS, type PermissionConfig, type PermissionHandler, type PermissionRequest, type PermissionResult, type ProviderInfo, type ProviderRegistration, type ProviderTool, type Session, SlidingWindowCompaction, type StreamChunk, SummarizationCompaction, type SystemMessage, type TextContentPart, type TextEvent, type ThinkingEvent, type ToolCall, type ToolCallEvent, type ToolContext, type ToolDefinition, type ToolProgress, ToolRegistry, type ToolResult, type ToolResultEvent, type ToolResultMessage, type UsageEvent, type UserMessage, allowAll, allowReadOnly, createAuth, createPermissionHandler, denyAll, estimateTokens, estimateTotalTokens };
+export { Agent, type AgentConfig, type AgentEvent, AnthropicProvider, type AssistantMessage, type AuthFlowProviderOption, type AuthFlowState, type AuthFlowStep, type AuthMethod, type AuthMethodApiKey, type AuthMethodBaseUrlKey, type AuthMethodNone, type AuthOptions, AuthRegistry, type AuthStorage, type AuthType, type ChatOptions, type CompactionResult, type CompactionStrategy, type ContentPart, ContextManager, type DoneEvent, type ErrorEvent, FileAuthStorage, FileSession, FileSessionStore, type ImageContentPart, InMemorySession, type LLMProvider, MCPClient, type MCPConfig, type MCPHttpServerConfig, type MCPServerConfig, type MCPStdioServerConfig, MemoryAuthStorage, type Message, MockProvider, NoopCompaction, OpenAIProvider, PRESET_PROVIDERS, type PermissionConfig, type PermissionHandler, type PermissionRequest, type PermissionResult, type ProviderInfo, type ProviderRegistration, type ProviderTool, type Session, SlidingWindowCompaction, type StreamChunk, SummarizationCompaction, type SystemMessage, type TextContentPart, type TextEvent, type ThinkingEvent, type ToolCall, type ToolCallEvent, type ToolContext, type ToolDefinition, type ToolProgress, ToolRegistry, type ToolResult, type ToolResultEvent, type ToolResultMessage, type UsageEvent, type UserMessage, allowAll, allowReadOnly, createAuth, createPermissionHandler, denyAll, estimateTokens, estimateTotalTokens };

package/dist/index.js

@@ -38,6 +38,7 @@ __export(index_exports, {
   FileSession: () => FileSession,
   FileSessionStore: () => FileSessionStore,
   InMemorySession: () => InMemorySession,
+  MCPClient: () => MCPClient,
   MemoryAuthStorage: () => MemoryAuthStorage,
   MockProvider: () => MockProvider,
   NoopCompaction: () => NoopCompaction,
@@ -134,6 +135,284 @@ var ContextManager = class {
   }
 };
 
+// src/mcp-client.ts
+var import_zod = require("zod");
+var VALID_SERVER_NAME = /^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$/;
+var DEFAULT_CONNECT_TIMEOUT = 3e4;
+var MCPClient = class {
+  config;
+  client = null;
+  transport = null;
+  _tools = [];
+  _connected = false;
+  constructor(config) {
+    if (!VALID_SERVER_NAME.test(config.name)) {
+      throw new Error(
+        `Invalid MCP server name "${config.name}": must match [a-zA-Z0-9_-] with no consecutive underscores (__).`
+      );
+    }
+    this.config = config;
+  }
+  get name() {
+    return this.config.name;
+  }
+  get connected() {
+    return this._connected;
+  }
+  get tools() {
+    return this._tools;
+  }
+  /**
+   * Connect to the MCP server and discover available tools.
+   * Throws if the SDK is not installed or the server fails to connect.
+   */
+  async connect() {
+    if (this._connected) return;
+    const sdk = await loadMCPSdk();
+    this.client = new sdk.Client(
+      { name: "claude-code-kit", version: "0.2.0" },
+      { capabilities: {} }
+    );
+    this.transport = isStdioConfig(this.config) ? new sdk.StdioClientTransport({
+      command: this.config.command,
+      args: this.config.args,
+      env: this.config.env,
+      cwd: this.config.cwd,
+      stderr: "pipe"
+    }) : new sdk.StreamableHTTPClientTransport(new URL(this.config.url), {
+      requestInit: this.config.headers ? { headers: this.config.headers } : void 0
+    });
+    const timeout = this.config.connectTimeout ?? DEFAULT_CONNECT_TIMEOUT;
+    const connectPromise = this.client.connect(this.transport);
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(
+        () => reject(new Error(`MCP server "${this.config.name}" connection timed out after ${timeout}ms`)),
+        timeout
+      );
+    });
+    await Promise.race([connectPromise, timeoutPromise]);
+    this._connected = true;
+    await this.discoverTools();
+  }
+  /**
+   * Refresh the tool list from the server.
+   */
+  async discoverTools() {
+    if (!this.client) {
+      throw new Error(`MCP client "${this.config.name}" is not connected`);
+    }
+    const result = await this.client.listTools();
+    const serverName = this.config.name;
+    this._tools = result.tools.map(
+      (mcpTool) => convertMCPTool(mcpTool, serverName, this.client)
+    );
+    return this._tools;
+  }
+  /**
+   * Disconnect from the MCP server and clean up resources.
+   */
+  async disconnect() {
+    if (!this._connected) return;
+    try {
+      await this.transport?.close();
+    } catch {
+    }
+    this.client = null;
+    this.transport = null;
+    this._tools = [];
+    this._connected = false;
+  }
+};
+function convertMCPTool(mcpTool, serverName, client) {
+  const qualifiedName = `mcp__${serverName}__${mcpTool.name}`;
+  const inputSchema = import_zod.z.record(import_zod.z.string(), import_zod.z.unknown());
+  const originalJsonSchema = mcpTool.inputSchema;
+  const isReadOnly = mcpTool.annotations?.readOnlyHint === true;
+  const isDestructive = mcpTool.annotations?.destructiveHint === true;
+  const tool = {
+    name: qualifiedName,
+    description: mcpTool.description ?? `MCP tool from ${serverName}`,
+    inputSchema,
+    isReadOnly,
+    isDestructive,
+    rawInputSchema: originalJsonSchema,
+    async execute(input, _context) {
+      try {
+        const result = await client.callTool({
+          name: mcpTool.name,
+          arguments: input
+        });
+        const content = extractTextContent(result);
+        const isError = "isError" in result ? result.isError === true : false;
+        return { content, isError };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: `MCP tool "${mcpTool.name}" (${serverName}) failed: ${message}`,
+          isError: true
+        };
+      }
+    }
+  };
+  return tool;
+}
+function extractTextContent(result) {
+  if (!result.content || !Array.isArray(result.content)) {
+    return JSON.stringify(result);
+  }
+  const parts = [];
+  for (const part of result.content) {
+    if (typeof part === "object" && part !== null) {
+      if ("text" in part && typeof part.text === "string") {
+        parts.push(part.text);
+      } else if ("data" in part && typeof part.data === "string") {
+        const mimeType = "mimeType" in part && typeof part.mimeType === "string" ? part.mimeType : "unknown";
+        parts.push(`[binary content: ${mimeType}]`);
+      } else {
+        parts.push(JSON.stringify(part));
+      }
+    }
+  }
+  return parts.join("\n") || "(empty result)";
+}
+var _sdkCache;
+async function loadMCPSdk() {
+  if (_sdkCache) return _sdkCache;
+  try {
+    const clientMod = await import("@modelcontextprotocol/sdk/client");
+    const stdioMod = await import("@modelcontextprotocol/sdk/client/stdio.js");
+    const httpMod = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+    const sdk = {
+      Client: clientMod.Client,
+      StdioClientTransport: stdioMod.StdioClientTransport,
+      StreamableHTTPClientTransport: httpMod.StreamableHTTPClientTransport
+    };
+    _sdkCache = sdk;
+    return sdk;
+  } catch {
+    throw new Error(
+      "MCP support requires @modelcontextprotocol/sdk. Install it: pnpm add @modelcontextprotocol/sdk"
+    );
+  }
+}
+function isStdioConfig(config) {
+  return "command" in config;
+}
+
+// src/parallel-tools.ts
+var DEFAULT_MAX_CONCURRENT = 5;
+async function executeToolCalls(options) {
+  const {
+    toolCalls,
+    toolRegistry,
+    permissionHandler,
+    context,
+    parseErrors,
+    maxConcurrent = DEFAULT_MAX_CONCURRENT
+  } = options;
+  const results = new Array(toolCalls.length);
+  const executionPlan = buildExecutionPlan(toolCalls, toolRegistry);
+  for (const group of executionPlan) {
+    if (group.kind === "parallel") {
+      await executeParallelGroup(group.entries, results, {
+        toolRegistry,
+        permissionHandler,
+        context,
+        parseErrors,
+        maxConcurrent
+      });
+    } else {
+      const entry = group.entries[0];
+      results[entry.index] = await executeSingleToolCall(
+        entry.toolCall,
+        toolRegistry,
+        permissionHandler,
+        context,
+        parseErrors
+      );
+    }
+  }
+  return results;
+}
+function buildExecutionPlan(toolCalls, registry) {
+  const groups = [];
+  let currentParallelBatch = [];
+  for (let i = 0; i < toolCalls.length; i++) {
+    const tc = toolCalls[i];
+    const toolDef = registry.get(tc.name);
+    const isReadOnly = toolDef?.isReadOnly === true;
+    if (isReadOnly) {
+      currentParallelBatch.push({ index: i, toolCall: tc });
+    } else {
+      if (currentParallelBatch.length > 0) {
+        groups.push({ kind: "parallel", entries: currentParallelBatch });
+        currentParallelBatch = [];
+      }
+      groups.push({ kind: "sequential", entries: [{ index: i, toolCall: tc }] });
+    }
+  }
+  if (currentParallelBatch.length > 0) {
+    groups.push({ kind: "parallel", entries: currentParallelBatch });
+  }
+  return groups;
+}
+async function executeParallelGroup(entries, results, opts) {
+  for (let i = 0; i < entries.length; i += opts.maxConcurrent) {
+    const batch = entries.slice(i, i + opts.maxConcurrent);
+    const promises = batch.map(async (entry) => {
+      results[entry.index] = await executeSingleToolCall(
+        entry.toolCall,
+        opts.toolRegistry,
+        opts.permissionHandler,
+        opts.context,
+        opts.parseErrors
+      );
+    });
+    await Promise.all(promises);
+  }
+}
+async function executeSingleToolCall(tc, toolRegistry, permissionHandler, context, parseErrors) {
+  const parseError = parseErrors?.get(tc.id);
+  if (parseError) {
+    return {
+      role: "tool",
+      toolCallId: tc.id,
+      content: parseError,
+      isError: true
+    };
+  }
+  try {
+    const toolDef = toolRegistry.get(tc.name);
+    const permissionResult = await permissionHandler({
+      tool: tc.name,
+      input: tc.input,
+      isReadOnly: toolDef?.isReadOnly
+    });
+    if (permissionResult.decision === "deny") {
+      return {
+        role: "tool",
+        toolCallId: tc.id,
+        content: `Permission denied for tool "${tc.name}"${permissionResult.reason ? `: ${permissionResult.reason}` : ""}`,
+        isError: true
+      };
+    }
+    const result = await toolRegistry.execute(tc.name, tc.input, context);
+    return {
+      role: "tool",
+      toolCallId: tc.id,
+      content: result.content,
+      isError: result.isError
+    };
+  } catch (error) {
+    return {
+      role: "tool",
+      toolCallId: tc.id,
+      content: `Permission error: ${error instanceof Error ? error.message : String(error)}`,
+      isError: true
+    };
+  }
+}
+
 // src/permission.ts
 function createPermissionHandler(config) {
   return async (request) => {
@@ -185,10 +464,10 @@ var InMemorySession = class {
 };
 
 // src/tool-formatter.ts
-var import_zod = require("zod");
+var import_zod2 = require("zod");
 function zodToInputSchema(schema) {
-  if (typeof import_zod.z.toJSONSchema === "function") {
-    const jsonSchema = import_zod.z.toJSONSchema(schema);
+  if (typeof import_zod2.z.toJSONSchema === "function") {
+    const jsonSchema = import_zod2.z.toJSONSchema(schema);
     const { $schema: _, ...rest } = jsonSchema;
     return rest;
   }
@@ -205,7 +484,7 @@ function toolToProviderFormat(tool) {
   return {
     name: tool.name,
     description: tool.description,
-    inputSchema: zodToInputSchema(tool.inputSchema)
+    inputSchema: tool.rawInputSchema ?? zodToInputSchema(tool.inputSchema)
   };
 }
 
@@ -269,6 +548,7 @@ var ToolRegistry = class {
 
 // src/agent.ts
 var DEFAULT_MAX_TURNS = 50;
+var DEFAULT_MAX_CONCURRENT_TOOLS = 5;
 var Agent = class {
   provider;
   model;
@@ -281,7 +561,12 @@ var Agent = class {
   contextManager;
   permissionHandler;
   workingDirectory;
+  maxConcurrentTools;
   abortController = null;
+  mcpClients = [];
+  mcpConfig;
+  mcpInitialized = false;
+  mcpInitPromise;
   constructor(config) {
     this.provider = config.provider;
     this.model = config.model;
@@ -289,9 +574,11 @@ var Agent = class {
     this.maxTokens = config.maxTokens;
     this.temperature = config.temperature;
     this.maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
+    this.maxConcurrentTools = config.maxConcurrentTools ?? DEFAULT_MAX_CONCURRENT_TOOLS;
     this.session = config.session ?? new InMemorySession();
     this.permissionHandler = config.permissionHandler ?? allowReadOnly;
     this.workingDirectory = config.workingDirectory ?? process.cwd();
+    this.mcpConfig = config.mcp;
     this.toolRegistry = new ToolRegistry();
     if (config.tools) {
       for (const tool of config.tools) {
@@ -317,6 +604,10 @@ var Agent = class {
    */
   async *run(input) {
     this.abortController = new AbortController();
+    if (this.mcpConfig && !this.mcpInitialized) {
+      this.mcpInitPromise ??= this.initializeMCP();
+      await this.mcpInitPromise;
+    }
     const messages = this.session.getMessages();
     if (typeof input === "string") {
       messages.push({ role: "user", content: input });
@@ -429,7 +720,17 @@ var Agent = class {
       msgs.push(assistantMessage);
       this.session.setMessages(msgs);
       if (accumulatedToolCalls.length > 0) {
-        const toolResults = await this.executeToolCalls(accumulatedToolCalls, toolParseErrors);
+        const toolResults = await executeToolCalls({
+          toolCalls: accumulatedToolCalls,
+          toolRegistry: this.toolRegistry,
+          permissionHandler: this.permissionHandler,
+          context: {
+            workingDirectory: this.workingDirectory,
+            abortSignal: this.abortController?.signal ?? AbortSignal.timeout(12e4)
+          },
+          parseErrors: toolParseErrors,
+          maxConcurrent: this.maxConcurrentTools
+        });
         const currentMsgs = this.session.getMessages();
         for (const result of toolResults) {
           yield {
@@ -497,50 +798,72 @@ var Agent = class {
   setPermissionHandler(handler) {
     this.permissionHandler = handler;
   }
+  /** Get the list of active MCP clients. */
+  getMCPClients() {
+    return [...this.mcpClients];
+  }
+  /**
+   * Disconnect all MCP servers and clean up resources.
+   * Call this when the agent is no longer needed.
+   */
+  async disconnectMCP() {
+    const toolNames = [];
+    for (const client of this.mcpClients) {
+      for (const tool of client.tools) {
+        toolNames.push(tool.name);
+      }
+    }
+    for (const name of toolNames) {
+      this.toolRegistry.unregister(name);
+    }
+    const errors = [];
+    for (const client of this.mcpClients) {
+      try {
+        await client.disconnect();
+      } catch (error) {
+        errors.push(
+          error instanceof Error ? error : new Error(String(error))
+        );
+      }
+    }
+    this.mcpClients = [];
+    this.mcpInitialized = false;
+    this.mcpInitPromise = void 0;
+    if (errors.length > 0) {
+      throw new AggregateError(errors, "Some MCP servers failed to disconnect");
+    }
+  }
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------
-  async executeToolCalls(toolCalls, parseErrors) {
-    const results = [];
-    for (const tc of toolCalls) {
-      const parseError = parseErrors?.get(tc.id);
-      if (parseError) {
-        results.push({
-          role: "tool",
-          toolCallId: tc.id,
-          content: parseError,
-          isError: true
-        });
-        continue;
-      }
-      const toolDef = this.toolRegistry.get(tc.name);
-      const permissionResult = await this.permissionHandler({
-        tool: tc.name,
-        input: tc.input,
-        isReadOnly: toolDef?.isReadOnly
-      });
-      if (permissionResult.decision === "deny") {
-        results.push({
-          role: "tool",
-          toolCallId: tc.id,
-          content: `Permission denied for tool "${tc.name}"${permissionResult.reason ? `: ${permissionResult.reason}` : ""}`,
-          isError: true
-        });
-        continue;
+  /**
+   * Connect to configured MCP servers and register their tools.
+   * Servers that fail to connect are skipped with a warning (non-fatal).
+   */
+  async initializeMCP() {
+    if (!this.mcpConfig?.servers.length) {
+      this.mcpInitialized = true;
+      return;
+    }
+    const results = await Promise.allSettled(
+      this.mcpConfig.servers.map(async (serverConfig) => {
+        const client = new MCPClient(serverConfig);
+        await client.connect();
+        return client;
+      })
+    );
+    for (const result of results) {
+      if (result.status === "fulfilled") {
+        const client = result.value;
+        this.mcpClients.push(client);
+        for (const tool of client.tools) {
+          if (!this.toolRegistry.has(tool.name)) {
+            this.toolRegistry.register(tool);
+          }
+        }
       }
-      const context = {
-        workingDirectory: this.workingDirectory,
-        abortSignal: this.abortController?.signal ?? AbortSignal.timeout(12e4)
-      };
-      const result = await this.toolRegistry.execute(tc.name, tc.input, context);
-      results.push({
-        role: "tool",
-        toolCallId: tc.id,
-        content: result.content,
-        isError: result.isError
-      });
     }
-    return results;
+    this.mcpInitialized = true;
   }
 };
 function isContextTooLongError(error) {
@@ -1704,6 +2027,7 @@ function createAuth(options) {
   FileSession,
   FileSessionStore,
   InMemorySession,
+  MCPClient,
   MemoryAuthStorage,
   MockProvider,
   NoopCompaction,

package/dist/index.mjs

@@ -83,6 +83,284 @@ var ContextManager = class {
   }
 };
 
+// src/mcp-client.ts
+import { z } from "zod";
+var VALID_SERVER_NAME = /^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$/;
+var DEFAULT_CONNECT_TIMEOUT = 3e4;
+var MCPClient = class {
+  config;
+  client = null;
+  transport = null;
+  _tools = [];
+  _connected = false;
+  constructor(config) {
+    if (!VALID_SERVER_NAME.test(config.name)) {
+      throw new Error(
+        `Invalid MCP server name "${config.name}": must match [a-zA-Z0-9_-] with no consecutive underscores (__).`
+      );
+    }
+    this.config = config;
+  }
+  get name() {
+    return this.config.name;
+  }
+  get connected() {
+    return this._connected;
+  }
+  get tools() {
+    return this._tools;
+  }
+  /**
+   * Connect to the MCP server and discover available tools.
+   * Throws if the SDK is not installed or the server fails to connect.
+   */
+  async connect() {
+    if (this._connected) return;
+    const sdk = await loadMCPSdk();
+    this.client = new sdk.Client(
+      { name: "claude-code-kit", version: "0.2.0" },
+      { capabilities: {} }
+    );
+    this.transport = isStdioConfig(this.config) ? new sdk.StdioClientTransport({
+      command: this.config.command,
+      args: this.config.args,
+      env: this.config.env,
+      cwd: this.config.cwd,
+      stderr: "pipe"
+    }) : new sdk.StreamableHTTPClientTransport(new URL(this.config.url), {
+      requestInit: this.config.headers ? { headers: this.config.headers } : void 0
+    });
+    const timeout = this.config.connectTimeout ?? DEFAULT_CONNECT_TIMEOUT;
+    const connectPromise = this.client.connect(this.transport);
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(
+        () => reject(new Error(`MCP server "${this.config.name}" connection timed out after ${timeout}ms`)),
+        timeout
+      );
+    });
+    await Promise.race([connectPromise, timeoutPromise]);
+    this._connected = true;
+    await this.discoverTools();
+  }
+  /**
+   * Refresh the tool list from the server.
+   */
+  async discoverTools() {
+    if (!this.client) {
+      throw new Error(`MCP client "${this.config.name}" is not connected`);
+    }
+    const result = await this.client.listTools();
+    const serverName = this.config.name;
+    this._tools = result.tools.map(
+      (mcpTool) => convertMCPTool(mcpTool, serverName, this.client)
+    );
+    return this._tools;
+  }
+  /**
+   * Disconnect from the MCP server and clean up resources.
+   */
+  async disconnect() {
+    if (!this._connected) return;
+    try {
+      await this.transport?.close();
+    } catch {
+    }
+    this.client = null;
+    this.transport = null;
+    this._tools = [];
+    this._connected = false;
+  }
+};
+function convertMCPTool(mcpTool, serverName, client) {
+  const qualifiedName = `mcp__${serverName}__${mcpTool.name}`;
+  const inputSchema = z.record(z.string(), z.unknown());
+  const originalJsonSchema = mcpTool.inputSchema;
+  const isReadOnly = mcpTool.annotations?.readOnlyHint === true;
+  const isDestructive = mcpTool.annotations?.destructiveHint === true;
+  const tool = {
+    name: qualifiedName,
+    description: mcpTool.description ?? `MCP tool from ${serverName}`,
+    inputSchema,
+    isReadOnly,
+    isDestructive,
+    rawInputSchema: originalJsonSchema,
+    async execute(input, _context) {
+      try {
+        const result = await client.callTool({
+          name: mcpTool.name,
+          arguments: input
+        });
+        const content = extractTextContent(result);
+        const isError = "isError" in result ? result.isError === true : false;
+        return { content, isError };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: `MCP tool "${mcpTool.name}" (${serverName}) failed: ${message}`,
+          isError: true
+        };
+      }
+    }
+  };
+  return tool;
+}
+function extractTextContent(result) {
+  if (!result.content || !Array.isArray(result.content)) {
+    return JSON.stringify(result);
+  }
+  const parts = [];
+  for (const part of result.content) {
+    if (typeof part === "object" && part !== null) {
+      if ("text" in part && typeof part.text === "string") {
+        parts.push(part.text);
+      } else if ("data" in part && typeof part.data === "string") {
+        const mimeType = "mimeType" in part && typeof part.mimeType === "string" ? part.mimeType : "unknown";
+        parts.push(`[binary content: ${mimeType}]`);
+      } else {
+        parts.push(JSON.stringify(part));
+      }
+    }
+  }
+  return parts.join("\n") || "(empty result)";
+}
+var _sdkCache;
+async function loadMCPSdk() {
+  if (_sdkCache) return _sdkCache;
+  try {
+    const clientMod = await import("@modelcontextprotocol/sdk/client");
+    const stdioMod = await import("@modelcontextprotocol/sdk/client/stdio.js");
+    const httpMod = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+    const sdk = {
+      Client: clientMod.Client,
+      StdioClientTransport: stdioMod.StdioClientTransport,
+      StreamableHTTPClientTransport: httpMod.StreamableHTTPClientTransport
+    };
+    _sdkCache = sdk;
+    return sdk;
+  } catch {
+    throw new Error(
+      "MCP support requires @modelcontextprotocol/sdk. Install it: pnpm add @modelcontextprotocol/sdk"
+    );
+  }
+}
+function isStdioConfig(config) {
+  return "command" in config;
+}
+
+// src/parallel-tools.ts
+var DEFAULT_MAX_CONCURRENT = 5;
+async function executeToolCalls(options) {
+  const {
+    toolCalls,
+    toolRegistry,
+    permissionHandler,
+    context,
+    parseErrors,
+    maxConcurrent = DEFAULT_MAX_CONCURRENT
+  } = options;
+  const results = new Array(toolCalls.length);
+  const executionPlan = buildExecutionPlan(toolCalls, toolRegistry);
+  for (const group of executionPlan) {
+    if (group.kind === "parallel") {
+      await executeParallelGroup(group.entries, results, {
+        toolRegistry,
+        permissionHandler,
+        context,
+        parseErrors,
+        maxConcurrent
+      });
+    } else {
+      const entry = group.entries[0];
+      results[entry.index] = await executeSingleToolCall(
+        entry.toolCall,
+        toolRegistry,
+        permissionHandler,
+        context,
+        parseErrors
+      );
+    }
+  }
+  return results;
+}
+function buildExecutionPlan(toolCalls, registry) {
+  const groups = [];
+  let currentParallelBatch = [];
+  for (let i = 0; i < toolCalls.length; i++) {
+    const tc = toolCalls[i];
+    const toolDef = registry.get(tc.name);
+    const isReadOnly = toolDef?.isReadOnly === true;
+    if (isReadOnly) {
+      currentParallelBatch.push({ index: i, toolCall: tc });
+    } else {
+      if (currentParallelBatch.length > 0) {
+        groups.push({ kind: "parallel", entries: currentParallelBatch });
+        currentParallelBatch = [];
+      }
+      groups.push({ kind: "sequential", entries: [{ index: i, toolCall: tc }] });
+    }
+  }
+  if (currentParallelBatch.length > 0) {
+    groups.push({ kind: "parallel", entries: currentParallelBatch });
+  }
+  return groups;
+}
+async function executeParallelGroup(entries, results, opts) {
+  for (let i = 0; i < entries.length; i += opts.maxConcurrent) {
+    const batch = entries.slice(i, i + opts.maxConcurrent);
+    const promises = batch.map(async (entry) => {
+      results[entry.index] = await executeSingleToolCall(
+        entry.toolCall,
+        opts.toolRegistry,
+        opts.permissionHandler,
+        opts.context,
+        opts.parseErrors
+      );
+    });
+    await Promise.all(promises);
+  }
+}
+async function executeSingleToolCall(tc, toolRegistry, permissionHandler, context, parseErrors) {
+  const parseError = parseErrors?.get(tc.id);
+  if (parseError) {
+    return {
+      role: "tool",
+      toolCallId: tc.id,
+      content: parseError,
+      isError: true
+    };
+  }
+  try {
+    const toolDef = toolRegistry.get(tc.name);
+    const permissionResult = await permissionHandler({
+      tool: tc.name,
+      input: tc.input,
+      isReadOnly: toolDef?.isReadOnly
+    });
+    if (permissionResult.decision === "deny") {
+      return {
+        role: "tool",
+        toolCallId: tc.id,
+        content: `Permission denied for tool "${tc.name}"${permissionResult.reason ? `: ${permissionResult.reason}` : ""}`,
+        isError: true
+      };
+    }
+    const result = await toolRegistry.execute(tc.name, tc.input, context);
+    return {
+      role: "tool",
+      toolCallId: tc.id,
+      content: result.content,
+      isError: result.isError
+    };
+  } catch (error) {
+    return {
+      role: "tool",
+      toolCallId: tc.id,
+      content: `Permission error: ${error instanceof Error ? error.message : String(error)}`,
+      isError: true
+    };
+  }
+}
+
 // src/permission.ts
 function createPermissionHandler(config) {
   return async (request) => {
@@ -134,10 +412,10 @@ var InMemorySession = class {
 };
 
 // src/tool-formatter.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 function zodToInputSchema(schema) {
-  if (typeof z.toJSONSchema === "function") {
-    const jsonSchema = z.toJSONSchema(schema);
+  if (typeof z2.toJSONSchema === "function") {
+    const jsonSchema = z2.toJSONSchema(schema);
     const { $schema: _, ...rest } = jsonSchema;
     return rest;
   }
@@ -154,7 +432,7 @@ function toolToProviderFormat(tool) {
   return {
     name: tool.name,
     description: tool.description,
-    inputSchema: zodToInputSchema(tool.inputSchema)
+    inputSchema: tool.rawInputSchema ?? zodToInputSchema(tool.inputSchema)
   };
 }
 
@@ -218,6 +496,7 @@ var ToolRegistry = class {
 
 // src/agent.ts
 var DEFAULT_MAX_TURNS = 50;
+var DEFAULT_MAX_CONCURRENT_TOOLS = 5;
 var Agent = class {
   provider;
   model;
@@ -230,7 +509,12 @@ var Agent = class {
   contextManager;
   permissionHandler;
   workingDirectory;
+  maxConcurrentTools;
   abortController = null;
+  mcpClients = [];
+  mcpConfig;
+  mcpInitialized = false;
+  mcpInitPromise;
   constructor(config) {
     this.provider = config.provider;
     this.model = config.model;
@@ -238,9 +522,11 @@ var Agent = class {
     this.maxTokens = config.maxTokens;
     this.temperature = config.temperature;
     this.maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
+    this.maxConcurrentTools = config.maxConcurrentTools ?? DEFAULT_MAX_CONCURRENT_TOOLS;
     this.session = config.session ?? new InMemorySession();
     this.permissionHandler = config.permissionHandler ?? allowReadOnly;
     this.workingDirectory = config.workingDirectory ?? process.cwd();
+    this.mcpConfig = config.mcp;
     this.toolRegistry = new ToolRegistry();
     if (config.tools) {
       for (const tool of config.tools) {
@@ -266,6 +552,10 @@ var Agent = class {
    */
   async *run(input) {
     this.abortController = new AbortController();
+    if (this.mcpConfig && !this.mcpInitialized) {
+      this.mcpInitPromise ??= this.initializeMCP();
+      await this.mcpInitPromise;
+    }
     const messages = this.session.getMessages();
     if (typeof input === "string") {
       messages.push({ role: "user", content: input });
@@ -378,7 +668,17 @@ var Agent = class {
       msgs.push(assistantMessage);
       this.session.setMessages(msgs);
       if (accumulatedToolCalls.length > 0) {
-        const toolResults = await this.executeToolCalls(accumulatedToolCalls, toolParseErrors);
+        const toolResults = await executeToolCalls({
+          toolCalls: accumulatedToolCalls,
+          toolRegistry: this.toolRegistry,
+          permissionHandler: this.permissionHandler,
+          context: {
+            workingDirectory: this.workingDirectory,
+            abortSignal: this.abortController?.signal ?? AbortSignal.timeout(12e4)
+          },
+          parseErrors: toolParseErrors,
+          maxConcurrent: this.maxConcurrentTools
+        });
         const currentMsgs = this.session.getMessages();
         for (const result of toolResults) {
           yield {
@@ -446,50 +746,72 @@ var Agent = class {
   setPermissionHandler(handler) {
     this.permissionHandler = handler;
   }
+  /** Get the list of active MCP clients. */
+  getMCPClients() {
+    return [...this.mcpClients];
+  }
+  /**
+   * Disconnect all MCP servers and clean up resources.
+   * Call this when the agent is no longer needed.
+   */
+  async disconnectMCP() {
+    const toolNames = [];
+    for (const client of this.mcpClients) {
+      for (const tool of client.tools) {
+        toolNames.push(tool.name);
+      }
+    }
+    for (const name of toolNames) {
+      this.toolRegistry.unregister(name);
+    }
+    const errors = [];
+    for (const client of this.mcpClients) {
+      try {
+        await client.disconnect();
+      } catch (error) {
+        errors.push(
+          error instanceof Error ? error : new Error(String(error))
+        );
+      }
+    }
+    this.mcpClients = [];
+    this.mcpInitialized = false;
+    this.mcpInitPromise = void 0;
+    if (errors.length > 0) {
+      throw new AggregateError(errors, "Some MCP servers failed to disconnect");
+    }
+  }
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------
-  async executeToolCalls(toolCalls, parseErrors) {
-    const results = [];
-    for (const tc of toolCalls) {
-      const parseError = parseErrors?.get(tc.id);
-      if (parseError) {
-        results.push({
-          role: "tool",
-          toolCallId: tc.id,
-          content: parseError,
-          isError: true
-        });
-        continue;
-      }
-      const toolDef = this.toolRegistry.get(tc.name);
-      const permissionResult = await this.permissionHandler({
-        tool: tc.name,
-        input: tc.input,
-        isReadOnly: toolDef?.isReadOnly
-      });
-      if (permissionResult.decision === "deny") {
-        results.push({
-          role: "tool",
-          toolCallId: tc.id,
-          content: `Permission denied for tool "${tc.name}"${permissionResult.reason ? `: ${permissionResult.reason}` : ""}`,
-          isError: true
-        });
-        continue;
+  /**
+   * Connect to configured MCP servers and register their tools.
+   * Servers that fail to connect are skipped with a warning (non-fatal).
+   */
+  async initializeMCP() {
+    if (!this.mcpConfig?.servers.length) {
+      this.mcpInitialized = true;
+      return;
+    }
+    const results = await Promise.allSettled(
+      this.mcpConfig.servers.map(async (serverConfig) => {
+        const client = new MCPClient(serverConfig);
+        await client.connect();
+        return client;
+      })
+    );
+    for (const result of results) {
+      if (result.status === "fulfilled") {
+        const client = result.value;
+        this.mcpClients.push(client);
+        for (const tool of client.tools) {
+          if (!this.toolRegistry.has(tool.name)) {
+            this.toolRegistry.register(tool);
+          }
+        }
       }
-      const context = {
-        workingDirectory: this.workingDirectory,
-        abortSignal: this.abortController?.signal ?? AbortSignal.timeout(12e4)
-      };
-      const result = await this.toolRegistry.execute(tc.name, tc.input, context);
-      results.push({
-        role: "tool",
-        toolCallId: tc.id,
-        content: result.content,
-        isError: result.isError
-      });
     }
-    return results;
+    this.mcpInitialized = true;
   }
 };
 function isContextTooLongError(error) {
@@ -1652,6 +1974,7 @@ export {
   FileSession,
   FileSessionStore,
   InMemorySession,
+  MCPClient,
   MemoryAuthStorage,
   MockProvider,
   NoopCompaction,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-code-kit/agent",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Headless agent framework for claude-code-kit — LLM query loop, tool execution, multi-provider",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -17,11 +17,17 @@
       "require": "./dist/index.js"
     }
   },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "biome check src/"
+  },
   "dependencies": {
     "zod": ">=3.20.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.30.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "openai": ">=4.0.0",
     "zod-to-json-schema": ">=3.20.0"
   },
@@ -29,6 +35,9 @@
     "@anthropic-ai/sdk": {
       "optional": true
     },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
     "openai": {
       "optional": true
     },
@@ -38,6 +47,7 @@
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "*",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "openai": "*",
     "tsup": "*",
     "typescript": "*"
@@ -62,10 +72,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "lint": "biome check src/"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Minnzen
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.