@cyanmycelium/mcp-broker 0.4.0 → 1.2.0

package/web/demos/broker-explorer/index.html

@@ -0,0 +1,94 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>MCP Broker, Broker Explorer 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">Broker Explorer Demo</span>
+            <span class="topbar-spacer"></span>
+            <a class="topbar-link" href="../../broker-self-mcp.html">Explainer →</a>
+            <span id="status-badge" class="badge disconnected">Disconnected</span>
+        </header>
+
+        <div class="layout">
+            <!-- Left: client connection -->
+            <aside class="left-panel panel">
+                <div class="panel-title">Client connection</div>
+                <div class="panel-body">
+                    <div class="field">
+                        <label for="ws-url">Broker client base URL</label>
+                        <input type="text" id="ws-url" />
+                    </div>
+                    <div class="field">
+                        <label for="slot-name">Slot to explore</label>
+                        <input type="text" id="slot-name" value="_broker" />
+                    </div>
+                    <div class="slot-presets">
+                        <button type="button" class="preset" data-slot="_broker">_broker</button>
+                        <button type="button" class="preset" data-slot="_all">_all</button>
+                    </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>
+                    </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 is an MCP <strong>client</strong>. Connecting opens a raw WebSocket to the
+                        broker's <code>/&lt;slot&gt;</code> endpoint, runs the MCP <code>initialize</code>
+                        handshake and lists the slot's tools. Try <code>_broker</code> for the broker's own
+                        introspection tools, or <code>_all</code> for the aggregate of every provider. The MCP
+                        client itself is isolated in <code>js/mcp-ws-client.js</code>.
+                    </p>
+                </div>
+            </aside>
+
+            <!-- Right: catalog + console -->
+            <div class="right-column">
+                <section class="panel catalog-panel">
+                    <div class="panel-title">Live catalog, call a tool on the connected slot</div>
+                    <div class="panel-body" id="catalog">
+                        <p class="empty-note">Not connected. Press Connect to list the slot's tools.</p>
+                    </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/broker-explorer/js/app.js

@@ -0,0 +1,271 @@
+/**
+ * app.js, UI wiring for the broker explorer demo.
+ *
+ * Owns the DOM: console log, status badge, live catalog, and the connect /
+ * disconnect lifecycle. The MCP-over-WebSocket client is imported from
+ * ./mcp-ws-client.js (standard MCP, nothing broker-specific).
+ */
+import { McpWebSocketClient } from "./mcp-ws-client.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");
+
+function setStatus(next) {
+    badgeEl.className = `badge ${next}`;
+    badgeEl.textContent = { disconnected: "Disconnected", connecting: "Connecting…", connected: "Connected" }[next] ?? next;
+}
+
+// =====================================================================
+// Catalog panel, rendered live from the slot's tools/list response.
+// =====================================================================
+const catalogEl = document.getElementById("catalog");
+
+function clearCatalog(note) {
+    catalogEl.innerHTML = "";
+    if (note) {
+        const p = document.createElement("p");
+        p.className = "empty-note";
+        p.textContent = note;
+        catalogEl.appendChild(p);
+    }
+}
+
+function renderCatalog(tools) {
+    catalogEl.innerHTML = "";
+    if (tools.length === 0) {
+        clearCatalog("This slot exposes no tools.");
+        return;
+    }
+
+    const group = document.createElement("div");
+    group.className = "cat-group";
+    group.innerHTML = `<div class="cat-group-title">Tools (${tools.length})</div>`;
+
+    for (const tool of tools) {
+        const schema = tool.inputSchema ?? {};
+        const props = schema.properties ?? {};
+        const required = schema.required ?? [];
+        const paramText = Object.entries(props)
+            .map(([pn, pd]) => {
+                const req = required.includes(pn);
+                const type = (pd && pd.type) || "any";
+                return `<span class="pname">${pn}</span>${req ? '<span class="preq">*</span>' : ""}: ${type}`;
+            })
+            .join(", ");
+
+        const item = document.createElement("div");
+        item.className = "cat-item";
+        item.innerHTML =
+            `<div class="cat-item-name"></div>` +
+            `<div class="cat-item-desc"></div>` +
+            (paramText ? `<div class="cat-item-params">(${paramText})</div>` : "") +
+            `<div class="cat-item-call">` +
+            `<input type="text" class="args-input" spellcheck="false" />` +
+            `<button class="call-btn">Call</button>` +
+            `</div>`;
+        item.querySelector(".cat-item-name").textContent = tool.name;
+        item.querySelector(".cat-item-desc").textContent = tool.description ?? "";
+
+        // Seed the args field with a skeleton object of the declared properties.
+        const skeleton = {};
+        for (const pn of Object.keys(props)) skeleton[pn] = "";
+        const argsInput = item.querySelector(".args-input");
+        argsInput.value = JSON.stringify(skeleton);
+
+        const callBtn = item.querySelector(".call-btn");
+        callBtn.addEventListener("click", () => void callTool(tool.name, argsInput, callBtn, item));
+
+        group.appendChild(item);
+    }
+    catalogEl.appendChild(group);
+}
+
+/**
+ * Renders an MCP `tools/call` result into readable text.
+ *
+ * Prefers `structuredContent` (MCP 2025-06-18) when the tool provides it.
+ * Otherwise falls back to the `content` blocks: a `text` block holding JSON is
+ * parsed and pretty-printed (rather than shown double-escaped); non-JSON text
+ * is kept verbatim.
+ */
+function formatToolResult(result) {
+    if (result && result.structuredContent !== undefined) {
+        return { text: JSON.stringify(result.structuredContent, null, 2), isError: result.isError === true };
+    }
+
+    const blocks = Array.isArray(result?.content) ? result.content : [];
+    const parts = blocks.map((block) => {
+        if (block && block.type === "text" && typeof block.text === "string") {
+            try {
+                return JSON.stringify(JSON.parse(block.text), null, 2);
+            } catch {
+                return block.text;
+            }
+        }
+        return JSON.stringify(block, null, 2);
+    });
+    const text = parts.length > 0 ? parts.join("\n\n") : JSON.stringify(result, null, 2);
+    return { text, isError: result?.isError === true };
+}
+
+/** Calls one tool and renders its result inline on the card. */
+async function callTool(name, argsInput, callBtn, item) {
+    if (!client) return;
+
+    let args;
+    try {
+        args = argsInput.value.trim() ? JSON.parse(argsInput.value) : {};
+    } catch {
+        log(`Invalid JSON arguments for "${name}".`, "error");
+        return;
+    }
+
+    let resultBox = item.querySelector(".cat-result");
+    if (!resultBox) {
+        resultBox = document.createElement("div");
+        resultBox.className = "cat-result";
+        item.appendChild(resultBox);
+    }
+
+    callBtn.disabled = true;
+    resultBox.classList.remove("error");
+    resultBox.textContent = "Calling…";
+    log(`tools/call → ${name} ${JSON.stringify(args)}`, "dim");
+
+    try {
+        const result = await client.callTool(name, args);
+        const formatted = formatToolResult(result);
+        resultBox.classList.toggle("error", formatted.isError);
+        resultBox.textContent = formatted.text;
+        log(`tools/call ← ${name} ${formatted.isError ? "returned an error result." : "returned."}`, formatted.isError ? "warn" : "ok");
+    } catch (err) {
+        resultBox.classList.add("error");
+        resultBox.textContent = err.message;
+        log(`tools/call ← ${name} failed: ${err.message}`, "error");
+    } finally {
+        callBtn.disabled = false;
+    }
+}
+
+// =====================================================================
+// Lifecycle
+// =====================================================================
+let client = null;
+let intentionalClose = false;
+
+const startBtn = document.getElementById("start-btn");
+const stopBtn = document.getElementById("stop-btn");
+const wsUrlInput = document.getElementById("ws-url");
+const slotInput = document.getElementById("slot-name");
+const endpointsEl = document.getElementById("endpoints");
+
+// Derive the client WebSocket base from the page origin: ws:// over HTTP,
+// wss:// over HTTPS, avoids mixed-content errors under TLS.
+(function deriveClientUrl() {
+    const scheme = window.location.protocol === "https:" ? "wss:" : "ws:";
+    wsUrlInput.value = `${scheme}//${window.location.host}`;
+})();
+
+// Slot preset chips fill the slot input.
+for (const preset of document.querySelectorAll(".preset")) {
+    preset.addEventListener("click", () => {
+        slotInput.value = preset.dataset.slot;
+    });
+}
+
+function teardown() {
+    client = null;
+    intentionalClose = false;
+    setStatus("disconnected");
+    startBtn.disabled = false;
+    stopBtn.disabled = true;
+    endpointsEl.hidden = true;
+}
+
+function showEndpoints(slot) {
+    const httpScheme = window.location.protocol === "https:" ? "https:" : "http:";
+    const wsScheme = window.location.protocol === "https:" ? "wss:" : "ws:";
+    const host = window.location.host;
+    const enc = encodeURIComponent(slot);
+    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;
+}
+
+startBtn.addEventListener("click", async () => {
+    const base = wsUrlInput.value.trim().replace(/\/+$/, "");
+    const slot = slotInput.value.trim();
+    if (!base || !slot) {
+        log("Enter the broker base URL and a slot name first.", "error");
+        return;
+    }
+    const url = `${base}/${encodeURIComponent(slot)}`;
+
+    setStatus("connecting");
+    startBtn.disabled = true;
+    intentionalClose = false;
+    clearCatalog("Connecting…");
+    log(`Opening WebSocket to ${url} …`, "dim");
+
+    const c = new McpWebSocketClient(url);
+    c.onError = (err) => log(`Socket error: ${err.message}`, "error");
+    c.onClose = () => {
+        if (intentionalClose) return;
+        if (client === c) {
+            log("Connection closed by the broker.", "warn");
+            clearCatalog("Disconnected.");
+            teardown();
+        }
+    };
+
+    try {
+        await c.open();
+        client = c;
+        const info = await c.initialize();
+        const serverName = info?.serverInfo?.name ?? slot;
+        log(`Connected, initialized against "${serverName}".`, "ok");
+
+        const tools = await c.listTools();
+        renderCatalog(tools);
+        log(`tools/list → ${tools.length} tool(s) on slot "${slot}".`, "ok");
+
+        setStatus("connected");
+        stopBtn.disabled = false;
+        showEndpoints(slot);
+    } catch (err) {
+        log(`Connection failed: ${err.message}`, "error");
+        c.close();
+        clearCatalog("Not connected. Press Connect to list the slot's tools.");
+        teardown();
+    }
+});
+
+stopBtn.addEventListener("click", () => {
+    if (!client) return;
+    intentionalClose = true;
+    stopBtn.disabled = true;
+    client.close();
+    log("Disconnected.", "warn");
+    clearCatalog("Not connected. Press Connect to list the slot's tools.");
+    teardown();
+});
+
+// =====================================================================
+// Boot
+// =====================================================================
+log("Ready. Pick a slot (_broker or _all) and press Connect.", "dim");

package/web/demos/broker-explorer/js/mcp-ws-client.js

@@ -0,0 +1,132 @@
+/**
+ * mcp-ws-client.js: a minimal MCP client over a raw WebSocket.
+ *
+ * The broker exposes every slot as a raw-WebSocket client transport at
+ * `ws://<host>/<slot>`: the frames are plain newline-free JSON-RPC, relayed
+ * untouched to whatever server backs the slot (`_broker`, `_all`, or any
+ * tunnelled provider). There is therefore nothing broker-specific here: this
+ * is a standard MCP client. It is kept separate from `app.js` the same way the
+ * provider-tunnel demo keeps its MCP server in `toolbox-server.js`.
+ *
+ * Zero dependencies; speaks just enough of MCP for the explorer demo:
+ * `initialize`, `tools/list`, `tools/call`.
+ */
+
+/** MCP protocol version negotiated with the slot. */
+const PROTOCOL_VERSION = "2024-11-05";
+
+/** Per-request timeout. */
+const REQUEST_TIMEOUT_MS = 15_000;
+
+export class McpWebSocketClient {
+    /**
+     * @param {string} url Full slot URL, e.g. `ws://host:3000/_broker`.
+     */
+    constructor(url) {
+        this.url = url;
+        this._ws = null;
+        this._pending = new Map();
+        this._nextId = 0;
+
+        /** @type {null | (() => void)} Fires when the socket closes. */
+        this.onClose = null;
+        /** @type {null | ((error: Error) => void)} Fires on a socket error. */
+        this.onError = null;
+    }
+
+    /**
+     * Opens the WebSocket. Resolves once the broker accepts the upgrade.
+     * @returns {Promise<void>}
+     */
+    open() {
+        return new Promise((resolve, reject) => {
+            let opened = false;
+            const ws = new WebSocket(this.url);
+            this._ws = ws;
+
+            ws.onopen = () => {
+                opened = true;
+                resolve();
+            };
+            ws.onerror = () => {
+                const err = new Error(`WebSocket error on ${this.url}`);
+                this.onError?.(err);
+                if (!opened) reject(err);
+            };
+            ws.onclose = () => {
+                this._rejectAll("connection closed");
+                this.onClose?.();
+            };
+            ws.onmessage = (ev) => {
+                let msg;
+                try {
+                    msg = JSON.parse(typeof ev.data === "string" ? ev.data : "");
+                } catch {
+                    return;
+                }
+                if (msg && typeof msg.id === "number" && this._pending.has(msg.id)) {
+                    const pending = this._pending.get(msg.id);
+                    this._pending.delete(msg.id);
+                    clearTimeout(pending.timer);
+                    pending.resolve(msg);
+                }
+            };
+        });
+    }
+
+    /** Runs the MCP `initialize` handshake. */
+    async initialize() {
+        const res = await this._request("initialize", {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: "broker-explorer", version: "1.0.0" },
+        });
+        this._send({ jsonrpc: "2.0", method: "notifications/initialized" });
+        return res.result;
+    }
+
+    /** Lists the slot's tools. */
+    async listTools() {
+        const res = await this._request("tools/list", {});
+        if (res.error) throw new Error(res.error.message || "tools/list failed");
+        return res.result?.tools ?? [];
+    }
+
+    /** Calls a tool and returns the raw JSON-RPC result (or throws on error). */
+    async callTool(name, args) {
+        const res = await this._request("tools/call", { name, arguments: args });
+        if (res.error) throw new Error(res.error.message || "tools/call failed");
+        return res.result;
+    }
+
+    /** Closes the WebSocket. */
+    close() {
+        this._ws?.close();
+    }
+
+    _send(obj) {
+        if (this._ws && this._ws.readyState === WebSocket.OPEN) {
+            this._ws.send(JSON.stringify(obj));
+        }
+    }
+
+    _request(method, params) {
+        return new Promise((resolve, reject) => {
+            const id = ++this._nextId;
+            const timer = setTimeout(() => {
+                this._pending.delete(id);
+                reject(new Error(`request "${method}" timed out`));
+            }, REQUEST_TIMEOUT_MS);
+            this._pending.set(id, { resolve, reject, timer });
+            this._send({ jsonrpc: "2.0", id, method, params });
+        });
+    }
+
+    _rejectAll(reason) {
+        for (const pending of this._pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error(reason));
+        }
+        this._pending.clear();
+    }
+}

package/web/demos/oauth-lab/README.md

@@ -0,0 +1,94 @@
+# OAuth Policy Lab
+
+A self-contained browser demonstration of the broker's OAuth 2.1 resource
+server and hierarchical authorization features.
+
+Its industrial resource paths use the compact ISA-95 / IEC 62264-aligned
+profile documented in the
+[hierarchical authorization guide](../../../../docs/hierarchical-authorization.md).
+The policy engine remains domain-neutral and does not claim full ISA-95
+compliance.
+
+## Run
+
+From the `node/` directory:
+
+```sh
+npm run demo:oauth
+```
+
+The command builds the broker, starts the local authorization server on
+`http://127.0.0.1:4100`, starts the broker and three stdio MCP providers on
+`http://127.0.0.1:3001`, then opens:
+
+```text
+http://127.0.0.1:3001/demos/oauth-lab/
+```
+
+Set `OAUTH_LAB_NO_OPEN=1` to keep the command from opening a browser.
+
+While the demo is running, its automated end-to-end check can be launched
+from another terminal:
+
+```sh
+npm run demo:oauth:smoke
+```
+
+This example is for local development only. Its authorization server presents
+four passwordless demo identities and generates an in-memory signing key on
+every start.
+
+## What it demonstrates
+
+- OAuth 2.0 Protected Resource Metadata discovery
+- Authorization Code with PKCE S256
+- authorization server metadata discovery
+- signed JWT access tokens and JWKS validation
+- issuer, expiration, OAuth scope, and RFC 8707 audience validation
+- tab-scoped token caching with silent per-resource token acquisition
+- claim mapping to users, groups, and client identities
+- role inheritance and resource-scoped assignments
+- explicit deny precedence
+- per-slot scope requirements for `_broker`
+- capability mapping for MCP tool calls
+- live allow and deny audit events
+
+## Demo identities
+
+| Identity | Group | Effective access |
+| --- | --- | --- |
+| Geordi La Forge, Chief Engineer | `starfleet-engineering` | Read, diagnose, and reset in Area A. Reset is explicitly denied on the critical furnace. |
+| Worf, Chief Security Officer | `starfleet-security` | Read and start machines in Area A. |
+| Seven of Nine, Astrometrics Specialist | `astrometrics` | Read-only access across the Paris site. |
+| Jean-Luc Picard, Captain | `starfleet-command` | Full resource access and the `broker:admin` OAuth scope. |
+
+Each token is audience-bound to the selected MCP resource. Picard's policy
+grants access everywhere, but a token issued for `_broker` cannot be reused for
+`motor-7`, `critical-furnace`, or `site-energy`. The browser caches one token
+per resource for the lifetime of the tab. After the first interactive identity
+selection, the local authorization server reuses its opaque identity session to
+add tokens silently without presenting the identity page again.
+
+The private signing key, authorization codes, identity sessions, and audit
+events are held only in server memory. Access tokens are held in the browser's
+tab-scoped session storage. Stop the demo with `Ctrl+C`.
+
+## Reading the results
+
+The two layers of refusal look different on the wire, and telling them apart is
+the point of the lab:
+
+| Refusal | Where it happens | What comes back |
+| --- | --- | --- |
+| No token, invalid token, missing scope | Before the request reaches the transport | HTTP `401` or `403` with `WWW-Authenticate` |
+| A policy denies the operation | Once the session is open and the frame is read | HTTP `200` with JSON-RPC `-32001 Forbidden` |
+
+A policy denial is not a transport failure: the request arrived, the session was
+valid, the operation was refused. So the status stays `200` and the refusal
+travels inside the JSON-RPC body, which is also what the raw WebSocket transport
+has always done.
+
+`/<slot>/mcp` runs the real Streamable HTTP state machine: `initialize` opens a
+session and returns `Mcp-Session-Id`, which every later request must send back.
+Requests from a browser also carry an `Origin`, refused by default, so
+`config.json` lists the lab's own origin under `allowedOrigins`.