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

package/CHANGELOG.md

@@ -0,0 +1,121 @@
+# @smthrs/mcp
+
+## [Unreleased]
+
+### Changed
+
+- Enforce a fixed 128-container JSON nesting limit, including the wire envelope,
+  before recursive consumers; reject incoming numeric overflow. Bound argument
+  expansion before copying shared-reference trees, require an object argument
+  root, and reject unsafe-integer limit options. Violations are typed failures.
+- Deep-freeze the public catalog and schemas so caller edits cannot change
+  subsequent tool dispatch or validation. Copy them before making local edits.
+- **Breaking error prose:** session errors no longer echo child stderr, spawn
+  details, remote error text/data, invalid protocol versions, duplicate tool
+  names, cursors, or argument/result property paths. Stable `McpError` codes and
+  remote numeric error codes remain available. Successful tool output is unchanged.
+
+### Added
+
+- Optional `Diagnostics.layer(report)` for trusted local host inspection.
+  Details are bounded to 16 KiB UTF-8 and wrapped in `Redacted`; JSON/log
+  inspection does not expose them. No implicit raw logging, and callback
+  failures cannot fail the connection. Hosts own access, retention, and any
+  explicit unwrapping.
+
+### Fixed
+
+- Stderr diagnostics are redacted one complete line at a time before the
+  `maxStderrBytes` cap. Capping raw bytes first could cut a credential's
+  recognizable prefix and hand its remainder to the private diagnostic observer
+  unredacted. A stderr line longer than 64 KiB is withheld whole.
+
+- Distinguish inbound server requests from notifications. Reply to `ping` with
+  an empty result and unsupported methods with `-32601`, preserving exact ids
+  independently of active client requests. Server responses obey the outbound
+  frame, queue, and admission-deadline bounds.
+- Keep a timed-out request's cancellation notification best-effort, dropping
+  it when the bounded outbound queue is full instead of blocking past the
+  deadline it reports.
+- Snapshot tool arguments through guarded property descriptors. Accessors are
+  never invoked, proxy reflection failures remain typed `McpError` failures,
+  and non-enumerable properties are omitted like `JSON.stringify`.
+- Point the package README at mcp.smithers.sh. The Markdown files under
+  `docs/` stay out of the published tarball.
+- Require every tool `inputSchema` to declare `type: "object"`, and reject C1
+  control characters in tool names alongside C0 controls and U+007F.
+- Drop stdout that does not claim JSON-RPC as server log noise, while closing
+  the connection when a tagged envelope has the wrong version or is missing a
+  reply id.
+- Map a server's explicit `-32601` or `-32602` unknown-tool rejection to
+  `tool_not_found` while retaining `tool_failed` for ordinary tool failures.
+- Validate `structuredContent` against the tool's declared `outputSchema` for
+  the supported `type`, `required`, `properties`, `items`, and `enum` subset,
+  and accept structured-only results with an empty `content` array.
+- Freeze the exported client identity and supported protocol revision list so
+  consumers cannot mutate later initialization frames.
+
+## [1.0.0-rc.0] - 2026-09-01
+
+### Added
+
+- Added `@smthrs/mcp`: a stdio MCP client (`McpClient`) and a
+  `FlowBinding.Source` projector (`McpFlows`) that turns a connected server's
+  tool catalog into one flow per tool, so an MCP tool call is an ordinary flow
+  call with no second registration path alongside `@smthrs/std`'s filesystem and
+  shell flows.
+- Added negotiation of the `initialize` result: the server's `protocolVersion`
+  must be one this client decodes and its `capabilities.tools` must be present
+  before the handshake completes.
+- Added `tools/list` pagination, following `nextCursor` across pages under a
+  page cap, with duplicate names rejected across the whole catalog.
+- Added bounds on what an untrusted server can size: `maxTools`,
+  `maxToolNameBytes`, `maxCatalogPages`, `maxOutboundFrameBytes`, and
+  `maxStderrBytes`, each with an exported default constant.
+- Added `include`, `exclude`, and `namePrefix` projection options so a host
+  chooses which of a server's tools reach the model and under what names.
+- Added `notifications/cancelled` for a timed-out or interrupted `tools/call`,
+  so remote work declared `irreversible` is not abandoned mid-flight.
+- Added pass-through of MCP 2025-06-18 structured tool output: a tool's
+  `outputSchema` on `ToolDescription` and `structuredContent` on `ToolResult`
+  and on the flow's own `Result` schema.
+- Added package-owned documentation under `docs/`, generated into
+  `docs/reference.md` by `scripts/docs.mjs`.
+
+### Changed
+
+- Declare authority as one exact `namespace:operation:resource` string per
+  `Capability.Action`, derived from `Capability.Action.literals` and frozen. The
+  bare `"*"` this module used to declare parsed as nothing, and an unparseable
+  declaration is treated as unauthorized, so every MCP tool was refused with
+  `capability_refused` before it ran even under an unrestricted envelope.
+- Close the stdio transport without racing a separate terminal signal.
+- Identify to remote servers as `smithers` at this package's version rather than
+  as `flows` at `0.1.0`.
+- Drain the child's stderr into a bounded tail and append it to `spawn_failed`,
+  `timeout`, and `connection_closed` messages, so a startup failure explains
+  itself instead of surfacing as an unexplained handshake deadline.
+
+### Fixed
+
+- Merge `env` into the inherited child environment instead of replacing it. A
+  server spawned with a credential received no `PATH`, so the canonical
+  `{ command: "npx", env: { TOKEN } }` entry failed to spawn at all.
+- Validate every JSON-RPC envelope before correlating it: a reply must carry a
+  valid id and exactly one of `result` or `error`, and an error must carry an
+  integer code and a string message. An `error: null` reply used to kill the
+  reader fiber and hang every pending request until its deadline.
+- Map a JSON-RPC error by the method that failed, keeping the numeric code in
+  the message, instead of reporting every failure as `tool_failed`.
+- Decode `tools/list` and `tools/call` payloads instead of casting them. A
+  `null` catalog entry used to throw a `TypeError` out of the declared error
+  channel, a non-object content block used to surface as a flow-authored schema
+  failure that named no server, and a missing `inputSchema` used to be
+  fabricated rather than rejected.
+- Reject duplicate tool names at the adapter. A server that repeated a name used
+  to fail the host's entire flow catalog, including flows unrelated to MCP.
+- Snapshot tool arguments to plain JSON before a request id is registered, so a
+  getter, a proxy, a cycle, or a non-finite number fails with a typed error and
+  a bounded path instead of a defect.
+- Bound the `notifications/initialized` step by `handshakeTimeoutMs` rather than
+  by the 120 second tool-call deadline.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Cory and the Smithers Flows contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# @smthrs/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Release candidate scope, host requirements and compatibility review are defined in the [library support policy](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md).
+
+This package declares `effect` as an exact
+`4.0.0-rc.115` peer dependency. Keep the application on that version so
+all Smithers packages share one Effect runtime.
+
+**Documentation:** https://mcp.smithers.sh
+
+Model Context Protocol client and flow adapter for Smithers.
+
+`@smthrs/mcp` connects to an MCP server over stdio or Streamable HTTP and projects the tools that
+server offers as flows a Smithers agent can call. `McpClient` speaks the
+protocol: the `initialize` handshake, `tools/list`, and `tools/call`.
+`McpFlows` turns the resulting catalog into one `FlowBinding.Binding` per tool,
+so a cell calls a remote tool with the same two lines it uses for a filesystem
+flow, and nothing downstream needs to know the difference.
+
+## 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, [`effect`](https://effect.website), and a
+`ChildProcessSpawner`, which `@effect/platform-node` provides on Node. Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+## Connect a server and read its flows
+
+Install a reviewed server version and its dependencies before supplying any
+credentials. This example pins the deprecated GitHub server to `2025.4.8`;
+review it for your use before running it. Use a dedicated directory, review and
+retain `package.json` and `package-lock.json`, then install from that lockfile:
+
+```bash
+mkdir -p /path/to/mcp-servers
+env -u GITHUB_TOKEN -u GITHUB_PERSONAL_ACCESS_TOKEN npm install --prefix /path/to/mcp-servers --package-lock-only --ignore-scripts --save-exact @modelcontextprotocol/server-github@2025.4.8
+# Review the pinned package and lockfile before installing.
+env -u GITHUB_TOKEN -u GITHUB_PERSONAL_ACCESS_TOKEN npm ci --prefix /path/to/mcp-servers --ignore-scripts
+```
+
+Both npm commands remove the GitHub credential variables from their environment.
+Launch the installed executable directly and supply the token only in the
+server's `env`. This server reads `GITHUB_PERSONAL_ACCESS_TOKEN`.
+
+```typescript
+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",
+    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)
+}))
+
+// [ "mcp/github/create_issue", "mcp/github/get_issue", "mcp/github/list_issues" ]
+console.log(await Effect.runPromise(Effect.provide(program, NodeServices.layer)))
+```
+
+Each tool becomes a flow named `mcp/<server>/<tool>`. The connection's lifetime
+is the scope's lifetime. The child inherits `PATH`, `HOME`, `USER`, `LANG`,
+`LC_*`, `TERM`, `TMPDIR`, and `SHELL`; `env` explicitly adds or replaces names.
+Other ambient variables, including provider credentials, are withheld.
+
+Catalog tools must declare `inputSchema.type: "object"`. Structured-only tool
+results are accepted with `content: []`, and declared `outputSchema` documents
+are enforced for the supported keyword subset.
+
+Session errors withhold raw child stderr, remote error text/data, and property
+paths. An optional host-only [Diagnostics observer](https://mcp.smithers.sh/reference/api/#diagnostics)
+provides credential-redacted `Redacted` details for explicit local inspection,
+with child stderr bounded by `maxStderrBytes` (2048 by default). Successful tool
+outputs, including `isError: true`, are returned unchanged.
+
+Every projected flow declares the widest authority the capability vocabulary
+can express, because an MCP tool is opaque code this package does not control.
+Narrowing that declaration to what you actually grant a server is the host's
+step, and the one thing standing between a projected source and a cell that can
+call it.
+
+This is the client half of Smithers and MCP: a Smithers run calling somebody
+else's tools. The other half, an agent such as Claude Code driving Smithers, is
+the Smithers MCP server behind `smthrs mcp`.
+
+## Documentation
+
+Full documentation is at [mcp.smithers.sh](https://mcp.smithers.sh):
+
+- [Quickstart](https://mcp.smithers.sh/quickstart/): a real server in its own
+  process, two tool calls, and the flows they project.
+- [A remote tool as a flow](https://mcp.smithers.sh/concepts/tools-as-flows/):
+  what the projection produces, and why nothing downstream knows the flow is
+  remote.
+- [Grant authority to MCP tools](https://mcp.smithers.sh/guides/grant-authority-to-mcp-tools/):
+  the step between a projected source and a cell that can call it.
+- [Configure servers for the CLI](https://mcp.smithers.sh/guides/configure-servers-for-the-cli/):
+  the `--mcp-config` file the `smthrs` command line reads.
+- [API reference](https://mcp.smithers.sh/reference/api/): every public export
+  of `Diagnostics`, `McpClient`, `McpError`, and `McpFlows`.
+- [Troubleshooting](https://mcp.smithers.sh/troubleshooting/): every failure
+  this package reports, with its cause and fix.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/cjs/Diagnostics.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Host-only access to untrusted MCP diagnostics, separate from model-facing
+ * errors. Merely logging or JSON-encoding an event cannot expose its detail.
+ *
+ * @since 1.0.0-rc.0
+ */
+import { Context, Layer } from "effect";
+import type { Redacted } from "effect";
+/**
+ * One bounded diagnostic from a connection. Detail can contain credentials,
+ * private tool arguments, or arbitrary server text. Only an explicitly trusted
+ * local host should unwrap it; never forward it to agents, journals, or logs.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Event {
+    readonly server: string;
+    readonly source: "spawn" | "stderr" | "transport" | "remote-error" | "invalid-response" | "invalid-arguments";
+    /** At most 16 KiB of UTF-8 text; never the original unbounded value. */
+    readonly detail: Redacted.Redacted<string>;
+    readonly truncated: boolean;
+}
+declare const Diagnostics_base: Context.ServiceClass<Diagnostics, "@smthrs/mcp/Diagnostics", {
+    readonly report: (event: Event) => void;
+}>;
+/**
+ * Optional diagnostic observer, captured when a connection is opened. The
+ * synchronous callback must not block; throws are isolated from the protocol.
+ * Absent this service, raw diagnostics are discarded, not logged implicitly.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ */
+export declare class Diagnostics extends Diagnostics_base {
+}
+/**
+ * Installs a trusted host observer. Inspecting detail requires an explicit
+ * `Redacted.value` call and responsibility for its destination and retention.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layer: (report: (event: Event) => void) => Layer.Layer<Diagnostics>;
+export {};
+//# sourceMappingURL=Diagnostics.d.ts.map

package/dist/cjs/Diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Diagnostics.d.ts","sourceRoot":"","sources":["../../src/Diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEtC;;;;;;;GAOG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,cAAc,GAAG,kBAAkB,GAAG,mBAAmB,CAAA;IAC7G,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;;qBAWkB,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI;;AATzC;;;;;;;GAOG;AACH,qBAAa,WAAY,SAAQ,gBAEF;CAAG;AAElC;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,GAAI,QAAQ,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,KAAG,KAAK,CAAC,KAAK,CAAC,WAAW,CACtC,CAAA"}

package/dist/cjs/Diagnostics.js

@@ -0,0 +1,29 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Diagnostics_exports = {};
+__export(Diagnostics_exports, {
+  Diagnostics: () => Diagnostics,
+  layer: () => layer
+});
+module.exports = __toCommonJS(Diagnostics_exports);
+var import_effect = require("effect");
+class Diagnostics extends import_effect.Context.Service()("@smthrs/mcp/Diagnostics") {
+}
+const layer = (report) => import_effect.Layer.succeed(Diagnostics)({ report });
+//# sourceMappingURL=Diagnostics.js.map

package/dist/cjs/Diagnostics.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Diagnostics.ts"],
+  "sourcesContent": ["/**\n * Host-only access to untrusted MCP diagnostics, separate from model-facing\n * errors. Merely logging or JSON-encoding an event cannot expose its detail.\n *\n * @since 1.0.0-rc.0\n */\n\nimport { Context, Layer } from \"effect\"\nimport type { Redacted } from \"effect\"\n\n/**\n * One bounded diagnostic from a connection. Detail can contain credentials,\n * private tool arguments, or arbitrary server text. Only an explicitly trusted\n * local host should unwrap it; never forward it to agents, journals, or logs.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Event {\n  readonly server: string\n  readonly source: \"spawn\" | \"stderr\" | \"transport\" | \"remote-error\" | \"invalid-response\" | \"invalid-arguments\"\n  /** At most 16 KiB of UTF-8 text; never the original unbounded value. */\n  readonly detail: Redacted.Redacted<string>\n  readonly truncated: boolean\n}\n\n/**\n * Optional diagnostic observer, captured when a connection is opened. The\n * synchronous callback must not block; throws are isolated from the protocol.\n * Absent this service, raw diagnostics are discarded, not logged implicitly.\n *\n * @category services\n * @since 1.0.0-rc.0\n */\nexport class Diagnostics extends Context.Service<Diagnostics, {\n  readonly report: (event: Event) => void\n}>()(\"@smthrs/mcp/Diagnostics\") {}\n\n/**\n * Installs a trusted host observer. Inspecting detail requires an explicit\n * `Redacted.value` call and responsibility for its destination and retention.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layer = (report: (event: Event) => void): Layer.Layer<Diagnostics> =>\n  Layer.succeed(Diagnostics)({ report })\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,oBAA+B;AA2BxB,MAAM,oBAAoB,sBAAQ,QAEtC,EAAE,yBAAyB,EAAE;AAAC;AAS1B,MAAM,QAAQ,CAAC,WACpB,oBAAM,QAAQ,WAAW,EAAE,EAAE,OAAO,CAAC;",
+  "names": []
+}

package/dist/cjs/McpClient.d.ts

@@ -0,0 +1,304 @@
+/**
+ * A minimal MCP client covering the `initialize` handshake, `tools/list`, and
+ * `tools/call`, over stdio or Streamable HTTP.
+ *
+ * This is deliberately not a general MCP SDK. Smithers has exactly one
+ * consumer of an MCP session: {@link McpFlows}, which needs a tool catalog
+ * and a way to invoke one entry from it, so the client exposes only that.
+ * Resources, prompts, sampling, and roots are not wired up; add them here
+ * when a flow adapter needs them, not speculatively.
+ *
+ * @since 1.0.0-rc.0
+ */
+import { Effect, Schema, Scope } from "effect";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner";
+import * as HttpTransport from "./internal/HttpTransport.ts";
+import * as StdioTransport from "./internal/StdioTransport.ts";
+import { McpError } from "./McpError.ts";
+/**
+ * One remote tool as the server describes it.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface ToolDescription {
+    readonly name: string;
+    readonly description: string | undefined;
+    /** The tool's parameter shape, as a JSON Schema document with `type: "object"`. */
+    readonly inputSchema: Record<string, unknown>;
+    /** The tool's structured result shape, when the server disclosed one. */
+    readonly outputSchema: Record<string, unknown> | undefined;
+}
+/**
+ * The result of one `tools/call`.
+ *
+ * MCP tool content is a small union (text, image, embedded resource, …); this
+ * client passes every block through by shape rather than modeling the union,
+ * since {@link McpFlows} only needs to hand the blocks back to the caller.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface ToolResult {
+    readonly content: ReadonlyArray<Record<string, unknown>>;
+    readonly isError: boolean;
+    readonly structuredContent: Record<string, unknown> | undefined;
+}
+/**
+ * A live MCP session, holding the tool catalog fetched at connect time and a
+ * way to call one of its entries.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface McpClient {
+    readonly server: string;
+    readonly tools: ReadonlyArray<ToolDescription>;
+    /**
+     * Calls one catalogued tool. An unknown name fails with `tool_not_found`
+     * before a JSON-RPC frame is written. Declared structured output is checked
+     * against the supported output-schema subset before it is returned.
+     */
+    readonly callTool: (name: string, args: Record<string, unknown>) => Effect.Effect<ToolResult, McpError>;
+}
+/**
+ * Session and catalog limits shared by every transport.
+ *
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export interface ClientOptions {
+    /** The name this server is known by, for flow naming and error messages. */
+    readonly server: string;
+    /** Deadline for each initialize/catalog request. See {@link defaultHandshakeTimeoutMs}. */
+    readonly handshakeTimeoutMs?: number | undefined;
+    /** Maximum tools accepted across every catalog page. See {@link defaultMaxTools}. */
+    readonly maxTools?: number | undefined;
+    /**
+     * Maximum UTF-8 bytes in a tool name. Names also cannot be `.` or `..`, or
+     * contain `/`, a control or format character (Unicode categories Cc and Cf,
+     * which include bidi and zero-width marks), U+2028, U+2029, or a lone
+     * surrogate. See {@link defaultMaxToolNameBytes}.
+     */
+    readonly maxToolNameBytes?: number | undefined;
+    /**
+     * Maximum UTF-8 bytes of one tool's model-facing text: its description plus
+     * its JSON-encoded `inputSchema`. See {@link defaultMaxToolDocumentBytes}.
+     */
+    readonly maxToolDocumentBytes?: number | undefined;
+    /** Maximum pages walked while fetching the catalog. See {@link defaultMaxCatalogPages}. */
+    readonly maxCatalogPages?: number | undefined;
+}
+/**
+ * A server spawned as a child process and spoken to over its stdio.
+ *
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export interface StdioConnectOptions extends StdioTransport.ConnectOptions, ClientOptions {
+    readonly url?: never;
+}
+/**
+ * Supplies the bearer credential for a Streamable HTTP server. `token` runs
+ * once per HTTP message, so a provider can rotate the credential; its failure
+ * fails that message unchanged.
+ *
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export type AuthProvider = HttpTransport.AuthProvider;
+/**
+ * A remote server reached over MCP Streamable HTTP through the `HttpClient`
+ * in context.
+ *
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export interface HttpConnectOptions extends HttpTransport.ConnectOptions, ClientOptions {
+    readonly command?: never;
+}
+/**
+ * Options accepted by {@link connect}: a stdio command or an HTTP `url`.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type ConnectOptions = StdioConnectOptions | HttpConnectOptions;
+/**
+ * The services {@link connect} needs for the given options: a process spawner
+ * for stdio, an `HttpClient` for a `url`.
+ *
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export type Requirements<O extends ConnectOptions> = O extends {
+    readonly url: string;
+} ? HttpClient.HttpClient : ChildProcessSpawner;
+/**
+ * Authoritative decoder for a persisted stdio MCP server entry.
+ *
+ * The schema requires non-empty server and command names, string arguments,
+ * a plain string-valued environment record, and positive-integer limits.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const ConnectOptionsSchema: Schema.Struct<{
+    readonly server: Schema.NonEmptyString;
+    readonly command: Schema.NonEmptyString;
+    readonly args: Schema.$Array<Schema.String>;
+    readonly cwd: Schema.optional<Schema.NonEmptyString>;
+    readonly env: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly handshakeTimeoutMs: Schema.optional<Schema.Int>;
+    readonly requestTimeoutMs: Schema.optional<Schema.Int>;
+    readonly queueCapacity: Schema.optional<Schema.Int>;
+    readonly maxFrameBytes: Schema.optional<Schema.Int>;
+    readonly maxOutboundFrameBytes: Schema.optional<Schema.Int>;
+    readonly maxStderrBytes: Schema.optional<Schema.Int>;
+    readonly maxTools: Schema.optional<Schema.Int>;
+    readonly maxToolNameBytes: Schema.optional<Schema.Int>;
+    readonly maxToolDocumentBytes: Schema.optional<Schema.Int>;
+    readonly maxCatalogPages: Schema.optional<Schema.Int>;
+}>;
+/**
+ * Authoritative decoder for a persisted Streamable HTTP MCP server entry.
+ *
+ * The schema requires a non-empty server name, an absolute `http:` or
+ * `https:` `url` without userinfo, and positive-integer limits. A bearer
+ * credential is never stored in the entry: `bearerTokenEnv` names the
+ * environment variable the host reads it from and turns into an
+ * {@link AuthProvider}.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.1
+ */
+export declare const HttpConnectOptionsSchema: Schema.Struct<{
+    readonly server: Schema.NonEmptyString;
+    readonly url: Schema.String;
+    readonly bearerTokenEnv: Schema.optionalKey<Schema.String>;
+    readonly handshakeTimeoutMs: Schema.optional<Schema.Int>;
+    readonly requestTimeoutMs: Schema.optional<Schema.Int>;
+    readonly maxFrameBytes: Schema.optional<Schema.Int>;
+    readonly maxOutboundFrameBytes: Schema.optional<Schema.Int>;
+    readonly maxTools: Schema.optional<Schema.Int>;
+    readonly maxToolNameBytes: Schema.optional<Schema.Int>;
+    readonly maxToolDocumentBytes: Schema.optional<Schema.Int>;
+    readonly maxCatalogPages: Schema.optional<Schema.Int>;
+}>;
+/**
+ * Frozen identity disclosed to every MCP server during initialization.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const clientInfo: {
+    readonly name: string;
+    readonly version: string;
+};
+/**
+ * MCP revisions whose `tools/list` and `tools/call` shapes this client
+ * decodes. The frozen list always proposes `2025-06-18` first.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const supportedProtocolVersions: ReadonlyArray<string>;
+/**
+ * Default deadline for each MCP handshake request.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultHandshakeTimeoutMs = 10000;
+/**
+ * Default deadline for each tool request.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultRequestTimeoutMs = 120000;
+/**
+ * Default number of outbound frames allowed to wait in memory.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultQueueCapacity = 64;
+/**
+ * Default maximum inbound JSON-RPC frame size.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultMaxFrameBytes: number;
+/**
+ * Default maximum outbound JSON-RPC frame size.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultMaxOutboundFrameBytes: number;
+/**
+ * Default maximum child-stderr tail retained for connection diagnostics.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultMaxStderrBytes = 2048;
+/**
+ * Default maximum number of tools in a remote catalog.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultMaxTools = 256;
+/**
+ * Default maximum UTF-8 byte length of one remote tool name.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultMaxToolNameBytes = 128;
+/**
+ * Default maximum UTF-8 bytes of one tool's description plus its JSON-encoded
+ * `inputSchema`, the server-authored text a model reads for that tool.
+ *
+ * @category constants
+ * @since 1.0.0-rc.1
+ */
+export declare const defaultMaxToolDocumentBytes = 65536;
+/**
+ * Default maximum number of remote catalog pages.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultMaxCatalogPages = 32;
+/**
+ * Maximum nested JSON containers, including the JSON-RPC envelope. Fixed so
+ * accepted server schemas and values remain safe for recursive consumers.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const maxJsonDepth = 128;
+/**
+ * Connects to an MCP server over stdio (`command`) or Streamable HTTP (`url`),
+ * completes the `initialize` handshake, and fetches its tool catalog once, up
+ * front. Failed or interrupted setup closes its subprocess, I/O fibers, or
+ * HTTP session before returning to the caller; a successful session stays
+ * open until the caller scope closes.
+ *
+ * The tool catalog is a snapshot: a server that changes its tools after
+ * connecting (a `notifications/tools/list_changed` push) is not re-polled.
+ * {@link McpFlows} rebuilds by reconnecting to refresh.
+ * Catalog input schemas must declare `type: "object"`. A later tool result may
+ * omit `content` when it carries `structuredContent`; a declared output schema
+ * is enforced for the documented keyword subset.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const connect: <O extends ConnectOptions>(options: O) => Effect.Effect<McpClient, McpError, Requirements<O> | Scope.Scope>;
+//# sourceMappingURL=McpClient.d.ts.map

package/dist/cjs/McpClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpClient.d.ts","sourceRoot":"","sources":["../../src/McpClient.ts"],"names":[],"mappings":"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"}