@orkestrel/scaffold 0.0.124 → 0.0.126
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agents/skills/orkestrel-publish/scripts/steps.js +523 -0
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +70 -11
- package/dist/bin/main.js +51 -18
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +7 -2
- package/dist/host/agents/platforms/windows.md +9 -1
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/methods.md +32 -4
- package/dist/host/agents/skills/orkestrel-journey/SKILL.md +18 -19
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -0
- package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +2 -1
- package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +5 -1
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +23 -6
- package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +654 -0
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +79 -14
- package/dist/host/claude/agents/orkestrel.md +28 -28
- package/dist/host/claude/rules/patterns.md +1 -1
- package/dist/host/claude/rules/portability.md +2 -0
- package/dist/host/claude/rules/quality.md +6 -1
- package/dist/host/claude/rules/tests.md +6 -1
- package/dist/host/claude/rules/workspace.md +8 -3
- package/dist/host/guides/agent.md +575 -346
- package/dist/host/guides/brief.md +52 -48
- package/dist/host/guides/browser.md +2 -2
- package/dist/host/guides/interpret.md +531 -155
- package/dist/host/guides/mcp.md +183 -61
- package/dist/host/guides/ndjson.md +4 -3
- package/dist/host/guides/ollama.md +125 -68
- package/dist/host/guides/program.md +117 -39
- package/dist/host/guides/qualifier.md +110 -59
- package/dist/host/guides/rater.md +85 -32
- package/dist/host/guides/scaffold.md +49 -22
- package/dist/host/guides/study.md +596 -489
- package/dist/host/guides/toolbox.md +159 -80
- package/dist/host/guides/workflow.md +44 -25
- package/dist/host/manifest.json +41 -35
- package/dist/src/core/index.cjs +12 -10
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +3 -1
- package/dist/src/core/index.d.ts +3 -1
- package/dist/src/core/index.js +12 -10
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +23 -11
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +10 -6
- package/dist/src/server/index.d.ts +10 -6
- package/dist/src/server/index.js +23 -11
- package/dist/src/server/index.js.map +1 -1
- package/package.json +7 -7
package/dist/host/guides/mcp.md
CHANGED
|
@@ -290,8 +290,9 @@ claim this server does not implement the revision it does implement.
|
|
|
290
290
|
its errors in band, byte-identically to what a `2025-06-18` client already expects. A
|
|
291
291
|
modern result maps to real statuses: `202` for a notification, `400` for `-32020` /
|
|
292
292
|
`-32021` / `-32022` / `-32602`, `404` for `-32601`, and `200` otherwise. A
|
|
293
|
-
transport-level failure — malformed JSON or
|
|
294
|
-
`400` under both eras, because no era was ever established.
|
|
293
|
+
transport-level failure — malformed JSON or an invalid request body — is
|
|
294
|
+
`400` under both eras, because no era was ever established. A response or a malformed
|
|
295
|
+
notification is accepted with `202` and no body, using the same classification as `handle`. See
|
|
295
296
|
[Route a request by era and build a modern result](#route-a-request-by-era-and-build-a-modern-result)
|
|
296
297
|
for the inferers this rides on.
|
|
297
298
|
|
|
@@ -305,7 +306,17 @@ import { createMCPServer } from '@orkestrel/mcp'
|
|
|
305
306
|
import { createTool, createToolManager } from '@orkestrel/tool'
|
|
306
307
|
|
|
307
308
|
const tools = createToolManager()
|
|
308
|
-
tools.add(
|
|
309
|
+
tools.add(
|
|
310
|
+
createTool({
|
|
311
|
+
name: 'add',
|
|
312
|
+
parameters: {
|
|
313
|
+
type: 'object',
|
|
314
|
+
properties: { x: { type: 'number' }, y: { type: 'number' } },
|
|
315
|
+
required: ['x', 'y'],
|
|
316
|
+
},
|
|
317
|
+
execute: (a) => Number(a.x) + Number(a.y),
|
|
318
|
+
}),
|
|
319
|
+
)
|
|
309
320
|
|
|
310
321
|
const server = createMCPServer({ identity: { name: 'calculator', version: '1.0.0' }, tools })
|
|
311
322
|
server.emitter.on('request', (method, id, era) => log(method, id, era))
|
|
@@ -314,12 +325,12 @@ server.emitter.on('request', (method, id, era) => log(method, id, era))
|
|
|
314
325
|
const reply = await server.handle(
|
|
315
326
|
'{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}',
|
|
316
327
|
)
|
|
317
|
-
// reply → '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"add","inputSchema":{"type":"object"}}]}}'
|
|
328
|
+
// reply → '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"add","inputSchema":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"]}}]}}'
|
|
318
329
|
|
|
319
330
|
const out = await server.handle(
|
|
320
331
|
'{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"add","arguments":{"x":2,"y":5},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}',
|
|
321
332
|
)
|
|
322
|
-
// out → '…"result":{"content":[{"type":"text","text":"7"}],"
|
|
333
|
+
// out → '…"result":{"content":[{"type":"text","text":"7"}],"resultType":"complete",…}}'
|
|
323
334
|
```
|
|
324
335
|
|
|
325
336
|
`dispatch` is the typed core; `handle` wraps it with the `JSON.parse` ↔
|
|
@@ -330,11 +341,18 @@ graph. A call with no `id` is a **notification** — a type of its own, handled
|
|
|
330
341
|
(the `request` event still fires) but yielding no response (`dispatch` resolves
|
|
331
342
|
`undefined`, `handle` returns `undefined`), whatever its method. The error
|
|
332
343
|
envelopes carry `id: null` for the id they could not read, as JSON-RPC 2.0 § 5
|
|
333
|
-
requires.
|
|
344
|
+
requires, and a malformed request's `-32600` carries the id it could read. A stray response and
|
|
345
|
+
a malformed notification are not answered, and reach the `error` event. Tool errors
|
|
334
346
|
are not protocol errors: the `ToolManager` (`@orkestrel/tool`) isolates a
|
|
335
347
|
thrown tool into a `success: false` result, which `tools/call` maps to an
|
|
336
348
|
`isError: true` tool result carrying its `error` text — so the server wraps
|
|
337
|
-
no tool-domain failure as a protocol error.
|
|
349
|
+
no tool-domain failure as a protocol error. An unknown tool is one: `tools/call` answers
|
|
350
|
+
`-32602` with `Unknown tool:`, the name, and at most `REFUSAL_LIST_LIMIT` of the available names,
|
|
351
|
+
before any input policy or `execution` port runs. A refused argument record is one of those
|
|
352
|
+
failures: the specification, revision 2025-11-25, Tools § Error Handling, reports input
|
|
353
|
+
validation in a tool result so a model can correct and retry, and the text `Tool` refuses with
|
|
354
|
+
says what to send. An in-process caller reads the same report from a `ToolError`'s
|
|
355
|
+
`context.faults`. A rejected execution provider or
|
|
338
356
|
malformed runtime result instead becomes a detail-free `-32603` response, and the
|
|
339
357
|
value that was caught is reported on the server's `error` event — the one place it
|
|
340
358
|
is legible, and never the wire.
|
|
@@ -363,8 +381,8 @@ invalid input carries `id: null`.
|
|
|
363
381
|
**A JSON-RPC result is any value, and an MCP result is an object.** The `result` member of
|
|
364
382
|
`@orkestrel/jsonrpc`'s `JSONRPCResultResponse` type is `unknown`, so narrow it with
|
|
365
383
|
`isMCPResult` or `isMCPLegacyResult` before reading it. `HTTPClientTransport` delivers an
|
|
366
|
-
`application/json` reply whose `result` is a primitive, and `MCPClient`
|
|
367
|
-
`
|
|
384
|
+
`application/json` reply whose `result` is a primitive, and `MCPClient` rejects the request it
|
|
385
|
+
answers with an `MCPError`, and reports one that answers no pending request on `error`. When a legacy peer answers a correlated request with a primitive
|
|
368
386
|
`result`, `MCPLegacyClientTransport` answers that request with a `-32603` error response.
|
|
369
387
|
|
|
370
388
|
```ts
|
|
@@ -641,6 +659,7 @@ result shape for them. See
|
|
|
641
659
|
| `MCP_SENTINEL_SUFFIX` | const | `"?="` | Names the closing marker of the Base64 sentinel a standard MCP header value travels in. |
|
|
642
660
|
| `MCP_PARAM_PREFIX` | const | `"Mcp-Param-"` | Names the request-header prefix an `x-mcp-header` annotation projects a tool argument onto. |
|
|
643
661
|
| `MCP_HEADER_ANNOTATION` | const | `"x-mcp-header"` | Identifies the tool-schema annotation key naming the header one parameter projects into. |
|
|
662
|
+
| `MCP_LIST_PAGES` | const | `64` | Bounds the `tools/list` pages a client reads into one listing. |
|
|
644
663
|
| `MCP_LOOKUP_PAGES` | const | `8` | Bounds the `tools/list` pages one modern `tools/call` walks to reach its own annotations. |
|
|
645
664
|
| `MCP_HEADER_MISMATCH` | const | `-32020` | Names the MCP reserved error for required HTTP metadata that does not match the request body. |
|
|
646
665
|
| `MCP_MISSING_CAPABILITY` | const | `-32021` | Names the MCP reserved error for an operation needing a client capability that was not declared. |
|
|
@@ -749,10 +768,10 @@ result shape for them. See
|
|
|
749
768
|
| `buildToolDescriptors` | function | `(manager: ToolManagerInterface) => readonly MCPToolDescriptor[]` | Maps a `ToolManagerInterface`'s definitions to MCP `tools/list` descriptors — renaming `parameters` to the wire's `inputSchema`. |
|
|
750
769
|
| `toolAnnotationsToMCP` | function | `(annotations: ToolAnnotations) => MCPToolAnnotations` | Projects domain tool annotations onto MCP wire hints without inventing defaults. |
|
|
751
770
|
| `mcpAnnotationsToTool` | function | `(annotations: MCPToolAnnotations) => ToolAnnotations` | Projects MCP wire hints onto domain tool annotations without inventing defaults. |
|
|
752
|
-
| `buildToolCall` | function | `(request: JSONRPCRequest, args
|
|
771
|
+
| `buildToolCall` | function | `(request: JSONRPCRequest, args: Readonly<Record<string, unknown>>) => ToolCall \| undefined` | Builds the canonical Tool call for one validated MCP `tools/call` request. |
|
|
753
772
|
| `buildProgressNotification` | function | `(token: string \| number, progress: MCPProgress) => JSONRPCNotification` | Builds one official progress notification for the original request stream. |
|
|
754
773
|
| `buildCancelledNotification` | function | `(id: JSONRPCId, reason?: string) => JSONRPCNotification` | Builds one official cancellation notification for a request already sent. |
|
|
755
|
-
| `buildCallOutcome` | function | `(name: string, result: unknown) => MCPCallOutcome`
|
|
774
|
+
| `buildCallOutcome` | function | `(name: string, result: unknown, output?: ContractInterface<unknown>) => MCPCallOutcome` | Narrows one `tools/call` answer to the arm the peer chose. |
|
|
756
775
|
| `extractContentText` | function | `(result: unknown) => string` | Concatenates an MCP tool-call result's text content blocks into one string. |
|
|
757
776
|
| `matchesResultType` | function | `(method: string, resultType: unknown) => boolean` | Determines whether one method may answer with a given modern `resultType`. |
|
|
758
777
|
| `snapshotJSON` | function | `(value: unknown, limits: MCPJSONLimitOptions) => readonly [value: JSONValue, text: string] \| undefined` | Snapshots one bounded exact JSON value together with its canonical wire serialization. The returned value is an owned, deeply frozen graph reconstructed from the canonical text; the frozen tuple shares no mutable structure with the input. Invalid exact-JSON shapes, hostile reflection, serialization failures, and values outside the byte, key, or depth limits return `undefined`. |
|
|
@@ -774,6 +793,12 @@ result shape for them. See
|
|
|
774
793
|
| `decodeBoundedMessage` | function | `(message: string, limits: MCPJSONLimitOptions) => JSONRPCMessage \| undefined` | Decodes one raw inbound message within an explicit bound — the decode a binder performs before it hands the string on. |
|
|
775
794
|
| `deliverMessage` | function | `(emitter: EmitterInterface<MCPMessageTransportEventMap>, text: string, fault: string) => void` | Decodes one inbound frame and delivers it onto a transport emitter as `message` or `error`. |
|
|
776
795
|
| `readCancelledId` | function | `(message: JSONRPCMessage) => JSONRPCId \| undefined` | Reads the request id an inbound `notifications/cancelled` names — the inverse of `buildCancelledNotification`. |
|
|
796
|
+
| `readToolPage` | function | `(result: unknown) => MCPToolPage` | Reads one `tools/list` answer as a page of tools, refusing a listing it cannot read. |
|
|
797
|
+
| `extractMessageId` | function | `(value: unknown) => JSONRPCId \| undefined` | Extracts the JSON-RPC id one unread message carries, when it carries a valid one. |
|
|
798
|
+
| `extractInvalidRequestId` | function | `(value: unknown) => JSONRPCId \| null \| undefined` | Extracts the id a `-32600` answer to one parsed value that is not an invocation goes under. |
|
|
799
|
+
| `buildParseFault` | function | `(message: string) => MCPError` | Builds the transport fault for one inbound frame that is not JSON, which answers under `null`. |
|
|
800
|
+
| `buildInboundAnswer` | function | `(fault: unknown) => JSONRPCErrorResponse \| undefined` | Builds the JSON-RPC error a server transport writes for one fault its carrier reported. |
|
|
801
|
+
| `buildInboundFault` | function | `(value: unknown, fault: string) => MCPError` | Builds the transport fault for one inbound value that is not the message its receiver takes. |
|
|
777
802
|
| `decodeSentinel` | function | `(value: string) => string \| undefined` | Reads the value one standard MCP request header carries, decoding the Base64 sentinel. |
|
|
778
803
|
| `encodeSentinel` | function | `(value: string) => string` | Builds the wire form one standard MCP request header value must travel as. |
|
|
779
804
|
| `isFieldToken` | function | `(value: unknown) => value is string` | Determines whether a value is one RFC 9110 field token. |
|
|
@@ -832,7 +857,7 @@ isMCPToolAnnotations({ readOnlyHint: false }) // true
|
|
|
832
857
|
| `MCPBlobResource` | interface | `{ uri, mimeType?, _meta?, blob }` | Represents embedded base64-encoded resource contents. |
|
|
833
858
|
| `MCPEmbeddedResource` | interface | `{ type, resource, annotations?, _meta? }` | Represents an MCP content block carrying embedded text or blob resource contents. |
|
|
834
859
|
| `MCPContent` | type | `MCPTextContent \| MCPImageContent \| MCPAudioContent \| MCPResourceLink \| MCPEmbeddedResource` | Represents one exact dated-schema tool content block. |
|
|
835
|
-
| `MCPUnstampedCallResult` | type | `{ readonly content: readonly MCPContent[]; readonly structuredContent?: JSONValue
|
|
860
|
+
| `MCPUnstampedCallResult` | type | `{ readonly content: readonly MCPContent[]; readonly structuredContent?: Readonly<Record<string, JSONValue>>; readonly isError?: boolean; readonly _meta?: MCPResultMetaObject; }` | Represents a `tools/call` result before the modern stamp — the executed tool's output as `content` blocks, with `isError` flagging a tool failure. |
|
|
836
861
|
| `MCPCallResult` | type | `MCPUnstampedCallResult & { readonly resultType: 'complete'; }` | Represents a required complete modern `tools/call` result. |
|
|
837
862
|
| `MCPPaginationParams` | interface | `{ cursor? }` | Represents the cursor parameters shared by every paginated modern list method. |
|
|
838
863
|
| `MCPPaginationResult` | interface | `{ nextCursor? }` | Represents the cursor result fields shared by every paginated modern list method. |
|
|
@@ -909,6 +934,8 @@ isMCPToolAnnotations({ readOnlyHint: false }) // true
|
|
|
909
934
|
| `MCPListResult` | type | `{ readonly tools: readonly MCPToolDescriptor[]; readonly resultType: 'complete'; readonly ttlMs: number; readonly cacheScope: 'public' \| 'private'; readonly _meta?: MCPResultMetaObject; }` | Represents the MCP `tools/list` result — tool descriptors plus optional modern result stamps. |
|
|
910
935
|
| `MCPToolAnnotations` | interface | `{ title?, readOnlyHint?, destructiveHint?, idempotentHint?, openWorldHint? }` | Describes tool hints using the MCP 2026-07-28 specification's wire field names. |
|
|
911
936
|
| `MCPToolDescriptor` | interface | `{ name, title?, description?, inputSchema, annotations? }` | Represents one entry of the MCP `tools/list` result with its display metadata and JSON-Schema input. |
|
|
937
|
+
| `MCPListedTool` | type | `Readonly<Record<string, unknown>> & Pick<MCPToolDescriptor, 'name' \| 'inputSchema'>` | Holds one `tools/list` entry past the members a client refuses a listing without. |
|
|
938
|
+
| `MCPToolPage` | interface | `{ tools, nextCursor? }` | Holds one `tools/list` page a client has read. |
|
|
912
939
|
| `MCPHeaderPrimitive` | type | `'boolean' \| 'integer' \| 'string'` | Names the JSON Schema types an `x-mcp-header` annotation may sit on. |
|
|
913
940
|
| `MCPHeaderParameter` | interface | `{ name, path, primitive }` | Represents one `x-mcp-header` projection a tool's `inputSchema` declares. |
|
|
914
941
|
| `MCPIdentity` | type | `MCPMetaObject & { readonly name: string; readonly version: string; readonly title?: string; readonly description?: string; readonly websiteUrl?: string; readonly icons?: readonly MCPIcon[]; }` | Represents the complete dated identity of an MCP server or client. |
|
|
@@ -1048,9 +1075,12 @@ so `caller` stays an HTTP-face seam.
|
|
|
1048
1075
|
request body through `mcp.dispatch`. For a streamed response,
|
|
1049
1076
|
`MCPDispatchOptions.signal` composes the fetch-standard request signal with
|
|
1050
1077
|
response-stream cancellation; the optional session middleware preserves the request
|
|
1051
|
-
signal when it rebuilds a buffered POST. A malformed JSON body
|
|
1052
|
-
|
|
1053
|
-
|
|
1078
|
+
signal when it rebuilds a buffered POST. A malformed JSON body or an invalid request
|
|
1079
|
+
is an HTTP `400` carrying a JSON-RPC error body (`-32700` / `-32600`). The error
|
|
1080
|
+
carries `id: null` unless a malformed request has a readable id. An object with neither
|
|
1081
|
+
invocation nor response members, including `{}`, receives `-32600` under `null`.
|
|
1082
|
+
A response or a malformed notification receives HTTP `202` with no body, matching
|
|
1083
|
+
the silence of `handle` and stdio. Legacy dispatch results retain uniform
|
|
1054
1084
|
HTTP `200` with in-band errors. Modern responses use `202` for notifications,
|
|
1055
1085
|
`400` for `-32020` / `-32021` / `-32022` / `-32602`, `404` for `-32601`, and
|
|
1056
1086
|
`200` otherwise. A unary reply is framed as one `@orkestrel/server` `createStream`
|
|
@@ -2156,7 +2186,8 @@ The `tasks` data member is the stable Tasks extension's client half — see
|
|
|
2156
2186
|
`tools()` returns a snapshot. The wire preserves `title`, the advertised `description`,
|
|
2157
2187
|
`inputSchema` (wrapped as `parameters`), and the mapped `annotations`. The server maps
|
|
2158
2188
|
`pure` to `readOnlyHint` and `consequential` to `destructiveHint`; the client applies the
|
|
2159
|
-
inverse projection.
|
|
2189
|
+
inverse projection. A tool that declares nothing advertises the closed empty object
|
|
2190
|
+
`CLOSED_PARAMETERS` from `@orkestrel/tool`, so a call that sends it a key is refused.
|
|
2160
2191
|
`untrusted` has no MCP counterpart. Unmapped hints remain absent from
|
|
2161
2192
|
the wrapped tool, and omitted hints receive no invented defaults. These hints do not authorize
|
|
2162
2193
|
execution. The wire loses `summary` as a separate field and, when a summary was authored,
|
|
@@ -2165,6 +2196,36 @@ The wrapped tool forwards `context.signal` into `call`, so agent-side abort reac
|
|
|
2165
2196
|
remote request. Refresh snapshots explicitly between agent runs; see
|
|
2166
2197
|
[Refresh the tools an agent holds](#refresh-the-tools-an-agent-holds).
|
|
2167
2198
|
|
|
2199
|
+
**A listing is complete or refused.** `tools()` follows `nextCursor` for up to `MCP_LIST_PAGES`
|
|
2200
|
+
pages and throws an `MCPError` when an answer is not an object, `tools` is not an array, an entry
|
|
2201
|
+
lacks a non-empty `name` with no surrounding space or a record `inputSchema`, a present
|
|
2202
|
+
`outputSchema` is not a record, a `nextCursor` is neither a string nor `null`, a cursor repeats, or
|
|
2203
|
+
a cursor is present on the last page it reads, because a cut listing would read as complete. A
|
|
2204
|
+
`null` or empty cursor reads as the end of the listing. The refusal names the entry's index.
|
|
2205
|
+
|
|
2206
|
+
**A wrapped tool enforces the remote `inputSchema` before it calls.** The schema enters through the
|
|
2207
|
+
lenient `schemaToShape` conversion on the wrapped tool's first `execute`, which widens what it
|
|
2208
|
+
cannot read and never narrows, so the remote server stays the authority on what remains. A
|
|
2209
|
+
refusal throws a `ToolError` with code `ARGUMENTS` and writes nothing to the transport.
|
|
2210
|
+
|
|
2211
|
+
**A tool's own error always reaches the caller.** `isError: true` throws `MCPToolError` before any
|
|
2212
|
+
block is validated, carrying the text of whichever blocks read, or a bare string `content`, because
|
|
2213
|
+
that message is what a model corrects from.
|
|
2214
|
+
|
|
2215
|
+
**A complete answer must be readable.** On a success, `call` throws an `MCPError` for a non-boolean
|
|
2216
|
+
`isError`, a `content` that is not a list of valid blocks, and a result carrying neither `content`
|
|
2217
|
+
nor an object `structuredContent`. `content: []` reads as a value of `undefined`. The specification,
|
|
2218
|
+
revision 2025-11-25, defines `structuredContent` as a JSON object, so `MCPServer` sets it only for a
|
|
2219
|
+
record value, the text carrying every other value, and `call` reads any other value there as absent
|
|
2220
|
+
and falls back to the text, because refusing it would lose a real answer from a sloppy server.
|
|
2221
|
+
|
|
2222
|
+
**A declared `outputSchema` binds the answer.** After `tools()` has read this connection's listing,
|
|
2223
|
+
a tool declaring an `outputSchema` must answer an object `structuredContent` the `is` guard of that
|
|
2224
|
+
schema's lenient conversion accepts. A miss throws an `MCPError` whose `context.faults` holds the
|
|
2225
|
+
audit, and its message says when the result carried no `structuredContent` object at all. A failure owes no value, so `isError: true` still throws
|
|
2226
|
+
`MCPToolError`. A `call` made before any listing knows no schema and checks none, and a new
|
|
2227
|
+
connection starts with none.
|
|
2228
|
+
|
|
2168
2229
|
**Every session-bound request refuses at once while the client holds no connection.** `call`,
|
|
2169
2230
|
`tools`, each `tasks/*` method reached through `client.tasks`, and a `listen` stream all carry
|
|
2170
2231
|
the same refusal, because they all issue through one correlated-request door. A client that has
|
|
@@ -2640,10 +2701,13 @@ The `adopt` method excludes a tool carrying `annotations.debugging: true` unless
|
|
|
2640
2701
|
`adopt({ debug: true })`. A false or omitted hint leaves the tool included either way;
|
|
2641
2702
|
the `origins` option continues to filter which registrations the registry returns.
|
|
2642
2703
|
|
|
2643
|
-
**An adopted tool
|
|
2644
|
-
`parameters` and
|
|
2645
|
-
|
|
2646
|
-
|
|
2704
|
+
**An adopted tool enforces the foreign schema.** It advertises the foreign `inputSchema` as its
|
|
2705
|
+
`parameters` and enforces it through the lenient `schemaToShape` conversion on its first `execute`,
|
|
2706
|
+
so a schema record it cannot read refuses that tool's calls rather than the whole `adopt` call. A
|
|
2707
|
+
foreign tool with no `inputSchema` declares nothing and takes nothing. A tool no local `Tool` can be
|
|
2708
|
+
built from, a non-record `inputSchema` or a name with surrounding space, rejects the whole `adopt`
|
|
2709
|
+
call with a `ToolError`. The handler in the other document stays the authority on whatever the
|
|
2710
|
+
conversion widens.
|
|
2647
2711
|
|
|
2648
2712
|
The bridge exposes these methods.
|
|
2649
2713
|
|
|
@@ -2736,10 +2800,25 @@ tools.add(
|
|
|
2736
2800
|
createTool({
|
|
2737
2801
|
name: 'search',
|
|
2738
2802
|
description: 'Search the docs',
|
|
2803
|
+
parameters: {
|
|
2804
|
+
type: 'object',
|
|
2805
|
+
properties: { query: { type: 'string' } },
|
|
2806
|
+
required: ['query'],
|
|
2807
|
+
},
|
|
2739
2808
|
execute: (a) => find(String(a.query)),
|
|
2740
2809
|
}),
|
|
2741
2810
|
)
|
|
2742
|
-
tools.add(
|
|
2811
|
+
tools.add(
|
|
2812
|
+
createTool({
|
|
2813
|
+
name: 'add',
|
|
2814
|
+
parameters: {
|
|
2815
|
+
type: 'object',
|
|
2816
|
+
properties: { x: { type: 'number' }, y: { type: 'number' } },
|
|
2817
|
+
required: ['x', 'y'],
|
|
2818
|
+
},
|
|
2819
|
+
execute: (a) => Number(a.x) + Number(a.y),
|
|
2820
|
+
}),
|
|
2821
|
+
)
|
|
2743
2822
|
|
|
2744
2823
|
const server = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools })
|
|
2745
2824
|
server.emitter.on('request', (method, id) => log(method, id))
|
|
@@ -2754,7 +2833,7 @@ for await (const message of transport) {
|
|
|
2754
2833
|
const listed = await server.handle(
|
|
2755
2834
|
'{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}',
|
|
2756
2835
|
)
|
|
2757
|
-
// listed → '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"search","inputSchema":{"type":"object"},"description":"Search the docs"},{"name":"add","inputSchema":{"type":"object"}}],"resultType":"complete","ttlMs":60000,"cacheScope":"private","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"docs","version":"1.0.0"}}}}'
|
|
2836
|
+
// listed → '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"search","inputSchema":{"type":"object","properties":{"query":{"type":"string"}},"required":["query"]},"description":"Search the docs"},{"name":"add","inputSchema":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"]}}],"resultType":"complete","ttlMs":60000,"cacheScope":"private","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"docs","version":"1.0.0"}}}}'
|
|
2758
2837
|
```
|
|
2759
2838
|
|
|
2760
2839
|
### Refresh the tools an agent holds
|
|
@@ -3144,7 +3223,17 @@ import { createScopeServer } from '@orkestrel/mcp/browser'
|
|
|
3144
3223
|
import { createTool, createToolManager } from '@orkestrel/tool'
|
|
3145
3224
|
|
|
3146
3225
|
const tools = createToolManager()
|
|
3147
|
-
tools.add(
|
|
3226
|
+
tools.add(
|
|
3227
|
+
createTool({
|
|
3228
|
+
name: 'add',
|
|
3229
|
+
parameters: {
|
|
3230
|
+
type: 'object',
|
|
3231
|
+
properties: { x: { type: 'number' }, y: { type: 'number' } },
|
|
3232
|
+
required: ['x', 'y'],
|
|
3233
|
+
},
|
|
3234
|
+
execute: (a) => Number(a.x) + Number(a.y),
|
|
3235
|
+
}),
|
|
3236
|
+
)
|
|
3148
3237
|
const worker = createScopeServer({ tools, name: 'worker-mcp', version: '1.0.0' })
|
|
3149
3238
|
// ... on teardown:
|
|
3150
3239
|
worker.stop()
|
|
@@ -3205,7 +3294,17 @@ const scope = {
|
|
|
3205
3294
|
}
|
|
3206
3295
|
|
|
3207
3296
|
const tools = createToolManager()
|
|
3208
|
-
tools.add(
|
|
3297
|
+
tools.add(
|
|
3298
|
+
createTool({
|
|
3299
|
+
name: 'add',
|
|
3300
|
+
parameters: {
|
|
3301
|
+
type: 'object',
|
|
3302
|
+
properties: { x: { type: 'number' }, y: { type: 'number' } },
|
|
3303
|
+
required: ['x', 'y'],
|
|
3304
|
+
},
|
|
3305
|
+
execute: (a) => Number(a.x) + Number(a.y),
|
|
3306
|
+
}),
|
|
3307
|
+
)
|
|
3209
3308
|
const worker = createScopeServer({ tools, name: 'worker-mcp', version: '1.0.0' }, scope)
|
|
3210
3309
|
|
|
3211
3310
|
const { port1, port2 } = new MessageChannel()
|
|
@@ -3219,7 +3318,7 @@ port2.postMessage(
|
|
|
3219
3318
|
'{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}',
|
|
3220
3319
|
)
|
|
3221
3320
|
|
|
3222
|
-
log(await reply) // '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"add","inputSchema":{"type":"object"}}]}}'
|
|
3321
|
+
log(await reply) // '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"add","inputSchema":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"]}}]}}'
|
|
3223
3322
|
worker.stop() // unbinds every binding, closes every accepted MessagePort
|
|
3224
3323
|
```
|
|
3225
3324
|
|
|
@@ -3884,12 +3983,12 @@ digesting, or execution. Whichever it is, one reference then reaches the argumen
|
|
|
3884
3983
|
the input selector, the canonical `ToolCall`, and the executor — no step re-snapshots, so no
|
|
3885
3984
|
step can be looking at a different value from another.
|
|
3886
3985
|
|
|
3887
|
-
|
|
3888
|
-
|
|
3889
|
-
|
|
3890
|
-
no protocol change to point at. Refusing a mutation of
|
|
3891
|
-
failure rather than a protocol fault, so that is where it is
|
|
3892
|
-
mutable bag copies first: `const working = { ...args }`.
|
|
3986
|
+
A `Tool` hands its handler `contract.parse(args)`, an owned copy, so only a tool built with
|
|
3987
|
+
`strict: false` sees that record. It is shared and frozen, which is worth knowing before it
|
|
3988
|
+
surprises you: a raw tool that writes to its own `arguments` throws, and the client sees an
|
|
3989
|
+
ordinary `isError: true` tool result with no protocol change to point at. Refusing a mutation of
|
|
3990
|
+
server-owned input is a tool-domain failure rather than a protocol fault, so that is where it is
|
|
3991
|
+
reported. A raw tool that needs a mutable bag copies first: `const working = { ...args }`.
|
|
3893
3992
|
|
|
3894
3993
|
The reporter exists only when `_meta.progressToken` is a string or integer.
|
|
3895
3994
|
`report` requires a bounded payload with finite, strictly increasing values and awaits
|
|
@@ -3935,7 +4034,7 @@ const server = createMCPServer({
|
|
|
3935
4034
|
{ type: 'text', text: 'Preview' },
|
|
3936
4035
|
{ type: 'image', data: 'iVBORw0KGgo=', mimeType: 'image/png' },
|
|
3937
4036
|
],
|
|
3938
|
-
structuredContent:
|
|
4037
|
+
structuredContent: { slides: 1 },
|
|
3939
4038
|
}
|
|
3940
4039
|
},
|
|
3941
4040
|
})
|
|
@@ -3992,12 +4091,15 @@ import {
|
|
|
3992
4091
|
|
|
3993
4092
|
const limits = { bytes: 4096, keys: 64, depth: 16 }
|
|
3994
4093
|
const parameters = { prompt: 'owl' }
|
|
3995
|
-
const call = buildToolCall(
|
|
3996
|
-
|
|
3997
|
-
|
|
3998
|
-
|
|
3999
|
-
|
|
4000
|
-
}
|
|
4094
|
+
const call = buildToolCall(
|
|
4095
|
+
{
|
|
4096
|
+
jsonrpc: '2.0',
|
|
4097
|
+
id: 1,
|
|
4098
|
+
method: 'tools/call',
|
|
4099
|
+
params: { name: 'render', arguments: parameters },
|
|
4100
|
+
},
|
|
4101
|
+
parameters,
|
|
4102
|
+
)
|
|
4001
4103
|
const canonical = serializeJSON(parameters, limits)
|
|
4002
4104
|
const digest = await digestJSON(parameters, limits)
|
|
4003
4105
|
const notification = buildProgressNotification('render-1', { progress: 1, total: 2 })
|
|
@@ -4120,7 +4222,7 @@ import { createMCPContinuation } from '@orkestrel/mcp/server'
|
|
|
4120
4222
|
import { createTool, createToolManager } from '@orkestrel/tool'
|
|
4121
4223
|
|
|
4122
4224
|
const tools = createToolManager()
|
|
4123
|
-
tools.add(createTool({ name: 'reply', execute: (input) => input }))
|
|
4225
|
+
tools.add(createTool({ name: 'reply', parameters: { type: 'object' }, execute: (input) => input }))
|
|
4124
4226
|
|
|
4125
4227
|
const server = createMCPServer({
|
|
4126
4228
|
identity: { name: 'supervisor', version: '1.0.0' },
|
|
@@ -4386,7 +4488,7 @@ import {
|
|
|
4386
4488
|
import { createTool, createToolManager } from '@orkestrel/tool'
|
|
4387
4489
|
|
|
4388
4490
|
const tools = createToolManager()
|
|
4389
|
-
tools.add(createTool({ name: 'render', execute: (input) => input }))
|
|
4491
|
+
tools.add(createTool({ name: 'render', parameters: { type: 'object' }, execute: (input) => input }))
|
|
4390
4492
|
|
|
4391
4493
|
const server = createMCPServer({
|
|
4392
4494
|
identity: { name: 'supervisor', version: '1.0.0' },
|
|
@@ -4655,7 +4757,17 @@ serverSide.connect(clientSide)
|
|
|
4655
4757
|
clientSide.connect(serverSide)
|
|
4656
4758
|
|
|
4657
4759
|
const tools = createToolManager()
|
|
4658
|
-
tools.add(
|
|
4760
|
+
tools.add(
|
|
4761
|
+
createTool({
|
|
4762
|
+
name: 'add',
|
|
4763
|
+
parameters: {
|
|
4764
|
+
type: 'object',
|
|
4765
|
+
properties: { x: { type: 'number' }, y: { type: 'number' } },
|
|
4766
|
+
required: ['x', 'y'],
|
|
4767
|
+
},
|
|
4768
|
+
execute: (a) => Number(a.x) + Number(a.y),
|
|
4769
|
+
}),
|
|
4770
|
+
)
|
|
4659
4771
|
const server = createMCPServer({ identity: { name: 'calculator', version: '1.0.0' }, tools })
|
|
4660
4772
|
bindServer(server, serverSide)
|
|
4661
4773
|
|
|
@@ -4984,7 +5096,7 @@ consumer can plan around it instead of discovering it.
|
|
|
4984
5096
|
| A built-in resource or prompt store | The `resources` / `prompts` / `completion` capabilities ship as ports, exactly as tools and durable tasks do. What backs one — a workspace, a database, a template registry, a plain object — is the host's decision, and a default store here would be product policy wearing a framework's clothes. |
|
|
4985
5097
|
| Server-initiated `elicitation/create` requests | 2026-07-28 removes server-initiated requests entirely. Input requests survive only inside a modern `tools/call` `input_required` result — see [Ask the client for input during the call in hand](#ask-the-client-for-input-during-the-call-in-hand). |
|
|
4986
5098
|
| Durable task or session storage | Task state outlives the request that created it and this package owns no persistence. The store arrives injected as `MCPTaskOptions.tasks`, exactly as `ToolManagerInterface` does — the extension's protocol ships here, its durability does not. |
|
|
4987
|
-
| `outputSchema` on tool descriptors
|
|
5099
|
+
| `outputSchema` on this server's tool descriptors | `ToolResult.value` (`@orkestrel/tool`) is `unknown`; the contract that owns the value owns its schema. `structuredContent` is produced without one, which no clause gates. `MCPClient` does enforce one a remote server declares. |
|
|
4988
5100
|
| Icons (2025-11-25) | Installed `@orkestrel/tool` definitions carry no icon field, so an MCP-only wrapper would have no originating consumer. |
|
|
4989
5101
|
| Withholding a consumer's own invalidly annotated tool from `tools/list` | The annotation is read and enforced on both sides; see [Protocol](#protocol) for the rules. The exclusion MUST binds an HTTP client, and this package's client transports honour it. A server that also dropped the definition would hide a consumer's tool from every peer over a mistake in one property, so this one serves it, recognizes no `Mcp-Param-*` name for it, and lets each conformant client exclude it. |
|
|
4990
5102
|
| `_meta['io.modelcontextprotocol/logLevel']` | The deprecated canonical value is validated as request metadata, but no consumer opts a request into server log emission. |
|
|
@@ -5556,25 +5668,26 @@ the exact statement:
|
|
|
5556
5668
|
client asking to `initialize` at `'2026-07-28'` is asking to negotiate a
|
|
5557
5669
|
revision that defines no negotiation, and the client decides what to do with
|
|
5558
5670
|
the legacy answer it gets. `ping` → `{}`. `tools/list` → `{ tools }`, each tool a
|
|
5559
|
-
`MCPToolDescriptor` (its `parameters` renamed to `inputSchema`,
|
|
5560
|
-
|
|
5671
|
+
`MCPToolDescriptor` (its `parameters` renamed to `inputSchema`, a tool
|
|
5672
|
+
that declares none advertising the closed empty object). `tools/call` → the executed
|
|
5561
5673
|
tool's `MCPCallResult`.
|
|
5562
5674
|
5. **Tool errors are tool results, not protocol errors.** `tools/call` reads
|
|
5563
5675
|
`params.name` (a string) + `params.arguments` (a record; the modern path defaults an
|
|
5564
5676
|
absent one to the shared frozen `EMPTY_MCP_ARGUMENTS`),
|
|
5565
5677
|
narrowed with `@orkestrel/contract`'s guards (no `as`); a missing /
|
|
5566
|
-
non-string `name` → a `-32602` invalid-params error
|
|
5678
|
+
non-string `name` → a `-32602` invalid-params error, and so does a name `tools.tool(name)` does
|
|
5679
|
+
not hold, naming the tool and the available names. Otherwise it runs
|
|
5567
5680
|
`tools.execute(call, context)` under the modern and legacy wire eras. The call carries
|
|
5568
5681
|
`{ id, name, arguments }`; the context carries the request's `signal` and the optional
|
|
5569
5682
|
`caller` from `options.caller`, omitted when absent. The tool body receives that context.
|
|
5570
5683
|
Because the `ToolManager`
|
|
5571
|
-
(`@orkestrel/tool`) already isolates a thrown tool
|
|
5572
|
-
into a `success: false` result, the server adds no try/catch: that branch's
|
|
5684
|
+
(`@orkestrel/tool`) already isolates a thrown tool and a refused argument
|
|
5685
|
+
record into a `success: false` result, the server adds no try/catch: that branch's
|
|
5573
5686
|
`error` maps to `{ content: [{ type: 'text', text: <error> }], isError: true }`;
|
|
5574
5687
|
a valued `success: true` branch maps to `{ content: [{ type: 'text', text:
|
|
5575
|
-
JSON.stringify(value) }]
|
|
5576
|
-
alongside the backwards-compatible text. A value-less success retains the
|
|
5577
|
-
empty text block and omits `structuredContent`.
|
|
5688
|
+
JSON.stringify(value) }] }`, and a record value also travels unchanged as
|
|
5689
|
+
`structuredContent` alongside the backwards-compatible text. A value-less success retains the
|
|
5690
|
+
required empty text block and omits `structuredContent`.
|
|
5578
5691
|
6. **One modern seam, subscriptions included, and `-32601` for anything off it.**
|
|
5579
5692
|
`server/discover`, `tools/list`, `tools/call`, and `subscriptions/listen` are registered on `server.methods` at
|
|
5580
5693
|
construction — unconditionally, because they need no consumer port — and
|
|
@@ -5618,8 +5731,11 @@ the exact statement:
|
|
|
5618
5731
|
metadata, and duplicated text/structured representations—is bounded before serialization; and
|
|
5619
5732
|
built-in subscription admission is capped until each stream's `finally` releases it.
|
|
5620
5733
|
Metadata/state failures use `-32602`; content/capacity failures use `-32603`. A
|
|
5621
|
-
|
|
5622
|
-
→ a serialized `-32600` (Invalid Request) response with `id: null
|
|
5734
|
+
batch, any other non-object, or a `method` beside an `id` that is not valid
|
|
5735
|
+
→ a serialized `-32600` (Invalid Request) response with `id: null`, and a malformed request
|
|
5736
|
+
carrying a valid id answers under that id. A response, malformed or not, and a malformed
|
|
5737
|
+
notification answer `undefined` and reach the `error` event, because JSON-RPC gives no
|
|
5738
|
+
response to a response and a notification waits on nothing. The
|
|
5623
5739
|
raw-string parse is the only `try`/`catch`; the guards (`parseJSONRPCMessage`
|
|
5624
5740
|
over `@orkestrel/jsonrpc`'s `isJSONRPCMessage`) are total and never throw.
|
|
5625
5741
|
8. **Total wire guards.** `isBoundedString` / `isBoundedJSON` / `isMCPResult` /
|
|
@@ -5770,12 +5886,15 @@ the exact statement:
|
|
|
5770
5886
|
exact open server-capability shapes and exact metadata before returning, rejects malformed
|
|
5771
5887
|
known fields or extension identifiers/values, and snapshots accepted capability/metadata
|
|
5772
5888
|
records with the installed exact JSON clone primitive so transport-owned objects cannot drift.
|
|
5773
|
-
`tools()` runs `tools/list`
|
|
5774
|
-
|
|
5889
|
+
`tools()` runs `tools/list` through `nextCursor` up to `MCP_LIST_PAGES` pages, refuses a page
|
|
5890
|
+
or a listing it cannot read as complete with an `MCPError`, and wraps each descriptor as a
|
|
5891
|
+
local `ToolInterface` — `inputSchema` mapped
|
|
5775
5892
|
back to `parameters` (the inverse of the `parameters` → `inputSchema` rename, no `as`),
|
|
5776
5893
|
`execute` bound to `call(name, …)`. `call(name, args)` runs `tools/call`,
|
|
5777
|
-
concatenates the result's `text` content blocks and throws an `Error` carrying
|
|
5778
|
-
`isError === true`,
|
|
5894
|
+
concatenates the result's `text` content blocks and throws an `Error` carrying
|
|
5895
|
+
the text when `isError === true`, refuses a success it cannot read, else takes an object
|
|
5896
|
+
`structuredContent`, checked against the listing's
|
|
5897
|
+
`outputSchema` when the tool declares one, or `JSON.parse`s the text (raw-string fallback;
|
|
5779
5898
|
empty → `undefined`); so a remote tool failure throws locally and an
|
|
5780
5899
|
agent's `ToolManager` isolates it into a `success: false` result exactly
|
|
5781
5900
|
like a local throw. `disconnect()` rejects every pending request, clears
|
|
@@ -5897,8 +6016,10 @@ the exact statement:
|
|
|
5897
6016
|
and sends unmasked frames), wraps it in a `WebSocketServerTransport`, and
|
|
5898
6017
|
pumps — each inbound `JSONRPCMessage` that `@orkestrel/jsonrpc`'s `isJSONRPCRequest` guard accepts runs
|
|
5899
6018
|
through `mcp.dispatch`, a defined response written back as a frame (a
|
|
5900
|
-
notification → `dispatch` `undefined` → nothing sent);
|
|
5901
|
-
|
|
6019
|
+
notification → `dispatch` `undefined` → nothing sent); invalid JSON or an invalid request
|
|
6020
|
+
is answered with `-32700` or `-32600`, and a stray response or a malformed notification is
|
|
6021
|
+
not answered; a transport,
|
|
6022
|
+
`dispatch`, or `send` fault surfaces on `mcp.emitter`'s
|
|
5902
6023
|
`error` event rather than escaping the async listener, and a peer whose
|
|
5903
6024
|
disconnect fires this transport's `close` is aborted by `bindServer` before
|
|
5904
6025
|
any response is written, so that disconnect costs no frame and raises no
|
|
@@ -6026,9 +6147,10 @@ the exact statement:
|
|
|
6026
6147
|
`process.stdout`) in a `StdioServerTransport` and pumps: each inbound
|
|
6027
6148
|
`@orkestrel/jsonrpc` `JSONRPCMessage` value that is a request runs through `mcp.dispatch`, a defined
|
|
6028
6149
|
response written back as a newline-terminated line after the output completion
|
|
6029
|
-
callback confirms it (a notification writes nothing);
|
|
6030
|
-
|
|
6031
|
-
|
|
6150
|
+
callback confirms it (a notification writes nothing); invalid JSON or an invalid request is
|
|
6151
|
+
answered with `-32700` or `-32600`, and a stray response or a malformed notification is not
|
|
6152
|
+
answered; a transport, `dispatch`, or
|
|
6153
|
+
`send` fault surfaces on `mcp.emitter`'s `error` event. `stop()` unbinds that pump and
|
|
6032
6154
|
closes the transport, which removes the listeners `start()` put on
|
|
6033
6155
|
`input` and `output`, rejects every pending send, preserves the caller's flowing or
|
|
6034
6156
|
non-flowing state and listeners,
|