@cyanmycelium/mcp-broker 0.4.0 → 1.2.0

package/web/demos/provider-tunnel/css/app.css

@@ -0,0 +1,384 @@
+/* =============================================================
+   Provider Tunnel Demo, app-specific overrides
+   Base: ../../css/styles.css
+   ============================================================= */
+
+/* Extra tokens not in styles.css */
+:root {
+    --amber: #ffb86b;
+    --red: #f78c6c;
+    --bg-code: #0a0e13;
+}
+
+/* App shell: full-viewport, no scroll */
+html, body {
+    height: 100dvh;
+}
+
+body {
+    font-size: 15px;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+}
+
+code {
+    font-family: var(--font-mono);
+}
+
+/* Topbar: direct-flex layout (styles.css flexes on .topbar-inner) */
+.topbar {
+    flex-shrink: 0;
+    height: 56px;
+    display: flex;
+    align-items: center;
+    gap: 16px;
+    padding: 0 22px;
+}
+
+/* Brand: override link color and suppress hover underline */
+.brand {
+    color: var(--fg);
+    text-decoration: none;
+}
+.brand:hover {
+    text-decoration: none;
+}
+
+/* Brand mark: 26px (styles.css uses 24px) */
+.brand-mark {
+    width: 26px;
+    height: 26px;
+}
+
+.topbar-tag {
+    font-family: var(--font-mono);
+    font-size: 11px;
+    letter-spacing: 0.14em;
+    text-transform: uppercase;
+    color: var(--blue);
+    padding: 3px 9px;
+    border: 1px solid var(--rule-strong);
+    border-radius: 4px;
+}
+
+.topbar-spacer {
+    flex: 1;
+}
+
+.topbar-link {
+    font-size: 13px;
+    color: var(--fg-muted);
+    text-decoration: none;
+}
+.topbar-link:hover {
+    color: var(--fg);
+    text-decoration: none;
+}
+
+/* Status badge (replaces docs .badge definition) */
+.badge {
+    font-family: var(--font-mono);
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    padding: 4px 11px;
+    border-radius: 99px;
+    border: 1px solid var(--rule-strong);
+    height: auto;
+    background: none;
+    color: var(--fg-muted);
+}
+.badge.disconnected {
+    color: var(--red);
+    background: rgba(247, 140, 108, 0.08);
+    border-color: rgba(247, 140, 108, 0.3);
+}
+.badge.connecting {
+    color: var(--amber);
+    background: rgba(255, 184, 107, 0.08);
+    border-color: rgba(255, 184, 107, 0.3);
+}
+.badge.connected {
+    color: var(--lime);
+    background: rgba(184, 224, 96, 0.08);
+    border-color: rgba(184, 224, 96, 0.32);
+}
+
+/* Buttons: 38px (styles.css uses 44px) */
+.btn {
+    height: 38px;
+    padding: 0 16px;
+    gap: 8px;
+}
+.btn:disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+}
+.btn-primary:not(:disabled):hover {
+    background: var(--blue-bright);
+    border-color: var(--blue-bright);
+    color: var(--blue-deep);
+}
+.btn-secondary:not(:disabled):hover {
+    border-color: var(--fg-muted);
+    background: var(--bg-elev-1);
+}
+
+/* Layout */
+.layout {
+    flex: 1;
+    display: flex;
+    overflow: hidden;
+}
+.left-panel {
+    width: 360px;
+    flex-shrink: 0;
+    border-right: 1px solid var(--rule);
+}
+.right-column {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+}
+.panel {
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+}
+.panel-title {
+    flex-shrink: 0;
+    font-family: var(--font-mono);
+    font-size: 11px;
+    font-weight: 500;
+    letter-spacing: 0.14em;
+    text-transform: uppercase;
+    color: var(--blue);
+    padding: 11px 18px;
+    background: var(--bg-elev-1);
+    border-bottom: 1px solid var(--rule);
+}
+.panel-body {
+    flex: 1;
+    overflow-y: auto;
+    padding: 18px;
+}
+.catalog-panel {
+    flex: 1;
+    border-bottom: 1px solid var(--rule);
+}
+.console-panel {
+    height: 240px;
+    flex-shrink: 0;
+}
+
+/* Form controls */
+.field {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+    margin-bottom: 16px;
+}
+.field label {
+    font-size: 12px;
+    color: var(--fg-dim);
+}
+input[type="text"] {
+    width: 100%;
+    background: var(--bg-code);
+    border: 1px solid var(--rule-strong);
+    border-radius: 6px;
+    color: var(--fg);
+    font-family: var(--font-mono);
+    font-size: 13px;
+    padding: 8px 11px;
+}
+input[type="text"]:focus {
+    outline: none;
+    border-color: var(--blue-dim);
+}
+input[readonly] {
+    color: var(--blue-bright);
+    cursor: text;
+}
+
+.btn-row {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 9px;
+    margin-top: 4px;
+}
+
+/* Aggregate opt-in checkbox + hover tooltip */
+.check {
+    position: relative;
+    margin-left: auto;
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    font-size: 12px;
+    color: var(--fg-muted);
+    cursor: pointer;
+    user-select: none;
+}
+.check input {
+    margin: 0;
+    accent-color: var(--blue);
+    cursor: pointer;
+}
+.check input:disabled {
+    cursor: not-allowed;
+}
+.check-tip {
+    position: absolute;
+    top: calc(100% + 8px);
+    right: 0;
+    width: 220px;
+    padding: 9px 11px;
+    background: var(--bg-elev-2);
+    border: 1px solid var(--rule-strong);
+    border-radius: 6px;
+    font-size: 12px;
+    line-height: 1.5;
+    color: var(--fg-muted);
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+    opacity: 0;
+    visibility: hidden;
+    transition: opacity 120ms;
+    z-index: 20;
+    pointer-events: none;
+}
+.check:hover .check-tip,
+.check:focus-within .check-tip {
+    opacity: 1;
+    visibility: visible;
+}
+.check-tip code {
+    font-family: var(--font-mono);
+    font-size: 0.9em;
+    color: var(--blue);
+}
+
+/* Endpoints */
+.endpoints {
+    margin-top: 20px;
+    padding-top: 16px;
+    border-top: 1px solid var(--rule);
+}
+.endpoints .field {
+    margin-bottom: 12px;
+}
+.endpoints .field label {
+    font-family: var(--font-mono);
+    font-size: 10px;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    color: var(--blue);
+}
+.endpoints .field:last-child {
+    margin-bottom: 0;
+}
+
+.hint {
+    margin-top: 18px;
+    font-size: 13px;
+    line-height: 1.6;
+    color: var(--fg-dim);
+}
+.hint code {
+    font-size: 0.86em;
+    color: var(--blue);
+    background: var(--bg-inline);
+    border: 1px solid var(--rule);
+    padding: 1px 5px;
+    border-radius: 4px;
+}
+.hint strong {
+    color: var(--fg-muted);
+    font-weight: 600;
+}
+
+/* Catalog */
+.cat-group {
+    margin-bottom: 20px;
+}
+.cat-group:last-child {
+    margin-bottom: 0;
+}
+.cat-group-title {
+    font-family: var(--font-mono);
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: var(--fg-dim);
+    margin-bottom: 10px;
+}
+.cat-item {
+    background: var(--bg-elev-1);
+    border: 1px solid var(--rule);
+    border-radius: 8px;
+    padding: 10px 13px;
+    margin-bottom: 9px;
+    transition: border-color 140ms, background 140ms;
+}
+.cat-item:hover {
+    border-color: var(--blue-dim);
+    background: var(--bg-elev-2);
+}
+.cat-item-name {
+    font-family: var(--font-mono);
+    font-size: 13px;
+    font-weight: 600;
+    color: var(--blue);
+}
+.cat-item-name.cat-item-uri {
+    color: var(--lime);
+}
+.cat-item-desc {
+    font-size: 13px;
+    color: var(--fg-muted);
+    margin-top: 3px;
+    line-height: 1.5;
+}
+.cat-item-params {
+    font-family: var(--font-mono);
+    font-size: 12px;
+    color: var(--fg-dim);
+    margin-top: 5px;
+}
+.cat-item-params .pname {
+    color: var(--amber);
+}
+.cat-item-params .preq {
+    color: var(--red);
+}
+
+/* Console */
+#console-output {
+    font-family: var(--font-mono);
+    font-size: 12.5px;
+    line-height: 1.65;
+    background: var(--bg-code);
+}
+.log-line {
+    display: flex;
+    gap: 10px;
+}
+.log-line .ts {
+    color: var(--fg-dim);
+    user-select: none;
+    flex-shrink: 0;
+}
+.log-line .msg {
+    min-width: 0;
+    overflow-wrap: anywhere;
+}
+.log-line.info .msg { color: var(--fg); }
+.log-line.ok   .msg { color: var(--lime); }
+.log-line.warn .msg { color: var(--amber); }
+.log-line.error .msg { color: var(--red); }
+.log-line.dim  .msg { color: var(--fg-dim); }

package/web/demos/provider-tunnel/index.html

@@ -0,0 +1,99 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>MCP Broker, Provider Tunnel Demo</title>
+        <link rel="icon" type="image/png" href="../../assets/logo.png" />
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+        <link
+            rel="stylesheet"
+            href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap"
+        />
+        <link rel="stylesheet" href="../../css/styles.css" />
+        <link rel="stylesheet" href="css/app.css" />
+    </head>
+    <body>
+        <!-- Topbar -->
+        <header class="topbar">
+            <a class="brand" href="https://github.com/pandaGaume/mcp-broker" target="_blank" rel="noopener">
+                <img class="brand-mark" src="../../assets/logo.png" alt="" aria-hidden="true" />
+                <span>@cyanmycelium/mcp-broker</span>
+            </a>
+            <span class="topbar-tag">Provider Tunnel Demo</span>
+            <span class="topbar-spacer"></span>
+            <a class="topbar-link" href="https://github.com/pandaGaume/mcp-broker" target="_blank" rel="noopener">
+                GitHub →
+            </a>
+            <span id="status-badge" class="badge disconnected">Disconnected</span>
+        </header>
+
+        <div class="layout">
+            <!-- Left: tunnel connection -->
+            <aside class="left-panel panel">
+                <div class="panel-title">Tunnel connection</div>
+                <div class="panel-body">
+                    <div class="field">
+                        <label for="ws-url">Broker provider base URL</label>
+                        <input type="text" id="ws-url" />
+                    </div>
+                    <div class="field">
+                        <label for="server-name">Provider slot name</label>
+                        <input type="text" id="server-name" value="demo-toolbox" />
+                    </div>
+                    <div class="btn-row">
+                        <button id="start-btn" class="btn btn-primary">Connect</button>
+                        <button id="stop-btn" class="btn btn-secondary" disabled>Disconnect</button>
+                        <label class="check">
+                            <input type="checkbox" id="aggregate-check" />
+                            <span>aggregate</span>
+                            <span class="check-tip" role="tooltip">
+                                Joins the broker's <code>_all</code> slot: this server's tools and prompts are
+                                merged into one aggregate MCP endpoint alongside every other aggregated
+                                provider, so a single client reaches them all.
+                            </span>
+                        </label>
+                    </div>
+
+                    <div class="endpoints" id="endpoints" hidden>
+                        <div class="field">
+                            <label for="ep-http">Streamable HTTP (MCP Inspector)</label>
+                            <input type="text" id="ep-http" readonly />
+                        </div>
+                        <div class="field">
+                            <label for="ep-sse">Legacy SSE</label>
+                            <input type="text" id="ep-sse" readonly />
+                        </div>
+                        <div class="field">
+                            <label for="ep-ws">Raw WebSocket</label>
+                            <input type="text" id="ep-ws" readonly />
+                        </div>
+                    </div>
+
+                    <p class="hint">
+                        This page hosts an MCP <strong>server</strong> built with the official
+                        <code>@modelcontextprotocol/sdk</code>. Connecting opens an outbound WebSocket to the broker's
+                        <code>/provider/&lt;name&gt;</code> endpoint: the broker then relays any MCP client that
+                        targets the slot above. The broker-specific code is isolated in
+                        <code>js/lib/broker-tunnel.js</code>.
+                    </p>
+                </div>
+            </aside>
+
+            <!-- Right: catalog + console -->
+            <div class="right-column">
+                <section class="panel catalog-panel">
+                    <div class="panel-title">Server catalog, what this MCP server exposes</div>
+                    <div class="panel-body" id="catalog"></div>
+                </section>
+                <section class="panel console-panel">
+                    <div class="panel-title">Console</div>
+                    <div class="panel-body" id="console-output"></div>
+                </section>
+            </div>
+        </div>
+
+        <script type="module" src="js/app.js"></script>
+    </body>
+</html>

package/web/demos/provider-tunnel/js/app.js

@@ -0,0 +1,226 @@
+/**
+ * app.js, UI wiring for the provider tunnel demo.
+ *
+ * Owns the DOM: console log, status badge, catalog panel, and the connect /
+ * disconnect lifecycle. The two pieces of real logic are imported:
+ *
+ * - js/lib/broker-tunnel.js, broker connection (reusable, zero-dependency,
+ *   shared across demos, lives at the web root).
+ * - ./toolbox-server.js    : the demo MCP server (plain MCP, broker-agnostic).
+ */
+import { BrokerTunnelTransport, describeTunnelClose } from "../../../js/lib/broker-tunnel.js";
+import { TOOLS, RESOURCES, createToolboxServer } from "./toolbox-server.js";
+
+// =====================================================================
+// Console + status helpers
+// =====================================================================
+const consoleEl = document.getElementById("console-output");
+
+function log(msg, level = "info") {
+    const ts = new Date().toLocaleTimeString("en", {
+        hour12: false,
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    });
+    const div = document.createElement("div");
+    div.className = `log-line ${level}`;
+    div.innerHTML = `<span class="ts">${ts}</span><span class="msg"></span>`;
+    div.querySelector(".msg").textContent = msg;
+    consoleEl.appendChild(div);
+    consoleEl.scrollTop = consoleEl.scrollHeight;
+}
+
+const badgeEl = document.getElementById("status-badge");
+let state = "disconnected";
+
+function setStatus(next) {
+    state = next;
+    badgeEl.className = `badge ${next}`;
+    badgeEl.textContent =
+        { disconnected: "Disconnected", connecting: "Connecting…", connected: "Connected" }[next] ?? next;
+}
+
+// =====================================================================
+// Catalog panel, rendered from the toolbox server's exported definitions.
+// =====================================================================
+function renderCatalog() {
+    const el = document.getElementById("catalog");
+    el.innerHTML = "";
+
+    const toolGroup = document.createElement("div");
+    toolGroup.className = "cat-group";
+    toolGroup.innerHTML = `<div class="cat-group-title">Tools (${TOOLS.length})</div>`;
+    for (const tool of TOOLS) {
+        const item = document.createElement("div");
+        item.className = "cat-item";
+        const props = tool.inputSchema.properties ?? {};
+        const required = tool.inputSchema.required ?? [];
+        const params = Object.entries(props)
+            .map(([pn, pd]) => {
+                const req = required.includes(pn);
+                return `<span class="pname">${pn}</span>${req ? '<span class="preq">*</span>' : ""}: ${pd.type}`;
+            })
+            .join(", ");
+        item.innerHTML =
+            `<div class="cat-item-name">${tool.name}</div>` +
+            `<div class="cat-item-desc"></div>` +
+            (params ? `<div class="cat-item-params">(${params})</div>` : "");
+        item.querySelector(".cat-item-desc").textContent = tool.description;
+        toolGroup.appendChild(item);
+    }
+    el.appendChild(toolGroup);
+
+    const resGroup = document.createElement("div");
+    resGroup.className = "cat-group";
+    resGroup.innerHTML = `<div class="cat-group-title">Resources (${RESOURCES.length})</div>`;
+    for (const res of RESOURCES) {
+        const item = document.createElement("div");
+        item.className = "cat-item";
+        item.innerHTML = `<div class="cat-item-name cat-item-uri"></div>` + `<div class="cat-item-desc"></div>`;
+        item.querySelector(".cat-item-uri").textContent = res.uri;
+        item.querySelector(".cat-item-desc").textContent = res.description;
+        resGroup.appendChild(item);
+    }
+    el.appendChild(resGroup);
+}
+
+// =====================================================================
+// Lifecycle
+// =====================================================================
+let server = null;
+let transport = null;
+let intentionalClose = false;
+let connectGraceTimer = null;
+let tunnelWasOpen = false;
+
+const startBtn = document.getElementById("start-btn");
+const stopBtn = document.getElementById("stop-btn");
+const wsUrlInput = document.getElementById("ws-url");
+const nameInput = document.getElementById("server-name");
+const endpointsEl = document.getElementById("endpoints");
+const aggregateCheck = document.getElementById("aggregate-check");
+
+// Derive the provider WebSocket base from the page origin: ws:// over HTTP,
+// wss:// over HTTPS, avoids mixed-content errors under TLS.
+(function deriveProviderUrl() {
+    const scheme = window.location.protocol === "https:" ? "wss:" : "ws:";
+    wsUrlInput.value = `${scheme}//${window.location.host}/provider`;
+})();
+
+function teardown() {
+    server = null;
+    transport = null;
+    tunnelWasOpen = false;
+    setStatus("disconnected");
+    startBtn.disabled = false;
+    stopBtn.disabled = true;
+    aggregateCheck.disabled = false;
+    endpointsEl.hidden = true;
+}
+
+function showEndpoints(slotName) {
+    const httpScheme = window.location.protocol === "https:" ? "https:" : "http:";
+    const wsScheme = window.location.protocol === "https:" ? "wss:" : "ws:";
+    const host = window.location.host;
+    const enc = encodeURIComponent(slotName);
+    document.getElementById("ep-http").value = `${httpScheme}//${host}/${enc}/mcp`;
+    document.getElementById("ep-sse").value = `${httpScheme}//${host}/${enc}/sse`;
+    document.getElementById("ep-ws").value = `${wsScheme}//${host}/${enc}`;
+    endpointsEl.hidden = false;
+}
+
+// The WS "handshake check": classify how the tunnel socket closed.
+// describeTunnelClose (lib/broker-tunnel.js) maps the close code to a
+// diagnosis, broker rejection (1008), unreachable, or dropped.
+function handleTunnelClose(code, reason) {
+    // A pending success banner must not fire once the slot is rejected.
+    if (connectGraceTimer) {
+        clearTimeout(connectGraceTimer);
+        connectGraceTimer = null;
+    }
+    if (intentionalClose) {
+        intentionalClose = false;
+        teardown();
+        return;
+    }
+    const { level, message } = describeTunnelClose(code, reason, tunnelWasOpen);
+    log(message, level);
+    teardown();
+}
+
+startBtn.addEventListener("click", async () => {
+    const base = wsUrlInput.value.trim().replace(/\/+$/, "");
+    const slotName = nameInput.value.trim() || "demo-toolbox";
+    if (!base) {
+        log("Enter the broker provider base URL first.", "error");
+        return;
+    }
+    const url = `${base}/${encodeURIComponent(slotName)}`;
+
+    const aggregate = aggregateCheck.checked;
+
+    setStatus("connecting");
+    startBtn.disabled = true;
+    aggregateCheck.disabled = true;
+    intentionalClose = false;
+    tunnelWasOpen = false;
+    log(`Opening tunnel WebSocket to ${url} …`, "dim");
+    if (aggregate) {
+        log("Aggregate mode on: this server will join the broker's _all slot.", "dim");
+    }
+
+    transport = new BrokerTunnelTransport(url, { aggregate });
+    transport.onTunnelOpen = () => {
+        tunnelWasOpen = true;
+    };
+    transport.onTunnelClose = handleTunnelClose;
+    transport.onTunnelError = (err) => log(`Transport error: ${err.message}`, "error");
+
+    server = createToolboxServer({ name: slotName, onActivity: log });
+
+    try {
+        // connect() awaits transport.start(), resolves when the broker accepts
+        // the WebSocket upgrade. The MCP initialize handshake happens later,
+        // when a real client targets the slot.
+        await server.connect(transport);
+    } catch (err) {
+        log(`Failed to open tunnel: ${err.message}`, "error");
+        // handleTunnelClose may already have run; teardown is idempotent.
+        teardown();
+        return;
+    }
+
+    // The broker accepts the WebSocket upgrade first, then may still reject the
+    // slot at the application layer with a 1008 close (name already taken, or
+    // reserved) within a few milliseconds. Hold a short grace window before
+    // declaring success, handleTunnelClose cancels this timer if a rejection
+    // lands first.
+    connectGraceTimer = setTimeout(() => {
+        connectGraceTimer = null;
+        setStatus("connected");
+        stopBtn.disabled = false;
+        showEndpoints(slotName);
+        log(`Tunnel open. Provider slot "${slotName}" is now routable through the broker.`, "ok");
+        log("Point an MCP client (e.g. MCP Inspector) at the Streamable HTTP URL.", "dim");
+    }, 250);
+});
+
+stopBtn.addEventListener("click", async () => {
+    if (!server) return;
+    intentionalClose = true;
+    stopBtn.disabled = true;
+    try {
+        await server.close(); // closes the transport, which closes the WS
+        log("Tunnel closed. Provider slot released.", "warn");
+    } catch (err) {
+        log(`Error while closing: ${err.message}`, "error");
+    }
+    teardown();
+});
+
+// =====================================================================
+// Boot
+// =====================================================================
+renderCatalog();
+log("Ready. Press Connect to tunnel this MCP server to the broker.", "dim");