@effected/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+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/McpHarness.js

@@ -0,0 +1,234 @@
+import { ToolFailure } from "./ToolFailure.js";
+import { DEFAULT_CLIENT_INFO, frame, initializeParams, isJsonRpcMessage, isResponse, isStateless, parseFrame, requestKey } from "./internal/wire.js";
+import { McpTestFailure } from "./McpTestFailure.js";
+import { Console, Deferred, Effect, Exit, Layer, Queue, Sink, Stdio, Stream } from "effect";
+import { McpProtocol } from "effect/unstable/ai";
+
+//#region src/McpHarness.ts
+/**
+* An in-process MCP client for a real server layer, over queue-backed stdio.
+*
+* @remarks
+* Builds your server with a queue-backed `Stdio.layerTest` that satisfies the
+* server's `Stdio` requirement, so tests see the exact served schemas and wire
+* results a real client would, with no child and no sockets. Pass the server
+* WITHOUT a `Stdio` of its own: a `Stdio` the server provides internally wins,
+* and talks to the real terminal. A bundled platform layer such as
+* `NodeServices.layer` (`@effect/platform-node`) brings its own `Stdio` along
+* with `FileSystem`, `Path`, `ChildProcessSpawner`, `Crypto` and `Terminal` —
+* providing it to the server loses `Stdio` the same way, and every wait
+* hangs to timeout with no error naming why. Compose the individual layers
+* the server needs instead and leave `Stdio` out; this harness supplies it.
+*
+* The server is built 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. 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)`.
+*
+* - Responses are matched by id, so notifications may interleave freely.
+* - No wait can hang: every response wait and `awaitOutboundMethod` fails
+*   with `ServerStopped` when the server stops (stdin closing does that),
+*   and dies when `strictStdout` sees a line that is not JSON-RPC.
+* - With `captureLogs`, the server's console is captured: `stderrSoFar`
+*   holds stderr writes and every log line, and `consoleLogSoFar` holds
+*   anything that went through `console.log`, which in a real server is
+*   the wire. Assert it empty.
+* - On a stateful revision (the default `2025-11-25`), send `initialize`
+*   first. Every other request before it fails with `NotInitialized` and
+*   is never written: the server would only answer an opaque
+*   `Invalid request metadata`, `ping` included.
+*
+* @public
+*/
+var McpHarness = class McpHarness {
+	/** The revision this client speaks. */
+	protocol;
+	/** `initialize` then `notifications/initialized`; `server/discover` on a stateless revision. Call it first on a stateful revision. */
+	initialize;
+	/** `server/discover`. */
+	discover;
+	/** Send a request and wait for its response. */
+	request;
+	/** Send a request now; wait for its response later. Fails with `NotInitialized`, sending nothing, on a stateful revision before `initialize`. */
+	startRequest;
+	/** Send a notification. */
+	notify;
+	/** `tools/call`, returning the whole response: a JSON-RPC error is data here. */
+	callTool;
+	/** `tools/list`'s tools; a JSON-RPC error fails with `ErrorResponse`. */
+	listTools;
+	/** `resources/list`'s resources; a JSON-RPC error fails with `ErrorResponse`. */
+	listResources;
+	/** `resources/read`, returning the whole response. */
+	readResource;
+	/** Write any value as one newline-framed line. Never gated; a raw `initialize` counts as sent. */
+	sendRaw;
+	/** The next server-initiated frame with this method, skipping and keeping others; fails with `ServerStopped` once the server stops. */
+	awaitOutboundMethod;
+	/** Everything written to stderr, plus every captured log line. */
+	stderrSoFar;
+	/** Every captured `console.log`, `info` or `debug` call. */
+	consoleLogSoFar;
+	/** End stdin, as a client disconnecting does. */
+	close;
+	constructor(parts) {
+		this.protocol = parts.protocol;
+		this.initialize = parts.initialize;
+		this.discover = parts.discover;
+		this.request = parts.request;
+		this.startRequest = parts.startRequest;
+		this.notify = parts.notify;
+		this.callTool = parts.callTool;
+		this.listTools = parts.listTools;
+		this.listResources = parts.listResources;
+		this.readResource = parts.readResource;
+		this.sendRaw = parts.sendRaw;
+		this.awaitOutboundMethod = parts.awaitOutboundMethod;
+		this.stderrSoFar = parts.stderrSoFar;
+		this.consoleLogSoFar = parts.consoleLogSoFar;
+		this.close = parts.close;
+	}
+	/** Build `server` over queue-backed stdio and return a client for it; fails with the layer's own error if it cannot build. */
+	static make = (server, options = {}) => Effect.gen(function* () {
+		const protocol = options.protocol ?? McpProtocol.v2025_11_25;
+		const clientInfo = options.clientInfo ?? DEFAULT_CLIENT_INFO;
+		const strictStdout = options.strictStdout ?? true;
+		const stdin = yield* Queue.unbounded();
+		const stdout = yield* Queue.unbounded();
+		const inbound = yield* Queue.unbounded();
+		const retained = [];
+		const waiters = /* @__PURE__ */ new Map();
+		const stderr = [];
+		const consoleLog = [];
+		const ready = yield* Deferred.make();
+		const stopped = yield* Deferred.make();
+		const corrupt = yield* Deferred.make();
+		const encoder = new TextEncoder();
+		const stdoutDecoder = new TextDecoder();
+		const stderrDecoder = new TextDecoder();
+		let nextId = 1;
+		const stdio = Stdio.layerTest({
+			stdin: Stream.fromQueue(stdin),
+			stdout: () => Sink.forEach((chunk) => Queue.offer(stdout, chunk)),
+			stderr: () => Sink.forEach((chunk) => Effect.sync(() => {
+				stderr.push(typeof chunk === "string" ? chunk : stderrDecoder.decode(chunk, { stream: true }));
+			}))
+		});
+		const ambient = yield* Console.Console;
+		const show = (args) => args.map((arg) => typeof arg === "string" ? arg : String(arg)).join(" ");
+		const toStdout = (...args) => {
+			consoleLog.push(show(args));
+		};
+		const toStderr = (...args) => {
+			stderr.push(`${show(args)}\n`);
+		};
+		const captured = {
+			...ambient,
+			log: toStdout,
+			info: toStdout,
+			debug: toStdout,
+			error: toStderr,
+			warn: toStderr
+		};
+		const provided = options.captureLogs === false ? server.pipe(Layer.provide(stdio)) : server.pipe(Layer.provide(stdio), Layer.provide(Layer.succeed(Console.Console, captured)));
+		const route = (line) => {
+			const parsed = parseFrame(line);
+			if (!isJsonRpcMessage(parsed)) return strictStdout ? Effect.asVoid(Deferred.die(corrupt, /* @__PURE__ */ new Error(`stdout carried a line that is not JSON-RPC: ${ToolFailure.truncate(line)}`))) : Effect.void;
+			if (isResponse(parsed)) {
+				const key = requestKey(parsed.id);
+				const waiter = waiters.get(key);
+				if (waiter !== void 0) {
+					waiters.delete(key);
+					return Effect.asVoid(Deferred.succeed(waiter, parsed));
+				}
+			}
+			return Effect.asVoid(Queue.offer(inbound, parsed));
+		};
+		yield* Stream.fromQueue(stdout).pipe(Stream.map((chunk) => typeof chunk === "string" ? chunk : stdoutDecoder.decode(chunk, { stream: true })), Stream.splitLines, Stream.runForEach((line) => line.length === 0 ? Effect.void : route(line)), Effect.forkScoped);
+		yield* Effect.flatMap(Effect.scope, (scope) => Layer.buildWithMemoMap(provided, Layer.makeMemoMapUnsafe(), scope)).pipe(Effect.andThen(Deferred.succeed(ready, void 0)), Effect.andThen(Effect.never), Effect.scoped, Effect.onExit((exit) => Effect.andThen(Exit.isFailure(exit) ? Deferred.failCause(ready, exit.cause) : Effect.void, Deferred.fail(stopped, new McpTestFailure({
+			reason: "ServerStopped",
+			message: "the server stopped before it responded"
+		})))), Effect.forkScoped);
+		yield* Deferred.await(ready);
+		const stopAware = (wait) => Effect.raceAllFirst([
+			wait,
+			Deferred.await(stopped),
+			Deferred.await(corrupt)
+		]);
+		const awaitResponse = (waiter) => Effect.suspend(() => Deferred.isDoneUnsafe(waiter) ? Deferred.await(waiter) : stopAware(Deferred.await(waiter)));
+		const stateful = !isStateless(protocol);
+		let initializeSent = false;
+		const sendRaw = (message) => Effect.suspend(() => {
+			if (isJsonRpcMessage(message) && message.method === "initialize") initializeSent = true;
+			return Effect.asVoid(Queue.offer(stdin, encoder.encode(`${JSON.stringify(message)}\n`)));
+		});
+		const startRequest = (method, params) => Effect.gen(function* () {
+			if (stateful && !initializeSent && method !== "initialize") return yield* new McpTestFailure({
+				reason: "NotInitialized",
+				message: `${method} was not sent: call initialize first on stateful protocol ${protocol.protocolVersion}`
+			});
+			const id = nextId++;
+			const waiter = yield* Deferred.make();
+			waiters.set(requestKey(id), waiter);
+			yield* sendRaw(frame(protocol, clientInfo, method, params, id));
+			return {
+				id,
+				response: awaitResponse(waiter)
+			};
+		});
+		const request = (method, params) => Effect.flatMap(startRequest(method, params), (started) => started.response);
+		const notify = (method, params) => sendRaw(frame(protocol, clientInfo, method, params));
+		const discover = request("server/discover", {});
+		const initialize = isStateless(protocol) ? discover : Effect.gen(function* () {
+			const response = yield* request("initialize", initializeParams(protocol, clientInfo));
+			yield* notify("notifications/initialized");
+			return response;
+		});
+		const listTools = Effect.flatMap(request("tools/list"), (response) => response.error === void 0 ? Effect.succeed(response.result.tools) : Effect.fail(new McpTestFailure({
+			reason: "ErrorResponse",
+			message: `tools/list failed: ${ToolFailure.truncate(JSON.stringify(response.error))}`
+		})));
+		const listResources = Effect.flatMap(request("resources/list"), (response) => response.error === void 0 ? Effect.succeed(response.result.resources) : Effect.fail(new McpTestFailure({
+			reason: "ErrorResponse",
+			message: `resources/list failed: ${ToolFailure.truncate(JSON.stringify(response.error))}`
+		})));
+		const awaitOutboundMethod = (method) => Effect.suspend(() => {
+			const index = retained.findIndex((message) => message.method === method);
+			if (index !== -1) return Effect.succeed(retained.splice(index, 1)[0]);
+			return stopAware(Effect.gen(function* () {
+				while (true) {
+					const message = yield* Queue.take(inbound);
+					if (message.method === method) return message;
+					retained.push(message);
+				}
+			}));
+		});
+		return new McpHarness({
+			protocol,
+			initialize,
+			discover,
+			request,
+			startRequest,
+			notify,
+			callTool: (name, args) => request("tools/call", {
+				name,
+				arguments: args ?? {}
+			}),
+			listTools,
+			listResources,
+			readResource: (uri) => request("resources/read", { uri }),
+			sendRaw,
+			awaitOutboundMethod,
+			stderrSoFar: Effect.sync(() => stderr.join("")),
+			consoleLogSoFar: Effect.sync(() => [...consoleLog]),
+			close: Effect.asVoid(Queue.end(stdin))
+		});
+	});
+};
+
+//#endregion
+export { McpHarness };

package/McpProbe.js

@@ -0,0 +1,81 @@
+import { ToolFailure } from "./ToolFailure.js";
+import { DEFAULT_CLIENT_INFO, STDERR_HINT, frame, initializeParams, isJsonRpcMessage, isResponse, isStateless, parseFrame } from "./internal/wire.js";
+import { McpTestFailure } from "./McpTestFailure.js";
+import { McpProcess } from "./McpProcess.js";
+import { Effect } from "effect";
+import { McpProtocol } from "effect/unstable/ai";
+
+//#region src/McpProbe.ts
+/**
+* The smallest proof that an installed MCP bin boots: one initialize, a clean
+* close, and exit 0.
+*
+* @remarks
+* Stdin stays open until the id-1 response has arrived. Closing it right
+* after writing, as every hand-rolled smoke test did, makes an Effect server
+* drop the in-flight response and exit 0, so a slow boot reads as a pass with
+* no response. The caller asserts `response.error === undefined`, `stderr` is
+* empty and `exitCode` is 0; this is the MCP half of a packed-install proof.
+* Checking stderr and the exit code alone passes a server that answers
+* the handshake with a JSON-RPC error, exits 0 and writes nothing.
+*
+* - Any stdout line that is not JSON-RPC fails with `NotJsonRpc`, naming the
+*   line: a server that logs to stdout corrupts the wire, so the probe fails
+*   rather than skipping the line.
+* - A child that exits before responding fails with `StreamEnded`, and the
+*   message carries its exit code and stderr.
+* - A child that ignores stdin EOF never exits, and the probe waits for it.
+*   Wrap the probe in `Effect.timeout`.
+*
+* @public
+*/
+var McpProbe = class {
+	constructor() {}
+	/**
+	* Spawn `command`, send one `initialize` (or `server/discover` on a
+	* stateless revision) as id 1, wait for its response, close stdin, and
+	* collect stdout, stderr and the exit code.
+	*/
+	static initialize = (command, options = {}) => Effect.scoped(Effect.gen(function* () {
+		const child = yield* McpProcess.spawn(command);
+		const protocol = options.protocol ?? McpProtocol.v2025_11_25;
+		const stateless = isStateless(protocol);
+		yield* child.send(frame(protocol, DEFAULT_CLIENT_INFO, stateless ? "server/discover" : "initialize", stateless ? {} : initializeParams(protocol, DEFAULT_CLIENT_INFO), 1));
+		const stdout = [];
+		const read = Effect.gen(function* () {
+			const line = yield* child.nextLine;
+			stdout.push(line);
+			const message = parseFrame(line);
+			if (!isJsonRpcMessage(message)) return yield* new McpTestFailure({
+				reason: "NotJsonRpc",
+				message: `stdout carried a line that is not JSON-RPC: ${ToolFailure.truncate(line)}`
+			});
+			return message;
+		});
+		const diagnose = (failure) => failure.reason !== "StreamEnded" ? Effect.fail(failure) : Effect.gen(function* () {
+			const code = yield* child.exitCode;
+			const stderr = yield* child.stderrFinal;
+			return yield* new McpTestFailure({
+				reason: "StreamEnded",
+				message: `${failure.message.replace(STDERR_HINT, "")}; the child exited with code ${code}; stderr: ${stderr === "" ? "(empty)" : ToolFailure.truncate(stderr)}`
+			});
+		});
+		let response;
+		while (response === void 0) {
+			const message = yield* Effect.catch(read, diagnose);
+			if (isResponse(message) && message.id === 1) response = message;
+		}
+		yield* child.closeStdin;
+		const exitCode = yield* child.exitCode;
+		while (true) if (!(yield* Effect.catch(Effect.map(read, () => true), (failure) => failure.reason === "StreamEnded" ? Effect.succeed(false) : Effect.fail(failure)))) break;
+		return {
+			response,
+			stdout,
+			stderr: yield* child.stderrFinal,
+			exitCode
+		};
+	}));
+};
+
+//#endregion
+export { McpProbe };

package/McpProcess.js

@@ -0,0 +1,135 @@
+import { ToolFailure } from "./ToolFailure.js";
+import { DEFAULT_CLIENT_INFO, STDERR_HINT, frame, initializeParams, isJsonRpcMessage, isResponse, isStateless, parseFrame } from "./internal/wire.js";
+import { McpTestFailure } from "./McpTestFailure.js";
+import { Deferred, Effect, Queue, Ref, Stream } from "effect";
+import { McpProtocol } from "effect/unstable/ai";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+//#region src/McpProcess.ts
+/**
+* A spawned MCP server bin a test writes to while it runs.
+*
+* @remarks
+* Build the command in the test file with `execPath` and an explicit `env`:
+* `ChildProcess.make(process.execPath, [bin], { env })`.
+*
+* - `nextLine` fails with `StreamEnded` when stdout ends, so a child that
+*   exits early fails the test instead of hanging it.
+* - `send` writes one JSON-encoded line; `sendRaw` writes a string or bytes
+*   exactly as given, for a malformed frame or one frame split across
+*   writes, even mid-character.
+* - `readUntilResponse` reads past interleaved notifications, such as
+*   `list_changed`, to the matching id and returns what it saw.
+* - `closeStdin` is `Queue.end`, never `Queue.shutdown`, so every frame
+*   already sent is delivered before stdin closes.
+* - A request in flight when stdin closes is dropped by an Effect server:
+*   read its response first.
+*
+* @public
+*/
+var McpProcess = class McpProcess {
+	/**
+	* Write one JSON-encoded, newline-framed message to the child's stdin.
+	*
+	* @remarks
+	* Never fails. A frame sent after `closeStdin` is dropped, and a write the
+	* child can no longer receive fails the stdin pump instead; the next
+	* `StreamEnded` message names that failure.
+	*/
+	send;
+	/**
+	* Write `text` to the child's stdin exactly as given: a string as UTF-8,
+	* bytes unchanged, with no JSON encoding and no newline added.
+	*
+	* @remarks
+	* For frames `send` cannot produce: a line that is not JSON, a blank line,
+	* or one frame split across several writes, including mid-character by
+	* passing bytes. Include the `\n` yourself.
+	* Never fails, on the same terms as `send`.
+	*/
+	sendRaw;
+	/** The next non-empty stdout line; fails with `StreamEnded` once stdout ends. */
+	nextLine;
+	/** Read JSON-RPC lines up to and including the response with this id. */
+	readUntilResponse;
+	/** `initialize` (id 1) then `notifications/initialized`, or `server/discover` (id 1) on a stateless revision. Use ids of 2 or more for your own requests. */
+	handshake;
+	/** End stdin after every frame already sent. */
+	closeStdin;
+	/** Wait for the child to exit. */
+	exitCode;
+	/** Everything written to stderr so far. */
+	stderrSoFar;
+	/** Everything written to stderr, once stderr has ended. Waits for the child to exit. */
+	stderrFinal;
+	constructor(parts) {
+		this.send = parts.send;
+		this.sendRaw = parts.sendRaw;
+		this.nextLine = parts.nextLine;
+		this.readUntilResponse = parts.readUntilResponse;
+		this.handshake = parts.handshake;
+		this.closeStdin = parts.closeStdin;
+		this.exitCode = parts.exitCode;
+		this.stderrSoFar = parts.stderrSoFar;
+		this.stderrFinal = parts.stderrFinal;
+	}
+	/** Spawn `command` for the life of the current scope. */
+	static spawn = (command) => Effect.gen(function* () {
+		const handle = yield* (yield* ChildProcessSpawner.ChildProcessSpawner).spawn(command);
+		const encoder = new TextEncoder();
+		const stdin = yield* Queue.unbounded();
+		const stdinFailure = yield* Ref.make(void 0);
+		yield* Stream.run(Stream.fromQueue(stdin), handle.stdin).pipe(Effect.catch((error) => Ref.set(stdinFailure, error.message)), Effect.forkScoped);
+		const lines = yield* Queue.unbounded();
+		yield* Stream.splitLines(Stream.decodeText(handle.stdout)).pipe(Stream.runForEach((line) => line.length === 0 ? Effect.void : Effect.asVoid(Queue.offer(lines, line))), Effect.ensuring(Queue.end(lines)), Effect.forkScoped);
+		const stderr = yield* Ref.make("");
+		const stderrDone = yield* Deferred.make();
+		yield* Stream.decodeText(handle.stderr).pipe(Stream.runForEach((text) => Ref.update(stderr, (sofar) => sofar + text)), Effect.ensuring(Deferred.succeed(stderrDone, void 0)), Effect.forkScoped);
+		const nextLine = Queue.take(lines).pipe(Effect.catch(() => Effect.flatMap(Ref.get(stdinFailure), (pump) => Effect.fail(new McpTestFailure({
+			reason: "StreamEnded",
+			message: `the server's stdout ended before the expected line${STDERR_HINT}${pump === void 0 ? "" : `; stdin pump failed: ${ToolFailure.truncate(pump)}`}`
+		})))));
+		const readUntilResponse = (id) => Effect.gen(function* () {
+			const seen = [];
+			while (true) {
+				const line = yield* nextLine;
+				const message = parseFrame(line);
+				if (!isJsonRpcMessage(message)) return yield* new McpTestFailure({
+					reason: "NotJsonRpc",
+					message: `stdout carried a line that is not JSON-RPC: ${ToolFailure.truncate(line)}`
+				});
+				seen.push(message);
+				if (isResponse(message) && message.id === id) return {
+					response: message,
+					seen
+				};
+			}
+		});
+		const sendRaw = (text) => Effect.asVoid(Queue.offer(stdin, typeof text === "string" ? encoder.encode(text) : text));
+		const send = (message) => sendRaw(`${JSON.stringify(message)}\n`);
+		const handshake = (protocol = McpProtocol.v2025_11_25) => Effect.gen(function* () {
+			if (isStateless(protocol)) {
+				yield* send(frame(protocol, DEFAULT_CLIENT_INFO, "server/discover", {}, 1));
+				return (yield* readUntilResponse(1)).response;
+			}
+			yield* send(frame(protocol, DEFAULT_CLIENT_INFO, "initialize", initializeParams(protocol, DEFAULT_CLIENT_INFO), 1));
+			const { response } = yield* readUntilResponse(1);
+			yield* send(frame(protocol, DEFAULT_CLIENT_INFO, "notifications/initialized", void 0));
+			return response;
+		});
+		return new McpProcess({
+			send,
+			sendRaw,
+			nextLine,
+			readUntilResponse,
+			handshake,
+			closeStdin: Effect.asVoid(Queue.end(stdin)),
+			exitCode: Effect.map(handle.exitCode, (code) => Number(code)),
+			stderrSoFar: Ref.get(stderr),
+			stderrFinal: Effect.andThen(Deferred.await(stderrDone), Ref.get(stderr))
+		});
+	});
+};
+
+//#endregion
+export { McpProcess };

package/McpStdio.js

@@ -0,0 +1,143 @@
+import { LaunchFailed } from "./internal/LaunchFailed.js";
+import { makeGuardedStdio } from "./internal/StdinFrames.js";
+import { Cause, Effect, Exit, Layer, References, Runtime } from "effect";
+import { McpProtocol, McpServer } from "effect/unstable/ai";
+
+//#region src/McpStdio.ts
+/**
+* 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
+*/
+var McpStdio = class McpStdio {
+	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 protocols = [
+		McpProtocol.v2026_07_28,
+		McpProtocol.v2025_11_25,
+		McpProtocol.v2025_06_18
+	];
+	/**
+	* `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 layer = (options) => McpServer.layerStdio({
+		name: options.name,
+		version: options.version,
+		instructions: options.instructions,
+		description: options.description,
+		protocols: options.protocols ?? McpStdio.protocols
+	}).pipe(Layer.provide(makeGuardedStdio()), Layer.provideMerge(Layer.succeed(References.LogToStderr, true)), Layer.orDie);
+	/**
+	* `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 launch = (layer) => Layer.launch(layer).pipe(Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause) ? Effect.failCause(cause) : Effect.logError(cause).pipe(Effect.andThen(Effect.fail(new LaunchFailed(Runtime.getErrorExitCode(Cause.squash(cause))))))), Effect.provideService(References.LogToStderr, true));
+	/**
+	* 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 teardown = (exit, onExit) => Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause) ? onExit(0) : Runtime.defaultTeardown(exit, onExit);
+};
+
+//#endregion
+export { McpStdio };

package/McpTestFailure.js

@@ -0,0 +1,43 @@
+import { Schema } from "effect";
+
+//#region src/McpTestFailure.ts
+/**
+* Why an MCP test client could not produce what was asked of it.
+*
+* @remarks
+* Each reason is raised by a specific client, and not every client raises
+* every reason:
+*
+* - `StreamEnded` (`McpProcess`, `McpProbe`): the spawned child's stdout
+*   ended first, because the child exited. `McpProbe` folds the exit code
+*   and stderr into the message.
+* - `NotJsonRpc` (`McpProcess.readUntilResponse`, `McpProbe`): a spawned
+*   child's stdout line was not a JSON-RPC frame. `McpHarness` never raises
+*   it: under `strictStdout` a non-JSON-RPC line DIES the pending wait as a
+*   defect instead, so assert it with `Effect.exit` and `Cause.hasDies`,
+*   not `catchTag`.
+* - `ServerStopped` (`McpHarness`): the in-process server stopped, usually
+*   because stdin closed while the request was in flight.
+* - `NotInitialized` (`McpHarness`): a request other than `initialize` was
+*   made on a stateful revision before `initialize` was sent. The request
+*   is never written; the server would only have refused it with an opaque
+*   `Invalid request metadata`.
+* - `ErrorResponse` (`McpHarness.listTools`): the server answered with a
+*   JSON-RPC error where a result was required. Every other request method
+*   returns the whole response, error included, as data.
+*
+* @public
+*/
+var McpTestFailure = class extends Schema.TaggedError()("McpTestFailure", {
+	reason: Schema.Literals([
+		"StreamEnded",
+		"ServerStopped",
+		"NotJsonRpc",
+		"NotInitialized",
+		"ErrorResponse"
+	]),
+	message: Schema.String
+}) {};
+
+//#endregion
+export { McpTestFailure };