@civic/nexus-bridge/dist/bridge.d.ts

Stdio <-> HTTP/SSE MCP bridge with Civic auth handling

/**
 * bridge.ts
 *
 * Connects stdio-based MCP clients (like Claude Desktop) with HTTP/SSE-based MCP servers.
 * Handles all aspects of message forwarding, authentication, and reconnection.
 *
 * Core Responsibilities:
 * 1. Authentication Flow: Manages Civic Auth login on startup by checking/refreshing tokens
 *    and opening a browser for login when needed. Authentication is handled in
 *    authProvider.ts which implements the OAuth PKCE flow.
 *
 * 2. Message Routing: Acts as a bidirectional proxy between local clients using
 *    stdio transport and remote servers using HTTP/SSE. All messages are converted
 *    from the local format to the remote format with authentication headers added.
 *
 * 3. Service Authorization: Detects when a remote server requires additional
 *    authorization (e.g., for a third-party API), opens the browser to complete
 *    the auth flow, and polls for completion.
 */
/**
 * The Bridge class implements the complete bridge functionality.
 * It handles:
 * 1. Local stdio server for LLM client connection
 * 2. Remote HTTP/SSE client for server connection
 * 3. Message forwarding in both directions
 * 4. Authentication flows and token management
 * 5. Service authorization detection and handling
 * 6. Request timeout management
 * 7. Capability registration and synchronization
 */
export declare class Bridge {
    private localServer;
    private remoteClient;
    private stdioTransport;
    private sseTransport;
    private authProvider;
    private serviceAuthorizationHandler;
    private isLocalServerConnected;
    private isRemoteClientConnected;
    private isShuttingDown;
    private clientMonitor;
    private remoteCapabilities;
    private requestTimeoutMs;
    private isReconnecting;
    private reconnectTimeoutId;
    constructor();
    /**
     * Main entry point to start the bridge
     *
     * The bridge startup flow follows these steps:
     * 1. Sets up token change listeners to handle auth events
     * 2. Attempts to connect to the remote server
     *    - If successful, starts the local server
     *    - If auth is needed, the auth flow is triggered by authProvider
     *    - Once auth completes, the token change listener will reconnect
     *      and start the local server
     */
    start(): Promise<void>;
    /**
     * Set up a listener for token changes to trigger reconnections
     *
     * When new tokens are received (either via refresh or browser login),
     * this handler will reconnect to the remote server with the new tokens.
     * If the local server isn't running yet, it will be started after
     * successful authentication.
     */
    private setupTokenChangeListener;
    /**
     * Attempt to connect to the remote server
     *
     * This method handles the following:
     * 1. Creating a new SSE transport with the authProvider
     * 2. Connecting to the remote server
     * 3. Handling authentication errors (401) by triggering auth flow
     * 4. Setting up reconnection on connection failures
     *
     * The authProvider is responsible for adding auth tokens to requests
     * and handling the OAuth flow when needed.
     *
     * @param isTokenTriggered Whether this connection attempt was triggered by a token change
     * @returns boolean indicating if connection was successful
     */
    private connectToRemoteServer;
    /**
     * Start the local stdio server
     *
     * This method starts the bridge's local stdio server to accept
     * connections from local clients (e.g., Claude Desktop).
     * It sets up event handlers and registers the request handler
     * that forwards requests to the remote server.
     */
    private startLocalServer;
    /**
     * Handle a request from the local client
     *
     * This is the core message routing function that:
     * 1. Receives requests from the local stdio client
     * 2. Routes local tool requests to local handlers
     * 3. Forwards all other requests to the remote server
     * 4. Handles special cases like tools/list to merge local tools
     */
    private handleLocalRequest;
    /**
     * Forward a request to the remote server, handling connection checks,
     * timeouts, and secondary authorization flows.
     *
     * This method:
     * 1. Ensures an active connection to the remote server
     * 2. Forwards the request with proper timeout handling
     * 3. Processes the result with the ServiceAuthorizationHandler
     *    to detect and handle service auth flows
     */
    private forwardRequest;
    /**
     * Register notification handlers for the remote client
     * This sets up a fallback handler to forward all remote notifications to the local server
     */
    private setupNotificationHandlers;
    /**
     * Set up signal handlers for graceful shutdown
     */
    private setupSignalHandlers;
    /**
     * Set up detection for client disconnection using the ClientConnectionMonitor
     */
    private setupClientDisconnectionDetection;
    /**
     * Gracefully shut down the bridge
     */
    shutdown(): Promise<void>;
}
//# sourceMappingURL=bridge.d.ts.map