@effected/mcp-kit 0.0.0-stage → 0.14.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/McpGuard.js

@@ -0,0 +1,81 @@
+import { ProcessGuard } from "@effected/kit/guard";
+
+// src/McpGuard.ts
+/**
+* Crash guards for an MCP server process, installed before the server's
+* module graph is loaded. Imported from `@effected/mcp-kit/guard`.
+*
+* @remarks
+* {@link McpGuard.run} is `ProcessGuard.run` from `@effected/kit/guard`
+* with an MCP launch in its `load`: it registers `uncaughtException` and
+* `unhandledRejection` listeners on `host`, then awaits `load()`, then
+* launches the server with `McpStdio.launch` and `McpStdio.teardown` under
+* the `runMain` it returned. A server on another transport (an LSP over
+* `vscode-languageserver`, say) uses `ProcessGuard.run` directly and calls
+* its `markConnected` itself. This entrypoint statically imports only
+* `@effected/kit/guard`, which imports nothing: it loads `effect` and the
+* stdio wiring only after the guards are listening, so a throw while any of
+* it evaluates is still reported on stderr.
+*
+* - "Connected" means the whole server layer has built, so stdin is being
+*   read. That is before any client sends `initialize`.
+* - `injectCrash` drives either half of the policy from a test, before
+*   `load()` or once connected; unset, it does nothing.
+* - A `load()` that rejects is reported as `startup failed` and exits 1
+*   whatever the policy. Left to a log-only rejection listener, it would
+*   let the event loop drain and exit 0 with no server.
+* - Installing an `unhandledRejection` listener switches off Node's default
+*   of throwing on one, so `"log"` really does keep the process running.
+* - An exit from a guard skips Effect's finalizers and the teardown.
+* - Keeping on serving after a crash works because the platform `runMain`
+*   holds the process open while the server fiber lives.
+* - A layer that fails to build is still reported by `McpStdio.launch`.
+*
+* @example
+* ```ts
+* import { McpGuard } from "@effected/mcp-kit/guard";
+*
+* await McpGuard.run({
+*   label: "my-server",
+*   host: process,
+*   policy: { onUncaught: "exitBeforeConnect", onRejection: "log" },
+*   load: async () => {
+*     const { NodeRuntime } = await import("@effect/platform-node");
+*     const { Main } = await import("./server.js");
+*     return { layer: Main, runMain: NodeRuntime.runMain };
+*   },
+* });
+* ```
+*
+* @public
+*/
+var McpGuard = class {
+	constructor() {}
+	/**
+	* Parse a test-only crash-injection setting into {@link McpGuardRunOptions.injectCrash}: `<at>:<kind>`, where `at`
+	* is `"load"` or `"connected"` and `kind` is `"uncaughtException"` or `"unhandledRejection"`. Anything else, or no
+	* value, is `undefined`. The same grammar as `ProcessGuard.parseInjectCrash` from `@effected/kit/guard`, which
+	* this is, so an MCP launcher need not import the engine guard for it.
+	*
+	* @example
+	* ```ts
+	* McpGuard.parseInjectCrash("load:uncaughtException"); // => { at: "load", kind: "uncaughtException" }
+	* ```
+	*/
+	static parseInjectCrash = ProcessGuard.parseInjectCrash;
+	/** Install the guards, load the server, and launch it. Resolves once the server is launched. */
+	static run = (options) => ProcessGuard.run({
+		label: options.label,
+		host: options.host,
+		policy: options.policy,
+		injectCrash: options.injectCrash,
+		load: async (guard) => {
+			const server = await options.load();
+			if (server.format !== void 0) guard.useFormat(server.format);
+			const { launchGuarded } = await import("./internal/guardLaunch.js");
+			launchGuarded(server, guard.markConnected);
+		}
+	});
+};
+
+export { McpGuard };

package/McpHarness.js

@@ -0,0 +1,357 @@
+import { DEFAULT_CLIENT_INFO, frame, initializeParams, isJsonRpcMessage, isResponse, isStateless, parseFrame, requestKey } from "./internal/wire.js";
+import { McpTestFailure } from "./McpTestFailure.js";
+import { ToolFailure } from "./ToolFailure.js";
+import { Console, Deferred, Effect, Exit, Fiber, Layer, Queue, Sink, Stdio, Stream } from "effect";
+import { McpProtocol } from "effect/ai";
+import { ErrorText } from "@effected/kit";
+
+// src/McpHarness.ts
+/** The generic tag `Object.prototype.toString` answers with: a value with no string form of its own. */
+const GENERIC_STRING = /^\[object [^\]]*\]$/;
+/**
+* One captured console argument as text, as close to what the console would show as a runtime-free rendering gets,
+* and never throwing.
+*
+* @remarks
+* A harness records what the server would have printed, so the record must not lose what the console shows. Hence
+* the order: a value's own string form first (`String(error)` is `Error: boom`, where `ErrorText.describe` would keep
+* only `boom`, and it is the same for any object carrying a `message`), then JSON for an array or a plain object,
+* whose string form is `1,2` or `[object Object]`. `ErrorText.describe` is the last resort for a value whose string
+* form throws and which has no JSON: an object with no prototype has no `toString`, and `String` throws on it inside
+* the server's own console call.
+*/
+const showArg = (arg) => {
+	if (typeof arg === "string") return arg;
+	if (typeof arg !== "object" || arg === null) return ErrorText.describe(arg);
+	try {
+		if (!Array.isArray(arg)) {
+			const text = String(arg);
+			if (!GENERIC_STRING.test(text)) return text;
+		}
+	} catch {}
+	try {
+		const json = JSON.stringify(arg);
+		if (json !== void 0) return json;
+	} catch {}
+	return ErrorText.describe(arg);
+};
+/**
+* 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.
+* - Every response wait and `awaitOutboundMethod` fails with `ServerStopped`
+*   when the server stops, and dies when `strictStdout` sees a line that is
+*   not JSON-RPC. `stop` stops the server at once; `close` ends stdin and lets
+*   in-flight requests answer first, so only `stop` releases a wait on a
+*   request that never completes.
+* - 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. `ping` is the exception: the server answers it `{}` before
+*   initialization, so it is written. Every other request before
+*   `initialize` fails with `NotInitialized` and is never written: the
+*   server would only answer an opaque refusal,
+*   `-32602 Invalid request metadata` when a stateless adapter is listed
+*   first (as in `McpStdio.protocols`), or `-32603 Internal error` when
+*   only stateful revisions are served.
+*
+* @example
+* ```ts
+* import { McpHarness } from "@effected/mcp-kit/testing";
+* import { Effect } from "effect";
+*
+* // `ServerLayer` is the server's layer, built without its own `Stdio`.
+* const program = Effect.gen(function* () {
+* 	const harness = yield* McpHarness.make(ServerLayer);
+* 	yield* harness.initialize;
+* 	const tools = yield* harness.listTools;
+* 	return tools.map((tool) => tool.name);
+* }).pipe(Effect.scoped);
+* ```
+*
+* Services the test also seeds go in `options.services`, built once. End the
+* session with `harness.close` (the server answers what is in flight, then
+* stops) or, when a request may never complete, `harness.stop` (the server is
+* interrupted at once):
+*
+* ```ts
+* import { McpHarness } from "@effected/mcp-kit/testing";
+* import { Context, Effect } from "effect";
+*
+* // `Database` is a service the server's tools need, and the test seeds it.
+* const program = Effect.gen(function* () {
+* 	const database = yield* makeDatabase;
+* 	const harness = yield* McpHarness.make(ServerLayer, { services: Context.make(Database, database) });
+* 	yield* harness.initialize;
+* 	yield* harness.stop;
+* }).pipe(Effect.scoped);
+* ```
+*
+* @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;
+	/**
+	* `initialize` asking for `protocolVersion` instead of the harness's own
+	* revision, then `notifications/initialized` only when the response
+	* carries no error. Returns the whole response: assert the negotiated
+	* `result.protocolVersion`, or the JSON-RPC `error`.
+	*
+	* @remarks
+	* It moves between stateful revisions only. A stateful server never
+	* refuses a version: it counter-offers its latest stateful revision, so
+	* asking for an unknown one, or for the stateless `2026-07-28`, comes back
+	* as `2025-11-25`. On a harness made with a stateless revision the server
+	* does not serve `initialize` at all, and the response is a JSON-RPC
+	* `-32601` "Method not found" error, with no `notifications/initialized`
+	* sent after it.
+	*/
+	initializeWith;
+	/** `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` (`ping` excepted). */
+	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;
+	/** Every frame written to the server's stdin so far, in order, as the JSON-parsed bytes written (a snapshot the caller's later mutations cannot reach): requests, notifications and `sendRaw` values. */
+	sentSoFar;
+	/** Everything written to stderr, plus every captured log line. */
+	stderrSoFar;
+	/**
+	* Every captured `console.log`, `info` or `debug` call, its arguments joined with a space, each rendered close to
+	* what the console would show: a string as itself, a value with its own string form as that form (an `Error` as
+	* `Error: boom`, a number, a date), an array or a plain object as JSON (`{"message":"x"}`, not just `x`).
+	*
+	* @remarks
+	* Rendering never throws inside the server's own call. A value whose string form throws (an object with no
+	* prototype, a throwing `toString`) and has no JSON falls back to `ErrorText.describe` from `@effected/kit`.
+	*/
+	consoleLogSoFar;
+	/**
+	* End stdin, as a client disconnecting does. The server drains first:
+	* requests already in flight still answer, and the server stops once they
+	* have, so a wait on a request that never completes keeps waiting. Use
+	* {@link McpHarness.stop} to end the server regardless.
+	*/
+	close;
+	/**
+	* Interrupt the server without draining, as a client killing the process
+	* does: every pending response wait and `awaitOutboundMethod` fails with
+	* `ServerStopped`.
+	*/
+	stop;
+	constructor(parts) {
+		this.protocol = parts.protocol;
+		this.initialize = parts.initialize;
+		this.initializeWith = parts.initializeWith;
+		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.sentSoFar = parts.sentSoFar;
+		this.stderrSoFar = parts.stderrSoFar;
+		this.consoleLogSoFar = parts.consoleLogSoFar;
+		this.close = parts.close;
+		this.stop = parts.stop;
+	}
+	/** 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(showArg).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 withLogs = options.captureLogs === false ? server.pipe(Layer.provide(stdio)) : server.pipe(Layer.provide(stdio), Layer.provide(Layer.succeed(Console.Console, captured)));
+		const provided = options.services === void 0 ? withLogs : withLogs.pipe(Layer.provide(Layer.succeedContext(options.services)));
+		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));
+		};
+		const router = 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);
+		const serverFiber = 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, Queue.end(stdout).pipe(Effect.andThen(Fiber.await(router)), Effect.andThen(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 sent = [];
+		const sendRaw = (message) => Effect.suspend(() => {
+			const line = JSON.stringify(message);
+			const written = line === void 0 ? void 0 : JSON.parse(line);
+			sent.push(written);
+			if (isJsonRpcMessage(written) && written.method === "initialize") initializeSent = true;
+			return Effect.asVoid(Queue.offer(stdin, encoder.encode(`${line}\n`)));
+		});
+		const startRequest = (method, params) => Effect.gen(function* () {
+			if (stateful && !initializeSent && method !== "initialize" && method !== "ping") 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 initializeWith = (protocolVersion) => Effect.gen(function* () {
+			const response = yield* request("initialize", {
+				...initializeParams(protocol, clientInfo),
+				protocolVersion
+			});
+			if (response.error === void 0) 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,
+			initializeWith,
+			discover,
+			request,
+			startRequest,
+			notify,
+			callTool: (name, args) => request("tools/call", {
+				name,
+				arguments: args ?? {}
+			}),
+			listTools,
+			listResources,
+			readResource: (uri) => request("resources/read", { uri }),
+			sendRaw,
+			awaitOutboundMethod,
+			sentSoFar: Effect.sync(() => [...sent]),
+			stderrSoFar: Effect.sync(() => stderr.join("")),
+			consoleLogSoFar: Effect.sync(() => [...consoleLog]),
+			close: Effect.asVoid(Queue.end(stdin)),
+			stop: Fiber.interrupt(serverFiber)
+		});
+	});
+};
+
+export { McpHarness };

package/McpProbe.js

@@ -0,0 +1,94 @@
+import { DEFAULT_CLIENT_INFO, STDERR_HINT, frame, initializeParams, isJsonRpcMessage, isResponse, isStateless, parseFrame } from "./internal/wire.js";
+import { McpProcess } from "./McpProcess.js";
+import { McpTestFailure } from "./McpTestFailure.js";
+import { ToolFailure } from "./ToolFailure.js";
+import { Effect } from "effect";
+import { McpProtocol } from "effect/ai";
+
+// 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 proves nothing against a server that stops at stdin EOF
+* without answering what is in flight: it replies nothing and exits 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`.
+*
+* @example
+* ```ts
+* import { McpProbe } from "@effected/mcp-kit/testing";
+* import { Effect } from "effect";
+* import { ChildProcess } from "effect/process";
+*
+* const program = Effect.gen(function* () {
+* 	const probe = yield* McpProbe.initialize(ChildProcess.make(process.execPath, ["./bin/server.js"]));
+* 	// A clean boot: no JSON-RPC error, empty stderr, exit code 0.
+* 	return probe.response.error === undefined && probe.stderr === "" && probe.exitCode === 0;
+* });
+* // Requires a `ChildProcessSpawner` from the platform layer.
+* ```
+*
+* @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
+		};
+	}));
+};
+
+export { McpProbe };