@effected/mcp 0.1.0

package/ToolInputSchema.js

@@ -0,0 +1,167 @@
+import { ToolFailure } from "./ToolFailure.js";
+import { Result } from "effect";
+
+//#region src/ToolInputSchema.ts
+const MAX_DEPTH = 256;
+const MAX_ECHOED = 20;
+const DISCRIMINANTS = [
+	"action",
+	"kind",
+	"_tag",
+	"type"
+];
+const REF_PREFIX = "#/$defs/";
+const isNode = (u) => typeof u === "object" && u !== null && !Array.isArray(u);
+const resolveRef = (node, root, seen = /* @__PURE__ */ new Set()) => {
+	const ref = node.$ref;
+	if (typeof ref !== "string" || !ref.startsWith(REF_PREFIX) || seen.has(ref)) return node;
+	const defs = root.$defs;
+	const name = ref.slice(8).replaceAll("~1", "/").replaceAll("~0", "~");
+	const target = isNode(defs) && Object.hasOwn(defs, name) ? defs[name] : void 0;
+	if (!isNode(target)) return node;
+	const { $ref: _ref, ...siblings } = node;
+	return resolveRef({
+		...target,
+		...siblings
+	}, root, /* @__PURE__ */ new Set([...seen, ref]));
+};
+const literalValues = (node) => {
+	if (!isNode(node)) return void 0;
+	if (Array.isArray(node.enum)) return node.enum;
+	return "const" in node ? [node.const] : void 0;
+};
+const discriminantOf = (members) => members.length === 0 ? void 0 : DISCRIMINANTS.find((key) => members.every((member) => isNode(member.properties) && literalValues(member.properties[key]) !== void 0));
+const selectMember = (members, value, root) => {
+	const resolved = members.filter(isNode).map((member) => resolveRef(member, root));
+	const key = discriminantOf(resolved);
+	if (key !== void 0) return resolved.find((member) => literalValues(member.properties[key])?.includes(value[key]) === true);
+	const objects = resolved.filter((member) => isNode(member.properties) || member.type === "object");
+	return objects.length === 1 ? objects[0] : void 0;
+};
+const matchesPattern = (pattern, key) => Result.getOrUndefined(Result.try(() => new RegExp(pattern, "u").test(key))) === true;
+const collect = (payload, root) => {
+	const out = [];
+	const walk = (value, raw, path, depth) => {
+		if (depth > MAX_DEPTH || !isNode(raw)) return;
+		const node = resolveRef(raw, root);
+		const parts = [node, ...Array.isArray(node.allOf) ? node.allOf.filter(isNode).map((m) => resolveRef(m, root)) : []];
+		const members = Array.isArray(node.oneOf) ? node.oneOf : Array.isArray(node.anyOf) ? node.anyOf : void 0;
+		const additional = parts.map((part) => part.additionalProperties).find(isNode);
+		const isClosed = parts.some((part) => part.additionalProperties === false);
+		if (Array.isArray(value)) {
+			const prefix = Array.isArray(node.prefixItems) ? node.prefixItems : [];
+			if (prefix.length === 0 && !isNode(node.items) && members !== void 0) {
+				const arrays = members.filter(isNode).map((member) => resolveRef(member, root)).filter((member) => member.type === "array");
+				if (arrays.length === 1) walk(value, arrays[0], path, depth + 1);
+				return;
+			}
+			for (const [index, item] of value.entries()) walk(item, index < prefix.length ? prefix[index] : node.items, [...path, String(index)], depth + 1);
+			return;
+		}
+		if (!isNode(value)) return;
+		const declared = parts.filter((part) => isNode(part.properties));
+		if (declared.length === 0 && members !== void 0) {
+			const member = selectMember(members, value, root);
+			if (member !== void 0) walk(value, member, path, depth + 1);
+			return;
+		}
+		const properties = Object.create(null);
+		for (const part of declared) for (const [key, schema] of Object.entries(part.properties)) properties[key] = schema;
+		const patterns = parts.flatMap((part) => isNode(part.patternProperties) ? Object.entries(part.patternProperties) : []);
+		const accepted = Object.keys(properties);
+		const extra = [];
+		const patterned = [];
+		for (const key of Object.keys(value)) {
+			if (Object.hasOwn(properties, key)) continue;
+			const match = patterns.find(([pattern]) => matchesPattern(pattern, key));
+			if (match === void 0) extra.push(key);
+			else patterned.push([key, match[1]]);
+		}
+		if (extra.length > 0 && isClosed) out.push({
+			path,
+			unknown: extra,
+			accepted
+		});
+		for (const key of accepted) if (Object.hasOwn(value, key)) walk(value[key], properties[key], [...path, key], depth + 1);
+		for (const [key, schema] of patterned) walk(value[key], schema, [...path, key], depth + 1);
+		if (additional !== void 0) for (const key of extra) walk(value[key], additional, [...path, key], depth + 1);
+	};
+	walk(payload, root, [], 0);
+	return out;
+};
+/**
+* Pure walkers over a tool's served JSON Schema: every unknown key at every
+* depth, a message naming them all, and an object-rooted form of a union.
+*
+* @remarks
+* Core's `Tool.Strict` rejects unknown keys but reports only the first
+* (effect `unstable/ai/McpServer.ts` decodes without `errors: "all"`), so an
+* agent fixes one typo per round trip. These walkers run over the schema core
+* actually serves, so what they accept matches what the tool advertises:
+*
+* - Only `additionalProperties: false` closes a node, as in JSON Schema; core
+*   emits it on every object node of a strict tool and `true` otherwise.
+* - `allOf` members' properties merge; `oneOf`/`anyOf` members are chosen by an
+*   `action`, `kind`, `_tag` or `type` literal (tried in that order), or by
+*   being the only object member. A payload whose discriminant matches no
+*   member, or is missing, is skipped and left for decoding.
+* - `items`, `prefixItems`, `$ref` into `$defs` (JSON Pointer escapes
+*   honoured), and `patternProperties` are followed; a key matched by a
+*   pattern is accepted and walked with the first matching pattern's schema.
+* - The payload is untrusted: the walk stops descending at depth 256 rather
+*   than overflowing the stack, so a deeper unknown key goes unreported and
+*   is left for decoding. Every hop counts toward that cap: each property or
+*   array position, and also each union member selection, which adds a hop
+*   without adding a path segment.
+*
+* @public
+*/
+var ToolInputSchema = class {
+	constructor() {}
+	/** Every level of `payload` that carries a key `schema` does not accept. */
+	static unknownKeys = (payload, schema) => collect(payload, schema);
+	/**
+	* `Unrecognized parameter(s): a, b.c. Accepted params: x, y.` per level. Each
+	* echoed key is truncated, and at most 20 keys and 20 levels are named; a
+	* trailing `(and N more levels).` counts the levels left out.
+	*/
+	static formatUnknownKeys = (levels, options = {}) => {
+		const limit = options.echoLimit ?? ToolFailure.ECHO_LIMIT;
+		const sentences = levels.slice(0, MAX_ECHOED).map((level) => {
+			const shown = level.unknown.slice(0, MAX_ECHOED).map((key) => ToolFailure.truncate([...level.path, key].join("."), limit));
+			const more = level.unknown.length > MAX_ECHOED ? ` (and ${level.unknown.length - MAX_ECHOED} more)` : "";
+			const accepted = level.accepted.length === 0 ? "(none)" : level.accepted.join(", ");
+			return `Unrecognized parameter(s): ${shown.join(", ")}${more}. Accepted params: ${accepted}.`;
+		});
+		const hidden = levels.length > MAX_ECHOED ? ` (and ${levels.length - MAX_ECHOED} more levels).` : "";
+		return `${sentences.join(" ")}${hidden}`;
+	};
+	/**
+	* `schema` with a root `$ref` inlined and a top-level union of objects
+	* sharing an `action`, `kind`, `_tag` or `type` literal rewritten to an
+	* object root carrying `type: "object"`, `oneOf` and `"x-discriminator"` —
+	* MCP requires an object root, and core dies at boot on a union root.
+	* Returned as the same value when nothing changes.
+	*/
+	static objectRooted = (schema) => {
+		const root = resolveRef(schema, schema);
+		const members = Array.isArray(root.anyOf) ? root.anyOf : Array.isArray(root.oneOf) ? root.oneOf : void 0;
+		if (root.type === void 0 && members !== void 0) {
+			const resolved = members.filter(isNode).map((member) => resolveRef(member, schema));
+			const key = resolved.length === members.length ? discriminantOf(resolved) : void 0;
+			if (key !== void 0) {
+				const { anyOf: _anyOf, oneOf: _oneOf, ...rest } = root;
+				return {
+					type: "object",
+					...rest,
+					oneOf: resolved,
+					"x-discriminator": key
+				};
+			}
+		}
+		return root;
+	};
+};
+
+//#endregion
+export { ToolInputSchema };

package/index.d.ts

@@ -0,0 +1,352 @@
+import { Array, Effect, JsonSchema, Layer, Runtime, Schema, Stdio } from "effect";
+import { McpProtocol, McpSchema, McpServer, Tool, Toolkit } from "effect/unstable/ai";
+import { Remediation } from "@effected/engine";
+//#region src/McpStdio.d.ts
+/**
+ * Options for {@link McpStdio.layer}.
+ *
+ * @public
+ */
+interface McpStdioOptions {
+  /** The server name reported to the client. */
+  readonly name: string;
+  /** The server version reported to the client. */
+  readonly version: string;
+  /** Surfaced in `initialize` and `server/discover`; tell the agent how to use the tools. */
+  readonly instructions?: string | undefined;
+  /** A one-line description of the server, reported to the client. */
+  readonly description?: string | undefined;
+  /** Defaults to {@link McpStdio.protocols}. Read its ordering rules before overriding. */
+  readonly protocols?: Array.NonEmptyReadonlyArray<McpProtocol.ProtocolAdapter> | undefined;
+}
+/**
+ * Serve an MCP server over stdio without ever writing a log line or a failure
+ * report onto stdout, which is the JSON-RPC wire.
+ *
+ * @remarks
+ * The one-line `main.ts`:
+ *
+ * ```ts
+ * NodeRuntime.runMain(McpStdio.launch(Main), { teardown: McpStdio.teardown })
+ * ```
+ *
+ * - {@link McpStdio.layer} is `McpServer.layerStdio` with `LogToStderr`
+ *   provided and merged into its output, and `Layer.orDie`. It answers a
+ *   stdin line that is not JSON with a JSON-RPC `-32700` parse error, and
+ *   JSON that is not a JSON-RPC message with `-32600`, and keeps serving.
+ * - {@link McpStdio.launch} reports a launch failure itself, on stderr, and
+ *   hides it from `runMain`, whose own report is written outside anything
+ *   the program can provide.
+ * - {@link McpStdio.teardown} maps stdin EOF, the normal end of every
+ *   session, to exit 0 instead of 130.
+ *
+ * Never `NodeRuntime.runMain(Layer.launch(Main).pipe(Effect.provideService(References.LogToStderr, true)))`:
+ * it typechecks and serves, but a launch failure is still reported by
+ * `runMain` through `console.log`, straight onto the wire, where the client
+ * reads it as a malformed frame instead of an error.
+ *
+ * @public
+ */
+export declare class McpStdio {
+  private constructor();
+  /**
+   * `[v2026_07_28, v2025_11_25, v2025_06_18]` — the stateless revision
+   * first, then the two newest stateful ones.
+   *
+   * @remarks
+   * Real clients open with either handshake: Claude Code 2.1.281 was
+   * measured opening a stdio server with the stateless `server/discover`,
+   * while most other shipping clients still send `initialize`. The order
+   * is load-bearing:
+   *
+   * - Stateless first: a request with no session and no `_meta` falls to
+   *   `protocols[0]`.
+   * - Never a single entry: `initialize` only matches stateful adapters, so
+   *   a stateless-only list refuses every client that opens with it.
+   * - At most one stateless adapter; a second fails the layer.
+   */
+  static readonly protocols: Array.NonEmptyReadonlyArray<McpProtocol.ProtocolAdapter>;
+  /**
+   * `McpServer.layerStdio` with `LogToStderr` provided and merged into the
+   * output, so every layer it provides logs to stderr too. A bad
+   * `protocols` list dies: it is the implementer's defect.
+   *
+   * @remarks
+   * Only a layer this one provides inherits `LogToStderr`: compose with
+   * `Layer.provideMerge(McpStdio.layer(...))`. A sibling merged beside it
+   * with `Layer.mergeAll` is not provided by it, so its build logs still
+   * go through `console.log`, onto the wire.
+   *
+   * The server reads stdin through a guard that frames it exactly as core's
+   * decoder does: one streaming UTF-8 decoder, a byte-order mark stripped
+   * only at the start of the stream, lines split on `\n`. A line that is
+   * not JSON is answered on stdout with a JSON-RPC parse error, code
+   * `-32700` and `id: null`, and never reaches core's decoder, which would
+   * otherwise throw on that line again for every later chunk and stop
+   * answering. So is a line longer than core's cap of 16 Mi UTF-16 code
+   * units: it is answered once, as soon as it passes the cap, and the rest
+   * of it is discarded up to its newline. A line of JSON whitespace (space,
+   * tab, carriage return) is ignored.
+   *
+   * A line that is JSON but no JSON-RPC message core can handle is answered
+   * with an Invalid Request, code `-32600` and `id: null`, and never reaches
+   * core: a value that is neither an object nor an array (core throws on
+   * `null`, dropping every other frame in its chunk, and ignores a number,
+   * string or boolean without a reply), an object whose `method` is not a
+   * string and whose `id` is absent or `null` (core throws on it too), and
+   * an object with neither `method` nor `id`, which is neither a request nor
+   * a response. Everything else goes to core: an array, which core answers
+   * `-32600` itself because it serves no batches; an object with an `id`
+   * and no `method`, which is a response and gets no reply; and a request
+   * with an `id`, which core answers even when its `method` is malformed.
+   *
+   * Give each server a fresh layer memo map. Core's stdio protocol layer
+   * is a shared constant, so a second `McpStdio.layer` server whose build
+   * sees the first one's memo map shares its protocol: only the first
+   * server reads stdin, and the second never answers. Merging both into
+   * one graph does that, and so does building or providing the second
+   * anywhere under the first one's `Effect.provide`: nested `Layer.build`
+   * and `Effect.provide` fork the ambient memo map rather than starting a
+   * new one. Isolate each server with its own `ManagedRuntime`,
+   * `Effect.provide(layer, { local: true })` or its own process.
+   *
+   * Code after a completed `Effect.provide` of a stdio server never runs:
+   * core's stdio protocol interrupts the fiber that built it when its stdin
+   * loop ends, which closing the provide's scope does. In a test, serve the
+   * layer through `McpHarness` from `@effected/mcp/testing` instead.
+   *
+   * Each call mints a fresh layer; bind the result to a `const` or the
+   * server builds twice.
+   */
+  static readonly layer: (options: McpStdioOptions) => Layer.Layer<McpServer.McpServer | McpSchema.McpServerClient, never, Stdio.Stdio>;
+  /**
+   * `Layer.launch`, with any failure other than an interrupt logged on
+   * stderr here and re-raised marked as already reported, keeping its exit
+   * code.
+   *
+   * @remarks
+   * `runMain` logs an unhandled failure from outside the program, where no
+   * `Effect.provideService` reaches, and Effect's default logger writes
+   * through `console.log` unless `LogToStderr` is set. For an MCP server
+   * that is stdout, which is the wire.
+   */
+  static readonly launch: <ROut, E, R>(layer: Layer.Layer<ROut, E, R>) => Effect.Effect<never, Error, R>;
+  /**
+   * Success or an interrupt-only exit maps to 0. Anything else goes to
+   * `Runtime.defaultTeardown`.
+   *
+   * @remarks
+   * Stdin EOF, the normal end of every session, ends in an interrupt-only
+   * exit, and so do SIGINT and SIGTERM: `runMain` interrupts the program on
+   * either signal. All three exit 0 here, not the 130 a default teardown
+   * reports for an interrupt.
+   */
+  static readonly teardown: Runtime.Teardown;
+}
+//#endregion
+//#region src/ToolInputSchema.d.ts
+/**
+ * The unknown keys found at one object level of a tool-call payload.
+ *
+ * @public
+ */
+interface UnknownKeysLevel {
+  /** Keys from the payload root to this object; empty at the root. Array positions are decimal strings. */
+  readonly path: ReadonlyArray<string>;
+  /** Keys the payload carries that this level does not accept, in payload order. */
+  readonly unknown: ReadonlyArray<string>;
+  /** Keys this level declares, in schema order. */
+  readonly accepted: ReadonlyArray<string>;
+}
+/**
+ * Options for {@link ToolInputSchema.formatUnknownKeys}.
+ *
+ * @public
+ */
+interface FormatUnknownKeysOptions {
+  /** The cap on each echoed key path, in UTF-16 code units. Defaults to `ToolFailure.ECHO_LIMIT`. */
+  readonly echoLimit?: number | undefined;
+}
+/**
+ * Pure walkers over a tool's served JSON Schema: every unknown key at every
+ * depth, a message naming them all, and an object-rooted form of a union.
+ *
+ * @remarks
+ * Core's `Tool.Strict` rejects unknown keys but reports only the first
+ * (effect `unstable/ai/McpServer.ts` decodes without `errors: "all"`), so an
+ * agent fixes one typo per round trip. These walkers run over the schema core
+ * actually serves, so what they accept matches what the tool advertises:
+ *
+ * - Only `additionalProperties: false` closes a node, as in JSON Schema; core
+ *   emits it on every object node of a strict tool and `true` otherwise.
+ * - `allOf` members' properties merge; `oneOf`/`anyOf` members are chosen by an
+ *   `action`, `kind`, `_tag` or `type` literal (tried in that order), or by
+ *   being the only object member. A payload whose discriminant matches no
+ *   member, or is missing, is skipped and left for decoding.
+ * - `items`, `prefixItems`, `$ref` into `$defs` (JSON Pointer escapes
+ *   honoured), and `patternProperties` are followed; a key matched by a
+ *   pattern is accepted and walked with the first matching pattern's schema.
+ * - The payload is untrusted: the walk stops descending at depth 256 rather
+ *   than overflowing the stack, so a deeper unknown key goes unreported and
+ *   is left for decoding. Every hop counts toward that cap: each property or
+ *   array position, and also each union member selection, which adds a hop
+ *   without adding a path segment.
+ *
+ * @public
+ */
+export declare class ToolInputSchema {
+  private constructor();
+  /** Every level of `payload` that carries a key `schema` does not accept. */
+  static readonly unknownKeys: (payload: unknown, schema: JsonSchema.JsonSchema) => ReadonlyArray<UnknownKeysLevel>;
+  /**
+   * `Unrecognized parameter(s): a, b.c. Accepted params: x, y.` per level. Each
+   * echoed key is truncated, and at most 20 keys and 20 levels are named; a
+   * trailing `(and N more levels).` counts the levels left out.
+   */
+  static readonly formatUnknownKeys: (levels: ReadonlyArray<UnknownKeysLevel>, options?: FormatUnknownKeysOptions) => string;
+  /**
+   * `schema` with a root `$ref` inlined and a top-level union of objects
+   * sharing an `action`, `kind`, `_tag` or `type` literal rewritten to an
+   * object root carrying `type: "object"`, `oneOf` and `"x-discriminator"` —
+   * MCP requires an object root, and core dies at boot on a union root.
+   * Returned as the same value when nothing changes.
+   */
+  static readonly objectRooted: (schema: JsonSchema.JsonSchema) => JsonSchema.JsonSchema;
+}
+//#endregion
+//#region src/McpToolkit.d.ts
+/**
+ * Options for {@link McpToolkit.layer}.
+ *
+ * @public
+ */
+interface McpToolkitOptions {
+  /**
+   * `"all"` (the default): every tool without its own `Tool.Strict`
+   * annotation is served and decoded strict. `"annotated"`: only tools
+   * annotated `Tool.Strict` true are. In both modes an explicit annotation,
+   * true or false, always wins, and a `Tool.dynamic` tool is never
+   * re-annotated (core dies at registration on a strict dynamic tool). Only
+   * a tool that ends up strict gets the unknown-key pre-check; a lenient
+   * one is passed through untouched even if its raw schema is closed.
+   */
+  readonly strict?: "all" | "annotated" | undefined;
+  /**
+   * Replaces the default `ToolInputSchema.formatUnknownKeys` rendering. It
+   * runs per rejected call inside the handler's effect, so a throw becomes
+   * a defect of that call alone — the client receives a JSON-RPC internal
+   * error (-32603) — never a crash of the server.
+   */
+  readonly unknownKeyMessage?: ((levels: ReadonlyArray<UnknownKeysLevel>) => string) | undefined;
+}
+/**
+ * Register a toolkit exactly as core's `McpServer.toolkit` does, except that a
+ * strict tool's unknown arguments are all named, at every depth, in one
+ * response.
+ *
+ * @remarks
+ * Rejection itself is core's: a tool annotated `Tool.Strict` is served with
+ * `additionalProperties: false` on every object node and decoded with
+ * `onExcessProperty: "error"`. But core reports only the FIRST excess key
+ * (`Expected no excess property at ["extra"]`), so an agent fixes one typo
+ * per round trip and never learns about a nested one until the next call.
+ * This layer is the better report, not the rejecter: it runs core's
+ * `registerToolkit` unchanged under a registration-scoped `McpServer` whose
+ * `addTool` puts a `ToolInputSchema.unknownKeys` pre-check in front of each
+ * handler. The pre-check walks the input schema the tool actually serves
+ * (after core's own top-level `$ref` inlining), follows `$ref`, `allOf` and
+ * discriminated `oneOf`/`anyOf` members, and fails with one
+ * `McpSchema.InvalidParams` naming every unknown key path plus the accepted
+ * params, before core decodes. Core's strict decode stays behind it as the
+ * backstop. The pre-check is gated on the same predicate core uses to choose
+ * strict decoding — the registered tool's `Tool.Strict` annotation is
+ * `true` — so a lenient tool (explicit `Tool.Strict` false, a
+ * `Tool.dynamic` tool, or any unannotated tool under `"annotated"`) is
+ * never rejected here, even when its raw JSON Schema carries
+ * `additionalProperties: false`. The pre-check runs under `Effect.suspend`,
+ * so a throwing `unknownKeyMessage` dies inside the call's effect. No core
+ * internals are patched, so this survives an rc bump without re-diffing.
+ *
+ * Registration goes through core's module-level `McpServer.McpServer.layer`,
+ * shared by reference with `McpStdio.layer`'s own copy — provide both into
+ * the same graph, as with `McpServer.toolkit`. Never wrap that layer in
+ * `Layer.fresh`: tools would register into a second registry nobody serves.
+ *
+ * Each call mints a fresh layer; bind the result to a `const` or the
+ * registration runs twice.
+ *
+ * @example
+ * ```ts
+ * import { Layer } from "effect";
+ * import { McpStdio, McpToolkit } from "@effected/mcp";
+ *
+ * const ToolsLayer = McpToolkit.layer(MyToolkit).pipe(Layer.provide(MyHandlers));
+ * const ServerLayer = ToolsLayer.pipe(Layer.provideMerge(McpStdio.layer({ name: "my-server", version: "1.0.0" })));
+ * ```
+ *
+ * @public
+ */
+export declare class McpToolkit {
+  private constructor();
+  /**
+   * `McpServer.toolkit`'s registration layer, strict by default and naming
+   * every unknown argument in one `InvalidParams`.
+   */
+  static readonly layer: <Tools extends Record<string, Tool.Any>>(toolkit: Toolkit.Toolkit<Tools>, options?: McpToolkitOptions) => Layer.Layer<never, never, Tool.HandlersFor<Tools> | Exclude<Tool.HandlerServices<Tools>, McpSchema.McpRequestContext>>;
+}
+//#endregion
+//#region src/ToolFailure.d.ts
+/**
+ * How a tool's declared failure should read on the wire.
+ *
+ * @remarks
+ * Core sends a declared failure that is an `Error` instance — every
+ * `Schema.TaggedError` is — as `isError: true` with `error.message` as the only
+ * text and no `structuredContent` (effect `unstable/ai/McpServer.ts`,
+ * `declaredFailureResult`). So the remediation must be folded into `message`
+ * when the error is constructed: whatever is not in the message never reaches
+ * the agent.
+ *
+ * Spread {@link ToolFailure.fields} into your tool's `Schema.TaggedError`, build
+ * `message` with {@link ToolFailure.message}, and pass every caller-supplied
+ * value through {@link ToolFailure.truncate} before echoing it.
+ *
+ * @example
+ * ```ts
+ * class NotFound extends Schema.TaggedError<NotFound>()("NotFound", { ...ToolFailure.fields, id: Schema.String }) {}
+ * const remediation = { hint: "List the ids first.", suggestedTool: "list_things" }
+ * new NotFound({ id, remediation, message: ToolFailure.message(`No thing "${ToolFailure.truncate(id)}".`, remediation) })
+ * ```
+ *
+ * @public
+ */
+export declare class ToolFailure {
+  private constructor();
+  /** The cap, in UTF-16 code units, on a caller-supplied value echoed into a message. */
+  static readonly ECHO_LIMIT: number;
+  /** The larger cap for a value the engine produced (a path, a diagnostic), not one a caller typed. */
+  static readonly ENGINE_ECHO_LIMIT: number;
+  /** The `message` and `remediation` fields to spread into a consumer's `Schema.TaggedError`. */
+  static readonly fields: {
+    readonly message: Schema.String;
+    readonly remediation: Schema.Struct<{
+      readonly hint: Schema.String;
+      readonly suggestedTool: Schema.optionalKey<Schema.String>;
+      readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+    }>;
+  };
+  /**
+   * `"<raw> <hint> Try <suggestedTool>."`, dropping any empty part, so a
+   * missing tool or an empty hint never leaves a double space.
+   */
+  static readonly message: (raw: string, remediation: Remediation) => string;
+  /**
+   * `value` cut to `limit` code units with a trailing ellipsis, backing off one
+   * unit rather than splitting a surrogate pair. A hostile multi-megabyte
+   * argument is otherwise echoed into the agent's context whole.
+   */
+  static readonly truncate: (value: string, limit?: number) => string;
+}
+//#endregion
+export type { FormatUnknownKeysOptions, McpStdioOptions, McpToolkitOptions, UnknownKeysLevel };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,6 @@
+import { McpStdio } from "./McpStdio.js";
+import { ToolFailure } from "./ToolFailure.js";
+import { ToolInputSchema } from "./ToolInputSchema.js";
+import { McpToolkit } from "./McpToolkit.js";
+
+export { McpStdio, McpToolkit, ToolFailure, ToolInputSchema };

package/internal/LaunchFailed.js

@@ -0,0 +1,23 @@
+import { Runtime } from "effect";
+
+//#region src/internal/LaunchFailed.ts
+/**
+* The failure `McpStdio.launch` re-raises after reporting a launch failure on
+* stderr itself. `errorReported: false` keeps `runMain` from reporting it a
+* second time — through a logger that writes to stdout — and the original exit
+* code rides along for the teardown.
+*
+* @internal
+*/
+var LaunchFailed = class extends Error {
+	[Runtime.errorReported] = false;
+	[Runtime.errorExitCode];
+	constructor(code) {
+		super(`the MCP server failed to launch (exit ${code})`);
+		this.name = "LaunchFailed";
+		this[Runtime.errorExitCode] = code;
+	}
+};
+
+//#endregion
+export { LaunchFailed };