@mcp-use/client 0.0.0-bootstrap.0 → 2.0.0-beta.1

package/dist/core/node.d.ts

@@ -0,0 +1,441 @@
+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 {@link 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 BaseMCPClient} for base client functionality
+ * @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 _customCodeExecutor;
+    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
+     * @param options.codeMode - Enable code execution mode (boolean or advanced config)
+     * @param options.onSampling - Callback for handling sampling requests from servers
+     * @param options.onElicitation - Callback for handling elicitation requests
+     *
+     * @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 constructor} 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 {Error} 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 constructor} 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 {Error} 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 {Error} 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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"}