@cyanmycelium/mcp-broker 0.4.0 → 1.2.0

package/dist/ws.tunnel.d.ts

@@ -1,373 +0,0 @@
-import type { GrammarResolverOptions, IMessageTransport } from "@cyanmycelium/mcp-core";
-import { type StdioUpstreamConfig } from "./stdio.upstream.js";
-import { type RemoteUpstreamConfig } from "./remote.upstream.js";
-import type { BrokerContext, BrokerProviderInfo } from "./broker/index.js";
-/**
- * A single static-file mount: serves the contents of `dir` under `urlPrefix`.
- *
- * @example
- * { urlPrefix: "/",       dir: "/absolute/path/to/www" }
- * { urlPrefix: "/bundle", dir: "/absolute/path/to/bundle" }
- */
-export interface StaticMount {
-    /** URL prefix that triggers this mount (e.g. `"/"` or `"/bundle"`). */
-    urlPrefix: string;
-    /** Absolute path to the directory to serve. */
-    dir: string;
-}
-/**
- * In-process client handle for a provider slot — the symmetric counterpart of
- * {@link WsTunnel.registerLoopbackProvider}. Lets a component inside the broker
- * process (e.g. the aggregate server) issue MCP requests to a provider slot and
- * receive both the responses and the provider's broadcast notifications,
- * without opening a real network connection.
- */
-export interface InternalClient {
-    /**
-     * Sends a JSON-RPC message to the provider slot. When the message carries an
-     * `id`, the matching response is delivered to {@link onMessage}. When the
-     * provider is not connected, a JSON-RPC error is delivered synchronously.
-     */
-    send(message: string): void;
-    /** Receives responses to this client's requests and the provider's notifications. */
-    onMessage: ((data: string) => void) | null;
-    /** Fires when the provider slot loses its connection. */
-    onClose: (() => void) | null;
-    /** Detaches this internal client; pending requests are dropped. */
-    close(): void;
-}
-/**
- * Configuration options for a {@link WsTunnel} instance.
- */
-export interface WsTunnelOptions {
-    /** TCP port to listen on. */
-    port: number;
-    /**
-     * Host/interface to bind to.
-     * @default "0.0.0.0"
-     */
-    host?: string;
-    /**
-     * URL path **prefix** the MCP provider connects to via WebSocket.
-     * Each provider appends its name: `<providerPath>/<encodedName>`.
-     * @default "/provider"
-     */
-    providerPath?: string;
-    /**
-     * URL path for **multiplexed** provider connections.
-     * A single WebSocket carries traffic for multiple providers using the
-     * envelope protocol `{ provider: string, payload: object }`.
-     * @default "/providers"
-     */
-    providersPath?: string;
-    /**
-     * URL path raw WebSocket MCP clients connect to.
-     * @default "/"
-     */
-    clientPath?: string;
-    /**
-     * **Suffix** appended to a provider name for the SSE endpoint.
-     * Full URL: `/<providerName>/sse`
-     * @default "/sse"
-     */
-    ssePath?: string;
-    /**
-     * **Suffix** appended to a provider name for the legacy SSE POST endpoint.
-     * Full URL: `/<providerName>/messages`
-     * @default "/messages"
-     */
-    messagesPath?: string;
-    /**
-     * **Suffix** appended to a provider name for the Streamable HTTP endpoint (MCP 2025-03-26).
-     * Full URL: `/<providerName>/mcp`
-     * MCP Inspector connects here.
-     * @default "/mcp"
-     */
-    mcpPath?: string;
-    /**
-     * URL path that returns a `{ files: string[] }` JSON listing of every file
-     * inside the `samples/` subdirectory of the root static mount.
-     * @default "/__samples_index__"
-     */
-    samplesIndexPath?: string;
-    /**
-     * Optional static-file mounts served over plain HTTP.
-     * Matched by longest URL prefix; directory requests fall back to `index.html`.
-     */
-    staticMounts?: StaticMount[];
-    /**
-     * Stdio upstream providers. Each entry spawns a child process and wires its
-     * stdin/stdout as an MCP transport. Clients reach the process using its `name`
-     * directly.
-     *
-     * If a WebSocket provider connects with the same name as a stdio upstream, the
-     * connection is rejected and a warning is logged — stdio takes priority.
-     * @default undefined — no stdio providers
-     */
-    stdioUpstreams?: StdioUpstreamConfig[];
-    /** Remote MCP servers reached by URL, exposed as provider slots. */
-    remoteUpstreams?: RemoteUpstreamConfig[];
-    /**
-     * Stdio client transport. When set, the broker reads JSON-RPC from
-     * `process.stdin` and writes responses to `process.stdout`, bridging an
-     * external MCP client (e.g. Claude Desktop) to the named provider.
-     *
-     * In this mode ALL logging is redirected to stderr so stdout stays clean
-     * for the JSON-RPC stream.
-     *
-     * Claude Desktop config example:
-     * ```json
-     * {
-     *   "command": "npx",
-     *   "args": ["-y", "@cyanmycelium/mcp-broker"],
-     *   "env": { "MCP_BROKER_STDIO_PROVIDER": "my-provider" }
-     * }
-     * ```
-     * @default undefined — stdio client transport disabled
-     */
-    stdioClient?: {
-        providerName: string;
-    };
-    /**
-     * TLS configuration. When provided, the server uses HTTPS and WSS instead of HTTP and WS.
-     * Both `cert` and `key` must be PEM-encoded strings (file contents, not file paths).
-     * Use {@link WsTunnelBuilder.withTlsFiles} to load from disk paths.
-     * @default undefined — plain HTTP/WS
-     */
-    tls?: {
-        /** PEM-encoded TLS certificate. */
-        cert: string;
-        /** PEM-encoded private key. */
-        key: string;
-    };
-    /**
-     * When `true` (default), the broker exposes itself as an MCP server under the
-     * reserved slot `_broker`. Tier-1 behaviors (`broker_info`, `providers_list`,
-     * `provider_status`) become callable at `<host>/_broker/mcp`.
-     *
-     * Set to `false` to keep the broker invisible to MCP clients.
-     * @default true
-     */
-    enableBrokerProvider?: boolean;
-    /**
-     * When `true` (default), the broker exposes the reserved slot `_all` — an
-     * aggregate MCP server that unions the tools and prompts of every provider
-     * that opted in via the registration handshake. Reachable like any other
-     * slot (`<host>/_all/mcp`, etc.).
-     *
-     * Set to `false` to disable aggregation entirely.
-     * @default true
-     */
-    enableAggregateProvider?: boolean;
-    /**
-     * Logical name reported by `broker_info`. Useful when running multiple
-     * broker instances and you want to tell them apart from the agent side
-     * (e.g. `"broker-eu-west"`).
-     * @default PACKAGE_NAME — `@cyanmycelium/mcp-broker`
-     */
-    brokerName?: string;
-    /**
-     * Overrides for the embedded broker server's grammar resolver — passed
-     * straight through to `mcp-core`'s `grammarResolverFromOptions`. The
-     * broker installs its own default `localeSource` (reads
-     * `process.env.MCP_BROKER_LOCALE`); anything you set here wins.
-     *
-     * Use this to inject a custom `localeSource` (e.g. read from an HTTP
-     * header proxied by your transport), enable the optional `versionFrom`
-     * dimension, or extend the `agents` map with additional LLM families.
-     */
-    brokerGrammarResolverOptions?: Partial<GrammarResolverOptions>;
-    /**
-     * Path to a user-supplied grammars directory whose `<userAgent>/<locale>.json`
-     * files are registered alongside the packaged grammars used by the
-     * embedded broker server. Typically pointed at `.mcp-broker/grammars/`.
-     *
-     * The candidate-chain resolution in `McpServer.initialize`
-     * (mcp-core@0.3.0) handles cascade across user-agent and locale
-     * dimensions, so partial files no longer need to be pre-merged with a
-     * baseline.
-     */
-    brokerLocalGrammarsDir?: string;
-}
-/**
- * A multi-provider relay that bridges any number of MCP server instances
- * (the **providers**) with their respective MCP clients.
- *
- * ## Transport overview
- * ```
- * Provider "<name>"
- *   ws://host/provider/<name>           ← WebSocket registration
- *
- * MCP Inspector (Streamable HTTP, 2025-03-26)
- *   GET  http://host/<name>/mcp         ← persistent SSE notification stream
- *   POST http://host/<name>/mcp         → JSON-RPC requests
- *
- * Claude (legacy SSE transport)
- *   GET  http://host/<name>/sse              ← SSE notification stream
- *   POST http://host/<name>/messages         → JSON-RPC requests
- * ```
- *
- * Each provider gets its own isolated set of sessions, pending requests, and
- * notification streams. Multiple providers can be connected simultaneously.
- */
-export declare class WsTunnel implements BrokerContext {
-    private readonly _options;
-    private _httpServer;
-    private _wss;
-    /**
-     * Per-provider state, keyed by provider name.
-     * Created lazily: a slot is allocated the first time any client references
-     * a provider name, even before the provider WebSocket connects.
-     */
-    private readonly _providers;
-    /** Maps a multiplexed WebSocket to the set of provider names it feeds. */
-    private readonly _multiplexSockets;
-    /** Upstream providers (stdio child processes and remote URL servers), keyed by name. */
-    private readonly _upstreams;
-    /**
-     * In-process loopback transports registered as provider slots.
-     * Used by the embedded broker server (`_broker`) and any other component
-     * that wants to expose itself as a provider without going through a network.
-     */
-    private readonly _loopbackProviders;
-    /** The embedded broker MCP server, when {@link WsTunnelOptions.enableBrokerProvider} is on. */
-    private _brokerServer;
-    /** The aggregate MCP server (`_all` slot), when {@link WsTunnelOptions.enableAggregateProvider} is on. */
-    private _aggregateServer;
-    /** Provider name that the stdio client transport is bridged to, or null when disabled. */
-    private _stdioClientProvider;
-    /** Buffered partial line from stdin (stdio client transport). */
-    private _stdioClientBuffer;
-    /** Timestamp of the most recent successful `start()`. */
-    private _startedAt;
-    constructor(options: WsTunnelOptions);
-    get version(): string;
-    get name(): string;
-    get startedAt(): Date | null;
-    get uptimeSeconds(): number;
-    get host(): string | undefined;
-    get port(): number;
-    get tls(): boolean;
-    get paths(): BrokerContext["paths"];
-    getProvidersInfo(): BrokerProviderInfo[];
-    getProviderInfo(name: string): BrokerProviderInfo | undefined;
-    private _buildProviderInfo;
-    /**
-     * Registers an in-process transport as a provider slot. Used by the embedded
-     * broker server and may be used by application code that wants to host an
-     * MCP server inside the same process without opening a real WebSocket.
-     *
-     * @throws if the name is already used by a stdio upstream or another loopback.
-     */
-    registerLoopbackProvider(name: string, transport: IMessageTransport): void;
-    /**
-     * Opens an in-process client to a provider slot. The returned handle can
-     * issue MCP requests and receives both the responses and the provider's
-     * broadcast notifications. Used by the aggregate server to fan a single
-     * in-process client out to every aggregated provider.
-     *
-     * The slot does not need a provider attached yet — `send` returns a
-     * JSON-RPC error while the provider is disconnected.
-     */
-    openInternalClient(providerName: string): InternalClient;
-    get isListening(): boolean;
-    /** Total number of connected MCP clients across all providers. */
-    get clientCount(): number;
-    /** Names of all providers that currently have an active connection. */
-    get providerNames(): readonly string[];
-    /** @deprecated Check `providerNames.length > 0` instead. */
-    get hasProvider(): boolean;
-    /**
-     * Starts the broker. Resolves once the HTTP server is listening.
-     */
-    start(): Promise<void>;
-    /**
-     * Starts the in-process MCP server that exposes the broker's own behaviors
-     * (`broker_info`, `providers_list`, `provider_status`) under the reserved
-     * provider slot `_broker`. No-op when {@link WsTunnelOptions.enableBrokerProvider}
-     * is `false`.
-     */
-    private _maybeStartBrokerServer;
-    /**
-     * Starts the aggregate MCP server and registers it on the reserved `_all`
-     * slot. No-op when {@link WsTunnelOptions.enableAggregateProvider} is `false`.
-     */
-    private _maybeStartAggregateServer;
-    /**
-     * Gracefully closes all connections and stops the HTTP server.
-     */
-    stop(): Promise<void>;
-    private _handleHttp;
-    /**
-     * Parses `/<providerName>/<endpoint>` from a URL path.
-     * Returns `null` if the URL does not match this two-segment pattern.
-     */
-    private _parseProviderRoute;
-    /**
-     * Handles `GET /<providerName>/sse` — opens a long-lived SSE stream for Claude.
-     * Sends an `endpoint` event so Claude knows where to POST its requests.
-     */
-    private _handleSseConnect;
-    /**
-     * Handles `POST /<providerName>/messages?sessionId=…` — receives a JSON-RPC
-     * request from Claude and forwards it to the provider.
-     * Always responds 202 Accepted; the real response arrives over SSE.
-     */
-    private _handleSseMessage;
-    /**
-     * Handles `POST /<providerName>/mcp` — Streamable HTTP transport (MCP 2025-03-26).
-     * Forwards the JSON-RPC request to the provider and holds the HTTP response
-     * open until the reply arrives, then writes it as `application/json`.
-     */
-    private _handleMcpPost;
-    /**
-     * Handles `GET /<providerName>/mcp` — opens a persistent SSE stream per MCP 2025-03-26.
-     * Streamable HTTP clients (e.g. MCP Inspector) use this to receive
-     * server-initiated notifications without re-polling.
-     */
-    private _handleMcpGetStream;
-    /** Writes one JSON-RPC message as an SSE `message` event. */
-    private _sendSseEvent;
-    private _onProviderConnect;
-    /**
-     * Inspects a provider's first WebSocket message for an optional registration
-     * control frame `{ "type": "register", "aggregate": boolean }`. Returns
-     * `true` when the message was a registration frame — and thus consumed, not
-     * routed as MCP traffic. A normal MCP frame always carries `jsonrpc`, so it
-     * returns `false` and the provider stays non-aggregated.
-     */
-    private _tryHandleRegistration;
-    private _onClientConnect;
-    /**
-     * Handles a multiplexed provider WebSocket (`/providers`).
-     * A single socket carries traffic for multiple providers using the
-     * envelope format `{ provider: string, payload: object }`.
-     * Provider names are registered lazily on first message.
-     */
-    private _onMultiplexProviderConnect;
-    /**
-     * Sends a raw JSON-RPC message to a provider, wrapping it in a multiplex
-     * envelope when the provider's WebSocket is a multiplexed connection.
-     */
-    private _sendToProvider;
-    private _routeFromStdioClient;
-    private _routeFromClient;
-    private _routeFromProvider;
-    /** Sends a message to all clients connected to one provider. */
-    private _broadcast;
-    /**
-     * Notifies every pending sink and internal client that the provider slot
-     * has disconnected, then clears the pending map. Shared by all provider
-     * close handlers (dedicated WS, multiplexed WS, loopback).
-     */
-    private _failProviderDisconnected;
-    /**
-     * Returns `true` if the provider is reachable — via a WebSocket connection,
-     * a stdio upstream, or an in-process loopback transport.
-     */
-    private _isProviderConnected;
-    /** Returns the state for `name`, creating it lazily if it doesn't exist yet. */
-    private _getOrCreateProviderState;
-    private _handleSamplesIndex;
-    private _serveStatic;
-}