@mcp-use/client 2.2.4 → 2.2.5

package/dist/core/config.d.ts

@@ -0,0 +1,225 @@
+import type { ElicitRequestFormParams, ElicitRequestURLParams, ElicitResult, Notification, AuthProvider, OAuthClientInformation, OAuthClientProvider, Root, RequestTypeMap, RequestOptions, ResultTypeMap, ClientOptions, VersionNegotiationMode } from "@modelcontextprotocol/client";
+import type { BaseConnector, ConnectorInitOptions } from "../transport/base.js";
+import type { ClientInfo } from "../transport/http.js";
+import type { StdioStderrMode } from "../transport/stdio.js";
+/** Parameters accepted by the MCP `sampling/createMessage` request. */
+export type SamplingCreateMessageParams = RequestTypeMap["sampling/createMessage"]["params"];
+/** Result returned for the MCP `sampling/createMessage` request. */
+export type SamplingCreateMessageResult = ResultTypeMap["sampling/createMessage"];
+/**
+ * Handles a sampling request initiated by an MCP server.
+ *
+ * @param params - Sampling request parameters supplied by the server.
+ * @returns The model-generated sampling result.
+ */
+export type OnSamplingCallback = (params: SamplingCreateMessageParams) => Promise<SamplingCreateMessageResult>;
+/**
+ * Handles a form or URL elicitation request initiated by an MCP server.
+ *
+ * @param params - Elicitation request parameters supplied by the server.
+ * @returns The user's elicitation decision and optional content.
+ */
+export type OnElicitationCallback = (params: ElicitRequestFormParams | ElicitRequestURLParams) => Promise<ElicitResult>;
+/**
+ * Handles a notification sent by an MCP server.
+ *
+ * @param notification - The notification envelope supplied by the server.
+ */
+export type OnNotificationCallback = (notification: Notification) => void | Promise<void>;
+/**
+ * Callback options shared by per-server config and global defaults.
+ */
+export interface CallbackConfig {
+    /**
+     * Callback for sampling input.
+     *
+     * @deprecated Sampling is deprecated by the 2026 protocol. Retained for v1
+     * push requests and the v2 `input_required` compatibility window.
+     */
+    onSampling?: OnSamplingCallback;
+    /** Callback for elicitation requests from servers. */
+    onElicitation?: OnElicitationCallback;
+    /** Callback for notifications from servers. */
+    onNotification?: OnNotificationCallback;
+}
+/**
+ * Resolves callback handlers, preferring per-server values over global values.
+ *
+ * @param perServer - Callback overrides for one server.
+ * @param globalDefaults - Fallback callbacks shared by all servers.
+ * @returns The effective callbacks for the server.
+ */
+export declare function resolveCallbacks(perServer: CallbackConfig | undefined, globalDefaults: CallbackConfig | undefined): {
+    /** Effective sampling callback. */
+    onSampling?: OnSamplingCallback;
+    /** Effective elicitation callback. */
+    onElicitation?: OnElicitationCallback;
+    /** Effective notification callback. */
+    onNotification?: OnNotificationCallback;
+};
+/**
+ * Base server configuration with common optional fields
+ */
+/** Options shared by HTTP and stdio server configurations. */
+interface BaseServerConfig extends CallbackConfig {
+    /** Client identity advertised to the server. */
+    clientInfo?: ClientInfo;
+    /** Initial roots advertised to the server. */
+    roots?: Root[];
+    /** Options forwarded to the official MCP SDK Client. */
+    clientOptions?: ClientOptions;
+    /** Default timeout/cancellation options for requests. */
+    defaultRequestOptions?: RequestOptions;
+}
+/**
+ * Configures a local MCP server launched over standard input and output.
+ */
+export interface StdioServerConfig extends BaseServerConfig {
+    /** Executable used to start the server. */
+    command: string;
+    /** Arguments passed to {@link StdioServerConfig.command}. */
+    args: string[];
+    /** Environment variables merged with the current process environment. */
+    env?: Record<string, string>;
+    /** Working directory used to launch the server process. */
+    cwd?: string;
+    /**
+     * How the server process's standard error is handled. Defaults to `"pipe"`,
+     * which forwards it to the connector's `errlog`. Use `"inherit"` to give the
+     * child the parent's stderr file descriptor instead, preserving TTY
+     * detection and colorization, or `"ignore"` to discard it.
+     */
+    stderr?: StdioStderrMode;
+    /**
+     * Protocol version negotiation mode. Defaults to `"legacy"` for stdio (the
+     * SDK advises against probing for spawn-per-invocation tools). See
+     * {@link StdioConnector}.
+     */
+    protocolNegotiation?: VersionNegotiationMode;
+}
+/**
+ * Options forwarded to the platform `createOAuthProvider` when the client
+ * auto-provisions OAuth for an HTTP server. Platform-specific fields
+ * (e.g. Node `openBrowser`, browser `oauthProxyUrl`) are accepted and ignored
+ * by the other runtime.
+ */
+export interface AutoOAuthOptions {
+    /** Prefix used for persisted OAuth session keys. */
+    storageKeyPrefix?: string;
+    /** OAuth client display name. */
+    clientName?: string;
+    /** Public URL describing the OAuth client. */
+    clientUri?: string;
+    /** Public URL for the OAuth client logo. */
+    logoUri?: string;
+    /** OAuth redirect URI. The platform provider supplies a default when omitted. */
+    callbackUrl?: string;
+    /** URL of an OAuth Client ID Metadata Document. */
+    clientMetadataUrl?: string;
+    /** Space-delimited OAuth scopes to request. */
+    scope?: string;
+    /** Pre-registered public client id (skips DCR). */
+    staticClientInfo?: OAuthClientInformation;
+    /** Preferred Node loopback port. Defaults to `33418`. */
+    preferredPort?: number;
+    /** Number of Node loopback ports to try. Defaults to `10`. */
+    portRange?: number;
+    /** Node loopback callback timeout in milliseconds. Defaults to five minutes. */
+    authTimeoutMs?: number;
+    /** Node: override browser launch (CLI prints the URL instead). */
+    openBrowser?: (url: string) => void | Promise<void>;
+    /** Browser: wait for explicit authenticate() instead of auto popup. */
+    preventAutoAuth?: boolean;
+    /** Browser: full-page redirect instead of popup. */
+    useRedirectFlow?: boolean;
+    /** Browser: same-origin OAuth BFF base URL. */
+    oauthProxyUrl?: string;
+    /** Whether browser OAuth HTTP uses `oauthProxyUrl`. Defaults to `true` when the URL is set. */
+    proxyOAuthRequests?: boolean;
+}
+/**
+ * Configures a remote MCP server accessed with streamable HTTP.
+ */
+export interface HttpServerConfig extends BaseServerConfig {
+    /** MCP endpoint URL. */
+    url: string;
+    /** Headers included with MCP transport requests. */
+    headers?: Record<string, string>;
+    /** Fetch implementation used by the HTTP transport. */
+    fetch?: typeof fetch;
+    /** Bearer token added as the `Authorization` header. */
+    authToken?: string;
+    /** Connection timeout in milliseconds. */
+    timeout?: number;
+    /** OAuth provider used when the server requires authorization. */
+    authProvider?: AuthProvider | OAuthClientProvider;
+    /**
+     * Auto-OAuth options for HTTP servers.
+     * - omit / `{}`: client creates the platform provider on connect
+     * - `false`: disable auto-OAuth (e.g. CLI `--no-oauth`)
+     * - object: forwarded to `createOAuthProvider`
+     *
+     * Ignored when `authProvider` or `authToken` is set, or when `headers`
+     * already includes `Authorization`.
+     */
+    oauth?: AutoOAuthOptions | false;
+    /**
+     * Detect mixed-auth servers after an anonymous connection by using the
+     * official SDK's RFC 9728 protected-resource metadata discovery.
+     * @defaultValue true
+     */
+    detectMixedAuth?: boolean;
+    /**
+     * Protocol version negotiation mode. Defaults to `"auto"` to negotiate both
+     * v1 and v2 MCP servers. See {@link HttpConnector}.
+     */
+    protocolNegotiation?: VersionNegotiationMode;
+}
+/**
+ * Tests whether the client should create an OAuth provider for an HTTP server.
+ *
+ * @param serverConfig - Server configuration to inspect.
+ * @returns `true` for an HTTP configuration without explicit authorization.
+ */
+export declare function shouldAutoProvisionOAuth(serverConfig: ServerConfig): serverConfig is HttpServerConfig;
+/**
+ * Configuration for either a local stdio server or a remote HTTP server.
+ */
+export type ServerConfig = StdioServerConfig | HttpServerConfig;
+/**
+ * Top-level MCP client configuration.
+ *
+ * Callback and client identity values act as defaults for individual servers.
+ */
+export interface MCPClientConfigShape extends CallbackConfig {
+    /** Default client identity for all servers; overridable per server. */
+    clientInfo?: ClientInfo;
+    /** Server configurations keyed by the name used in client methods. */
+    mcpServers?: Record<string, ServerConfig>;
+}
+/**
+ * Normalizes a client identity and fills optional metadata with package defaults.
+ *
+ * @param input - Candidate client identity.
+ * @returns The supplied identity merged with defaults, or the complete default
+ * identity when `input` does not contain both `name` and `version`.
+ */
+export declare function normalizeClientInfo(input: unknown): ClientInfo;
+/**
+ * Expands the `capabilities.views` shorthand into the MCP Apps extension.
+ *
+ * @param clientOptions - SDK client options to normalize.
+ * @returns Normalized options, or `undefined` when no options were supplied.
+ */
+export declare function resolveClientOptions(clientOptions: ClientOptions | undefined): ClientOptions | undefined;
+/**
+ * Creates an HTTP connector from a runtime-neutral server configuration.
+ *
+ * @param serverConfig - Server configuration to convert.
+ * @param connectorOptions - Connector options that override derived values.
+ * @returns An HTTP connector for the configured endpoint.
+ * @throws When `serverConfig` is a stdio configuration or has no recognized transport.
+ */
+export declare function createConnectorFromConfig(serverConfig: ServerConfig, connectorOptions?: Partial<ConnectorInitOptions>): BaseConnector;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"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"}

package/dist/core/node.d.ts

@@ -0,0 +1,437 @@
+import type { ElicitRequestFormParams, ElicitRequestURLParams, ElicitResult, OAuthClientProvider } from "@modelcontextprotocol/client";
+import { BaseMCPClient } from "./base.js";
+import type { ExecutionResult, ToolSearchResponse } from "../code-mode/executor.js";
+import { BaseCodeExecutor } from "../code-mode/executor.js";
+import { type AutoOAuthOptions, type SamplingCreateMessageParams, type SamplingCreateMessageResult } from "./config.js";
+import type { BaseConnector } from "../transport/base.js";
+/** Read and parse a JSON MCP client config file. Node-only. */
+export declare function loadConfigFile(filepath: string): Record<string, any>;
+/**
+ * Custom function type for code execution in code mode.
+ * Allows providing a custom executor implementation.
+ */
+export type CodeExecutorFunction = (code: string, timeout?: number) => Promise<ExecutionResult>;
+/**
+ * Built-in code executor types.
+ * - `"vm"`: Node.js VM-based executor (default, local execution)
+ * - `"e2b"`: E2B cloud sandbox executor (secure remote execution)
+ */
+export type CodeExecutorType = "vm" | "e2b";
+/**
+ * Configuration options for the VM-based code executor.
+ */
+export interface VMExecutorOptions {
+    /** Maximum execution time in milliseconds. Default: 30000 (30 seconds) */
+    timeoutMs?: number;
+    /** Memory limit in megabytes. Default: undefined (no limit) */
+    memoryLimitMb?: number;
+}
+/**
+ * Configuration options for the E2B cloud sandbox executor.
+ */
+export interface E2BExecutorOptions {
+    /** E2B API key (required). Get one at https://e2b.dev */
+    apiKey: string;
+    /** Maximum execution time in milliseconds. Default: 300000 (5 minutes) */
+    timeoutMs?: number;
+}
+/**
+ * Union type for executor configuration options.
+ */
+export type ExecutorOptions = VMExecutorOptions | E2BExecutorOptions;
+/**
+ * Advanced configuration for code execution mode.
+ */
+export interface CodeModeConfig {
+    /** Whether to enable code execution mode */
+    enabled: boolean;
+    /** Executor type or custom implementation. Defaults to "vm" */
+    executor?: CodeExecutorType | CodeExecutorFunction | BaseCodeExecutor;
+    /** Type-safe configuration options for the executor */
+    executorOptions?: ExecutorOptions;
+}
+/**
+ * Options for configuring MCPClient behavior.
+ */
+export interface MCPClientOptions {
+    /** Enable code execution mode (simple boolean or advanced configuration) */
+    codeMode?: boolean | CodeModeConfig;
+    /**
+     * Optional callback function to handle sampling requests from servers.
+     * When provided, the client will declare sampling capability and handle
+     * `sampling/createMessage` requests by calling this callback.
+     *
+     * @deprecated Sampling is deprecated by the 2026 protocol. Retained for v1
+     * push requests and v2 multi-round-trip compatibility.
+     */
+    onSampling?: (params: SamplingCreateMessageParams) => Promise<SamplingCreateMessageResult>;
+    /**
+     * Optional callback function to handle elicitation requests from servers.
+     * When provided, the client will declare elicitation capability and handle
+     * `elicitation/create` requests by calling this callback.
+     *
+     * Elicitation allows servers to request additional information from users:
+     * - Form mode: Collect structured data with JSON schema validation
+     * - URL mode: Direct users to external URLs for sensitive interactions
+     */
+    onElicitation?: (params: ElicitRequestFormParams | ElicitRequestURLParams) => Promise<ElicitResult>;
+    /**
+     * Optional callback function for server notifications.
+     * Applied as default when per-server config does not specify one.
+     */
+    onNotification?: (notification: import("@modelcontextprotocol/client").Notification) => void | Promise<void>;
+}
+export { BaseCodeExecutor } from "../code-mode/executor.js";
+export { E2BCodeExecutor } from "../code-mode/executor-e2b.js";
+export { isVMAvailable, VMCodeExecutor } from "../code-mode/executor-vm.js";
+export { accept, acceptWithDefaults, applyDefaults, cancel, decline, getDefaults, validate, } from "../utils/elicitation.js";
+export type { ElicitContent, ElicitValidationResult, } from "../utils/elicitation.js";
+export { MCPSession } from "./session.js";
+export type { CallToolResult, MetaObject, Notification, Root, Tool, } from "./session.js";
+/**
+ * Node.js-specific MCP client implementation with advanced features.
+ *
+ * The MCPClient class provides a complete MCP client implementation for Node.js
+ * environments, extending the runtime-neutral `BaseMCPClient` with platform-specific capabilities:
+ *
+ * - **All Connector Types**: Supports Stdio, HTTP, and WebSocket connectors
+ * - **Code Execution Mode**: Execute code dynamically using VM or E2B sandboxes
+ * - **File System Operations**: Load and save configurations from/to files
+ * - **Sampling & Elicitation**: Handle advanced MCP protocol features
+ * - **Session Management**: Create and manage multiple server connections
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with config file
+ * const client = new MCPClient('./mcp-config.json');
+ * const session = await client.createSession('my-server');
+ * const tools = await session.listTools();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With inline configuration
+ * const client = new MCPClient({
+ *   mcpServers: {
+ *     'filesystem': {
+ *       command: 'npx',
+ *       args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp']
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With code execution mode
+ * const client = new MCPClient('./config.json', {
+ *   codeMode: {
+ *     enabled: true,
+ *     executor: 'e2b',
+ *     executorOptions: { apiKey: process.env.E2B_API_KEY }
+ *   }
+ * });
+ *
+ * const result = await client.executeCode('console.log("Hello!")');
+ * ```
+ *
+ * @see {@link MCPSession} for session management
+ */
+export declare class MCPClient extends BaseMCPClient {
+    /**
+     * Gets the mcp-use package version.
+     *
+     * This static method returns the version string of the installed mcp-use package,
+     * which is useful for debugging and compatibility checks.
+     *
+     * @returns The package version string (e.g., "1.13.2")
+     *
+     * @example
+     * ```typescript
+     * console.log(`mcp-use version: ${MCPClient.getPackageVersion()}`);
+     * ```
+     */
+    static getPackageVersion(): string;
+    /**
+     * Indicates whether code execution mode is enabled.
+     *
+     * When true, the client provides special tools for executing code dynamically
+     * through the {@link executeCode} and {@link searchTools} methods.
+     *
+     * @example
+     * ```typescript
+     * if (client.codeMode) {
+     *   const result = await client.executeCode('return 2 + 2');
+     *   console.log(result.output); // "4"
+     * }
+     * ```
+     */
+    codeMode: boolean;
+    private _codeExecutor;
+    private _codeExecutorConfig;
+    private _executorOptions?;
+    private _globalCallbacks;
+    /**
+     * Creates a new MCPClient instance.
+     *
+     * The client can be initialized with either a configuration object, a path to
+     * a configuration file, or no configuration at all (servers can be added later
+     * using {@link addServer}).
+     *
+     * @param config - Configuration object or path to JSON config file. If omitted,
+     *                 starts with empty configuration
+     * @param options - Optional client behavior configuration
+     * Options can enable code mode or provide sampling and elicitation callbacks.
+     *
+     * @example
+     * ```typescript
+     * // From config file
+     * const client = new MCPClient('./mcp-config.json');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // From inline config
+     * const client = new MCPClient({
+     *   mcpServers: {
+     *     'my-server': {
+     *       command: 'node',
+     *       args: ['server.js']
+     *     }
+     *   }
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With code mode enabled
+     * const client = new MCPClient('./config.json', {
+     *   codeMode: true
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With sampling callback
+     * const client = new MCPClient('./config.json', {
+     *   onSampling: async (params) => {
+     *     // Call your LLM here
+     *     return anthropic.messages.create(params);
+     *   }
+     * });
+     * ```
+     *
+     * @see {@link fromDict} for creating from config object (alternative syntax)
+     * @see {@link fromConfigFile} for creating from file (alternative syntax)
+     */
+    constructor(config?: string | Record<string, any>, options?: MCPClientOptions);
+    /**
+     * Creates a client instance from a configuration dictionary.
+     *
+     * This static factory method provides an alternative syntax for creating
+     * a client from an inline configuration object.
+     *
+     * @param cfg - Configuration dictionary with server definitions
+     * @param options - Optional client behavior configuration
+     * @returns New MCPClient instance
+     *
+     * @example
+     * ```typescript
+     * const client = MCPClient.fromDict({
+     *   mcpServers: {
+     *     'filesystem': {
+     *       command: 'npx',
+     *       args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp']
+     *     }
+     *   }
+     * });
+     * ```
+     *
+     * @see {@link MCPClient} for direct instantiation
+     * @see {@link fromConfigFile} for loading from file
+     */
+    static fromDict(cfg: Record<string, any>, options?: MCPClientOptions): MCPClient;
+    /**
+     * Creates a client instance from a configuration file.
+     *
+     * This static factory method loads MCP server configurations from a JSON
+     * file and creates a new client instance.
+     *
+     * @param path - Path to the JSON configuration file
+     * @param options - Optional client behavior configuration
+     * @returns New MCPClient instance
+     * @throws If the file cannot be read or parsed
+     *
+     * @example
+     * ```typescript
+     * const client = MCPClient.fromConfigFile('./mcp-config.json');
+     * await client.createAllSessions();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With code mode
+     * const client = MCPClient.fromConfigFile('./config.json', {
+     *   codeMode: true
+     * });
+     * ```
+     *
+     * @see {@link MCPClient} for direct instantiation
+     * @see {@link fromDict} for inline configuration
+     */
+    static fromConfigFile(path: string, options?: MCPClientOptions): MCPClient;
+    /**
+     * Saves the current configuration to a file.
+     *
+     * This Node.js-specific method writes the client's current configuration
+     * (including all server definitions) to a JSON file. The directory will be
+     * created if it doesn't exist.
+     *
+     * @param filepath - Path where the configuration file should be saved
+     *
+     * @example
+     * ```typescript
+     * const client = new MCPClient();
+     * client.addServer('my-server', {
+     *   command: 'node',
+     *   args: ['server.js']
+     * });
+     *
+     * // Save configuration for later use
+     * client.saveConfig('./mcp-config.json');
+     * ```
+     *
+     * @see {@link fromConfigFile} for loading configurations
+     */
+    saveConfig(filepath: string): void;
+    protected createDefaultOAuthProvider(serverUrl: string, options?: AutoOAuthOptions): Promise<OAuthClientProvider>;
+    /**
+     * Create a connector from server configuration (Node.js version)
+     * Supports all connector types including StdioConnector (lazy-loaded to avoid pulling Node-only code into browser bundles).
+     */
+    protected createConnectorFromConfig(serverConfig: Record<string, any>): Promise<BaseConnector>;
+    private _setupCodeModeConnector;
+    private _ensureCodeExecutor;
+    /**
+     * Executes JavaScript/TypeScript code in a sandboxed environment.
+     *
+     * This method is only available when code mode is enabled. It executes the
+     * provided code in an isolated environment (VM or E2B sandbox) and returns
+     * the results including stdout, stderr, and return value.
+     *
+     * @param code - JavaScript/TypeScript code to execute
+     * @param timeout - Optional execution timeout in milliseconds
+     * @returns Execution result with output, errors, and return value
+     * @throws If code mode is not enabled
+     *
+     * @example
+     * ```typescript
+     * const client = new MCPClient('./config.json', { codeMode: true });
+     *
+     * const result = await client.executeCode(`
+     *   console.log('Hello, world!');
+     *   return 2 + 2;
+     * `);
+     *
+     * console.log(result.stdout);      // "Hello, world!\n"
+     * console.log(result.returnValue); // 4
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With timeout
+     * try {
+     *   const result = await client.executeCode('while(true) {}', 1000);
+     * } catch (error) {
+     *   console.log('Execution timed out');
+     * }
+     * ```
+     *
+     * @see {@link searchTools} for discovering available tools in code mode
+     */
+    executeCode(code: string, timeout?: number): Promise<ExecutionResult>;
+    /**
+     * Searches for available tools across all MCP servers.
+     *
+     * This method is only available when code mode is enabled. It searches
+     * through tools from all active servers and returns matching tools based
+     * on the query and detail level.
+     *
+     * @param query - Optional search query to filter tools (defaults to empty string for all tools)
+     * @param detailLevel - Level of detail to return: "names", "descriptions", or "full"
+     * @returns Tool search results with matching tools
+     * @throws If code mode is not enabled
+     *
+     * @example
+     * ```typescript
+     * const client = new MCPClient('./config.json', { codeMode: true });
+     * await client.createAllSessions();
+     *
+     * // Search for all tools
+     * const allTools = await client.searchTools();
+     * console.log(`Found ${allTools.tools.length} tools`);
+     *
+     * // Search for specific tools
+     * const fileTools = await client.searchTools('file', 'descriptions');
+     * ```
+     *
+     * @see {@link executeCode} for executing code in code mode
+     */
+    searchTools(query?: string, detailLevel?: "names" | "descriptions" | "full"): Promise<ToolSearchResponse>;
+    /**
+     * Gets the names of all configured MCP servers (excluding internal servers).
+     *
+     * This method overrides the base implementation to filter out internal
+     * meta-servers like the code mode server, which is an implementation detail
+     * not intended for direct user interaction.
+     *
+     * @returns Array of user-configured server names
+     *
+     * @example
+     * ```typescript
+     * const names = client.getServerNames();
+     * console.log(`User servers: ${names.join(', ')}`);
+     * // Note: 'code_mode' is excluded even if code mode is enabled
+     * ```
+     *
+     * @see {@link activeSessions} for servers with active sessions
+     */
+    getServerNames(): string[];
+    /**
+     * Closes the client and cleans up all resources.
+     *
+     * This method performs a complete cleanup by:
+     * 1. Shutting down code executors (VM or E2B sandboxes)
+     * 2. Closing all active MCP sessions
+     * 3. Releasing any other held resources
+     *
+     * Always call this method when you're done with the client to ensure
+     * proper resource cleanup, especially when using E2B sandboxes which
+     * have associated costs.
+     *
+     * @example
+     * ```typescript
+     * const client = new MCPClient('./config.json', { codeMode: true });
+     * await client.createAllSessions();
+     *
+     * // Do work...
+     *
+     * // Clean up
+     * await client.close();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Use in shutdown handler
+     * process.on('SIGINT', async () => {
+     *   console.log('Shutting down...');
+     *   await client.close();
+     *   process.exit(0);
+     * });
+     * ```
+     *
+     * @see {@link closeAllSessions} for closing just the sessions
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=node.d.ts.map

package/dist/core/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/core/node.ts"],"names":[],"mappings":"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"}