@cyanmycelium/mcp-broker 1.0.1 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (188) hide show
  1. package/.mcp-broker.example/README.md +3 -3
  2. package/README.md +6 -2
  3. package/dist/bin.d.ts +0 -1
  4. package/dist/bin.js +176 -253
  5. package/dist/bin.js.map +1 -1
  6. package/dist/chunk-FTDKH2C4.js +3670 -0
  7. package/dist/chunk-FTDKH2C4.js.map +1 -0
  8. package/dist/{broker/grammars → grammars}/claude/en.json +1 -1
  9. package/dist/{broker/grammars → grammars}/claude/fr.json +1 -1
  10. package/dist/index.d.ts +1790 -22
  11. package/dist/index.js +2 -18
  12. package/dist/index.js.map +1 -1
  13. package/package.json +9 -7
  14. package/scripts/copy-assets.mjs +16 -10
  15. package/scripts/gen-cert.mjs +5 -5
  16. package/scripts/pack-mcpb.mjs +5 -5
  17. package/scripts/sign-bundle.mjs +6 -6
  18. package/src/auth/auth.config.ts +3 -3
  19. package/src/auth/auth.types.ts +34 -59
  20. package/src/auth/http.auth.ts +18 -22
  21. package/src/auth/index.ts +12 -12
  22. package/src/auth/jwt.validator.ts +3 -3
  23. package/src/auth/provider.auth.ts +1 -1
  24. package/src/auth/resource.metadata.ts +14 -21
  25. package/src/authorization/audit.ts +2 -2
  26. package/src/authorization/capability.classifier.ts +1 -1
  27. package/src/authorization/index.ts +13 -13
  28. package/src/authorization/policy.engine.ts +3 -3
  29. package/src/authorization/policy.types.ts +1 -1
  30. package/src/authorization/runtime.ts +5 -5
  31. package/src/authorization/slot.resource.ts +1 -1
  32. package/src/authorization/subject.mapper.ts +1 -1
  33. package/src/bin.ts +38 -8
  34. package/src/broker/adapters/broker.adapter.info.ts +1 -1
  35. package/src/broker/adapters/broker.adapter.providers.ts +1 -1
  36. package/src/broker/aggregate/aggregate.catalog.ts +1 -1
  37. package/src/broker/aggregate/aggregate.server.ts +7 -7
  38. package/src/broker/aggregate/provider.client.session.ts +2 -2
  39. package/src/broker/behaviors/broker.behavior.info.ts +3 -3
  40. package/src/broker/behaviors/broker.behavior.providers.ts +5 -5
  41. package/src/broker/broker.grammars.ts +9 -9
  42. package/src/broker/broker.server.ts +6 -6
  43. package/src/broker/grammars/claude/en.json +1 -1
  44. package/src/broker/grammars/claude/fr.json +1 -1
  45. package/src/broker/index.ts +9 -9
  46. package/src/config.ts +25 -3
  47. package/src/index.ts +24 -24
  48. package/src/{mcpb.loader.ts → mcpb/mcpb.loader.ts} +11 -11
  49. package/src/{mcpb.unzip.ts → mcpb/mcpb.unzip.ts} +2 -2
  50. package/src/remote.transports.ts +3 -3
  51. package/src/remote.upstream.ts +3 -3
  52. package/src/stdio.upstream.ts +2 -2
  53. package/src/upstream.ts +2 -2
  54. package/src/ws/ws.interfaces.ts +357 -0
  55. package/src/{ws.tunnel.builder.ts → ws/ws.tunnel.builder.ts} +28 -5
  56. package/src/{ws.tunnel.ts → ws/ws.tunnel.ts} +231 -467
  57. package/web/README.md +3 -3
  58. package/web/broker-self-mcp.html +9 -9
  59. package/web/css/styles.css +1 -1
  60. package/web/demos/DemoPlaceholder.html +6 -6
  61. package/web/demos/broker-explorer/css/app.css +1 -1
  62. package/web/demos/broker-explorer/index.html +2 -2
  63. package/web/demos/broker-explorer/js/app.js +4 -4
  64. package/web/demos/broker-explorer/js/mcp-ws-client.js +2 -2
  65. package/web/demos/oauth-lab/README.md +26 -0
  66. package/web/demos/oauth-lab/config.json +1 -0
  67. package/web/demos/oauth-lab/js/app.js +40 -16
  68. package/web/demos/oauth-lab/server/smoke-test.mjs +57 -10
  69. package/web/demos/provider-tunnel/css/app.css +1 -1
  70. package/web/demos/provider-tunnel/index.html +3 -3
  71. package/web/demos/provider-tunnel/js/app.js +10 -10
  72. package/web/demos/provider-tunnel/js/toolbox-server.js +5 -5
  73. package/web/index.html +11 -11
  74. package/web/js/lib/broker-tunnel.js +12 -12
  75. package/dist/auth/auth.config.d.ts +0 -40
  76. package/dist/auth/auth.config.js +0 -62
  77. package/dist/auth/auth.config.js.map +0 -1
  78. package/dist/auth/auth.types.d.ts +0 -119
  79. package/dist/auth/auth.types.js +0 -38
  80. package/dist/auth/auth.types.js.map +0 -1
  81. package/dist/auth/http.auth.d.ts +0 -51
  82. package/dist/auth/http.auth.js +0 -121
  83. package/dist/auth/http.auth.js.map +0 -1
  84. package/dist/auth/index.d.ts +0 -16
  85. package/dist/auth/index.js +0 -12
  86. package/dist/auth/index.js.map +0 -1
  87. package/dist/auth/jwt.validator.d.ts +0 -35
  88. package/dist/auth/jwt.validator.js +0 -46
  89. package/dist/auth/jwt.validator.js.map +0 -1
  90. package/dist/auth/provider.auth.d.ts +0 -51
  91. package/dist/auth/provider.auth.js +0 -80
  92. package/dist/auth/provider.auth.js.map +0 -1
  93. package/dist/auth/resource.metadata.d.ts +0 -32
  94. package/dist/auth/resource.metadata.js +0 -26
  95. package/dist/auth/resource.metadata.js.map +0 -1
  96. package/dist/authorization/audit.d.ts +0 -14
  97. package/dist/authorization/audit.js +0 -20
  98. package/dist/authorization/audit.js.map +0 -1
  99. package/dist/authorization/capability.classifier.d.ts +0 -30
  100. package/dist/authorization/capability.classifier.js +0 -85
  101. package/dist/authorization/capability.classifier.js.map +0 -1
  102. package/dist/authorization/index.d.ts +0 -13
  103. package/dist/authorization/index.js +0 -8
  104. package/dist/authorization/index.js.map +0 -1
  105. package/dist/authorization/policy.engine.d.ts +0 -11
  106. package/dist/authorization/policy.engine.js +0 -192
  107. package/dist/authorization/policy.engine.js.map +0 -1
  108. package/dist/authorization/policy.types.d.ts +0 -92
  109. package/dist/authorization/policy.types.js +0 -2
  110. package/dist/authorization/policy.types.js.map +0 -1
  111. package/dist/authorization/resource.path.d.ts +0 -27
  112. package/dist/authorization/resource.path.js +0 -122
  113. package/dist/authorization/resource.path.js.map +0 -1
  114. package/dist/authorization/runtime.d.ts +0 -22
  115. package/dist/authorization/runtime.js +0 -34
  116. package/dist/authorization/runtime.js.map +0 -1
  117. package/dist/authorization/slot.resource.d.ts +0 -12
  118. package/dist/authorization/slot.resource.js +0 -41
  119. package/dist/authorization/slot.resource.js.map +0 -1
  120. package/dist/authorization/subject.mapper.d.ts +0 -15
  121. package/dist/authorization/subject.mapper.js +0 -67
  122. package/dist/authorization/subject.mapper.js.map +0 -1
  123. package/dist/broker/adapters/broker.adapter.info.d.ts +0 -16
  124. package/dist/broker/adapters/broker.adapter.info.js +0 -43
  125. package/dist/broker/adapters/broker.adapter.info.js.map +0 -1
  126. package/dist/broker/adapters/broker.adapter.providers.d.ts +0 -18
  127. package/dist/broker/adapters/broker.adapter.providers.js +0 -61
  128. package/dist/broker/adapters/broker.adapter.providers.js.map +0 -1
  129. package/dist/broker/aggregate/aggregate.catalog.d.ts +0 -66
  130. package/dist/broker/aggregate/aggregate.catalog.js +0 -119
  131. package/dist/broker/aggregate/aggregate.catalog.js.map +0 -1
  132. package/dist/broker/aggregate/aggregate.server.d.ts +0 -66
  133. package/dist/broker/aggregate/aggregate.server.js +0 -257
  134. package/dist/broker/aggregate/aggregate.server.js.map +0 -1
  135. package/dist/broker/aggregate/provider.client.session.d.ts +0 -52
  136. package/dist/broker/aggregate/provider.client.session.js +0 -140
  137. package/dist/broker/aggregate/provider.client.session.js.map +0 -1
  138. package/dist/broker/behaviors/broker.behavior.info.d.ts +0 -15
  139. package/dist/broker/behaviors/broker.behavior.info.js +0 -41
  140. package/dist/broker/behaviors/broker.behavior.info.js.map +0 -1
  141. package/dist/broker/behaviors/broker.behavior.providers.d.ts +0 -19
  142. package/dist/broker/behaviors/broker.behavior.providers.js +0 -69
  143. package/dist/broker/behaviors/broker.behavior.providers.js.map +0 -1
  144. package/dist/broker/broker.context.d.ts +0 -63
  145. package/dist/broker/broker.context.js +0 -2
  146. package/dist/broker/broker.context.js.map +0 -1
  147. package/dist/broker/broker.grammars.d.ts +0 -132
  148. package/dist/broker/broker.grammars.js +0 -229
  149. package/dist/broker/broker.grammars.js.map +0 -1
  150. package/dist/broker/broker.server.d.ts +0 -68
  151. package/dist/broker/broker.server.js +0 -73
  152. package/dist/broker/broker.server.js.map +0 -1
  153. package/dist/broker/index.d.ts +0 -9
  154. package/dist/broker/index.js +0 -7
  155. package/dist/broker/index.js.map +0 -1
  156. package/dist/config.d.ts +0 -182
  157. package/dist/config.js +0 -61
  158. package/dist/config.js.map +0 -1
  159. package/dist/mcpb.loader.d.ts +0 -26
  160. package/dist/mcpb.loader.js +0 -161
  161. package/dist/mcpb.loader.js.map +0 -1
  162. package/dist/mcpb.unzip.d.ts +0 -6
  163. package/dist/mcpb.unzip.js +0 -95
  164. package/dist/mcpb.unzip.js.map +0 -1
  165. package/dist/remote.transports.d.ts +0 -18
  166. package/dist/remote.transports.js +0 -297
  167. package/dist/remote.transports.js.map +0 -1
  168. package/dist/remote.upstream.d.ts +0 -38
  169. package/dist/remote.upstream.js +0 -52
  170. package/dist/remote.upstream.js.map +0 -1
  171. package/dist/stdio.upstream.d.ts +0 -47
  172. package/dist/stdio.upstream.js +0 -85
  173. package/dist/stdio.upstream.js.map +0 -1
  174. package/dist/upstream.d.ts +0 -35
  175. package/dist/upstream.js +0 -2
  176. package/dist/upstream.js.map +0 -1
  177. package/dist/version.d.ts +0 -2
  178. package/dist/version.js +0 -9
  179. package/dist/version.js.map +0 -1
  180. package/dist/ws.tunnel.builder.d.ts +0 -176
  181. package/dist/ws.tunnel.builder.js +0 -271
  182. package/dist/ws.tunnel.builder.js.map +0 -1
  183. package/dist/ws.tunnel.d.ts +0 -455
  184. package/dist/ws.tunnel.js +0 -1425
  185. package/dist/ws.tunnel.js.map +0 -1
  186. /package/dist/{broker/grammars → grammars}/default/en.json +0 -0
  187. /package/dist/{broker/grammars → grammars}/default/fr.json +0 -0
  188. /package/dist/{broker/grammars → grammars}/default/zh.json +0 -0
@@ -5,23 +5,27 @@ import * as nodePath from "path";
5
5
  import { randomUUID } from "crypto";
6
6
  import type { IncomingMessage, ServerResponse } from "http";
7
7
  import { WebSocket, WebSocketServer, type VerifyClientCallbackAsync } from "ws";
8
- import type { GrammarResolverOptions, IMessageTransport, IMcpServer } from "@cyanmycelium/mcp-core";
9
- import { StdioUpstream, type IStdioUpstreamConfig } from "./stdio.upstream.js";
10
- import { RemoteUpstream, type IRemoteUpstreamConfig } from "./remote.upstream.js";
11
- import type { IUpstream } from "./upstream.js";
12
- import { startBrokerServer, BROKER_PROVIDER_NAME } from "./broker/index.js";
13
- import type { IBrokerContext, IBrokerProviderInfo, BrokerProviderTransport } from "./broker/index.js";
14
- import { AggregateServer } from "./broker/aggregate/aggregate.server.js";
8
+ import type { IMessageTransport, IMcpServer } from "@cyanmycelium/mcp-core";
9
+ import { StdioTransport, StreamableHttpEndpoint } from "@cyanmycelium/mcp-core/node";
10
+ // The broker is itself a provider: it publishes its own `_broker` and `_all`
11
+ // slots: so sharing the provider package's wire contract is the natural way to
12
+ // keep one definition of the envelope rather than two that drift.
13
+ import { decodeEnvelope, encodeEnvelope, encodeErrorEnvelope, envelopeFrame, TunnelErrorCodes } from "@cyanmycelium/mcp-broker-provider/protocol";
14
+ import { StdioUpstream } from "../stdio.upstream";
15
+ import { RemoteUpstream } from "../remote.upstream";
16
+ import type { IUpstream } from "../upstream";
17
+ import { startBrokerServer, BROKER_PROVIDER_NAME } from "../broker/index";
18
+ import type { IBrokerContext, IBrokerProviderInfo, BrokerProviderTransport } from "../broker/index";
19
+ import { AggregateServer } from "../broker/aggregate/aggregate.server";
15
20
  import {
16
21
  HttpAuthGuard,
17
22
  AuthError,
18
23
  normalizeProviderAuthentication,
19
24
  providerMayPublish,
20
- type IResolvedAuth,
21
25
  type IProviderAuthenticator,
22
26
  type IPrincipal,
23
27
  type IProviderPrincipal,
24
- } from "./auth/index.js";
28
+ } from "../auth/index";
25
29
  import {
26
30
  DefaultSlotResourceResolver,
27
31
  SubjectMappingError,
@@ -32,8 +36,9 @@ import {
32
36
  type IPolicyAuthorization,
33
37
  type ResourcePath,
34
38
  type ISlotResourceResolver,
35
- } from "./authorization/index.js";
36
- import { VERSION, PACKAGE_NAME } from "./version.js";
39
+ } from "../authorization/index";
40
+ import { VERSION, PACKAGE_NAME } from "../version";
41
+ import type { AllowedOrigins, IHttpSession, IInternalClient, IProviderState, IWsTunnelOptions, McpEndpointKind } from "./ws.interfaces";
37
42
 
38
43
  // ---------------------------------------------------------------------------
39
44
  // Static-file helpers
@@ -55,293 +60,63 @@ const MIME: Readonly<Record<string, string>> = {
55
60
  };
56
61
 
57
62
  // ---------------------------------------------------------------------------
58
- // Internal types
63
+ // JSON-RPC helpers
59
64
  // ---------------------------------------------------------------------------
60
65
 
61
66
  /**
62
- * Where a JSON-RPC response should be delivered.
63
- * Either a WebSocket socket (raw WS client), an SSE session (legacy MCP/HTTP),
64
- * a held-open HTTP response (Streamable HTTP transport, MCP 2025-03-26),
65
- * the process stdout (stdio transport for Claude Desktop), or an in-process
66
- * internal client (e.g. the aggregate server).
67
- */
68
- type ResponseSink =
69
- | { type: "ws"; socket: WebSocket }
70
- | { type: "sse"; sessionId: string }
71
- | { type: "http"; res: ServerResponse }
72
- | { type: "stdio" }
73
- | { type: "internal"; client: IInternalClient };
74
-
75
- /** The four HTTP client-transport handlers a provider route can resolve to. */
76
- type McpEndpointKind = "mcp-get" | "mcp-post" | "sse-connect" | "sse-message";
77
-
78
- /**
79
- * All mutable state for one named provider slot.
80
- * Created lazily on first client connection; the WebSocket field is set when
81
- * the provider actually connects (and cleared on disconnect).
82
- */
83
- interface IProviderState {
84
- /** The active provider WebSocket, or `null` when the provider is not connected. */
85
- ws: WebSocket | null;
86
- /** Pending JSON-RPC request ids → response sinks waiting for a reply. */
87
- readonly pending: Map<string | number, ResponseSink>;
88
- /** Active legacy SSE sessions (Claude), keyed by session id. */
89
- readonly sseSessions: Map<string, ServerResponse>;
90
- /** Active Streamable HTTP GET streams (MCP Inspector), keyed by session id. */
91
- readonly mcpGetSessions: Map<string, ServerResponse>;
92
- /** Raw WebSocket MCP clients connected to this provider. */
93
- readonly wsClients: Set<WebSocket>;
94
- /** In-process clients (e.g. the aggregate server) attached to this slot. */
95
- readonly internalClients: Set<IInternalClient>;
96
- }
97
-
98
- // ---------------------------------------------------------------------------
99
- // Public types
100
- // ---------------------------------------------------------------------------
101
-
102
- /**
103
- * A single static-file mount: serves the contents of `dir` under `urlPrefix`.
67
+ * The JSON-RPC id a frame is waiting on, or `undefined` when nothing will come
68
+ * back for it: a notification, or something that did not parse.
104
69
  *
105
- * @example
106
- * { urlPrefix: "/", dir: "/absolute/path/to/www" }
107
- * { urlPrefix: "/bundle", dir: "/absolute/path/to/bundle" }
70
+ * `null` is a legal id in an error response, so absence cannot be signalled
71
+ * with it, hence `undefined`.
108
72
  */
109
- export interface IStaticMount {
110
- /** URL prefix that triggers this mount (e.g. `"/"` or `"/bundle"`). */
111
- urlPrefix: string;
112
- /** Absolute path to the directory to serve. */
113
- dir: string;
73
+ function requestIdOf(frame: string): string | number | undefined {
74
+ try {
75
+ const parsed = JSON.parse(frame) as { id?: unknown };
76
+ if (typeof parsed?.id === "string" || typeof parsed?.id === "number") return parsed.id;
77
+ } catch {
78
+ /* not JSON: nothing to route by */
79
+ }
80
+ return undefined;
114
81
  }
115
82
 
116
83
  /**
117
- * In-process client handle for a provider slot — the symmetric counterpart of
118
- * {@link WsTunnel.registerLoopbackProvider}. Lets a component inside the broker
119
- * process (e.g. the aggregate server) issue MCP requests to a provider slot and
120
- * receive both the responses and the provider's broadcast notifications,
121
- * without opening a real network connection.
84
+ * Turns the three shapes an operator may configure into the single predicate
85
+ * the Streamable HTTP endpoint expects.
86
+ *
87
+ * Absent means closed, not open: a browser origin is refused unless it was
88
+ * named. A `RegExp` is reset before each test, because one carrying the `g`
89
+ * flag keeps `lastIndex` between calls and would otherwise accept and refuse
90
+ * the same origin in turn.
122
91
  */
123
- export interface IInternalClient {
124
- /**
125
- * Sends a JSON-RPC message to the provider slot. When the message carries an
126
- * `id`, the matching response is delivered to {@link onMessage}. When the
127
- * provider is not connected, a JSON-RPC error is delivered synchronously.
128
- */
129
- send(message: string): void;
130
- /** Receives responses to this client's requests and the provider's notifications. */
131
- onMessage: ((data: string) => void) | null;
132
- /** Fires when the provider slot loses its connection. */
133
- onClose: (() => void) | null;
134
- /** Detaches this internal client; pending requests are dropped. */
135
- close(): void;
92
+ function originPredicate(allowed: AllowedOrigins | undefined): (origin: string) => boolean {
93
+ if (!allowed) return () => false;
94
+ if (typeof allowed === "function") return allowed;
95
+ if (allowed instanceof RegExp) {
96
+ return (origin) => {
97
+ allowed.lastIndex = 0;
98
+ return allowed.test(origin);
99
+ };
100
+ }
101
+ const exact = new Set(allowed);
102
+ return (origin) => exact.has(origin);
136
103
  }
137
104
 
138
105
  /**
139
- * Configuration options for a {@link WsTunnel} instance.
106
+ * Opens a transport that was handed over closed.
107
+ *
108
+ * `connect` is not part of `IMessageTransport`, because some transports arrive
109
+ * already open, so it is probed for rather than required. This is the same
110
+ * check `McpServer` makes on the transport it is given, and for the same
111
+ * reason: testing for a concrete class would tie the caller to one
112
+ * implementation.
140
113
  */
141
- export interface IWsTunnelOptions {
142
- /** TCP port to listen on. */
143
- port: number;
144
-
145
- /**
146
- * Host/interface to bind to.
147
- * @default "0.0.0.0"
148
- */
149
- host?: string;
150
-
151
- /**
152
- * URL path **prefix** the MCP provider connects to via WebSocket.
153
- * Each provider appends its name: `<providerPath>/<encodedName>`.
154
- * @default "/provider"
155
- */
156
- providerPath?: string;
157
-
158
- /**
159
- * URL path for **multiplexed** provider connections.
160
- * A single WebSocket carries traffic for multiple providers using the
161
- * envelope protocol `{ provider: string, payload: object }`.
162
- * @default "/providers"
163
- */
164
- providersPath?: string;
165
-
166
- /**
167
- * URL path raw WebSocket MCP clients connect to.
168
- * @default "/"
169
- */
170
- clientPath?: string;
171
-
172
- /**
173
- * **Suffix** appended to a provider name for the SSE endpoint.
174
- * Full URL: `/<providerName>/sse`
175
- * @default "/sse"
176
- */
177
- ssePath?: string;
178
-
179
- /**
180
- * **Suffix** appended to a provider name for the legacy SSE POST endpoint.
181
- * Full URL: `/<providerName>/messages`
182
- * @default "/messages"
183
- */
184
- messagesPath?: string;
185
-
186
- /**
187
- * **Suffix** appended to a provider name for the Streamable HTTP endpoint (MCP 2025-03-26).
188
- * Full URL: `/<providerName>/mcp`
189
- * MCP Inspector connects here.
190
- * @default "/mcp"
191
- */
192
- mcpPath?: string;
193
-
194
- /**
195
- * URL path that returns a `{ files: string[] }` JSON listing of every file
196
- * inside the `samples/` subdirectory of the root static mount.
197
- * @default "/__samples_index__"
198
- */
199
- samplesIndexPath?: string;
200
-
201
- /**
202
- * Optional static-file mounts served over plain HTTP.
203
- * Matched by longest URL prefix; directory requests fall back to `index.html`.
204
- */
205
- staticMounts?: IStaticMount[];
206
-
207
- /**
208
- * Stdio upstream providers. Each entry spawns a child process and wires its
209
- * stdin/stdout as an MCP transport. Clients reach the process using its `name`
210
- * directly.
211
- *
212
- * If a WebSocket provider connects with the same name as a stdio upstream, the
213
- * connection is rejected and a warning is logged — stdio takes priority.
214
- * @default undefined — no stdio providers
215
- */
216
- stdioUpstreams?: IStdioUpstreamConfig[];
217
-
218
- /** Remote MCP servers reached by URL, exposed as provider slots. */
219
- remoteUpstreams?: IRemoteUpstreamConfig[];
220
-
221
- /**
222
- * Stdio client transport. When set, the broker reads JSON-RPC from
223
- * `process.stdin` and writes responses to `process.stdout`, bridging an
224
- * external MCP client (e.g. Claude Desktop) to the named provider.
225
- *
226
- * In this mode ALL logging is redirected to stderr so stdout stays clean
227
- * for the JSON-RPC stream.
228
- *
229
- * Claude Desktop config example:
230
- * ```json
231
- * {
232
- * "command": "npx",
233
- * "args": ["-y", "@cyanmycelium/mcp-broker"],
234
- * "env": { "MCP_BROKER_STDIO_PROVIDER": "my-provider" }
235
- * }
236
- * ```
237
- * @default undefined — stdio client transport disabled
238
- */
239
- stdioClient?: { providerName: string };
240
-
241
- /**
242
- * TLS configuration. When provided, the server uses HTTPS and WSS instead of HTTP and WS.
243
- * Both `cert` and `key` must be PEM-encoded strings (file contents, not file paths).
244
- * Use {@link WsTunnelBuilder.withTlsFiles} to load from disk paths.
245
- * @default undefined — plain HTTP/WS
246
- */
247
- tls?: {
248
- /** PEM-encoded TLS certificate. */
249
- cert: string;
250
- /** PEM-encoded private key. */
251
- key: string;
252
- };
253
-
254
- /**
255
- * When `true` (default), the broker exposes itself as an MCP server under the
256
- * reserved slot `_broker`. Tier-1 behaviors (`broker_info`, `providers_list`,
257
- * `provider_status`) become callable at `<host>/_broker/mcp`.
258
- *
259
- * Set to `false` to keep the broker invisible to MCP clients.
260
- * @default true
261
- */
262
- enableBrokerProvider?: boolean;
263
-
264
- /**
265
- * When `true` (default), the broker exposes the reserved slot `_all` — an
266
- * aggregate MCP server that unions the tools and prompts of every provider
267
- * that opted in via the registration handshake. Reachable like any other
268
- * slot (`<host>/_all/mcp`, etc.).
269
- *
270
- * Set to `false` to disable aggregation entirely.
271
- * @default true
272
- */
273
- enableAggregateProvider?: boolean;
274
-
275
- /**
276
- * Logical name reported by `broker_info`. Useful when running multiple
277
- * broker instances and you want to tell them apart from the agent side
278
- * (e.g. `"broker-eu-west"`).
279
- * @default PACKAGE_NAME — `@cyanmycelium/mcp-broker`
280
- */
281
- brokerName?: string;
282
-
283
- /**
284
- * Overrides for the embedded broker server's grammar resolver — passed
285
- * straight through to `mcp-core`'s `grammarResolverFromOptions`. The
286
- * broker installs its own default `localeSource` (reads
287
- * `process.env.MCP_BROKER_LOCALE`); anything you set here wins.
288
- *
289
- * Use this to inject a custom `localeSource` (e.g. read from an HTTP
290
- * header proxied by your transport), enable the optional `versionFrom`
291
- * dimension, or extend the `agents` map with additional LLM families.
292
- */
293
- brokerGrammarResolverOptions?: Partial<GrammarResolverOptions>;
294
-
295
- /**
296
- * Path to a user-supplied grammars directory whose `<userAgent>/<locale>.json`
297
- * files are registered alongside the packaged grammars used by the
298
- * embedded broker server. Typically pointed at `.mcp-broker/grammars/`.
299
- *
300
- * The candidate-chain resolution in `McpServer.initialize`
301
- * (mcp-core@0.3.0) handles cascade across user-agent and locale
302
- * dimensions, so partial files no longer need to be pre-merged with a
303
- * baseline.
304
- */
305
- brokerLocalGrammarsDir?: string;
306
-
307
- /**
308
- * OAuth 2.1 resource-server authorization. When set, every HTTP client
309
- * request to a slot (`/<slot>/mcp`, `/<slot>/sse`, `/<slot>/messages`) must
310
- * carry a valid `Authorization: Bearer` token issued for that slot, and the
311
- * broker publishes Protected Resource Metadata (RFC 9728) under
312
- * `/.well-known/oauth-protected-resource/<slot>/<mcp>`.
313
- *
314
- * When `undefined` (default), the broker performs **no** authentication —
315
- * appropriate only behind a trusted network boundary.
316
- */
317
- auth?: IResolvedAuth;
318
-
319
- /**
320
- * Authenticates **providers** (engines) connecting to `/provider/<slot>` and
321
- * the multiplexed `/providers` socket. Independent of {@link auth} (which
322
- * guards clients): set this to stop strangers from occupying a free slot and
323
- * impersonating the real engine.
324
- *
325
- * When `undefined` (default), provider connections are **not** authenticated.
326
- */
327
- providerAuth?: IProviderAuthenticator;
328
-
329
- /** Hierarchical policy runtime. Absent preserves legacy OAuth behavior. */
330
- authorization?: IPolicyAuthorization;
331
-
332
- /** Slot-to-resource resolver also used for provider namespace restrictions. */
333
- slotResourceResolver?: ISlotResourceResolver;
114
+ function openTransport(transport: IMessageTransport): void {
115
+ if ("connect" in transport && typeof (transport as { connect: unknown }).connect === "function") {
116
+ (transport as { connect(): void }).connect();
117
+ }
334
118
  }
335
119
 
336
- /** @deprecated Use {@link IStaticMount}. */
337
- export type StaticMount = IStaticMount;
338
-
339
- /** @deprecated Use {@link IInternalClient}. */
340
- export type InternalClient = IInternalClient;
341
-
342
- /** @deprecated Use {@link IWsTunnelOptions}. */
343
- export type WsTunnelOptions = IWsTunnelOptions;
344
-
345
120
  // ---------------------------------------------------------------------------
346
121
  // WsTunnel
347
122
  // ---------------------------------------------------------------------------
@@ -401,8 +176,8 @@ export class WsTunnel implements IBrokerContext {
401
176
  /** Provider name that the stdio client transport is bridged to, or null when disabled. */
402
177
  private _stdioClientProvider: string | null = null;
403
178
 
404
- /** Buffered partial line from stdin (stdio client transport). */
405
- private _stdioClientBuffer = "";
179
+ /** mcp-core transport connected to the broker process stdin/stdout. */
180
+ private _stdioClientTransport: StdioTransport | null = null;
406
181
 
407
182
  /** Timestamp of the most recent successful `start()`. */
408
183
  private _startedAt: Date | null = null;
@@ -419,6 +194,9 @@ export class WsTunnel implements IBrokerContext {
419
194
  /** Stable technical-slot to hierarchical-resource mapping. */
420
195
  private readonly _slotResourceResolver: ISlotResourceResolver;
421
196
 
197
+ /** Origin check applied by every slot's Streamable HTTP endpoint. */
198
+ private readonly _allowedOrigins: (origin: string) => boolean;
199
+
422
200
  /** Principal captured at a client's WS upgrade, keyed by the upgrade request. */
423
201
  private readonly _pendingClientPrincipals = new WeakMap<IncomingMessage, IPrincipal>();
424
202
 
@@ -436,6 +214,7 @@ export class WsTunnel implements IBrokerContext {
436
214
  this._options = options;
437
215
  this._authGuard = options.auth ? new HttpAuthGuard(options.auth, options.mcpPath ?? "/mcp") : null;
438
216
  this._providerAuth = options.providerAuth ?? null;
217
+ this._allowedOrigins = originPredicate(options.allowedOrigins);
439
218
  this._authorization = options.authorization ?? options.auth?.authorization ?? null;
440
219
  this._slotResourceResolver =
441
220
  options.slotResourceResolver ?? this._authorization?.slotResourceResolver ?? options.auth?.slotResourceResolver ?? new DefaultSlotResourceResolver();
@@ -523,7 +302,7 @@ export class WsTunnel implements IBrokerContext {
523
302
  transport,
524
303
  connected,
525
304
  clientCount: state.wsClients.size,
526
- sessionCount: state.sseSessions.size + state.mcpGetSessions.size,
305
+ sessionCount: state.sseSessions.size + state.httpSessions.size,
527
306
  pendingCount: state.pending.size,
528
307
  };
529
308
  }
@@ -563,7 +342,7 @@ export class WsTunnel implements IBrokerContext {
563
342
  * broadcast notifications. Used by the aggregate server to fan a single
564
343
  * in-process client out to every aggregated provider.
565
344
  *
566
- * The slot does not need a provider attached yet — `send` returns a
345
+ * The slot does not need a provider attached yet, `send` returns a
567
346
  * JSON-RPC error while the provider is disconnected.
568
347
  */
569
348
  public openInternalClient(providerName: string): IInternalClient {
@@ -621,7 +400,7 @@ export class WsTunnel implements IBrokerContext {
621
400
  get clientCount(): number {
622
401
  let n = 0;
623
402
  for (const s of this._providers.values()) {
624
- n += s.wsClients.size + s.sseSessions.size + s.mcpGetSessions.size;
403
+ n += s.wsClients.size + s.sseSessions.size + s.httpSessions.size;
625
404
  }
626
405
  return n;
627
406
  }
@@ -706,22 +485,19 @@ export class WsTunnel implements IBrokerContext {
706
485
  // stdin carries Claude Desktop's JSON-RPC requests; stdout carries responses.
707
486
  if (this._options.stdioClient) {
708
487
  this._stdioClientProvider = this._options.stdioClient.providerName;
709
- process.stdin.setEncoding("utf8");
710
- process.stdin.on("data", (chunk: string) => {
711
- this._stdioClientBuffer += chunk;
712
- let nl: number;
713
- while ((nl = this._stdioClientBuffer.indexOf("\n")) !== -1) {
714
- const line = this._stdioClientBuffer.slice(0, nl).trim();
715
- this._stdioClientBuffer = this._stdioClientBuffer.slice(nl + 1);
716
- if (line) {
717
- const state = this._getOrCreateProviderState(this._stdioClientProvider!);
718
- this._routeFromStdioClient(state, line);
719
- }
720
- }
721
- });
722
- process.stdin.on("end", () => {
723
- // Client disconnected — nothing to clean up; pending sinks will time out.
724
- });
488
+ const transport = new StdioTransport();
489
+ this._stdioClientTransport = transport;
490
+ transport.onMessage = (data: string): void => {
491
+ const state = this._getOrCreateProviderState(this._stdioClientProvider!);
492
+ this._routeFromStdioClient(state, data);
493
+ };
494
+ transport.onError = (err: Error): void => {
495
+ console.error(`[broker] stdio client transport: ${err.message}`);
496
+ };
497
+ transport.onClose = (): void => {
498
+ // Client disconnected: nothing to clean up; pending sinks will time out.
499
+ };
500
+ transport.connect();
725
501
  }
726
502
 
727
503
  this._startedAt = new Date();
@@ -807,12 +583,21 @@ export class WsTunnel implements IBrokerContext {
807
583
  }
808
584
  }
809
585
 
586
+ this._stdioClientTransport?.close();
587
+ this._stdioClientTransport = null;
588
+ this._stdioClientProvider = null;
589
+
590
+ // Streamable HTTP sessions are torn down by the endpoint that owns them,
591
+ // not by ending their responses here: `closeAll` runs each session's
592
+ // `stop`, which is what empties `httpSessions`.
593
+ await Promise.all([...this._providers.values()].map((state) => state.httpEndpoint?.closeAll() ?? Promise.resolve()));
594
+
810
595
  return new Promise((resolve, reject) => {
811
596
  for (const state of this._providers.values()) {
812
597
  for (const res of state.sseSessions.values()) res.end();
813
598
  state.sseSessions.clear();
814
- for (const res of state.mcpGetSessions.values()) res.end();
815
- state.mcpGetSessions.clear();
599
+ state.httpSessions.clear();
600
+ state.httpEndpoint = null;
816
601
  for (const client of state.wsClients) client.close();
817
602
  state.wsClients.clear();
818
603
  state.ws?.close();
@@ -937,6 +722,15 @@ export class WsTunnel implements IBrokerContext {
937
722
  });
938
723
  }
939
724
 
725
+ /** The JSON-RPC error returned when the slot has nobody behind it. */
726
+ private _notConnectedPayload(providerName: string, frame: string): string {
727
+ return JSON.stringify({
728
+ jsonrpc: "2.0",
729
+ id: requestIdOf(frame) ?? null,
730
+ error: { code: -32000, message: `Provider "${providerName}" not connected` },
731
+ });
732
+ }
733
+
940
734
  // -------------------------------------------------------------------------
941
735
  // HTTP dispatcher
942
736
  // -------------------------------------------------------------------------
@@ -964,7 +758,7 @@ export class WsTunnel implements IBrokerContext {
964
758
  return;
965
759
  }
966
760
 
967
- // Protected Resource Metadata (RFC 9728) — public discovery data, served
761
+ // Protected Resource Metadata (RFC 9728), public discovery data, served
968
762
  // unauthenticated so a client can find the authorization server after a 401.
969
763
  if (this._authGuard && method === "GET") {
970
764
  const metaSlot = this._authGuard.matchMetadataRequest(rawUrl);
@@ -1027,8 +821,8 @@ export class WsTunnel implements IBrokerContext {
1027
821
  const mcpSuffix = (this._options.mcpPath ?? "/mcp").replace(/^\//, "");
1028
822
  const sseSuffix = (this._options.ssePath ?? "/sse").replace(/^\//, "");
1029
823
  const messagesSuffix = (this._options.messagesPath ?? "/messages").replace(/^\//, "");
1030
- if (endpoint === mcpSuffix && method === "GET") return "mcp-get";
1031
- if (endpoint === mcpSuffix && method === "POST") return "mcp-post";
824
+ // GET, POST and DELETE all belong to the Streamable HTTP state machine.
825
+ if (endpoint === mcpSuffix) return "mcp";
1032
826
  if (endpoint === sseSuffix && method === "GET") return "sse-connect";
1033
827
  if (endpoint === messagesSuffix && method === "POST") return "sse-message";
1034
828
  return null;
@@ -1037,11 +831,8 @@ export class WsTunnel implements IBrokerContext {
1037
831
  /** Routes an already-authorized (or auth-disabled) request to its handler. */
1038
832
  private _dispatchMcpEndpoint(kind: McpEndpointKind, req: IncomingMessage, res: ServerResponse, providerName: string, principal: IPrincipal | null): void {
1039
833
  switch (kind) {
1040
- case "mcp-get":
1041
- this._handleMcpGetStream(req, res, providerName, principal);
1042
- return;
1043
- case "mcp-post":
1044
- this._handleMcpPost(req, res, providerName, principal);
834
+ case "mcp":
835
+ this._handleStreamableHttp(req, res, providerName, principal);
1045
836
  return;
1046
837
  case "sse-connect":
1047
838
  this._handleSseConnect(req, res, providerName, principal);
@@ -1058,7 +849,7 @@ export class WsTunnel implements IBrokerContext {
1058
849
  guard.writeChallenge(res, providerName, err);
1059
850
  return;
1060
851
  }
1061
- // Not a token failure (e.g. the JWKS endpoint is unreachable) — surface a
852
+ // Not a token failure (e.g. the JWKS endpoint is unreachable), surface a
1062
853
  // 500 rather than a misleading 401.
1063
854
  console.error(`[broker] token validation error for "${providerName}":`, err);
1064
855
  res.writeHead(500, { "Content-Type": "application/json; charset=utf-8" });
@@ -1092,7 +883,7 @@ export class WsTunnel implements IBrokerContext {
1092
883
  const isDedicated = url.startsWith(providerPath + "/") || url === providerPath;
1093
884
 
1094
885
  if (isMultiplex || isDedicated) {
1095
- // Provider (engine) upgrade — shared-secret / custom authenticator.
886
+ // Provider (engine) upgrade, shared-secret / custom authenticator.
1096
887
  if (!providerAuth) {
1097
888
  cb(true);
1098
889
  return;
@@ -1124,7 +915,7 @@ export class WsTunnel implements IBrokerContext {
1124
915
  return;
1125
916
  }
1126
917
 
1127
- // Raw WS MCP client upgrade — OAuth 2.1 resource server.
918
+ // Raw WS MCP client upgrade, OAuth 2.1 resource server.
1128
919
  if (!guard) {
1129
920
  cb(true);
1130
921
  return;
@@ -1153,7 +944,7 @@ export class WsTunnel implements IBrokerContext {
1153
944
  // -------------------------------------------------------------------------
1154
945
 
1155
946
  /**
1156
- * Handles `GET /<providerName>/sse` — opens a long-lived SSE stream for Claude.
947
+ * Handles `GET /<providerName>/sse`, opens a long-lived SSE stream for Claude.
1157
948
  * Sends an `endpoint` event so Claude knows where to POST its requests.
1158
949
  */
1159
950
  private _handleSseConnect(req: IncomingMessage, res: ServerResponse, providerName: string, principal: IPrincipal | null): void {
@@ -1181,7 +972,7 @@ export class WsTunnel implements IBrokerContext {
1181
972
  }
1182
973
 
1183
974
  /**
1184
- * Handles `POST /<providerName>/messages?sessionId=…` — receives a JSON-RPC
975
+ * Handles `POST /<providerName>/messages?sessionId=…`, receives a JSON-RPC
1185
976
  * request from Claude and forwards it to the provider.
1186
977
  * Always responds 202 Accepted; the real response arrives over SSE.
1187
978
  */
@@ -1210,7 +1001,7 @@ export class WsTunnel implements IBrokerContext {
1210
1001
  const msg = JSON.parse(body) as { id?: string | number };
1211
1002
  if (msg.id != null) state.pending.set(msg.id, { type: "sse", sessionId });
1212
1003
  } catch {
1213
- /* malformed — forward anyway */
1004
+ /* malformed, forward anyway */
1214
1005
  }
1215
1006
 
1216
1007
  if (this._isProviderConnected(providerName, state)) {
@@ -1241,86 +1032,94 @@ export class WsTunnel implements IBrokerContext {
1241
1032
  }
1242
1033
 
1243
1034
  /**
1244
- * Handles `POST /<providerName>/mcp` — Streamable HTTP transport (MCP 2025-03-26).
1245
- * Forwards the JSON-RPC request to the provider and holds the HTTP response
1246
- * open until the reply arrives, then writes it as `application/json`.
1035
+ * Serves `/<providerName>/mcp` by handing the request to the slot's
1036
+ * Streamable HTTP endpoint.
1037
+ *
1038
+ * Everything protocol-shaped, sessions, `Mcp-Session-Id`, `DELETE`, the
1039
+ * `404` on a terminated session, `Origin` and `MCP-Protocol-Version`
1040
+ * validation, `202` on a notification, belongs to `mcp-core` and is no
1041
+ * longer reimplemented here. What stays is the broker's own business:
1042
+ * deciding who may speak (already done upstream by the auth guard) and
1043
+ * relaying frames to a provider that lives somewhere else entirely.
1247
1044
  */
1248
- private _handleMcpPost(req: IncomingMessage, res: ServerResponse, providerName: string, principal: IPrincipal | null): void {
1249
- let body = "";
1250
- req.on("data", (chunk: Buffer) => {
1251
- body += chunk.toString();
1252
- });
1253
- req.on("end", () => {
1254
- let msg: { id?: string | number } = {};
1255
- try {
1256
- msg = JSON.parse(body) as { id?: string | number };
1257
- } catch {
1258
- res.writeHead(400, { "Content-Type": "text/plain" });
1259
- res.end("Invalid JSON");
1260
- return;
1261
- }
1262
-
1263
- const state = this._getOrCreateProviderState(providerName);
1264
-
1265
- if (!this._authorizeMcpFrame(providerName, body, principal)) {
1266
- res.writeHead(403, { "Content-Type": "application/json; charset=utf-8" });
1267
- res.end(this._policyDeniedPayload(body));
1268
- return;
1269
- }
1270
-
1271
- if (!this._isProviderConnected(providerName, state)) {
1272
- res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
1273
- res.end(
1274
- JSON.stringify({
1275
- jsonrpc: "2.0",
1276
- id: msg.id ?? null,
1277
- error: { code: -32000, message: `Provider "${providerName}" not connected` },
1278
- })
1279
- );
1280
- return;
1281
- }
1045
+ private _handleStreamableHttp(req: IncomingMessage, res: ServerResponse, providerName: string, principal: IPrincipal | null): void {
1046
+ const state = this._getOrCreateProviderState(providerName);
1282
1047
 
1283
- if (msg.id != null) {
1284
- // Request: hold the response open; reply arrives in _routeFromProvider.
1285
- state.pending.set(msg.id, { type: "http", res });
1286
- } else {
1287
- // Notification: forward and acknowledge immediately.
1288
- res.writeHead(202);
1289
- res.end();
1290
- }
1048
+ // The endpoint authenticates nothing: this broker has its own guard,
1049
+ // richer than the spec's (per-slot scopes, subject mapping into the
1050
+ // policy engine). So the principal is attached to the session here,
1051
+ // refreshed on every request, and read back when a frame is checked.
1052
+ const sessionId = req.headers["mcp-session-id"];
1053
+ if (typeof sessionId === "string") {
1054
+ const session = state.httpSessions.get(sessionId);
1055
+ if (session) session.principal = principal;
1056
+ }
1291
1057
 
1292
- this._sendToProvider(state, providerName, body, principal);
1293
- });
1058
+ void this._endpointFor(providerName, state).handleRequest(req, res);
1294
1059
  }
1295
1060
 
1296
1061
  /**
1297
- * Handles `GET /<providerName>/mcp` — opens a persistent SSE stream per MCP 2025-03-26.
1298
- * Streamable HTTP clients (e.g. MCP Inspector) use this to receive
1299
- * server-initiated notifications without re-polling.
1062
+ * The slot's Streamable HTTP endpoint, built on first use.
1063
+ *
1064
+ * Its factory does not create an MCP server: the server is the provider,
1065
+ * reachable only through the tunnel. It creates a bridge instead: frames the
1066
+ * client sends go out to the provider, and frames coming back are addressed
1067
+ * to this session by id.
1300
1068
  */
1301
- private _handleMcpGetStream(req: IncomingMessage, res: ServerResponse, providerName: string, principal: IPrincipal | null): void {
1302
- const sessionId = (req.headers["mcp-session-id"] as string | undefined) ?? randomUUID();
1303
-
1304
- res.writeHead(200, {
1305
- "Content-Type": "text/event-stream",
1306
- "Cache-Control": "no-cache, no-transform",
1307
- Connection: "keep-alive",
1308
- "Mcp-Session-Id": sessionId,
1069
+ private _endpointFor(providerName: string, state: IProviderState): StreamableHttpEndpoint {
1070
+ if (state.httpEndpoint) return state.httpEndpoint;
1071
+
1072
+ state.httpEndpoint = new StreamableHttpEndpoint({
1073
+ allowedOrigins: this._allowedOrigins,
1074
+
1075
+ createServer: (transport, sessionId, _principal) => {
1076
+ const session: IHttpSession = { transport, principal: null };
1077
+ state.httpSessions.set(sessionId, session);
1078
+
1079
+ transport.onMessage = (frame: string) => this._fromHttpSession(state, providerName, sessionId, session, frame);
1080
+
1081
+ return {
1082
+ // No server to launch: the one serving this session is the
1083
+ // provider, at the far end of the tunnel. What `start` still
1084
+ // owes is opening the transport, since a closed one drops
1085
+ // every frame it is handed.
1086
+ start: () => openTransport(transport),
1087
+ stop: () => {
1088
+ state.httpSessions.delete(sessionId);
1089
+ // Nothing can answer the requests this session had in
1090
+ // flight; leaving them would pin the ids forever.
1091
+ for (const [id, sink] of state.pending) {
1092
+ if (sink.type === "http-session" && sink.sessionId === sessionId) state.pending.delete(id);
1093
+ }
1094
+ },
1095
+ };
1096
+ },
1309
1097
  });
1310
- res.write(": stream open\n\n");
1311
1098
 
1312
- const state = this._getOrCreateProviderState(providerName);
1313
- state.mcpGetSessions.set(sessionId, res);
1314
- if (principal) this._streamPrincipals.set(res, principal);
1099
+ return state.httpEndpoint;
1100
+ }
1315
1101
 
1316
- req.on("close", () => {
1317
- state.mcpGetSessions.delete(sessionId);
1318
- });
1102
+ /** Relays one frame from an HTTP session to the provider behind the slot. */
1103
+ private _fromHttpSession(state: IProviderState, providerName: string, sessionId: string, session: IHttpSession, frame: string): void {
1104
+ if (!this._authorizeMcpFrame(providerName, frame, session.principal)) {
1105
+ session.transport.send(this._policyDeniedPayload(frame));
1106
+ return;
1107
+ }
1108
+
1109
+ if (!this._isProviderConnected(providerName, state)) {
1110
+ session.transport.send(this._notConnectedPayload(providerName, frame));
1111
+ return;
1112
+ }
1113
+
1114
+ const id = requestIdOf(frame);
1115
+ if (id !== undefined) state.pending.set(id, { type: "http-session", sessionId });
1116
+
1117
+ this._sendToProvider(state, providerName, frame, session.principal);
1319
1118
  }
1320
1119
 
1321
1120
  /** Writes one JSON-RPC message as an SSE `message` event. */
1322
1121
  private _sendSseEvent(res: ServerResponse, data: string): void {
1323
- // data is already a compact JSON string — no need to parse+re-serialize.
1122
+ // data is already a compact JSON string: no need to parse+re-serialize.
1324
1123
  res.write(`event: message\ndata: ${data}\n\n`);
1325
1124
  }
1326
1125
 
@@ -1349,15 +1148,14 @@ export class WsTunnel implements IBrokerContext {
1349
1148
  }
1350
1149
  if (this._upstreams.has(name)) {
1351
1150
  console.warn(
1352
- `[broker] WARNING: WebSocket provider "${name}" rejected — a stdio upstream with the same name is already configured. ` +
1353
- `Rename one of them to avoid the conflict.`
1151
+ `[broker] WARNING: WebSocket provider "${name}" rejected: a stdio upstream with the same name is already configured. ` + `Rename one of them to avoid the conflict.`
1354
1152
  );
1355
1153
  ws.close(1008, `Provider "${name}" is managed by a stdio upstream`);
1356
1154
  return;
1357
1155
  }
1358
1156
 
1359
1157
  if (this._loopbackProviders.has(name)) {
1360
- console.warn(`[broker] WARNING: WebSocket provider "${name}" rejected — the slot is held by an in-process loopback (reserved system slot).`);
1158
+ console.warn(`[broker] WARNING: WebSocket provider "${name}" rejected: the slot is held by an in-process loopback (reserved system slot).`);
1361
1159
  ws.close(1008, `Provider "${name}" is reserved by the broker`);
1362
1160
  return;
1363
1161
  }
@@ -1375,8 +1173,8 @@ export class WsTunnel implements IBrokerContext {
1375
1173
  }
1376
1174
 
1377
1175
  // A provider MAY send a registration control frame as its very first
1378
- // message (see _tryHandleRegistration). Any other first message —
1379
- // including a normal MCP frame — is routed and leaves the provider
1176
+ // message (see _tryHandleRegistration). Any other first message ,
1177
+ // including a normal MCP frame, is routed and leaves the provider
1380
1178
  // non-aggregated, so every pre-existing provider keeps working.
1381
1179
  let registrationChecked = false;
1382
1180
  ws.on("message", (data: Buffer) => {
@@ -1397,7 +1195,7 @@ export class WsTunnel implements IBrokerContext {
1397
1195
  /**
1398
1196
  * Inspects a provider's first WebSocket message for an optional registration
1399
1197
  * control frame `{ "type": "register", "aggregate": boolean }`. Returns
1400
- * `true` when the message was a registration frame — and thus consumed, not
1198
+ * `true` when the message was a registration frame: and thus consumed, not
1401
1199
  * routed as MCP traffic. A normal MCP frame always carries `jsonrpc`, so it
1402
1200
  * returns `false` and the provider stays non-aggregated.
1403
1201
  */
@@ -1453,15 +1251,10 @@ export class WsTunnel implements IBrokerContext {
1453
1251
  }
1454
1252
 
1455
1253
  ws.on("message", (data: Buffer) => {
1456
- let envelope: { provider?: string; payload?: unknown };
1457
- try {
1458
- envelope = JSON.parse(data.toString()) as { provider?: string; payload?: unknown };
1459
- } catch {
1460
- return; // malformed — drop
1461
- }
1254
+ const envelope = decodeEnvelope(data.toString());
1255
+ if (!envelope) return; // malformed, drop
1462
1256
 
1463
1257
  const name = envelope.provider;
1464
- if (!name || envelope.payload === undefined) return;
1465
1258
 
1466
1259
  // Register provider name lazily on first encounter.
1467
1260
  if (!providerNames.has(name)) {
@@ -1469,64 +1262,28 @@ export class WsTunnel implements IBrokerContext {
1469
1262
  const resource = this._slotResourceResolver.resolve(name);
1470
1263
  if (!resource || !providerMayPublish(providerPrincipal, resource)) {
1471
1264
  this._logProviderRegistration(providerPrincipal, name, resource, false);
1472
- ws.send(
1473
- JSON.stringify({
1474
- provider: name,
1475
- payload: {
1476
- jsonrpc: "2.0",
1477
- id: null,
1478
- error: { code: -32001, message: "Provider registration forbidden" },
1479
- },
1480
- })
1481
- );
1265
+ ws.send(encodeErrorEnvelope(name, TunnelErrorCodes.RegistrationForbidden, "Provider registration forbidden"));
1482
1266
  return;
1483
1267
  }
1484
1268
  }
1485
1269
  if (this._upstreams.has(name)) {
1486
1270
  console.warn(
1487
- `[broker] WARNING: Multiplexed WebSocket provider "${name}" rejected — a stdio upstream with the same name is already configured. ` +
1271
+ `[broker] WARNING: Multiplexed WebSocket provider "${name}" rejected: a stdio upstream with the same name is already configured. ` +
1488
1272
  `Rename one of them to avoid the conflict.`
1489
1273
  );
1490
- ws.send(
1491
- JSON.stringify({
1492
- provider: name,
1493
- payload: {
1494
- jsonrpc: "2.0",
1495
- id: null,
1496
- error: { code: -32000, message: `Provider "${name}" is managed by a stdio upstream` },
1497
- },
1498
- })
1499
- );
1274
+ ws.send(encodeErrorEnvelope(name, TunnelErrorCodes.ProviderUnavailable, `Provider "${name}" is managed by a stdio upstream`));
1500
1275
  return;
1501
1276
  }
1502
1277
 
1503
1278
  if (this._loopbackProviders.has(name)) {
1504
- ws.send(
1505
- JSON.stringify({
1506
- provider: name,
1507
- payload: {
1508
- jsonrpc: "2.0",
1509
- id: null,
1510
- error: { code: -32000, message: `Provider "${name}" is reserved by the broker` },
1511
- },
1512
- })
1513
- );
1279
+ ws.send(encodeErrorEnvelope(name, TunnelErrorCodes.ProviderUnavailable, `Provider "${name}" is reserved by the broker`));
1514
1280
  return;
1515
1281
  }
1516
1282
 
1517
1283
  const existing = this._providers.get(name);
1518
1284
  if (existing?.ws?.readyState === WebSocket.OPEN) {
1519
- // Provider already connected via another socket — reject this name.
1520
- ws.send(
1521
- JSON.stringify({
1522
- provider: name,
1523
- payload: {
1524
- jsonrpc: "2.0",
1525
- id: null,
1526
- error: { code: -32000, message: `Provider "${name}" is already connected` },
1527
- },
1528
- })
1529
- );
1285
+ // Provider already connected via another socket, reject this name.
1286
+ ws.send(encodeErrorEnvelope(name, TunnelErrorCodes.ProviderUnavailable, `Provider "${name}" is already connected`));
1530
1287
  return;
1531
1288
  }
1532
1289
  providerNames.add(name);
@@ -1538,7 +1295,7 @@ export class WsTunnel implements IBrokerContext {
1538
1295
  }
1539
1296
 
1540
1297
  const state = this._providers.get(name)!;
1541
- this._routeFromProvider(state, name, JSON.stringify(envelope.payload));
1298
+ this._routeFromProvider(state, name, envelopeFrame(envelope));
1542
1299
  });
1543
1300
 
1544
1301
  ws.on("close", () => {
@@ -1563,7 +1320,7 @@ export class WsTunnel implements IBrokerContext {
1563
1320
  */
1564
1321
  private _sendToProvider(state: IProviderState, providerName: string, data: string, principal: IPrincipal | null = null): void {
1565
1322
  // The `_all` aggregate is a loopback, but it needs the caller's principal
1566
- // to scope its catalog/routing — hand it off directly rather than through
1323
+ // to scope its catalog/routing, hand it off directly rather than through
1567
1324
  // the generic transport, which would drop the context.
1568
1325
  if (providerName === AggregateServer.SLOT && this._aggregateServer) {
1569
1326
  this._aggregateServer.sendAs(data, principal);
@@ -1588,8 +1345,7 @@ export class WsTunnel implements IBrokerContext {
1588
1345
 
1589
1346
  if (this._multiplexSockets.has(state.ws)) {
1590
1347
  // Wrap in envelope for the multiplexed socket.
1591
- const payload = JSON.parse(data) as unknown;
1592
- state.ws.send(JSON.stringify({ provider: providerName, payload }));
1348
+ state.ws.send(encodeEnvelope(providerName, data));
1593
1349
  } else {
1594
1350
  state.ws.send(data);
1595
1351
  }
@@ -1613,12 +1369,12 @@ export class WsTunnel implements IBrokerContext {
1613
1369
  /* */
1614
1370
  }
1615
1371
  if (errId != null) {
1616
- process.stdout.write(
1372
+ this._stdioClientTransport?.send(
1617
1373
  JSON.stringify({
1618
1374
  jsonrpc: "2.0",
1619
1375
  id: errId,
1620
1376
  error: { code: -32000, message: `Provider "${this._stdioClientProvider}" not connected` },
1621
- }) + "\n"
1377
+ })
1622
1378
  );
1623
1379
  }
1624
1380
  }
@@ -1663,11 +1419,12 @@ export class WsTunnel implements IBrokerContext {
1663
1419
  } else if (sink?.type === "sse") {
1664
1420
  const sseRes = state.sseSessions.get(sink.sessionId);
1665
1421
  if (sseRes) this._sendSseEvent(sseRes, data);
1666
- } else if (sink?.type === "http") {
1667
- sink.res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
1668
- sink.res.end(data);
1422
+ } else if (sink?.type === "http-session") {
1423
+ // The session transport decides whether this answers a held-open
1424
+ // POST or travels on the GET stream: it correlates by id.
1425
+ state.httpSessions.get(sink.sessionId)?.transport.send(data);
1669
1426
  } else if (sink?.type === "stdio") {
1670
- process.stdout.write(data + "\n");
1427
+ this._stdioClientTransport?.send(data);
1671
1428
  } else if (sink?.type === "internal") {
1672
1429
  sink.client.onMessage?.(data);
1673
1430
  }
@@ -1695,10 +1452,12 @@ export class WsTunnel implements IBrokerContext {
1695
1452
  this._sendSseEvent(sseRes, data);
1696
1453
  }
1697
1454
  }
1698
- for (const mcpRes of state.mcpGetSessions.values()) {
1699
- const principal = this._streamPrincipals.get(mcpRes) ?? null;
1700
- if (this._authorizeMcpFrame(providerName, data, principal)) {
1701
- this._sendSseEvent(mcpRes, data);
1455
+ for (const session of state.httpSessions.values()) {
1456
+ // The principal rides on the session here rather than in a WeakMap
1457
+ // keyed by the response: a Streamable HTTP session spans many HTTP
1458
+ // exchanges, so there is no single response to hang it on.
1459
+ if (this._authorizeMcpFrame(providerName, data, session.principal)) {
1460
+ session.transport.send(data);
1702
1461
  }
1703
1462
  }
1704
1463
  for (const ic of state.internalClients) {
@@ -1706,7 +1465,7 @@ export class WsTunnel implements IBrokerContext {
1706
1465
  }
1707
1466
  // Forward notifications to the stdio client if it is watching this provider.
1708
1467
  if (this._stdioClientProvider && this._providers.get(this._stdioClientProvider) === state) {
1709
- process.stdout.write(data + "\n");
1468
+ this._stdioClientTransport?.send(data);
1710
1469
  }
1711
1470
  }
1712
1471
 
@@ -1716,20 +1475,24 @@ export class WsTunnel implements IBrokerContext {
1716
1475
  * close handlers (dedicated WS, multiplexed WS, loopback).
1717
1476
  */
1718
1477
  private _failProviderDisconnected(state: IProviderState, name: string): void {
1719
- const error = JSON.stringify({
1720
- jsonrpc: "2.0",
1721
- id: null,
1722
- error: { code: -32000, message: `Provider "${name}" disconnected` },
1723
- });
1724
- for (const sink of state.pending.values()) {
1478
+ // Echoing the pending id rather than `null`: a Streamable HTTP session
1479
+ // matches the answer to its held-open POST by id, so an unaddressed
1480
+ // error would leave that request hanging until it times out.
1481
+ for (const [id, sink] of state.pending) {
1482
+ const error = JSON.stringify({
1483
+ jsonrpc: "2.0",
1484
+ id,
1485
+ error: { code: -32000, message: `Provider "${name}" disconnected` },
1486
+ });
1725
1487
  if (sink.type === "ws" && sink.socket.readyState === WebSocket.OPEN) {
1726
1488
  sink.socket.send(error);
1727
1489
  } else if (sink.type === "sse") {
1728
1490
  const sseRes = state.sseSessions.get(sink.sessionId);
1729
1491
  if (sseRes) this._sendSseEvent(sseRes, error);
1730
- } else if (sink.type === "http") {
1731
- sink.res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
1732
- sink.res.end(error);
1492
+ } else if (sink.type === "http-session") {
1493
+ state.httpSessions.get(sink.sessionId)?.transport.send(error);
1494
+ } else if (sink.type === "stdio") {
1495
+ this._stdioClientTransport?.send(error);
1733
1496
  } else if (sink.type === "internal") {
1734
1497
  sink.client.onMessage?.(error);
1735
1498
  }
@@ -1743,7 +1506,7 @@ export class WsTunnel implements IBrokerContext {
1743
1506
  // -------------------------------------------------------------------------
1744
1507
 
1745
1508
  /**
1746
- * Returns `true` if the provider is reachable — via a WebSocket connection,
1509
+ * Returns `true` if the provider is reachable, via a WebSocket connection,
1747
1510
  * a stdio upstream, or an in-process loopback transport.
1748
1511
  */
1749
1512
  private _isProviderConnected(providerName: string, state: IProviderState): boolean {
@@ -1761,9 +1524,10 @@ export class WsTunnel implements IBrokerContext {
1761
1524
  ws: null,
1762
1525
  pending: new Map(),
1763
1526
  sseSessions: new Map(),
1764
- mcpGetSessions: new Map(),
1527
+ httpSessions: new Map(),
1765
1528
  wsClients: new Set(),
1766
1529
  internalClients: new Set(),
1530
+ httpEndpoint: null,
1767
1531
  };
1768
1532
  this._providers.set(name, state);
1769
1533
  }