@cyanmycelium/mcp-broker 0.1.0

package/dist/broker/grammars/default/en.json

@@ -0,0 +1,32 @@
+{
+    "tools": {
+        "broker_info": {
+            "description": "Returns the broker's name, version, uptime, host, port, TLS status, and configured URL paths."
+        },
+        "providers_list": {
+            "description": "Returns every provider slot known to the broker (connected and disconnected), with transport kind, client count, and pending request count."
+        },
+        "provider_status": {
+            "description": "Returns the status of one provider slot identified by name. Errors if the slot does not exist.",
+            "properties": {
+                "name": "Exact provider name (case-sensitive)."
+            }
+        }
+    },
+    "resources": {
+        "broker://info": {
+            "name": "Broker info",
+            "description": "Broker identity, version, uptime, and listening configuration."
+        },
+        "broker://providers": {
+            "name": "Broker providers",
+            "description": "List of every provider slot known to the broker, including disconnected ones."
+        }
+    },
+    "templates": {
+        "broker://providers/{name}": {
+            "name": "Broker provider",
+            "description": "Snapshot of one specific provider slot, addressed by its name."
+        }
+    }
+}

package/dist/broker/grammars/default/fr.json

@@ -0,0 +1,32 @@
+{
+    "tools": {
+        "broker_info": {
+            "description": "Retourne le nom, la version, l'uptime, l'hôte, le port, l'état TLS et les chemins URL du broker."
+        },
+        "providers_list": {
+            "description": "Liste tous les emplacements de providers connus du broker (connectés et déconnectés), avec leur type de transport, leur nombre de clients et le nombre de requêtes en attente."
+        },
+        "provider_status": {
+            "description": "Retourne l'état d'un emplacement de provider identifié par son nom. Échoue si le provider n'existe pas.",
+            "properties": {
+                "name": "Nom exact du provider (sensible à la casse)."
+            }
+        }
+    },
+    "resources": {
+        "broker://info": {
+            "name": "Informations du broker",
+            "description": "Identité, version, uptime et configuration d'écoute du broker."
+        },
+        "broker://providers": {
+            "name": "Providers du broker",
+            "description": "Liste de tous les emplacements de providers connus du broker, y compris les déconnectés."
+        }
+    },
+    "templates": {
+        "broker://providers/{name}": {
+            "name": "Provider du broker",
+            "description": "Snapshot d'un emplacement de provider spécifique, identifié par son nom."
+        }
+    }
+}

package/dist/broker/grammars/default/zh.json

@@ -0,0 +1,32 @@
+{
+    "tools": {
+        "broker_info": {
+            "description": "返回 broker 的名称、版本、运行时间、主机、端口、TLS 状态和已配置的 URL 路径。"
+        },
+        "providers_list": {
+            "description": "列出 broker 已知的所有 provider 槽位（已连接和未连接），包括传输类型、客户端数量和待处理请求数量。"
+        },
+        "provider_status": {
+            "description": "返回由名称标识的某个 provider 槽位的状态。如果槽位不存在则返回错误。",
+            "properties": {
+                "name": "provider 的精确名称（区分大小写）。"
+            }
+        }
+    },
+    "resources": {
+        "broker://info": {
+            "name": "Broker 信息",
+            "description": "Broker 的身份、版本、运行时间和监听配置。"
+        },
+        "broker://providers": {
+            "name": "Broker Providers",
+            "description": "Broker 已知的所有 provider 槽位列表，包括未连接的。"
+        }
+    },
+    "templates": {
+        "broker://providers/{name}": {
+            "name": "Broker Provider",
+            "description": "指定名称的 provider 槽位快照。"
+        }
+    }
+}

package/dist/broker/index.d.ts

@@ -0,0 +1,9 @@
+export { BrokerInfoBehavior } from "./behaviors/broker.behavior.info.js";
+export { BrokerProvidersBehavior } from "./behaviors/broker.behavior.providers.js";
+export { BrokerInfoAdapter, BROKER_INFO_URI } from "./adapters/broker.adapter.info.js";
+export { BrokerProvidersAdapter, PROVIDERS_URI, PROVIDER_URI_TEMPLATE } from "./adapters/broker.adapter.providers.js";
+export { startBrokerServer, BROKER_PROVIDER_NAME } from "./broker.server.js";
+export type { StartBrokerServerOptions } from "./broker.server.js";
+export { brokerBaselineGrammar, brokerBaselinePropertyDescription, brokerBaselineResourceDescription, brokerBaselineResourceName, brokerBaselineResourceTemplateDescription, brokerBaselineResourceTemplateName, brokerBaselineToolDescription, brokerGrammarKey, defaultBrokerLocaleResolver, defaultBrokerUserAgentResolver, iterAvailableBrokerGrammars, loadBrokerGrammar, resolveBrokerLocale, resolveBrokerUserAgent, } from "./broker.grammars.js";
+export type { BrokerLocale, BrokerLocaleResolver, BrokerUserAgent, BrokerUserAgentResolver } from "./broker.grammars.js";
+export type { BrokerContext, BrokerProviderInfo, BrokerProviderTransport } from "./broker.context.js";

package/dist/broker/index.js

@@ -0,0 +1,7 @@
+export { BrokerInfoBehavior } from "./behaviors/broker.behavior.info.js";
+export { BrokerProvidersBehavior } from "./behaviors/broker.behavior.providers.js";
+export { BrokerInfoAdapter, BROKER_INFO_URI } from "./adapters/broker.adapter.info.js";
+export { BrokerProvidersAdapter, PROVIDERS_URI, PROVIDER_URI_TEMPLATE } from "./adapters/broker.adapter.providers.js";
+export { startBrokerServer, BROKER_PROVIDER_NAME } from "./broker.server.js";
+export { brokerBaselineGrammar, brokerBaselinePropertyDescription, brokerBaselineResourceDescription, brokerBaselineResourceName, brokerBaselineResourceTemplateDescription, brokerBaselineResourceTemplateName, brokerBaselineToolDescription, brokerGrammarKey, defaultBrokerLocaleResolver, defaultBrokerUserAgentResolver, iterAvailableBrokerGrammars, loadBrokerGrammar, resolveBrokerLocale, resolveBrokerUserAgent, } from "./broker.grammars.js";
+//# sourceMappingURL=index.js.map

package/dist/broker/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/broker/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACvF,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AACtH,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE7E,OAAO,EACH,qBAAqB,EACrB,iCAAiC,EACjC,iCAAiC,EACjC,0BAA0B,EAC1B,yCAAyC,EACzC,kCAAkC,EAClC,6BAA6B,EAC7B,gBAAgB,EAChB,2BAA2B,EAC3B,8BAA8B,EAC9B,2BAA2B,EAC3B,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,GACzB,MAAM,sBAAsB,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Shape of the optional JSON config file consumed by `bin.ts` at startup.
+ * Every field is optional. Environment variables (`MCP_BROKER_*`) always win
+ * over file values, and file values win over the built-in defaults.
+ *
+ * @example
+ * ```json
+ * {
+ *     "port": 3001,
+ *     "locale": "fr",
+ *     "tls": { "cert": "certs/cert.pem", "key": "certs/key.pem" },
+ *     "stdioUpstreams": [
+ *         { "name": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"] }
+ *     ]
+ * }
+ * ```
+ */
+export interface BrokerConfig {
+    /** TCP port. Maps to `MCP_BROKER_PORT`. */
+    port?: number;
+    /** Bind host. Maps to `MCP_BROKER_HOST`. */
+    host?: string;
+    /** Force protocol (`http`/`https`) regardless of cert presence. Maps to `MCP_BROKER_PROTOCOL`. */
+    protocol?: "http" | "https";
+    /** Locale fed to the broker grammar resolver. Maps to `MCP_BROKER_LOCALE`. */
+    locale?: string;
+    /** Bridge stdin/stdout for a Claude-Desktop-style client. Maps to `MCP_BROKER_STDIO_PROVIDER`. */
+    stdioProvider?: string;
+    /** Logical broker name reported by `broker_info`. */
+    brokerName?: string;
+    /** URL paths (override the defaults). */
+    paths?: {
+        provider?: string;
+        providers?: string;
+        client?: string;
+        mcp?: string;
+        sse?: string;
+        messages?: string;
+    };
+    /** TLS material as paths on disk. Resolved against the config file's directory. */
+    tls?: {
+        cert: string;
+        key: string;
+    };
+    /**
+     * Static-file serving alongside the JSON-RPC endpoints. JSON-RPC routes
+     * always take precedence.
+     */
+    www?: {
+        /** Auto-launch the default browser at the root URL on startup. */
+        open?: boolean;
+        /** URL-prefix → directory mappings. Longest-prefix match wins. */
+        mounts?: Array<{
+            urlPrefix: string;
+            dir: string;
+        }>;
+    };
+    /** Stdio upstream providers spawned by the broker at startup. */
+    stdioUpstreams?: Array<{
+        name: string;
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+    }>;
+}
+/**
+ * Returned by {@link loadBrokerConfig}. The {@link config} is the parsed JSON;
+ * {@link baseDir} is the directory used to resolve relative paths inside it
+ * (the directory containing the config file when one was found, otherwise
+ * `process.cwd()`).
+ */
+export interface LoadedBrokerConfig {
+    config: BrokerConfig;
+    baseDir: string;
+    /** Absolute path of the config file that was loaded, or `null` if none. */
+    sourcePath: string | null;
+}
+/** Default folder name (relative to `process.cwd()`) holding broker-local files. */
+export declare const DEFAULT_CONFIG_DIR = ".mcp-broker";
+/** Default config filename inside {@link DEFAULT_CONFIG_DIR}. */
+export declare const DEFAULT_CONFIG_FILENAME = "config.json";
+/** Legacy flat config filename at the cwd root (pre-`.mcp-broker/` layout). */
+export declare const LEGACY_CONFIG_FILENAME = "mcp-broker.config.json";
+/**
+ * Loads the broker config from a JSON file.
+ *
+ * Discovery order:
+ * 1. The `path` argument when provided (explicit override).
+ * 2. The `MCP_BROKER_CONFIG` env var.
+ * 3. `./.mcp-broker/config.json` relative to `process.cwd()`.
+ * 4. `./mcp-broker.config.json` relative to `process.cwd()` (legacy layout —
+ *    a deprecation warning is written to stderr).
+ *
+ * When no file is found, returns the built-in empty config with
+ * `baseDir = process.cwd()`. On invalid JSON, logs a warning to stderr and
+ * returns the same empty config — never throws.
+ *
+ * Paths inside the config file are intended to be resolved against
+ * {@link LoadedBrokerConfig.baseDir} by the consumer.
+ */
+export declare function loadBrokerConfig(path?: string): LoadedBrokerConfig;

package/dist/config.js

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+/** Default folder name (relative to `process.cwd()`) holding broker-local files. */
+export const DEFAULT_CONFIG_DIR = ".mcp-broker";
+/** Default config filename inside {@link DEFAULT_CONFIG_DIR}. */
+export const DEFAULT_CONFIG_FILENAME = "config.json";
+/** Legacy flat config filename at the cwd root (pre-`.mcp-broker/` layout). */
+export const LEGACY_CONFIG_FILENAME = "mcp-broker.config.json";
+/**
+ * Loads the broker config from a JSON file.
+ *
+ * Discovery order:
+ * 1. The `path` argument when provided (explicit override).
+ * 2. The `MCP_BROKER_CONFIG` env var.
+ * 3. `./.mcp-broker/config.json` relative to `process.cwd()`.
+ * 4. `./mcp-broker.config.json` relative to `process.cwd()` (legacy layout —
+ *    a deprecation warning is written to stderr).
+ *
+ * When no file is found, returns the built-in empty config with
+ * `baseDir = process.cwd()`. On invalid JSON, logs a warning to stderr and
+ * returns the same empty config — never throws.
+ *
+ * Paths inside the config file are intended to be resolved against
+ * {@link LoadedBrokerConfig.baseDir} by the consumer.
+ */
+export function loadBrokerConfig(path) {
+    const cwd = process.cwd();
+    const envPath = process.env["MCP_BROKER_CONFIG"];
+    let sourcePath = null;
+    if (path) {
+        sourcePath = resolve(cwd, path);
+    }
+    else if (envPath) {
+        sourcePath = resolve(cwd, envPath);
+    }
+    else {
+        const modern = resolve(cwd, DEFAULT_CONFIG_DIR, DEFAULT_CONFIG_FILENAME);
+        const legacy = resolve(cwd, LEGACY_CONFIG_FILENAME);
+        if (existsSync(modern)) {
+            sourcePath = modern;
+        }
+        else if (existsSync(legacy)) {
+            sourcePath = legacy;
+            process.stderr.write(`[mcp-broker] Using legacy config at ${legacy}. ` + `Move it to ${resolve(cwd, DEFAULT_CONFIG_DIR, DEFAULT_CONFIG_FILENAME)} ` + `to silence this warning.\n`);
+        }
+    }
+    if (!sourcePath || !existsSync(sourcePath)) {
+        return { config: {}, baseDir: cwd, sourcePath: null };
+    }
+    const baseDir = dirname(sourcePath);
+    try {
+        const raw = readFileSync(sourcePath, "utf-8");
+        const config = JSON.parse(raw);
+        return { config, baseDir, sourcePath };
+    }
+    catch (err) {
+        process.stderr.write(`[mcp-broker] Failed to parse config file at ${sourcePath}: ${err.message}\n`);
+        return { config: {}, baseDir: cwd, sourcePath: null };
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0F7C,oFAAoF;AACpF,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAEhD,iEAAiE;AACjE,MAAM,CAAC,MAAM,uBAAuB,GAAG,aAAa,CAAC;AAErD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE/D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAEjD,IAAI,UAAU,GAAkB,IAAI,CAAC;IAErC,IAAI,IAAI,EAAE,CAAC;QACP,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACpC,CAAC;SAAM,IAAI,OAAO,EAAE,CAAC;QACjB,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;SAAM,CAAC;QACJ,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,kBAAkB,EAAE,uBAAuB,CAAC,CAAC;QACzE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,sBAAsB,CAAC,CAAC;QACpD,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACrB,UAAU,GAAG,MAAM,CAAC;QACxB,CAAC;aAAM,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,UAAU,GAAG,MAAM,CAAC;YACpB,OAAO,CAAC,MAAM,CAAC,KAAK,CAChB,uCAAuC,MAAM,IAAI,GAAG,cAAc,OAAO,CAAC,GAAG,EAAE,kBAAkB,EAAE,uBAAuB,CAAC,GAAG,GAAG,4BAA4B,CAChK,CAAC;QACN,CAAC;IACL,CAAC;IAED,IAAI,CAAC,UAAU,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACzC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC1D,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAEpC,IAAI,CAAC;QACD,MAAM,GAAG,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAiB,CAAC;QAC/C,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IAC3C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,+CAA+C,UAAU,KAAM,GAAa,CAAC,OAAO,IAAI,CAAC,CAAC;QAC/G,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC1D,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { WsTunnel } from "./ws.tunnel.js";
+export { WsTunnelBuilder } from "./ws.tunnel.builder.js";
+export type { WsTunnelOptions, StaticMount } from "./ws.tunnel.js";
+export { StdioUpstream } from "./stdio.upstream.js";
+export type { StdioUpstreamConfig } from "./stdio.upstream.js";
+export { BrokerInfoBehavior, BrokerProvidersBehavior, startBrokerServer, BROKER_PROVIDER_NAME } from "./broker/index.js";
+export type { StartBrokerServerOptions } from "./broker/index.js";
+export { brokerGrammarKey, defaultBrokerLocaleResolver, defaultBrokerUserAgentResolver, iterAvailableBrokerGrammars, loadBrokerGrammar, resolveBrokerLocale, resolveBrokerUserAgent, } from "./broker/index.js";
+export type { BrokerContext, BrokerProviderInfo, BrokerProviderTransport, BrokerLocale, BrokerLocaleResolver, BrokerUserAgent, BrokerUserAgentResolver } from "./broker/index.js";
+export { VERSION, PACKAGE_NAME } from "./version.js";
+export { loadBrokerConfig, DEFAULT_CONFIG_FILENAME } from "./config.js";
+export type { BrokerConfig } from "./config.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+export { WsTunnel } from "./ws.tunnel.js";
+export { WsTunnelBuilder } from "./ws.tunnel.builder.js";
+export { StdioUpstream } from "./stdio.upstream.js";
+// Broker introspection — tier 1.
+export { BrokerInfoBehavior, BrokerProvidersBehavior, startBrokerServer, BROKER_PROVIDER_NAME } from "./broker/index.js";
+export { brokerGrammarKey, defaultBrokerLocaleResolver, defaultBrokerUserAgentResolver, iterAvailableBrokerGrammars, loadBrokerGrammar, resolveBrokerLocale, resolveBrokerUserAgent, } from "./broker/index.js";
+export { VERSION, PACKAGE_NAME } from "./version.js";
+// JSON config file used by `bin.ts` at startup. Exported so a programmatic
+// embedder can re-use the same loader against a custom path.
+export { loadBrokerConfig, DEFAULT_CONFIG_FILENAME } from "./config.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,iCAAiC;AACjC,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzH,OAAO,EACH,gBAAgB,EAChB,2BAA2B,EAC3B,8BAA8B,EAC9B,2BAA2B,EAC3B,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,GACzB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAErD,2EAA2E;AAC3E,6DAA6D;AAC7D,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}

package/dist/stdio.upstream.d.ts

@@ -0,0 +1,42 @@
+export interface StdioUpstreamConfig {
+    /** Logical name of this provider (matched against incoming WebSocket provider names). */
+    name: string;
+    /** Executable to spawn (e.g. `"node"`, `"python"`, an absolute path). */
+    command: string;
+    /** Arguments passed to the command. */
+    args?: string[];
+    /** Extra environment variables merged with `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Manages a stdio-based MCP server process.
+ * JSON-RPC messages are exchanged over the child process stdin/stdout using
+ * newline-delimited framing (matching the MCP SDK stdio transport).
+ *
+ * One instance per configured provider. The broker uses this to bridge
+ * WebSocket/SSE/HTTP clients to local MCP server processes.
+ */
+export declare class StdioUpstream {
+    readonly name: string;
+    private readonly _config;
+    private _proc;
+    private _buffer;
+    private _open;
+    private _stopped;
+    /** Called when a complete JSON-RPC line arrives from the process stdout. */
+    onMessage: ((data: string) => void) | null;
+    /** Called when the process has started and stdin is writable. */
+    onOpen: (() => void) | null;
+    /** Called when the process exits (cleanly or otherwise). */
+    onClose: (() => void) | null;
+    /** Called on spawn or runtime errors. */
+    onError: ((error: Error) => void) | null;
+    constructor(config: StdioUpstreamConfig);
+    get isOpen(): boolean;
+    /** Spawns the child process and wires up stdio listeners. */
+    connect(): void;
+    /** Sends a JSON-RPC message to the process stdin (appends newline). */
+    send(data: string): void;
+    /** Kills the child process and prevents further reconnection attempts. */
+    close(): void;
+}

package/dist/stdio.upstream.js

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+// ---------------------------------------------------------------------------
+// StdioUpstream
+// ---------------------------------------------------------------------------
+/**
+ * Manages a stdio-based MCP server process.
+ * JSON-RPC messages are exchanged over the child process stdin/stdout using
+ * newline-delimited framing (matching the MCP SDK stdio transport).
+ *
+ * One instance per configured provider. The broker uses this to bridge
+ * WebSocket/SSE/HTTP clients to local MCP server processes.
+ */
+export class StdioUpstream {
+    name;
+    _config;
+    _proc = null;
+    _buffer = "";
+    _open = false;
+    _stopped = false;
+    /** Called when a complete JSON-RPC line arrives from the process stdout. */
+    onMessage = null;
+    /** Called when the process has started and stdin is writable. */
+    onOpen = null;
+    /** Called when the process exits (cleanly or otherwise). */
+    onClose = null;
+    /** Called on spawn or runtime errors. */
+    onError = null;
+    constructor(config) {
+        this.name = config.name;
+        this._config = config;
+    }
+    get isOpen() {
+        return this._open;
+    }
+    /** Spawns the child process and wires up stdio listeners. */
+    connect() {
+        this._stopped = false;
+        const { command, args = [], env } = this._config;
+        this._proc = spawn(command, args, {
+            env: { ...process.env, ...env },
+            stdio: ["pipe", "pipe", "inherit"],
+        });
+        this._proc.on("error", (err) => {
+            this._open = false;
+            this.onError?.(new Error(`StdioUpstream "${this.name}": process error — ${err.message}`));
+        });
+        this._proc.on("spawn", () => {
+            this._open = true;
+            this.onOpen?.();
+        });
+        this._proc.stdout.on("data", (chunk) => {
+            this._buffer += chunk.toString("utf8");
+            let nl;
+            while ((nl = this._buffer.indexOf("\n")) !== -1) {
+                const line = this._buffer.slice(0, nl).trim();
+                this._buffer = this._buffer.slice(nl + 1);
+                if (line)
+                    this.onMessage?.(line);
+            }
+        });
+        this._proc.on("close", (code) => {
+            this._open = false;
+            this._proc = null;
+            this.onClose?.();
+            if (!this._stopped) {
+                this.onError?.(new Error(`StdioUpstream "${this.name}": process exited with code ${code ?? "null"}`));
+            }
+        });
+    }
+    /** Sends a JSON-RPC message to the process stdin (appends newline). */
+    send(data) {
+        if (!this._open || !this._proc?.stdin?.writable)
+            return;
+        this._proc.stdin.write(data + "\n", "utf8");
+    }
+    /** Kills the child process and prevents further reconnection attempts. */
+    close() {
+        this._stopped = true;
+        this._open = false;
+        this._proc?.stdin?.end();
+        this._proc?.kill();
+        this._proc = null;
+    }
+}
+//# sourceMappingURL=stdio.upstream.js.map

package/dist/stdio.upstream.js.map

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

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION: string;
+export declare const PACKAGE_NAME: string;

package/dist/version.js

@@ -0,0 +1,9 @@
+import { createRequire } from "module";
+// Resolves the package's own version from package.json without bundler help.
+// Works both for the compiled dist/version.js (one level below package.json)
+// and for tsc's source-level resolution from src/version.ts.
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+export const VERSION = pkg.version;
+export const PACKAGE_NAME = pkg.name;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEvC,6EAA6E;AAC7E,6EAA6E;AAC7E,6DAA6D;AAC7D,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAsC,CAAC;AAE5E,MAAM,CAAC,MAAM,OAAO,GAAW,GAAG,CAAC,OAAO,CAAC;AAC3C,MAAM,CAAC,MAAM,YAAY,GAAW,GAAG,CAAC,IAAI,CAAC"}

package/dist/ws.tunnel.builder.d.ts

@@ -0,0 +1,133 @@
+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 declare class WsTunnelBuilder {
+    private _port;
+    private _host;
+    private _providerPath;
+    private _providersPath;
+    private _clientPath;
+    private _ssePath;
+    private _messagesPath;
+    private _mcpPath;
+    private _samplesIndexPath;
+    private _staticMounts;
+    private _stdioUpstreams;
+    private _stdioClient;
+    private _tls;
+    private _brokerLocalGrammarsDir;
+    /** Sets the TCP port the broker listens on. */
+    withPort(port: number): this;
+    /**
+     * Sets the host/interface to bind to.
+     * @default "0.0.0.0" (all interfaces)
+     */
+    withHost(host: string): this;
+    /**
+     * Sets the URL path the MCP provider connects to.
+     * @default "/provider"
+     */
+    withProviderPath(path: string): this;
+    /**
+     * Sets the URL path for multiplexed provider connections.
+     * Multiple providers share a single WebSocket using the envelope protocol.
+     * @default "/providers"
+     */
+    withProvidersPath(path: string): this;
+    /**
+     * Sets the URL path MCP clients connect to.
+     * @default "/"
+     */
+    withClientPath(path: string): this;
+    /**
+     * Sets the URL path for the SSE stream (legacy Claude transport, GET).
+     * @default "/sse"
+     */
+    withSsePath(path: string): this;
+    /**
+     * Sets the URL path for JSON-RPC POST requests (legacy Claude transport).
+     * @default "/messages"
+     */
+    withMessagesPath(path: string): 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: string): 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: string): 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: string, dir: string): 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: string, command: string, args?: string[], env?: NodeJS.ProcessEnv): 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: string): 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: string, key: string): 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: string, keyPath: string): this;
+    /**
+     * 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: string): this;
+    /** Constructs and returns a configured {@link WsTunnel}. */
+    build(): WsTunnel;
+}