@yolk-sdk/mcp 0.1.0-canary.13 → 0.1.0-canary.130

package/README.md

@@ -1,83 +1,436 @@
 # @yolk-sdk/mcp
 
-Domain-free Model Context Protocol client/server package.
+MCP v2 (`2026-07-28`) client/server/protocol APIs, Effect/Yolk adapters, and legacy compatibility.
 
-Root export is intentionally tiny. Import client, protocol, and server APIs from explicit subpaths.
+The root export is intentionally empty. Import APIs from explicit subpaths.
+
+## Tool schema admission
+
+Yolk's `tools/list` adapter admits `inputSchema` as the object arm of
+`@yolk-sdk/agent/protocol`'s `ToolJsonSchema`. This is plain finite JSON-data representation admission,
+not JSON Schema meta-validation. Boolean roots fail in the typed `McpError` validation channel;
+omitted schemas still default to `{ type: 'object', additionalProperties: true }`.
+Tool arguments/results remain opaque until their execution/provider boundary.
 
 ## Install
 
 ```bash
-pnpm add @yolk-sdk/mcp@canary @yolk-sdk/agent@canary effect
+pnpm add @yolk-sdk/mcp@canary @yolk-sdk/agent@canary effect@4.1.2
 ```
 
+Running the experimental `@yolk-sdk/mcp/conformance` cases? Also add `@yolk-sdk/conformance@canary` (usually as a dev dependency); the examples import `@yolk-sdk/conformance/*` subpaths directly.
+
 Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
+Use the SDK's matching Effect version (`4.1.2`) in host code.
+Published package metadata requires Node.js 22+; `client/node` and `server/node` are Node-only.
 
 ## Subpaths
 
-| Subpath | Purpose |
-| --- | --- |
-| `@yolk-sdk/mcp/client` | Remote/local MCP config, tool listing/calling, protocol adapters |
-| `@yolk-sdk/mcp/client/node` | Node-only local stdio convenience helpers |
-| `@yolk-sdk/mcp/protocol` | JSON-RPC/MCP wire helpers |
-| `@yolk-sdk/mcp/server` | Tool-only MCP server primitives |
+| Subpath                     | Purpose                                                                |
+| --------------------------- | ---------------------------------------------------------------------- |
+| `@yolk-sdk/mcp/client`      | Official full-core client plus Effect/Yolk list and call helpers       |
+| `@yolk-sdk/mcp/client/node` | Official stdio client transport plus NodeServices convenience wrappers |
+| `@yolk-sdk/mcp/conformance` | Experimental MCP conformance cases, target, seeds, and fixtures        |
+| `@yolk-sdk/mcp/core`        | Official MCP v2 wire schemas                                           |
+| `@yolk-sdk/mcp/protocol`    | Yolk JSON-RPC/MCP adapter helpers                                      |
+| `@yolk-sdk/mcp/server`      | Official full-core server plus Yolk tool-only server primitives        |
+| `@yolk-sdk/mcp/server/node` | Official dual-era stdio server entrypoint                              |
+
+Use `core` for the official full MCP wire-schema surface. Use `protocol` only for Yolk adapters and
+legacy JSON-RPC helpers; it is not a replacement for the full-core APIs.
+
+Yolk JSON-RPC initialize and tools/call construction uses Schema owners on both
+`@yolk-sdk/mcp/client` and `@yolk-sdk/mcp/protocol` (same `protocol.ts`; no new export subpath):
+
+| Symbol                    | Role                                                                           |
+| ------------------------- | ------------------------------------------------------------------------------ |
+| `InitializeClientInfo`    | `{ name, version }`                                                            |
+| `InitializeParams`        | `{ protocolVersion, capabilities, clientInfo }`                                |
+| `InitializedNotification` | `{ jsonrpc: '2.0', method: 'notifications/initialized' }` (no `id` / `params`) |
+| `ToolsCallParams`         | `{ name, arguments? }`                                                         |
+
+Prefer those Schema owners for new construction. Compatibility constructors
+`makeJsonRpcRequest`, `makeInitializeParams`, and `makeInitializedNotification` remain and build
+through the schemas. `makeJsonRpcRequest` still omits `params` when `undefined`.
 
 ## Imports
 
 ```ts
-import { listMcpTools } from '@yolk-sdk/mcp/client'
-import { listMcpToolsNode } from '@yolk-sdk/mcp/client/node'
-import { makeJsonRpcRequest } from '@yolk-sdk/mcp/protocol'
-import { makeMcpToolServer } from '@yolk-sdk/mcp/server'
+import { Client } from '@yolk-sdk/mcp/client'
+import { listLocalMcpServerToolsNode } from '@yolk-sdk/mcp/client/node'
+import * as McpCore from '@yolk-sdk/mcp/core'
+import { McpServer } from '@yolk-sdk/mcp/server'
+import { serveStdio } from '@yolk-sdk/mcp/server/node'
 ```
 
-## Remote client
+## Use the full MCP v2 client
+
+The official client surface supports tools, resources, prompts, completions, MRTR, response caching, subscriptions, OAuth helpers, and legacy negotiation.
+
+```ts
+import { Client, StreamableHTTPClientTransport } from '@yolk-sdk/mcp/client'
+
+const client = new Client(
+  { name: 'my-app', version: '1.0.0' },
+  { versionNegotiation: { mode: 'auto' } }
+)
+
+await client.connect(new StreamableHTTPClientTransport(new URL('https://example.com/mcp')))
+
+const { tools } = await client.listTools()
+```
+
+`mode: 'auto'` prefers stateless MCP `2026-07-28` and falls back to an initialize-based server. Pin `{ pin: '2026-07-28' }` for modern-only behavior. The upstream `Client` default remains legacy for compatibility.
+
+## Use Effect/Yolk tool adapters
+
+The high-level remote helpers use the official v2 client over an Effect `HttpClient` bridge. They negotiate modern MCP automatically, aggregate paginated tool lists, honor v2 routing headers and cache hints, and fall back to legacy servers. Discovered tools preserve provider `title`, `inputSchema`, `outputSchema`, and `annotations` metadata. Adapted tools are typed ([ADR 0013](https://github.com/magoz/yolk-sdk/blob/main/docs/adr/0013-typed-tool-results.md)): `ToolDef.outputSchema` is `{ value, files }` (`value` the server's `outputSchema`, unknown without one) and a successful call's `structuredContent` is `{ value, files }`: `value` is the server's `structuredContent` (checked against the listed `outputSchema`, remote and local), else the text of its text blocks and embedded text resources parsed once when it is one JSON object or array, else the text (`resource_link` blocks never enter it); blobs, images and audio become file fields (`FileRef`, or `FileUnavailable` without a file store). The model still sees the server's content, unchanged for results without file blocks. Registrations of adapted tools set `decodeOutput: mcpToolOutputDecoder` (`resolveTools` checks every result with it and fails `output_validation_required` without it). Files are stored when the call runs, through the `ToolFileCapture` `resolveTools` provides to its registrations; a call outside one (a HITL route calling `resumeRemoteMcpServerToolCall`, a direct `callLocalMcpServerTool`) passes `fileCapture: makeToolFileCapture({ store })` from `@yolk-sdk/agent/tools` on its input, or every file is `FileUnavailable` (`no file store`) and the blob is lost. Pass `exposure` in the options (a `ToolExposure` value or `(tool, serverName) => ToolExposure`) to set code mode `callableBy`/`discovery` on the adapted definitions; `mcpToolToToolDef` takes the same option.
 
 ```ts
 import { Effect } from 'effect'
+import { FetchHttpClient } from 'effect/http'
 import { listRemoteMcpServerTools } from '@yolk-sdk/mcp/client'
 
-const tools = listRemoteMcpServerTools({
-  id: 'docs',
-  transport: { kind: 'http', url: 'https://example.com/mcp' },
-  allowHttpLocalhost: false
+const tools = await Effect.runPromise(
+  listRemoteMcpServerTools({
+    name: 'docs',
+    type: 'remote',
+    url: 'https://example.com/mcp'
+  }).pipe(Effect.provide(FetchHttpClient.layer))
+)
+```
+
+Use `McpClientOptions.sdk` for official client options such as capabilities, MRTR, and shared response caching. Set `McpClientOptions.configureClient` to register elicitation or sampling handlers before connection. Use a persistent official `Client` directly for long-lived subscriptions and progress streams.
+
+## Form elicitation for durable hosts (MRTR)
+
+A server can pause a `tools/call` with an MCP `2026-07-28` `InputRequiredResult` (for example to
+confirm a destructive tool with a form). A durable host cannot block on a person inside a tool
+step, so Yolk returns the pause as data and resumes later, possibly in another process:
+
+```ts
+import { Effect } from 'effect'
+import { makeToolFileCapture } from '@yolk-sdk/agent/tools'
+import {
+  callRemoteMcpServerToolResumable,
+  resumeRemoteMcpServerToolCall,
+  type McpClientOptions,
+  type McpElicitationResponse,
+  type McpElicitationResponses
+} from '@yolk-sdk/mcp/client'
+
+const options: McpClientOptions = { elicitation: { form: true } }
+
+// A resume runs outside `resolveTools`: pass a capture (`makeToolFileCapture({ store })` from
+// `@yolk-sdk/agent/tools`) or the resumed result's blobs are `FileUnavailable` and lost.
+const call = {
+  config,
+  mcpToolName: 'delete-invoice',
+  toolCallId: 'call_1',
+  params,
+  options,
+  fileCapture: makeToolFileCapture({ store })
+}
+
+const step = Effect.gen(function* () {
+  const outcome = yield* callRemoteMcpServerToolResumable(call)
+
+  if (outcome._tag === 'Complete') return outcome.result
+
+  // Integration fragment: persist outcome.inputRequired (a Schema class) and show its forms to a
+  // person; resume later, possibly in another process, with their decisions, one per form keyed
+  // by its `key`. This sketch declines every form (the safe default when nobody decides); never
+  // auto-accept a confirmation.
+  const decline: McpElicitationResponse = { action: 'decline' }
+  const responses: McpElicitationResponses = Object.fromEntries(
+    outcome.inputRequired.elicitations.map(form => [form.key, decline])
+  )
+
+  return yield* resumeRemoteMcpServerToolCall({
+    ...call,
+    inputRequired: outcome.inputRequired,
+    responses
+  })
+})
+```
+
+- `elicitation: { form: true }` is the opt-in. Only then do the listing and the resumable call
+  functions declare `elicitation.form`, in the per-request `_meta` client capabilities of a modern
+  connection. Nothing declares it in a legacy `initialize`, and `callRemoteMcpServerTool` (which
+  cannot represent a pause) never declares it.
+- The outcome is `Complete` (a `ToolResult`) or `InputRequired` (`McpInputRequired`: Schema-decoded
+  form elicitations with `key`, `message` and `requestedSchema`, the opaque `requestState`, the
+  binding `mcpToolName` and `argumentsDigest`, and the listed tool definition `tool`).
+- The bound is 256 KiB of JSON by default (`elicitation.maxInputRequiredBytes`, a positive
+  integer, checked before connecting) plus 16 requests, applied to two parts separately. The
+  server-provided pause (the `InputRequiredResult` and the decoded pause without its tool
+  definition) is checked after the response body is buffered, so it bounds what is decoded and
+  persisted, not what is received. The listed tool definition is checked before the call: a tool
+  whose definition alone exceeds the bound fails `too_large` with nothing sent, so a pause the
+  server already made is never lost to the bound. A persisted pause is at most about twice the
+  bound.
+- The resume is re-sent as a new request on a new connection with the same tool call (checked
+  against the pause's binding), the exact `requestState`, and the decisions (`accept` with
+  `content`, `decline`, `cancel`) as `inputResponses`. It lists nothing: it calls with the pause's
+  tool definition (for `x-mcp-header` mirroring) and checks the result against its `outputSchema`.
+  A carried definition that is not a valid MCP tool fails `malformed` before sending. Because the
+  definition is passed as `toolDefinition`, the official client does not re-list and retry after a
+  `HEADER_MISMATCH` (`-32020`): a server that changed the tool's `x-mcp-header` declarations since
+  the pause answers `McpError` (`cause: 'protocol'`). Decisions are checked before anything is sent
+  (type (integer vs number), `required`, `const`, `enum`, titled `oneOf`, `minLength`/`maxLength`, `format` (email, uri, date, date-time), `minimum`/`maximum`, `items.enum`, titled `items.anyOf`, `minItems`/`maxItems`); the server validates them again. The server may pause again.
+- The carried definition is `name`, `inputSchema` and `outputSchema`: the only `toolDefinition`
+  fields the pinned official client reads. `annotations`, `_meta` and `execution` (task support,
+  which its `2026-07-28` codec removes from listings) are not carried.
+- The pause is decoded from the raw `input_required` response as the server sent it: the response
+  the official client resolves the call with (the first whose id matches under the client's own
+  `Number(id)` coercion), captured at the transport before the client normalises it (it would drop
+  a non-string `requestState` and turn non-object `inputRequests` into `{}`). Such a response, or a
+  matched one whose id is not identical to the call's (`"1"` for `1`), fails `malformed`; other
+  ids, notifications and later duplicates are ignored.
+- Formats are syntax checks, all linear: `date`/`date-time` per RFC 3339 on the proleptic
+  Gregorian calendar (years 0000-9999; second `60` only at `23:59:60` UTC after the offset); `uri`
+  an absolute RFC 3986 URI (scheme, then unreserved, sub-delims and the delimiters, other characters
+  percent-encoded; IP literals per the `IPv6address` grammar or `IPvFuture`; no WHATWG
+  normalisation);
+  `email` a pragmatic mailbox: a dot-atom local part (RFC 5322 `atext` runs joined by single dots,
+  at most 64 characters; no quoted strings), `@`, and a hostname of at least two LDH labels.
+- Typed failures: `McpInputRequiredError` (`malformed`, `too_large`, `unsupported_request` for URL
+  mode, sampling, roots or input without the opt-in, `invalid_responses`, `mismatched_resume`,
+  `unsupported_era`) and `McpClientCapabilityRequiredError` for MCP `-32021`.
+- Legacy-era elicitation (a server-initiated request answered while the call's stream is open) is
+  not supported; resuming against a legacy connection fails with `unsupported_era`.
+
+### Files in tool results
+
+A successful call's `structuredContent` is `{ value, files }`
+([ADR 0013](https://github.com/magoz/yolk-sdk/blob/main/docs/adr/0013-typed-tool-results.md)):
+embedded text resources go into `value` with the text blocks, and blobs, images and audio become
+`files`, each a `FileRef` `{ fileId, name, mimeType, size }` (blob names come from the URI) or a
+`FileUnavailable` `{ unavailable, name, mimeType }`. The model sees blob resources as file labels
+(never base64) and images and audio as the server sent them, followed by their label once stored.
+
+Files are stored while the call runs. Inside a `resolveTools` registration they go to the
+resolution's `files` store. A call made anywhere else (a HITL route resuming
+`resumeRemoteMcpServerToolCall`, a direct `callRemoteMcpServerTool` or `callLocalMcpServerTool`)
+passes `fileCapture: makeToolFileCapture({ store })` (`@yolk-sdk/agent/tools`); without it every
+file is `FileUnavailable` (`no file store`), and the blob cannot be fetched again later. See
+[Move files between tools](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/integrations/files.mdx).
+
+When adapting Yolk tools into an MCP server (`makeMcpToolServer`), an inline `FilePart` leaves as
+an embedded resource blob and a stored (or omitted) one as its label.
+
+## Connect to a local stdio server
+
+Node hosts can use the convenience wrappers from `client/node`:
+
+```ts
+import { Effect } from 'effect'
+import { listLocalMcpServerToolsNode } from '@yolk-sdk/mcp/client/node'
+
+const tools = await Effect.runPromise(
+  listLocalMcpServerToolsNode(
+    {
+      name: 'local-tools',
+      type: 'local',
+      command: [process.execPath, './mcp-server.mjs'],
+      environment: {}
+    },
+    { securityPolicy: { allowLocalServers: true, allowDevHttpLocalhost: false } }
+  )
+)
+```
+
+Local servers are disabled by default. The host must explicitly allow them, choose a trusted
+command, and provide the complete child environment; configured environment values do not extend
+the host environment.
+
+## Build a full MCP server
+
+Use the official server surface for tools, resources, prompts, completions, MRTR, and subscriptions:
+
+```ts
+import { McpServer, createMcpHandler } from '@yolk-sdk/mcp/server'
+
+const handler = createMcpHandler(() => {
+  const server = new McpServer({ name: 'my-server', version: '1.0.0' })
+  // Register tools, resources, and prompts here.
+  return server
 })
 
-// Host provides HttpClient layer and auth policy.
-Effect.runPromise(tools)
+export default { fetch: handler.fetch }
 ```
 
-## Local stdio client
+`createMcpHandler` serves stateless `2026-07-28` and legacy initialize-based HTTP clients from one endpoint. Validate `Origin` and `Host` before calling `handler.fetch`.
+
+For dual-era Node stdio, import `serveStdio` from `@yolk-sdk/mcp/server/node`. This subpath owns the
+Node stdio transport only; the host owns authorization, process lifecycle, logging, and deployment
+policy.
+
+## Adapt Yolk tools into MCP
 
 ```ts
-import { listMcpToolsNode } from '@yolk-sdk/mcp/client/node'
+import { makeMcpToolServer, runStdioMcpServer } from '@yolk-sdk/mcp/server'
 ```
 
-`@yolk-sdk/mcp/client/node` may use Node process APIs. Keep Worker/browser imports on `@yolk-sdk/mcp/client`.
+`makeMcpToolServer` exposes approved Yolk tools. Its HTTP handler accepts both stateless v2 and legacy requests, validates browser origins against the endpoint hostname by default, and preserves MCP content and structured results. No tool call outlives `handleHttpRequest` (an SSE answer is read to its end, and a read failure answers 500 with `-32603`; a call still running is interrupted and awaited), so its requirements may come from a scoped request layer; a cancelled request that carries `MCP-Protocol-Version` interrupts the tool. `subscriptions/listen` answers its acknowledgement plus a `complete` result: this tool-only server has no change notifications. `runStdioMcpServer` remains the Effect-native minimal stdio adapter; use `serveStdio` for the full modern stdio surface.
 
-## Server
+For legacy HTTP requests, an unreadable or already consumed body produces a JSON-RPC
+invalid-request error (`-32600`) rather than an Effect defect. Malformed JSON remains a parse error
+(`-32700`).
+
+A tool may carry `annotations` (`title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`,
+`openWorldHint`), listed as the MCP tool annotations.
+
+### Ask the user before a tool runs
+
+An approval tool (`McpServerApprovalTool`) runs only after the user accepts the call through MCP
+form elicitation over multi round-trip requests (`2026-07-28`). Give the server `approvals`:
 
 ```ts
-import { makeMcpToolServer } from '@yolk-sdk/mcp/server'
+import { Effect } from 'effect'
+import { ToolDef, ToolResult } from '@yolk-sdk/agent/protocol'
+import { makeMcpToolServer, type McpServerTool } from '@yolk-sdk/mcp/server'
+
+declare const signingKey: string // at least 32 bytes, the same on every instance
+declare const tokenId: string // the authenticated principal of this request
+
+const send: McpServerTool = {
+  def: ToolDef.make({
+    name: 'send',
+    description: 'Send a message',
+    parameters: { type: 'object' }
+  }),
+  annotations: { destructiveHint: false },
+  approval: { message: call => Effect.succeed(`Send ${JSON.stringify(call.params)}?`) },
+  execute: (call, approved) =>
+    // Run the call at most once per `approved.approvalId`.
+    Effect.succeed(ToolResult.make({ toolCallId: call.id, content: 'sent' }))
+}
+
+const server = makeMcpToolServer({
+  name: 'my-server',
+  version: '1.0.0',
+  tools: [send],
+  approvals: { key: signingKey, principal: tokenId }
+})
 ```
 
-The server is tool-only. Hosts own HTTP routes, auth, deployment, and tool policy.
-Protocol document parts are exposed as MCP resource blocks with encoded `file:///...` URIs.
+- The first call answers an `input_required` result: one form elicitation under
+  `approvalInputKey` (`'approval'`, no fields: the client offers accept, decline and cancel) with
+  the policy's `message`, and a `requestState` signed by the SDK's `createRequestStateCodec`
+  (HMAC-SHA256, `ttlSeconds` default 600) and bound to `principal` and `tools/call`. Its payload
+  names the tool, the digest of the arguments (`mcpArgumentsDigest`) and a fresh `approvalId`.
+- Only a retry that answers `accept` with a state that verifies for the same principal, tool and
+  arguments runs the tool, with `{ approvalId }`. A decline or a cancel answers an error result.
+  A state that fails verification, belongs to another call, or arrives without a decision asks
+  again with a new state.
+- Build the server per request: `principal` is fixed when it is built. The state is also bound to
+  the server's `name`.
+- The server keeps no state, so an accepted retry replays until the state expires: key once-only
+  execution on `approvalId`.
+- A direct tool refuses a call that answers an approval prompt (a `requestState` or an answer under
+  `approvalInputKey`, `staleApprovalMessage`): when the host's policy turned an approval tool into a
+  direct one between the prompt and the answer, neither a decline nor a replayed accept becomes a
+  plain call.
+- A request that does not declare form elicitation gets an error result and nothing runs.
+  Approval tools are not offered on 2025-era requests (stateless serving cannot route the
+  client's answer back to the open call) or on the header-less JSON path, and not at all without
+  `approvals`. Unusable `approvals` (a key under 32 bytes, an empty `principal`, a `ttlSeconds`
+  that is not a positive integer) leave them listed but answering an error result that names the
+  problem.
 
-## Host responsibilities
+## Conformance cases (experimental)
 
-- Own persisted MCP server config, auth, and product tool policy.
-- Provide HTTP runtime layers and credentials for remote MCP.
-- Keep Node stdio usage behind Node-only hosts.
+`@yolk-sdk/mcp/conformance` holds nine `read` conformance cases for `@yolk-sdk/conformance/runner`,
+plus one opt-in `read` case, `mcpElicitationDeclarationCase` (fixtures:
+`mcpConformanceElicitationFixtures`), for hosts that set `McpClientOptions.elicitation`; it only
+lists, so it never triggers a confirmation.
+They check the wire claims the remote client relies on: era negotiation, the modern stateless
+headers, the legacy session, response encoding, the tool listing, a read call, a tool error, an
+unknown tool, and a rejected credential. Every case runs the real `listRemoteMcpServerTools` and
+`callRemoteMcpServerTool` through an observing `HttpClient`. The observer never sends a request of
+its own (it may refuse to forward one, see below). It never keeps `authorization` or any other
+credential-named header, never keeps the URL query, and never keeps a raw `mcp-session-id` value
+(only evidence: an equality class such as `session#1`). It keeps request and response bodies
+exactly as received; they may reflect anything a server echoes, credentials and session ids
+included, so they are sensitive: in memory only, never logged or persisted. Persisted or printed
+output is the live runner's job.
 
-## Boundaries
+A case that calls a tool (`mcp.modern.stateless`, `mcp.errors.unknown-tool`,
+`mcp.tools.call-read`, `mcp.tools.call-tool-error`) is protected by the observer's fail-closed call
+gate. The `tools/call` is forwarded only when every exchange of the call operation is fully
+understood, that operation's own listing (made right before the call) is complete, and that
+listing proves the call safe: the absent tool is not listed, or the read tool is marked
+`readOnlyHint: true`. Anything else, including any uncertainty (a 202 answer to a request, a
+message delivered on a GET, an unparseable body, an unterminated stream, two responses for one id,
+an unknown shape), refuses to forward. A refusal before any forwarded call fails the precondition
+with zero forwarded calls; a refused client retry after a forwarded call is reported as a retry.
+Earlier preflight listings stay as friendly early failures. Answers are read as the SDK reads them:
+JSON with `JSON.parse` semantics, and event streams with the SDK's own parser
+(the same `eventsource-parser` the client resolves, verified in-repo by a parity test; a consumer
+install whose package manager does not dedupe could still resolve two copies), fed the decoder
+chunks the client's `TextDecoderStream` emits.
+
+Mismatch messages carry only structural facts (methods, statuses, counts, positions, codes), never
+body text or the target URL. A client failure a case re-raises is reported as the client words it
+(it can quote a server body) and is sanitized by the runner. A host provides an `HttpClient`, an
+`McpConformanceTarget` (server URL, headers, era, protocol version, timeout), and
+`McpConformanceConfig` seeds. The cases name no product: provider targets and seeds live with the
+provider. `selectMcpConformanceCases` leaves out the cases of the other era. The synthetic fixtures
+replay on `https://mcp.example.test/modern/mcp` and `https://mcp.example.test/legacy/mcp`. See the
+conformance API reference for every claim.
+
+```ts
+import { Effect, Layer } from 'effect'
+import { FetchHttpClient } from 'effect/http'
+import { runConformance } from '@yolk-sdk/conformance/runner'
+import {
+  McpConformanceConfig,
+  McpConformanceTarget,
+  mcpConformanceCases,
+  selectMcpConformanceCases
+} from '@yolk-sdk/mcp/conformance'
 
-- App auth, persisted config, policy, and product tools stay outside this package.
-- Node convenience wrappers stay behind `@yolk-sdk/mcp/client/node`.
-- MCP may adapt to `@yolk-sdk/agent/protocol` tool types; agent loop/providers stay MCP-agnostic.
-- Remote MCP requires `https:` by default; localhost HTTP is explicit dev policy.
+const target = {
+  name: 'docs',
+  url: 'https://example.com/mcp',
+  headers: {},
+  era: 'modern',
+  protocolVersion: '2026-07-28',
+  timeoutMs: 30_000
+} as const
 
-## Tree-shaking
+const { applicable } = selectMcpConformanceCases(mcpConformanceCases, target.era)
+
+const report = await Effect.runPromise(
+  runConformance(applicable, {
+    target: { kind: 'live', account: 'practice' },
+    layer: () =>
+      Layer.mergeAll(
+        FetchHttpClient.layer,
+        Layer.succeed(McpConformanceTarget, target),
+        Layer.succeed(McpConformanceConfig, {})
+      )
+  })
+)
+```
+
+No case is observed live yet. Only code under `src/conformance/` may import `@yolk-sdk/conformance`.
+
+## Host responsibilities
+
+- Own persisted server config, credentials, authorization policy, and enabled capabilities.
+- Partition private MCP caches by authorization context.
+- Validate HTTP `Origin` and `Host` at deployment boundaries.
+- Keep Node stdio usage behind trusted Node hosts and explicitly control child commands and environments.
+- Treat tool annotations, server identity, icons, and request state as untrusted input.
+
+Remote MCP requires HTTPS by default; localhost HTTP is an explicit development policy.
+
+## Boundaries
 
-- ESM package with `sideEffects: false`.
-- Explicit subpath exports only.
-- No wildcard exports or root feature barrel.
+- MCP is external protocol infrastructure, not agent-loop or provider policy.
+- `core`, `client`, and `server` expose protocol mechanics; Yolk adapters bridge generic tool and
+  content contracts only.
+- App auth, credential storage, persisted server config, and product catalogs remain host-owned.
+- Node process and stdio conveniences stay behind `client/node` and `server/node`.

package/dist/client/client.d.mts

@@ -1,40 +1,104 @@
 import { McpClientInfo, McpLocalServerConfig, McpRemoteServerConfig, McpSecurityPolicy, McpServerConfig } from "./config.mjs";
-import { McpError } from "./errors.mjs";
-import { mcpToolToToolDef } from "./protocol.mjs";
+import { McpElicitationResponses, McpElicitationSupport, McpInputRequired, McpToolCallOutcome } from "./elicitation.mjs";
+import { McpClientCapabilityRequiredError, McpError, McpInputRequiredError } from "./errors.mjs";
+import { McpToolAnnotations, McpToolExposureResolver, mcpToolToToolDef } from "./protocol.mjs";
 import { Effect } from "effect";
-import { HttpClient } from "effect/unstable/http";
-import { ChildProcessSpawner } from "effect/unstable/process";
-import { ToolResult } from "@yolk-sdk/agent/protocol";
-
-//#region src/client/client.d.ts
-type McpClientOptions = {
+import { Client, ClientOptions } from "@modelcontextprotocol/client";
+import { HttpClient } from "effect/http";
+import { ChildProcessSpawner } from "effect/process";
+import { ToolFileCapture, ToolResult } from "@yolk-sdk/agent/protocol";
+export type McpClientOptions = {
   readonly clientInfo?: McpClientInfo;
   readonly securityPolicy?: McpSecurityPolicy;
   readonly timeoutMs?: number;
+  readonly sdk?: ClientOptions;
+  readonly configureClient?: (client: Client) => void;
+  /** Code mode exposure of the listed tools' definitions (listing functions only). */
+  readonly exposure?: McpToolExposureResolver;
+  /**
+   * Opt-in MCP form elicitation (multi round-trip requests, protocol `2026-07-28`). When set, the
+   * remote listing and the resumable call functions declare `elicitation.form` in the per-request
+   * `_meta` client capabilities of a modern connection. It is never declared in a legacy
+   * `initialize` (legacy elicitation is a server-initiated request the host would have to answer
+   * synchronously), and `callRemoteMcpServerTool`, which cannot represent a paused call, never
+   * declares it.
+   */
+  readonly elicitation?: McpElicitationSupport;
 };
-type McpResolvedTool = {
+export type McpResolvedTool = {
   readonly serverName: string;
   readonly mcpToolName: string;
+  readonly title?: string;
+  readonly outputSchema?: unknown;
+  readonly annotations?: McpToolAnnotations;
   readonly def: ReturnType<typeof mcpToolToToolDef>;
 };
-declare const listRemoteMcpServerTools: (config: McpRemoteServerConfig, options?: McpClientOptions) => Effect.Effect<ReadonlyArray<McpResolvedTool>, McpError, HttpClient.HttpClient>;
-declare const listLocalMcpServerTools: (config: McpLocalServerConfig, options?: McpClientOptions) => Effect.Effect<ReadonlyArray<McpResolvedTool>, McpError, ChildProcessSpawner.ChildProcessSpawner>;
-declare const listMcpServerTools: (config: McpServerConfig, options?: McpClientOptions) => Effect.Effect<readonly McpResolvedTool[], McpError, HttpClient.HttpClient | ChildProcessSpawner.ChildProcessSpawner>;
-type CallMcpServerToolInput = {
+export declare const listRemoteMcpServerTools: (config: McpRemoteServerConfig, options?: McpClientOptions) => Effect.Effect<ReadonlyArray<McpResolvedTool>, McpError, HttpClient.HttpClient>;
+export declare const listLocalMcpServerTools: (config: McpLocalServerConfig, options?: McpClientOptions) => Effect.Effect<ReadonlyArray<McpResolvedTool>, McpError, ChildProcessSpawner.ChildProcessSpawner>;
+export declare const listMcpServerTools: (config: McpServerConfig, options?: McpClientOptions) => Effect.Effect<readonly McpResolvedTool[], McpError, ChildProcessSpawner.ChildProcessSpawner | HttpClient.HttpClient>;
+export type CallMcpServerToolInput = {
   readonly config: McpServerConfig;
   readonly mcpToolName: string;
   readonly toolCallId: string;
   readonly params: unknown;
   readonly options?: McpClientOptions;
+  /**
+   * Stores the call's blobs, images and audio as file fields (ADR 0013), for example
+   * `makeToolFileCapture({ store })` from `@yolk-sdk/agent/tools`. Defaults to the ambient
+   * `ToolFileCapture`, which `resolveTools` provides around every registration; a call made
+   * outside one (a HITL route resuming a call, a host calling directly) needs this option, or
+   * every file is `FileUnavailable` (`no file store`).
+   */
+  readonly fileCapture?: ToolFileCapture['Service'];
 };
-declare const callRemoteMcpServerTool: (input: Omit<CallMcpServerToolInput, "config"> & {
+export declare const callRemoteMcpServerTool: (input: Omit<CallMcpServerToolInput, 'config'> & {
   readonly config: McpRemoteServerConfig;
 }) => Effect.Effect<ToolResult, McpError, HttpClient.HttpClient>;
-declare const callLocalMcpServerTool: (input: Omit<CallMcpServerToolInput, "config"> & {
+export type CallRemoteMcpServerToolInput = Omit<CallMcpServerToolInput, 'config'> & {
+  readonly config: McpRemoteServerConfig;
+};
+export type ResumeRemoteMcpServerToolCallInput = CallRemoteMcpServerToolInput & {
+  /** The paused call, exactly as the previous step answered it (persisted by the host). */
+  readonly inputRequired: McpInputRequired;
+  /** One decision per elicitation, keyed by `McpFormElicitation.key`. */
+  readonly responses: McpElicitationResponses;
+};
+export type McpResumableToolCallError = McpError | McpInputRequiredError | McpClientCapabilityRequiredError;
+/**
+ * Calls a remote MCP tool and answers a typed outcome instead of blocking on input:
+ * `Complete` (the adapted result) or `InputRequired` (a serializable `McpInputRequired` the host
+ * persists, decides on, and passes to `resumeRemoteMcpServerToolCall`). Like
+ * `callRemoteMcpServerTool`, it lists tools on its own connection before calling; the pause
+ * carries the listed definition. Set `options.elicitation` to declare form elicitation; without
+ * it a server may refuse a tool that needs confirmation (`McpClientCapabilityRequiredError` for
+ * MCP `-32021`, or a tool error result).
+ */
+export declare const callRemoteMcpServerToolResumable: (input: CallRemoteMcpServerToolInput) => Effect.Effect<McpToolCallOutcome, McpResumableToolCallError, HttpClient.HttpClient>;
+/**
+ * Resumes a paused remote MCP tool call: the same tool call (same `mcpToolName` and `params`,
+ * checked against the pause's binding) is re-sent as a new request on a new connection, with the
+ * exact `requestState`, the host's decisions as `inputResponses`, and the pause's tool definition
+ * (no listing). The server may pause again (`InputRequired`). Fails with `McpInputRequiredError`
+ * before sending when the call does not match the pause (`mismatched_resume`) or `responses` do
+ * not match the elicitations (`invalid_responses`), and when the server now negotiates a legacy
+ * era (`unsupported_era`).
+ */
+export declare const resumeRemoteMcpServerToolCall: (input: ResumeRemoteMcpServerToolCallInput) => Effect.Effect<McpToolCallOutcome, McpResumableToolCallError, HttpClient.HttpClient>;
+/**
+ * Calls a local stdio MCP tool in one session, in order: `initialize`, then `tools/list`, awaited
+ * and decoded, then the output validator compiled, and only then `tools/call`. So anything that
+ * fails before the call (an `initialize` error, an `outputSchema` that is unusable or does not
+ * compile) sends no `tools/call`, nor does a broken session (a stdout line that is no JSON-RPC
+ * response, an early end before the listing's answer). A listing answered with an error or an
+ * undecodable result, or one that does not hold the tool (the first page only), does not fail
+ * the call: it runs without output validation (a value-free warning is logged;
+ * `mcpToolOutputDecoder` still checks the `{ value, files }` envelope). A successful result of a
+ * tool with a usable `outputSchema` must carry `structuredContent` that passes it, as on the
+ * remote calls (`assertStructuredOutput`).
+ */
+export declare const callLocalMcpServerTool: (input: Omit<CallMcpServerToolInput, 'config'> & {
   readonly config: McpLocalServerConfig;
 }) => Effect.Effect<ToolResult, McpError, ChildProcessSpawner.ChildProcessSpawner>;
-declare const callMcpServerTool: (input: CallMcpServerToolInput) => Effect.Effect<ToolResult, McpError, ChildProcessSpawner.ChildProcessSpawner | HttpClient.HttpClient>;
-declare const listMcpTools: (configs: ReadonlyArray<McpServerConfig>, options?: McpClientOptions) => Effect.Effect<McpResolvedTool[], McpError, HttpClient.HttpClient | ChildProcessSpawner.ChildProcessSpawner>;
-//#endregion
-export { CallMcpServerToolInput, McpClientOptions, McpResolvedTool, callLocalMcpServerTool, callMcpServerTool, callRemoteMcpServerTool, listLocalMcpServerTools, listMcpServerTools, listMcpTools, listRemoteMcpServerTools };
+export declare const callMcpServerTool: (input: CallMcpServerToolInput) => Effect.Effect<ToolResult, McpError, ChildProcessSpawner.ChildProcessSpawner | HttpClient.HttpClient>;
+export declare const listMcpTools: (configs: ReadonlyArray<McpServerConfig>, options?: McpClientOptions) => Effect.Effect<McpResolvedTool[], McpError, ChildProcessSpawner.ChildProcessSpawner | HttpClient.HttpClient>;
 //# sourceMappingURL=client.d.mts.map

package/dist/client/client.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.mts","names":[],"sources":["../../src/client/client.ts"],"mappings":";;;;;;;;;KAgCY,gBAAA;EAAA,SACD,UAAA,GAAa,aAAA;EAAA,SACb,cAAA,GAAiB,iBAAiB;EAAA,SAClC,SAAA;AAAA;AAAA,KAGC,eAAA;EAAA,SACD,UAAA;EAAA,SACA,WAAA;EAAA,SACA,GAAA,EAAK,UAAU,QAAQ,gBAAA;AAAA;AAAA,cAqUrB,wBAAA,GACX,MAAA,EAAQ,qBAAA,EACR,OAAA,GAAU,gBAAA,KACT,MAAA,CAAO,MAAA,CAAO,aAAA,CAAc,eAAA,GAAkB,QAAA,EAAU,UAAA,CAAW,UAAA;AAAA,cAUzD,uBAAA,GACX,MAAA,EAAQ,oBAAA,EACR,OAAA,GAAU,gBAAA,KACT,MAAA,CAAO,MAAA,CACR,aAAA,CAAc,eAAA,GACd,QAAA,EACA,mBAAA,CAAoB,mBAAA;AAAA,cAYT,kBAAA,GAAsB,MAAA,EAAQ,eAAA,EAAiB,OAAA,GAAU,gBAAA,KAAgB,MAAA,CAAA,MAAA,UAAA,eAAA,IAAA,QAAA,EAAA,UAAA,CAAA,UAAA,GAAA,mBAAA,CAAA,mBAAA;AAAA,KAa1E,sBAAA;EAAA,SACD,MAAA,EAAQ,eAAA;EAAA,SACR,WAAA;EAAA,SACA,UAAA;EAAA,SACA,MAAA;EAAA,SACA,OAAA,GAAU,gBAAgB;AAAA;AAAA,cAmBxB,uBAAA,GACX,KAAA,EAAO,IAAA,CAAK,sBAAA;EAAA,SAA+C,MAAA,EAAQ,qBAAA;AAAA,MAClE,MAAA,CAAO,MAAA,CAAO,UAAA,EAAY,QAAA,EAAU,UAAA,CAAW,UAAA;AAAA,cAUrC,sBAAA,GACX,KAAA,EAAO,IAAA,CAAK,sBAAA;EAAA,SAA+C,MAAA,EAAQ,oBAAA;AAAA,MAClE,MAAA,CAAO,MAAA,CAAO,UAAA,EAAY,QAAA,EAAU,mBAAA,CAAoB,mBAAA;AAAA,cAU9C,iBAAA,GACX,KAAA,EAAO,sBAAA,KACN,MAAA,CAAO,MAAA,CACR,UAAA,EACA,QAAA,EACA,mBAAA,CAAoB,mBAAA,GAAsB,UAAA,CAAW,UAAA;AAAA,cAkB1C,YAAA,GAAgB,OAAA,EAAS,aAAA,CAAc,eAAA,GAAkB,OAAA,GAAU,gBAAA,KAAgB,MAAA,CAAA,MAAA,CAAA,eAAA,IAAA,QAAA,EAAA,UAAA,CAAA,UAAA,GAAA,mBAAA,CAAA,mBAAA"}
+{"version":3,"file":"client.d.mts","names":["SdkClientOptions","SdkClient"],"sources":["../../src/client/client.ts"],"mappings":";;;;;;;;;YA8EY;WACD,aAAa;WACb,iBAAiB;WACjB;WACA,MAAMA;WACN,mBAAmB,QAAQC;;WAE3B,WAAW;;;;;;;;;WASX,cAAc;;YAGb;WACD;WACA;WACA;WACA;WACA,cAAc;WACd,KAAK,kBAAkB;;qBAoYrB,2BAAwB,QAC3B,uBAAqB,UACnB,qBACT,OAAO,OAAO,cAAc,kBAAkB,UAAU,WAAW;qBA6BzD,0BAAuB,QAC1B,sBAAoB,UAClB,qBACT,OAAO,OACR,cAAc,kBACd,UACA,oBAAoB;qBAwBT,qBAAkB,QAAY,iBAAe,UAAY,qBAAgB,OAAA,gBAAA,mBAAA,UAAA,oBAAA,sBAAA,WAAA;YAa1E;WACD,QAAQ;WACR;WACA;WACA;WACA,UAAU;;;;;;;;WAQV,cAAc;;qBAGZ,0BAAuB,OAC3B,KAAK;WAA+C,QAAQ;MAClE,OAAO,OAAO,YAAY,UAAU,WAAW;YAsBtC,+BAA+B,KAAK;WACrC,QAAQ;;YAGP,qCAAqC;;WAEtC,eAAe;;WAEf,WAAW;;YAGV,4BACR,WACA,wBACA;;;;;;;;;;qBAgeS,mCAAgC,OACpC,iCACN,OAAO,OAAO,oBAAoB,2BAA2B,WAAW;;;;;;;;;;qBAuB9D,gCAA6B,OACjC,uCACN,OAAO,OAAO,oBAAoB,2BAA2B,WAAW;;;;;;;;;;;;;qBA2L9D,yBAAsB,OAC1B,KAAK;WAA+C,QAAQ;MAClE,OAAO,OAAO,YAAY,UAAU,oBAAoB;qBA2E9C,oBAAiB,OACrB,2BACN,OAAO,OACR,YACA,UACA,oBAAoB,sBAAsB,WAAW;qBAM1C,eAAY,SAAa,cAAc,kBAAgB,UAAY,qBAAgB,OAAA,OAAA,mBAAA,UAAA,oBAAA,sBAAA,WAAA"}