@agentionai/agents 1.0.2 → 1.2.0

package/dist/mcp/MCPClient.d.ts

@@ -1,5 +1,33 @@
+import EventEmitter from "events";
 import { Tool } from "../tools/Tool";
-import { MCPStdioConfig, MCPHttpConfig, MCPClientOptions } from "./types";
+import { MCPCallOptionsSource, MCPCallToolResult, MCPClientEventMap, MCPClientOptions, MCPConnectionState, MCPHttpConfig, MCPStdioConfig, MCPToolCallOptions } from "./types";
+/**
+ * Names of the events an {@link MCPClient} emits.
+ *
+ * @example
+ * ```typescript
+ * mcp.on(MCPClientEvent.DISCONNECTED, ({ willReconnect }) => {
+ *   if (!willReconnect) scheduleManualReconnect();
+ * });
+ * ```
+ */
+export declare class MCPClientEvent {
+    /** Emitted after a successful {@link MCPClient.connect}. */
+    static CONNECTED: "connected";
+    /** Emitted whenever the connection is lost, deliberately or not. */
+    static DISCONNECTED: "disconnected";
+    /** Emitted before each automatic reconnect attempt. */
+    static RECONNECTING: "reconnecting";
+    /** Emitted when an automatic reconnect succeeds. */
+    static RECONNECTED: "reconnected";
+    /** Emitted when the server's tool list changes. */
+    static TOOLS_CHANGED: "toolsChanged";
+    /**
+     * Emitted for out-of-band transport errors and for failures inside background
+     * work such as reconnection or tool refresh.
+     */
+    static ERROR: "error";
+}
 /**
  * MCPClient connects to an MCP (Model Context Protocol) server and converts its
  * tools into agention-lib {@link Tool} instances that can be passed to any agent.
@@ -8,6 +36,9 @@ import { MCPStdioConfig, MCPHttpConfig, MCPClientOptions } from "./types";
  * - **stdio** — spawns a local process and communicates over stdin/stdout
  * - **http** — connects to a remote MCP server over Streamable HTTP
  *
+ * The client is an `EventEmitter`; see {@link MCPClientEvent} for the lifecycle
+ * events a host can watch.
+ *
  * @requires @modelcontextprotocol/sdk - Install as a peer dependency:
  * ```
  * npm install @modelcontextprotocol/sdk
@@ -46,6 +77,20 @@ import { MCPStdioConfig, MCPHttpConfig, MCPClientOptions } from "./types";
  * agent.addTools(mcp.getTools());
  * ```
  *
+ * @example Cancellable, time-boxed tool calls
+ * ```typescript
+ * let turn = new AbortController();
+ *
+ * const mcp = MCPClient.fromUrl("https://my-mcp-server.com/mcp", {
+ *   // Resolved per call, so each agent turn gets the current signal
+ *   callOptions: () => ({ signal: turn.signal, timeout: 20_000 }),
+ *   reconnect: { enabled: true },
+ * });
+ *
+ * // Interrupting the turn now aborts any in-flight MCP call
+ * turn.abort();
+ * ```
+ *
  * @example HTTP with OAuth
  * ```typescript
  * import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
@@ -55,19 +100,34 @@ import { MCPStdioConfig, MCPHttpConfig, MCPClientOptions } from "./types";
  * });
  * ```
  */
-export declare class MCPClient {
+export declare class MCPClient extends EventEmitter {
     private readonly transportConfig;
-    private readonly options;
+    private readonly clientName;
+    private readonly clientVersion;
+    private readonly throwOnToolError;
+    private readonly refreshToolsOnListChanged;
+    private readonly formatResult;
+    private readonly reconnectOptions;
+    private callOptions;
     private sdkClient;
     private sdkTransport;
     private _tools;
-    private connected;
+    /** Signature per tool name, used to keep Tool identity stable across refreshes. */
+    private toolSignatures;
+    private _state;
+    private connectPromise;
+    private reconnectPromise;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private reconnectWake;
+    private closedByUser;
+    private lastTransportError;
     private constructor();
     /**
      * Create an MCPClient that connects to a local MCP server process via stdio.
      *
      * @param config - Command and arguments to spawn the MCP server process
-     * @param options - Optional client identification options
+     * @param options - Optional client identification and behaviour options
      */
     static fromStdio(config: MCPStdioConfig, options?: MCPClientOptions): MCPClient;
     /**
@@ -80,7 +140,8 @@ export declare class MCPClient {
     /**
      * Connect to the MCP server and discover all available tools.
      *
-     * This method is idempotent — calling it when already connected is a no-op.
+     * This method is idempotent — calling it when already connected is a no-op, and
+     * concurrent calls share a single connection attempt.
      * Must be called before {@link getTools}.
      *
      * @throws If the MCP server cannot be reached or the SDK is not installed
@@ -92,15 +153,131 @@ export declare class MCPClient {
      * Returns an empty array if {@link connect} has not been called yet.
      * The returned tools can be passed directly to any agent via the `tools` config
      * option or {@link BaseAgent.addTools}.
+     *
+     * Tool instances are stable across reconnects and tool-list refreshes: a tool
+     * whose definition is unchanged keeps its identity, so agents already holding it
+     * keep working. Listen for {@link MCPClientEvent.TOOLS_CHANGED} to learn when the
+     * list itself changed.
      */
     getTools(): Tool<unknown>[];
+    /**
+     * Current connection state.
+     *
+     * @see {@link MCPConnectionState}
+     */
+    getState(): MCPConnectionState;
+    /** Whether the client currently has a usable connection. */
+    isConnected(): boolean;
+    /**
+     * Replace the default options applied to every tool call.
+     *
+     * Pass a function to have them resolved per call — the usual way to scope an
+     * `AbortSignal` to the current agent turn.
+     *
+     * @example
+     * ```typescript
+     * mcp.setCallOptions(() => ({ signal: currentTurn.signal, timeout: 15_000 }));
+     * ```
+     */
+    setCallOptions(options: MCPCallOptionsSource | undefined): void;
+    /**
+     * Call an MCP tool directly and receive the raw `CallToolResult`, including any
+     * image, audio or resource blocks and the `isError` flag.
+     *
+     * Unlike the wrapped {@link Tool} instances from {@link getTools}, this does not
+     * render the result or throw on `isError` — it is the escape hatch for hosts
+     * that want to handle MCP content themselves.
+     *
+     * @param name - Name of the tool as advertised by the server
+     * @param input - Arguments for the tool
+     * @param options - Per-call options, merged over the client defaults
+     */
+    callTool(name: string, input?: Record<string, unknown>, options?: MCPToolCallOptions): Promise<MCPCallToolResult>;
+    /**
+     * Re-run tool discovery against the connected server.
+     *
+     * Called automatically when the server sends `notifications/tools/list_changed`
+     * (unless `refreshToolsOnListChanged` is disabled) and after a successful
+     * reconnect. Emits {@link MCPClientEvent.TOOLS_CHANGED} when the list differs.
+     *
+     * @returns The refreshed tool list
+     */
+    refreshTools(): Promise<Tool<unknown>[]>;
     /**
      * Disconnect from the MCP server and release all resources.
      *
-     * This method is idempotent — calling it when not connected is a no-op.
-     * After disconnecting, {@link getTools} returns an empty array.
+     * This method is idempotent — calling it when not connected is a no-op. It also
+     * cancels any pending automatic reconnect. After disconnecting, {@link getTools}
+     * returns an empty array; call {@link connect} again to start over.
      */
     disconnect(): Promise<void>;
+    /**
+     * Subscribe to a client lifecycle event.
+     *
+     * @see {@link MCPClientEvent} for the available event names.
+     */
+    on<K extends keyof MCPClientEventMap>(event: K, listener: (payload: MCPClientEventMap[K]) => void): this;
+    on(event: string | symbol, listener: (...args: any[]) => void): this;
+    /** Subscribe to a client lifecycle event for a single emission. */
+    once<K extends keyof MCPClientEventMap>(event: K, listener: (payload: MCPClientEventMap[K]) => void): this;
+    once(event: string | symbol, listener: (...args: any[]) => void): this;
+    /**
+     * Open the SDK client and transport, wire up lifecycle handlers and discover
+     * tools. Shared by {@link connect} and the reconnect loop.
+     */
+    private establish;
+    /**
+     * Ask the server to notify us about tool list changes. Failures here are not
+     * fatal — an older SDK or a server without the capability simply means the
+     * cached list stays as it was at connect time.
+     */
+    private subscribeToToolListChanges;
+    /** Page through `tools/list` until the server stops handing back a cursor. */
+    private listAllTools;
+    /**
+     * Reconcile the cached tool list with a fresh set of definitions, reusing the
+     * existing {@link Tool} instance for every definition that has not changed so
+     * agents holding a reference keep working.
+     */
+    private applyToolDefinitions;
+    /**
+     * Handle the transport closing. Deliberate closes are reported by
+     * {@link disconnect} itself; everything else is an unexpected drop.
+     */
+    private handleClose;
+    private handleTransportError;
+    /**
+     * Retry {@link establish} with exponential backoff until it succeeds, the retry
+     * budget runs out, or {@link disconnect} is called.
+     */
+    private startReconnectLoop;
+    private waitBeforeReconnect;
+    private cancelReconnectWait;
+    /**
+     * `EventEmitter` throws when an `error` event has no listener, which would turn
+     * a background transport hiccup into a process crash. Only emit when someone is
+     * actually listening.
+     */
+    private emitError;
+    private emitEvent;
+    /**
+     * Resolve the effective request options for a call: client defaults (static or
+     * per-call), with explicit per-call options layered on top.
+     */
+    private resolveCallOptions;
+    /**
+     * Wait for the client to become usable, then issue the call. Wrapping every
+     * transport-level failure keeps the error surface stable, while `cause` lets a
+     * host tell an abort apart from a server error.
+     */
+    private invokeTool;
+    /**
+     * Return the SDK client once one is usable. While a reconnect is in flight the
+     * call waits for it rather than failing outright, so a transient drop does not
+     * surface as a tool error — but an aborted signal still wins immediately.
+     */
+    private awaitUsableClient;
+    private raceAbort;
     private wrapMcpTool;
 }
 //# sourceMappingURL=MCPClient.d.ts.map