@cyanmycelium/mcp-broker 0.2.0 → 0.3.0

package/src/mcpb.unzip.ts

@@ -0,0 +1,103 @@
+/**
+ * Minimal ZIP extractor for `.mcpb` bundles, built on `node:zlib` only.
+ *
+ * A `.mcpb` bundle is an ordinary ZIP archive. The broker deliberately avoids
+ * the `@anthropic-ai/mcpb` package so it stays compatible with the format
+ * without being coupled to Anthropic's tooling — hence this small reader.
+ *
+ * Supports the two compression methods used in practice: stored (0) and
+ * deflate (8). ZIP64 archives are rejected with a clear error (`.mcpb` bundles
+ * are small and never need it). Any trailing bytes after the End Of Central
+ * Directory record — e.g. a native PKCS#7 signature block — are ignored, since
+ * extraction is driven entirely by the central directory.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { inflateRawSync } from "node:zlib";
+
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_HEADER_SIGNATURE = 0x02014b50;
+const LOCAL_HEADER_SIGNATURE = 0x04034b50;
+
+/** Locates the End Of Central Directory record by scanning backwards. */
+function findEocd(buf: Buffer): number {
+    // The EOCD is 22 bytes plus a comment of up to 65535 bytes.
+    const minPos = Math.max(0, buf.length - 22 - 0xffff);
+    for (let pos = buf.length - 22; pos >= minPos; pos--) {
+        if (buf.readUInt32LE(pos) === EOCD_SIGNATURE) return pos;
+    }
+    throw new Error("not a ZIP archive (no End Of Central Directory record found)");
+}
+
+/**
+ * Extracts every entry of the `.mcpb` archive at `mcpbPath` into `destDir`.
+ * `destDir` is created if missing. Entries whose resolved path would escape
+ * `destDir` (zip-slip) are rejected.
+ */
+export function unzipMcpb(mcpbPath: string, destDir: string): void {
+    const buf = readFileSync(mcpbPath);
+    const eocd = findEocd(buf);
+
+    const totalEntries = buf.readUInt16LE(eocd + 10);
+    const centralDirOffset = buf.readUInt32LE(eocd + 16);
+    if (centralDirOffset === 0xffffffff || totalEntries === 0xffff) {
+        throw new Error("ZIP64 archives are not supported");
+    }
+
+    const absDest = resolve(destDir);
+    mkdirSync(absDest, { recursive: true });
+
+    let pos = centralDirOffset;
+    for (let i = 0; i < totalEntries; i++) {
+        if (buf.readUInt32LE(pos) !== CENTRAL_HEADER_SIGNATURE) {
+            throw new Error(`corrupt ZIP: bad central directory header at offset ${pos}`);
+        }
+        const method = buf.readUInt16LE(pos + 10);
+        const compressedSize = buf.readUInt32LE(pos + 20);
+        const uncompressedSize = buf.readUInt32LE(pos + 24);
+        const nameLen = buf.readUInt16LE(pos + 28);
+        const extraLen = buf.readUInt16LE(pos + 30);
+        const commentLen = buf.readUInt16LE(pos + 32);
+        const localHeaderOffset = buf.readUInt32LE(pos + 42);
+        const name = buf.toString("utf8", pos + 46, pos + 46 + nameLen);
+        pos += 46 + nameLen + extraLen + commentLen;
+
+        if (compressedSize === 0xffffffff || uncompressedSize === 0xffffffff || localHeaderOffset === 0xffffffff) {
+            throw new Error("ZIP64 archives are not supported");
+        }
+
+        // Resolve the destination path and reject zip-slip escapes.
+        const target = resolve(absDest, name);
+        const rel = relative(absDest, target);
+        if (rel.startsWith("..") || isAbsolute(rel)) {
+            throw new Error(`unsafe ZIP entry path (zip-slip): ${name}`);
+        }
+
+        // Directory entry.
+        if (name.endsWith("/")) {
+            mkdirSync(target, { recursive: true });
+            continue;
+        }
+
+        // Parse the local header to locate the entry's data.
+        if (buf.readUInt32LE(localHeaderOffset) !== LOCAL_HEADER_SIGNATURE) {
+            throw new Error(`corrupt ZIP: bad local header for "${name}"`);
+        }
+        const localNameLen = buf.readUInt16LE(localHeaderOffset + 26);
+        const localExtraLen = buf.readUInt16LE(localHeaderOffset + 28);
+        const dataStart = localHeaderOffset + 30 + localNameLen + localExtraLen;
+        const compressed = buf.subarray(dataStart, dataStart + compressedSize);
+
+        let data: Buffer;
+        if (method === 0) {
+            data = compressed;
+        } else if (method === 8) {
+            data = inflateRawSync(compressed);
+        } else {
+            throw new Error(`unsupported ZIP compression method ${method} for "${name}"`);
+        }
+
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, data);
+    }
+}

package/src/remote.transports.ts

@@ -0,0 +1,316 @@
+/**
+ * Hand-rolled client transports for reaching a remote MCP server by URL.
+ *
+ * No `@modelcontextprotocol/sdk` dependency: the broker stays SDK-free, the
+ * official SDK is only used outside the broker (in the demo) to prove the
+ * broker is implementation-agnostic. Each transport is a thin frame relay —
+ * it does not interpret MCP, it pipes JSON-RPC strings both ways.
+ */
+import * as http from "node:http";
+import * as https from "node:https";
+import type { ClientRequest, IncomingMessage, RequestOptions } from "node:http";
+import { WebSocket } from "ws";
+
+/** Lifecycle + callbacks shared by every remote client transport. */
+export interface RemoteTransport {
+    onMessage: ((data: string) => void) | null;
+    onOpen: (() => void) | null;
+    onClose: (() => void) | null;
+    onError: ((error: Error) => void) | null;
+    connect(): void;
+    send(data: string): void;
+    close(): void;
+}
+
+/** The three supported remote transports. */
+export type RemoteTransportKind = "streamable-http" | "sse" | "websocket";
+
+/** Issues an http/https request, picking the module from the URL scheme. */
+function makeRequest(url: URL, options: RequestOptions, onResponse: (res: IncomingMessage) => void): ClientRequest {
+    return url.protocol === "https:" ? https.request(url, options, onResponse) : http.request(url, options, onResponse);
+}
+
+/**
+ * Incremental Server-Sent-Events decoder. Normalizes line endings, buffers
+ * across chunks, and emits one `(event, data)` pair per complete SSE block.
+ */
+class SseDecoder {
+    private _buf = "";
+
+    feed(chunk: string, emit: (event: string, data: string) => void): void {
+        this._buf += chunk.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+        let sep: number;
+        while ((sep = this._buf.indexOf("\n\n")) !== -1) {
+            const block = this._buf.slice(0, sep);
+            this._buf = this._buf.slice(sep + 2);
+            let event = "message";
+            const data: string[] = [];
+            for (const line of block.split("\n")) {
+                if (line.startsWith(":")) continue; // comment
+                const colon = line.indexOf(":");
+                const field = colon === -1 ? line : line.slice(0, colon);
+                let value = colon === -1 ? "" : line.slice(colon + 1);
+                if (value.startsWith(" ")) value = value.slice(1);
+                if (field === "event") event = value;
+                else if (field === "data") data.push(value);
+            }
+            if (data.length > 0) emit(event, data.join("\n"));
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// WebSocket
+// ---------------------------------------------------------------------------
+
+class WebSocketRemoteTransport implements RemoteTransport {
+    onMessage: ((data: string) => void) | null = null;
+    onOpen: (() => void) | null = null;
+    onClose: (() => void) | null = null;
+    onError: ((error: Error) => void) | null = null;
+
+    private _ws: WebSocket | null = null;
+
+    constructor(
+        private readonly _url: string,
+        private readonly _headers: Record<string, string>
+    ) {}
+
+    connect(): void {
+        const ws = new WebSocket(this._url, { headers: this._headers });
+        this._ws = ws;
+        ws.on("open", () => this.onOpen?.());
+        ws.on("message", (data: Buffer) => this.onMessage?.(data.toString("utf8")));
+        ws.on("close", () => this.onClose?.());
+        ws.on("error", (err: Error) => this.onError?.(err));
+    }
+
+    send(data: string): void {
+        if (this._ws && this._ws.readyState === WebSocket.OPEN) this._ws.send(data);
+    }
+
+    close(): void {
+        this._ws?.close();
+        this._ws = null;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Legacy MCP SSE (GET event stream + POST message endpoint)
+// ---------------------------------------------------------------------------
+
+class SseRemoteTransport implements RemoteTransport {
+    onMessage: ((data: string) => void) | null = null;
+    onOpen: (() => void) | null = null;
+    onClose: (() => void) | null = null;
+    onError: ((error: Error) => void) | null = null;
+
+    private readonly _decoder = new SseDecoder();
+    private _streamReq: ClientRequest | null = null;
+    private _postUrl: string | null = null;
+    private _closed = false;
+
+    constructor(
+        private readonly _url: string,
+        private readonly _headers: Record<string, string>
+    ) {}
+
+    connect(): void {
+        const req = makeRequest(new URL(this._url), { method: "GET", headers: { ...this._headers, Accept: "text/event-stream" } }, (res) => {
+            const status = res.statusCode ?? 0;
+            if (status >= 400) {
+                this.onError?.(new Error(`SSE GET responded ${status}`));
+                res.resume();
+                return;
+            }
+            res.setEncoding("utf8");
+            res.on("data", (chunk: string) => this._decoder.feed(chunk, (ev, data) => this._onEvent(ev, data)));
+            res.on("end", () => {
+                if (!this._closed) this.onClose?.();
+            });
+        });
+        this._streamReq = req;
+        req.on("error", (err: Error) => {
+            if (!this._closed) this.onError?.(err);
+        });
+        req.end();
+    }
+
+    private _onEvent(event: string, data: string): void {
+        if (event === "endpoint") {
+            this._postUrl = new URL(data, this._url).toString();
+            this.onOpen?.();
+        } else if (event === "message") {
+            this.onMessage?.(data);
+        }
+    }
+
+    send(data: string): void {
+        if (!this._postUrl) return;
+        const req = makeRequest(new URL(this._postUrl), { method: "POST", headers: { ...this._headers, "Content-Type": "application/json" } }, (res) => res.resume());
+        req.on("error", (err: Error) => this.onError?.(err));
+        req.end(data);
+    }
+
+    close(): void {
+        this._closed = true;
+        this._streamReq?.destroy();
+        this._streamReq = null;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Streamable HTTP (MCP 2025-03-26)
+// ---------------------------------------------------------------------------
+
+class StreamableHttpRemoteTransport implements RemoteTransport {
+    onMessage: ((data: string) => void) | null = null;
+    onOpen: (() => void) | null = null;
+    onClose: (() => void) | null = null;
+    onError: ((error: Error) => void) | null = null;
+
+    private _sessionId: string | null = null;
+    private _streamReq: ClientRequest | null = null;
+    private _closed = false;
+
+    constructor(
+        private readonly _url: string,
+        private readonly _headers: Record<string, string>
+    ) {}
+
+    connect(): void {
+        // Streamable HTTP is stateless — there is no connection to open. The
+        // transport is usable as soon as connect() is called; the session id
+        // is captured later from the first response that carries one.
+        this._closed = false;
+        this.onOpen?.();
+    }
+
+    send(data: string): void {
+        if (this._closed) return;
+        const headers: Record<string, string> = {
+            ...this._headers,
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+        };
+        if (this._sessionId) headers["Mcp-Session-Id"] = this._sessionId;
+        const req = makeRequest(new URL(this._url), { method: "POST", headers }, (res) => this._handleResponse(res));
+        req.on("error", (err: Error) => {
+            if (!this._closed) this.onError?.(err);
+        });
+        req.end(data);
+    }
+
+    private _handleResponse(res: IncomingMessage): void {
+        const sid = res.headers["mcp-session-id"];
+        if (typeof sid === "string" && sid.length > 0 && sid !== this._sessionId) {
+            this._sessionId = sid;
+            this._openServerStream();
+        }
+        const status = res.statusCode ?? 0;
+        if (status === 202) {
+            res.resume();
+            return;
+        }
+        if (status >= 400) {
+            this.onError?.(new Error(`Streamable HTTP POST responded ${status}`));
+            res.resume();
+            return;
+        }
+        res.setEncoding("utf8");
+        if (String(res.headers["content-type"] ?? "").includes("text/event-stream")) {
+            const decoder = new SseDecoder();
+            res.on("data", (chunk: string) =>
+                decoder.feed(chunk, (ev, data) => {
+                    if (ev === "message") this.onMessage?.(data);
+                })
+            );
+        } else {
+            let body = "";
+            res.on("data", (chunk: string) => {
+                body += chunk;
+            });
+            res.on("end", () => this._emitJsonBody(body));
+        }
+    }
+
+    private _emitJsonBody(body: string): void {
+        const trimmed = body.trim();
+        if (!trimmed) return;
+        try {
+            const parsed: unknown = JSON.parse(trimmed);
+            if (Array.isArray(parsed)) {
+                for (const message of parsed) this.onMessage?.(JSON.stringify(message));
+                return;
+            }
+        } catch {
+            /* not JSON — forward verbatim */
+        }
+        this.onMessage?.(trimmed);
+    }
+
+    /** Opens the optional standalone GET stream for server-initiated messages. */
+    private _openServerStream(): void {
+        if (this._closed || this._streamReq) return;
+        const headers: Record<string, string> = { ...this._headers, Accept: "text/event-stream" };
+        if (this._sessionId) headers["Mcp-Session-Id"] = this._sessionId;
+        const req = makeRequest(new URL(this._url), { method: "GET", headers }, (res) => {
+            if ((res.statusCode ?? 0) >= 400) {
+                // The server may not support the standalone GET stream (405). Fine.
+                res.resume();
+                this._streamReq = null;
+                return;
+            }
+            const decoder = new SseDecoder();
+            res.setEncoding("utf8");
+            res.on("data", (chunk: string) =>
+                decoder.feed(chunk, (ev, data) => {
+                    if (ev === "message") this.onMessage?.(data);
+                })
+            );
+            res.on("end", () => {
+                this._streamReq = null;
+            });
+        });
+        this._streamReq = req;
+        req.on("error", () => {
+            this._streamReq = null;
+        });
+        req.end();
+    }
+
+    close(): void {
+        this._closed = true;
+        this._streamReq?.destroy();
+        this._streamReq = null;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/** Builds the transport of the given kind. */
+export function createRemoteTransport(url: string, kind: RemoteTransportKind, headers: Record<string, string>): RemoteTransport {
+    switch (kind) {
+        case "websocket":
+            return new WebSocketRemoteTransport(url, headers);
+        case "sse":
+            return new SseRemoteTransport(url, headers);
+        case "streamable-http":
+            return new StreamableHttpRemoteTransport(url, headers);
+    }
+}
+
+/** Heuristic transport detection from the URL when none is configured. */
+export function detectTransport(url: string): RemoteTransportKind {
+    let parsed: URL;
+    try {
+        parsed = new URL(url);
+    } catch {
+        return "streamable-http";
+    }
+    if (parsed.protocol === "ws:" || parsed.protocol === "wss:") return "websocket";
+    if (parsed.pathname.replace(/\/+$/, "").endsWith("/sse")) return "sse";
+    return "streamable-http";
+}

package/src/remote.upstream.ts

@@ -0,0 +1,75 @@
+import type { Upstream } from "./upstream.js";
+import { createRemoteTransport, detectTransport, type RemoteTransport, type RemoteTransportKind } from "./remote.transports.js";
+
+export interface RemoteUpstreamConfig {
+    /** Provider slot name this upstream is bound to. */
+    name: string;
+    /** URL of the remote MCP server. */
+    url: string;
+    /** Transport to use. Auto-detected from the URL scheme/path when omitted. */
+    transport?: RemoteTransportKind;
+    /** Extra HTTP / WebSocket headers (e.g. an `Authorization` header). */
+    headers?: Record<string, string>;
+    /** When `true`, this upstream joins the `_all` aggregate slot once connected. */
+    aggregate?: boolean;
+}
+
+/**
+ * Bridges a remote MCP server (reachable by URL) into a broker provider slot.
+ *
+ * The broker-facing contract is identical to {@link StdioUpstream}: the broker
+ * muxes the slot's clients onto this single upstream. The only difference is
+ * the transport — Streamable HTTP / SSE / WebSocket instead of a child process.
+ */
+export class RemoteUpstream implements Upstream {
+    readonly name: string;
+
+    onMessage: ((data: string) => void) | null = null;
+    onOpen: (() => void) | null = null;
+    onClose: (() => void) | null = null;
+    onError: ((error: Error) => void) | null = null;
+
+    private readonly _config: RemoteUpstreamConfig;
+    private _transport: RemoteTransport | null = null;
+    private _open = false;
+
+    constructor(config: RemoteUpstreamConfig) {
+        this.name = config.name;
+        this._config = config;
+    }
+
+    get isOpen(): boolean {
+        return this._open;
+    }
+
+    connect(): void {
+        const kind = this._config.transport ?? detectTransport(this._config.url);
+        const transport = createRemoteTransport(this._config.url, kind, this._config.headers ?? {});
+        this._transport = transport;
+
+        transport.onOpen = (): void => {
+            this._open = true;
+            this.onOpen?.();
+        };
+        transport.onMessage = (data: string): void => this.onMessage?.(data);
+        transport.onClose = (): void => {
+            this._open = false;
+            this.onClose?.();
+        };
+        transport.onError = (err: Error): void => {
+            this.onError?.(new Error(`RemoteUpstream "${this.name}": ${err.message}`));
+        };
+
+        transport.connect();
+    }
+
+    send(data: string): void {
+        this._transport?.send(data);
+    }
+
+    close(): void {
+        this._open = false;
+        this._transport?.close();
+        this._transport = null;
+    }
+}

package/src/stdio.upstream.ts

@@ -1,4 +1,5 @@
 import { spawn, ChildProcess } from "node:child_process";
+import type { Upstream } from "./upstream.js";
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -13,6 +14,8 @@ export interface StdioUpstreamConfig {
     args?: string[];
     /** Extra environment variables merged with `process.env`. */
     env?: NodeJS.ProcessEnv;
+    /** When `true`, this upstream joins the `_all` aggregate slot once connected. */
+    aggregate?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -27,7 +30,7 @@ export interface StdioUpstreamConfig {
  * One instance per configured provider. The broker uses this to bridge
  * WebSocket/SSE/HTTP clients to local MCP server processes.
  */
-export class StdioUpstream {
+export class StdioUpstream implements Upstream {
     readonly name: string;
 
     private readonly _config: StdioUpstreamConfig;

package/src/upstream.ts

@@ -0,0 +1,33 @@
+/**
+ * Common contract for an upstream MCP server bound to a provider slot.
+ *
+ * The broker treats every upstream the same way: it muxes the slot's clients
+ * onto the single upstream connection, regardless of the underlying transport.
+ *
+ * Implementations:
+ * - `StdioUpstream`  — a local child process (newline-delimited JSON-RPC over stdio).
+ * - `RemoteUpstream` — a remote MCP server reached by URL (Streamable HTTP / SSE / WebSocket).
+ *
+ * `StdioUpstream` is reused as-is by the future `.mcpb` bundle loader: a bundle
+ * is a local server whose `mcp_config` maps directly onto a stdio upstream.
+ */
+export interface Upstream {
+    /** Provider slot name this upstream is bound to. */
+    readonly name: string;
+    /** Whether the upstream connection is currently usable. */
+    readonly isOpen: boolean;
+    /** Receives one complete JSON-RPC message from the upstream server. */
+    onMessage: ((data: string) => void) | null;
+    /** Fires once the upstream connection is established and ready to send. */
+    onOpen: (() => void) | null;
+    /** Fires when the upstream connection closes. */
+    onClose: (() => void) | null;
+    /** Fires on a connection or runtime error. */
+    onError: ((error: Error) => void) | null;
+    /** Opens the upstream connection. */
+    connect(): void;
+    /** Sends one JSON-RPC message to the upstream server. */
+    send(data: string): void;
+    /** Closes the upstream connection. */
+    close(): void;
+}

package/src/ws.tunnel.builder.ts

@@ -1,6 +1,7 @@
 import * as fs from "fs";
 import { WsTunnel, type WsTunnelOptions, type StaticMount } from "./ws.tunnel.js";
 import type { StdioUpstreamConfig } from "./stdio.upstream.js";
+import type { RemoteUpstreamConfig } from "./remote.upstream.js";
 
 /**
  * Fluent builder that constructs a configured {@link WsTunnel}.
@@ -31,6 +32,7 @@ export class WsTunnelBuilder {
     private _samplesIndexPath = "/__samples_index__";
     private _staticMounts: StaticMount[] = [];
     private _stdioUpstreams: StdioUpstreamConfig[] = [];
+    private _remoteUpstreams: RemoteUpstreamConfig[] = [];
     private _stdioClient: { providerName: string } | undefined = undefined;
     private _tls: { cert: string; key: string } | undefined = undefined;
     private _brokerLocalGrammarsDir: string | undefined = undefined;
@@ -129,19 +131,26 @@ export class WsTunnelBuilder {
     }
 
     /**
-     * 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`).
+     * Registers a stdio upstream provider. The broker spawns the configured
+     * command and bridges its stdin/stdout as an MCP transport. Clients reach
+     * it using `config.name` directly (e.g. `/<name>/mcp`).
      *
      * Can be called multiple times to register multiple providers.
+     */
+    withStdioUpstream(config: StdioUpstreamConfig): this {
+        this._stdioUpstreams.push(config);
+        return this;
+    }
+
+    /**
+     * Registers a remote MCP server reached by URL. The broker connects out to
+     * it and exposes it as a provider slot named `config.name`, bridging the
+     * Streamable HTTP / SSE / WebSocket transport for the slot's clients.
      *
-     * @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`.
+     * Can be called multiple times to register multiple servers.
      */
-    withStdioUpstream(name: string, command: string, args?: string[], env?: NodeJS.ProcessEnv): this {
-        this._stdioUpstreams.push({ name, command, args, env });
+    withRemoteUpstream(config: RemoteUpstreamConfig): this {
+        this._remoteUpstreams.push(config);
         return this;
     }
 
@@ -205,6 +214,7 @@ export class WsTunnelBuilder {
             samplesIndexPath: this._samplesIndexPath,
             staticMounts: this._staticMounts.length > 0 ? [...this._staticMounts] : undefined,
             stdioUpstreams: this._stdioUpstreams.length > 0 ? [...this._stdioUpstreams] : undefined,
+            remoteUpstreams: this._remoteUpstreams.length > 0 ? [...this._remoteUpstreams] : undefined,
             stdioClient: this._stdioClient,
             tls: this._tls,
             brokerLocalGrammarsDir: this._brokerLocalGrammarsDir,