@mcpjam/sdk 0.1.4 → 0.8.1

package/dist/index.d.ts

@@ -1,9 +1,1942 @@
-export { ElicitationHandler, ExecuteToolArguments, MCPClientManager, MCPClientManagerConfig, MCPConnectionStatus, MCPConvertedToolSet, MCPGetPromptResult, MCPPrompt, MCPPromptListResult, MCPReadResourceResult, MCPResource, MCPResourceListResult, MCPServerConfig, MCPServerSummary, MCPToolSchemaOverrides } from './mcp-client-manager/index.js';
-import 'zod';
-import '@modelcontextprotocol/sdk/client/index.js';
-import '@modelcontextprotocol/sdk/client/sse.js';
-import '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import '@modelcontextprotocol/sdk/shared/protocol.js';
-import '@modelcontextprotocol/sdk/types.js';
-import 'ai';
-import '@ai-sdk/provider-utils';
+import { ClientOptions, Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransportOptions } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { SSEClientTransportOptions } from '@modelcontextprotocol/sdk/client/sse.js';
+import { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import { ElicitResult, ElicitRequest, Tool as Tool$1, CallToolResult, ServerCapabilities, LoggingLevel } from '@modelcontextprotocol/sdk/types.js';
+export { ElicitResult } from '@modelcontextprotocol/sdk/types.js';
+import { ToolSet, dynamicTool, AssistantModelMessage, ModelMessage, ToolModelMessage, UserModelMessage } from 'ai';
+import { createOpenAI } from '@ai-sdk/openai';
+
+/**
+ * TypeScript types and interfaces for MCPClientManager
+ */
+
+/**
+ * Client capability options extracted from MCP SDK ClientOptions
+ */
+type ClientCapabilityOptions = NonNullable<ClientOptions["capabilities"]>;
+/**
+ * Base configuration shared by all server types
+ */
+type BaseServerConfig = {
+    /** Client capabilities to advertise to this server */
+    capabilities?: ClientCapabilityOptions;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Client version to report */
+    version?: string;
+    /** Error handler for this server */
+    onError?: (error: unknown) => void;
+    /** Enable simple console logging of JSON-RPC traffic */
+    logJsonRpc?: boolean;
+    /** Custom logger for JSON-RPC traffic (overrides logJsonRpc) */
+    rpcLogger?: RpcLogger;
+};
+/**
+ * Configuration for stdio-based MCP servers (subprocess)
+ */
+type StdioServerConfig = BaseServerConfig & {
+    /** Command to execute */
+    command: string;
+    /** Command arguments */
+    args?: string[];
+    /** Environment variables */
+    env?: Record<string, string>;
+    url?: never;
+    accessToken?: never;
+    requestInit?: never;
+    eventSourceInit?: never;
+    authProvider?: never;
+    reconnectionOptions?: never;
+    sessionId?: never;
+    preferSSE?: never;
+};
+/**
+ * Configuration for HTTP-based MCP servers (SSE or Streamable HTTP)
+ */
+type HttpServerConfig = BaseServerConfig & {
+    /** Server URL */
+    url: string;
+    /**
+     * Access token for Bearer authentication.
+     * If provided, adds `Authorization: Bearer <accessToken>` header to requests.
+     */
+    accessToken?: string;
+    /** Additional request initialization options */
+    requestInit?: StreamableHTTPClientTransportOptions["requestInit"];
+    /** SSE-specific event source options */
+    eventSourceInit?: SSEClientTransportOptions["eventSourceInit"];
+    /** OAuth auth provider */
+    authProvider?: StreamableHTTPClientTransportOptions["authProvider"];
+    /** Reconnection options for Streamable HTTP */
+    reconnectionOptions?: StreamableHTTPClientTransportOptions["reconnectionOptions"];
+    /** Session ID for Streamable HTTP */
+    sessionId?: StreamableHTTPClientTransportOptions["sessionId"];
+    /** Prefer SSE transport over Streamable HTTP */
+    preferSSE?: boolean;
+    command?: never;
+    args?: never;
+    env?: never;
+};
+/**
+ * Union type for all server configurations
+ */
+type MCPServerConfig = StdioServerConfig | HttpServerConfig;
+/**
+ * Configuration map for multiple servers (serverId -> config)
+ */
+type MCPClientManagerConfig = Record<string, MCPServerConfig>;
+/**
+ * Connection status for a server
+ */
+type MCPConnectionStatus = "connected" | "connecting" | "disconnected";
+/**
+ * Summary information for a server
+ */
+type ServerSummary = {
+    id: string;
+    status: MCPConnectionStatus;
+    config?: MCPServerConfig;
+};
+/**
+ * Event passed to RPC loggers
+ */
+type RpcLogEvent = {
+    direction: "send" | "receive";
+    message: unknown;
+    serverId: string;
+};
+/**
+ * Function type for JSON-RPC logging
+ */
+type RpcLogger = (event: RpcLogEvent) => void;
+/**
+ * Progress event from server operations
+ */
+type ProgressEvent = {
+    serverId: string;
+    progressToken: string | number;
+    progress: number;
+    total?: number;
+    message?: string;
+};
+/**
+ * Function type for progress handling
+ */
+type ProgressHandler = (event: ProgressEvent) => void;
+/**
+ * Options for MCPClientManager constructor
+ */
+interface MCPClientManagerOptions {
+    /** Default client name to report to servers */
+    defaultClientName?: string;
+    /** Default client version to report */
+    defaultClientVersion?: string;
+    /** Default capabilities to advertise */
+    defaultCapabilities?: ClientCapabilityOptions;
+    /** Default request timeout in milliseconds */
+    defaultTimeout?: number;
+    /** Enable JSON-RPC logging for all servers by default */
+    defaultLogJsonRpc?: boolean;
+    /** Global JSON-RPC logger */
+    rpcLogger?: RpcLogger;
+    /** Global progress handler */
+    progressHandler?: ProgressHandler;
+}
+/**
+ * Arguments passed to tool execution
+ */
+type ExecuteToolArguments = Record<string, unknown>;
+/**
+ * Options for task-augmented tool calls
+ */
+type TaskOptions = {
+    /** Time-to-live for the task in milliseconds */
+    ttl?: number;
+};
+/**
+ * Handler for server-specific elicitation requests
+ */
+type ElicitationHandler = (params: ElicitRequest["params"]) => Promise<ElicitResult> | ElicitResult;
+/**
+ * Request passed to global elicitation callback
+ */
+type ElicitationCallbackRequest = {
+    requestId: string;
+    message: string;
+    schema: unknown;
+    /** Task ID if this elicitation is related to a task (MCP Tasks spec 2025-11-25) */
+    relatedTaskId?: string;
+};
+/**
+ * Global callback for handling elicitation requests
+ */
+type ElicitationCallback = (request: ElicitationCallbackRequest) => Promise<ElicitResult> | ElicitResult;
+/**
+ * Task status values
+ */
+type MCPTaskStatus = "working" | "input_required" | "completed" | "failed" | "cancelled";
+/**
+ * MCP Task object
+ */
+type MCPTask = {
+    taskId: string;
+    status: MCPTaskStatus;
+    statusMessage?: string;
+    createdAt: string;
+    lastUpdatedAt: string;
+    ttl: number | null;
+    pollInterval?: number;
+};
+/**
+ * Result from listing tasks
+ */
+type MCPListTasksResult = {
+    tasks: MCPTask[];
+    nextCursor?: string;
+};
+type ClientRequestOptions = RequestOptions;
+type ListResourcesParams = Parameters<Client["listResources"]>[0];
+type ListResourceTemplatesParams = Parameters<Client["listResourceTemplates"]>[0];
+type ReadResourceParams = Parameters<Client["readResource"]>[0];
+type SubscribeResourceParams = Parameters<Client["subscribeResource"]>[0];
+type UnsubscribeResourceParams = Parameters<Client["unsubscribeResource"]>[0];
+type ListPromptsParams = Parameters<Client["listPrompts"]>[0];
+type GetPromptParams = Parameters<Client["getPrompt"]>[0];
+type ListToolsResult = Awaited<ReturnType<Client["listTools"]>>;
+type MCPPromptListResult = Awaited<ReturnType<Client["listPrompts"]>>;
+type MCPPrompt = MCPPromptListResult["prompts"][number];
+type MCPGetPromptResult = Awaited<ReturnType<Client["getPrompt"]>>;
+type MCPResourceListResult = Awaited<ReturnType<Client["listResources"]>>;
+type MCPResource = MCPResourceListResult["resources"][number];
+type MCPReadResourceResult = Awaited<ReturnType<Client["readResource"]>>;
+type MCPResourceTemplateListResult = Awaited<ReturnType<Client["listResourceTemplates"]>>;
+type MCPResourceTemplate = MCPResourceTemplateListResult["resourceTemplates"][number];
+type MCPServerSummary = ServerSummary;
+/**
+ * An MCP tool with an execute function pre-wired to call the manager.
+ * Extends the official MCP SDK Tool type.
+ * Returned by MCPClientManager.getTools().
+ */
+/** Options for tool execution */
+interface ToolExecuteOptions {
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+interface Tool extends Tool$1 {
+    /** Execute the tool with the given arguments */
+    execute: (args: Record<string, unknown>, options?: ToolExecuteOptions) => Promise<CallToolResult>;
+    _meta?: {
+        _serverId: string;
+        [key: string]: unknown;
+    };
+}
+
+/**
+ * AI SDK compatible tool set (Record<string, CoreTool>).
+ * Returned by MCPClientManager.getToolsForAiSdk().
+ * Can be passed directly to AI SDK's generateText().
+ */
+type AiSdkTool = ToolSet;
+
+/**
+ * Notification handler management for MCPClientManager
+ */
+
+type NotificationSchema = Parameters<Client["setNotificationHandler"]>[0];
+type NotificationHandler = Parameters<Client["setNotificationHandler"]>[1];
+
+/**
+ * Tool conversion utilities for integrating MCP tools with Vercel AI SDK
+ */
+
+/**
+ * Input schema type for tool definitions
+ */
+type ToolInputSchema = Parameters<typeof dynamicTool>[0]["inputSchema"];
+/**
+ * Schema overrides for specific tools
+ * Maps tool name to custom input schema definition
+ */
+type ToolSchemaOverrides = Record<string, {
+    inputSchema: ToolInputSchema;
+}>;
+/**
+ * Checks whether a tool is an MCP App by inspecting its _meta for a UI resource URI.
+ *
+ * @param toolMeta - The tool's _meta field from listTools result
+ * @returns true if the tool is an MCP App
+ */
+declare function isMcpAppTool(toolMeta: Record<string, unknown> | undefined): boolean;
+/**
+ * Checks whether a tool is a ChatGPT App by inspecting its _meta for an output template.
+ *
+ * @param toolMeta - The tool's _meta field from listTools result
+ * @returns true if the tool is a ChatGPT App
+ */
+declare function isChatGPTAppTool(toolMeta: Record<string, unknown> | undefined): boolean;
+/**
+ * Removes only the _meta field from a tool result (shallow copy).
+ *
+ * @param result - The full tool call result
+ * @returns A shallow copy of the result without _meta
+ */
+declare function scrubMetaFromToolResult(result: CallToolResult): CallToolResult;
+/**
+ * Returns a shallow copy of a CallToolResult with _meta and structuredContent removed.
+ *
+ * @param result - The full tool call result
+ * @returns A scrubbed shallow copy without _meta and structuredContent
+ */
+declare function scrubMetaAndStructuredContentFromToolResult(result: CallToolResult): CallToolResult;
+
+/**
+ * Manages multiple MCP server connections with support for tools, resources,
+ * prompts, notifications, elicitation, and tasks.
+ *
+ * @example
+ * ```typescript
+ * const manager = new MCPClientManager({
+ *   everything: {
+ *     command: "npx",
+ *     args: ["-y", "@modelcontextprotocol/server-everything"],
+ *   },
+ *   myServer: {
+ *     url: "https://my-server.com/mcp",
+ *     accessToken: "my-token",
+ *   },
+ * });
+ *
+ * const tools = await manager.listTools("everything");
+ * const result = await manager.executeTool("everything", "add", { a: 1, b: 2 });
+ * ```
+ */
+declare class MCPClientManager {
+    private readonly clientStates;
+    private readonly toolsMetadataCache;
+    private readonly notificationManager;
+    private readonly elicitationManager;
+    private readonly defaultClientName;
+    private readonly defaultClientVersion;
+    private readonly defaultCapabilities;
+    private readonly defaultTimeout;
+    private readonly defaultLogJsonRpc;
+    private readonly defaultRpcLogger?;
+    private readonly defaultProgressHandler?;
+    private progressTokenCounter;
+    /**
+     * Creates a new MCPClientManager.
+     *
+     * @param servers - Configuration map of server IDs to server configs
+     * @param options - Global options for the manager
+     */
+    constructor(servers?: MCPClientManagerConfig, options?: MCPClientManagerOptions);
+    /**
+     * Lists all registered server IDs.
+     */
+    listServers(): string[];
+    /**
+     * Checks if a server is registered.
+     */
+    hasServer(serverId: string): boolean;
+    /**
+     * Gets summaries for all registered servers.
+     */
+    getServerSummaries(): ServerSummary[];
+    /**
+     * Gets the connection status for a server.
+     */
+    getConnectionStatus(serverId: string): MCPConnectionStatus;
+    /**
+     * Gets the configuration for a server.
+     */
+    getServerConfig(serverId: string): MCPServerConfig | undefined;
+    /**
+     * Gets the capabilities reported by a server.
+     */
+    getServerCapabilities(serverId: string): ServerCapabilities | undefined;
+    /**
+     * Gets the underlying MCP Client for a server.
+     */
+    getClient(serverId: string): Client | undefined;
+    /**
+     * Gets initialization information for a connected server.
+     */
+    getInitializationInfo(serverId: string): {
+        protocolVersion: string | undefined;
+        transport: string;
+        serverCapabilities: {
+            experimental?: {
+                [x: string]: object;
+            } | undefined;
+            logging?: object | undefined;
+            completions?: object | undefined;
+            prompts?: {
+                listChanged?: boolean | undefined;
+            } | undefined;
+            resources?: {
+                subscribe?: boolean | undefined;
+                listChanged?: boolean | undefined;
+            } | undefined;
+            tools?: {
+                listChanged?: boolean | undefined;
+            } | undefined;
+            tasks?: {
+                [x: string]: unknown;
+                list?: object | undefined;
+                cancel?: object | undefined;
+                requests?: {
+                    [x: string]: unknown;
+                    tools?: {
+                        [x: string]: unknown;
+                        call?: object | undefined;
+                    } | undefined;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+        serverVersion: {
+            version: string;
+            name: string;
+            websiteUrl?: string | undefined;
+            description?: string | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        } | undefined;
+        instructions: string | undefined;
+        clientCapabilities: {
+            experimental?: {
+                [x: string]: object;
+            } | undefined;
+            sampling?: {
+                context?: object | undefined;
+                tools?: object | undefined;
+            } | undefined;
+            elicitation?: {
+                [x: string]: unknown;
+                form?: {
+                    [x: string]: unknown;
+                    applyDefaults?: boolean | undefined;
+                } | undefined;
+                url?: object | undefined;
+            } | undefined;
+            roots?: {
+                listChanged?: boolean | undefined;
+            } | undefined;
+            tasks?: {
+                [x: string]: unknown;
+                list?: object | undefined;
+                cancel?: object | undefined;
+                requests?: {
+                    [x: string]: unknown;
+                    sampling?: {
+                        [x: string]: unknown;
+                        createMessage?: object | undefined;
+                    } | undefined;
+                    elicitation?: {
+                        [x: string]: unknown;
+                        create?: object | undefined;
+                    } | undefined;
+                } | undefined;
+            } | undefined;
+        };
+    } | undefined;
+    /**
+     * Connects to an MCP server.
+     *
+     * @param serverId - Unique identifier for the server
+     * @param config - Server configuration
+     * @returns The connected MCP Client
+     */
+    connectToServer(serverId: string, config: MCPServerConfig): Promise<Client>;
+    /**
+     * Disconnects from a server.
+     */
+    disconnectServer(serverId: string): Promise<void>;
+    /**
+     * Removes a server from the manager entirely.
+     */
+    removeServer(serverId: string): Promise<void>;
+    /**
+     * Disconnects from all servers.
+     */
+    disconnectAllServers(): Promise<void>;
+    /**
+     * Lists tools available from a server.
+     */
+    listTools(serverId: string, params?: Parameters<Client["listTools"]>[0], options?: ClientRequestOptions): Promise<ListToolsResult>;
+    /**
+     * Gets tools from multiple servers (or all servers if none specified).
+     * Returns tools with execute functions pre-wired to call this manager.
+     *
+     * @param serverIds - Server IDs to get tools from (or all if omitted)
+     * @returns Array of executable tools
+     *
+     * @example
+     * ```typescript
+     * const tools = await manager.getTools(["asana"]);
+     * const agent = new TestAgent({ tools, model: "openai/gpt-4o", apiKey });
+     * ```
+     */
+    getTools(serverIds?: string[]): Promise<Tool[]>;
+    /**
+     * Gets cached tool metadata for a server.
+     */
+    getAllToolsMetadata(serverId: string): Record<string, Record<string, any>>;
+    /**
+     * Gets tools formatted for Vercel AI SDK.
+     *
+     * @param serverIds - Server IDs to get tools from (or all if omitted)
+     * @param options - Schema options
+     * @returns AiSdkTool compatible with Vercel AI SDK's generateText()
+     */
+    getToolsForAiSdk(serverIds?: string[] | string, options?: {
+        schemas?: ToolSchemaOverrides | "automatic";
+    }): Promise<AiSdkTool>;
+    /**
+     * Executes a tool on a server.
+     *
+     * @param serverId - The server ID
+     * @param toolName - The tool name
+     * @param args - Tool arguments
+     * @param options - Request options
+     * @param taskOptions - Task options for async execution
+     */
+    executeTool(serverId: string, toolName: string, args?: ExecuteToolArguments, options?: ClientRequestOptions, taskOptions?: TaskOptions): Promise<{
+        [x: string]: unknown;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations
+            /**
+             * Lists prompts available from a server.
+             */
+            ?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority? /**
+                 * Lists prompts available from a server.
+                 */: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                text: string;
+                mimeType?: string | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                uri: string;
+                blob: string;
+                mimeType?: string | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            };
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            uri: string;
+            name: string;
+            type: "resource_link";
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        })[];
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        structuredContent?: Record<string, unknown> | undefined;
+        isError?: boolean | undefined;
+    } | {
+        [x: string]: unknown;
+        toolResult: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | {
+        task: {
+            taskId: string;
+            status: "working" | "input_required" | "completed" | "failed" | "cancelled";
+            ttl: number | null;
+            createdAt: string;
+            lastUpdatedAt: string;
+            pollInterval?: number | undefined;
+            statusMessage?: string | undefined;
+        };
+        _meta: {
+            "io.modelcontextprotocol/model-immediate-response": string;
+        };
+    }>;
+    /**
+     * Lists resources available from a server.
+     */
+    listResources(serverId: string, params?: ListResourcesParams, options?: ClientRequestOptions): Promise<{
+        [x: string]: unknown;
+        resources: {
+            uri: string;
+            name: string;
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        }[];
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        nextCursor?: string | undefined;
+    }>;
+    /**
+     * Reads a resource from a server.
+     */
+    readResource(serverId: string, params: ReadResourceParams, options?: ClientRequestOptions): Promise<{
+        [x: string]: unknown;
+        contents: ({
+            uri: string;
+            text: string;
+            mimeType?: string | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            uri: string;
+            blob: string;
+            mimeType?: string | undefined;
+            _meta
+            /**
+             * Lists resources available from a server.
+             */
+            ?: Record<string, unknown> | undefined;
+        })[];
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    /**
+     * Subscribes to resource updates.
+     */
+    subscribeResource(serverId: string, params: SubscribeResourceParams, options?: ClientRequestOptions): Promise<{
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    /**
+     * Unsubscribes from resource updates.
+     */
+    unsubscribeResource(serverId: string, params: UnsubscribeResourceParams, options?: ClientRequestOptions): Promise<{
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    /**
+     * Lists resource templates from a server.
+     */
+    listResourceTemplates(serverId: string, params?: ListResourceTemplatesParams, options?: ClientRequestOptions): Promise<{
+        [x: string]: unknown;
+        resourceTemplates: {
+            uriTemplate: string;
+            name: string;
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        }[];
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        nextCursor?: string | undefined;
+    }>;
+    /**
+     * Lists prompts available from a server.
+     */
+    listPrompts(serverId: string, params?: ListPromptsParams, options?: ClientRequestOptions): Promise<{
+        [x: string]: unknown;
+        prompts: {
+            name: string;
+            description?: string | undefined;
+            arguments?: {
+                name: string;
+                description?: string | undefined;
+                required?: boolean | undefined;
+            }[] | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons? /**
+             * Gets tools formatted for Vercel AI SDK.
+             *
+             * @param serverIds - Server IDs to get tools from (or all if omitted)
+             * @param options - Schema options
+             * @returns AiSdkTool compatible with Vercel AI SDK's generateText()
+             */: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        }[];
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        nextCursor?: string | undefined;
+    }>;
+    /**
+     * Gets a prompt from a server.
+     */
+    getPrompt(serverId: string, params: GetPromptParams, options?: ClientRequestOptions): Promise<{
+        [x: string]: unknown;
+        messages: {
+            role: "user" | "assistant";
+            content: {
+                type: "text";
+                text: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                type: "image";
+                data: string;
+                mimeType: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                type: "audio";
+                data: string;
+                mimeType: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                type: "resource";
+                resource: {
+                    uri: string;
+                    text: string;
+                    mimeType?: string | undefined;
+                    _meta?: Record<string, unknown> | undefined;
+                } | {
+                    uri: string;
+                    blob: string;
+                    mimeType?: string | undefined;
+                    _meta?: Record<string, unknown> | undefined;
+                };
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                uri: string;
+                name: string;
+                type: "resource_link";
+                description?: string | undefined;
+                mimeType?: string | undefined;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                icons?: {
+                    src: string;
+                    mimeType?: string | undefined;
+                    sizes?: string[] | undefined;
+                    theme?: "light" | "dark" | undefined;
+                }[] | undefined;
+                title?: string | undefined;
+            };
+        }[];
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        description?: string | undefined;
+    }>;
+    /**
+     * Pings a server to check connectivity.
+     */
+    pingServer(serverId: string, options?: RequestOptions): void;
+    /**
+     * Sets the logging level for a server.
+     */
+    setLoggingLevel(serverId: string, level?: LoggingLevel): Promise<void>;
+    /**
+     * Gets the session ID for a Streamable HTTP server.
+     */
+    getSessionIdByServer(serverId: string): string | undefined;
+    /**
+     * Adds a notification handler for a server.
+     */
+    addNotificationHandler(serverId: string, schema: NotificationSchema, handler: NotificationHandler): void;
+    /**
+     * Registers a handler for resource list changes.
+     */
+    onResourceListChanged(serverId: string, handler: NotificationHandler): void;
+    /**
+     * Registers a handler for resource updates.
+     */
+    onResourceUpdated(serverId: string, handler: NotificationHandler): void;
+    /**
+     * Registers a handler for prompt list changes.
+     */
+    onPromptListChanged(serverId: string, handler: NotificationHandler): void;
+    /**
+     * Registers a handler for task status changes.
+     */
+    onTaskStatusChanged(serverId: string, handler: NotificationHandler): void;
+    /**
+     * Sets a server-specific elicitation handler.
+     */
+    setElicitationHandler(serverId: string, handler: ElicitationHandler): void;
+    /**
+     * Clears a server-specific elicitation handler.
+     */
+    clearElicitationHandler(serverId: string): void;
+    /**
+     * Sets a global elicitation callback for all servers.
+     */
+    setElicitationCallback(callback: ElicitationCallback): void;
+    /**
+     * Clears the global elicitation callback.
+     */
+    clearElicitationCallback(): void;
+    /**
+     * Gets the pending elicitations map for external resolvers.
+     */
+    getPendingElicitations(): Map<string, {
+        resolve: (value: ElicitResult) => void;
+        reject: (error: unknown) => void;
+    }>;
+    /**
+     * Responds to a pending elicitation.
+     */
+    respondToElicitation(requestId: string, response: ElicitResult): boolean;
+    /**
+     * Lists tasks from a server.
+     */
+    listTasks(serverId: string, cursor?: string, options?: ClientRequestOptions): Promise<MCPListTasksResult>;
+    /**
+     * Gets a task by ID.
+     */
+    getTask(serverId: string, taskId: string, options?: ClientRequestOptions): Promise<MCPTask>;
+    /**
+     * Gets the result of a completed task.
+     */
+    getTaskResult(serverId: string, taskId: string, options?: ClientRequestOptions): Promise<unknown>;
+    /**
+     * Cancels a task.
+     */
+    cancelTask(serverId: string, taskId: string, options?: ClientRequestOptions): Promise<MCPTask>;
+    /**
+     * Checks if server supports task-augmented tool calls.
+     */
+    supportsTasksForToolCalls(serverId: string): boolean;
+    /**
+     * Checks if server supports listing tasks.
+     */
+    supportsTasksList(serverId: string): boolean;
+    /**
+     * Checks if server supports canceling tasks.
+     */
+    supportsTasksCancel(serverId: string): boolean;
+    private performConnection;
+    private connectViaStdio;
+    private connectViaHttp;
+    private safeCloseTransport;
+    private ensureConnected;
+    private getClientOrThrow;
+    private resetState;
+    private withTimeout;
+    private withProgressHandler;
+    private buildCapabilities;
+    private resolveRpcLogger;
+    private cacheToolsMetadata;
+    private isStdioConfig;
+}
+
+/**
+ * Custom error classes for MCP SDK
+ */
+/**
+ * Base error class for all MCP SDK errors
+ */
+declare class MCPError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Authentication error - thrown for 401, token expired, invalid token, etc.
+ */
+declare class MCPAuthError extends MCPError {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Type guard to check if an error is an MCPAuthError
+ */
+declare function isMCPAuthError(error: unknown): error is MCPAuthError;
+/**
+ * Checks if an error is an authentication-related error.
+ * Detects auth errors by:
+ * 1. Error class name (UnauthorizedError from MCP SDK)
+ * 2. HTTP status codes (401, 403) from transport errors
+ * 3. Common auth-related patterns in error messages (case-insensitive)
+ */
+declare function isAuthError(error: unknown): {
+    isAuth: boolean;
+    statusCode?: number;
+};
+
+/**
+ * Core types for SDK evals functionality
+ */
+
+type CoreMessage = ModelMessage;
+type CoreUserMessage = UserModelMessage;
+type CoreAssistantMessage = AssistantModelMessage;
+type CoreToolMessage = ToolModelMessage;
+/**
+ * Built-in LLM providers with native SDK support
+ */
+type LLMProvider = "anthropic" | "openai" | "azure" | "deepseek" | "google" | "ollama" | "mistral" | "openrouter" | "xai";
+/**
+ * Compatible API protocols for custom providers
+ */
+type CompatibleProtocol = "openai-compatible" | "anthropic-compatible";
+/**
+ * Configuration for a custom provider (user-defined)
+ */
+interface CustomProvider {
+    /** Unique name for this provider (used in model strings, e.g., "groq/llama-3") */
+    name: string;
+    /** API protocol this provider is compatible with */
+    protocol: CompatibleProtocol;
+    /** Base URL for the API endpoint */
+    baseUrl: string;
+    /** List of available model IDs */
+    modelIds: string[];
+    /** Optional API key (can also be provided at runtime) */
+    apiKey?: string;
+    /** Environment variable name to read API key from (fallback) */
+    apiKeyEnvVar?: string;
+    /**
+     * Use Chat Completions API (.chat()) instead of default.
+     * Required for some OpenAI-compatible providers like LiteLLM.
+     * Only applies to openai-compatible protocol.
+     */
+    useChatCompletions?: boolean;
+}
+/**
+ * Configuration for an LLM
+ */
+interface LLMConfig {
+    provider: LLMProvider;
+    model: string;
+    apiKey: string;
+}
+/**
+ * Represents a tool call made by the LLM
+ */
+interface ToolCall {
+    toolName: string;
+    arguments: Record<any, any>;
+}
+/**
+ * Token usage statistics
+ */
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+/**
+ * Latency breakdown for prompt execution
+ */
+interface LatencyBreakdown {
+    /** Total wall-clock time in milliseconds */
+    e2eMs: number;
+    /** LLM API time in milliseconds */
+    llmMs: number;
+    /** MCP tool execution time in milliseconds */
+    mcpMs: number;
+}
+/**
+ * Raw prompt result data (used internally)
+ */
+interface PromptResultData {
+    /** The original prompt/query that was sent */
+    prompt: string;
+    /** The full conversation history (user, assistant, tool messages) */
+    messages: ModelMessage[];
+    text: string;
+    toolCalls: ToolCall[];
+    usage: TokenUsage;
+    latency: LatencyBreakdown;
+    error?: string;
+}
+
+/**
+ * PromptResult class - wraps the result of a TestAgent prompt
+ */
+
+/**
+ * Represents the result of a TestAgent prompt.
+ * Provides convenient methods to inspect tool calls, token usage, and errors.
+ */
+declare class PromptResult {
+    /** The original prompt/query that was sent */
+    readonly prompt: string;
+    /** The text response from the LLM */
+    readonly text: string;
+    /** The full conversation history */
+    private readonly _messages;
+    /** Latency breakdown (e2e, llm, mcp) */
+    private readonly _latency;
+    /** Tool calls made during the prompt */
+    private readonly _toolCalls;
+    /** Token usage statistics */
+    private readonly _usage;
+    /** Error message if the prompt failed */
+    private readonly _error?;
+    /**
+     * Create a new PromptResult
+     * @param data - The raw prompt result data
+     */
+    constructor(data: PromptResultData);
+    /**
+     * Get the original query/prompt that was sent.
+     *
+     * @returns The original prompt string
+     */
+    getPrompt(): string;
+    /**
+     * Get the full conversation history (user, assistant, tool messages).
+     * Returns a copy to prevent external modification.
+     *
+     * @returns Array of CoreMessage objects
+     */
+    getMessages(): CoreMessage[];
+    /**
+     * Get only user messages from the conversation.
+     *
+     * @returns Array of CoreUserMessage objects
+     */
+    getUserMessages(): CoreUserMessage[];
+    /**
+     * Get only assistant messages from the conversation.
+     *
+     * @returns Array of CoreAssistantMessage objects
+     */
+    getAssistantMessages(): CoreAssistantMessage[];
+    /**
+     * Get only tool result messages from the conversation.
+     *
+     * @returns Array of CoreToolMessage objects
+     */
+    getToolMessages(): CoreToolMessage[];
+    /**
+     * Get the end-to-end latency in milliseconds.
+     * This is the total wall-clock time for the prompt.
+     *
+     * @returns End-to-end latency in milliseconds
+     */
+    e2eLatencyMs(): number;
+    /**
+     * Get the LLM API latency in milliseconds.
+     * This is the time spent waiting for LLM responses (excluding tool execution).
+     *
+     * @returns LLM latency in milliseconds
+     */
+    llmLatencyMs(): number;
+    /**
+     * Get the MCP tool execution latency in milliseconds.
+     * This is the time spent executing MCP tools.
+     *
+     * @returns MCP tool latency in milliseconds
+     */
+    mcpLatencyMs(): number;
+    /**
+     * Get the full latency breakdown.
+     *
+     * @returns LatencyBreakdown object with e2eMs, llmMs, and mcpMs
+     */
+    getLatency(): LatencyBreakdown;
+    /**
+     * Get the names of all tools that were called during this prompt.
+     * Returns a standard string[] that can be used with .includes().
+     *
+     * @returns Array of tool names
+     */
+    toolsCalled(): string[];
+    /**
+     * Check if a specific tool was called during this prompt.
+     * Case-sensitive exact match.
+     *
+     * @param toolName - The name of the tool to check for
+     * @returns true if the tool was called
+     */
+    hasToolCall(toolName: string): boolean;
+    /**
+     * Get all tool calls with their arguments.
+     *
+     * @returns Array of ToolCall objects
+     */
+    getToolCalls(): ToolCall[];
+    /**
+     * Get the arguments passed to a specific tool call.
+     * Returns undefined if the tool was not called.
+     * If the tool was called multiple times, returns the first call's arguments.
+     *
+     * @param toolName - The name of the tool
+     * @returns The arguments object or undefined
+     */
+    getToolArguments(toolName: string): Record<string, unknown> | undefined;
+    /**
+     * Get the total number of tokens used.
+     *
+     * @returns Total tokens (input + output)
+     */
+    totalTokens(): number;
+    /**
+     * Get the number of input tokens used.
+     *
+     * @returns Input token count
+     */
+    inputTokens(): number;
+    /**
+     * Get the number of output tokens used.
+     *
+     * @returns Output token count
+     */
+    outputTokens(): number;
+    /**
+     * Get the full token usage statistics.
+     *
+     * @returns TokenUsage object
+     */
+    getUsage(): TokenUsage;
+    /**
+     * Check if this prompt resulted in an error.
+     *
+     * @returns true if there was an error
+     */
+    hasError(): boolean;
+    /**
+     * Get the error message if the prompt failed.
+     *
+     * @returns The error message or undefined
+     */
+    getError(): string | undefined;
+    /**
+     * Create a PromptResult from raw data.
+     * Factory method for convenience.
+     *
+     * @param data - The raw prompt result data
+     * @returns A new PromptResult instance
+     */
+    static from(data: PromptResultData): PromptResult;
+    /**
+     * Create an error PromptResult.
+     * Factory method for error cases.
+     *
+     * @param error - The error message
+     * @param latency - The latency breakdown or e2e time in milliseconds
+     * @returns A new PromptResult instance with error state
+     */
+    static error(error: string, latency?: LatencyBreakdown | number, prompt?: string): PromptResult;
+    /**
+     * Format the conversation trace as a JSON string.
+     * Useful for debugging failed evaluations.
+     *
+     * @returns A JSON string of the conversation messages
+     */
+    formatTrace(): string;
+}
+
+/**
+ * TestAgent - Runs LLM prompts with tool calling for evals
+ */
+
+/**
+ * Configuration for creating a TestAgent
+ */
+interface TestAgentConfig {
+    /** Tools to provide to the LLM (Tool[] from manager.getTools() or AiSdkTool from manager.getToolsForAiSdk()) */
+    tools: Tool[] | AiSdkTool;
+    /** LLM provider and model string (e.g., "openai/gpt-4o", "anthropic/claude-3-5-sonnet-20241022") */
+    model: string;
+    /** API key for the LLM provider */
+    apiKey: string;
+    /** System prompt for the LLM (default: "You are a helpful assistant.") */
+    systemPrompt?: string;
+    /** Temperature for LLM responses (0-2). If undefined, uses model default. Some models (e.g., reasoning models) don't support temperature. */
+    temperature?: number;
+    /** Maximum number of agentic steps/tool calls (default: 10) */
+    maxSteps?: number;
+    /** Custom providers registry for non-standard LLM providers */
+    customProviders?: Map<string, CustomProvider> | Record<string, CustomProvider>;
+}
+/**
+ * Options for the prompt() method
+ */
+interface PromptOptions {
+    /** Previous PromptResult(s) to include as conversation context for multi-turn conversations */
+    context?: PromptResult | PromptResult[];
+}
+/**
+ * Agent for running LLM prompts with tool calling.
+ * Wraps the AI SDK generateText function with proper tool integration.
+ *
+ * @example
+ * ```typescript
+ * const manager = new MCPClientManager({
+ *   everything: { command: "npx", args: ["-y", "@modelcontextprotocol/server-everything"] },
+ * });
+ * await manager.connectToServer("everything");
+ *
+ * const agent = new TestAgent({
+ *   tools: await manager.getToolsForAiSdk(["everything"]),
+ *   model: "openai/gpt-4o",
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ * });
+ *
+ * const result = await agent.prompt("Add 2 and 3");
+ * console.log(result.toolsCalled()); // ["add"]
+ * console.log(result.text); // "The result of adding 2 and 3 is 5."
+ * ```
+ */
+declare class TestAgent {
+    private readonly tools;
+    private readonly model;
+    private readonly apiKey;
+    private systemPrompt;
+    private temperature;
+    private readonly maxSteps;
+    private readonly customProviders?;
+    /** The result of the last prompt (for toolsCalled() convenience method) */
+    private lastResult;
+    /** History of all prompt results during a test execution */
+    private promptHistory;
+    /**
+     * Create a new TestAgent
+     * @param config - Agent configuration
+     */
+    constructor(config: TestAgentConfig);
+    /**
+     * Create instrumented tools that track execution latency.
+     * @param onLatency - Callback to report latency for each tool execution
+     * @returns ToolSet with instrumented execute functions
+     */
+    private createInstrumentedTools;
+    /**
+     * Build an array of ModelMessages from previous PromptResult(s) for multi-turn context.
+     * @param context - Single PromptResult or array of PromptResults to include as context
+     * @returns Array of ModelMessages representing the conversation history
+     */
+    private buildContextMessages;
+    /**
+     * Run a prompt with the LLM, allowing tool calls.
+     * Never throws - errors are returned in the PromptResult.
+     *
+     * @param message - The user message to send to the LLM
+     * @param options - Optional settings including context for multi-turn conversations
+     * @returns PromptResult with text response, tool calls, token usage, and latency breakdown
+     *
+     * @example
+     * // Single-turn (default)
+     * const result = await agent.prompt("Show me workspaces");
+     *
+     * @example
+     * // Multi-turn with context
+     * const r1 = await agent.prompt("Show me workspaces");
+     * const r2 = await agent.prompt("Now show tasks", { context: r1 });
+     *
+     * @example
+     * // Multi-turn with multiple context results
+     * const r1 = await agent.prompt("Show workspaces");
+     * const r2 = await agent.prompt("Pick the first", { context: r1 });
+     * const r3 = await agent.prompt("Show tasks", { context: [r1, r2] });
+     */
+    prompt(message: string, options?: PromptOptions): Promise<PromptResult>;
+    /**
+     * Get the names of tools called in the last prompt.
+     * Convenience method for quick checks in eval functions.
+     *
+     * @returns Array of tool names from the last prompt, or empty array if no prompt has been run
+     */
+    toolsCalled(): string[];
+    /**
+     * Create a new TestAgent with modified options.
+     * Useful for creating variants for different test scenarios.
+     *
+     * @param options - Partial config to override
+     * @returns A new TestAgent instance with the merged configuration
+     */
+    withOptions(options: Partial<TestAgentConfig>): TestAgent;
+    /**
+     * Get the configured tools
+     */
+    getTools(): ToolSet;
+    /**
+     * Get the LLM provider/model string
+     */
+    getModel(): string;
+    /**
+     * Get the API key
+     */
+    getApiKey(): string;
+    /**
+     * Get the current system prompt
+     */
+    getSystemPrompt(): string;
+    /**
+     * Set a new system prompt
+     */
+    setSystemPrompt(prompt: string): void;
+    /**
+     * Get the current temperature (undefined means model default)
+     */
+    getTemperature(): number | undefined;
+    /**
+     * Set the temperature (must be between 0 and 2)
+     */
+    setTemperature(temperature: number): void;
+    /**
+     * Get the max steps configuration
+     */
+    getMaxSteps(): number;
+    /**
+     * Get the result of the last prompt
+     */
+    getLastResult(): PromptResult | undefined;
+    /**
+     * Reset the prompt history.
+     * Call this before each test iteration to clear previous results.
+     */
+    resetPromptHistory(): void;
+    /**
+     * Get the history of all prompt results since the last reset.
+     * Returns a copy of the array to prevent external modification.
+     */
+    getPromptHistory(): PromptResult[];
+}
+
+/**
+ * Validators for matching tool calls in eval tests
+ *
+ * All matching is case-sensitive and uses exact strings only (no wildcards).
+ */
+
+/**
+ * Exact match - all expected tools must be present in exact order.
+ * Case-sensitive exact string comparison.
+ *
+ * @param expected - The expected tool names in order
+ * @param actual - The actual tool names that were called
+ * @returns true if actual matches expected exactly
+ *
+ * @example
+ * matchToolCalls(['add', 'multiply'], ['add', 'multiply']) // true
+ * matchToolCalls(['add', 'multiply'], ['multiply', 'add']) // false (wrong order)
+ * matchToolCalls(['add'], ['add', 'multiply']) // false (extra tool)
+ */
+declare function matchToolCalls(expected: string[], actual: string[]): boolean;
+/**
+ * Subset match - all expected tools must be present, order doesn't matter.
+ * Case-sensitive exact string comparison.
+ *
+ * @param expected - The expected tool names (any order)
+ * @param actual - The actual tool names that were called
+ * @returns true if all expected tools are present in actual
+ *
+ * @example
+ * matchToolCallsSubset(['add', 'multiply'], ['multiply', 'add']) // true
+ * matchToolCallsSubset(['add'], ['add', 'multiply']) // true
+ * matchToolCallsSubset(['add', 'subtract'], ['add', 'multiply']) // false (missing subtract)
+ */
+declare function matchToolCallsSubset(expected: string[], actual: string[]): boolean;
+/**
+ * Any match - at least one expected tool must be present.
+ * Case-sensitive exact string comparison.
+ *
+ * @param expected - The expected tool names (at least one must match)
+ * @param actual - The actual tool names that were called
+ * @returns true if at least one expected tool is present in actual
+ *
+ * @example
+ * matchAnyToolCall(['add', 'subtract'], ['multiply', 'add']) // true
+ * matchAnyToolCall(['add', 'subtract'], ['multiply', 'divide']) // false
+ * matchAnyToolCall([], ['add']) // false (empty expected)
+ */
+declare function matchAnyToolCall(expected: string[], actual: string[]): boolean;
+/**
+ * Count match - check if a specific tool was called exactly N times.
+ * Case-sensitive exact string comparison.
+ *
+ * @param toolName - The tool name to count
+ * @param actual - The actual tool names that were called
+ * @param count - The expected number of times the tool should be called
+ * @returns true if the tool was called exactly count times
+ *
+ * @example
+ * matchToolCallCount('add', ['add', 'add', 'multiply'], 2) // true
+ * matchToolCallCount('add', ['add', 'multiply'], 2) // false
+ */
+declare function matchToolCallCount(toolName: string, actual: string[], count: number): boolean;
+/**
+ * No tools match - check that no tools were called.
+ *
+ * @param actual - The actual tool names that were called
+ * @returns true if no tools were called
+ *
+ * @example
+ * matchNoToolCalls([]) // true
+ * matchNoToolCalls(['add']) // false
+ */
+declare function matchNoToolCalls(actual: string[]): boolean;
+/**
+ * Check if tool was called with exact arguments (deep equality).
+ * Returns true if any call to the tool has exactly matching arguments.
+ * Case-sensitive for tool names.
+ *
+ * @param toolName - The tool name to match
+ * @param expectedArgs - The expected arguments (exact match)
+ * @param toolCalls - The actual tool calls made
+ * @returns true if any call to the tool has exactly matching arguments
+ *
+ * @example
+ * matchToolCallWithArgs('add', {a: 2, b: 3}, toolCalls) // true if add({a:2, b:3}) was called
+ * matchToolCallWithArgs('add', {a: 2}, [{toolName:'add', arguments:{a:2, b:3}}]) // false (extra arg)
+ */
+declare function matchToolCallWithArgs(toolName: string, expectedArgs: Record<string, unknown>, toolCalls: ToolCall[]): boolean;
+/**
+ * Check if tool was called with at least these arguments (partial match).
+ * Allows extra arguments in the actual call.
+ * Case-sensitive for tool names.
+ *
+ * @param toolName - The tool name to match
+ * @param expectedArgs - The expected arguments (partial match)
+ * @param toolCalls - The actual tool calls made
+ * @returns true if any call to the tool contains all expected arguments
+ *
+ * @example
+ * matchToolCallWithPartialArgs('add', {a: 2}, [{toolName:'add', arguments:{a:2, b:3}}]) // true
+ * matchToolCallWithPartialArgs('add', {a: 2, c: 5}, [{toolName:'add', arguments:{a:2, b:3}}]) // false
+ */
+declare function matchToolCallWithPartialArgs(toolName: string, expectedArgs: Record<string, unknown>, toolCalls: ToolCall[]): boolean;
+/**
+ * Check if a specific argument has a specific value in any call to the tool.
+ * Case-sensitive for tool names.
+ *
+ * @param toolName - The tool name to match
+ * @param argKey - The argument key to check
+ * @param expectedValue - The expected value for the argument
+ * @param toolCalls - The actual tool calls made
+ * @returns true if any call to the tool has the specified argument value
+ *
+ * @example
+ * matchToolArgument('add', 'a', 2, toolCalls) // true if any add() call had a=2
+ */
+declare function matchToolArgument(toolName: string, argKey: string, expectedValue: unknown, toolCalls: ToolCall[]): boolean;
+/**
+ * Check if argument value matches a predicate function.
+ * Useful for partial matches, type checks, or range validation.
+ * Case-sensitive for tool names.
+ *
+ * @param toolName - The tool name to match
+ * @param argKey - The argument key to check
+ * @param predicate - Function that tests the argument value
+ * @param toolCalls - The actual tool calls made
+ * @returns true if any call to the tool has an argument value that passes the predicate
+ *
+ * @example
+ * matchToolArgumentWith('echo', 'message', (v) => typeof v === 'string' && v.includes('hello'), toolCalls)
+ * matchToolArgumentWith('add', 'a', (v) => typeof v === 'number' && v > 0, toolCalls)
+ */
+declare function matchToolArgumentWith(toolName: string, argKey: string, predicate: (value: unknown) => boolean, toolCalls: ToolCall[]): boolean;
+
+/**
+ * Statistics for latency values
+ */
+interface LatencyStats {
+    /** Minimum value */
+    min: number;
+    /** Maximum value */
+    max: number;
+    /** Mean (average) value */
+    mean: number;
+    /** 50th percentile (median) */
+    p50: number;
+    /** 95th percentile */
+    p95: number;
+    /** Number of values */
+    count: number;
+}
+
+/**
+ * Configuration for an EvalTest
+ *
+ * All tests use the multi-turn pattern with a test function that receives a TestAgent.
+ */
+interface EvalTestConfig {
+    name: string;
+    test: (agent: TestAgent) => boolean | Promise<boolean>;
+}
+/**
+ * Options for running an EvalTest
+ */
+interface EvalTestRunOptions {
+    iterations: number;
+    concurrency?: number;
+    retries?: number;
+    timeoutMs?: number;
+    onProgress?: (completed: number, total: number) => void;
+    /** Called with a failure report if any iterations fail */
+    onFailure?: (report: string) => void;
+}
+/**
+ * Result details for a single iteration
+ */
+interface IterationResult {
+    passed: boolean;
+    latencies: LatencyBreakdown[];
+    tokens: {
+        total: number;
+        input: number;
+        output: number;
+    };
+    error?: string;
+    retryCount?: number;
+    /** The prompt results from this iteration */
+    prompts?: PromptResult[];
+}
+/**
+ * Result of running an EvalTest
+ */
+interface EvalRunResult {
+    iterations: number;
+    successes: number;
+    failures: number;
+    results: boolean[];
+    iterationDetails: IterationResult[];
+    tokenUsage: {
+        total: number;
+        input: number;
+        output: number;
+        perIteration: {
+            total: number;
+            input: number;
+            output: number;
+        }[];
+    };
+    latency: {
+        e2e: LatencyStats;
+        llm: LatencyStats;
+        mcp: LatencyStats;
+        perIteration: LatencyBreakdown[];
+    };
+}
+/**
+ * EvalTest - Runs a single test scenario with iterations
+ *
+ * Can be run standalone or as part of an EvalSuite.
+ *
+ * @example
+ * ```ts
+ * const test = new EvalTest({
+ *   name: "addition",
+ *   test: async (agent) => {
+ *     const result = await agent.prompt("Add 2+3");
+ *     return result.hasToolCall("add");
+ *   },
+ * });
+ * await test.run(agent, { iterations: 30 });
+ * console.log(test.accuracy()); // 0.97
+ * ```
+ */
+declare class EvalTest {
+    private config;
+    private lastRunResult;
+    constructor(config: EvalTestConfig);
+    /**
+     * Run this test with the given agent and options
+     */
+    run(agent: TestAgent, options: EvalTestRunOptions): Promise<EvalRunResult>;
+    private aggregateResults;
+    /**
+     * Get the accuracy of the last run (success rate)
+     */
+    accuracy(): number;
+    /**
+     * Get the recall (true positive rate) of the last run
+     */
+    recall(): number;
+    /**
+     * Get the precision of the last run
+     */
+    precision(): number;
+    /**
+     * Get the true positive rate (same as recall)
+     */
+    truePositiveRate(): number;
+    /**
+     * Get the false positive rate
+     */
+    falsePositiveRate(): number;
+    /**
+     * Get the average token use per iteration
+     */
+    averageTokenUse(): number;
+    /**
+     * Get the full results of the last run
+     */
+    getResults(): EvalRunResult | null;
+    /**
+     * Get the name of this test
+     */
+    getName(): string;
+    /**
+     * Get the configuration of this test
+     */
+    getConfig(): EvalTestConfig;
+    /**
+     * Get all iteration details from the last run
+     */
+    getAllIterations(): IterationResult[];
+    /**
+     * Get only the failed iterations from the last run
+     */
+    getFailedIterations(): IterationResult[];
+    /**
+     * Get only the successful iterations from the last run
+     */
+    getSuccessfulIterations(): IterationResult[];
+    /**
+     * Get a failure report with traces from all failed iterations.
+     * Useful for debugging why evaluations failed.
+     *
+     * @returns A formatted string with failure details
+     */
+    getFailureReport(): string;
+}
+
+/**
+ * Configuration for an EvalSuite
+ */
+interface EvalSuiteConfig {
+    name?: string;
+}
+/**
+ * Result for a single test within the suite
+ */
+interface TestResult {
+    name: string;
+    result: EvalRunResult;
+}
+/**
+ * Result of running an EvalSuite
+ */
+interface EvalSuiteResult {
+    tests: Map<string, EvalRunResult>;
+    aggregate: {
+        iterations: number;
+        successes: number;
+        failures: number;
+        accuracy: number;
+        tokenUsage: {
+            total: number;
+            perTest: number[];
+        };
+        latency: {
+            e2e: LatencyStats;
+            llm: LatencyStats;
+            mcp: LatencyStats;
+        };
+    };
+}
+/**
+ * EvalSuite - Groups multiple EvalTests and provides aggregate metrics
+ *
+ * @example
+ * ```ts
+ * const suite = new EvalSuite({ name: "Math" });
+ * suite.add(new EvalTest({
+ *   name: "addition",
+ *   test: async (agent) => {
+ *     const r = await agent.prompt("Add 2+3");
+ *     return r.hasToolCall("add");
+ *   },
+ * }));
+ * suite.add(new EvalTest({
+ *   name: "multiply",
+ *   test: async (agent) => {
+ *     const r = await agent.prompt("Multiply 4*5");
+ *     return r.hasToolCall("multiply");
+ *   },
+ * }));
+ *
+ * await suite.run(agent, { iterations: 30 });
+ * console.log(suite.accuracy());                 // Aggregate: 0.95
+ * console.log(suite.get("addition").accuracy()); // Individual: 0.97
+ * ```
+ */
+declare class EvalSuite {
+    private name;
+    private tests;
+    private lastRunResult;
+    constructor(config?: EvalSuiteConfig);
+    /**
+     * Add a test to the suite
+     */
+    add(test: EvalTest): void;
+    /**
+     * Get a test by name
+     */
+    get(name: string): EvalTest | undefined;
+    /**
+     * Get all tests in the suite
+     */
+    getAll(): EvalTest[];
+    /**
+     * Run all tests in the suite with the given agent and options
+     */
+    run(agent: TestAgent, options: EvalTestRunOptions): Promise<EvalSuiteResult>;
+    private aggregateResults;
+    /**
+     * Get the aggregate accuracy across all tests
+     */
+    accuracy(): number;
+    /**
+     * Get the aggregate recall (same as accuracy in basic context)
+     */
+    recall(): number;
+    /**
+     * Get the aggregate precision (same as accuracy in basic context)
+     */
+    precision(): number;
+    /**
+     * Get the aggregate true positive rate (same as recall)
+     */
+    truePositiveRate(): number;
+    /**
+     * Get the aggregate false positive rate
+     */
+    falsePositiveRate(): number;
+    /**
+     * Get the average token use per iteration across all tests
+     */
+    averageTokenUse(): number;
+    /**
+     * Get the full suite results
+     */
+    getResults(): EvalSuiteResult | null;
+    /**
+     * Get the name of the suite
+     */
+    getName(): string;
+    /**
+     * Get the number of tests in the suite
+     */
+    size(): number;
+}
+
+/**
+ * Model factory for creating AI SDK language models from provider/model strings.
+ * Supports both built-in providers and user-defined custom providers.
+ */
+
+/**
+ * Custom base URLs for built-in providers that support them.
+ */
+interface BaseUrls {
+    ollama?: string;
+    azure?: string;
+    anthropic?: string;
+    openai?: string;
+}
+/**
+ * Options for creating a model.
+ */
+interface CreateModelOptions {
+    apiKey: string;
+    baseUrls?: BaseUrls;
+    /** Custom providers registry (name -> config) */
+    customProviders?: Map<string, CustomProvider> | Record<string, CustomProvider>;
+}
+/**
+ * Result of parsing an LLM string
+ */
+type ParsedLLMString = {
+    type: "builtin";
+    provider: LLMProvider;
+    model: string;
+} | {
+    type: "custom";
+    providerName: string;
+    model: string;
+};
+/**
+ * Parse an LLM string into provider and model components.
+ * Supports both built-in providers and custom provider names.
+ *
+ * @param llmString - String in format "provider/model" (e.g., "openai/gpt-4o" or "my-litellm/gpt-4")
+ * @param customProviderNames - Optional set of registered custom provider names for validation
+ * @returns Parsed result with type discriminator
+ */
+declare function parseLLMString(llmString: string, customProviderNames?: Set<string>): ParsedLLMString;
+/**
+ * Model type returned by provider factories.
+ */
+type ProviderLanguageModel = ReturnType<ReturnType<typeof createOpenAI>>;
+/**
+ * Create a language model from an LLM string.
+ * @param llmString - String in format "provider/model" (e.g., "openai/gpt-4o" or "my-provider/model")
+ * @param options - API key, optional base URLs, and custom providers registry
+ * @returns AI SDK language model instance
+ */
+declare function createModelFromString(llmString: string, options: CreateModelOptions): ProviderLanguageModel;
+/**
+ * Parse a comma-separated string of model IDs into an array.
+ * Handles whitespace and empty entries.
+ */
+declare function parseModelIds(modelIdsString: string): string[];
+/**
+ * Create a CustomProvider configuration from user input.
+ * This is a helper for building the configuration from form inputs.
+ */
+declare function createCustomProvider(config: {
+    name: string;
+    protocol: "openai-compatible" | "anthropic-compatible";
+    baseUrl: string;
+    modelIds: string | string[];
+    apiKey?: string;
+    apiKeyEnvVar?: string;
+    useChatCompletions?: boolean;
+}): CustomProvider;
+/**
+ * Preset configurations for common OpenAI-compatible providers.
+ * Users can use these as starting points and customize as needed.
+ */
+declare const PROVIDER_PRESETS: {
+    /** LiteLLM proxy - requires useChatCompletions */
+    readonly litellm: (baseUrl: string | undefined, modelIds: string[]) => CustomProvider;
+};
+
+export { type AiSdkTool, type BaseServerConfig, type BaseUrls, type ClientCapabilityOptions, type CompatibleProtocol, type CoreAssistantMessage, type CoreMessage, type CoreToolMessage, type CoreUserMessage, type CreateModelOptions, type CustomProvider, type ElicitationCallback, type ElicitationCallbackRequest, type ElicitationHandler, type EvalRunResult, EvalSuite, type EvalSuiteConfig, type EvalSuiteResult, EvalTest, type EvalTestConfig, type EvalTestRunOptions, type ExecuteToolArguments, type HttpServerConfig, type IterationResult, type LLMConfig, type LLMProvider, type LatencyBreakdown, type ListToolsResult, MCPAuthError, MCPClientManager, type MCPClientManagerConfig, type MCPClientManagerOptions, type MCPConnectionStatus, MCPError, type MCPGetPromptResult, type MCPListTasksResult, type MCPPrompt, type MCPPromptListResult, type MCPReadResourceResult, type MCPResource, type MCPResourceListResult, type MCPResourceTemplate, type MCPResourceTemplateListResult, type MCPServerConfig, type MCPServerSummary, type MCPTask, type MCPTaskStatus, PROVIDER_PRESETS, type ParsedLLMString, type ProgressEvent, type ProgressHandler, type PromptOptions, PromptResult, type PromptResultData, type ProviderLanguageModel, type RpcLogEvent, type RpcLogger, type ServerSummary, type StdioServerConfig, type TaskOptions, TestAgent, type TestAgentConfig, type TestResult, type TokenUsage, type Tool, type ToolCall, type ToolExecuteOptions, createCustomProvider, createModelFromString, isAuthError, isChatGPTAppTool, isMCPAuthError, isMcpAppTool, matchAnyToolCall, matchNoToolCalls, matchToolArgument, matchToolArgumentWith, matchToolCallCount, matchToolCallWithArgs, matchToolCallWithPartialArgs, matchToolCalls, matchToolCallsSubset, parseLLMString, parseModelIds, scrubMetaAndStructuredContentFromToolResult, scrubMetaFromToolResult };