@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.
- package/.mcp-broker.example/README.md +3 -3
- package/README.md +6 -2
- package/dist/bin.d.ts +0 -1
- package/dist/bin.js +176 -253
- package/dist/bin.js.map +1 -1
- package/dist/chunk-FTDKH2C4.js +3670 -0
- package/dist/chunk-FTDKH2C4.js.map +1 -0
- package/dist/{broker/grammars → grammars}/claude/en.json +1 -1
- package/dist/{broker/grammars → grammars}/claude/fr.json +1 -1
- package/dist/index.d.ts +1790 -22
- package/dist/index.js +2 -18
- package/dist/index.js.map +1 -1
- package/package.json +9 -7
- package/scripts/copy-assets.mjs +16 -10
- package/scripts/gen-cert.mjs +5 -5
- package/scripts/pack-mcpb.mjs +5 -5
- package/scripts/sign-bundle.mjs +6 -6
- package/src/auth/auth.config.ts +3 -3
- package/src/auth/auth.types.ts +34 -59
- package/src/auth/http.auth.ts +18 -22
- package/src/auth/index.ts +12 -12
- package/src/auth/jwt.validator.ts +3 -3
- package/src/auth/provider.auth.ts +1 -1
- package/src/auth/resource.metadata.ts +14 -21
- package/src/authorization/audit.ts +2 -2
- package/src/authorization/capability.classifier.ts +1 -1
- package/src/authorization/index.ts +13 -13
- package/src/authorization/policy.engine.ts +3 -3
- package/src/authorization/policy.types.ts +1 -1
- package/src/authorization/runtime.ts +5 -5
- package/src/authorization/slot.resource.ts +1 -1
- package/src/authorization/subject.mapper.ts +1 -1
- package/src/bin.ts +38 -8
- package/src/broker/adapters/broker.adapter.info.ts +1 -1
- package/src/broker/adapters/broker.adapter.providers.ts +1 -1
- package/src/broker/aggregate/aggregate.catalog.ts +1 -1
- package/src/broker/aggregate/aggregate.server.ts +7 -7
- package/src/broker/aggregate/provider.client.session.ts +2 -2
- package/src/broker/behaviors/broker.behavior.info.ts +3 -3
- package/src/broker/behaviors/broker.behavior.providers.ts +5 -5
- package/src/broker/broker.grammars.ts +9 -9
- package/src/broker/broker.server.ts +6 -6
- package/src/broker/grammars/claude/en.json +1 -1
- package/src/broker/grammars/claude/fr.json +1 -1
- package/src/broker/index.ts +9 -9
- package/src/config.ts +25 -3
- package/src/index.ts +24 -24
- package/src/{mcpb.loader.ts → mcpb/mcpb.loader.ts} +11 -11
- package/src/{mcpb.unzip.ts → mcpb/mcpb.unzip.ts} +2 -2
- package/src/remote.transports.ts +3 -3
- package/src/remote.upstream.ts +3 -3
- package/src/stdio.upstream.ts +2 -2
- package/src/upstream.ts +2 -2
- package/src/ws/ws.interfaces.ts +357 -0
- package/src/{ws.tunnel.builder.ts → ws/ws.tunnel.builder.ts} +28 -5
- package/src/{ws.tunnel.ts → ws/ws.tunnel.ts} +231 -467
- package/web/README.md +3 -3
- package/web/broker-self-mcp.html +9 -9
- package/web/css/styles.css +1 -1
- package/web/demos/DemoPlaceholder.html +6 -6
- package/web/demos/broker-explorer/css/app.css +1 -1
- package/web/demos/broker-explorer/index.html +2 -2
- package/web/demos/broker-explorer/js/app.js +4 -4
- package/web/demos/broker-explorer/js/mcp-ws-client.js +2 -2
- package/web/demos/oauth-lab/README.md +26 -0
- package/web/demos/oauth-lab/config.json +1 -0
- package/web/demos/oauth-lab/js/app.js +40 -16
- package/web/demos/oauth-lab/server/smoke-test.mjs +57 -10
- package/web/demos/provider-tunnel/css/app.css +1 -1
- package/web/demos/provider-tunnel/index.html +3 -3
- package/web/demos/provider-tunnel/js/app.js +10 -10
- package/web/demos/provider-tunnel/js/toolbox-server.js +5 -5
- package/web/index.html +11 -11
- package/web/js/lib/broker-tunnel.js +12 -12
- package/dist/auth/auth.config.d.ts +0 -40
- package/dist/auth/auth.config.js +0 -62
- package/dist/auth/auth.config.js.map +0 -1
- package/dist/auth/auth.types.d.ts +0 -119
- package/dist/auth/auth.types.js +0 -38
- package/dist/auth/auth.types.js.map +0 -1
- package/dist/auth/http.auth.d.ts +0 -51
- package/dist/auth/http.auth.js +0 -121
- package/dist/auth/http.auth.js.map +0 -1
- package/dist/auth/index.d.ts +0 -16
- package/dist/auth/index.js +0 -12
- package/dist/auth/index.js.map +0 -1
- package/dist/auth/jwt.validator.d.ts +0 -35
- package/dist/auth/jwt.validator.js +0 -46
- package/dist/auth/jwt.validator.js.map +0 -1
- package/dist/auth/provider.auth.d.ts +0 -51
- package/dist/auth/provider.auth.js +0 -80
- package/dist/auth/provider.auth.js.map +0 -1
- package/dist/auth/resource.metadata.d.ts +0 -32
- package/dist/auth/resource.metadata.js +0 -26
- package/dist/auth/resource.metadata.js.map +0 -1
- package/dist/authorization/audit.d.ts +0 -14
- package/dist/authorization/audit.js +0 -20
- package/dist/authorization/audit.js.map +0 -1
- package/dist/authorization/capability.classifier.d.ts +0 -30
- package/dist/authorization/capability.classifier.js +0 -85
- package/dist/authorization/capability.classifier.js.map +0 -1
- package/dist/authorization/index.d.ts +0 -13
- package/dist/authorization/index.js +0 -8
- package/dist/authorization/index.js.map +0 -1
- package/dist/authorization/policy.engine.d.ts +0 -11
- package/dist/authorization/policy.engine.js +0 -192
- package/dist/authorization/policy.engine.js.map +0 -1
- package/dist/authorization/policy.types.d.ts +0 -92
- package/dist/authorization/policy.types.js +0 -2
- package/dist/authorization/policy.types.js.map +0 -1
- package/dist/authorization/resource.path.d.ts +0 -27
- package/dist/authorization/resource.path.js +0 -122
- package/dist/authorization/resource.path.js.map +0 -1
- package/dist/authorization/runtime.d.ts +0 -22
- package/dist/authorization/runtime.js +0 -34
- package/dist/authorization/runtime.js.map +0 -1
- package/dist/authorization/slot.resource.d.ts +0 -12
- package/dist/authorization/slot.resource.js +0 -41
- package/dist/authorization/slot.resource.js.map +0 -1
- package/dist/authorization/subject.mapper.d.ts +0 -15
- package/dist/authorization/subject.mapper.js +0 -67
- package/dist/authorization/subject.mapper.js.map +0 -1
- package/dist/broker/adapters/broker.adapter.info.d.ts +0 -16
- package/dist/broker/adapters/broker.adapter.info.js +0 -43
- package/dist/broker/adapters/broker.adapter.info.js.map +0 -1
- package/dist/broker/adapters/broker.adapter.providers.d.ts +0 -18
- package/dist/broker/adapters/broker.adapter.providers.js +0 -61
- package/dist/broker/adapters/broker.adapter.providers.js.map +0 -1
- package/dist/broker/aggregate/aggregate.catalog.d.ts +0 -66
- package/dist/broker/aggregate/aggregate.catalog.js +0 -119
- package/dist/broker/aggregate/aggregate.catalog.js.map +0 -1
- package/dist/broker/aggregate/aggregate.server.d.ts +0 -66
- package/dist/broker/aggregate/aggregate.server.js +0 -257
- package/dist/broker/aggregate/aggregate.server.js.map +0 -1
- package/dist/broker/aggregate/provider.client.session.d.ts +0 -52
- package/dist/broker/aggregate/provider.client.session.js +0 -140
- package/dist/broker/aggregate/provider.client.session.js.map +0 -1
- package/dist/broker/behaviors/broker.behavior.info.d.ts +0 -15
- package/dist/broker/behaviors/broker.behavior.info.js +0 -41
- package/dist/broker/behaviors/broker.behavior.info.js.map +0 -1
- package/dist/broker/behaviors/broker.behavior.providers.d.ts +0 -19
- package/dist/broker/behaviors/broker.behavior.providers.js +0 -69
- package/dist/broker/behaviors/broker.behavior.providers.js.map +0 -1
- package/dist/broker/broker.context.d.ts +0 -63
- package/dist/broker/broker.context.js +0 -2
- package/dist/broker/broker.context.js.map +0 -1
- package/dist/broker/broker.grammars.d.ts +0 -132
- package/dist/broker/broker.grammars.js +0 -229
- package/dist/broker/broker.grammars.js.map +0 -1
- package/dist/broker/broker.server.d.ts +0 -68
- package/dist/broker/broker.server.js +0 -73
- package/dist/broker/broker.server.js.map +0 -1
- package/dist/broker/index.d.ts +0 -9
- package/dist/broker/index.js +0 -7
- package/dist/broker/index.js.map +0 -1
- package/dist/config.d.ts +0 -182
- package/dist/config.js +0 -61
- package/dist/config.js.map +0 -1
- package/dist/mcpb.loader.d.ts +0 -26
- package/dist/mcpb.loader.js +0 -161
- package/dist/mcpb.loader.js.map +0 -1
- package/dist/mcpb.unzip.d.ts +0 -6
- package/dist/mcpb.unzip.js +0 -95
- package/dist/mcpb.unzip.js.map +0 -1
- package/dist/remote.transports.d.ts +0 -18
- package/dist/remote.transports.js +0 -297
- package/dist/remote.transports.js.map +0 -1
- package/dist/remote.upstream.d.ts +0 -38
- package/dist/remote.upstream.js +0 -52
- package/dist/remote.upstream.js.map +0 -1
- package/dist/stdio.upstream.d.ts +0 -47
- package/dist/stdio.upstream.js +0 -85
- package/dist/stdio.upstream.js.map +0 -1
- package/dist/upstream.d.ts +0 -35
- package/dist/upstream.js +0 -2
- package/dist/upstream.js.map +0 -1
- package/dist/version.d.ts +0 -2
- package/dist/version.js +0 -9
- package/dist/version.js.map +0 -1
- package/dist/ws.tunnel.builder.d.ts +0 -176
- package/dist/ws.tunnel.builder.js +0 -271
- package/dist/ws.tunnel.builder.js.map +0 -1
- package/dist/ws.tunnel.d.ts +0 -455
- package/dist/ws.tunnel.js +0 -1425
- package/dist/ws.tunnel.js.map +0 -1
- /package/dist/{broker/grammars → grammars}/default/en.json +0 -0
- /package/dist/{broker/grammars → grammars}/default/fr.json +0 -0
- /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 {
|
|
9
|
-
import {
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
import
|
|
14
|
-
import {
|
|
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 "
|
|
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 "
|
|
36
|
-
import { VERSION, PACKAGE_NAME } from "
|
|
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
|
-
//
|
|
63
|
+
// JSON-RPC helpers
|
|
59
64
|
// ---------------------------------------------------------------------------
|
|
60
65
|
|
|
61
66
|
/**
|
|
62
|
-
*
|
|
63
|
-
*
|
|
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
|
-
*
|
|
106
|
-
*
|
|
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
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
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
|
-
*
|
|
118
|
-
*
|
|
119
|
-
*
|
|
120
|
-
*
|
|
121
|
-
*
|
|
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
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
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
|
-
*
|
|
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
|
-
|
|
142
|
-
|
|
143
|
-
|
|
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
|
-
/**
|
|
405
|
-
private
|
|
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.
|
|
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
|
|
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.
|
|
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
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
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
|
-
|
|
815
|
-
state.
|
|
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)
|
|
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
|
-
|
|
1031
|
-
if (endpoint === mcpSuffix
|
|
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
|
|
1041
|
-
this.
|
|
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)
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
*
|
|
1245
|
-
*
|
|
1246
|
-
*
|
|
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
|
|
1249
|
-
|
|
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
|
-
|
|
1284
|
-
|
|
1285
|
-
|
|
1286
|
-
|
|
1287
|
-
|
|
1288
|
-
|
|
1289
|
-
|
|
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
|
-
|
|
1293
|
-
});
|
|
1058
|
+
void this._endpointFor(providerName, state).handleRequest(req, res);
|
|
1294
1059
|
}
|
|
1295
1060
|
|
|
1296
1061
|
/**
|
|
1297
|
-
*
|
|
1298
|
-
*
|
|
1299
|
-
* server
|
|
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
|
|
1302
|
-
|
|
1303
|
-
|
|
1304
|
-
|
|
1305
|
-
|
|
1306
|
-
|
|
1307
|
-
|
|
1308
|
-
|
|
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
|
-
|
|
1313
|
-
|
|
1314
|
-
if (principal) this._streamPrincipals.set(res, principal);
|
|
1099
|
+
return state.httpEndpoint;
|
|
1100
|
+
}
|
|
1315
1101
|
|
|
1316
|
-
|
|
1317
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
1457
|
-
|
|
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
|
|
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
|
|
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,
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
})
|
|
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
|
-
|
|
1668
|
-
|
|
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
|
-
|
|
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
|
|
1699
|
-
|
|
1700
|
-
|
|
1701
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1720
|
-
|
|
1721
|
-
|
|
1722
|
-
|
|
1723
|
-
|
|
1724
|
-
|
|
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.
|
|
1732
|
-
|
|
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
|
|
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
|
-
|
|
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
|
}
|