@orkestrel/scaffold 0.0.120 → 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.
Files changed (40) hide show
  1. package/dist/bin/main.js +5 -5
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/claude/agents/orkestrel.md +26 -26
  4. package/dist/host/guides/agent.md +5 -5
  5. package/dist/host/guides/brief.md +7 -15
  6. package/dist/host/guides/browser.md +1 -1
  7. package/dist/host/guides/capture.md +2 -2
  8. package/dist/host/guides/console.md +4 -30
  9. package/dist/host/guides/guide.md +0 -1
  10. package/dist/host/guides/interpret.md +165 -182
  11. package/dist/host/guides/lsp.md +26 -51
  12. package/dist/host/guides/mcp.md +220 -276
  13. package/dist/host/guides/middleware.md +14 -22
  14. package/dist/host/guides/ollama.md +1 -3
  15. package/dist/host/guides/probe.md +71 -80
  16. package/dist/host/guides/program.md +26 -35
  17. package/dist/host/guides/qualifier.md +0 -6
  18. package/dist/host/guides/queue.md +0 -4
  19. package/dist/host/guides/rater.md +6 -12
  20. package/dist/host/guides/relation.md +0 -2
  21. package/dist/host/guides/scaffold.md +12 -8
  22. package/dist/host/guides/sea.md +47 -51
  23. package/dist/host/guides/server.md +15 -19
  24. package/dist/host/guides/terminal.md +0 -26
  25. package/dist/host/guides/toolbox.md +0 -10
  26. package/dist/host/guides/worker.md +57 -57
  27. package/dist/host/guides/workflow.md +13 -26
  28. package/dist/host/guides/workspace.md +15 -21
  29. package/dist/host/manifest.json +28 -448
  30. package/dist/src/core/index.cjs +7 -45
  31. package/dist/src/core/index.cjs.map +1 -1
  32. package/dist/src/core/index.js +7 -45
  33. package/dist/src/core/index.js.map +1 -1
  34. package/dist/src/server/index.cjs +10 -9
  35. package/dist/src/server/index.cjs.map +1 -1
  36. package/dist/src/server/index.d.cts +12 -8
  37. package/dist/src/server/index.d.ts +12 -8
  38. package/dist/src/server/index.js +10 -9
  39. package/dist/src/server/index.js.map +1 -1
  40. package/package.json +5 -5
@@ -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 types, `@orkestrel/tool`'s tool registry, `@orkestrel/emitter`'s
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 `JSONRPCRequest` and
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 omits
34
- the `id` it could not read. The client mirrors it: `connect` negotiates the modern revision, `tools()`
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. `createWebSocketClientTransport` is the
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 same core HTTP client
63
- transport the Node face returns, plus the symmetric
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 omit the `id` they could not read; a `null` `id` never reaches the
334
- wire. Tool errors
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
- A JSON-RPC message splits on invocation and on response, and the types make each
352
- split unrepresentable to get wrong. An invocation is a **request** — a `method` call
353
- carrying the `id` that correlates it with its answer — or a **notification**, the
354
- same call with no `id`, answered by nothing. A response is a **result** arm or an
355
- **error** arm, never both. Each guard is total over an already-parsed `unknown`,
356
- and each pair is mutually exclusive on every input, so a positive answer names
357
- exactly one arm.
358
-
359
- **An `id` is present or it is not there at all.** `null` is not an id anywhere in
360
- this layer — not on a request, not on a response, not on the wire. The error arm
361
- is the one place an `id` may be absent, and absence there means omitted: MCP
362
- overrides JSON-RPC 2.0 §5, so a peer that could not read the failed request's id
363
- receives an envelope with no `id` member. `isJSONRPCId` rejects `null` for the
364
- same reason.
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
- isMCPLegacyResult,
377
- isMCPResult,
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 — MCP omits an unreadable id rather than nulling it
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 }) // false — a result is an object
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(undefined, -32700, 'Parse error')
398
- Object.hasOwn(anonymous, 'id') // false — the member is absent, not null
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, createMCPServer } from '@orkestrel/mcp'
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
- A `Shape` cell holds the constant's declared type.
621
-
622
- | Name | Kind | Signature | Summary |
623
- | ------------------------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
624
- | `MCP_HANDSHAKE_VERSION` | const | `MCPLegacyVersion` | Names the revision offered and defaulted to in the legacy `initialize` handshake, `'2025-11-25'`. |
625
- | `MCP_FALLBACK_VERSION` | const | `MCPLegacyVersion` | Names the older legacy revision the optional legacy decorator accepts and an adapter can pin, `'2025-06-18'`. |
626
- | `MCP_MODERN_VERSION` | const | `MCPModernVersion` | Names the modern revision offered by an unpinned client during discovery, `'2026-07-28'`. |
627
- | `SUPPORTED_MODERN_PROTOCOL_VERSIONS` | const | `readonly MCPModernVersion[]` | Lists the modern MCP protocol revisions a bare server accepts and advertises, `2026-07-28`. |
628
- | `SUPPORTED_LEGACY_PROTOCOL_VERSIONS` | const | `readonly MCPLegacyVersion[]` | Lists the protocol revisions accepted by the optional legacy decorator, `2025-11-25` and `2025-06-18`. |
629
- | `SUPPORTED_MCP_VERSIONS` | const | `readonly MCPVersion[]` | Lists the protocol revisions the `isMCPVersion` guard admits, spanning the modern and legacy eras. |
630
- | `MCP_META_VERSION` | const | `"io.modelcontextprotocol/protocolVersion"` | Names the reserved modern `_meta` key carrying the request's protocol revision. |
631
- | `MCP_META_CAPABILITIES` | const | `"io.modelcontextprotocol/clientCapabilities"` | Names the reserved modern `_meta` key carrying the client's open capability record. |
632
- | `MCP_META_CLIENT` | const | `"io.modelcontextprotocol/clientInfo"` | Names the reserved modern `_meta` key carrying the optional client identity. |
633
- | `MCP_META_SERVER` | const | `"io.modelcontextprotocol/serverInfo"` | Names the reserved modern `_meta` key carrying the server identity on results. |
634
- | `MCP_META_SUBSCRIPTION` | const | `"io.modelcontextprotocol/subscriptionId"` | Names the reserved modern `_meta` key carrying a `subscriptions/listen` request id. |
635
- | `MCP_EXTENSION_TASKS` | const | `"io.modelcontextprotocol/tasks"` | Names the reserved extension key identifying the stable Tasks extension. |
636
- | `MCP_SENTINEL_PREFIX` | const | `"=?base64?"` | Names the opening marker of the Base64 sentinel a standard MCP header value travels in. |
637
- | `MCP_SENTINEL_SUFFIX` | const | `"?="` | Names the closing marker of the Base64 sentinel a standard MCP header value travels in. |
638
- | `MCP_PARAM_PREFIX` | const | `"Mcp-Param-"` | Names the request-header prefix an `x-mcp-header` annotation projects a tool argument onto. |
639
- | `MCP_HEADER_ANNOTATION` | const | `"x-mcp-header"` | Identifies the tool-schema annotation key naming the header one parameter projects into. |
640
- | `MCP_LOOKUP_PAGES` | const | `8` | Bounds the `tools/list` pages one modern `tools/call` walks to reach its own annotations. |
641
- | `MCP_HEADER_MISMATCH` | const | `-32020` | Names the MCP reserved error for required HTTP metadata that does not match the request body. |
642
- | `MCP_MISSING_CAPABILITY` | const | `-32021` | Names the MCP reserved error for an operation needing a client capability that was not declared. |
643
- | `MCP_UNSUPPORTED_VERSION` | const | `-32022` | Names the MCP reserved error for a request naming an unsupported protocol revision. |
644
- | `DEFAULT_MCP_CACHE_TTL` | const | `60000` | Sets the default modern result freshness lifetime in milliseconds. |
645
- | `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. |
646
- | `EMPTY_MCP_ARGUMENTS` | const | `Readonly<Record<string, unknown>>` | Holds the one empty argument record every argument-less modern `tools/call` runs with. |
647
- | `JSONRPC_PARSE_ERROR` | const | `-32700` | Names the JSON-RPC 2.0 reserved error for invalid JSON received (the message did not parse). |
648
- | `JSONRPC_INVALID_REQUEST` | const | `-32600` | Names the JSON-RPC 2.0 reserved error for a payload that was not a valid Request object. |
649
- | `JSONRPC_METHOD_NOT_FOUND` | const | `-32601` | Names the JSON-RPC 2.0 reserved error for a requested method that does not exist. |
650
- | `JSONRPC_INVALID_PARAMS` | const | `-32602` | Names the JSON-RPC 2.0 reserved error for a method's invalid parameters. |
651
- | `JSONRPC_INTERNAL_ERROR` | const | `-32603` | Names the JSON-RPC 2.0 reserved error for a server that failed while handling an otherwise valid request. |
652
- | `JSONRPC_SERVER_ERROR` | const | `-32000` | Names the JSON-RPC 2.0 implementation-defined server error (the `-32000` to `-32099` range). |
653
- | `DEFAULT_MCP_CLIENT_NAME` | const | `"@orkestrel/mcp"` | Supplies the default client name reported in the MCP `initialize` handshake (`clientInfo.name`). |
654
- | `DEFAULT_MCP_CLIENT_VERSION` | const | `"1.0.0"` | Supplies the default client version reported in the MCP `initialize` handshake (`clientInfo.version`). |
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 no `id` member at all). Legacy dispatch results retain uniform
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: StreamInterface) => 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. |
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
- `createWebSocketClientTransport` is the egress mirror — a
1236
+ `createNodeWebSocketClientTransport` is the egress mirror — a
1270
1237
  `MCPMessageTransportInterface` an `MCPClient` drives over a `node:http(s)`
1271
- upgrade. Both `WebSocketServerTransport` and `WebSocketClientTransport` reuse
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 { createWebSocketClientTransport, createWebSocketServer } from '@orkestrel/mcp/server'
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: createWebSocketClientTransport({ url: `ws://127.0.0.1:${port}/mcp` }),
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 | Kind | Signature | Summary |
1330
- | -------------------------------- | -------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1331
- | `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. |
1332
- | `createWebSocketClientTransport` | function | `(options: WebSocketClientTransportOptions) => 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`. |
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 | Kind | Signature | Summary |
1337
- | -------------------------- | ----- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1338
- | `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 `WebSocketClientTransport` reuses. |
1339
- | `WebSocketClientTransport` | class | `new (options: WebSocketClientTransportOptions) => 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`. |
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
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
1354
- optional member and `plus` introducing its call-signature members, and a type alias's own type
1355
- literal with a union's arms escaped as `\|`.
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 `createWebSocketClientTransport`. |
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 `WebSocketClientTransport`. |
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
- `createWebSocketClientTransport` drives the native `WebSocket` global (the
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, published
1564
- from `@orkestrel/mcp` and returned by this factory and by the Node face's, because it touches
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. The WebSocket transports share their exported names
1570
- across the faces — same API shape, a different host underneath
1571
- — deliberately, so a consumer swaps `@orkestrel/mcp/server` for
1572
- `@orkestrel/mcp/browser` with no call-site change.
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 { createHTTPClientTransport, createWebSocketClientTransport } from '@orkestrel/mcp/browser'
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: createWebSocketClientTransport({ url: 'ws://localhost:3000/mcp' }),
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 | Kind | Signature | Summary |
1700
- | -------------------------------- | -------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1701
- | `createWebSocketClientTransport` | function | `(options: WebSocketClientTransportOptions) => 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 `createWebSocketClientTransport` (`@orkestrel/mcp/server`). |
1702
- | `createHTTPClientTransport` | function | `(options: HTTPClientTransportOptions) => MCPMessageTransportInterface` | Creates the HTTP client transport for an `MCPClientInterface` — a `MCPMessageTransportInterface` that drives a remote Streamable-HTTP MCP server over the native `fetch`. |
1703
- | `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. |
1704
- | `createScopeServer` | function | `(options: ScopeServerOptions, scope?: ScopeInterface) => 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`. |
1705
- | `createScopeTransport` | function | `(scope: ScopeInterface) => ScopeTransportInterface` | Adapts a hostable `ScopeInterface` (`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. |
1706
- | `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. |
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 | Kind | Signature | Summary |
1712
- | -------------------------- | ----- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1713
- | `WebSocketClientTransport` | class | `new (options: WebSocketClientTransportOptions) => 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 `WebSocketClientTransport`. |
1714
- | `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`. |
1715
- | `ModelContext` | class | `new (document: WebMCPDocument, options?: ModelContextOptions) => ModelContextInterface` | Bridges a `ToolManagerInterface` and a document's WebMCP tool registry — the `ModelContextInterface` `createModelContext` returns. |
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
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
1756
- optional member and `plus` introducing its call-signature members, and a type alias's own type
1757
- literal with a union's arms escaped as `\|`.
1758
- An extended interface's name comes before `plus`, with the members it adds after.
1759
-
1760
- | Name | Kind | Signature | Summary |
1761
- | --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1762
- | `WebSocketClientTransportOptions` | interface | `{ url, protocols? }` | Options for `createWebSocketClientTransport` (browser face) — the remote MCP WebSocket endpoint and any negotiated subprotocols. |
1763
- | `MessagePortTransportOptions` | interface | `{ port }` | Options for `createMessagePortTransport` — the native `MessagePort` a `MessagePortTransport` sends and listens on. |
1764
- | `ScopeInterface` | 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). |
1765
- | `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`). |
1766
- | `ScopeServerInterface` | interface | `{ stop() }` | Represents one MCP server hosted inside a worker scope — what `createScopeServer` returns. |
1767
- | `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`). |
1768
- | `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. |
1769
- | `PageServerInterface` | interface | `{ client, stop() }` | Represents one MCP server hosted inside the calling page — what `createPageServer` returns. |
1770
- | `WebMCPAnnotations` | interface | `{ readOnlyHint?, untrustedContentHint?, consequentialHint?, debugging? }` | Describes a tool's observable effects as the WebMCP registry declares them. |
1771
- | `WebMCPDescriptor` | interface | `{ name, title?, description, inputSchema?, annotations? }` | Describes the members a WebMCP tool carries into the registry and back out of it. |
1772
- | `WebMCPHandlerOptions` | interface | `{ signal }` | Carries the execution signal the WebMCP registry hands a registered tool's callback. |
1773
- | `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. |
1774
- | `WebMCPTool` | interface | `{ execute }` | Describes one tool as handed to the WebMCP registry for registration. |
1775
- | `WebMCPRegisteredTool` | interface | `{ window, origin }` | Describes one tool as the WebMCP registry reports it back. |
1776
- | `WebMCPRegisterOptions` | interface | `{ exposedTo?, signal? }` | Options for the WebMCP registry's `registerTool` — the exposure list and the unregistration signal. |
1777
- | `WebMCPToolsOptions` | interface | `{ fromOrigins? }` | Options for the WebMCP registry's `getTools` — the origins whose tools are read. |
1778
- | `WebMCPExecuteOptions` | interface | `{ signal? }` | Options for the WebMCP registry's `executeTool` — the caller's cancellation signal. |
1779
- | `WebMCPToolEvent` | interface | `{ toolName }` | Carries the tool name a WebMCP execution event reports. |
1780
- | `WebMCPRegistryInterface` | interface | `{ registerTool(), getTools(), executeTool(), addEventListener(), removeEventListener() }` | Represents the WebMCP tool registry a document exposes as `document.modelContext`. |
1781
- | `WebMCPDocument` | interface | `{ modelContext }` | Describes a document that exposes the WebMCP tool registry. |
1782
- | `WebMCPProjection` | interface | `{ tool, descriptor }` | Pairs one tool with the WebMCP descriptor a registry advertises for it. |
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 | Summary |
1823
- | ---------------- | ----- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
1824
- | `ScopeServer` | class | `new (options: ScopeServerOptions, scope?: ScopeInterface) => ScopeServerInterface` | Owns a scope's implicit binding and every accepted client-port binding. |
1825
- | `ScopeTransport` | class | `new (scope: ScopeInterface) => ScopeTransportInterface` | Adapts a scope's implicit channel to replaceable MCP transport callbacks. |
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 both faces'
1899
- `createHTTPClientTransport`), `WebSocketServerTransport` / `WebSocketClientTransport`
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
- own `WebSocketClientTransport` (`src/browser`, the same exported name over a different
1902
- host) ↔ `MCPMessageTransportInterface` (they all share the one generic bidirectional
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, createMCPServer } from '@orkestrel/mcp'
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. The `WebSocketClientTransport`s unsubscribe
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/server'
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
- #### `ScopeInterface`
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 `ScopeInterface` carries what
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
- createHTTPClientTransport,
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: createWebSocketClientTransport({ url: 'ws://localhost:3000/mcp' }),
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. Use them in a test or custom transport.
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 `ScopeInterface` (the exact
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-less `-32600`, locally answered and forwarded alike. Every other method is
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 { createMCPClient, createMCPLegacyClientTransport } from '@orkestrel/mcp'
4924
- import { createHTTPClientTransport } from '@orkestrel/mcp/server'
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/WebSocketClientTransport.test.ts)
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
- missing, and it is then omitted — the member is absent from the envelope, never
5571
- present as `null` — which is what a `handle` parse or invalid-request failure
5572
- produces, because neither could read an id to echo. MCP overrides JSON-RPC 2.0 §5
5573
- here, and `JSONRPCErrorResponse` states it: `id?: JSONRPCId`, where `JSONRPCId`
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 no `id` member; a
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 no `id` member. The
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` / `isJSONRPCId` /
5675
- `isJSONRPCRequest` / `isJSONRPCNotification` / `isJSONRPCInvocation` /
5676
- `isJSONRPCResultResponse` / `isJSONRPCErrorResponse` / `isJSONRPCResponse` /
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. Each pair of arms is mutually exclusive on every
5683
- input, so a positive answer names exactly one arm: `isJSONRPCRequest` requires
5684
- a valid `id` and `isJSONRPCNotification` requires no own `id` member; a result
5685
- response requires an `id` and an object `result` with no `error`, while an error
5686
- response permits an absent `id` and requires an `error` with no `result`;
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` / `WebSocketClientTransport` /
5667
+ (`src/core`), `WebSocketServerTransport` / `NodeWebSocketClientTransport` /
5724
5668
  `StdioClientTransport` / `StdioServerTransport` (`src/server`), and the browser face's
5725
- own `WebSocketClientTransport`
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/server`).** `createHTTPClientTransport({ url, headers?, fetch?,
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`).** `createWebSocketClientTransport({ url, headers? })`
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
- `createWebSocketClientTransport({ url, protocols? })` returns a
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's factory of that name returns, because
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