@orkestrel/scaffold 0.0.119 → 0.0.121
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/dist/bin/main.js +19 -19
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
- package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +52 -51
- package/dist/host/claude/rules/tests.md +2 -2
- package/dist/host/claude/rules/typescript.md +2 -3
- package/dist/host/guides/abort.md +0 -4
- package/dist/host/guides/agent.md +5 -5
- package/dist/host/guides/brief.md +7 -15
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/budget.md +1 -5
- package/dist/host/guides/capture.md +2 -2
- package/dist/host/guides/codec.md +18 -3
- package/dist/host/guides/console.md +4 -30
- package/dist/host/guides/contract.md +23 -44
- package/dist/host/guides/csv.md +86 -93
- package/dist/host/guides/database.md +0 -4
- package/dist/host/guides/emitter.md +0 -2
- package/dist/host/guides/form.md +26 -47
- package/dist/host/guides/guide.md +0 -1
- package/dist/host/guides/html.md +3 -7
- package/dist/host/guides/indexeddb.md +28 -32
- package/dist/host/guides/interpret.md +165 -182
- package/dist/host/guides/jsonrpc.md +187 -0
- package/dist/host/guides/lsp.md +26 -51
- package/dist/host/guides/markdown.md +132 -141
- package/dist/host/guides/mcp.md +220 -276
- package/dist/host/guides/middleware.md +14 -22
- package/dist/host/guides/msg.md +47 -63
- package/dist/host/guides/ndjson.md +0 -4
- package/dist/host/guides/ollama.md +1 -3
- package/dist/host/guides/pool.md +0 -4
- package/dist/host/guides/probe.md +71 -80
- package/dist/host/guides/process.md +71 -79
- package/dist/host/guides/program.md +26 -35
- package/dist/host/guides/qualifier.md +0 -6
- package/dist/host/guides/queue.md +0 -4
- package/dist/host/guides/rater.md +6 -12
- package/dist/host/guides/reason.md +30 -36
- package/dist/host/guides/relation.md +0 -2
- package/dist/host/guides/router.md +11 -18
- package/dist/host/guides/scaffold.md +148 -144
- package/dist/host/guides/sea.md +47 -51
- package/dist/host/guides/server.md +15 -19
- package/dist/host/guides/sqlite.md +0 -4
- package/dist/host/guides/sse.md +6 -10
- package/dist/host/guides/table.md +481 -493
- package/dist/host/guides/template.md +0 -4
- package/dist/host/guides/terminal.md +0 -26
- package/dist/host/guides/test.md +46 -66
- package/dist/host/guides/timeout.md +0 -6
- package/dist/host/guides/tool.md +2 -6
- package/dist/host/guides/toolbox.md +0 -10
- package/dist/host/guides/websocket.md +0 -4
- package/dist/host/guides/worker.md +57 -57
- package/dist/host/guides/workflow.md +13 -26
- package/dist/host/guides/workspace.md +15 -21
- package/dist/host/manifest.json +64 -909
- package/dist/src/core/index.cjs +128 -181
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +213 -213
- package/dist/src/core/index.d.ts +213 -213
- package/dist/src/core/index.js +117 -170
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +35 -34
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +62 -58
- package/dist/src/server/index.d.ts +62 -58
- package/dist/src/server/index.js +36 -35
- package/dist/src/server/index.js.map +1 -1
- package/package.json +13 -13
package/dist/host/guides/mcp.md
CHANGED
|
@@ -21,17 +21,17 @@ itself holds no era branch. See [Protocol](#protocol),
|
|
|
21
21
|
|
|
22
22
|
**The dispatch core is transport-agnostic and provider-agnostic.** `MCPServer`
|
|
23
23
|
and `MCPClient` live in [`src/core`](../src/core) and import only siblings —
|
|
24
|
-
JSON-RPC
|
|
24
|
+
`@orkestrel/jsonrpc`'s JSON-RPC 2.0 wire contract, `@orkestrel/tool`'s tool registry, `@orkestrel/emitter`'s
|
|
25
25
|
observable surface, `@orkestrel/contract`'s guards, `@orkestrel/codec`'s Base64
|
|
26
26
|
coding. No HTTP, no WebSocket, no stdio, and no `as`: every value off the wire is
|
|
27
27
|
narrowed by a total guard. The
|
|
28
28
|
server's entry points are `dispatch` and `handle` — `dispatch` runs an already-parsed
|
|
29
|
-
`JSONRPCInvocation`, resolving a `JSONRPCResponse` for a
|
|
30
|
-
`undefined` for a `JSONRPCNotification` (its overloads say exactly that, so
|
|
29
|
+
`JSONRPCInvocation` from `@orkestrel/jsonrpc`, resolving a `JSONRPCResponse` for a
|
|
30
|
+
`JSONRPCRequest` and `undefined` for a `JSONRPCNotification` (its overloads say exactly that, so
|
|
31
31
|
neither caller handles the other's answer), and `handle(message)` is the string
|
|
32
32
|
boundary that wraps it with `JSON.parse` / `JSON.stringify` plus the parse
|
|
33
|
-
(`-32700`) and invalid-request (`-32600`) mapping, each of whose envelopes
|
|
34
|
-
|
|
33
|
+
(`-32700`) and invalid-request (`-32600`) mapping, each of whose envelopes carries
|
|
34
|
+
`id: null` for the id it could not read. The client mirrors it: `connect` negotiates the modern revision, `tools()`
|
|
35
35
|
exposes the remote tools as local `ToolInterface`s, and `call` runs one — a
|
|
36
36
|
remote failure throws locally, so an agent's `ToolManager` isolates it exactly
|
|
37
37
|
like a local throw. A remote tool result with `isError: true` throws `MCPToolError`
|
|
@@ -53,14 +53,14 @@ Each is a matched ingress/egress pair speaking the same `MCPServerInterface` /
|
|
|
53
53
|
- **WebSocket** — `createWebSocketServer` claims an upgrade on
|
|
54
54
|
`@orkestrel/server`'s upgrade seam, composing `@orkestrel/websocket`'s RFC 6455
|
|
55
55
|
wrapper for full duplex over one persistent connection, and closes every socket
|
|
56
|
-
it claimed when that spine stops. `
|
|
56
|
+
it claimed when that spine stops. `createNodeWebSocketClientTransport` is the
|
|
57
57
|
`node:http(s)`-upgrade egress.
|
|
58
58
|
- **stdio** — `createStdioServer` pumps newline-delimited JSON-RPC over a
|
|
59
59
|
process's `stdin`/`stdout` (or injected streams); `createStdioClientTransport`
|
|
60
60
|
spawns a child process and drives the same protocol over its piped stdio.
|
|
61
61
|
- **browser** — the page / Web Worker / Service Worker face: its own
|
|
62
|
-
`WebSocket` client transport over the native global, the
|
|
63
|
-
transport
|
|
62
|
+
`WebSocket` client transport over the native global, the core HTTP client
|
|
63
|
+
transport, plus the symmetric
|
|
64
64
|
`MessagePort` carrier and the `createScopeServer` worker bootstrap.
|
|
65
65
|
|
|
66
66
|
**Every transport is mechanism, not policy.** Auth, invocation rate limiting, and
|
|
@@ -165,8 +165,7 @@ Use the client and HTTP transport together and none of that wire anatomy reaches
|
|
|
165
165
|
call site — the transport derives all reserved metadata and headers:
|
|
166
166
|
|
|
167
167
|
```ts
|
|
168
|
-
import { createMCPClient } from '@orkestrel/mcp'
|
|
169
|
-
import { createHTTPClientTransport } from '@orkestrel/mcp/server'
|
|
168
|
+
import { createHTTPClientTransport, createMCPClient } from '@orkestrel/mcp'
|
|
170
169
|
|
|
171
170
|
const transport = createHTTPClientTransport({ url: 'https://mcp.example/rpc' })
|
|
172
171
|
const client = createMCPClient({ transport })
|
|
@@ -330,8 +329,8 @@ an oversized valid document receives `-32700` without first allocating its parse
|
|
|
330
329
|
graph. A call with no `id` is a **notification** — a type of its own, handled
|
|
331
330
|
(the `request` event still fires) but yielding no response (`dispatch` resolves
|
|
332
331
|
`undefined`, `handle` returns `undefined`), whatever its method. The error
|
|
333
|
-
envelopes
|
|
334
|
-
|
|
332
|
+
envelopes carry `id: null` for the id they could not read, as JSON-RPC 2.0 § 5
|
|
333
|
+
requires. Tool errors
|
|
335
334
|
are not protocol errors: the `ToolManager` (`@orkestrel/tool`) isolates a
|
|
336
335
|
thrown tool into a `success: false` result, which `tools/call` maps to an
|
|
337
336
|
`isError: true` tool result carrying its `error` text — so the server wraps
|
|
@@ -348,38 +347,42 @@ the reference tables for the core, then one section per transport.
|
|
|
348
347
|
|
|
349
348
|
### Narrow a message to its JSON-RPC arm
|
|
350
349
|
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
exactly one arm.
|
|
358
|
-
|
|
359
|
-
**An `id` is
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
350
|
+
The JSON-RPC 2.0 wire contract — the message types, their guards, the response builders, and
|
|
351
|
+
the reserved error codes — comes from `@orkestrel/jsonrpc`, and this package imports it. A
|
|
352
|
+
message splits on invocation and on response. An invocation is a **request** — a `method` call
|
|
353
|
+
carrying the `id` that correlates it with its answer — or a **notification**, the same call with
|
|
354
|
+
no `id`, answered by nothing. A response is a **result** arm or an **error** arm, never both.
|
|
355
|
+
Each `@orkestrel/jsonrpc` guard is total over an already-parsed `unknown`, and the arms partition
|
|
356
|
+
every input, so a positive answer names exactly one arm.
|
|
357
|
+
|
|
358
|
+
**An unreadable `id` is `null`.** A request's `id` is a string or an integer and never
|
|
359
|
+
`null`. JSON-RPC 2.0 § 5 requires an `id` on every response and sets it to `null` when the
|
|
360
|
+
request's id could not be read, so every error envelope this package writes for unparsable or
|
|
361
|
+
invalid input carries `id: null`.
|
|
362
|
+
|
|
363
|
+
**A JSON-RPC result is any value, and an MCP result is an object.** The `result` member of
|
|
364
|
+
`@orkestrel/jsonrpc`'s `JSONRPCResultResponse` type is `unknown`, so narrow it with
|
|
365
|
+
`isMCPResult` or `isMCPLegacyResult` before reading it. `HTTPClientTransport` delivers an
|
|
366
|
+
`application/json` reply whose `result` is a primitive, and `MCPClient` reports that reply on
|
|
367
|
+
`error` as a malformed message. When a legacy peer answers a correlated request with a primitive
|
|
368
|
+
`result`, `MCPLegacyClientTransport` answers that request with a `-32603` error response.
|
|
365
369
|
|
|
366
370
|
```ts
|
|
367
371
|
import {
|
|
368
372
|
buildJSONRPCError,
|
|
369
|
-
buildMethodOptions,
|
|
370
373
|
isJSONRPCErrorResponse,
|
|
371
374
|
isJSONRPCId,
|
|
372
375
|
isJSONRPCInvocation,
|
|
373
376
|
isJSONRPCNotification,
|
|
374
377
|
isJSONRPCRequest,
|
|
375
378
|
isJSONRPCResultResponse,
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
} from '@orkestrel/mcp'
|
|
379
|
+
JSONRPC_PARSE_ERROR,
|
|
380
|
+
} from '@orkestrel/jsonrpc'
|
|
381
|
+
import { buildMethodOptions, isMCPLegacyResult, isMCPResult } from '@orkestrel/mcp'
|
|
379
382
|
|
|
380
383
|
isJSONRPCId(1) // true
|
|
381
384
|
isJSONRPCId('') // true — an empty string is a legal id
|
|
382
|
-
isJSONRPCId(null) // false —
|
|
385
|
+
isJSONRPCId(null) // false — a request's id is never null
|
|
383
386
|
|
|
384
387
|
const call = { jsonrpc: '2.0', method: 'ping', id: 1 }
|
|
385
388
|
const signal = { jsonrpc: '2.0', method: 'notifications/initialized' }
|
|
@@ -390,12 +393,13 @@ isJSONRPCInvocation(signal) // true — the union of the two arms
|
|
|
390
393
|
|
|
391
394
|
const answer = { jsonrpc: '2.0', id: 1, result: { resultType: 'complete' } }
|
|
392
395
|
isJSONRPCResultResponse(answer) // true
|
|
393
|
-
isJSONRPCResultResponse({ jsonrpc: '2.0', id: 1, result: 5 }) //
|
|
396
|
+
isJSONRPCResultResponse({ jsonrpc: '2.0', id: 1, result: 5 }) // true — a JSON-RPC result is any value
|
|
394
397
|
isMCPResult(answer.result) // true — a modern result always carries `resultType`
|
|
398
|
+
isMCPResult(5) // false — an MCP result is an object
|
|
395
399
|
isMCPLegacyResult({ protocolVersion: '2025-11-25' }) // true — the legacy arm never does
|
|
396
400
|
|
|
397
|
-
const anonymous = buildJSONRPCError(
|
|
398
|
-
|
|
401
|
+
const anonymous = buildJSONRPCError(null, JSONRPC_PARSE_ERROR, 'Parse error')
|
|
402
|
+
anonymous.id // null — the request's id could not be read
|
|
399
403
|
isJSONRPCErrorResponse(anonymous) // true
|
|
400
404
|
|
|
401
405
|
// The resolved options every dispatched method receives. The signal is the request's
|
|
@@ -426,7 +430,8 @@ dispatched by the same lookup, and a name with no handler still answers
|
|
|
426
430
|
`-32601`:
|
|
427
431
|
|
|
428
432
|
```ts
|
|
429
|
-
import { buildJSONRPCResult
|
|
433
|
+
import { buildJSONRPCResult } from '@orkestrel/jsonrpc'
|
|
434
|
+
import { createMCPServer } from '@orkestrel/mcp'
|
|
430
435
|
import { createToolManager } from '@orkestrel/tool'
|
|
431
436
|
|
|
432
437
|
const server = createMCPServer({
|
|
@@ -451,7 +456,7 @@ short-circuits every notification before the registry is read. Nothing answers a
|
|
|
451
456
|
notification, and now nothing has to say so.
|
|
452
457
|
|
|
453
458
|
Answering is not optional either. `MCPMethodHandler` returns a
|
|
454
|
-
`JSONRPCResponse` or an `MCPStream` and nothing else, because a handler that
|
|
459
|
+
`JSONRPCResponse` from `@orkestrel/jsonrpc` or an `MCPStream` and nothing else, because a handler that
|
|
455
460
|
resolved `undefined` for a request would contradict `dispatch`'s own overloads
|
|
456
461
|
and leave the caller waiting to its deadline. The registry is open, so a handler
|
|
457
462
|
that was never typechecked against the seam can still arrive; dispatch contains
|
|
@@ -500,7 +505,7 @@ generic that would falsely promise protocol verification.
|
|
|
500
505
|
#### Control a streaming method response
|
|
501
506
|
|
|
502
507
|
A handler that must hold the request open returns an `MCPStream` instead of
|
|
503
|
-
a response: each `yield` is a `JSONRPCNotification`, and the generator's
|
|
508
|
+
a response: each `yield` is a `JSONRPCNotification` from `@orkestrel/jsonrpc`, and the generator's
|
|
504
509
|
`return` value is the terminating response — closure is a result, not an
|
|
505
510
|
out-of-band event, so consuming a stream ends exactly where consuming a
|
|
506
511
|
unary response ends. The yield type forbids an `id`, so a producer cannot put
|
|
@@ -596,6 +601,7 @@ result shape for them. See
|
|
|
596
601
|
| `createMCPLegacy` | function | `(server: MCPServerInterface) => MCPDispatcherInterface` | Decorates one MCP server with the fixed legacy method translation. |
|
|
597
602
|
| `createMCPClient` | function | `(options: MCPClientOptions) => MCPClientInterface` | Creates a transport-agnostic Model Context Protocol client — connects to a remote MCP server over an injected `MCPMessageTransportInterface`, negotiates the modern revision through `server/discover`, and exposes the server's tools as local `ToolInterface`s an agent can run. |
|
|
598
603
|
| `createMCPLegacyClientTransport` | function | `(transport: MCPMessageTransportInterface, options?: MCPLegacyClientTransportOptions) => MCPMessageTransportInterface` | Decorates one client transport with explicit legacy handshake and era translation. |
|
|
604
|
+
| `createHTTPClientTransport` | function | `(options: HTTPClientTransportOptions) => MCPMessageTransportInterface` | Creates the HTTP client transport for an `MCPClientInterface` — a `MCPMessageTransportInterface` that drives a remote Streamable-HTTP MCP server over `fetch`. |
|
|
599
605
|
| `createDuplexClientTransport` | function | `(transport: MCPTransportInterface) => MCPMessageTransportInterface` | Adapts an `MCPTransportInterface` (the environment-agnostic duplex message channel) into a `MCPMessageTransportInterface` — the additive bridge that lets `createMCPClient` run over the new port without any change to `MCPClient`'s existing shape. |
|
|
600
606
|
|
|
601
607
|
### Classes
|
|
@@ -617,54 +623,46 @@ result shape for them. See
|
|
|
617
623
|
|
|
618
624
|
### Constants
|
|
619
625
|
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
|
623
|
-
|
|
|
624
|
-
| `
|
|
625
|
-
| `
|
|
626
|
-
| `
|
|
627
|
-
| `
|
|
628
|
-
| `
|
|
629
|
-
| `
|
|
630
|
-
| `
|
|
631
|
-
| `
|
|
632
|
-
| `
|
|
633
|
-
| `
|
|
634
|
-
| `
|
|
635
|
-
| `
|
|
636
|
-
| `
|
|
637
|
-
| `
|
|
638
|
-
| `
|
|
639
|
-
| `
|
|
640
|
-
| `
|
|
641
|
-
| `
|
|
642
|
-
| `
|
|
643
|
-
| `
|
|
644
|
-
| `
|
|
645
|
-
| `
|
|
646
|
-
| `
|
|
647
|
-
| `
|
|
648
|
-
| `
|
|
649
|
-
| `
|
|
650
|
-
| `
|
|
651
|
-
| `
|
|
652
|
-
| `
|
|
653
|
-
| `
|
|
654
|
-
| `
|
|
655
|
-
| `DEFAULT_MCP_REQUEST_TIMEOUT` | const | `30000` | Sets the default per-request deadline (ms) an `MCPClient` applies when `options.timeout` is unset — a request the remote server does not answer within it rejects. |
|
|
656
|
-
| `DEFAULT_MCP_SUBSCRIPTION_CAPACITY` | const | `64` | Sets the default number of subscription frames retained while no client read is parked. |
|
|
657
|
-
| `MCP_SESSION_HEADER` | const | `"mcp-session-id"` | Names the Streamable-HTTP transport header that carries the MCP session id. |
|
|
658
|
-
| `MCP_PROTOCOL_VERSION_HEADER` | const | `"mcp-protocol-version"` | Names the Streamable-HTTP transport header carrying the MCP protocol version. |
|
|
659
|
-
| `MCP_METHOD_HEADER` | const | `"mcp-method"` | Names the modern Streamable-HTTP request header carrying the JSON-RPC method. |
|
|
660
|
-
| `MCP_NAME_HEADER` | const | `"mcp-name"` | Names the modern Streamable-HTTP request header carrying a named target. |
|
|
661
|
-
| `MCP_WEBSOCKET_SUBPROTOCOL` | const | `"mcp"` | Names the WebSocket subprotocol `createWebSocketClientTransport` requests by default — `'mcp'`, which `createWebSocketServer` selects when the client offers it. Per RFC 6455 §4.1 a client MUST fail the connection if the server returns a subprotocol it did not request; Node ≥ 22 (undici) enforces this strictly, so the default bakes the correct value in. Override `WebSocketClientTransportOptions.protocols` only when connecting to a foreign server that speaks a different subprotocol (or `[]` for no subprotocol negotiation at all). |
|
|
626
|
+
| Name | Kind | Signature | Summary |
|
|
627
|
+
| ------------------------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
628
|
+
| `MCP_HANDSHAKE_VERSION` | const | `MCPLegacyVersion` | Names the revision offered and defaulted to in the legacy `initialize` handshake, `'2025-11-25'`. |
|
|
629
|
+
| `MCP_FALLBACK_VERSION` | const | `MCPLegacyVersion` | Names the older legacy revision the optional legacy decorator accepts and an adapter can pin, `'2025-06-18'`. |
|
|
630
|
+
| `MCP_MODERN_VERSION` | const | `MCPModernVersion` | Names the modern revision offered by an unpinned client during discovery, `'2026-07-28'`. |
|
|
631
|
+
| `SUPPORTED_MODERN_PROTOCOL_VERSIONS` | const | `readonly MCPModernVersion[]` | Lists the modern MCP protocol revisions a bare server accepts and advertises, `2026-07-28`. |
|
|
632
|
+
| `SUPPORTED_LEGACY_PROTOCOL_VERSIONS` | const | `readonly MCPLegacyVersion[]` | Lists the protocol revisions accepted by the optional legacy decorator, `2025-11-25` and `2025-06-18`. |
|
|
633
|
+
| `SUPPORTED_MCP_VERSIONS` | const | `readonly MCPVersion[]` | Lists the protocol revisions the `isMCPVersion` guard admits, spanning the modern and legacy eras. |
|
|
634
|
+
| `MCP_META_VERSION` | const | `"io.modelcontextprotocol/protocolVersion"` | Names the reserved modern `_meta` key carrying the request's protocol revision. |
|
|
635
|
+
| `MCP_META_CAPABILITIES` | const | `"io.modelcontextprotocol/clientCapabilities"` | Names the reserved modern `_meta` key carrying the client's open capability record. |
|
|
636
|
+
| `MCP_META_CLIENT` | const | `"io.modelcontextprotocol/clientInfo"` | Names the reserved modern `_meta` key carrying the optional client identity. |
|
|
637
|
+
| `MCP_META_SERVER` | const | `"io.modelcontextprotocol/serverInfo"` | Names the reserved modern `_meta` key carrying the server identity on results. |
|
|
638
|
+
| `MCP_META_SUBSCRIPTION` | const | `"io.modelcontextprotocol/subscriptionId"` | Names the reserved modern `_meta` key carrying a `subscriptions/listen` request id. |
|
|
639
|
+
| `MCP_EXTENSION_TASKS` | const | `"io.modelcontextprotocol/tasks"` | Names the reserved extension key identifying the stable Tasks extension. |
|
|
640
|
+
| `MCP_SENTINEL_PREFIX` | const | `"=?base64?"` | Names the opening marker of the Base64 sentinel a standard MCP header value travels in. |
|
|
641
|
+
| `MCP_SENTINEL_SUFFIX` | const | `"?="` | Names the closing marker of the Base64 sentinel a standard MCP header value travels in. |
|
|
642
|
+
| `MCP_PARAM_PREFIX` | const | `"Mcp-Param-"` | Names the request-header prefix an `x-mcp-header` annotation projects a tool argument onto. |
|
|
643
|
+
| `MCP_HEADER_ANNOTATION` | const | `"x-mcp-header"` | Identifies the tool-schema annotation key naming the header one parameter projects into. |
|
|
644
|
+
| `MCP_LOOKUP_PAGES` | const | `8` | Bounds the `tools/list` pages one modern `tools/call` walks to reach its own annotations. |
|
|
645
|
+
| `MCP_HEADER_MISMATCH` | const | `-32020` | Names the MCP reserved error for required HTTP metadata that does not match the request body. |
|
|
646
|
+
| `MCP_MISSING_CAPABILITY` | const | `-32021` | Names the MCP reserved error for an operation needing a client capability that was not declared. |
|
|
647
|
+
| `MCP_UNSUPPORTED_VERSION` | const | `-32022` | Names the MCP reserved error for a request naming an unsupported protocol revision. |
|
|
648
|
+
| `DEFAULT_MCP_CACHE_TTL` | const | `60000` | Sets the default modern result freshness lifetime in milliseconds. |
|
|
649
|
+
| `DEFAULT_MCP_LIMITS` | const | `Readonly<{ message: 1048576; metadata: 16384; keys: 64; state: 16384; content: 4194304; subscriptions: 128; depth: 32; }>` | Sets the secure server bounds used when the matching `limit` option leaf is absent or malformed. |
|
|
650
|
+
| `EMPTY_MCP_ARGUMENTS` | const | `Readonly<Record<string, unknown>>` | Holds the one empty argument record every argument-less modern `tools/call` runs with. |
|
|
651
|
+
| `JSONRPC_SERVER_ERROR` | const | `-32000` | Names the JSON-RPC 2.0 implementation-defined server error (the `-32000` to `-32099` range). |
|
|
652
|
+
| `DEFAULT_MCP_CLIENT_NAME` | const | `"@orkestrel/mcp"` | Supplies the default client name reported in the MCP `initialize` handshake (`clientInfo.name`). |
|
|
653
|
+
| `DEFAULT_MCP_CLIENT_VERSION` | const | `"1.0.0"` | Supplies the default client version reported in the MCP `initialize` handshake (`clientInfo.version`). |
|
|
654
|
+
| `DEFAULT_MCP_REQUEST_TIMEOUT` | const | `30000` | Sets the default per-request deadline (ms) an `MCPClient` applies when `options.timeout` is unset — a request the remote server does not answer within it rejects. |
|
|
655
|
+
| `DEFAULT_MCP_SUBSCRIPTION_CAPACITY` | const | `64` | Sets the default number of subscription frames retained while no client read is parked. |
|
|
656
|
+
| `MCP_SESSION_HEADER` | const | `"mcp-session-id"` | Names the Streamable-HTTP transport header that carries the MCP session id. |
|
|
657
|
+
| `MCP_PROTOCOL_VERSION_HEADER` | const | `"mcp-protocol-version"` | Names the Streamable-HTTP transport header carrying the MCP protocol version. |
|
|
658
|
+
| `MCP_METHOD_HEADER` | const | `"mcp-method"` | Names the modern Streamable-HTTP request header carrying the JSON-RPC method. |
|
|
659
|
+
| `MCP_NAME_HEADER` | const | `"mcp-name"` | Names the modern Streamable-HTTP request header carrying a named target. |
|
|
660
|
+
| `MCP_WEBSOCKET_SUBPROTOCOL` | const | `"mcp"` | Names the WebSocket subprotocol `createBrowserWebSocketClientTransport` and `createNodeWebSocketClientTransport` request by default — `'mcp'`, which `createWebSocketServer` selects when the client offers it. Per RFC 6455 §4.1 a client MUST fail the connection if the server returns a subprotocol it did not request; Node ≥ 22 (undici) enforces this strictly, so the default bakes the correct value in. Override `BrowserWebSocketClientTransportOptions.protocols` only when connecting to a foreign server that speaks a different subprotocol (or `[]` for no subprotocol negotiation at all). |
|
|
662
661
|
|
|
663
662
|
### Helpers
|
|
664
663
|
|
|
665
664
|
| Name | Kind | Signature | Summary |
|
|
666
665
|
| ---------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
667
|
-
| `isJSONRPCId` | function | `(value: unknown) => value is JSONRPCId` | Determines whether a value is a valid JSON-RPC correlation id — a string or a finite integer. |
|
|
668
666
|
| `isBoundedString` | function | `(value: unknown, bytes: number) => value is string` | Determines whether a value is a string within a UTF-8 byte bound. |
|
|
669
667
|
| `isBoundedJSON` | function | `<T>(value: T, limits: MCPJSONLimitOptions) => value is T & JSONValue` | Determines whether a value is bounded, cycle-free exact JSON. |
|
|
670
668
|
| `isJSONObject` | function | `(value: unknown) => value is Readonly<Record<string, JSONValue>>` | Determines whether a value is an exact finite JSON object. |
|
|
@@ -704,14 +702,6 @@ A `Shape` cell holds the constant's declared type.
|
|
|
704
702
|
| `isAbsoluteURI` | function | `(value: unknown) => value is string` | Determines whether a value is one absolute URI under RFC 3986 syntax. |
|
|
705
703
|
| `isRFC3339Date` | function | `(value: unknown) => value is string` | Determines whether a value is one RFC 3339 `full-date` naming a real calendar day. |
|
|
706
704
|
| `isRFC3339DateTime` | function | `(value: unknown) => value is string` | Determines whether a value is one RFC 3339 `date-time` naming a real calendar day. |
|
|
707
|
-
| `isJSONRPCRequest` | function | `(value: unknown) => value is JSONRPCRequest` | Determines whether a parsed value is a `JSONRPCRequest`. |
|
|
708
|
-
| `isJSONRPCNotification` | function | `(value: unknown) => value is JSONRPCNotification` | Determines whether a parsed value is a `JSONRPCNotification`. |
|
|
709
|
-
| `isJSONRPCInvocation` | function | `(value: unknown) => value is JSONRPCInvocation` | Determines whether a parsed value is a `JSONRPCInvocation` — a request or a notification. |
|
|
710
|
-
| `isJSONRPCResultResponse` | function | `(value: unknown) => value is JSONRPCResultResponse` | Determines whether a parsed value is a `JSONRPCResultResponse` — the success arm of a response. |
|
|
711
|
-
| `isJSONRPCError` | function | `(value: unknown) => value is JSONRPCError` | Determines whether a value is one JSON-RPC `error` member. |
|
|
712
|
-
| `isJSONRPCErrorResponse` | function | `(value: unknown) => value is JSONRPCErrorResponse` | Determines whether a parsed value is a `JSONRPCErrorResponse` — the failure arm of a response. |
|
|
713
|
-
| `isJSONRPCResponse` | function | `(value: unknown) => value is JSONRPCResponse` | Determines whether a parsed value is a `JSONRPCResponse`. |
|
|
714
|
-
| `isJSONRPCMessage` | function | `(value: unknown) => value is JSONRPCMessage` | Determines whether a parsed value is a `JSONRPCMessage` — an invocation or a response. |
|
|
715
705
|
| `isMCPResult` | function | `(value: unknown) => value is MCPResult` | Determines whether a value is one modern MCP result. |
|
|
716
706
|
| `isMCPLegacyResult` | function | `(value: unknown) => value is MCPLegacyResult` | Determines whether a value is one legacy-era MCP result. |
|
|
717
707
|
| `isInitializeRequest` | function | `(value: unknown) => value is JSONRPCInvocation` | Determines whether a parsed value is an MCP `initialize` invocation. |
|
|
@@ -755,8 +745,6 @@ A `Shape` cell holds the constant's declared type.
|
|
|
755
745
|
| `inferVersion` | function | `(offered: readonly string[]) => MCPModernVersion \| undefined` | Infers the newest supported modern protocol revision present in a peer's offer. |
|
|
756
746
|
| `inferRequestEra` | function | `(invocation: JSONRPCInvocation) => MCPEra` | Infers the wire era one invocation's own structure selects. |
|
|
757
747
|
| `inferRequestVersion` | function | `(message: JSONRPCMessage) => string \| undefined` | Infers the protocol version an outbound message announces itself with — the one projection every HTTP client transport stamps `mcp-protocol-version` from. |
|
|
758
|
-
| `buildJSONRPCResult` | function | `(id: JSONRPCId, result: MCPResult \| MCPLegacyResult) => JSONRPCResultResponse` | Builds a JSON-RPC success `JSONRPCResultResponse` — the `id` echoed, the method's value as `result`. |
|
|
759
|
-
| `buildJSONRPCError` | function | `(id: JSONRPCId \| undefined, code: number, message: string, data?: unknown) => JSONRPCErrorResponse` | Builds a JSON-RPC error `JSONRPCErrorResponse` — the `id` echoed, the failure as an `error` object. |
|
|
760
748
|
| `buildMethodOptions` | function | `(options: MCPDispatchOptions, lifetime: AbortSignal) => MCPMethodOptions` | Resolves the caller-facing dispatch options into the options a dispatched method receives. |
|
|
761
749
|
| `buildToolDescriptors` | function | `(manager: ToolManagerInterface) => readonly MCPToolDescriptor[]` | Maps a `ToolManagerInterface`'s definitions to MCP `tools/list` descriptors — renaming `parameters` to the wire's `inputSchema`. |
|
|
762
750
|
| `toolAnnotationsToMCP` | function | `(annotations: ToolAnnotations) => MCPToolAnnotations` | Projects domain tool annotations onto MCP wire hints without inventing defaults. |
|
|
@@ -819,22 +807,8 @@ isMCPToolAnnotations({ readOnlyHint: false }) // true
|
|
|
819
807
|
|
|
820
808
|
### Types
|
|
821
809
|
|
|
822
|
-
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
|
|
823
|
-
optional member and `plus` introducing its call-signature members, and a type alias's own type
|
|
824
|
-
literal with a union's arms escaped as `\|`.
|
|
825
|
-
An extended interface's name comes before `plus`, with the members it adds after.
|
|
826
|
-
|
|
827
810
|
| Name | Kind | Signature | Summary |
|
|
828
811
|
| ---------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
829
|
-
| `JSONRPCId` | type | `string \| number` | Represents a JSON-RPC 2.0 correlation id — the value a request and its response share. |
|
|
830
|
-
| `JSONRPCRequest` | interface | `{ jsonrpc, method, id, params? }` | Represents a JSON-RPC 2.0 request — a `method` call with optional `params`, correlated to its response by the `id` it requires. |
|
|
831
|
-
| `JSONRPCNotification` | interface | `{ jsonrpc, method, id?, params? }` | Represents a JSON-RPC 2.0 notification — a fire-and-forget `method` call that is answered by nothing (for example, `notifications/initialized`). |
|
|
832
|
-
| `JSONRPCInvocation` | type | `JSONRPCRequest \| JSONRPCNotification` | Represents one inbound JSON-RPC call — the common dispatch input. |
|
|
833
|
-
| `JSONRPCError` | interface | `{ code, message, data? }` | Represents a JSON-RPC 2.0 error object — the `error` member of a `JSONRPCErrorResponse`. |
|
|
834
|
-
| `JSONRPCResultResponse` | interface | `{ jsonrpc, id, result, error? }` | Represents the success arm of a JSON-RPC 2.0 response — the request's `id` echoed with the method's `result`. |
|
|
835
|
-
| `JSONRPCErrorResponse` | interface | `{ jsonrpc, id?, error, result? }` | Represents the failure arm of a JSON-RPC 2.0 response — the request's `id` echoed with the `JSONRPCError` that ended it. |
|
|
836
|
-
| `JSONRPCResponse` | type | `JSONRPCResultResponse \| JSONRPCErrorResponse` | Represents a JSON-RPC 2.0 response — the answer to one `JSONRPCRequest`. |
|
|
837
|
-
| `JSONRPCMessage` | type | `JSONRPCInvocation \| JSONRPCResponse` | Represents a JSON-RPC 2.0 message on the wire — a `JSONRPCInvocation` or a `JSONRPCResponse`. |
|
|
838
812
|
| `MCPResult` | interface | `{ resultType, _meta?, readonly [key: string]: unknown }` | Represents one modern MCP result — the open contract every dated-revision result satisfies. |
|
|
839
813
|
| `MCPLegacyResult` | interface | `{ resultType?, readonly [key: string]: unknown }` | Represents one legacy-era result — the payload of an answer produced by the fixed legacy method switch. |
|
|
840
814
|
| `MCPVersion` | type | `MCPModernVersion \| MCPLegacyVersion` | Names a protocol revision supported by an MCP package surface. |
|
|
@@ -968,6 +942,7 @@ An extended interface's name comes before `plus`, with the members it adds after
|
|
|
968
942
|
| `MCPMessageTransportEventMap` | type | `{ readonly message: readonly [message: JSONRPCMessage]; readonly close: readonly []; readonly error: readonly [error: unknown]; }` | Lists the observable events of a `MCPMessageTransportInterface` — the moments the `MCPClientInterface` (and any tracer) subscribes to through `transport.emitter.on`. |
|
|
969
943
|
| `MCPMessageTransportInterface` | interface | `{ emitter, session, duplex, start(), send(), close() }` | Pumps JSON-RPC messages to a peer and surfaces received messages on its `emitter`'s `message` event, with no knowledge of the protocol role on either side — a transport-agnostic MCP message carrier. |
|
|
970
944
|
| `HTTPClientTransportOptions` | interface | `{ url, headers?, fetch?, timeout? }` | Options for `createHTTPClientTransport` — the remote MCP server's URL and any extra request headers. |
|
|
945
|
+
| `WebSocketClientTransportOptions` | interface | `{ url }` | Describes the options every WebSocket client transport shares — the remote MCP server's WebSocket endpoint. |
|
|
971
946
|
| `MCPLegacyClientTransportOptions` | interface | `{ identity?, capabilities?, version?, timeout? }` | Options for the explicit legacy client transport adapter. |
|
|
972
947
|
| `MCPClientEventMap` | type | `{ readonly connect: readonly []; readonly disconnect: readonly []; readonly notification: readonly [message: JSONRPCMessage]; readonly error: readonly [error: unknown]; }` | Represents the push observation surface of an `MCPClientInterface` — the moments a fire-and-forget observer (logging, tracing) subscribes to through `client.emitter.on`. |
|
|
973
948
|
| `MCPClientOptions` | interface | `{ on?, error?, transport, identity?, capabilities?, version?, timeout? }` | Options for `createMCPClient` — the `MCPMessageTransportInterface` to drive, the optional client `MCPIdentity`, the per-request `timeout`, and the reserved `on` hooks. |
|
|
@@ -1075,7 +1050,7 @@ request body through `mcp.dispatch`. For a streamed response,
|
|
|
1075
1050
|
response-stream cancellation; the optional session middleware preserves the request
|
|
1076
1051
|
signal when it rebuilds a buffered POST. A malformed JSON body, or a parsed value
|
|
1077
1052
|
that is not a JSON-RPC request, is an HTTP `400` carrying a JSON-RPC error
|
|
1078
|
-
body (`-32700` / `-32600`, with
|
|
1053
|
+
body (`-32700` / `-32600`, with `id: null`). Legacy dispatch results retain uniform
|
|
1079
1054
|
HTTP `200` with in-band errors. Modern responses use `202` for notifications,
|
|
1080
1055
|
`400` for `-32020` / `-32021` / `-32022` / `-32602`, `404` for `-32601`, and
|
|
1081
1056
|
`200` otherwise. A unary reply is framed as one `@orkestrel/server` `createStream`
|
|
@@ -1180,7 +1155,6 @@ in-memory `Map` with capacity + lazy-TTL eviction.
|
|
|
1180
1155
|
| `createMCPContinuation` | function | `(secret: TokenSecret) => MCPContinuationInterface` | Adapts the installed server token primitives to the host-neutral MCP continuation port. |
|
|
1181
1156
|
| `createMCPRoutes` | function | `<TState = unknown>(mcp: MCPDispatcherInterface, options?: HTTPTransportOptions<TState>) => ReadonlyArray<RouteInput<string, TState>>` | Creates the MCP Streamable-HTTP transport routes — mounts a transport-agnostic `MCPDispatcherInterface` (the `@orkestrel/mcp` dispatch boundary) on the fetch-standard router spine, pumping each `POST` body through `mcp.dispatch`. Returns the `RouteInput`s to hand to `router.add(...)`. |
|
|
1182
1157
|
| `createMCPPostHandler` | function | `<TState = unknown>(mcp: MCPDispatcherInterface, options?: HTTPHandlerOptions<TState>) => (request: Request, context?: RouteContext<string, TState>) => Promise<Response>` | Creates the Streamable-HTTP POST handler used by `createMCPRoutes`. |
|
|
1183
|
-
| `createHTTPClientTransport` | function | `(options: HTTPClientTransportOptions) => MCPMessageTransportInterface` | Creates the HTTP client transport for an `MCPClientInterface` — a `MCPMessageTransportInterface` that drives a remote Streamable-HTTP MCP server over `fetch`. The egress mirror of `createMCPRoutes`. |
|
|
1184
1158
|
| `createMCPSession` | function | `<TState extends MCPSessionState>(options?: MCPSessionMiddlewareOptions) => MiddlewareHandler<TState>` | Creates the native MCP session `MiddlewareHandler` — the plug-and-play stateful layer that fronts a session-agnostic `createMCPRoutes`. Compose it with `router.use(createMCPSession())` (or the equivalent middleware seam), mirroring any other closure-scoped stateful middleware. Has no dependency on `@orkestrel/middleware` — the session store, mint-on-`initialize`, and resumable stream are all native to this package. |
|
|
1185
1159
|
| `createDuplexServerTransport` | function | `(transport: MCPMessageTransportInterface) => MCPTransportInterface` | Creates the server-side mirror of `createDuplexClientTransport`: the adapter that bridges a message-channel `MCPMessageTransportInterface` (the shape the stdio and WebSocket server transports already implement) onto the environment-agnostic `MCPTransportInterface` port — what `createStdioServer` and `createWebSocketServer` pipe through `bindServer`, so the request/reply/error pump those factories used to hand-roll identically now lives once in the core binder. `createDuplexClientTransport` adapts the same contracts the other way. |
|
|
1186
1160
|
|
|
@@ -1196,8 +1170,6 @@ _This face declares no `HTTPClientTransport`. It is host-independent and ships f
|
|
|
1196
1170
|
|
|
1197
1171
|
#### Constants
|
|
1198
1172
|
|
|
1199
|
-
A `Shape` cell holds the constant's declared type.
|
|
1200
|
-
|
|
1201
1173
|
| Name | Kind | Signature | Summary |
|
|
1202
1174
|
| -------------------------------- | ----- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1203
1175
|
| `SSE_BUFFERING_HEADER` | const | `"x-accel-buffering"` | Names the reverse-proxy response header controlling buffering of an SSE response. |
|
|
@@ -1223,7 +1195,7 @@ A `Shape` cell holds the constant's declared type.
|
|
|
1223
1195
|
| `readSessionHeader` | function | `(request: Request) => string \| undefined` | Reads the request's `mcp-session-id` header — the session id a stateful transport validates, or `undefined` when absent. |
|
|
1224
1196
|
| `readLastEventId` | function | `(request: Request) => string \| undefined` | Reads the request's `Last-Event-ID` header — the SSE resume cursor a client sends when it reconnects to the resumable `GET {path}` stream, or `undefined` when absent. |
|
|
1225
1197
|
| `rejectUnknownSession` | function | `() => Response` | Builds the stateful transport's "unknown session" rejection — an HTTP `404` carrying a JSON-RPC error body. |
|
|
1226
|
-
| `sendEventStream` | function | `(stream: MCPStreamControllerInterface, sse:
|
|
1198
|
+
| `sendEventStream` | function | `(stream: MCPStreamControllerInterface, sse: SSEStreamInterface) => Promise<void>` | Pumps a controlled held-open exchange onto an open SSE stream — one `data:` event per notification in order, then the terminating response — and end the exchange however the pump leaves. |
|
|
1227
1199
|
| `upgradeRequestPath` | function | `(request: IncomingMessage) => string` | Reads the path (without the query string) of a raw `node:http` protocol-upgrade request — the `createWebSocketServer` upgrade-path match. |
|
|
1228
1200
|
| `extractLines` | function | `(buffer: string, chunk: string) => LineExtraction` | Folds one more chunk of raw stdio bytes into a newline-framed buffer — the shared line-framing step both stdio transports (client and server) read their inbound newline-delimited JSON-RPC messages through. |
|
|
1229
1201
|
| `writeLine` | function | `(output: NodeJS.WritableStream, line: string) => Promise<void>` | Writes one line to a Node writable stream and waits for its completion callback. |
|
|
@@ -1235,11 +1207,6 @@ decoders and the response-error builder are host-independent and ship from `@ork
|
|
|
1235
1207
|
|
|
1236
1208
|
#### Types
|
|
1237
1209
|
|
|
1238
|
-
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
|
|
1239
|
-
optional member and `plus` introducing its call-signature members, and a type alias's own type
|
|
1240
|
-
literal with a union's arms escaped as `\|`.
|
|
1241
|
-
An extended interface's name comes before `plus`, with the members it adds after.
|
|
1242
|
-
|
|
1243
1210
|
| Name | Kind | Signature | Summary |
|
|
1244
1211
|
| ----------------------------- | --------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1245
1212
|
| `MCPHeaderIssue` | interface | `{ header, reason, message }` | Reports one required MCP HTTP header that is absent or disagrees with its server-derived value. |
|
|
@@ -1266,9 +1233,9 @@ connection. `createWebSocketServer` returns an `UpgradeHandler`
|
|
|
1266
1233
|
(`@orkestrel/server`) to register on the spine's `server.upgrade(...)`
|
|
1267
1234
|
seam; it composes the lean `@orkestrel/websocket` RFC 6455 wrapper and pumps
|
|
1268
1235
|
each inbound JSON-RPC request through `mcp.dispatch`.
|
|
1269
|
-
`
|
|
1236
|
+
`createNodeWebSocketClientTransport` is the egress mirror — a
|
|
1270
1237
|
`MCPMessageTransportInterface` an `MCPClient` drives over a `node:http(s)`
|
|
1271
|
-
upgrade. Both `WebSocketServerTransport` and `
|
|
1238
|
+
upgrade. Both `WebSocketServerTransport` and `NodeWebSocketClientTransport` reuse
|
|
1272
1239
|
the same `MCPMessageTransportInterface` the HTTP client transport implements (a
|
|
1273
1240
|
generic bidirectional JSON-RPC channel — `emitter` / `start` / `send` /
|
|
1274
1241
|
`close`, `session` `undefined` for the stateless v1), so the WebSocket and
|
|
@@ -1307,7 +1274,7 @@ neither throws nor delays the stop.
|
|
|
1307
1274
|
|
|
1308
1275
|
```ts
|
|
1309
1276
|
import { createMCPClient, createMCPLegacy, createMCPServer } from '@orkestrel/mcp'
|
|
1310
|
-
import {
|
|
1277
|
+
import { createNodeWebSocketClientTransport, createWebSocketServer } from '@orkestrel/mcp/server'
|
|
1311
1278
|
import { createToolManager } from '@orkestrel/tool'
|
|
1312
1279
|
|
|
1313
1280
|
const mcp = createMCPServer({
|
|
@@ -1319,24 +1286,24 @@ server.upgrade(createWebSocketServer(createMCPLegacy(mcp), { emitter: server.emi
|
|
|
1319
1286
|
|
|
1320
1287
|
// An MCP client connects over the same MCPClient, a WebSocket transport instead of HTTP:
|
|
1321
1288
|
const client = createMCPClient({
|
|
1322
|
-
transport:
|
|
1289
|
+
transport: createNodeWebSocketClientTransport({ url: `ws://127.0.0.1:${port}/mcp` }),
|
|
1323
1290
|
})
|
|
1324
1291
|
await client.connect() // the RFC 6455 handshake, then modern `server/discover` over frames
|
|
1325
1292
|
```
|
|
1326
1293
|
|
|
1327
1294
|
#### Factories
|
|
1328
1295
|
|
|
1329
|
-
| Name
|
|
1330
|
-
|
|
|
1331
|
-
| `createWebSocketServer`
|
|
1332
|
-
| `
|
|
1296
|
+
| Name | Kind | Signature | Summary |
|
|
1297
|
+
| ------------------------------------ | -------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1298
|
+
| `createWebSocketServer` | function | `(mcp: MCPDispatcherInterface, options: WebSocketServerOptions) => UpgradeHandler` | Creates the MCP WebSocket transport ingress — an `UpgradeHandler` that exposes a transport-agnostic `MCPDispatcherInterface` over a WebSocket, the WebSocket mirror of `createMCPRoutes`. Register it on the spine's upgrade seam. |
|
|
1299
|
+
| `createNodeWebSocketClientTransport` | function | `(options: NodeWebSocketClientTransportOptions) => MCPMessageTransportInterface` | Creates the WebSocket client transport for an `MCPClientInterface` — a `MCPMessageTransportInterface` that drives a remote MCP server over a WebSocket. The egress mirror of `createWebSocketServer` and the WebSocket sibling of `createHTTPClientTransport`. |
|
|
1333
1300
|
|
|
1334
1301
|
#### Classes
|
|
1335
1302
|
|
|
1336
|
-
| Name
|
|
1337
|
-
|
|
|
1338
|
-
| `WebSocketServerTransport`
|
|
1339
|
-
| `
|
|
1303
|
+
| Name | Kind | Signature | Summary |
|
|
1304
|
+
| ------------------------------ | ----- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
1305
|
+
| `WebSocketServerTransport` | class | `new (socket: NodeWebSocketInterface) => MCPMessageTransportInterface` | Wraps a `NodeWebSocketInterface` (the RFC 6455 wire wrapper) as a `MCPMessageTransportInterface` — the per-connection JSON-RPC-over-WebSocket server bridge, the bidirectional JSON-RPC message channel `createWebSocketServer` pumps `mcp.dispatch` over and the egress mirror's `NodeWebSocketClientTransport` reuses. |
|
|
1306
|
+
| `NodeWebSocketClientTransport` | class | `new (options: NodeWebSocketClientTransportOptions) => MCPMessageTransportInterface` | Drives a remote MCP server over a WebSocket — a client `MCPMessageTransportInterface` for the Model Context Protocol, the egress mirror of `createWebSocketServer` and the WebSocket sibling of `HTTPClientTransport`. |
|
|
1340
1307
|
|
|
1341
1308
|
#### Constants
|
|
1342
1309
|
|
|
@@ -1350,14 +1317,10 @@ _`upgradeRequestPath` (used by `createWebSocketServer`) is documented under [HTT
|
|
|
1350
1317
|
|
|
1351
1318
|
#### Types
|
|
1352
1319
|
|
|
1353
|
-
|
|
1354
|
-
|
|
1355
|
-
|
|
1356
|
-
|
|
1357
|
-
| Name | Kind | Signature | Summary |
|
|
1358
|
-
| --------------------------------- | --------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1359
|
-
| `WebSocketServerOptions` | interface | `{ emitter, path?, subprotocol? }` | Options for `createWebSocketServer` — the spine lifecycle the ingress follows, plus where the WebSocket upgrade is accepted and the subprotocol negotiated. |
|
|
1360
|
-
| `WebSocketClientTransportOptions` | interface | `{ url, headers? }` | Options for `createWebSocketClientTransport` — the remote MCP WebSocket endpoint and any extra handshake headers. |
|
|
1320
|
+
| Name | Kind | Signature | Summary |
|
|
1321
|
+
| ------------------------------------- | --------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1322
|
+
| `WebSocketServerOptions` | interface | `{ emitter, path?, subprotocol? }` | Options for `createWebSocketServer` — the spine lifecycle the ingress follows, plus where the WebSocket upgrade is accepted and the subprotocol negotiated. |
|
|
1323
|
+
| `NodeWebSocketClientTransportOptions` | interface | `{ headers? }` | Options for `createNodeWebSocketClientTransport` — the remote MCP WebSocket endpoint and any extra handshake headers. |
|
|
1361
1324
|
|
|
1362
1325
|
### stdio transport
|
|
1363
1326
|
|
|
@@ -1510,22 +1473,20 @@ const tools = await client.tools()
|
|
|
1510
1473
|
|
|
1511
1474
|
#### Factories
|
|
1512
1475
|
|
|
1513
|
-
| Name | Kind | Signature | Summary
|
|
1514
|
-
| ---------------------------- | -------- | ------------------------------------------------------------------------------------- |
|
|
1515
|
-
| `createStdioClientTransport` | function | `(options: StdioClientTransportOptions) => StdioClientTransportInterface` | Creates the stdio client transport for an `MCPClientInterface` — a `StdioClientTransportInterface` that spawns and drives a child process MCP server over newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of `createHTTPClientTransport` and `
|
|
1516
|
-
| `createStdioServer` | function | `(mcp: MCPDispatcherInterface, options?: StdioServerOptions) => StdioServerInterface` | Creates the MCP stdio transport ingress — pumps a transport-agnostic `MCPDispatcherInterface` over newline-delimited JSON-RPC on `stdin`/`stdout` (or an injected stream pair), the stdio mirror of `createWebSocketServer`.
|
|
1476
|
+
| Name | Kind | Signature | Summary |
|
|
1477
|
+
| ---------------------------- | -------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1478
|
+
| `createStdioClientTransport` | function | `(options: StdioClientTransportOptions) => StdioClientTransportInterface` | Creates the stdio client transport for an `MCPClientInterface` — a `StdioClientTransportInterface` that spawns and drives a child process MCP server over newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of `createHTTPClientTransport` and `createNodeWebSocketClientTransport`. |
|
|
1479
|
+
| `createStdioServer` | function | `(mcp: MCPDispatcherInterface, options?: StdioServerOptions) => StdioServerInterface` | Creates the MCP stdio transport ingress — pumps a transport-agnostic `MCPDispatcherInterface` over newline-delimited JSON-RPC on `stdin`/`stdout` (or an injected stream pair), the stdio mirror of `createWebSocketServer`. |
|
|
1517
1480
|
|
|
1518
1481
|
#### Classes
|
|
1519
1482
|
|
|
1520
1483
|
| Name | Kind | Signature | Summary |
|
|
1521
1484
|
| ---------------------- | ----- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
1522
|
-
| `StdioClientTransport` | class | `new (options: StdioClientTransportOptions) => StdioClientTransportInterface` | Drives a child process MCP server over newline-delimited JSON-RPC on `stdin`/`stdout` — a `StdioClientTransportInterface`, the stdio sibling of `HTTPClientTransport` and `
|
|
1485
|
+
| `StdioClientTransport` | class | `new (options: StdioClientTransportOptions) => StdioClientTransportInterface` | Drives a child process MCP server over newline-delimited JSON-RPC on `stdin`/`stdout` — a `StdioClientTransportInterface`, the stdio sibling of `HTTPClientTransport` and `NodeWebSocketClientTransport`. |
|
|
1523
1486
|
| `StdioServerTransport` | class | `new (input: NodeJS.ReadableStream, output: NodeJS.WritableStream) => MCPMessageTransportInterface` | Wraps an injectable readable/writable stream pair (`process.stdin`/`process.stdout` in production, a test double in tests) as a `MCPMessageTransportInterface` — the newline-delimited JSON-RPC channel `createStdioServer` pumps `mcp.dispatch` over, the stdio mirror of `WebSocketServerTransport`. |
|
|
1524
1487
|
|
|
1525
1488
|
#### Constants
|
|
1526
1489
|
|
|
1527
|
-
A `Shape` cell holds the constant's declared type.
|
|
1528
|
-
|
|
1529
1490
|
| Name | Kind | Signature | Summary |
|
|
1530
1491
|
| ---------------------- | ----- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
1531
1492
|
| `DEFAULT_MCP_DELIVERY` | const | `10000` | Sets the default bound in milliseconds on one unconfirmed write to a stdio client transport's child `stdin` — the `delivery` a `createStdioClientTransport` caller who supplies none gets. |
|
|
@@ -1537,11 +1498,6 @@ _See `extractLines` / `dispatchLines` under [HTTP transport § Helpers](#helpers
|
|
|
1537
1498
|
|
|
1538
1499
|
#### Types
|
|
1539
1500
|
|
|
1540
|
-
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
|
|
1541
|
-
optional member and `plus` introducing its call-signature members, and a type alias's own type
|
|
1542
|
-
literal with a union's arms escaped as `\|`.
|
|
1543
|
-
An extended interface's name comes before `plus`, with the members it adds after.
|
|
1544
|
-
|
|
1545
1501
|
| Name | Kind | Signature | Summary |
|
|
1546
1502
|
| ------------------------------- | --------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1547
1503
|
| `StdioClientTransportInterface` | interface | `{ evidence }` | Declares the contract `createStdioClientTransport` returns — a `MCPMessageTransportInterface` that also reports the supervised child's stderr tail, the diagnostic a child that dies at startup leaves behind. |
|
|
@@ -1557,19 +1513,19 @@ The **browser transport** (`src/browser`, through the `@src/browser` barrel /
|
|
|
1557
1513
|
Client-only transports drive a remote MCP server from the browser,
|
|
1558
1514
|
over the same `MCPMessageTransportInterface` the Node face's transports
|
|
1559
1515
|
implement, so `createMCPClient` consumes either identically.
|
|
1560
|
-
`
|
|
1516
|
+
`createBrowserWebSocketClientTransport` drives the native `WebSocket` global (the
|
|
1561
1517
|
host performs the RFC 6455 handshake, so this face carries none of the
|
|
1562
1518
|
Node client's `node:crypto` / `node:http(s)` machinery).
|
|
1563
|
-
`createHTTPClientTransport` returns the core `HTTPClientTransport` — one class,
|
|
1564
|
-
from `@orkestrel/mcp`
|
|
1519
|
+
`createHTTPClientTransport` returns the core `HTTPClientTransport` — one factory and one class,
|
|
1520
|
+
published from `@orkestrel/mcp` for both faces, because the class touches
|
|
1565
1521
|
`fetch`, `Response`, `AbortController`, `AbortSignal`, and `WeakMap` alone. Every header rule,
|
|
1566
1522
|
every SEP-2243 `x-mcp-header` decision, and the non-success rejection are therefore literally
|
|
1567
1523
|
the same code on both faces rather than two copies that agree. It honors the
|
|
1568
1524
|
same `mcp-session-id` semantics, so a browser client interoperates with an
|
|
1569
|
-
`MCPSession`-based server unchanged.
|
|
1570
|
-
|
|
1571
|
-
|
|
1572
|
-
|
|
1525
|
+
`MCPSession`-based server unchanged. Each face names its WebSocket client for its host
|
|
1526
|
+
over the core `WebSocketClientTransportOptions`, because the handshake controls differ: a
|
|
1527
|
+
page offers `protocols` to `createBrowserWebSocketClientTransport`, and a Node process sets
|
|
1528
|
+
`headers` on `createNodeWebSocketClientTransport`.
|
|
1573
1529
|
|
|
1574
1530
|
A browser deployment served from a non-loopback origin must list the page origin in the shared
|
|
1575
1531
|
`origin.origins` value passed to the server's enforcement sites, or delegate validation with
|
|
@@ -1677,13 +1633,13 @@ in a worker, and answers `undefined` there — the same answer it gives a page w
|
|
|
1677
1633
|
ships no registry.
|
|
1678
1634
|
|
|
1679
1635
|
```ts
|
|
1680
|
-
import { createMCPClient } from '@orkestrel/mcp'
|
|
1681
|
-
import {
|
|
1636
|
+
import { createHTTPClientTransport, createMCPClient } from '@orkestrel/mcp'
|
|
1637
|
+
import { createBrowserWebSocketClientTransport } from '@orkestrel/mcp/browser'
|
|
1682
1638
|
|
|
1683
1639
|
const ws = createMCPClient({
|
|
1684
1640
|
// No `protocols` needed — defaults to MCP_WEBSOCKET_SUBPROTOCOL ('mcp'), which
|
|
1685
1641
|
// createWebSocketServer selects from the offered list. Override only for foreign servers.
|
|
1686
|
-
transport:
|
|
1642
|
+
transport: createBrowserWebSocketClientTransport({ url: 'ws://localhost:3000/mcp' }),
|
|
1687
1643
|
})
|
|
1688
1644
|
await ws.connect() // the browser handshakes, then modern `server/discover` runs over WS frames
|
|
1689
1645
|
|
|
@@ -1696,28 +1652,25 @@ const tools = await http.tools()
|
|
|
1696
1652
|
|
|
1697
1653
|
#### Factories
|
|
1698
1654
|
|
|
1699
|
-
| Name
|
|
1700
|
-
|
|
|
1701
|
-
| `
|
|
1702
|
-
| `
|
|
1703
|
-
| `
|
|
1704
|
-
| `
|
|
1705
|
-
| `
|
|
1706
|
-
| `
|
|
1707
|
-
| `createModelContext` | function | `(options?: ModelContextOptions) => ModelContextInterface \| undefined` | Creates the bridge between a tool registry and a document's WebMCP registry, or reports that the document exposes none. |
|
|
1655
|
+
| Name | Kind | Signature | Summary |
|
|
1656
|
+
| --------------------------------------- | -------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1657
|
+
| `createBrowserWebSocketClientTransport` | function | `(options: BrowserWebSocketClientTransportOptions) => MCPMessageTransportInterface` | Creates the browser-face WebSocket client transport for an `MCPClientInterface` — a `MCPMessageTransportInterface` that drives a remote MCP server over the native `WebSocket` global. This factory is the browser sibling of the Node face's `createNodeWebSocketClientTransport` (`@orkestrel/mcp/server`). |
|
|
1658
|
+
| `createMessagePortTransport` | function | `(options: MessagePortTransportOptions) => MCPTransportInterface` | Creates the browser-face `MessagePort` transport — a `MCPTransportInterface` over a native `MessagePort`, the symmetric carrier that works as either a server or a client transport depending on which binder (`bindServer` or `bindClient`) it is handed to. |
|
|
1659
|
+
| `createScopeServer` | function | `(options: ScopeServerOptions, scope?: WorkerScopeInterface) => ScopeServerInterface` | Creates an `MCPServer` hosted inside a worker scope and wires that scope's message events to it — the browser face's bootstrap, and the twin of the Node face's `createStdioServer`. |
|
|
1660
|
+
| `createScopeTransport` | function | `(scope: WorkerScopeInterface) => ScopeTransportInterface` | Adapts a hostable `WorkerScopeInterface` (`self` in a dedicated Web Worker, or any structurally matching double) into a `ScopeTransportInterface` — the implicit, portless message channel `createScopeServer` binds for the dedicated-worker shape. |
|
|
1661
|
+
| `createPageServer` | function | `(options: PageServerOptions) => PageServerInterface` | Creates an `MCPServer` hosted inside the calling page and hands back the client bound to it — the page twin of `createScopeServer`, and the in-page MCP pair as one call. |
|
|
1662
|
+
| `createModelContext` | function | `(options?: ModelContextOptions) => ModelContextInterface \| undefined` | Creates the bridge between a tool registry and a document's WebMCP registry, or reports that the document exposes none. |
|
|
1708
1663
|
|
|
1709
1664
|
#### Classes
|
|
1710
1665
|
|
|
1711
|
-
| Name
|
|
1712
|
-
|
|
|
1713
|
-
| `
|
|
1714
|
-
| `MessagePortTransport`
|
|
1715
|
-
| `ModelContext`
|
|
1666
|
+
| Name | Kind | Signature | Summary |
|
|
1667
|
+
| --------------------------------- | ----- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1668
|
+
| `BrowserWebSocketClientTransport` | class | `new (options: BrowserWebSocketClientTransportOptions) => MCPMessageTransportInterface` | Drives a remote MCP server over the native `WebSocket` global from the browser face, as a client `MCPMessageTransportInterface`. This class is the browser sibling of the Node face's `NodeWebSocketClientTransport`. |
|
|
1669
|
+
| `MessagePortTransport` | class | `new (options: MessagePortTransportOptions) => MCPTransportInterface` | Carries the Model Context Protocol over a native `MessagePort` from the browser face — a `MCPTransportInterface`, the genuinely new capability this face adds: MCP over `postMessage`. |
|
|
1670
|
+
| `ModelContext` | class | `new (document: WebMCPDocument, options?: ModelContextOptions) => ModelContextInterface` | Bridges a `ToolManagerInterface` and a document's WebMCP tool registry — the `ModelContextInterface` `createModelContext` returns. |
|
|
1716
1671
|
|
|
1717
1672
|
#### Constants
|
|
1718
1673
|
|
|
1719
|
-
A `Shape` cell holds the constant's declared type.
|
|
1720
|
-
|
|
1721
1674
|
| Name | Kind | Signature | Summary |
|
|
1722
1675
|
| ---------------------------- | ----- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1723
1676
|
| `DEFAULT_MCP_SERVER_NAME` | const | `"@orkestrel/mcp"` | Supplies the default server name `createScopeServer` reports (`initialize`'s `serverInfo.name`) when `options.name` is omitted. |
|
|
@@ -1752,39 +1705,34 @@ The SSE decoders `decodeEvent` and `readEventStream` are host-independent and sh
|
|
|
1752
1705
|
|
|
1753
1706
|
#### Types
|
|
1754
1707
|
|
|
1755
|
-
|
|
1756
|
-
|
|
1757
|
-
|
|
1758
|
-
|
|
1759
|
-
|
|
1760
|
-
|
|
|
1761
|
-
|
|
|
1762
|
-
| `
|
|
1763
|
-
| `
|
|
1764
|
-
| `
|
|
1765
|
-
| `
|
|
1766
|
-
| `
|
|
1767
|
-
| `
|
|
1768
|
-
| `
|
|
1769
|
-
| `
|
|
1770
|
-
| `
|
|
1771
|
-
| `
|
|
1772
|
-
| `
|
|
1773
|
-
| `
|
|
1774
|
-
| `
|
|
1775
|
-
| `
|
|
1776
|
-
| `
|
|
1777
|
-
| `
|
|
1778
|
-
| `
|
|
1779
|
-
| `
|
|
1780
|
-
| `
|
|
1781
|
-
| `
|
|
1782
|
-
| `
|
|
1783
|
-
| `ModelContextEventMap` | type | `{ readonly change: readonly []; readonly activate: readonly [name: string]; readonly abort: readonly [name: string]; }` | Reports changes and execution events from a WebMCP registry. |
|
|
1784
|
-
| `ModelContextOptions` | interface | `{ document?, on?, error? }` | Options for `createModelContext` — the document to bridge and the emitter's initial wiring. |
|
|
1785
|
-
| `ModelContextPublishOptions` | interface | `{ origins? }` | Options for `ModelContextInterface.publish` — the origins each registration is exposed to. |
|
|
1786
|
-
| `ModelContextAdoptOptions` | interface | `{ origins?, debug? }` | Options for `ModelContextInterface.adopt` — the origins and debugging tools to include. |
|
|
1787
|
-
| `ModelContextInterface` | interface | `{ emitter, publish(), adopt(), destroy() }` | Represents the bridge between a `ToolManagerInterface` and a document's WebMCP registry — what `createModelContext` returns. |
|
|
1708
|
+
| Name | Kind | Signature | Summary |
|
|
1709
|
+
| ---------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1710
|
+
| `BrowserWebSocketClientTransportOptions` | interface | `{ protocols? }` | Options for `createBrowserWebSocketClientTransport` (browser face) — the remote MCP WebSocket endpoint and any negotiated subprotocols. |
|
|
1711
|
+
| `MessagePortTransportOptions` | interface | `{ port }` | Options for `createMessagePortTransport` — the native `MessagePort` a `MessagePortTransport` sends and listens on. |
|
|
1712
|
+
| `WorkerScopeInterface` | interface | `{ postMessage(), addEventListener(), removeEventListener() }` | Describes the structural shape `createScopeServer` needs from a hostable scope — `self` in a dedicated Web Worker or a Service Worker (or any double matching this shape). |
|
|
1713
|
+
| `ScopeTransportInterface` | interface | `{ deliver() }` | Adapts a message-event-bearing scope (`self` in a dedicated Web Worker, or any object shaped the same way) as a duplex `MCPTransportInterface` — the internal carrier `createScopeServer` binds to route the implicit (portless) message channel, plus the `deliver` entry point the scope's own `message` listener pushes an inbound string through (the scope itself never registers `listen`'s handler for the caller — the scope server's dispatcher does, through this `deliver`). |
|
|
1714
|
+
| `ScopeServerInterface` | interface | `{ stop() }` | Represents one MCP server hosted inside a worker scope — what `createScopeServer` returns. |
|
|
1715
|
+
| `ScopeServerOptions` | interface | `{ tools, name?, version?, accept? }` | Options for `createScopeServer` — the live `ToolManagerInterface` to expose plus the optional server identity, mirroring `createMCPServer`'s `MCPServerOptions` (`@orkestrel/mcp`) but with `name`/`version` optional (defaulting to `DEFAULT_MCP_SERVER_NAME` / `DEFAULT_MCP_SERVER_VERSION`). |
|
|
1716
|
+
| `PageServerOptions` | interface | `{ tools, name?, version?, client? }` | Options for `createPageServer` — the live `ToolManagerInterface` to expose, the optional server identity, and the optional settings for the client half the pair owns. |
|
|
1717
|
+
| `PageServerInterface` | interface | `{ client, stop() }` | Represents one MCP server hosted inside the calling page — what `createPageServer` returns. |
|
|
1718
|
+
| `WebMCPAnnotations` | interface | `{ readOnlyHint?, untrustedContentHint?, consequentialHint?, debugging? }` | Describes a tool's observable effects as the WebMCP registry declares them. |
|
|
1719
|
+
| `WebMCPDescriptor` | interface | `{ name, title?, description, inputSchema?, annotations? }` | Describes the members a WebMCP tool carries into the registry and back out of it. |
|
|
1720
|
+
| `WebMCPHandlerOptions` | interface | `{ signal }` | Carries the execution signal the WebMCP registry hands a registered tool's callback. |
|
|
1721
|
+
| `WebMCPExecuteHandler` | type | `(input: Readonly<Record<string, unknown>>, options: WebMCPHandlerOptions) => Promise<unknown>` | Runs one registered WebMCP tool with the caller's input and the registry's signal. |
|
|
1722
|
+
| `WebMCPTool` | interface | `{ execute }` | Describes one tool as handed to the WebMCP registry for registration. |
|
|
1723
|
+
| `WebMCPRegisteredTool` | interface | `{ window, origin }` | Describes one tool as the WebMCP registry reports it back. |
|
|
1724
|
+
| `WebMCPRegisterOptions` | interface | `{ exposedTo?, signal? }` | Options for the WebMCP registry's `registerTool` — the exposure list and the unregistration signal. |
|
|
1725
|
+
| `WebMCPToolsOptions` | interface | `{ fromOrigins? }` | Options for the WebMCP registry's `getTools` — the origins whose tools are read. |
|
|
1726
|
+
| `WebMCPExecuteOptions` | interface | `{ signal? }` | Options for the WebMCP registry's `executeTool` — the caller's cancellation signal. |
|
|
1727
|
+
| `WebMCPToolEvent` | interface | `{ toolName }` | Carries the tool name a WebMCP execution event reports. |
|
|
1728
|
+
| `WebMCPRegistryInterface` | interface | `{ registerTool(), getTools(), executeTool(), addEventListener(), removeEventListener() }` | Represents the WebMCP tool registry a document exposes as `document.modelContext`. |
|
|
1729
|
+
| `WebMCPDocument` | interface | `{ modelContext }` | Describes a document that exposes the WebMCP tool registry. |
|
|
1730
|
+
| `WebMCPProjection` | interface | `{ tool, descriptor }` | Pairs one tool with the WebMCP descriptor a registry advertises for it. |
|
|
1731
|
+
| `ModelContextEventMap` | type | `{ readonly change: readonly []; readonly activate: readonly [name: string]; readonly abort: readonly [name: string]; }` | Reports changes and execution events from a WebMCP registry. |
|
|
1732
|
+
| `ModelContextOptions` | interface | `{ document?, on?, error? }` | Options for `createModelContext` — the document to bridge and the emitter's initial wiring. |
|
|
1733
|
+
| `ModelContextPublishOptions` | interface | `{ origins? }` | Options for `ModelContextInterface.publish` — the origins each registration is exposed to. |
|
|
1734
|
+
| `ModelContextAdoptOptions` | interface | `{ origins?, debug? }` | Options for `ModelContextInterface.adopt` — the origins and debugging tools to include. |
|
|
1735
|
+
| `ModelContextInterface` | interface | `{ emitter, publish(), adopt(), destroy() }` | Represents the bridge between a `ToolManagerInterface` and a document's WebMCP registry — what `createModelContext` returns. |
|
|
1788
1736
|
|
|
1789
1737
|
_This face declares no `HTTPClientTransportOptions`. It is host-independent and ships from
|
|
1790
1738
|
`@orkestrel/mcp`; see [Core § Types](#types)._
|
|
@@ -1819,10 +1767,10 @@ Array.from(walkHeaderAnnotations({ properties: { region: { 'x-mcp-header': 'Regi
|
|
|
1819
1767
|
The browser face exports the scope entities used by `createScopeServer` and
|
|
1820
1768
|
`createScopeTransport`.
|
|
1821
1769
|
|
|
1822
|
-
| Name | Kind | Signature
|
|
1823
|
-
| ---------------- | ----- |
|
|
1824
|
-
| `ScopeServer` | class | `new (options: ScopeServerOptions, scope?:
|
|
1825
|
-
| `ScopeTransport` | class | `new (scope:
|
|
1770
|
+
| Name | Kind | Signature | Summary |
|
|
1771
|
+
| ---------------- | ----- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
|
1772
|
+
| `ScopeServer` | class | `new (options: ScopeServerOptions, scope?: WorkerScopeInterface) => ScopeServerInterface` | Owns a scope's implicit binding and every accepted client-port binding. |
|
|
1773
|
+
| `ScopeTransport` | class | `new (scope: WorkerScopeInterface) => ScopeTransportInterface` | Adapts a scope's implicit channel to replaceable MCP transport callbacks. |
|
|
1826
1774
|
|
|
1827
1775
|
The server face exports the session table and serialized carrier adapter.
|
|
1828
1776
|
`createMCPSession` creates an isolated `MCPSessionStore` unless `options.store` supplies
|
|
@@ -1895,12 +1843,11 @@ implementing class exposes exactly its interface's methods: `MCPServer` ↔
|
|
|
1895
1843
|
its subject's surface would not be substitutable for it),
|
|
1896
1844
|
`MCPMethodManager` ↔ `MCPMethodManagerInterface`,
|
|
1897
1845
|
`MCPClient` ↔ `MCPClientInterface`, the transports
|
|
1898
|
-
`HTTPClientTransport` (`src/core`, host-independent and returned by
|
|
1899
|
-
`createHTTPClientTransport`), `WebSocketServerTransport` / `
|
|
1846
|
+
`HTTPClientTransport` (`src/core`, host-independent and returned by
|
|
1847
|
+
`createHTTPClientTransport`), `WebSocketServerTransport` / `NodeWebSocketClientTransport`
|
|
1900
1848
|
/ `StdioClientTransport` / `StdioServerTransport` (`src/server`), and the browser face's
|
|
1901
|
-
|
|
1902
|
-
|
|
1903
|
-
JSON-RPC carrier — only the wire framing / host differs, so they add no new
|
|
1849
|
+
`BrowserWebSocketClientTransport` (`src/browser`) ↔ `MCPMessageTransportInterface` (they
|
|
1850
|
+
all share the one generic bidirectional JSON-RPC carrier — only the wire framing / host differs, so they add no new
|
|
1904
1851
|
behavioral interface), and the session entity `MCPSession` ↔
|
|
1905
1852
|
`MCPSessionInterface` (the folded replay log is private to it), and the stream
|
|
1906
1853
|
entities `MCPStreamController` ↔ `MCPStreamControllerInterface` /
|
|
@@ -1934,7 +1881,7 @@ Both take an optional `MCPDispatchOptions` bag carrying `signal` and asserted
|
|
|
1934
1881
|
`caller`, so every existing caller compiles unchanged.
|
|
1935
1882
|
|
|
1936
1883
|
`dispatch` carries an overload per argument arm rather than one union, so the answer's type
|
|
1937
|
-
follows the argument's arm: a `JSONRPCRequest` resolves a response or a held-open
|
|
1884
|
+
follows the argument's arm, each one an `@orkestrel/jsonrpc` type: a `JSONRPCRequest` resolves a response or a held-open
|
|
1938
1885
|
controlled stream and never `undefined`; a `JSONRPCNotification` resolves `undefined`
|
|
1939
1886
|
and never a response; and the union arm — for a transport that narrowed no
|
|
1940
1887
|
further than `JSONRPCInvocation` — admits each of them. The Returns column in this table
|
|
@@ -2092,7 +2039,8 @@ why its methods answer `-32601` rather than a bespoke refusal.
|
|
|
2092
2039
|
This example registers and looks up a modern method handler.
|
|
2093
2040
|
|
|
2094
2041
|
```ts
|
|
2095
|
-
import { buildJSONRPCResult
|
|
2042
|
+
import { buildJSONRPCResult } from '@orkestrel/jsonrpc'
|
|
2043
|
+
import { createMCPServer } from '@orkestrel/mcp'
|
|
2096
2044
|
import { createToolManager } from '@orkestrel/tool'
|
|
2097
2045
|
|
|
2098
2046
|
const server = createMCPServer({
|
|
@@ -2260,8 +2208,7 @@ list are frozen. Hostile snapshot failures surface as `MCPError` `-32602`, never
|
|
|
2260
2208
|
implementation error.
|
|
2261
2209
|
|
|
2262
2210
|
```ts
|
|
2263
|
-
import { createMCPClient } from '@orkestrel/mcp'
|
|
2264
|
-
import { createHTTPClientTransport } from '@orkestrel/mcp/server'
|
|
2211
|
+
import { createHTTPClientTransport, createMCPClient } from '@orkestrel/mcp'
|
|
2265
2212
|
|
|
2266
2213
|
const client = createMCPClient({
|
|
2267
2214
|
transport: createHTTPClientTransport({ url: 'http://localhost:3000/mcp' }),
|
|
@@ -2372,8 +2319,8 @@ that connection and emits once for it.
|
|
|
2372
2319
|
"Release resources" is a per-transport promise, so here is what each carrier in
|
|
2373
2320
|
this package actually gives up. The `HTTPClientTransport`s abort every
|
|
2374
2321
|
in-flight `fetch` and response reader they still hold, clear that set, and drop
|
|
2375
|
-
the negotiated protocol version.
|
|
2376
|
-
from the socket before closing it; the browser one also discards its pre-open
|
|
2322
|
+
the negotiated protocol version. `BrowserWebSocketClientTransport` and
|
|
2323
|
+
`NodeWebSocketClientTransport` unsubscribe from the socket before closing it; the browser one also discards its pre-open
|
|
2377
2324
|
queue, so nothing queued against the ended connection rides the next one, and
|
|
2378
2325
|
the Node one also destroys an upgrade request still on the wire.
|
|
2379
2326
|
`WebSocketServerTransport` unsubscribes before it runs the close handshake, so a
|
|
@@ -2407,7 +2354,7 @@ promise rather than throwing. The client cannot tell a rejection from a throw, w
|
|
|
2407
2354
|
why the obligation lives here rather than in a guard it could not write.
|
|
2408
2355
|
|
|
2409
2356
|
```ts
|
|
2410
|
-
import { createHTTPClientTransport } from '@orkestrel/mcp
|
|
2357
|
+
import { createHTTPClientTransport } from '@orkestrel/mcp'
|
|
2411
2358
|
|
|
2412
2359
|
const transport = createHTTPClientTransport({ url: 'http://localhost:3000/mcp' })
|
|
2413
2360
|
transport.emitter.on('message', (message) => log(message))
|
|
@@ -2518,7 +2465,7 @@ stdio.start() // a repeat arms nothing further — one reply per request
|
|
|
2518
2465
|
stdio.stop() // unbind, release stdin, and end this handle
|
|
2519
2466
|
```
|
|
2520
2467
|
|
|
2521
|
-
#### `
|
|
2468
|
+
#### `WorkerScopeInterface`
|
|
2522
2469
|
|
|
2523
2470
|
The hostable scope `createScopeServer` binds — `self` in a dedicated Web Worker or a Service
|
|
2524
2471
|
Worker, or any object of this shape. No class implements it: the host does. It declares the
|
|
@@ -2730,7 +2677,7 @@ if (bridge !== undefined) {
|
|
|
2730
2677
|
The foreign registry itself, as `document.modelContext` exposes it, declared here because
|
|
2731
2678
|
TypeScript's DOM library declares none of it. No class implements it: a user agent does, and
|
|
2732
2679
|
`isWebMCPDocument` is what narrows a document onto it. The declaration carries the members the
|
|
2733
|
-
bridge dereferences and stops there, exactly as `
|
|
2680
|
+
bridge dereferences and stops there, exactly as `WorkerScopeInterface` carries what
|
|
2734
2681
|
`createScopeServer` touches — a real registry satisfies it structurally and so does an
|
|
2735
2682
|
IDL-faithful double. Reach it directly only to do something `ModelContextInterface` does not;
|
|
2736
2683
|
the bridge is the supported path, and it is what owns the registration lifetime.
|
|
@@ -2929,10 +2876,9 @@ the transports unchanged — only the injected `MCPMessageTransportInterface`
|
|
|
2929
2876
|
differs.
|
|
2930
2877
|
|
|
2931
2878
|
```ts
|
|
2932
|
-
import { createMCPClient } from '@orkestrel/mcp'
|
|
2879
|
+
import { createHTTPClientTransport, createMCPClient } from '@orkestrel/mcp'
|
|
2933
2880
|
import {
|
|
2934
|
-
|
|
2935
|
-
createWebSocketClientTransport,
|
|
2881
|
+
createNodeWebSocketClientTransport,
|
|
2936
2882
|
createStdioClientTransport,
|
|
2937
2883
|
} from '@orkestrel/mcp/server'
|
|
2938
2884
|
|
|
@@ -2940,7 +2886,7 @@ const http = createMCPClient({
|
|
|
2940
2886
|
transport: createHTTPClientTransport({ url: 'http://localhost:3000/mcp' }),
|
|
2941
2887
|
})
|
|
2942
2888
|
const ws = createMCPClient({
|
|
2943
|
-
transport:
|
|
2889
|
+
transport: createNodeWebSocketClientTransport({ url: 'ws://localhost:3000/mcp' }),
|
|
2944
2890
|
})
|
|
2945
2891
|
const stdio = createMCPClient({
|
|
2946
2892
|
transport: createStdioClientTransport({ command: 'node', args: ['./server.js'] }),
|
|
@@ -2954,16 +2900,19 @@ await stdio.connect()
|
|
|
2954
2900
|
### Build response envelopes and validate wire messages directly
|
|
2955
2901
|
|
|
2956
2902
|
This example uses the response builders and wire guards that the `dispatch` and
|
|
2957
|
-
`handle` methods compose internally
|
|
2903
|
+
`handle` methods compose internally: the JSON-RPC ones from `@orkestrel/jsonrpc` and the MCP
|
|
2904
|
+
ones from this package. Use them in a test or custom transport.
|
|
2958
2905
|
|
|
2959
2906
|
```ts
|
|
2960
2907
|
import {
|
|
2961
|
-
buildInitializeResult,
|
|
2962
2908
|
buildJSONRPCError,
|
|
2963
2909
|
buildJSONRPCResult,
|
|
2964
|
-
buildToolDescriptors,
|
|
2965
2910
|
isJSONRPCMessage,
|
|
2966
2911
|
isJSONRPCResponse,
|
|
2912
|
+
} from '@orkestrel/jsonrpc'
|
|
2913
|
+
import {
|
|
2914
|
+
buildInitializeResult,
|
|
2915
|
+
buildToolDescriptors,
|
|
2967
2916
|
isMCPError,
|
|
2968
2917
|
isMCPToolError,
|
|
2969
2918
|
MCPError,
|
|
@@ -3237,7 +3186,7 @@ worker.stop()
|
|
|
3237
3186
|
#### Drive an explicit worker scope
|
|
3238
3187
|
|
|
3239
3188
|
Passing `scope` explicitly is the same wiring over an object you supply — this
|
|
3240
|
-
runnable fence drives it with a minimal `
|
|
3189
|
+
runnable fence drives it with a minimal `WorkerScopeInterface` (the exact
|
|
3241
3190
|
shape a real worker's `self` satisfies) plus a real `new MessageChannel()`
|
|
3242
3191
|
standing in for a Service-Worker-shaped client connection, so `tools/list`
|
|
3243
3192
|
genuinely round-trips with no worker harness:
|
|
@@ -3665,7 +3614,7 @@ while the previous frame is unread, coalesce into one.
|
|
|
3665
3614
|
built-in tools producer. The consumer producer advances on the stream's demand. A producer
|
|
3666
3615
|
failure terminates the stream after the notifications it already produced. A consumer filter
|
|
3667
3616
|
that is malformed, and one claiming `toolsListChanged: true`, are both invalid: construction
|
|
3668
|
-
throws `MCPError` with `JSONRPC_INVALID_PARAMS` (`-32602`). Consumer-produced tools
|
|
3617
|
+
throws `MCPError` with `@orkestrel/jsonrpc`'s `JSONRPC_INVALID_PARAMS` code (`-32602`). Consumer-produced tools
|
|
3669
3618
|
notifications are dropped, so the tools family has only the registry as its source. The
|
|
3670
3619
|
built-in owns wire acknowledgement, filtering, id stamping, and graceful closure. A producer
|
|
3671
3620
|
only yields project notifications and ends its iterable when the source closes; while idle it
|
|
@@ -3696,8 +3645,8 @@ is this package's reading of an under-specified extension point rather than sett
|
|
|
3696
3645
|
[Declared conformance gaps](#declared-conformance-gaps) records the search that ended there.
|
|
3697
3646
|
|
|
3698
3647
|
```ts
|
|
3648
|
+
import type { JSONRPCNotification } from '@orkestrel/jsonrpc'
|
|
3699
3649
|
import {
|
|
3700
|
-
type JSONRPCNotification,
|
|
3701
3650
|
buildSubscriptionAcknowledgement,
|
|
3702
3651
|
buildSubscriptionFilter,
|
|
3703
3652
|
buildSubscriptionResult,
|
|
@@ -3781,8 +3730,8 @@ The helpers behind that path are `buildSubscriptionFilter` and
|
|
|
3781
3730
|
`matchesSubscriptionNotification`, the ones the other families use, with `enabled` supplied:
|
|
3782
3731
|
|
|
3783
3732
|
```ts
|
|
3733
|
+
import type { JSONRPCNotification } from '@orkestrel/jsonrpc'
|
|
3784
3734
|
import {
|
|
3785
|
-
type JSONRPCNotification,
|
|
3786
3735
|
buildSubscriptionFilter,
|
|
3787
3736
|
isMCPTaskNotification,
|
|
3788
3737
|
matchesSubscriptionNotification,
|
|
@@ -4423,11 +4372,11 @@ disconnected. Spend `options.signal` on work that must finish before the answer
|
|
|
4423
4372
|
and give the task's own work a lifetime the manager owns.
|
|
4424
4373
|
|
|
4425
4374
|
```ts
|
|
4375
|
+
import { isJSONRPCError } from '@orkestrel/jsonrpc'
|
|
4426
4376
|
import {
|
|
4427
4377
|
createMCPServer,
|
|
4428
4378
|
DEFAULT_MCP_LIMITS,
|
|
4429
4379
|
digestJSON,
|
|
4430
|
-
isJSONRPCError,
|
|
4431
4380
|
isMCPTaskDetail,
|
|
4432
4381
|
isMCPTaskResult,
|
|
4433
4382
|
isMCPTaskStatus,
|
|
@@ -4762,7 +4711,7 @@ counterpart and the modern seam registers no `ping`. `tools/list` and `tools/cal
|
|
|
4762
4711
|
acquire modern request metadata, run through the same dispatcher a modern request runs through,
|
|
4763
4712
|
and have the answer projected back into the unstamped legacy shape. Every arm answers under the
|
|
4764
4713
|
message bound the wrapped dispatcher advertises: an invocation outside it earns that
|
|
4765
|
-
dispatcher's own id
|
|
4714
|
+
dispatcher's own `-32600` with `id: null`, locally answered and forwarded alike. Every other method is
|
|
4766
4715
|
refused with `-32601` at the door.
|
|
4767
4716
|
|
|
4768
4717
|
**That fixed set is the whole legacy era, so the modern-only surfaces do not exist for a legacy
|
|
@@ -4920,8 +4869,11 @@ const legacyResult = modernResultToLegacy(result)
|
|
|
4920
4869
|
Wrap the transport explicitly when the peer exposes only the legacy handshake:
|
|
4921
4870
|
|
|
4922
4871
|
```ts
|
|
4923
|
-
import {
|
|
4924
|
-
|
|
4872
|
+
import {
|
|
4873
|
+
createHTTPClientTransport,
|
|
4874
|
+
createMCPClient,
|
|
4875
|
+
createMCPLegacyClientTransport,
|
|
4876
|
+
} from '@orkestrel/mcp'
|
|
4925
4877
|
|
|
4926
4878
|
const carrier = createHTTPClientTransport({ url: 'https://legacy.example/mcp' })
|
|
4927
4879
|
const transport = createMCPLegacyClientTransport(carrier, { version: '2025-06-18' })
|
|
@@ -4971,7 +4923,7 @@ Passing a legacy revision to
|
|
|
4971
4923
|
- [The WebMCP projections and descriptor matching a bridge reconciles against](../tests/src/browser/helpers.test.ts)
|
|
4972
4924
|
- [The WebMCP registry, document, and tool-event narrowing guards](../tests/src/browser/validators.test.ts)
|
|
4973
4925
|
- [The message-port transport contract over a real `MessageChannel`](../tests/src/browser/transports/MessagePortTransport.test.ts)
|
|
4974
|
-
- [The WebSocket client transport releasing its socket on close and rejecting a send the channel cannot carry](../tests/src/browser/transports/
|
|
4926
|
+
- [The WebSocket client transport releasing its socket on close and rejecting a send the channel cannot carry](../tests/src/browser/transports/BrowserWebSocketClientTransport.test.ts)
|
|
4975
4927
|
- [The server face composed end to end over a real `node:http` listener](../tests/src/server/integration.test.ts)
|
|
4976
4928
|
- [HTTP response lifecycle composition](../tests/src/server/HTTPDisconnect.test.ts)
|
|
4977
4929
|
- [HTTP handler integration](../tests/src/server/handlers.test.ts)
|
|
@@ -5567,20 +5519,19 @@ the exact statement:
|
|
|
5567
5519
|
'2.0', … }` with exactly one of `result` / `error`. The success arm always
|
|
5568
5520
|
carries an `id`, echoing the request's, because a result answers a request and
|
|
5569
5521
|
a request always has one. The error arm is the only arm whose `id` may be
|
|
5570
|
-
|
|
5571
|
-
|
|
5572
|
-
|
|
5573
|
-
|
|
5574
|
-
admits no `null`.
|
|
5522
|
+
`null`, which is what a `handle` parse or invalid-request failure produces,
|
|
5523
|
+
because neither could read an id to echo. JSON-RPC 2.0 § 5 requires it, and
|
|
5524
|
+
`@orkestrel/jsonrpc`'s `JSONRPCErrorResponse` type states it: `id: JSONRPCId | null`,
|
|
5525
|
+
where `JSONRPCId` admits no `null`.
|
|
5575
5526
|
`handle` serializes that envelope with `JSON.stringify` and returns the
|
|
5576
5527
|
string. A held-open answer is the other arm of the same return: `dispatch`
|
|
5577
5528
|
resolves an `MCPStream` and `handle` its serialized `MCPTextStream` mirror,
|
|
5578
5529
|
narrowed apart at one point (`Symbol.asyncIterator in result`). The stream's
|
|
5579
5530
|
`return` value is the terminating response and obeys this same envelope, and its
|
|
5580
|
-
`yield` type is `JSONRPCNotification`, so no stream can carry a call the peer is
|
|
5531
|
+
`yield` type is `@orkestrel/jsonrpc`'s `JSONRPCNotification`, so no stream can carry a call the peer is
|
|
5581
5532
|
expected to answer.
|
|
5582
5533
|
3. **Notifications yield no response.** A call with no `id` is a
|
|
5583
|
-
`JSONRPCNotification`, a type distinct from `JSONRPCRequest` and unassignable to
|
|
5534
|
+
`JSONRPCNotification` from `@orkestrel/jsonrpc`, a type distinct from `JSONRPCRequest` and unassignable to
|
|
5584
5535
|
it: `dispatch` emits `request` (whose id argument is `undefined`, beside the
|
|
5585
5536
|
structural era) and then
|
|
5586
5537
|
resolves `undefined` whatever the method (`ping`, `notifications/initialized`,
|
|
@@ -5640,7 +5591,7 @@ the exact statement:
|
|
|
5640
5591
|
registration rather than by a precedence rule, and there is no second
|
|
5641
5592
|
dispatch path. An id-bearing request whose method resolves to `undefined`
|
|
5642
5593
|
(modern) or falls off `MCPLegacy`'s fixed set resolves a
|
|
5643
|
-
`JSONRPC_METHOD_NOT_FOUND` error whose message names the method. The modern
|
|
5594
|
+
`@orkestrel/jsonrpc`'s `JSONRPC_METHOD_NOT_FOUND` error whose message names the method. The modern
|
|
5644
5595
|
metadata checks (`-32602`, `-32022`) run before the seam is consulted, and a
|
|
5645
5596
|
legacy method never reaches it — the decorator answers or refuses at its own
|
|
5646
5597
|
door, and only its translated methods travel on. The seam carries the request arm:
|
|
@@ -5659,7 +5610,7 @@ the exact statement:
|
|
|
5659
5610
|
The request id is only stream identity: a later request does not supersede
|
|
5660
5611
|
an earlier one. The legacy method remains absent and answers `-32601`.
|
|
5661
5612
|
7. **`handle` maps the boundary failures.** A `JSON.parse` throw (malformed
|
|
5662
|
-
JSON) → a serialized `-32700` (Parse error) response with
|
|
5613
|
+
JSON) → a serialized `-32700` (Parse error) response with `id: null`; a
|
|
5663
5614
|
message exceeding `limit.message` reaches that same response before `JSON.parse`;
|
|
5664
5615
|
`_meta` is then bounded by serialized bytes, total object keys, and depth
|
|
5665
5616
|
before modern context parsing; `requestState` is bounded before HMAC verification
|
|
@@ -5668,29 +5619,22 @@ the exact statement:
|
|
|
5668
5619
|
built-in subscription admission is capped until each stream's `finally` releases it.
|
|
5669
5620
|
Metadata/state failures use `-32602`; content/capacity failures use `-32603`. A
|
|
5670
5621
|
parsed value that is not a valid invocation (a response, or any non-message)
|
|
5671
|
-
→ a serialized `-32600` (Invalid Request) response with
|
|
5622
|
+
→ a serialized `-32600` (Invalid Request) response with `id: null`. The
|
|
5672
5623
|
raw-string parse is the only `try`/`catch`; the guards (`parseJSONRPCMessage`
|
|
5673
|
-
over `isJSONRPCMessage`) are total and never throw.
|
|
5674
|
-
8. **Total wire guards.** `isBoundedString` / `isBoundedJSON` / `
|
|
5675
|
-
`
|
|
5676
|
-
|
|
5677
|
-
`isJSONRPCMessage` / `isMCPResult` / `isMCPLegacyResult` /
|
|
5678
|
-
`isInitializeRequest` / `isMCPSubscriptionFilter` are total functions over an
|
|
5679
|
-
already-parsed `unknown` — adversarial input returns `false`, never
|
|
5624
|
+
over `@orkestrel/jsonrpc`'s `isJSONRPCMessage`) are total and never throw.
|
|
5625
|
+
8. **Total wire guards.** `isBoundedString` / `isBoundedJSON` / `isMCPResult` /
|
|
5626
|
+
`isMCPLegacyResult` / `isInitializeRequest` / `isMCPSubscriptionFilter` are total
|
|
5627
|
+
functions over an already-parsed `unknown` — adversarial input returns `false`, never
|
|
5680
5628
|
throws. `isBoundedJSON` is iterative and rejects excessive depth, cycles,
|
|
5681
5629
|
accessors/hostile proxies, `Map`/`Set`, and non-JSON values while accepting
|
|
5682
|
-
hostile-looking own data keys.
|
|
5683
|
-
|
|
5684
|
-
|
|
5685
|
-
|
|
5686
|
-
|
|
5687
|
-
`isMCPResult` requires a string `resultType` and `isMCPLegacyResult` requires
|
|
5688
|
-
its absence. `null` is refused as an `id` everywhere — `isJSONRPCId` accepts a
|
|
5689
|
-
string or a finite integer and nothing else — and numeric ids and error codes are
|
|
5690
|
-
finite integers. `parseJSONRPCMessage` returns a frozen owned snapshot;
|
|
5630
|
+
hostile-looking own data keys. `isMCPResult` requires a string `resultType` and
|
|
5631
|
+
`isMCPLegacyResult` requires its absence, so a positive answer names exactly one arm. The
|
|
5632
|
+
JSON-RPC guards come from `@orkestrel/jsonrpc`: their arms partition every input, a
|
|
5633
|
+
request's `id` is a string or a finite integer, an error response's `id` is one of those or
|
|
5634
|
+
`null`, and error codes are integers. `parseJSONRPCMessage` returns a frozen owned snapshot;
|
|
5691
5635
|
every non-`undefined` output satisfies `isJSONRPCMessage` and shares no caller-owned graph.
|
|
5692
5636
|
9. **The core is provider-agnostic, no transport.** `src/core` imports only
|
|
5693
|
-
`@orkestrel/emitter`, `@orkestrel/tool`, `@orkestrel/contract`, and
|
|
5637
|
+
`@orkestrel/jsonrpc`, `@orkestrel/emitter`, `@orkestrel/tool`, `@orkestrel/contract`, and
|
|
5694
5638
|
`@orkestrel/codec` (plus, for the client's per-request deadline,
|
|
5695
5639
|
`AbortSignal.timeout`) — never `@orkestrel/server`, `@orkestrel/router`, `@orkestrel/sse`, or
|
|
5696
5640
|
`@orkestrel/websocket` — and carries no transport, no HTTP, and no model.
|
|
@@ -5720,9 +5664,9 @@ the exact statement:
|
|
|
5720
5664
|
directions, so the client's table carries `discover` alongside `connect` /
|
|
5721
5665
|
`disconnect` / `tools` / `call`, and each implementing class (`MCPServer` /
|
|
5722
5666
|
`MCPClient`; the adapter `MCPLegacyClientTransport`; the transports `HTTPClientTransport`
|
|
5723
|
-
(`src/core`), `WebSocketServerTransport` / `
|
|
5667
|
+
(`src/core`), `WebSocketServerTransport` / `NodeWebSocketClientTransport` /
|
|
5724
5668
|
`StdioClientTransport` / `StdioServerTransport` (`src/server`), and the browser face's
|
|
5725
|
-
|
|
5669
|
+
`BrowserWebSocketClientTransport`
|
|
5726
5670
|
(`src/browser`), each implementing the one `MCPMessageTransportInterface` —
|
|
5727
5671
|
`StdioClientTransport` through the narrower `StdioClientTransportInterface`
|
|
5728
5672
|
that extends it; and `MCPSession`) exposes the same public methods, no more. The
|
|
@@ -5893,12 +5837,12 @@ the exact statement:
|
|
|
5893
5837
|
isolates a listener throw, routing it to its `error` handler (the
|
|
5894
5838
|
`error` option, not a domain event). Consumers subscribe through `emitter.on`.
|
|
5895
5839
|
15. **The HTTP client transport drives a remote server over `fetch`
|
|
5896
|
-
(`src/
|
|
5840
|
+
(`src/core`).** `createHTTPClientTransport({ url, headers?, fetch?,
|
|
5897
5841
|
timeout? })` returns a `MCPMessageTransportInterface` whose `send` POSTs one
|
|
5898
5842
|
JSON-serialized message to `url` with `content-type:
|
|
5899
5843
|
application/json` and an `Accept` of both `application/json` and
|
|
5900
5844
|
`text/event-stream` (plus any `headers`), then decodes the reply and
|
|
5901
|
-
emits each carried `JSONRPCMessage` on the `message` event: an
|
|
5845
|
+
emits each carried `@orkestrel/jsonrpc` `JSONRPCMessage` value on the `message` event: an
|
|
5902
5846
|
`application/json` body is narrowed with `parseJSONRPCMessage`; a
|
|
5903
5847
|
`text/event-stream` body is decoded with `@orkestrel/sse`'s `SSEParser`
|
|
5904
5848
|
(`readEventStream`); a `202` (a notification accepted) carries no body
|
|
@@ -5951,7 +5895,7 @@ the exact statement:
|
|
|
5951
5895
|
socket, key, head, protocol })` (server mode → writes the `101` handshake,
|
|
5952
5896
|
selecting the configured subprotocol only when the client's offer contains it,
|
|
5953
5897
|
and sends unmasked frames), wraps it in a `WebSocketServerTransport`, and
|
|
5954
|
-
pumps — each inbound `JSONRPCMessage` that `isJSONRPCRequest` runs
|
|
5898
|
+
pumps — each inbound `JSONRPCMessage` that `@orkestrel/jsonrpc`'s `isJSONRPCRequest` guard accepts runs
|
|
5955
5899
|
through `mcp.dispatch`, a defined response written back as a frame (a
|
|
5956
5900
|
notification → `dispatch` `undefined` → nothing sent); a non-request
|
|
5957
5901
|
message is ignored; a `dispatch` / `send` fault surfaces on `mcp.emitter`'s
|
|
@@ -5980,7 +5924,7 @@ the exact statement:
|
|
|
5980
5924
|
mid-protocol. A transport drops out of the held set on its own `close`,
|
|
5981
5925
|
so a peer that already vanished neither throws nor delays the stop.
|
|
5982
5926
|
17. **The WebSocket client transport drives a remote server over an upgrade
|
|
5983
|
-
(`src/server`).** `
|
|
5927
|
+
(`src/server`).** `createNodeWebSocketClientTransport({ url, headers? })`
|
|
5984
5928
|
returns a `MCPMessageTransportInterface` — the WebSocket egress mirror of the
|
|
5985
5929
|
WebSocket ingress clause. `start()` (run by `client.connect()`) performs the RFC 6455
|
|
5986
5930
|
client handshake: a `node:http`(`s`) `GET` carrying `Connection: Upgrade`
|
|
@@ -6080,7 +6024,7 @@ the exact statement:
|
|
|
6080
6024
|
(`src/server`).** `createStdioServer(mcp, options?)` wraps
|
|
6081
6025
|
`options.input` (default `process.stdin`) / `options.output` (default
|
|
6082
6026
|
`process.stdout`) in a `StdioServerTransport` and pumps: each inbound
|
|
6083
|
-
`JSONRPCMessage` that is a request runs through `mcp.dispatch`, a defined
|
|
6027
|
+
`@orkestrel/jsonrpc` `JSONRPCMessage` value that is a request runs through `mcp.dispatch`, a defined
|
|
6084
6028
|
response written back as a newline-terminated line after the output completion
|
|
6085
6029
|
callback confirms it (a notification writes nothing); a non-request message is ignored; a
|
|
6086
6030
|
`dispatch` / `send` fault
|
|
@@ -6186,7 +6130,7 @@ the exact statement:
|
|
|
6186
6130
|
`undefined` (the process pipe carries no session concept).
|
|
6187
6131
|
21. **The browser transport carries the same `MCPMessageTransportInterface`
|
|
6188
6132
|
contract over native host APIs (`src/browser`).**
|
|
6189
|
-
`
|
|
6133
|
+
`createBrowserWebSocketClientTransport({ url, protocols? })` returns a
|
|
6190
6134
|
`MCPMessageTransportInterface` whose `start()` opens `new WebSocket(url,
|
|
6191
6135
|
protocols)` and awaits the native `'open'` event (the RFC 6455 handshake
|
|
6192
6136
|
is the host's concern; a connection failure — the native `'error'` event
|
|
@@ -6209,7 +6153,7 @@ the exact statement:
|
|
|
6209
6153
|
resolves the pending `start()` rather than leaving it pending, matching the
|
|
6210
6154
|
Node face.
|
|
6211
6155
|
`createHTTPClientTransport({ url, headers?, fetch?, timeout? })` returns the core
|
|
6212
|
-
`HTTPClientTransport` — the same class the Node face
|
|
6156
|
+
`HTTPClientTransport` — the same factory and class the Node face imports from core, because
|
|
6213
6157
|
the class touches `fetch`, `Response`, `AbortController`, `AbortSignal`, and `WeakMap`
|
|
6214
6158
|
alone. Every rule the HTTP client transport clause states therefore holds here as the same
|
|
6215
6159
|
code rather than as a second copy that agrees: the header contract, the SEP-2243
|
|
@@ -6286,7 +6230,7 @@ the exact statement:
|
|
|
6286
6230
|
27. **Not found is `undefined` at the port and `-32602` on the wire.**
|
|
6287
6231
|
`MCPResourceManagerInterface.resource`, `MCPPromptManagerInterface.prompt`, and
|
|
6288
6232
|
`MCPCompletionInterface.complete` each answer `undefined` for something they
|
|
6289
|
-
do not resolve, and the server maps that to `JSONRPC_INVALID_PARAMS` naming the
|
|
6233
|
+
do not resolve, and the server maps that to `@orkestrel/jsonrpc`'s `JSONRPC_INVALID_PARAMS` code naming the
|
|
6290
6234
|
unresolved URI or prompt. `-32002` is the pre-`2026-07-28` spelling a client `SHOULD`
|
|
6291
6235
|
still accept from an older peer and this server never produces. `resource` and
|
|
6292
6236
|
`prompt` may instead answer an `MCPInputResult`, which is stamped and returned as the
|