pocketsmith-mcp/dist/mcp-client/core/clientManager.d.ts

MCP server for managing budgets via PocketSmith API

/**
 * @fileoverview Defines the McpClientManager class for orchestrating MCP client connections.
 * This module provides a class-based approach to managing MCP server connections,
 * allowing for isolated sets of connections, suitable for multi-agent or swarm scenarios.
 * Each instance of McpClientManager maintains its own cache of active and pending connections.
 *
 * Key responsibilities include:
 * - Providing `connectMcpClient` to establish or retrieve cached/pending connections within an instance.
 * - Providing `disconnectMcpClient` to terminate a specific server connection with a timeout.
 * - Providing `disconnectAllMcpClients` for graceful shutdown of all connections managed by an instance.
 *
 * @module src/mcp-client/core/clientManager
 */
import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { McpError } from "../../types-global/errors.js";
import { RequestContext } from "../../utils/index.js";
export type ConnectedMcpClient = Client;
/**
 * Manages a distinct, isolated set of MCP client connections.
 * Each instance of this class has its own connection cache, making it suitable
 * for scenarios like agent swarms where each agent needs its own connection pool.
 */
export declare class McpClientManager {
    private connectedClients;
    private pendingConnections;
    /**
     * Creates, connects, or returns an existing/pending MCP client instance for a specified server
     * within this manager's scope.
     *
     * @param serverName - The unique name of the MCP server to connect to.
     * @param parentContext - Optional parent `RequestContext` for logging and tracing.
     * @returns A promise that resolves to the connected and initialized `ConnectedMcpClient` instance.
     * @throws {McpError} If connection or initialization fails, or if configuration is invalid.
     */
    connectMcpClient(serverName: string, parentContext?: RequestContext | null): Promise<ConnectedMcpClient>;
    /**
     * Disconnects a specific MCP client managed by this instance, closes its transport with a timeout,
     * and removes it from the cache.
     *
     * @param serverName - The name of the server whose client connection should be terminated.
     * @param parentContext - Optional parent `RequestContext` for logging.
     * @param error - Optional error that triggered the disconnect, for logging.
     * @returns A promise that resolves when the disconnection attempt is complete.
     */
    disconnectMcpClient(serverName: string, parentContext?: RequestContext | null, error?: Error | McpError): Promise<void>;
    /**
     * Disconnects all currently active MCP client connections managed by this instance.
     *
     * @param parentContext - Optional parent `RequestContext` for logging.
     * @returns A promise that resolves when all disconnection attempts are processed.
     */
    disconnectAllMcpClients(parentContext?: RequestContext | null): Promise<void>;
    /**
     * Clears all cached clients and pending connections for this manager instance.
     */
    private clearAllCache;
    /**
     * Asynchronously retrieves a map of all available tools from all connected MCP servers by actively fetching them.
     * @param parentContext - The context of the calling operation.
     * @returns A promise that resolves to a map where keys are tool names and values are their definitions.
     */
    getAllTools(parentContext?: RequestContext | null): Promise<Map<string, unknown>>;
    /**
     * Finds the server name for a given tool from the cached tool map.
     * This is a synchronous method and relies on `getAllTools` having been called first.
     * @param toolName - The name of the tool to find.
     * @param allTools - The map of all available tools.
     * @returns The server name, or null if the tool is not found.
     */
    getServerForTool(toolName: string, allTools: Map<string, unknown>): string | null;
}