@effected/mcp 0.1.0

package/McpToolAudit.js

@@ -0,0 +1,105 @@
+//#region src/McpToolAudit.ts
+const isNode = (u) => typeof u === "object" && u !== null && !Array.isArray(u);
+const HINTS = [
+	"readOnlyHint",
+	"destructiveHint",
+	"idempotentHint",
+	"openWorldHint"
+];
+/** Real branches whose members are separate object shapes, each worth its own report. `allOf` is not one of these: core emits it to merge keywords (declared `properties` plus a Record's `additionalProperties`) onto the SAME node, never to introduce a sibling shape. */
+const BRANCHES = [
+	"prefixItems",
+	"anyOf",
+	"oneOf"
+];
+const objectNodes = (schema) => {
+	const out = [];
+	const join = (path, key) => path === "" ? key : `${path}.${key}`;
+	const visit = (node, path) => {
+		if (!isNode(node)) return;
+		const merged = Array.isArray(node.allOf) ? [node, ...node.allOf.filter(isNode)] : [node];
+		const declaredParts = merged.filter((part) => isNode(part.properties));
+		const properties = declaredParts.length === 0 ? void 0 : declaredParts.reduce((acc, part) => {
+			for (const [key, child] of Object.entries(part.properties)) acc[key] = child;
+			return acc;
+		}, Object.create(null));
+		const closed = merged.some((part) => part.additionalProperties === false);
+		if (isNode(properties) || merged.some((part) => part.type === "object")) out.push({
+			path,
+			properties,
+			closed
+		});
+		if (isNode(properties)) for (const [key, child] of Object.entries(properties)) visit(child, join(path, key));
+		visit(node.items, join(path, "items"));
+		visit(node.additionalProperties, join(path, "additionalProperties"));
+		for (const keyword of BRANCHES) {
+			const list = node[keyword];
+			if (Array.isArray(list)) for (const [index, child] of list.entries()) visit(child, join(path, `${keyword}[${index}]`));
+		}
+		if (isNode(node.$defs)) for (const [key, child] of Object.entries(node.$defs)) visit(child, `$defs.${key}`);
+	};
+	visit(schema, "");
+	return out;
+};
+/**
+* A pure sweep over a served `tools/list` that returns every policy
+* violation, as `"<tool>: <what>"` strings.
+*
+* @remarks
+* Run it against what a real server serves (`McpHarness.listTools`), not
+* against your own schemas: the served document is what a client sees, and
+* it differs by protocol revision. The stateless `2026-07-28` adapter passes a
+* non-object output through, while the stateful adapters drop it — which is
+* why `objectRootedOutput` defaults to `true`.
+*
+* `"closed"` is only as sound as the walk. It follows `properties`,
+* `items`, a schema-valued `additionalProperties`, `prefixItems`, `anyOf`,
+* `oneOf` and `$defs`, and merges an `allOf` member's `properties` and
+* `additionalProperties: false` onto its node. It does not visit
+* `patternProperties` values, an `allOf` member's `items` or
+* `additionalProperties` schema, or an `allOf` nested inside another; and
+* a key declared in two `allOf` members is last-write-wins. A hand-authored
+* or `Tool.dynamic` schema can therefore pass `"closed"` with an open node
+* the walk never reached. Core-emitted strict schemas close every node, so
+* a strict `Tool.make` tool is reported faithfully.
+*
+* @public
+*/
+var McpToolAudit = class {
+	constructor() {}
+	/**
+	* Every violation of `policy` across `tools`, as `"<tool>: <what>"`, in
+	* tool order. Empty means the sweep passed. A duplicate tool name is
+	* reported under every policy, `input: "any"` included.
+	*/
+	static check = (tools, policy) => {
+		const violations = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const tool of tools) {
+			const report = (what) => {
+				violations.push(`${tool.name}: ${what}`);
+			};
+			if (seen.has(tool.name)) report("duplicate tool name");
+			seen.add(tool.name);
+			if (policy.input !== "any") for (const { path, properties, closed } of objectNodes(tool.inputSchema)) {
+				const where = path === "" ? "the root" : path;
+				if (policy.input === "closed" && !closed) report(`input schema is open at ${where}`);
+				if (policy.input === "open" && isNode(properties) && closed) report(`input schema is closed at ${where}`);
+			}
+			const title = tool.title ?? tool.annotations?.title;
+			if (policy.requireTitle === true && (typeof title !== "string" || title === "")) report("no title");
+			if (policy.requireOutputSchema === true && tool.outputSchema === void 0) report("no outputSchema");
+			if ((policy.objectRootedOutput ?? true) && tool.outputSchema !== void 0 && tool.outputSchema.type !== "object") report(`outputSchema is not object-rooted (root type: ${String(tool.outputSchema.type ?? "none")})`);
+			const length = (tool.description ?? "").length;
+			if (policy.maxDescription !== void 0 && length > policy.maxDescription) report(`description is ${length} characters, over the ${policy.maxDescription} limit`);
+			if (policy.requireHints === true) {
+				const missing = HINTS.filter((hint) => typeof tool.annotations?.[hint] !== "boolean");
+				if (missing.length > 0) report(`missing annotation hints: ${missing.join(", ")}`);
+			}
+		}
+		return violations;
+	};
+};
+
+//#endregion
+export { McpToolAudit };

package/McpToolkit.js

@@ -0,0 +1,79 @@
+import { ToolInputSchema } from "./ToolInputSchema.js";
+import { Context, Effect, Layer } from "effect";
+import { McpSchema, McpServer, Tool, Toolkit } from "effect/unstable/ai";
+
+//#region src/McpToolkit.ts
+const DEFAULT_STRICT = "all";
+const strictened = (toolkit, mode) => mode === "annotated" ? toolkit : Toolkit.make(...Object.values(toolkit.tools).map((tool) => Tool.isDynamic(tool) || Tool.getStrictMode(tool) !== void 0 ? tool : tool.annotate(Tool.Strict, true)));
+/**
+* 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
+*/
+var McpToolkit = class {
+	constructor() {}
+	/**
+	* `McpServer.toolkit`'s registration layer, strict by default and naming
+	* every unknown argument in one `InvalidParams`.
+	*/
+	static layer = (toolkit, options = {}) => Layer.effectDiscard(Effect.gen(function* () {
+		const registry = yield* McpServer.McpServer;
+		const format = options.unknownKeyMessage ?? ((levels) => ToolInputSchema.formatUnknownKeys(levels));
+		const decorated = McpServer.McpServer.of({
+			...registry,
+			addTool: (registration) => Context.get(registration.annotations, Tool.Strict) === true ? registry.addTool({
+				...registration,
+				handle: (payload) => Effect.suspend(() => {
+					const levels = ToolInputSchema.unknownKeys(payload ?? {}, registration.tool.inputSchema);
+					return levels.length > 0 ? Effect.fail(new McpSchema.InvalidParams({ message: format(levels) })) : registration.handle(payload);
+				})
+			}) : registry.addTool(registration)
+		});
+		yield* McpServer.registerToolkit(strictened(toolkit, options.strict ?? DEFAULT_STRICT)).pipe(Effect.provideService(McpServer.McpServer, decorated));
+	})).pipe(Layer.provide(McpServer.McpServer.layer));
+};
+
+//#endregion
+export { McpToolkit };

package/README.md

@@ -0,0 +1,406 @@
+# @effected/mcp
+
+The boundary layer of an `effect/unstable/ai` MCP server: stdio wiring that keeps stdout the JSON-RPC wire, tool-failure shaping, and strict-input walkers, plus a `./testing` subpath for driving a built server from a test.
+
+[![npm](https://img.shields.io/npm/v/@effected%2Fmcp?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
+> development against a single pinned Effect v4 prerelease. Packages graduate to
+> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
+> exactly the ones the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Install
+
+```bash
+npm install @effected/mcp @effected/engine effect
+```
+
+```bash
+pnpm add @effected/mcp @effected/engine effect
+```
+
+Requires Node.js >=24.11.0.
+
+All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
+
+`effect` v4 and `@effected/engine` are the only peer dependencies. Boundary tier: `src/` reads no `process` token, imports no `node:` module and no `@effect/platform*` package, and calls no `console.*` — stdout is the JSON-RPC wire a server writes over.
+
+## ToolFailure
+
+Core's MCP server sends a tool's declared failure — an `Error` instance, which every `Schema.TaggedError` is — as `isError: true` with `error.message` as the only text and no `structuredContent`. Whatever is not folded into `message` when the error is constructed never reaches the agent. `ToolFailure` is the shared shape for doing that folding consistently across a server's tools.
+
+Spread `ToolFailure.fields` into a tool's `Schema.TaggedError`, build `message` with `ToolFailure.message`, and pass every caller-supplied value through `ToolFailure.truncate` before echoing it back:
+
+```ts
+import { ToolFailure } from "@effected/mcp";
+import { Schema } from "effect";
+
+class NotFound extends Schema.TaggedError<NotFound>()("NotFound", {
+  ...ToolFailure.fields,
+  id: Schema.String,
+}) {}
+
+const remediation = { hint: "List the ids first.", suggestedTool: "list_things" };
+const id = "missing-id";
+
+const error = new NotFound({
+  id,
+  remediation,
+  message: ToolFailure.message(`No thing "${ToolFailure.truncate(id)}".`, remediation),
+});
+
+console.log(error.message);
+// => No thing "missing-id". List the ids first. Try list_things.
+```
+
+`ToolFailure.message` drops any empty part, so an omitted `suggestedTool` or an empty `hint` never leaves a double space:
+
+```ts
+import { ToolFailure } from "@effected/mcp";
+
+console.log(ToolFailure.message("Config missing.", { hint: "Run init." }));
+// => Config missing. Run init.
+```
+
+`ToolFailure.truncate` caps a caller-supplied value at `ToolFailure.ECHO_LIMIT` (200 UTF-16 code units) before it is echoed into a message, backing off one unit rather than splitting a surrogate pair. A value the engine itself produced — a path, a diagnostic — can take the larger `ToolFailure.ENGINE_ECHO_LIMIT` (2000):
+
+```ts
+import { ToolFailure } from "@effected/mcp";
+
+console.log(ToolFailure.truncate("a".repeat(500)).length);
+// => 201 (200 characters, then "…")
+
+const enginePath = `/work/${"deep/".repeat(100)}file.ts`;
+console.log(ToolFailure.truncate(enginePath, ToolFailure.ENGINE_ECHO_LIMIT) === enginePath);
+// => true (under the 2000-unit engine cap)
+```
+
+`ToolFailure` is a static-namespace class with a private constructor — it is never instantiated.
+
+## Putting it together
+
+A stdio server's `main.ts` is one line, plus the layer that wires it:
+
+```ts
+import { McpStdio, McpToolkit, ToolFailure } from "@effected/mcp";
+import { NodeRuntime, NodeStdio } from "@effect/platform-node";
+import { Effect, Layer, Schema } from "effect";
+import { Tool, Toolkit } from "effect/unstable/ai";
+
+class NotFound extends Schema.TaggedError<NotFound>()("NotFound", {
+  ...ToolFailure.fields,
+  id: Schema.String,
+}) {}
+
+const GetThing = Tool.make("get_thing", {
+  description: "Fetch a thing by id.",
+  parameters: Schema.Struct({ id: Schema.String }),
+  success: Schema.Struct({ name: Schema.String }),
+  failure: NotFound,
+});
+
+const MyTools = Toolkit.make(GetThing);
+
+const MyHandlers = MyTools.toLayer({
+  get_thing: ({ id }) =>
+    id === "known"
+      ? Effect.succeed({ name: "a known thing" })
+      : Effect.fail(
+          new NotFound({
+            id,
+            remediation: { hint: "List the ids first.", suggestedTool: "list_things" },
+            message: ToolFailure.message(`No thing "${ToolFailure.truncate(id)}".`, {
+              hint: "List the ids first.",
+              suggestedTool: "list_things",
+            }),
+          }),
+        ),
+});
+
+const ToolsLayer = McpToolkit.layer(MyTools).pipe(Layer.provide(MyHandlers));
+const ServerLayer = ToolsLayer.pipe(
+  Layer.provideMerge(McpStdio.layer({ name: "my-server", version: "1.0.0" })),
+);
+
+// The platform Stdio is the one service provided at the edge.
+const Main = ServerLayer.pipe(Layer.provide(NodeStdio.layer));
+
+NodeRuntime.runMain(McpStdio.launch(Main), { teardown: McpStdio.teardown });
+```
+
+The platform `Stdio` is the one service provided at the edge: `ServerLayer`
+still requires it, and `Main` supplies `NodeStdio.layer` from
+`@effect/platform-node` just before launch. Leave that line out and
+`McpStdio.launch(Main)` fails to typecheck, because `Stdio` is still in its
+requirements. Test `ServerLayer`, never `Main`: `McpHarness.make` supplies
+its own queue-backed `Stdio`.
+
+`McpToolkit.layer` re-annotates every tool without its own `Tool.Strict`
+annotation to strict by default, so `get_thing({ id: "known", extra: 1 })`
+is rejected with one `Unrecognized parameter(s): extra. Accepted params:
+id.` before the handler ever runs — see [Strict input](#strict-input)
+below.
+
+## The stdio boundary
+
+`McpStdio.layer` is core's `McpServer.layerStdio` with every log line sent to
+stderr, and with stdin read through a guard. Core's own stdio decoder throws on
+a line that is not JSON without ever trimming it from its buffer, so one bad
+line wedges the server: every later request goes unanswered while stdin EOF
+still exits 0. The guard frames stdin exactly as core does — one streaming
+UTF-8 decoder, a byte-order mark stripped only at the start of the stream,
+lines split on `\n` — and answers each line core would choke on itself, on
+stdout:
+
+- a line that is not JSON gets a JSON-RPC parse error,
+  `{"jsonrpc":"2.0","id":null,"error":{"code":-32700,"message":"Parse error"}}`,
+  and the server keeps serving the lines after it;
+- a line longer than core's cap of 16 Mi UTF-16 code units gets the same
+  reply once, as soon as it passes the cap, and the rest of it is discarded
+  up to its newline;
+- a line that is JSON but no JSON-RPC message gets an Invalid Request,
+  `{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Invalid Request"}}`,
+  and the server keeps serving. That covers a value that is neither an object
+  nor an array (core throws on a bare `null`, dropping every other frame that
+  arrived in the same 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 that too), and an object with neither `method` nor
+  `id`, which is neither a request nor a response;
+- a line of JSON whitespace (space, tab, carriage return) is ignored.
+
+Every other line goes to core. That includes an array, which core answers with
+`-32600` itself because it serves no batches, and an object with an `id` and
+no `method`, which is a response and never gets a reply.
+
+**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` — a nested `Layer.build` or `Effect.provide` forks 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.
+
+## Strict input
+
+Two ways to close a tool's input schema against unknown keys, at different
+scopes:
+
+- **`ToolInputSchema`** — pure walkers, for a `Tool.dynamic` tool,
+  whose raw JSON Schema core never validates strictly: run
+  `ToolInputSchema.unknownKeys(payload, schema)` inside its handler against
+  the schema you registered, usually paired with `objectRooted(schema)`,
+  because a top-level discriminated union only reaches a server as raw
+  JSON Schema — core dies at boot on a union root. Not for a `Tool.make`
+  tool: core decodes its payload before the handler runs, so an excess key
+  is already dropped or rejected by then.
+- **`McpToolkit.layer(toolkit, options?)`** — the registration-scoped
+  decorator, and the recommended default: every tool without its own
+  `Tool.Strict` annotation is served and decoded strict
+  (`options.strict` defaults to `"all"`), and a rejected call names every
+  unknown key at every depth in one response, not just the first. An
+  explicit `Tool.Strict` annotation always wins, and a `Tool.dynamic` tool
+  is never re-annotated. Pass `{ strict: "annotated" }` to leave
+  unannotated tools lenient, or annotate an individual tool
+  `Tool.Strict` false to opt it out under the default.
+
+```ts
+import { McpToolkit } from "@effected/mcp";
+import { Layer } from "effect";
+import type { Tool, Toolkit } from "effect/unstable/ai";
+
+// The toolkit and its handlers, as built in "Putting it together".
+declare const MyTools: Toolkit.Toolkit<Record<string, Tool.Any>>;
+declare const MyHandlers: Layer.Layer<never>;
+
+// Default: every tool is strict, and every rejection names every unknown key.
+const ToolsLayer = McpToolkit.layer(MyTools).pipe(Layer.provide(MyHandlers));
+
+// Only tools explicitly annotated Tool.Strict are decoded strict.
+const LenientByDefault = McpToolkit.layer(MyTools, { strict: "annotated" }).pipe(Layer.provide(MyHandlers));
+```
+
+The dynamic-tool recipe, with the handler reporting every unknown key:
+
+```ts
+import { McpToolkit, ToolInputSchema } from "@effected/mcp";
+import { Effect, Layer, Schema } from "effect";
+import { Tool, Toolkit } from "effect/unstable/ai";
+
+// A top-level union, written as raw JSON Schema and rewritten to an object root.
+const EditInput = ToolInputSchema.objectRooted({
+  anyOf: [
+    {
+      type: "object",
+      properties: {
+        action: { const: "rename" },
+        to: { type: "string" },
+        options: { type: "object", properties: { force: { type: "boolean" } }, additionalProperties: false },
+      },
+      required: ["action", "to"],
+      additionalProperties: false,
+    },
+    {
+      type: "object",
+      properties: { action: { const: "delete" } },
+      required: ["action"],
+      additionalProperties: false,
+    },
+  ],
+});
+
+class UnknownKeys extends Schema.TaggedError<UnknownKeys>()("UnknownKeys", { message: Schema.String }) {}
+
+const Edit = Tool.dynamic("edit", {
+  description: "Rename or delete a thing.",
+  parameters: EditInput,
+  failure: UnknownKeys,
+});
+
+const EditTools = Toolkit.make(Edit);
+
+const EditHandlers = EditTools.toLayer({
+  // A dynamic tool is decoded as Schema.Unknown: the handler sees the raw payload.
+  edit: (payload) => {
+    const levels = ToolInputSchema.unknownKeys(payload, EditInput);
+    return levels.length > 0
+      ? Effect.fail(new UnknownKeys({ message: ToolInputSchema.formatUnknownKeys(levels) }))
+      : Effect.succeed(payload);
+  },
+});
+
+// McpToolkit never re-annotates a Tool.dynamic tool, so it stays lenient and the handler reports.
+const EditLayer = McpToolkit.layer(EditTools).pipe(Layer.provide(EditHandlers));
+```
+
+```text
+edit({ action: "rename", to: "b", extra: 1, options: { force: true, bogus: 2 } })
+=> Unrecognized parameter(s): extra. Accepted params: action, to, options. Unrecognized parameter(s): options.bogus. Accepted params: force.
+```
+
+## Testing
+
+`@effected/mcp/testing` is a separate entrypoint — importing it never pulls
+test machinery into a server's runtime import graph.
+
+```ts
+import { McpHarness } from "@effected/mcp/testing";
+import { Effect, type Layer, type Stdio } from "effect";
+import type { McpServer } from "effect/unstable/ai";
+
+// The server layer from "Putting it together" — still requiring Stdio.
+declare const ServerLayer: Layer.Layer<McpServer.McpServer, never, Stdio.Stdio>;
+
+const test = Effect.gen(function* () {
+  const client = yield* McpHarness.make(ServerLayer);
+  yield* client.initialize; // initialize + notifications/initialized: every stateful revision requires it
+  const result = yield* client.callTool("get_thing", { id: "known" });
+  // result.result.structuredContent === { name: "a known thing" }
+  yield* client.close;
+});
+```
+
+On a stateful revision (the default is `2025-11-25`), `initialize` comes
+first: any other request sent before it fails fast with `McpTestFailure`
+reason `NotInitialized` instead of the server's opaque `Invalid request
+metadata`.
+
+`McpHarness.make` runs the server in-process over queue-backed `Stdio`, so
+a test sees the exact served schemas and wire results a real client would,
+with no child process and no sockets. Pass `server` **without** a `Stdio`
+of its own — a `Stdio` the server provides internally would talk to the
+real terminal instead of the test's queues, including one that arrives
+bundled: `@effect/platform-node`'s `NodeServices.layer` brings its own
+`Stdio` along with `FileSystem`, `Path`, `ChildProcessSpawner`, `Crypto`
+and `Terminal`, so composing the server with that bundle loses the harness's
+`Stdio` the same way. Compose the individual platform layers the server
+needs instead and leave `Stdio` out; the harness supplies it. The harness builds the server
+with a fresh layer memo map, never the ambient one, so a harness made under
+another stdio server's `Effect.provide` still serves its own. For the same
+reason, never pass a server layer that provides a layer the test also
+provides and then reads: `McpHarness.make(server.pipe(Layer.provide(AppLayer)))`
+under `Effect.provide(AppLayer)` builds `AppLayer` twice, so the tools write
+to one instance and the test reads the other. Leave the service in the
+server layer's requirements and provide it once from the test, or build it
+once and pass `Layer.succeed(Tag, value)`. `McpProcess.spawn` and
+`McpProbe.initialize` are the spawned-bin equivalents, for a test that
+must exercise a built artifact rather than a layer — `McpProbe` in
+particular is the MCP half of a packed-install proof: it keeps stdin open
+until the response arrives, and the caller asserts
+`result.response.error === undefined`, empty `stderr` and exit 0 — a
+server that refuses the handshake still answers, exits 0 and stays quiet.
+`McpToolAudit.check` is a pure sweep over a served `tools/list`, for a
+static policy check with no server at all. `client.listResources` and
+`client.readResource(uri)` mirror `listTools`/`callTool` for a server's
+`resources/list` and `resources/read`.
+
+`McpProcess` writes a JSON-encoded message with `send`, and anything at all
+with `sendRaw(text: string | Uint8Array)`, which writes the string or bytes
+verbatim. `sendRaw` is the only way to put genuinely malformed input on a
+server's stdin — `send` and `McpHarness` always encode valid JSON — so it is
+how a test proves the stdin guard against a spawned server:
+
+```ts
+import { unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { NodeServices } from "@effect/platform-node";
+import { McpProcess } from "@effected/mcp/testing";
+import { Effect } from "effect";
+import { ChildProcess } from "effect/unstable/process";
+
+// A minimal server, written to disk so it can be spawned as a real process.
+const serverFile = join(import.meta.dirname, "mcp-guard-demo-server.mjs");
+writeFileSync(
+  serverFile,
+  `
+import { McpStdio, McpToolkit } from "@effected/mcp";
+import { NodeRuntime, NodeStdio } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+import { Tool, Toolkit } from "effect/unstable/ai";
+
+const Ping = Tool.make("ping", { description: "Liveness check.", parameters: Tool.EmptyParams });
+const Tools = Toolkit.make(Ping);
+const Handlers = Tools.toLayer({ ping: () => Effect.void });
+const Main = McpToolkit.layer(Tools).pipe(
+  Layer.provide(Handlers),
+  Layer.provideMerge(McpStdio.layer({ name: "guard-demo", version: "0.0.0" })),
+  Layer.provide(NodeStdio.layer),
+);
+
+NodeRuntime.runMain(McpStdio.launch(Main), { teardown: McpStdio.teardown });
+`,
+);
+
+const program = Effect.gen(function* () {
+  const server = yield* McpProcess.spawn(ChildProcess.make(process.execPath, [serverFile]));
+  yield* server.handshake(); // always id 1
+  // A bad line and a good one, in the same write.
+  yield* server.sendRaw('not json\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n');
+  const { response, seen } = yield* server.readUntilResponse(2);
+  console.log("answered the bad line:", seen.some((frame) => (frame as { id: unknown }).id === null));
+  console.log("kept serving:", Array.isArray((response.result as { tools: unknown }).tools));
+}).pipe(Effect.scoped, Effect.provide(NodeServices.layer), Effect.timeout("5 seconds"));
+
+await Effect.runPromise(program).finally(() => unlinkSync(serverFile));
+// => answered the bad line: true
+// => kept serving: true
+```
+
+## Tier
+
+Boundary tier. Peers: `@effected/engine` and `effect`. Nothing in the kit depends on `@effected/mcp` except an application; it never depends on `@effected/cli` or `@effected/workspaces` — a CLI boundary and an MCP boundary are siblings, both front ends, never layers on each other.
+
+## License
+
+[MIT](LICENSE)

package/ToolFailure.js

@@ -0,0 +1,63 @@
+import { Schema } from "effect";
+import { Remediation } from "@effected/engine";
+
+//#region src/ToolFailure.ts
+const isHighSurrogate = (code) => code >= 55296 && code <= 56319;
+/**
+* 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
+*/
+var ToolFailure = class ToolFailure {
+	constructor() {}
+	/** The cap, in UTF-16 code units, on a caller-supplied value echoed into a message. */
+	static ECHO_LIMIT = 200;
+	/** The larger cap for a value the engine produced (a path, a diagnostic), not one a caller typed. */
+	static ENGINE_ECHO_LIMIT = 2e3;
+	/** The `message` and `remediation` fields to spread into a consumer's `Schema.TaggedError`. */
+	static fields = {
+		message: Schema.String,
+		remediation: Remediation
+	};
+	/**
+	* `"<raw> <hint> Try <suggestedTool>."`, dropping any empty part, so a
+	* missing tool or an empty hint never leaves a double space.
+	*/
+	static message = (raw, remediation) => [
+		raw,
+		remediation.hint,
+		remediation.suggestedTool === void 0 ? "" : `Try ${remediation.suggestedTool}.`
+	].filter((part) => part !== "").join(" ");
+	/**
+	* `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 truncate = (value, limit = ToolFailure.ECHO_LIMIT) => {
+		if (value.length <= limit) return value;
+		const end = limit > 0 && isHighSurrogate(value.charCodeAt(limit - 1)) ? limit - 1 : limit;
+		return `${value.slice(0, end)}…`;
+	};
+};
+
+//#endregion
+export { ToolFailure };