@cyanmycelium/mcp-broker 0.1.0

package/dist/ws.tunnel.builder.js

@@ -0,0 +1,197 @@
+import * as fs from "fs";
+import { WsTunnel } from "./ws.tunnel.js";
+/**
+ * Fluent builder that constructs a configured {@link WsTunnel}.
+ *
+ * @example
+ * ```typescript
+ * const tunnel = new WsTunnelBuilder()
+ *     .withPort(3000)
+ *     .withHost("localhost")
+ *     .withStaticMount("/", "/abs/path/to/www")
+ *     .build();
+ *
+ * await tunnel.start();
+ * console.log("Broker listening on ws://localhost:3000");
+ * console.log("  Provider connects to: ws://localhost:3000/provider/<name>");
+ * console.log("  Clients  connect to:  ws://localhost:3000/<name>");
+ * ```
+ */
+export class WsTunnelBuilder {
+    _port = 3000;
+    _host;
+    _providerPath = "/provider";
+    _providersPath = "/providers";
+    _clientPath = "/";
+    _ssePath = "/sse";
+    _messagesPath = "/messages";
+    _mcpPath = "/mcp";
+    _samplesIndexPath = "/__samples_index__";
+    _staticMounts = [];
+    _stdioUpstreams = [];
+    _stdioClient = undefined;
+    _tls = undefined;
+    _brokerLocalGrammarsDir = undefined;
+    /** Sets the TCP port the broker listens on. */
+    withPort(port) {
+        this._port = port;
+        return this;
+    }
+    /**
+     * Sets the host/interface to bind to.
+     * @default "0.0.0.0" (all interfaces)
+     */
+    withHost(host) {
+        this._host = host;
+        return this;
+    }
+    /**
+     * Sets the URL path the MCP provider connects to.
+     * @default "/provider"
+     */
+    withProviderPath(path) {
+        this._providerPath = path;
+        return this;
+    }
+    /**
+     * Sets the URL path for multiplexed provider connections.
+     * Multiple providers share a single WebSocket using the envelope protocol.
+     * @default "/providers"
+     */
+    withProvidersPath(path) {
+        this._providersPath = path;
+        return this;
+    }
+    /**
+     * Sets the URL path MCP clients connect to.
+     * @default "/"
+     */
+    withClientPath(path) {
+        this._clientPath = path;
+        return this;
+    }
+    /**
+     * Sets the URL path for the SSE stream (legacy Claude transport, GET).
+     * @default "/sse"
+     */
+    withSsePath(path) {
+        this._ssePath = path;
+        return this;
+    }
+    /**
+     * Sets the URL path for JSON-RPC POST requests (legacy Claude transport).
+     * @default "/messages"
+     */
+    withMessagesPath(path) {
+        this._messagesPath = path;
+        return this;
+    }
+    /**
+     * Sets the URL path for the Streamable HTTP transport (MCP 2025-03-26).
+     * MCP Inspector and other 2025+ clients POST JSON-RPC here.
+     * @default "/mcp"
+     */
+    withMcpPath(path) {
+        this._mcpPath = path;
+        return this;
+    }
+    /**
+     * Sets the URL path that returns a `{ files: string[] }` listing of the
+     * `samples/` subdirectory under the root static mount.
+     * @default "/__samples_index__"
+     */
+    withSamplesIndexPath(path) {
+        this._samplesIndexPath = path;
+        return this;
+    }
+    /**
+     * Adds a static-file mount served over plain HTTP.
+     * Can be called multiple times; longest-prefix match wins at runtime.
+     *
+     * @param urlPrefix  URL prefix that triggers this mount (e.g. `"/"` or `"/bundle"`).
+     * @param dir        Absolute path to the directory to serve.
+     */
+    withStaticMount(urlPrefix, dir) {
+        this._staticMounts.push({ urlPrefix, dir });
+        return this;
+    }
+    /**
+     * Registers a stdio upstream provider. The broker will spawn the given
+     * command and bridge its stdin/stdout as an MCP transport.
+     * Clients reach it using `name` directly (e.g. `/<name>/mcp`).
+     *
+     * Can be called multiple times to register multiple providers.
+     *
+     * @param name     Provider name (must be unique across all upstream types).
+     * @param command  Executable to spawn.
+     * @param args     Arguments passed to the command.
+     * @param env      Extra environment variables merged with `process.env`.
+     */
+    withStdioUpstream(name, command, args, env) {
+        this._stdioUpstreams.push({ name, command, args, env });
+        return this;
+    }
+    /**
+     * Enables the stdio client transport. The broker will read JSON-RPC from
+     * `process.stdin` and write responses to `process.stdout`, bridging Claude
+     * Desktop (or any stdio MCP client) to the named provider.
+     *
+     * All console output is automatically redirected to stderr in this mode so
+     * stdout stays clean for the JSON-RPC stream.
+     *
+     * @param providerName  The provider the stdio client maps to.
+     */
+    withStdioClient(providerName) {
+        this._stdioClient = { providerName };
+        return this;
+    }
+    /**
+     * Enables HTTPS/WSS mode by supplying PEM-encoded certificate and key strings directly.
+     * Call this when you already have the PEM content in memory.
+     */
+    withTls(cert, key) {
+        this._tls = { cert, key };
+        return this;
+    }
+    /**
+     * Enables HTTPS/WSS mode by reading the certificate and key from the given file paths.
+     * Files are read synchronously at call time.
+     *
+     * @param certPath  Path to the PEM certificate file (e.g. `fullchain.pem`).
+     * @param keyPath   Path to the PEM private-key file (e.g. `privkey.pem`).
+     */
+    withTlsFiles(certPath, keyPath) {
+        return this.withTls(fs.readFileSync(certPath, "utf8"), fs.readFileSync(keyPath, "utf8"));
+    }
+    /**
+     * Sets the path to a user-supplied grammars directory whose
+     * `<userAgent>/<locale>.json` files are merged on top of the packaged
+     * grammars used by the embedded broker server (the reserved `_broker`
+     * provider slot). Typically pointed at `.mcp-broker/grammars/`.
+     */
+    withBrokerLocalGrammarsDir(dir) {
+        this._brokerLocalGrammarsDir = dir;
+        return this;
+    }
+    /** Constructs and returns a configured {@link WsTunnel}. */
+    build() {
+        const options = {
+            port: this._port,
+            host: this._host,
+            providerPath: this._providerPath,
+            providersPath: this._providersPath,
+            clientPath: this._clientPath,
+            ssePath: this._ssePath,
+            messagesPath: this._messagesPath,
+            mcpPath: this._mcpPath,
+            samplesIndexPath: this._samplesIndexPath,
+            staticMounts: this._staticMounts.length > 0 ? [...this._staticMounts] : undefined,
+            stdioUpstreams: this._stdioUpstreams.length > 0 ? [...this._stdioUpstreams] : undefined,
+            stdioClient: this._stdioClient,
+            tls: this._tls,
+            brokerLocalGrammarsDir: this._brokerLocalGrammarsDir,
+        };
+        return new WsTunnel(options);
+    }
+}
+//# sourceMappingURL=ws.tunnel.builder.js.map

package/dist/ws.tunnel.builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.tunnel.builder.js","sourceRoot":"","sources":["../src/ws.tunnel.builder.ts"],"names":[],"mappings":"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"}

package/dist/ws.tunnel.d.ts

@@ -0,0 +1,310 @@
+import type { IMessageTransport } from "@cyanmycelium/mcp-core";
+import { type StdioUpstreamConfig } from "./stdio.upstream.js";
+import type { BrokerContext, BrokerLocaleResolver, BrokerProviderInfo, BrokerUserAgentResolver } 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;
+}
+/**
+ * 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[];
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Custom resolver picking the grammar locale for the embedded broker
+     * server. Defaults to `defaultBrokerLocaleResolver` (keeps the ISO 639-1
+     * prefix of a BCP-47 tag read from `MCP_BROKER_LOCALE`).
+     */
+    brokerLocaleResolver?: BrokerLocaleResolver;
+    /**
+     * Custom resolver mapping a connecting client's identity to a user-agent
+     * family. Defaults to `defaultBrokerUserAgentResolver` (substring match on
+     * `clientInfo.name` against known LLM families).
+     */
+    brokerUserAgentResolver?: BrokerUserAgentResolver;
+    /**
+     * Custom source of the raw locale string fed to the locale resolver.
+     * Defaults to `() => process.env.MCP_BROKER_LOCALE`. Override when the
+     * locale should come from a config file, HTTP header, etc.
+     */
+    brokerLocaleSource?: () => string | undefined;
+    /**
+     * Path to a user-supplied grammars directory whose `<userAgent>/<locale>.json`
+     * files are merged **on top of** the packaged grammars used by the embedded
+     * broker server. Typically pointed at `.mcp-broker/grammars/`.
+     */
+    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;
+    /** Stdio upstream providers, keyed by provider name. */
+    private readonly _stdioUpstreams;
+    /**
+     * 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;
+    /** 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;
+    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;
+    /**
+     * 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;
+    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;
+    /**
+     * 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;
+}