@cyanmycelium/mcp-broker 1.2.0 → 1.3.0

package/src/broker/broker.guides.ts

@@ -0,0 +1,1029 @@
+/**
+ * The broker's self-documentation, as plain Markdown constants.
+ *
+ * This module is the **source of truth** for how to integrate with an
+ * mcp-broker instance. It is served live over MCP by
+ * {@link BrokerGuideBehavior} (resources `broker://guide/*` and the
+ * `broker_guide` tool), so an agent that can reach the reserved `_broker`
+ * slot, or `_all` which aggregates it, learns the integration rules without
+ * ever opening a README.
+ *
+ * Every statement here is derived from the broker's own source, not from the
+ * repository's prose documentation. When the two disagree, this file is right
+ * and the prose is stale. The markdown docs and the samples import these
+ * constants rather than restating them, so there is exactly one copy of the
+ * rules to keep correct.
+ *
+ * Content is written for a machine reader with no prior knowledge of this
+ * project: rules are stated as rules, failure modes name their observable
+ * signature, and every diagnosis ends in an action.
+ */
+
+// ---------------------------------------------------------------------------
+// Topics
+// ---------------------------------------------------------------------------
+
+/**
+ * Identifier of one guide page. Also the last URI segment of the matching
+ * `broker://guide/<topic>` resource, and the value accepted by the
+ * `broker_guide` tool's `topic` argument.
+ */
+export type BrokerGuideTopic = "index" | "publish-provider" | "connect-client" | "host-config" | "deploy" | "troubleshooting";
+
+/** Scheme + path prefix shared by every guide resource URI. */
+export const BROKER_GUIDE_URI_PREFIX = "broker://guide/";
+
+/** RFC 6570 URI template covering every guide page. */
+export const BROKER_GUIDE_URI_TEMPLATE = "broker://guide/{topic}";
+
+/** One guide page: its identity, its one-line pitch, and its Markdown body. */
+export interface IBrokerGuide {
+    /** Stable topic id, used by the tool argument and the resource URI. */
+    topic: BrokerGuideTopic;
+
+    /** Canonical resource URI, `broker://guide/<topic>`. */
+    uri: string;
+
+    /** Short human title, e.g. "Publish a provider". */
+    title: string;
+
+    /** One line describing when to read this page. Shown in the index. */
+    summary: string;
+
+    /** The page body, Markdown, self-contained. */
+    content: string;
+}
+
+// ---------------------------------------------------------------------------
+// Shared fragments
+// ---------------------------------------------------------------------------
+
+/**
+ * The pairing rule, verbatim in every page that can be reached by someone
+ * about to make the mistake. Restated rather than cross-referenced on
+ * purpose: an agent may read exactly one page.
+ */
+const PAIRING_RULE = [
+    "```",
+    "  DirectTransport      <->  ws://<host>/provider/<name>    plain JSON-RPC frames",
+    "  MultiplexTransport   <->  ws://<host>/providers          envelope frames { provider, payload }",
+    "```",
+    "",
+    "`ws://<host>/providers/<name>` is NEITHER of those two. The broker's router",
+    "matches `/providers` exactly and `/provider/` as a prefix, so a URL that starts",
+    "with `/providers/` falls through to the client branch and is accepted as an MCP",
+    "**client** on a slot literally named `providers/<name>`. Nothing errors. Your",
+    "provider is not published, and the slot you meant stays empty forever.",
+].join("\n");
+
+// ---------------------------------------------------------------------------
+// index
+// ---------------------------------------------------------------------------
+
+const GUIDE_INDEX = [
+    "# mcp-broker integration guide",
+    "",
+    "You are reading the built-in documentation of a running mcp-broker instance.",
+    "It is authoritative for THIS broker. You do not need a README, and you should",
+    "not trust one that disagrees with this text.",
+    "",
+    "## What the broker is",
+    "",
+    "One process that puts N MCP servers behind one host and one port. Each server",
+    "occupies a named **slot**. Servers reach a slot from the inside as *providers*;",
+    "MCP clients reach a slot from the outside over HTTP, SSE, WebSocket or stdio.",
+    "Slots are created lazily: any name works, there is no registry to declare.",
+    "",
+    "## The one rule that costs the most time",
+    "",
+    "A provider's transport and its URL path are a matched pair.",
+    "",
+    PAIRING_RULE,
+    "",
+    "Get it wrong in the DirectTransport-on-`/providers` direction and the slot is",
+    "never claimed. Get it wrong the other way and the slot reports itself connected",
+    "while every client request hangs. This broker detects both on your first frame",
+    "and closes the socket with code `1008` and a reason naming the correction, but",
+    "it cannot detect a provider that connects and never sends anything, and older",
+    "brokers say nothing at all. See `broker://guide/publish-provider`.",
+    "",
+    "## The pages",
+    "",
+    "| topic | read it when |",
+    "|---|---|",
+    "| `publish-provider` | you have an MCP server and want this broker to expose it |",
+    "| `connect-client` | you have an MCP client and want to reach a slot |",
+    "| `host-config` | you are wiring Claude Desktop or another stdio MCP host |",
+    "| `deploy` | you are choosing between embedding the broker and running it |",
+    "| `troubleshooting` | something is already broken: symptom, cause, fix |",
+    "",
+    "Read a page as a resource (`broker://guide/<topic>`) or call",
+    '`broker_guide({ topic: "<topic>" })`. Calling `broker_guide` with no argument',
+    "returns this index.",
+    "",
+    "## Tools on this slot",
+    "",
+    "| tool | what it answers |",
+    "|---|---|",
+    "| `broker_info` | identity, version, uptime, bind address, TLS, effective URL paths |",
+    "| `providers_list` | every known slot, connected or not, with live counters |",
+    "| `provider_status({ name })` | one slot in detail |",
+    "| `broker_guide({ topic? })` | these pages |",
+    "| `broker_diagnose({ slot? })` | live state PLUS detected problems, each with a fix |",
+    "",
+    "When something does not work, call `broker_diagnose` before reading anything.",
+    "It does the correlation for you and names the fix.",
+    "",
+    "## Reserved slots",
+    "",
+    "- `_broker`: this slot. Introspection only. It routes to nothing else.",
+    "- `_all`: an aggregate that unions the tools and prompts of every opted-in",
+    "  provider, including `_broker`. Tool names are prefixed `<slot>-<original>`.",
+    "  It is the correct target for a stdio MCP host. See `broker://guide/host-config`.",
+    "",
+    "## Vocabulary",
+    "",
+    "- **slot**: a name. Providers publish into it; clients connect to it.",
+    "- **provider**: an MCP *server* that connects INTO the broker to serve a slot.",
+    "- **client**: an MCP *client* that connects to the broker to reach a slot.",
+    "- **upstream**: a provider the broker itself starts or dials out to",
+    "  (a child process, a remote URL, a signed `.mcpb` bundle).",
+].join("\n");
+
+// ---------------------------------------------------------------------------
+// publish-provider
+// ---------------------------------------------------------------------------
+
+const GUIDE_PUBLISH_PROVIDER = [
+    "# Publish an MCP server into a broker slot",
+    "",
+    "## 1. The pairing rule",
+    "",
+    "A provider's transport and its URL path are a matched pair. This is the single",
+    "most expensive mistake to make against this broker: both ways of getting it",
+    "wrong leave every side believing it succeeded.",
+    "",
+    PAIRING_RULE,
+    "",
+    "Two more paths that look plausible and are not. Both are now refused at the",
+    "WebSocket handshake with HTTP 400, and the response body is the full",
+    "diagnosis; a Node client reads it off the `unexpected-response` event, a",
+    "browser sees only a bare `error` event and you have to read the broker log:",
+    "",
+    "- `ws://<host>/provider` with no name. It used to be accepted and to occupy a",
+    "  slot literally named `(unnamed)`, which no client could address.",
+    "- `ws://<host>/provider/a/b`, more than one segment after the prefix. A slot",
+    "  name containing `/` must be percent-encoded: `/provider/a%2Fb`. Both",
+    "  spellings resolve to the same slot, so only the encoded one is accepted and",
+    "  nothing is lost. Prefer a flat name anyway.",
+    "",
+    "## 2. How each mismatch presents",
+    "",
+    "The broker inspects the first frame on a provider socket and refuses both",
+    "directions: it answers in the framing the peer can actually decode, then",
+    "closes with code `1008` and a reason naming both corrections. Only an",
+    "unambiguous frame triggers this (an envelope with no `jsonrpc` on the",
+    "slot-scoped path, a `jsonrpc` frame that is not an envelope on the multiplex",
+    "path), so a dialect the broker does not recognize is still left alone.",
+    "",
+    "Do not rely on the refusal. It cannot fire before your first frame, so a",
+    "provider that connects and stays silent still looks connected, and older",
+    "brokers say nothing at all. The signatures below are what you read then.",
+    "",
+    "**MultiplexTransport pointed at `/provider/<name>`.** The slot-scoped path takes",
+    "the slot name from the URL at connect time, so registration succeeds before any",
+    'frame exists: `providers_list` reports `connected: true, transport: "ws"`. But',
+    "the broker now writes plain JSON-RPC onto that socket, and MultiplexTransport",
+    "drops every frame that is not an envelope. Your MCP server never receives",
+    "`initialize`. Meanwhile your envelope-wrapped replies carry no top-level `id`,",
+    "so the broker classifies them as notifications and broadcasts them instead of",
+    "answering the waiting request.",
+    "",
+    "  Observable signature: `provider_status` shows `connected: true`,",
+    '  `transport: "ws"`, `pendingCount` climbing and never returning to 0, while the',
+    "  client's `initialize` never resolves. `broker_diagnose` reports this as",
+    "  `transport-path-mismatch`.",
+    "",
+    "**DirectTransport pointed at `/providers`.** The multiplex path learns slot names",
+    "only from envelopes. A plain JSON-RPC frame has no `provider`/`payload` pair, so",
+    "it is dropped and no slot is ever claimed.",
+    "",
+    "  Observable signature: the socket is open on your side, and the slot does not",
+    "  appear in `providers_list` at all. Clients get",
+    '  `-32000 Provider "<name>" not connected`.',
+    "",
+    "## 3. Dedicated socket (DirectTransport)",
+    "",
+    "One socket per slot. The slot is claimed the instant the socket opens, before",
+    "any frame is sent, so a client arriving first is served immediately.",
+    "",
+    "```ts",
+    'import { DirectTransport } from "@cyanmycelium/mcp-broker-provider";',
+    'import { McpServerBuilder } from "@cyanmycelium/mcp-core";',
+    "",
+    'const transport = new DirectTransport("ws://localhost:3000/provider/my-slot");',
+    "const server = new McpServerBuilder()",
+    '    .withName("my-slot")',
+    "    .withTransport(transport)",
+    "    .register(/* your behaviors */)",
+    "    .build();",
+    "",
+    "await server.start(); // opens the socket",
+    "```",
+    "",
+    "`server.start()` resolving means the socket reported itself open. It does NOT",
+    "mean the broker accepted the slot: a refusal arrives after the open as a",
+    "WebSocket close with code 1008, and the reason string says which refusal it was.",
+    "",
+    "## 4. Shared socket (MultiplexTransport)",
+    "",
+    "One socket carrying N slots, keyed per frame. Use it when one page or one",
+    "process publishes several servers.",
+    "",
+    "```ts",
+    'import { MultiplexTransport } from "@cyanmycelium/mcp-broker-provider";',
+    "",
+    'const a = MultiplexTransport.create("scene-1", "ws://localhost:3000/providers");',
+    'const b = MultiplexTransport.create("scene-2", "ws://localhost:3000/providers");',
+    "// a and b share one WebSocket. Same URL means same socket.",
+    "```",
+    "",
+    "On open it sends one registration notification per slot,",
+    '`{ "provider": "<name>", "payload": { "jsonrpc": "2.0", "method": "notifications/register" } }`,',
+    "so the broker creates the slot before your first MCP frame. MultiplexTransport",
+    "reconnects on its own with exponential backoff and jitter, capped at 30s.",
+    "DirectTransport does not reconnect at all: if you need that, reconnect yourself",
+    "in `onClose`.",
+    "",
+    "## 5. Wire format",
+    "",
+    "Slot-scoped socket, both directions, plain MCP frames:",
+    "",
+    "```json",
+    '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }',
+    "```",
+    "",
+    "Multiplex socket, both directions, every frame wrapped:",
+    "",
+    "```json",
+    '{ "provider": "scene-1", "payload": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } }',
+    "```",
+    "",
+    "A frame the broker cannot decode on the multiplex socket is dropped, and the",
+    "first drop per socket is logged with the reason. A plain JSON-RPC frame there",
+    "is not merely dropped: it is the DirectTransport-on-`/providers` mismatch, so",
+    "it is answered with a bare JSON-RPC error and the socket is closed with `1008`.",
+    "A tunnel-level refusal comes back as an envelope whose payload is a JSON-RPC",
+    "error with `id: null` and code `-32000` (slot unavailable) or `-32001`",
+    "(registration forbidden).",
+    "",
+    "## 6. Joining the `_all` aggregate",
+    "",
+    "A provider is NOT in `_all` by default. Opting in is per provider and depends on",
+    "how the provider reaches the broker.",
+    "",
+    "| provider kind | how it joins `_all` |",
+    "|---|---|",
+    "| WebSocket on `/provider/<name>` | send the aggregate opt-in as the socket's **first** frame, see below |",
+    "| WebSocket on `/providers` (multiplex) | announce it in the registration envelope, see below |",
+    '| `stdioUpstreams[]` config entry | set `"aggregate": true` (omitted means NOT aggregated) |',
+    '| `mcpServers[]` config entry | aggregated by default; set `"aggregate": false` to opt out |',
+    '| `mcpbBundles[]` config entry | aggregated by default; set `"aggregate": false` to opt out |',
+    "| `_broker` | always, automatically |",
+    "",
+    "### From the SDK",
+    "",
+    "```ts",
+    'new DirectTransport("ws://localhost:3000/provider/my-slot", { aggregate: true });',
+    'MultiplexTransport.create("my-slot", "ws://localhost:3000/providers", { aggregate: true });',
+    "```",
+    "",
+    "Both send the JSON-RPC-shaped registration notification on open,",
+    '`{"jsonrpc":"2.0","method":"notifications/register","params":{"aggregate":true}}`,',
+    "wrapped in an envelope on the shared socket.",
+    "",
+    "### The raw control frame",
+    "",
+    "The broker also accepts a non-JSON-RPC control frame on the slot-scoped path,",
+    "which is what to send when you drive the socket yourself:",
+    "",
+    "```ts",
+    'const ws = new WebSocket("ws://localhost:3000/provider/my-slot");',
+    "ws.onopen = () => {",
+    '    ws.send(JSON.stringify({ type: "register", aggregate: true }));',
+    "    // ... then hand the socket to your transport / start the server",
+    "};",
+    "```",
+    "",
+    "It must be the FIRST frame on that socket. The broker inspects exactly one frame",
+    "per socket for this, and a frame carrying `jsonrpc` is routed as traffic, so a",
+    "socket that has already sent an MCP frame stays non-aggregated for its whole life.",
+    "",
+    "**Do not assume the opt-in took.** The two shapes are honored by different",
+    "broker versions, and a refused or ignored opt-in produces no error. Verify:",
+    "call `tools/list` on the `_all` slot and look for your `<slot>-<tool>` names, or",
+    "call `broker_diagnose()`, which reports `aggregate-empty` and",
+    "`aggregate-missing-live-slots` when a connected slot is not in the aggregate.",
+    "",
+    "**Install your MCP message handler before you opt in.** The moment the broker",
+    "accepts the aggregate registration it opens an internal client and sends",
+    "`initialize`. A provider that is not listening yet fails that handshake and is",
+    "dropped from `_all` silently, with no log and no retry.",
+    "",
+    "## 7. Lifecycle: connect, register, release",
+    "",
+    "1. **Connect.** Open the WebSocket at the path that matches your transport.",
+    "2. **Register.** Slot-scoped: automatic, from the URL. Multiplex: from the first",
+    "   envelope, which the SDK sends on open. Optionally opt into `_all` first.",
+    "3. **Release.** Close the socket. There is no release message: the only control",
+    "   frame the broker understands is the registration frame. On close the broker",
+    "   clears the slot and fails every in-flight request with",
+    '   `-32000 Provider "<name>" disconnected`, echoing the original request id.',
+    "",
+    "**Release explicitly anyway.** A slot is occupied while the incumbent socket is",
+    "`readyState === OPEN`, and a socket that dies without sending a close frame (a",
+    "hard kill, a crashed tab, a suspended laptop, devtools set to offline) stays",
+    "OPEN until the OS TCP keepalive gives up, which is hours.",
+    "",
+    "```ts",
+    "// Browsers fire pagehide reliably on reload, navigation and tab close.",
+    'addEventListener("pagehide", () => transport.close());',
+    "```",
+    "",
+    "A ws-level ping/pong heartbeat is what stops that from wedging the slot",
+    "forever. Each provider socket is pinged every `providerHeartbeatIntervalMs`",
+    "(default 30000; `0` disables it), and one that misses a full interval is",
+    "terminated and its slot freed. So a reconnect in the gap is still refused with",
+    'close code 1008 and reason `Provider "<name>" is already connected`, but the',
+    "window is one interval rather than hours. Releasing on `pagehide` is what makes",
+    "it instant instead.",
+    "",
+    '`providerTakeover` decides who wins the contention: `"liveness"` (default) lets',
+    'the newcomer in only once the incumbent has missed a heartbeat, `"reject"` never',
+    'hands a slot over, and `"always"` is honored only when provider authentication',
+    "is configured and the newcomer authenticated as the same principal (otherwise",
+    'the broker logs why and falls back to `"liveness"`).',
+    "",
+    "One honest limit: an RFC 6455 pong is answered by the browser's network stack,",
+    "so the heartbeat proves the process is alive, not that the page's JS thread is",
+    "serving. A throttled background tab answers pings and still never replies to a",
+    "request; `providerRequestTimeoutMs` is what covers that case.",
+    "",
+    "## 8. Refusals you can receive",
+    "",
+    "On the slot-scoped socket a refusal is a WebSocket close with code 1008; the",
+    "reason string is the message below. On the multiplex socket it is an error",
+    "envelope for that slot name and the socket stays open.",
+    "",
+    "| reason | cause | fix |",
+    "|---|---|---|",
+    '| `Provider "<n>" is already connected` | a live socket holds the slot | release on `pagehide`; a genuinely dead holder is reaped within one heartbeat interval (default 30s), so retry |',
+    '| `Provider "<n>" is reserved by the broker` | you targeted `_broker` or `_all` | pick another slot name |',
+    '| `Provider "<n>" is managed by a stdio upstream` | the name collides with a configured upstream | rename one of them |',
+    "| HTTP 401 at the handshake | provider auth is on and no credential was presented | see below |",
+    "| HTTP 403 at the handshake | your principal may not publish on that slot | widen `allowedResources` |",
+    "",
+    "## 9. In a browser",
+    "",
+    "- **A bundler is required.** Both packages ship ESM under `dist/`, with no",
+    "  `browser` field and no UMD build, so a plain `<script>` tag will not do.",
+    "- **Provider authentication cannot work from a browser.** The broker reads the",
+    "  provider secret from the `X-Provider-Token` header or from",
+    "  `Authorization: Bearer`, and the browser `WebSocket` constructor cannot set",
+    "  headers. Neither transport accepts a credential. If the broker is configured",
+    "  with a provider secret, every browser provider is refused at the handshake",
+    "  with HTTP 401, which reaches your page as a bare `error` event with no status.",
+    "  Run the broker without a provider secret, or terminate provider auth in a",
+    "  reverse proxy that injects the header.",
+    "- A page served by the broker's own static mount is still a browser origin for",
+    "  the purposes of the client-side origin check. Serving the page does not",
+    "  exempt it. See `broker://guide/connect-client`.",
+    "",
+    "## 10. In Node",
+    "",
+    "Both transports call the **global** `WebSocket` constructor with no import. Node",
+    "22 and later provide one. On Node 20 assign a polyfill before connecting:",
+    "",
+    "```ts",
+    'import WebSocket from "ws";',
+    "globalThis.WebSocket = WebSocket as unknown as typeof globalThis.WebSocket;",
+    "```",
+    "",
+    "If the MCP server and the broker live in the same process, skip WebSockets",
+    "entirely and call `tunnel.registerLoopbackProvider(name, transport)` with an",
+    "in-process transport. See `broker://guide/deploy`.",
+].join("\n");
+
+// ---------------------------------------------------------------------------
+// connect-client
+// ---------------------------------------------------------------------------
+
+const GUIDE_CONNECT_CLIENT = [
+    "# Reach a slot as an MCP client",
+    "",
+    "## 1. Endpoints, per slot",
+    "",
+    "| transport | endpoint | notes |",
+    "|---|---|---|",
+    "| Streamable HTTP | `POST`, `GET`, `DELETE` `http(s)://<host>/<slot>/mcp` | current MCP transport, use this |",
+    "| Legacy SSE | `GET http(s)://<host>/<slot>/sse` then `POST .../<slot>/messages` | 2024-11-05 HTTP+SSE, kept for old hosts |",
+    "| Raw WebSocket | `ws(s)://<host>/<slot>` | bare JSON-RPC frames, no session layer |",
+    "| stdio bridge | the broker process itself | one slot per broker process, see `broker://guide/host-config` |",
+    "",
+    "`<slot>` is the slot name. The HTTP router splits the path on `/` and requires",
+    "exactly two segments, so a slot name containing `/` must be percent-encoded:",
+    "slot `a/b` is reachable at `/a%2Fb/mcp`.",
+    "",
+    "Default path suffixes are `/mcp`, `/sse` and `/messages`; call `broker_info` to",
+    "read the effective values if the deployment customized them.",
+    "",
+    "## 2. Connecting to a slot that has no provider",
+    "",
+    "Slots are lazy. Connecting to a name nobody serves is not an error: the",
+    "connection succeeds and every request is answered with",
+    '`-32000 Provider "<slot>" not connected`. Call `providers_list` on `_broker` to',
+    "see which names actually exist, or `broker_diagnose` to be told why one is empty.",
+    "",
+    "## 3. Reserved slots",
+    "",
+    "### `_broker`",
+    "",
+    "The broker's own introspection server, and nothing else. It exposes",
+    "`broker_info`, `providers_list`, `provider_status`, `broker_guide` and",
+    "`broker_diagnose`, plus the resources `broker://info`, `broker://providers`,",
+    "`broker://providers/{name}` and `broker://guide/{topic}`. It does not proxy any",
+    "other provider. It is available from the moment the broker finishes starting.",
+    "",
+    "### `_all`",
+    "",
+    "An aggregate, not a proxy. It presents the union of the tools and prompts of",
+    "every **opted-in** provider as one MCP server. Membership covers configured",
+    "upstreams (`stdioUpstreams`, `mcpServers`, `mcpbBundles`), `_broker` itself, and",
+    "WebSocket provider slots that sent the aggregate opt-in frame. See",
+    "`broker://guide/publish-provider` for how a provider opts in.",
+    "",
+    "Names are prefixed with the origin slot:",
+    "",
+    "```",
+    "  <slot>-<original>        e.g. weather-forecast, _broker-broker_info",
+    "```",
+    "",
+    "**Never reconstruct a prefixed name.** The prefixed name is capped at 64",
+    "characters, and an overlong one is truncated and given a hash suffix; a",
+    "collision between two providers is broken with a `-2`, `-3` suffix. The mapping",
+    "back to `(provider, original)` is a lookup table, not a parse. Call `tools/list`",
+    "on `_all` and pass the returned string back verbatim in `tools/call`.",
+    "",
+    "Descriptions are tagged with their origin, `[<slot>] <original description>`, so",
+    "you can tell where a tool came from without parsing its name.",
+    "",
+    "`_all` implements `initialize`, `ping`, `tools/list`, `tools/call`,",
+    "`prompts/list` and `prompts/get`. **Everything else returns",
+    "`-32601 Method not found`**, including `resources/list` and `resources/read`. If",
+    "you need a provider's resources, connect to that provider's own slot.",
+    "",
+    "`_all` emits `notifications/tools/list_changed` and",
+    "`notifications/prompts/list_changed` whenever a provider joins, leaves, or",
+    "changes its catalog. A client that subscribes sees a provider that arrives",
+    "mid-session without reconnecting.",
+    "",
+    "## 4. Browser clients and the origin check",
+    "",
+    "All three HTTP client endpoints, `/<slot>/mcp`, `/<slot>/sse` and",
+    "`/<slot>/messages`, refuse any request carrying an `Origin` header that is not",
+    "on the allow list, with HTTP 403. **The list is empty by default**, so out of",
+    "the box no browser origin passes while every non-browser client (which sends no",
+    "`Origin`) passes. This is deliberate: without the check any page in the user's",
+    "browser could drive the broker.",
+    "",
+    "Serving the page from the broker's own static mount does NOT exempt it. Set the",
+    "origins explicitly:",
+    "",
+    "```json",
+    '{ "allowedOrigins": ["http://localhost:3000", "https://app.example.com"] }',
+    "```",
+    "",
+    "or `MCP_BROKER_ALLOWED_ORIGINS=http://localhost:3000,https://app.example.com`.",
+    "Match the scheme, host and port exactly, as the browser sends them; if the",
+    "broker runs with TLS the origin is `https://`, not `http://`.",
+    "",
+    "The 403 body names the refused origin, says whether the list was unset or set",
+    "but non-matching, and states the comparison rule, so the usual causes (a",
+    "trailing slash, `http` against a TLS broker, a missing port) are readable off",
+    "the response.",
+    "",
+    "The **WebSocket** endpoints carry no origin check at all: `ws://<host>/<slot>`",
+    "and the two provider paths are gated by authorization and by provider auth,",
+    "never by `Origin`. Do not treat a working WebSocket as evidence that the same",
+    "page's HTTP requests will pass.",
+    "",
+    "## 5. Authorization",
+    "",
+    "When OAuth 2.1 is enabled, every HTTP request to a slot must carry",
+    "`Authorization: Bearer <token>` issued for that slot's canonical resource URI. A",
+    "missing or invalid token gets 401 with an RFC 9728 `WWW-Authenticate` challenge;",
+    "a valid token lacking the required scope gets 403 with the missing scope named",
+    "in the challenge. Protected Resource Metadata is served unauthenticated so a",
+    "client can discover the authorization server after the first 401.",
+    "",
+    "On `_all`, authorization filters the catalog rather than rejecting the call: a",
+    "caller sees only the providers it is scoped for, and a tool it may not see",
+    "answers `-32602 Unknown aggregated tool`, deliberately indistinguishable from a",
+    "name that does not exist.",
+    "",
+    "## 6. Errors you can receive, and what they mean",
+    "",
+    "| error | meaning |",
+    "|---|---|",
+    '| `-32000 Provider "<n>" ... not connected` | the slot exists but nothing is serving it right now |',
+    '| `-32000 Provider "<n>" disconnected` | the provider dropped while your request was in flight |',
+    '| `-32000 Provider "<n>" is no longer connected` | `_all` routed to a provider that left between list and call |',
+    '| `-32000 Provider "<n>" did not respond within <ms>ms` | the provider stayed connected and never answered; raise `providerRequestTimeoutMs` for genuinely long tools |',
+    "| `-32601 Method not found` | on `_all`, a method outside tools and prompts |",
+    "| `-32602 Unknown aggregated tool` | on `_all`, a stale or invisible prefixed name; re-list |",
+    "| HTTP 403 `invalid_origin` | your `Origin` is not on the allow list |",
+    "| HTTP 401 / 403 | bearer token missing, invalid, or missing a scope |",
+    "",
+    "A request that produces no reply at all is not in this table. That is the",
+    "transport/path mismatch described in `broker://guide/troubleshooting`; call",
+    "`broker_diagnose` and it will name it.",
+].join("\n");
+
+// ---------------------------------------------------------------------------
+// host-config
+// ---------------------------------------------------------------------------
+
+const GUIDE_HOST_CONFIG = [
+    "# Wiring an MCP host (Claude Desktop and friends)",
+    "",
+    "## 1. Point the bridge at `_all`, not at your slot",
+    "",
+    "This is the second most expensive mistake against this broker, and unlike the",
+    "transport pairing it is a pure ordering problem.",
+    "",
+    "An MCP host starts its servers when the host application launches. It sends",
+    "`initialize` immediately and treats a failure as a dead server: no retry, no",
+    "backoff, the entry is disabled for the session. Your provider, meanwhile, does",
+    "not exist yet. A browser provider needs a human to open a page; a provider in",
+    "another process needs that process to start.",
+    "",
+    "So pinning the stdio bridge to a real slot fails every single time: the bridge",
+    "answers the host's very first `initialize` with",
+    '`-32000 Provider "<slot>" not connected`, and the host gives up.',
+    "",
+    "**Pin it to `_all`.** `_all` is registered before the broker resumes stdin, it",
+    "answers `initialize` itself, it already aggregates `_broker` so the host always",
+    "has at least the introspection tools, and it pushes",
+    "`notifications/tools/list_changed` when a provider joins, so a page opened ten",
+    "minutes into the session appears in the host's tool list live.",
+    "",
+    "`_broker` is the fallback if you want introspection only. It is also always up,",
+    "but it will never show you anything except the broker's own five tools.",
+    "",
+    "## 2. Claude Desktop recipe",
+    "",
+    "```json",
+    "{",
+    '    "mcpServers": {',
+    '        "mcp-broker": {',
+    '            "command": "npx",',
+    '            "args": ["-y", "@cyanmycelium/mcp-broker"],',
+    '            "env": {',
+    '                "MCP_BROKER_STDIO_PROVIDER": "_all",',
+    '                "MCP_BROKER_PORT": "3000",',
+    '                "MCP_BROKER_HOST": "127.0.0.1"',
+    "            }",
+    "        }",
+    "    }",
+    "}",
+    "```",
+    "",
+    "`MCP_BROKER_STDIO_PROVIDER` is what turns the process into a stdio bridge: stdin",
+    "carries the host's JSON-RPC, stdout carries the replies, and all logging is",
+    "redirected to stderr so it cannot corrupt the channel. The broker keeps",
+    "listening on its port at the same time, so providers can still tunnel in.",
+    "",
+    "## 3. One broker per port. Exactly one.",
+    "",
+    "Do not add a second host entry that spawns another broker. The second process",
+    "cannot bind the port and dies; the host reports `Connection closed` with no",
+    "cause, and the real cause (`EADDRINUSE`) is only in the host's",
+    "`mcp-server-<name>.log`. If you want two logical servers visible to the host,",
+    "publish both into the one broker and let `_all` union them. That is the entire",
+    "point of `_all`.",
+    "",
+    "If a broker is already running on the port from another launcher, give the host",
+    "entry a different `MCP_BROKER_PORT`, or drop the host entry and reach the",
+    "running broker over Streamable HTTP instead.",
+    "",
+    "## 4. The bridge is anonymous",
+    "",
+    "The stdio bridge forwards frames to `_all` with **no principal attached**. While",
+    "no authorization is configured that is invisible. The moment you enable",
+    "per-provider scopes or a policy that denies an anonymous subject, the host's",
+    "tool list silently empties: `tools/list` still returns 200 with `tools: []`, and",
+    "nothing anywhere says why. If you enable authorization and the host goes blank,",
+    "this is why.",
+    "",
+    "## 5. Environment variables the host entry can set",
+    "",
+    "| variable | default | meaning |",
+    "|---|---|---|",
+    "| `MCP_BROKER_STDIO_PROVIDER` | unset | slot the stdin/stdout bridge serves. Use `_all`. |",
+    "| `MCP_BROKER_PORT` | `3000` | TCP port |",
+    "| `MCP_BROKER_HOST` | `0.0.0.0` | bind interface; `127.0.0.1` keeps it local |",
+    "| `MCP_BROKER_CONFIG` | unset | path to a JSON config file |",
+    "| `MCP_BROKER_LOCALE` | `en` | locale for the `_broker` tool descriptions |",
+    "| `MCP_BROKER_ALLOWED_ORIGINS` | unset | comma-separated browser origins for `/<slot>/mcp` |",
+    "| `MCP_BROKER_TLS_CERT` / `_KEY` | unset | PEM paths; both set means HTTPS and WSS |",
+    "| `MCP_BROKER_PROTOCOL` | auto | force `http` or `https` |",
+    "| `MCP_BROKER_WWW_DIR` | unset | serve this directory at `/` |",
+    "| `MCP_BROKER_BUNDLE_DIR` | unset | serve this directory at `/bundle` |",
+    "",
+    "Environment variables win over the config file. Paths in env vars resolve",
+    "against the working directory; paths in the config file resolve against the",
+    "config file's own directory.",
+    "",
+    "## 6. Verifying the wiring",
+    "",
+    "From inside the host, the aggregated introspection tools are named",
+    "`_broker-broker_info`, `_broker-providers_list`, `_broker-provider_status`,",
+    "`_broker-broker_guide` and `_broker-broker_diagnose`. If you can see those, the",
+    "bridge works and `_all` is alive. If you can see nothing else, no provider has",
+    "opted into the aggregate: call `_broker-broker_diagnose` and it will say so.",
+].join("\n");
+
+// ---------------------------------------------------------------------------
+// deploy
+// ---------------------------------------------------------------------------
+
+const GUIDE_DEPLOY = [
+    "# Deploying the broker",
+    "",
+    "## 1. Two ways to run it",
+    "",
+    "**As a process.** `npx @cyanmycelium/mcp-broker`, configured by",
+    "`.mcp-broker/config.json` and `MCP_BROKER_*` environment variables. Choose this",
+    "when the broker is infrastructure: a host entry, a container, a service.",
+    "",
+    "**As a library.** Build a tunnel and start it inside your own process. Choose",
+    "this when your application already owns the port, or when it hosts MCP servers",
+    "itself and you want them served without a WebSocket round trip.",
+    "",
+    "```ts",
+    'import { WsTunnelBuilder } from "@cyanmycelium/mcp-broker";',
+    "",
+    "const tunnel = new WsTunnelBuilder()",
+    "    .withPort(3000)",
+    '    .withHost("127.0.0.1")',
+    '    .withAllowedOrigins(["http://localhost:5173"])',
+    '    .withStaticMount("/", "/abs/path/to/www")',
+    "    .build();",
+    "",
+    "await tunnel.start();",
+    "// ... later",
+    "await tunnel.stop();",
+    "```",
+    "",
+    "An MCP server living in the same process skips the network entirely:",
+    "",
+    "```ts",
+    'import { LoopbackTransport } from "@cyanmycelium/mcp-core";',
+    "",
+    "const [serverEnd, clientEnd] = LoopbackTransport.createPair();",
+    "const server = new McpServerBuilder().withTransport(serverEnd).register(/* ... */).build();",
+    "await server.start();",
+    'tunnel.registerLoopbackProvider("in-process", clientEnd);',
+    "```",
+    "",
+    "A loopback slot outranks a WebSocket provider of the same name: the WebSocket",
+    'one is refused with `Provider "<n>" is reserved by the broker`.',
+    "",
+    "## 2. What `start()` does, in order",
+    "",
+    "1. Creates the HTTP(S) server and attaches the WebSocket server.",
+    "2. Binds the port.",
+    "3. Starts the provider heartbeat and the request-timeout sweep, both on",
+    "   `unref`'d timers so they never hold a process open.",
+    "4. Registers the `_all` aggregate slot.",
+    "5. Wires and connects every configured upstream (`stdioUpstreams`, `mcpServers`,",
+    "   `mcpbBundles`). Upstreams marked `aggregate` join `_all` when they open.",
+    "6. Attaches the stdio bridge, if configured, and resumes stdin.",
+    "7. Starts the embedded `_broker` server and adds it to `_all`.",
+    "",
+    "Step 4 before step 6 is what makes `_all` a safe stdio bridge target: the slot",
+    "exists before the host's first byte arrives. Nothing in this sequence waits for",
+    "a WebSocket provider, because none can exist yet.",
+    "",
+    "`start()` **rejects** on a listen failure, and the rejection names the port, the",
+    "one-broker-per-port rule and the URL to attach to the broker already holding it.",
+    "Await it and catch it: `void tunnel.start()` turns that into an unhandled",
+    "rejection. The original errno is preserved as `err.cause`.",
+    "",
+    "## 3. Topologies",
+    "",
+    "**Browser app plus broker.** The broker serves the page from a static mount and",
+    "the page publishes a provider over WebSocket. Needs `allowedOrigins` for the",
+    "page's own origin if the page is also an MCP client, and needs provider auth",
+    "OFF, because a browser cannot present the provider secret.",
+    "",
+    "**Stdio host plus broker plus browser provider.** The host launches the broker",
+    "pinned to `_all`; the human opens the page later; `_all` pushes",
+    "`list_changed` and the tools appear. This is the topology `broker://guide/host-config`",
+    "is written for.",
+    "",
+    "**Broker in front of remote MCP servers.** `mcpServers[]` entries: the broker",
+    "dials out over Streamable HTTP, SSE or WebSocket and republishes each as a slot.",
+    "Aggregated into `_all` by default.",
+    "",
+    "**Broker running signed bundles.** `mcpbBundles[]` entries: each `.mcpb` is a ZIP",
+    "with a manifest, signature-verified against a trusted public key before being",
+    "unpacked and spawned as a stdio upstream. A bundle that fails verification is",
+    "skipped and never spawned. Aggregated into `_all` by default.",
+    "",
+    "## 4. Configuration",
+    "",
+    "The CLI reads `.mcp-broker/config.json` (or `MCP_BROKER_CONFIG`). Environment",
+    "variables win over the file. Relative paths in the file resolve against the",
+    "file's directory; relative paths in env vars resolve against the working",
+    "directory.",
+    "",
+    "```json",
+    "{",
+    '    "port": 3000,',
+    '    "host": "127.0.0.1",',
+    '    "allowedOrigins": ["http://localhost:3000"],',
+    '    "stdioProvider": "_all",',
+    '    "www": { "mounts": [{ "urlPrefix": "/", "dir": "./www" }] },',
+    '    "stdioUpstreams": [',
+    '        { "name": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"], "aggregate": true }',
+    "    ],",
+    '    "mcpServers": [{ "name": "geo", "url": "https://geo.example.com/mcp" }]',
+    "}",
+    "```",
+    "",
+    "Note the asymmetry, it is real and it bites: a `stdioUpstreams` entry is NOT",
+    'aggregated unless you write `"aggregate": true`, while `mcpServers` and',
+    '`mcpbBundles` entries ARE aggregated unless you write `"aggregate": false`.',
+    "",
+    "All six `paths.*` keys are read by the CLI, as `env ?? config ?? default`. One",
+    "key is still library-only: `brokerName` is a valid config key and `WsTunnel`",
+    "honors it, but `WsTunnelBuilder` has no `withBrokerName()`, so the CLI cannot",
+    "forward it and setting it in the file changes nothing. `enableBrokerProvider`",
+    "and `enableAggregateProvider` are `IWsTunnelOptions` fields only, not config",
+    "keys at all. Confirm the effective values with `broker_info` rather than",
+    "assuming the file won.",
+    "",
+    "## 5. Static files",
+    "",
+    "Mounts are matched longest-prefix-first and JSON-RPC routes always win over",
+    "them, so a slot named like a directory shadows that directory. Directory",
+    "requests serve `index.html`. Paths escaping the mount are refused with 403.",
+    "`MCP_BROKER_WWW_DIR` is a shortcut for a mount at `/`, `MCP_BROKER_BUNDLE_DIR`",
+    "for one at `/bundle`; a directory that does not exist is skipped with a warning",
+    "rather than failing startup.",
+    "",
+    "## 6. TLS",
+    "",
+    "Setting both a certificate and a key switches the whole server to HTTPS and WSS",
+    "at once. There is no mixed mode: providers then connect with `wss://` and",
+    "clients with `https://`, and browser origins in `allowedOrigins` must be spelled",
+    "with `https://`. The files are read synchronously when the tunnel is built, so a",
+    "wrong path throws before the port is bound.",
+    "",
+    "## 7. Shutdown",
+    "",
+    "`stop()` tears down in the reverse order of `start()`: the embedded broker",
+    "server first, then the aggregate, then the stdio bridge, then every session,",
+    "client socket, provider socket and upstream, then the heartbeat and",
+    "request-timeout timers, then the listener. It resolves when the HTTP server is",
+    "fully closed, and a second `stop()` is silent rather than an error. Call it",
+    "before your process exits so providers see a clean close rather than a dropped",
+    "connection.",
+].join("\n");
+
+// ---------------------------------------------------------------------------
+// troubleshooting
+// ---------------------------------------------------------------------------
+
+const GUIDE_TROUBLESHOOTING = [
+    "# Troubleshooting",
+    "",
+    "Call `broker_diagnose()` first. It reads the live state and names the problems",
+    "it can prove, each with a fix. This page is the reference behind it, and covers",
+    "the failures the broker cannot see from the inside.",
+    "",
+    "## Symptom table",
+    "",
+    "| symptom | cause | fix |",
+    "|---|---|---|",
+    "| Client hangs forever on `initialize`, and the provider shows connected | transport / path mismatch: a MultiplexTransport on `/provider/<name>` | move the provider to `ws://<host>/providers`, or switch it to `DirectTransport` on `/provider/<name>` |",
+    "| Provider socket is open, but the slot never appears in `providers_list` | transport / path mismatch the other way: a DirectTransport on `/providers` | move it to `ws://<host>/provider/<name>`, or switch it to `MultiplexTransport` |",
+    "| Provider connects to `/providers/<name>` and nothing works | that path is neither endpoint: it is accepted as a CLIENT on a slot named `providers/<name>` | drop the name from the URL for multiplex, or add `/provider/` for a dedicated socket |",
+    "| WebSocket upgrade refused with HTTP 400 before it opens | the path cannot work: bare `/provider` (no slot name) or `/provider/a/b` (more than one segment) | append one slot name; percent-encode a `/` inside it. The 400 body is the full diagnosis; a browser sees only a bare `error` event, so read the broker log |",
+    "| Socket opens, then closes immediately with 1008 naming DirectTransport or MultiplexTransport | the broker detected the transport/path mismatch on your first frame | apply either correction the reason names; do not reconnect unchanged |",
+    "| WebSocket closes with 1008 `already connected` right after a page reload | a stale socket still holds the slot | release on `pagehide`; a dead holder is reaped within one heartbeat interval (default 30s), so retry rather than restart |",
+    "| MCP host reports `Connection closed` with no cause | a second broker could not bind the port | one broker per port; do not spawn one per host entry. `EADDRINUSE` is in the host's `mcp-server-<name>.log` |",
+    "| HTTP 403 `invalid_origin` from a page the broker itself serves | a static mount does not exempt the origin it serves | set `allowedOrigins` (or `MCP_BROKER_ALLOWED_ORIGINS`) to that exact origin, scheme and port included |",
+    '| `Provider "<slot>" not connected` at host start | ordering: the host starts before any provider exists | point `MCP_BROKER_STDIO_PROVIDER` at `_all` |',
+    "| Tool list is stale and never refreshes | a remote upstream's server-to-client stream dropped and is not reopened | restart the broker; the slot keeps answering requests, which is why nothing looks broken |",
+    "| `_all` shows only `_broker-*` tools | no provider opted into the aggregate, or the opt-in shape this broker honors differs from the one the provider sent | see the aggregate opt-in section in `broker://guide/publish-provider`, and never assume an opt-in took: verify with `tools/list` on `_all` |",
+    "| Host's tool list goes empty after enabling authorization | the stdio bridge reaches `_all` anonymously | grant the anonymous subject, or stop using the bridge for authorized deployments |",
+    "| Browser provider gets a bare `error` event and never connects | provider auth is on; a browser cannot send the required header | run without a provider secret, or authenticate in a reverse proxy |",
+    "| `-32601 Method not found` on `_all` for `resources/list` | `_all` covers tools and prompts only | connect to the provider's own slot for resources |",
+    "| `-32602 Unknown aggregated tool` on a name you built yourself | prefixed names are capped, hashed and de-duplicated | re-run `tools/list` and pass the returned name back verbatim |",
+    "",
+    "## The transport/path mismatch, in detail",
+    "",
+    "This one deserves its own section because it produces the least evidence.",
+    "",
+    "The broker refuses both directions on the first frame, answering in the framing",
+    "the peer can decode and closing with `1008` and a reason naming both",
+    "corrections. That covers the common case. It cannot cover a provider that",
+    "connects and sends nothing, and it does not exist in brokers before 1.3.0, so",
+    "the manual diagnosis below is still what you fall back to.",
+    "",
+    "`DirectTransport` speaks plain JSON-RPC; `MultiplexTransport` speaks",
+    "`{ provider, payload }` envelopes. The broker decides which language to speak on",
+    "a socket from the URL that socket connected to, not from what arrives on it.",
+    "",
+    "- Slot-scoped path `/provider/<name>`: the broker registers the slot from the",
+    "  URL at connect time and then writes plain frames. A multiplex provider on that",
+    "  path shows `connected: true` while silently discarding everything the broker",
+    "  sends, because it is not an envelope.",
+    "- Multiplex path `/providers`: the broker learns slot names from envelopes only.",
+    "  A plain frame decodes to nothing and is dropped, so no slot is ever created.",
+    "",
+    "**How to confirm it in ten seconds.** Call",
+    '`provider_status({ name: "<slot>" })` while a client request is outstanding:',
+    "",
+    '- `connected: true`, `transport: "ws"`, `pendingCount` > 0 and never falling:',
+    "  a multiplex provider is sitting on the slot-scoped path. This is the case.",
+    "- the slot is absent from `providers_list` entirely while your socket is open:",
+    "  a direct provider is sitting on the multiplex path.",
+    "",
+    "`broker_diagnose` runs exactly these two checks for you.",
+    "",
+    "## The slot is wedged after a crash",
+    "",
+    "A slot is occupied while the incumbent socket is `readyState === OPEN`, and a",
+    "socket killed without a close frame stays OPEN until the OS TCP keepalive",
+    "expires, which is hours. The heartbeat is what bounds that: every provider",
+    "socket is pinged every `providerHeartbeatIntervalMs` (default 30000), and one",
+    "that misses a full interval is terminated and its slot freed. So the wedge",
+    "lasts one interval, not a restart.",
+    "",
+    "If it lasts longer, check the three things that disable the recovery:",
+    "",
+    "- `providerHeartbeatIntervalMs: 0` turns the heartbeat off entirely. With no",
+    "  liveness evidence the broker refuses every takeover, by design.",
+    '- `providerTakeover: "reject"` never hands a live slot over, whatever the',
+    "  heartbeat says.",
+    "- The incumbent is answering pings but not serving. An RFC 6455 pong comes from",
+    "  the network stack, so a throttled or wedged JS thread still looks alive. The",
+    "  request timeout below is what catches that.",
+    "",
+    "The broker prints the reason it refused a takeover on every 1008, including",
+    "which of these applies. Prevention is still cheaper: release explicitly on",
+    "`pagehide` in a browser and on `SIGTERM` / `SIGINT` in a process.",
+    "",
+    "## Requests that never come back",
+    "",
+    "A pending entry is released by a matching response, by the provider",
+    "disconnecting, by the caller's own connection closing, or by",
+    "`providerRequestTimeoutMs` expiring (default 60000; `0` disables it). On expiry",
+    'the caller gets `-32000 Provider "<name>" did not respond within <ms>ms`,',
+    "addressed to its own request id, and the broker logs the three usual causes.",
+    "",
+    "So a request that hangs *forever* now means either the timeout is disabled or",
+    "the request never reached a provider at all, which is the transport/path",
+    "mismatch above. A request that fails at the deadline means the provider is",
+    "connected and not answering: the ordinary case is a throttled background browser",
+    "tab. `pendingCount` in `provider_status` is the number of requests in flight,",
+    "and one that only grows is the signal. Raise the timeout only if you host",
+    "genuinely long-running tools.",
+    "",
+    "## Sessions outliving their clients",
+    "",
+    "Streamable HTTP and SSE sessions do not expire. A client that closes its tab",
+    "without sending `DELETE /<slot>/mcp` leaves its session alive, and every",
+    "notification the provider broadcasts is queued into it, without bound.",
+    "",
+    "The broker cannot tell a live session from an abandoned one, so no single",
+    "reading proves a leak. `sessionCount` in `provider_status` growing monotonically",
+    "across a run, and never falling when clients go away, is the signal. Note that",
+    "`clientCount` counts raw WebSocket clients only: a perfectly healthy HTTP client",
+    "shows as `clientCount: 0, sessionCount: 1`. Send the DELETE when a client is",
+    "done; restart the broker if the count is already large.",
+    "",
+    "## Reading the console",
+    "",
+    "The broker prints one line per accepted WebSocket upgrade, naming the path, the",
+    "role the router assigned (`dedicated-provider`, `multiplex-provider` or",
+    "`client`) and the slot it landed on. A provider URL that came out as",
+    "`role=client` is the mismatch, caught for free. In stdio mode every log goes to",
+    "stderr, so look in the host's `mcp-server-<name>.log`, never on stdout.",
+    "",
+    "Do not read silence as success or as failure. Client sessions, routed frames and",
+    "provider replies are not logged at all. `providers_list` and `broker_diagnose`",
+    "are the ground truth for what is actually connected.",
+].join("\n");
+
+// ---------------------------------------------------------------------------
+// Catalog
+// ---------------------------------------------------------------------------
+
+/**
+ * Every guide page, in the order an agent should meet them: the index first,
+ * then the two integration directions, then deployment, then the failure
+ * reference.
+ */
+export const BROKER_GUIDES: readonly IBrokerGuide[] = [
+    {
+        topic: "index",
+        uri: `${BROKER_GUIDE_URI_PREFIX}index`,
+        title: "Guide index",
+        summary: "What the broker is, the transport pairing rule, and which page to read next.",
+        content: GUIDE_INDEX,
+    },
+    {
+        topic: "publish-provider",
+        uri: `${BROKER_GUIDE_URI_PREFIX}publish-provider`,
+        title: "Publish a provider",
+        summary: "Put an MCP server into a slot: the transport/path pairing rule, the aggregate opt-in, the lifecycle, browser limits.",
+        content: GUIDE_PUBLISH_PROVIDER,
+    },
+    {
+        topic: "connect-client",
+        uri: `${BROKER_GUIDE_URI_PREFIX}connect-client`,
+        title: "Connect a client",
+        summary: "Reach a slot: the four client transports, the reserved `_broker` and `_all` slots, origins, authorization, error codes.",
+        content: GUIDE_CONNECT_CLIENT,
+    },
+    {
+        topic: "host-config",
+        uri: `${BROKER_GUIDE_URI_PREFIX}host-config`,
+        title: "MCP host configuration",
+        summary: "Wire Claude Desktop or another stdio host: why the bridge must target `_all`, the recipe, the one-broker-per-port rule.",
+        content: GUIDE_HOST_CONFIG,
+    },
+    {
+        topic: "deploy",
+        uri: `${BROKER_GUIDE_URI_PREFIX}deploy`,
+        title: "Deploy the broker",
+        summary: "Embed as a library or run as a process: startup ordering, topologies, configuration, static files, TLS, shutdown.",
+        content: GUIDE_DEPLOY,
+    },
+    {
+        topic: "troubleshooting",
+        uri: `${BROKER_GUIDE_URI_PREFIX}troubleshooting`,
+        title: "Troubleshooting",
+        summary: "Symptom to cause to fix, starting with the silent failures that produce no log line anywhere.",
+        content: GUIDE_TROUBLESHOOTING,
+    },
+];
+
+/** Every topic id, in catalog order. */
+export const BROKER_GUIDE_TOPICS: readonly BrokerGuideTopic[] = BROKER_GUIDES.map((g) => g.topic);
+
+/** MIME type every guide page is served with. */
+export const BROKER_GUIDE_MIME_TYPE = "text/markdown";
+
+/** Builds the canonical resource URI for a topic. */
+export function brokerGuideUri(topic: BrokerGuideTopic): string {
+    return `${BROKER_GUIDE_URI_PREFIX}${topic}`;
+}
+
+/** Looks a guide page up by topic id. `undefined` when the topic is unknown. */
+export function brokerGuide(topic: string): IBrokerGuide | undefined {
+    return BROKER_GUIDES.find((g) => g.topic === topic);
+}
+
+/**
+ * Extracts the topic from a `broker://guide/<topic>` URI, or `undefined` when
+ * the URI is not a guide URI or names a topic that does not exist.
+ *
+ * Percent-encoding is decoded so `broker://guide/publish%2Dprovider` resolves,
+ * and a decode failure is treated as "not a guide URI" rather than throwing:
+ * the URI comes off the wire.
+ */
+export function brokerGuideTopicFromUri(uri: string): BrokerGuideTopic | undefined {
+    if (!uri.startsWith(BROKER_GUIDE_URI_PREFIX)) return undefined;
+    const raw = uri.slice(BROKER_GUIDE_URI_PREFIX.length);
+    if (!raw || raw.includes("/")) return undefined;
+    let decoded: string;
+    try {
+        decoded = decodeURIComponent(raw);
+    } catch {
+        return undefined;
+    }
+    return brokerGuide(decoded)?.topic;
+}
+
+/**
+ * The index rendered as data rather than prose: one entry per page, for a
+ * client that would rather plan its reads than parse a Markdown table.
+ */
+export function brokerGuideIndex(): Array<{ topic: BrokerGuideTopic; uri: string; title: string; summary: string }> {
+    return BROKER_GUIDES.map(({ topic, uri, title, summary }) => ({ topic, uri, title, summary }));
+}