@smthrs/mcp 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/internal/Transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transport.js","sourceRoot":"","sources":["../../../src/internal/Transport.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The request/notify surface both MCP transports provide, and the failure\n * wording they share. {@link McpClient} speaks to this interface only; stdio\n * and Streamable HTTP differ in how a frame travels, not in what it means.\n *\n * @since 1.0.0-rc.1\n */\n\nimport { Effect, Stream } from \"effect\"\nimport { McpError } from \"../McpError.ts\"\nimport * as Limits from \"./Limits.ts\"\nimport type * as Rpc from \"./Rpc.ts\"\n\n/**\n * One live connection to an MCP server.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Transport {\n  /** Sends a request and resolves with its `result`, or fails with the server's `error`. */\n  readonly request: (method: string, params?: unknown, timeoutMs?: number) => Effect.Effect<unknown, McpError>\n  /** Sends a notification, bounding delivery by the optional positive-integer deadline. */\n  readonly notify: (method: string, params?: unknown, timeoutMs?: number) => Effect.Effect<void, McpError>\n}\n\n/**\n * Default request deadline.\n *\n * @category constants\n * @since 1.0.0-rc.0\n */\nexport const defaultRequestTimeoutMs = 120_000\n\n/**\n * Default maximum inbound JSON-RPC frame size (one MiB).\n *\n * @category constants\n * @since 1.0.0-rc.0\n */\nexport const defaultMaxFrameBytes = 1024 * 1024\n\n/**\n * Default maximum outbound JSON-RPC frame size (one MiB).\n *\n * @category constants\n * @since 1.0.0-rc.0\n */\nexport const defaultMaxOutboundFrameBytes = 1024 * 1024\n\n/**\n * The reason sent with a best-effort `notifications/cancelled`.\n *\n * @category constants\n * @since 1.0.0-rc.1\n */\nexport const cancellationReason = \"request no longer awaited\"\n\n/**\n * A `connection_closed` failure naming the server.\n *\n * @category errors\n * @since 1.0.0-rc.1\n */\nexport const closed = (server: string, reason: string): McpError =>\n  new McpError({ code: \"connection_closed\", message: `MCP server \"${server}\" ${reason}`, server })\n\n/**\n * A `timeout` failure naming the server, method and deadline.\n *\n * @category errors\n * @since 1.0.0-rc.1\n */\nexport const timeout = (server: string, method: string, timeoutMs: number): McpError =>\n  new McpError({\n    code: \"timeout\",\n    message: `MCP server \"${server}\" did not answer ${method} within ${timeoutMs}ms`,\n    server\n  })\n\n/**\n * The model-facing failure for a correlated JSON-RPC error reply. Remote text\n * is withheld; the caller reports it to Diagnostics.\n *\n * @category errors\n * @since 1.0.0-rc.1\n */\nexport const replyError = (\n  server: string,\n  method: string,\n  reply: Extract<Rpc.Reply, { readonly _tag: \"Error\" }>\n): McpError => {\n  // Servers do not standardize unknown-tool prose, so this heuristic stays\n  // limited to the two MCP error codes and an explicit tool plus absence phrase.\n  const remoteUnknownTool = (reply.code === -32_601 || reply.code === -32_602) &&\n    /\\btool\\b/i.test(reply.message) &&\n    /\\b(?:unknown|unrecognized|no such|not found)\\b/i.test(reply.message)\n  return new McpError({\n    code: method === \"tools/call\"\n      ? remoteUnknownTool ? \"tool_not_found\" : \"tool_failed\"\n      : \"protocol_error\",\n    message: `MCP server \"${server}\" failed ${method} (${reply.code}); remote details withheld`,\n    server\n  })\n}\n\n/**\n * Splits a byte stream into lines in linear time, retaining one bounded\n * partial line. Lines end at LF, with a CR before the LF dropped; with\n * `crTerminates`, as server-sent events require, a lone CR also ends a line.\n * Blank lines are kept: server-sent events use them as delimiters.\n *\n * @category constructors\n * @since 1.0.0-rc.1\n */\nexport const lines = <E>(\n  server: string,\n  maxLineBytes: number,\n  stream: Stream.Stream<Uint8Array, E>,\n  options: { readonly crTerminates?: boolean } = {}\n): Stream.Stream<string, E | McpError> => {\n  type PartialLine = { pieces: Array<Uint8Array>; bytes: number; skipLf: boolean }\n  const crTerminates = options.crTerminates === true\n  const decoder = new TextDecoder()\n  const decode = (partial: PartialLine): string => {\n    const joined = new Uint8Array(partial.bytes)\n    let offset = 0\n    for (const piece of partial.pieces) {\n      joined.set(piece, offset)\n      offset += piece.byteLength\n    }\n    const end = joined[partial.bytes - 1] === 0x0d ? partial.bytes - 1 : partial.bytes\n    return decoder.decode(joined.subarray(0, end))\n  }\n  const terminator = (chunk: Uint8Array, from: number): number => {\n    if (!crTerminates) return chunk.indexOf(0x0a, from)\n    for (let index = from; index < chunk.byteLength; index += 1) {\n      if (chunk[index] === 0x0a || chunk[index] === 0x0d) return index\n    }\n    return -1\n  }\n  const tooLong = () => Effect.fail(Limits.protocolError(server, `MCP frame exceeded ${maxLineBytes} bytes`))\n  return stream.pipe(\n    Stream.mapAccumEffect(\n      (): PartialLine => ({ pieces: [], bytes: 0, skipLf: false }),\n      (partial, chunk) => {\n        const complete: Array<string> = []\n        const append = (piece: Uint8Array): boolean => {\n          if (piece.byteLength === 0) return true\n          const bytes = partial.bytes + piece.byteLength\n          // A final CR may be the first half of CRLF. Allow that one byte\n          // beyond the cap, but count it if more frame content follows.\n          const contentBytes = bytes - (piece[piece.byteLength - 1] === 0x0d ? 1 : 0)\n          if (contentBytes > maxLineBytes) return false\n          partial.pieces.push(piece)\n          partial.bytes = bytes\n          return true\n        }\n        // The LF of a CRLF split across chunks ends nothing new.\n        let start = partial.skipLf && chunk[0] === 0x0a ? 1 : 0\n        partial.skipLf = false\n        for (let end = terminator(chunk, start); end !== -1; end = terminator(chunk, start)) {\n          if (!append(chunk.subarray(start, end))) return tooLong()\n          complete.push(decode(partial))\n          partial = { pieces: [], bytes: 0, skipLf: false }\n          start = end + 1\n          if (chunk[end] === 0x0d) {\n            if (start === chunk.byteLength) partial.skipLf = true\n            else if (chunk[start] === 0x0a) start += 1\n          }\n        }\n        if (!append(chunk.subarray(start))) return tooLong()\n        return Effect.succeed([partial, complete] as const)\n      },\n      { onHalt: (partial) => partial.bytes === 0 ? [] : [decode(partial)] }\n    )\n  )\n}\n"]}

package/docs/README.md

@@ -0,0 +1,139 @@
+---
+title: "@smthrs/mcp"
+description: "A Model Context Protocol client for Node, and the adapter that projects a remote server's tools into a Smithers run as ordinary flows named mcp/<server>/<tool>."
+---
+
+`@smthrs/mcp` connects to a Model Context Protocol (MCP) server over stdio or
+Streamable HTTP and
+projects the tools that server offers as flows a Smithers agent can call. It is
+two halves: `McpClient`, a small JSON-RPC client covering the `initialize`
+handshake, `tools/list`, and `tools/call`, and `McpFlows`, which turns a
+connected session's catalog into one flow per tool.
+
+## What it solves
+
+MCP is how a service publishes tools to an agent: a GitHub server, a database
+server, an internal service somebody on your team wrote. Calling one of those
+from an agent run could have been a second kind of capability, with its own
+dispatch, its own permission rules, and its own error type. It is not. This
+package makes a remote tool an ordinary flow:
+
+- Each tool becomes a flow named `mcp/<server>/<tool>`, so two servers may offer
+  a tool of the same name without colliding.
+- Each flow carries the server's own JSON Schema as its parameter document, so a
+  model reading the catalog sees the real argument shape rather than a
+  placeholder.
+- A cell calls it with the two lines it already uses for a filesystem flow: find
+  the name in `ctx.flows`, invoke it with `ctx.call`.
+
+The client half is deliberately small. Resources, prompts, sampling, and roots
+are not implemented, because a projection needs a tool catalog and a way to call
+one entry of it, and nothing else.
+
+## Install
+
+`@smthrs/mcp` is not published to npm yet. Its source is on
+[GitHub](https://github.com/smithersai/smithers).
+
+It needs Node.js 26.4.0 or later. Opening a connection requires two services
+from the caller's environment: Effect's `ChildProcessSpawner`, because an MCP
+server is a subprocess, and a `Scope`, because closing the scope tears that
+subprocess down. `@effect/platform-node` supplies the spawner on Node. For the
+version requirements and the import forms, see
+[Installation](./installation.md).
+
+## Connect a server and read its flows
+
+`McpFlows.connected` spawns the server, completes the handshake, fetches the
+tool catalog, and returns the projection in one step:
+
+```ts
+import { NodeServices } from "@effect/platform-node"
+import * as McpFlows from "@smthrs/mcp/McpFlows"
+import { Effect } from "effect"
+
+const program = Effect.scoped(Effect.gen(function*() {
+  const source = yield* McpFlows.connected({
+    server: "github",
+    // A reviewed server installed at an exact version with --ignore-scripts.
+    command: "/path/to/mcp-servers/node_modules/.bin/mcp-server-github",
+    args: [],
+    env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
+    include: ["create_issue", "get_issue", "list_issues"]
+  })
+  const bindings = yield* source.bindings()
+  return bindings.map((binding) => binding.descriptor.name)
+}))
+
+console.log(await Effect.runPromise(Effect.provide(program, NodeServices.layer)))
+```
+
+```text
+[ 'mcp/github/create_issue', 'mcp/github/get_issue', 'mcp/github/list_issues' ]
+```
+
+Three details in that program decide how the rest behaves:
+
+- `Effect.scoped` owns the subprocess. The session lasts as long as the scope,
+  and every request outstanding when it closes fails with `connection_closed`
+  rather than hanging.
+- `include` is an exact-name allowlist, checked against the catalog the server
+  actually sent, so a typo fails the connection instead of quietly handing the
+  model a smaller toolset. Omit it to project every tool.
+- `env` is overlaid on a bootstrap allowlist (`PATH`, `HOME`, `USER`, `LANG`,
+  `LC_*`, `TERM`, `TMPDIR`, `SHELL`), not on the full host environment, so a
+  server receives only the credentials you declare. Install and pin the server
+  before giving it one, as
+  [Connect a server](./guides/connect-a-server.md) shows.
+
+One step separates that source from a cell that can call it. Every projected
+flow declares the widest authority the capability vocabulary can express,
+because an MCP tool is opaque code this package does not control, and a host
+narrows that declaration to the authority it actually grants the server. The
+recipe is in
+[Grant authority to MCP tools](./guides/grant-authority-to-mcp-tools.md).
+
+## How this relates to the smithers CLI
+
+`@smthrs/mcp` is one of the packages behind [`@smthrs/cli`](/api/cli), the
+`smthrs` command line that plans, runs, and inspects Smithers flows. The CLI
+composes this package for you: `smthrs --mcp-config <path>` reads a JSON array
+of server entries, connects every one of them when the executor starts, and adds
+their tools to the run's flow catalog. Each entry in that file is structurally an
+`McpClient.ConnectOptions` with optional `include`, `exclude`, and `namePrefix`
+projection fields. The flag supports filtering and renaming tools per server. See
+[Configure servers for the CLI](./guides/configure-servers-for-the-cli.md).
+
+Import the package directly when you embed Smithers in a program of your own, or
+when you need to customize the projected capability declaration. The
+projected `FlowBinding.Source` is the same type the standard flows return, so it
+composes with them in one array; that contract belongs to
+[`@smthrs/harness`](/api/harness).
+
+The CLI also hosts the mirror image of this package, under a name close enough
+to confuse.
+`smthrs --mcp-config` is a Smithers run calling somebody else's tools;
+[`smthrs mcp`](/cli/mcp) runs Smithers itself as an MCP server, so an agent such
+as Claude Code can drive a control plane. For that direction, see
+[Wire the MCP server into an agent](/pkg/cli/guides/wire-the-mcp-server).
+
+## Where to go next
+
+- [Installation](./installation.md): requirements, the services a connection
+  needs, and the import forms.
+- [Quickstart](./quickstart.md): a real server in its own process, two tool
+  calls, and the flows they project.
+- Concepts: [a remote tool as a flow](./concepts/tools-as-flows.md) and
+  [the life of a session](./concepts/the-session.md).
+- Guides: [connect a server](./guides/connect-a-server.md),
+  [select the tools a run sees](./guides/select-the-tools-a-run-sees.md),
+  [grant authority to MCP tools](./guides/grant-authority-to-mcp-tools.md),
+  [handle a failed tool call](./guides/handle-a-failed-tool-call.md),
+  [validate structured output](./guides/validate-structured-output.md),
+  [bound an untrusted server](./guides/bound-an-untrusted-server.md),
+  [configure servers for the CLI](./guides/configure-servers-for-the-cli.md),
+  and [test against a server](./guides/testing.md).
+- [API reference](./api.md): every export of `McpClient`, `McpError`, and
+  `McpFlows`.
+- [Troubleshooting](./troubleshooting.md): each failure this package reports,
+  found by the message you saw.

package/docs/api.md

@@ -0,0 +1,469 @@
+---
+title: "API reference"
+description: "Every public export of @smthrs/mcp: sessions, limits, safe errors, private host diagnostics, and tool flow projections."
+---
+
+`@smthrs/mcp` exports four modules from its root entry point, and each is also
+importable from `@smthrs/mcp/<Module>`:
+
+```ts
+import { Diagnostics, McpClient, McpError, McpFlows } from "@smthrs/mcp"
+// or
+import * as McpClient from "@smthrs/mcp/McpClient"
+```
+
+`@smthrs/mcp/internal/*` and `@smthrs/mcp/*/index` are not public, so the
+JSON-RPC codec and the stdio and HTTP transports are not importable.
+`@smthrs/mcp/package.json` is exported.
+
+`McpError` is a namespace under both import forms. The error class is
+`McpError.McpError`.
+
+For the flow-binding contract this package implements, see the
+[`@smthrs/harness` reference](/api/harness). For the action vocabulary
+`McpFlows.capabilities` is derived from, see the
+[`@smthrs/capability` reference](/api/capability).
+
+## Example
+
+```ts
+import * as McpFlows from "@smthrs/mcp/McpFlows"
+import { Effect } from "effect"
+
+const program = Effect.scoped(Effect.gen(function*() {
+  const source = yield* McpFlows.connected({
+    server: "github",
+    // Installed with --ignore-scripts at an exact version; see the Connect a server guide.
+    command: "/path/to/mcp-servers/node_modules/.bin/mcp-server-github",
+    args: []
+  })
+  return yield* source.bindings()
+}))
+```
+
+## McpClient
+
+A minimal MCP client covering the `initialize` handshake, `tools/list`, and
+`tools/call` over stdio or Streamable HTTP. It is deliberately not a general MCP SDK: resources,
+prompts, sampling, and roots are not wired up.
+
+### McpClient.connect
+
+```ts
+const connect: <O extends ConnectOptions>(
+  options: O
+) => Effect.Effect<McpClient, McpError, Requirements<O> | Scope.Scope>
+```
+
+Spawns the server (`command`) or opens a Streamable HTTP session (`url`),
+completes the handshake, and fetches its tool catalog once, up front, following
+`nextCursor` across pages.
+
+Requires a `Scope`, plus `ChildProcessSpawner` for `command` or `HttpClient`
+for `url` (`Requirements<O>`). The connection's lifetime is the scope's
+lifetime: closing the scope tears the process down or ends the HTTP session,
+and every stdio request pending at that moment fails with `connection_closed`.
+
+Over HTTP, a destination the `HttpClient`'s egress policy denies and an
+unreachable server fail with `connection_closed`; a non-2xx answer fails with
+`protocol_error`; a `404` for an established session fails with
+`connection_closed` and is not retried.
+
+Fails with `spawn_failed` when the process will not start, `protocol_error` when
+an option is invalid or negotiation fails, and `invalid_response` when the
+catalog breaks one of the rules in
+[Bound an untrusted server](./guides/bound-an-untrusted-server.md).
+
+### McpClient.McpClient
+
+A live session.
+
+```ts
+interface McpClient {
+  readonly server: string
+  readonly tools: ReadonlyArray<ToolDescription>
+  readonly callTool: (
+    name: string,
+    args: Record<string, unknown>
+  ) => Effect.Effect<ToolResult, McpError>
+}
+```
+
+| Member     | Meaning                                                                                                                                                                   |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `server`   | The name this session was connected under. It is the default flow-name prefix and appears in every error message.                                                         |
+| `tools`    | The catalog as fetched at connect time, in the order the server listed it. A snapshot: this client never re-polls it.                                                     |
+| `callTool` | Calls one catalogued tool. An unknown name fails with `tool_not_found` before a JSON-RPC frame is written. Declared structured output is validated before it is returned. |
+
+### McpClient.ToolDescription
+
+One remote tool as the server describes it.
+
+| Field          | Type                                   | Meaning                                                                                                |
+| -------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `name`         | `string`                               | The tool's name. Never empty, `.`, or `..`; never containing `/` or an invisible or control character. |
+| `description`  | `string \| undefined`                  | The server's description, when it sent a string.                                                       |
+| `inputSchema`  | `Record<string, unknown>`              | The tool's parameter shape, a JSON Schema document with `type: "object"`.                              |
+| `outputSchema` | `Record<string, unknown> \| undefined` | The tool's structured result shape, when the server disclosed one.                                     |
+
+### McpClient.ToolResult
+
+The result of one `tools/call`.
+
+| Field               | Type                                     | Meaning                                                                                           |
+| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `content`           | `ReadonlyArray<Record<string, unknown>>` | The tool's content blocks, passed through by shape. `[]` for a structured-only result.            |
+| `isError`           | `boolean`                                | Whether the tool reported a problem. A successful call may carry `true`; this is not a failure.   |
+| `structuredContent` | `Record<string, unknown> \| undefined`   | The tool's structured result, validated against its declared `outputSchema` when it declared one. |
+
+### McpClient.ConnectOptions
+
+`StdioConnectOptions | HttpConnectOptions`. The stdio form:
+
+| Field                   | Type                                               | Meaning                                                                                                   |
+| ----------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `server`                | `string`                                           | The name this server is known by, for flow naming and error messages. Required.                           |
+| `command`               | `string`                                           | The executable to spawn. Required.                                                                        |
+| `args`                  | `ReadonlyArray<string>`                            | Its arguments. Required.                                                                                  |
+| `cwd`                   | `string \| undefined`                              | The child's working directory.                                                                            |
+| `env`                   | `Record<string, string \| undefined> \| undefined` | Values overlaid on the bootstrap child environment.                                                       |
+| `handshakeTimeoutMs`    | `number \| undefined`                              | Deadline for each `initialize` and `tools/list` request. Default 10000.                                   |
+| `requestTimeoutMs`      | `number \| undefined`                              | Deadline for each later tool request. Default 120000.                                                     |
+| `queueCapacity`         | `number \| undefined`                              | Maximum outbound frames waiting to be written. Default 64.                                                |
+| `maxFrameBytes`         | `number \| undefined`                              | Maximum UTF-8 bytes in one inbound JSON-RPC frame. Default 1048576.                                       |
+| `maxOutboundFrameBytes` | `number \| undefined`                              | Maximum UTF-8 bytes in one outbound JSON-RPC frame. Default 1048576.                                      |
+| `maxStderrBytes`        | `number \| undefined`                              | Maximum diagnostic stderr bytes retained in memory and rendered after credential redaction. Default 2048. |
+| `maxTools`              | `number \| undefined`                              | Maximum tools accepted across every catalog page. Default 256.                                            |
+| `maxToolNameBytes`      | `number \| undefined`                              | Maximum UTF-8 bytes in a tool name. Default 128.                                                          |
+| `maxToolDocumentBytes`  | `number \| undefined`                              | Maximum UTF-8 bytes of one tool's description plus its JSON-encoded `inputSchema`. Default 65536.         |
+| `maxCatalogPages`       | `number \| undefined`                              | Maximum `tools/list` pages walked. Default 32.                                                            |
+
+`HttpConnectOptions` has `server`, the catalog limits, `requestTimeoutMs`,
+`maxFrameBytes`, and `maxOutboundFrameBytes` from the table above, plus:
+
+| Field          | Type                        | Meaning                                                                                        |
+| -------------- | --------------------------- | ---------------------------------------------------------------------------------------------- |
+| `url`          | `string`                    | The server's MCP endpoint, an absolute `http:` or `https:` URL without credentials. Required.  |
+| `authProvider` | `AuthProvider \| undefined` | `{ token: Effect<Redacted<string>, McpError> }`, read once per HTTP message as a bearer token. |
+
+Every numeric field must be a positive safe integer. Anything else fails with
+`protocol_error` naming the option, before the process is spawned or a request
+is sent.
+
+The bootstrap child environment contains only `PATH`, `HOME`, `USER`, `LANG`,
+`LC_*`, `TERM`, `TMPDIR`, and `SHELL`. Other ambient names are withheld;
+entries in `env` are explicit declarations and are applied last.
+
+### McpClient.ConnectOptionsSchema
+
+```ts
+const ConnectOptionsSchema = Schema.Struct({
+  server: Schema.NonEmptyString,
+  command: Schema.NonEmptyString,
+  args: Schema.Array(Schema.String),
+  cwd: Schema.optional(Schema.NonEmptyString),
+  env: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  // every limit, each a positive integer
+  handshakeTimeoutMs: Schema.optional(PositiveInteger)
+  // ...
+})
+```
+
+The authoritative decoder for a persisted stdio MCP server entry. It requires
+non-empty `server` and `command` strings, string `args`, an optional
+string-valued `env` record, and positive integers for every limit. Use it
+wherever connection options arrive from a file or a database.
+
+### McpClient.HttpConnectOptionsSchema
+
+```ts
+const HttpConnectOptionsSchema = Schema.Struct({
+  server: Schema.NonEmptyString,
+  url: Schema.String, // absolute http: or https:, no userinfo
+  bearerTokenEnv: Schema.optionalKey(Schema.String), // an environment variable name
+  // every limit HttpConnectOptions accepts, each a positive integer
+  requestTimeoutMs: Schema.optional(PositiveInteger)
+  // ...
+})
+```
+
+The authoritative decoder for a persisted Streamable HTTP server entry. It
+requires a non-empty `server`, an absolute `http:` or `https:` `url` without
+a user or password, and positive integers for every limit. The entry never
+holds a credential: `bearerTokenEnv` names the environment variable the host
+reads the bearer token from and supplies as `authProvider`.
+
+### McpClient.clientInfo
+
+```ts
+const clientInfo: { readonly name: string; readonly version: string }
+```
+
+The frozen identity disclosed to every server during initialization:
+`name` is `"smithers"` and `version` is this package's version. Not
+configurable.
+
+### McpClient.supportedProtocolVersions
+
+```ts
+const supportedProtocolVersions: ReadonlyArray<string>
+```
+
+The MCP revisions whose `tools/list` and `tools/call` shapes this client
+decodes, frozen, always proposing the first entry:
+`["2025-06-18", "2025-03-26", "2024-11-05"]`.
+
+### Limit defaults
+
+Each option's default is exported as a constant, so a caller can read or
+adjust one without restating a literal.
+
+| Constant                       | Value   | Option                  |
+| ------------------------------ | ------- | ----------------------- |
+| `defaultHandshakeTimeoutMs`    | 10000   | `handshakeTimeoutMs`    |
+| `defaultRequestTimeoutMs`      | 120000  | `requestTimeoutMs`      |
+| `defaultQueueCapacity`         | 64      | `queueCapacity`         |
+| `defaultMaxFrameBytes`         | 1048576 | `maxFrameBytes`         |
+| `defaultMaxOutboundFrameBytes` | 1048576 | `maxOutboundFrameBytes` |
+| `defaultMaxStderrBytes`        | 2048    | `maxStderrBytes`        |
+| `defaultMaxTools`              | 256     | `maxTools`              |
+| `defaultMaxToolNameBytes`      | 128     | `maxToolNameBytes`      |
+| `defaultMaxToolDocumentBytes`  | 65536   | `maxToolDocumentBytes`  |
+| `defaultMaxCatalogPages`       | 32      | `maxCatalogPages`       |
+
+`McpClient.maxJsonDepth` is a fixed safety limit of **128 nested containers**,
+including the JSON-RPC envelope. Arrays and objects each count as one container;
+scalar values do not. Both incoming messages and outgoing arguments obey it.
+An inbound violation closes the connection with `protocol_error`; invalid
+arguments fail before dispatch without closing an otherwise healthy session.
+Incoming JSON numbers that overflow to infinity are also rejected.
+
+Before copying arguments, the client accounts for their expanded JSON size
+against `maxOutboundFrameBytes`. Reusing the same object under several properties
+does not bypass that accounting. The transport additionally checks the exact
+UTF-8 size of the full encoded frame. Neither bound limits a caller's own
+already-allocated input object or time spent in caller-provided Proxy traps.
+
+## McpError
+
+The single typed error returned by the client and the flow adapter. Ordinary
+tool outcomes stay in the success channel; this error is reserved for failures
+of the MCP session itself.
+
+### McpError.McpError
+
+```ts
+class McpError extends Schema.TaggedError<McpError>()("flows/mcp/McpError", {
+  code: Code,
+  message: Schema.String,
+  server: Schema.optional(Schema.String)
+}) {}
+```
+
+| Field     | Type                  | Meaning                                                                                                                                                                             |
+| --------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `code`    | `Code`                | The stable, model-facing failure code.                                                                                                                                              |
+| `message` | `string`              | A fixed failure summary naming the configured server, with a remote numeric error code when available. No child stderr, remote error prose/data, or user-controlled property paths. |
+| `server`  | `string \| undefined` | The server the failure belongs to.                                                                                                                                                  |
+
+The tag is `"flows/mcp/McpError"`, so `Effect.catchTag("flows/mcp/McpError", ...)`
+matches it.
+
+### McpError.Code
+
+```ts
+const Code = Schema.Literals([
+  "spawn_failed",
+  "connection_closed",
+  "timeout",
+  "protocol_error",
+  "tool_not_found",
+  "tool_failed",
+  "invalid_response"
+])
+
+type Code = typeof Code.Type
+```
+
+| Code                | Meaning                                                                                          |
+| ------------------- | ------------------------------------------------------------------------------------------------ |
+| `spawn_failed`      | The server process would not start.                                                              |
+| `connection_closed` | The process exited or a pipe closed while a request was outstanding.                             |
+| `timeout`           | The server did not answer within the deadline for that method.                                   |
+| `protocol_error`    | Negotiation failed, an envelope was malformed, or an option was invalid.                         |
+| `tool_not_found`    | The catalog lacks a tool, `include` names a missing tool, or the server rejects an unknown tool. |
+| `tool_failed`       | The server rejected a `tools/call` with a JSON-RPC error.                                        |
+| `invalid_response`  | A well-formed reply carried a `tools/list` or `tools/call` payload this client rejects.          |
+
+For which JSON-RPC errors become which code, see
+[Handle a failed tool call](./guides/handle-a-failed-tool-call.md).
+
+## Diagnostics
+
+Optional host-only diagnostics, separate from the model-facing `McpError`.
+Install `Diagnostics.layer(report)` around the effect that opens the connection.
+The connection captures that observer once. Without it, private details are
+discarded rather than logged.
+
+```ts
+import { Diagnostics } from "@smthrs/mcp"
+
+// A host-owned, bounded sink; this is not an agent or journal callback.
+const privateDiagnostics = Diagnostics.layer((event) => {
+  retainForLocalInspection(event)
+})
+```
+
+`Diagnostics.Diagnostics` is the optional Context service. Its `report` callback
+takes one `Diagnostics.Event`:
+
+| Field       | Meaning                                                                                     |
+| ----------- | ------------------------------------------------------------------------------------------- |
+| `server`    | The host-configured server alias. Do not put credentials in aliases.                        |
+| `source`    | `spawn`, `stderr`, `transport`, `remote-error`, `invalid-response`, or `invalid-arguments`. |
+| `detail`    | `Redacted.Redacted<string>`, at most 16 KiB of UTF-8. May contain secrets.                  |
+| `truncated` | Whether this event's private detail exceeded that 16 KiB bound.                             |
+
+Ordinary JSON serialization and inspection hide `detail`. A trusted local host
+can explicitly unwrap it with `Redacted.value`; it must control access and
+retention and must never forward that value to agents, journals, traces, or
+routine logs. The callback is synchronous: it must not block or retain an
+unbounded event history. Callback and serialization exceptions are isolated
+from the MCP connection. Diagnostic delivery is best effort, not an audit log.
+On process or stdio closure, pending requests wait up to 250 ms for the stderr
+reader to finish before receiving the terminal error. Request deadlines and
+scope interruption can end that wait sooner. A pipe held open beyond that
+budget contributes only the tail already read; it cannot hold shutdown open.
+The separate `maxStderrBytes` limit applies before the observer sees a stderr
+tail, so `truncated: false` does not imply the entire child output is present.
+
+This protects session errors, not successful tool output. `content`,
+`structuredContent`, and tool-reported `isError: true` results remain unchanged;
+the host must choose which tool outputs it may expose.
+
+## McpFlows
+
+Projects a connected session's tool catalog as an ordinary
+`FlowBinding.Source`, one flow per tool.
+
+### McpFlows.connected
+
+```ts
+const connected: (
+  options: McpClient.ConnectOptions & ProjectionOptions
+) => Effect.Effect<FlowBinding.Source, McpError, ChildProcessSpawner | Scope.Scope>
+```
+
+Connects and projects in one step. This is the checked entry point: it validates
+the projection options against the freshly fetched catalog, failing with
+`tool_not_found` when `include` names a tool the server does not offer, and with
+`protocol_error` when `namePrefix` is empty.
+
+### McpFlows.mcp
+
+```ts
+const mcp: (
+  client: McpClient.McpClient,
+  options?: ProjectionOptions
+) => FlowBinding.Source
+```
+
+Projects an already-connected session. Total: it applies exact filters to the
+catalog it is given and validates nothing.
+
+The client is a precondition rather than a parameter this constructor resolves,
+because connecting is scoped and a `Source` is not. A host composes
+`McpClient.connect` once, where it composes its other scoped services, and
+passes the live client here.
+
+### McpFlows.ProjectionOptions
+
+| Field        | Type                                 | Meaning                                                         |
+| ------------ | ------------------------------------ | --------------------------------------------------------------- |
+| `include`    | `ReadonlyArray<string> \| undefined` | Exact tool names to project. Omitted or empty means every tool. |
+| `exclude`    | `ReadonlyArray<string> \| undefined` | Exact tool names to drop, applied after `include`.              |
+| `namePrefix` | `string \| undefined`                | Replaces the default `mcp/<server>` flow-name prefix.           |
+
+### McpFlows.Args
+
+```ts
+const Args = Schema.Record(Schema.String, Schema.Unknown)
+```
+
+The decoded input accepted by every MCP tool flow. It is permissive because the
+remote server, not this adapter, owns argument validation. The registry still
+discloses the real parameter shape: each binding carries the server's own
+`inputSchema` as its input document.
+
+### McpFlows.Result
+
+```ts
+const Result = Schema.Struct({
+  content: Schema.Array(Schema.Record(Schema.String, Schema.Unknown)),
+  isError: Schema.Boolean,
+  structuredContent: Schema.optional(Schema.Record(Schema.String, Schema.Unknown))
+})
+```
+
+The decoded output returned by every MCP tool flow. `structuredContent` is
+absent, not null, when the tool sent none.
+
+### McpFlows.capabilities
+
+```ts
+const capabilities: ReadonlyArray<string>
+```
+
+The authority every MCP tool flow declares: one exact
+`namespace:operation:resource` string per host action, at resource `**`, derived
+from `Capability.Action.literals` and frozen.
+
+```ts
+;[
+  "fs:read:**",
+  "fs:write:**",
+  "net:get:**",
+  "net:post:**",
+  "net:private:**",
+  "model:call:**",
+  "memory:read:**",
+  "memory:write:**",
+  "proc:spawn:**",
+  "jj:status:**",
+  "jj:diff:**",
+  "jj:snapshot:**",
+  "jj:restore:**",
+  "jj:workspace-add:**",
+  "jj:workspace-forget:**",
+  "jj:root:**",
+  "jj:revert:**",
+  "jj:op-restore:**"
+]
+```
+
+It is enumerated rather than written as a wildcard because the cell boundary
+parses each declaration with `Capability.parse`, which requires exactly three
+colon-separated components and treats anything else as unauthorized. Narrowing
+this to what a host actually grants is the host's job; see
+[Grant authority to MCP tools](./guides/grant-authority-to-mcp-tools.md).
+
+### McpFlows.effects
+
+```ts
+const effects: Effects.Declaration // from @smthrs/core/Effects
+```
+
+The conservative effect envelope every MCP tool flow declares:
+
+```ts
+{
+  reads: ["**"],
+  writes: ["**"],
+  mode: "expected",
+  onConflict: "serialize",
+  tier: "irreversible"
+}
+```
+
+The irreversible tier is why an abandoned `tools/call` sends one
+`notifications/cancelled` rather than being left in flight.