@effected/mcp 0.1.0

package/internal/StdinFrames.js

@@ -0,0 +1,201 @@
+import { Effect, Layer, Stdio, Stream } from "effect";
+import { McpSchema } from "effect/unstable/ai";
+
+//#region src/internal/StdinFrames.ts
+/**
+* The line-length cap core's stdio NDJSON decoder applies, in the same unit
+* (UTF-16 code units of the decoded text) and with the same predicate
+* (`length > cap`). The guard answers a longer line itself, so no line core
+* would reject ever reaches core.
+*
+* @internal
+*/
+const MAX_FRAME_LENGTH = 16777216;
+/**
+* The JSON-RPC 2.0 answer to a frame that is not JSON, newline-framed. The id
+* is `null` because no id can be read from an unparseable frame.
+*
+* @internal
+*/
+const PARSE_ERROR_FRAME = `${JSON.stringify({
+	jsonrpc: "2.0",
+	id: null,
+	error: {
+		code: McpSchema.PARSE_ERROR_CODE,
+		message: "Parse error"
+	}
+})}\n`;
+/**
+* The JSON-RPC 2.0 answer to a frame that is JSON but no JSON-RPC message
+* core can handle, newline-framed. The id is `null` because such a frame
+* carries no usable id.
+*
+* @internal
+*/
+const INVALID_REQUEST_FRAME = `${JSON.stringify({
+	jsonrpc: "2.0",
+	id: null,
+	error: {
+		code: McpSchema.INVALID_REQUEST_ERROR_CODE,
+		message: "Invalid Request"
+	}
+})}\n`;
+/** JSON's insignificant whitespace, minus the newline that ends the line. */
+const BLANK = /^[ \t\r]*$/;
+const isNullish = (value) => value === null || value === void 0;
+/**
+* The guard's answer to one non-blank line within the cap, or `undefined` to
+* forward it to core.
+*
+* @remarks
+* A frame that parses is forwarded unless core would throw on it or ignore
+* it without a reply, which JSON-RPC 2.0 calls an Invalid Request:
+*
+* - 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 with a `method` that is not a string and no usable `id`: core
+*   throws on it, dropping the rest of its chunk (with an `id`, core answers
+*   `-32601` itself);
+* - an object with neither `method` nor `id`: every JSON-RPC request carries a
+*   `method` and every response an `id`, so it is neither, and core ignores it
+*   as a response to nothing.
+*
+* Arrays are forwarded: core answers a batch `-32600` itself. So is any object
+* with an `id` and no `method`, which is a response; JSON-RPC never answers a
+* response.
+*/
+const answerFor = (line) => {
+	let value;
+	try {
+		value = JSON.parse(line);
+	} catch {
+		return PARSE_ERROR_FRAME;
+	}
+	if (typeof value !== "object" || value === null) return INVALID_REQUEST_FRAME;
+	if (Array.isArray(value)) return void 0;
+	const message = value;
+	if (Object.hasOwn(message, "method")) return typeof message.method !== "string" && isNullish(message.id) ? INVALID_REQUEST_FRAME : void 0;
+	return Object.hasOwn(message, "id") ? void 0 : INVALID_REQUEST_FRAME;
+};
+/**
+* A stateful step over stdin chunks that forwards only complete lines core's
+* decoder will parse and answer, each with its newline.
+*
+* @remarks
+* Core's stdio decoder parses each line inside its read loop. A line that is
+* not JSON throws before the decoder advances past it, so the line stays at
+* the head of its buffer and every later chunk throws on it again: the server
+* never reads another frame. A line that is JSON but no JSON-RPC message core
+* can handle either throws inside the decoder, dropping the frames after it in
+* the same chunk, or is ignored without a reply. The guard frames stdin
+* exactly as core does and answers such a line itself, returning
+* {@link PARSE_ERROR_FRAME} or {@link INVALID_REQUEST_FRAME} for the caller
+* to write.
+*
+* - Decoding mirrors core: one streaming UTF-8 decoder, so a character split
+*   across chunks decodes whole, a byte-order mark is stripped only at the
+*   start of the stream, and a U+FEFF opening any later line stays in that
+*   line, where `JSON.parse` rejects it as core's would.
+* - A partial line is held until its newline arrives.
+* - A line of JSON whitespace only is not a frame: dropped, not answered.
+* - A line that is JSON is answered `-32600` when it is not an object or an
+*   array, when its `method` is not a string and it has no usable `id`, or
+*   when it has neither `method` nor `id`; everything else goes to core.
+* - A line longer than `maxFrameLength` code units is answered once, as soon
+*   as the held part exceeds the cap, and the rest of it is discarded up to
+*   its newline. Nothing is held beyond the cap.
+*
+* Create one guard per stdin: its state must outlive core re-subscribing to
+* stdin after any failure in its read loop, or a held partial line is lost.
+*
+* @internal
+*/
+const makeFrameGuard = (maxFrameLength = MAX_FRAME_LENGTH) => {
+	const decoder = new TextDecoder();
+	const encoder = new TextEncoder();
+	let pending = "";
+	let discarding = false;
+	return (chunk) => {
+		const text = decoder.decode(chunk, { stream: true });
+		let forward = "";
+		const replies = [];
+		let start = 0;
+		if (discarding) {
+			const newline = text.indexOf("\n");
+			if (newline === -1) return {
+				forward: void 0,
+				replies
+			};
+			discarding = false;
+			start = newline + 1;
+		}
+		let newline = text.indexOf("\n", start);
+		while (newline !== -1) {
+			const line = pending + text.slice(start, newline);
+			pending = "";
+			start = newline + 1;
+			newline = text.indexOf("\n", start);
+			if (line.length > maxFrameLength) {
+				replies.push(PARSE_ERROR_FRAME);
+				continue;
+			}
+			if (BLANK.test(line)) continue;
+			const answer = answerFor(line);
+			if (answer === void 0) forward += `${line}\n`;
+			else replies.push(answer);
+		}
+		pending += text.slice(start);
+		if (pending.length > maxFrameLength) {
+			pending = "";
+			discarding = true;
+			replies.push(PARSE_ERROR_FRAME);
+		}
+		return {
+			forward: forward === "" ? void 0 : encoder.encode(forward),
+			replies
+		};
+	};
+};
+/**
+* `Stdio` whose `stdin` carries only lines core's decoder will parse and
+* answer, writing the guard's reply to every other line on `stdout`: one
+* write per chunk, replies in stdin order. Everything else is the ambient
+* `Stdio`.
+*
+* @remarks
+* One guard per call, shared by every subscription to the returned `stdin`,
+* because core re-subscribes after a failure and builds its own decoder once.
+*
+* @internal
+*/
+const guardStdin = (stdio) => {
+	const step = makeFrameGuard();
+	return Stdio.make({
+		args: stdio.args,
+		stdinIsTerminal: stdio.stdinIsTerminal,
+		stdoutIsTerminal: stdio.stdoutIsTerminal,
+		stdout: (options) => stdio.stdout(options),
+		stderr: (options) => stdio.stderr(options),
+		stdin: stdio.stdin.pipe(Stream.mapEffect((chunk) => {
+			const { forward, replies } = step(chunk);
+			return replies.length === 0 ? Effect.succeed(forward) : Stream.run(Stream.make(replies.join("")), stdio.stdout()).pipe(Effect.as(forward));
+		}), Stream.filter((chunk) => chunk !== void 0))
+	});
+};
+/**
+* A layer replacing the ambient `Stdio` with {@link guardStdin}'s, for one
+* server layer only.
+*
+* @remarks
+* A function, never a module constant: layers memoize by reference, so one
+* shared constant is built once per graph, and a second server in that graph
+* would read the first server's guarded stdin. Each call mints a fresh layer;
+* `McpStdio.layer` calls it once per server.
+*
+* @internal
+*/
+const makeGuardedStdio = () => Layer.effect(Stdio.Stdio, Effect.map(Stdio.Stdio, guardStdin));
+
+//#endregion
+export { INVALID_REQUEST_FRAME, MAX_FRAME_LENGTH, PARSE_ERROR_FRAME, guardStdin, makeFrameGuard, makeGuardedStdio };

package/internal/wire.js

@@ -0,0 +1,66 @@
+import { Result } from "effect";
+
+//#region src/internal/wire.ts
+/** @internal */
+const DEFAULT_CLIENT_INFO = {
+	name: "effected-mcp-testing",
+	version: "0.0.0"
+};
+const isRecord = (u) => typeof u === "object" && u !== null && !Array.isArray(u);
+/**
+* The pointer `McpProcess` appends to a `StreamEnded` message. `McpProbe`
+* strips it: the probe folds stderr into its own message, so the pointer is
+* stale there.
+*
+* @internal
+*/
+const STDERR_HINT = "; read stderrFinal for why";
+/** @internal */
+const parseFrame = (line) => Result.getOrUndefined(Result.try(() => JSON.parse(line)));
+/** @internal */
+const isJsonRpcMessage = (u) => isRecord(u) && u.jsonrpc === "2.0";
+/** @internal */
+const isResponse = (message) => (typeof message.id === "string" || typeof message.id === "number") && message.method === void 0;
+/** @internal */
+const requestKey = (id) => `${typeof id}:${id}`;
+/** @internal */
+const isStateless = (protocol) => protocol.runtime._tag === "Stateless";
+/**
+* A request (with `id`) or notification frame. On the stateless revision every
+* frame carries the protocol fields under `params._meta`, with any `_meta`
+* the caller passed spread over them, so the caller wins. That matches core's
+* own harness (`McpStdioHarness.ts`, `withRequestMetadata`) and lets a test
+* send a deliberately wrong revision.
+*
+* @internal
+*/
+const frame = (protocol, clientInfo, method, params, id) => {
+	const withMeta = () => {
+		const base = isRecord(params) ? params : {};
+		const caller = isRecord(base._meta) ? base._meta : {};
+		return {
+			...base,
+			_meta: {
+				"io.modelcontextprotocol/protocolVersion": protocol.protocolVersion,
+				"io.modelcontextprotocol/clientCapabilities": {},
+				"io.modelcontextprotocol/clientInfo": clientInfo,
+				...caller
+			}
+		};
+	};
+	return {
+		jsonrpc: "2.0",
+		...id === void 0 ? {} : { id },
+		method,
+		...isStateless(protocol) ? { params: withMeta() } : params === void 0 ? {} : { params }
+	};
+};
+/** @internal */
+const initializeParams = (protocol, clientInfo) => ({
+	protocolVersion: protocol.protocolVersion,
+	capabilities: {},
+	clientInfo
+});
+
+//#endregion
+export { DEFAULT_CLIENT_INFO, STDERR_HINT, frame, initializeParams, isJsonRpcMessage, isResponse, isStateless, parseFrame, requestKey };

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@effected/mcp",
+	"version": "0.1.0",
+	"private": false,
+	"description": "The boundary layer of an effect/unstable/ai MCP server: stdio wiring that keeps stdout the wire, tool-failure shaping, strict-input walkers, and test clients",
+	"keywords": [
+		"effect",
+		"mcp",
+		"model-context-protocol",
+		"stdio",
+		"json-rpc",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/mcp#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/mcp"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./testing": {
+			"types": "./testing.d.ts",
+			"import": "./testing.js",
+			"default": "./testing.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"@effected/engine": "^0.1.0",
+		"effect": "4.0.0-rc.117"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/testing.d.ts

@@ -0,0 +1,365 @@
+import { Effect, JsonSchema, Layer, PlatformError, Schema, Scope, Stdio } from "effect";
+import { McpProtocol } from "effect/unstable/ai";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+//#region src/McpTestFailure.d.ts
+declare const McpTestFailure_base: Schema.Class<McpTestFailure, Schema.TaggedStruct<"McpTestFailure", {
+  readonly reason: Schema.Literals<readonly ["StreamEnded", "ServerStopped", "NotJsonRpc", "NotInitialized", "ErrorResponse"]>;
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+export declare class McpTestFailure extends McpTestFailure_base {}
+//#endregion
+//#region src/McpWire.d.ts
+/**
+ * One JSON-RPC 2.0 frame as an MCP test client sees it.
+ *
+ * @public
+ */
+interface JsonRpcMessage {
+  readonly jsonrpc: "2.0";
+  readonly id?: string | number | null | undefined;
+  readonly method?: string | undefined;
+  readonly params?: unknown;
+  readonly result?: unknown;
+  readonly error?: unknown;
+}
+/**
+ * One entry of a `tools/list` result.
+ *
+ * @public
+ */
+interface ServedTool {
+  readonly name: string;
+  readonly title?: string | undefined;
+  readonly description?: string | undefined;
+  readonly inputSchema: JsonSchema.JsonSchema;
+  readonly outputSchema?: JsonSchema.JsonSchema | undefined;
+  readonly annotations?: {
+    readonly [key: string]: unknown;
+  } | undefined;
+  readonly _meta?: {
+    readonly [key: string]: unknown;
+  } | undefined;
+}
+/**
+ * One entry of a `resources/list` result.
+ *
+ * @public
+ */
+interface ServedResource {
+  readonly uri: string;
+  readonly name: string;
+  readonly title?: string | undefined;
+  readonly description?: string | undefined;
+  readonly mimeType?: string | undefined;
+  readonly annotations?: {
+    readonly [key: string]: unknown;
+  } | undefined;
+  readonly size?: number | undefined;
+  readonly _meta?: {
+    readonly [key: string]: unknown;
+  } | undefined;
+}
+//#endregion
+//#region src/McpHarness.d.ts
+/**
+ * Options for {@link McpHarness.make}.
+ *
+ * @public
+ */
+interface McpHarnessOptions {
+  /** The revision this client speaks. Defaults to `McpProtocol.v2025_11_25`; a stateless adapter switches to `server/discover` and per-request `_meta`. */
+  readonly protocol?: McpProtocol.ProtocolAdapter | undefined;
+  /** The `clientInfo` sent in `initialize` and in stateless `_meta`. */
+  readonly clientInfo?: {
+    readonly name: string;
+    readonly version: string;
+  } | undefined;
+  /** Capture the server's console so logs are asserted, not printed. Defaults to `true`. */
+  readonly captureLogs?: boolean | undefined;
+  /** Treat any stdout line that is not JSON-RPC as a defect. Defaults to `true`. */
+  readonly strictStdout?: boolean | undefined;
+}
+/**
+ * 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
+ */
+export declare class McpHarness {
+  /** The revision this client speaks. */
+  readonly protocol: McpProtocol.ProtocolAdapter;
+  /** `initialize` then `notifications/initialized`; `server/discover` on a stateless revision. Call it first on a stateful revision. */
+  readonly initialize: Effect.Effect<JsonRpcMessage, McpTestFailure>;
+  /** `server/discover`. */
+  readonly discover: Effect.Effect<JsonRpcMessage, McpTestFailure>;
+  /** Send a request and wait for its response. */
+  readonly request: (method: string, params?: unknown) => Effect.Effect<JsonRpcMessage, McpTestFailure>;
+  /** Send a request now; wait for its response later. Fails with `NotInitialized`, sending nothing, on a stateful revision before `initialize`. */
+  readonly startRequest: (method: string, params?: unknown) => Effect.Effect<{
+    readonly id: number;
+    readonly response: Effect.Effect<JsonRpcMessage, McpTestFailure>;
+  }, McpTestFailure>;
+  /** Send a notification. */
+  readonly notify: (method: string, params?: unknown) => Effect.Effect<void>;
+  /** `tools/call`, returning the whole response: a JSON-RPC error is data here. */
+  readonly callTool: (name: string, args?: unknown) => Effect.Effect<JsonRpcMessage, McpTestFailure>;
+  /** `tools/list`'s tools; a JSON-RPC error fails with `ErrorResponse`. */
+  readonly listTools: Effect.Effect<ReadonlyArray<ServedTool>, McpTestFailure>;
+  /** `resources/list`'s resources; a JSON-RPC error fails with `ErrorResponse`. */
+  readonly listResources: Effect.Effect<ReadonlyArray<ServedResource>, McpTestFailure>;
+  /** `resources/read`, returning the whole response. */
+  readonly readResource: (uri: string) => Effect.Effect<JsonRpcMessage, McpTestFailure>;
+  /** Write any value as one newline-framed line. Never gated; a raw `initialize` counts as sent. */
+  readonly sendRaw: (message: unknown) => Effect.Effect<void>;
+  /** The next server-initiated frame with this method, skipping and keeping others; fails with `ServerStopped` once the server stops. */
+  readonly awaitOutboundMethod: (method: string) => Effect.Effect<JsonRpcMessage, McpTestFailure>;
+  /** Everything written to stderr, plus every captured log line. */
+  readonly stderrSoFar: Effect.Effect<string>;
+  /** Every captured `console.log`, `info` or `debug` call. */
+  readonly consoleLogSoFar: Effect.Effect<ReadonlyArray<string>>;
+  /** End stdin, as a client disconnecting does. */
+  readonly close: Effect.Effect<void>;
+  private constructor();
+  /** Build `server` over queue-backed stdio and return a client for it; fails with the layer's own error if it cannot build. */
+  static readonly make: <ROut, E, R>(server: Layer.Layer<ROut, E, R>, options?: McpHarnessOptions) => Effect.Effect<McpHarness, E, Scope.Scope | Exclude<R, Stdio.Stdio>>;
+}
+//#endregion
+//#region src/McpProbe.d.ts
+/**
+ * Options for {@link McpProbe.initialize}.
+ *
+ * @public
+ */
+interface McpProbeOptions {
+  /** Defaults to `McpProtocol.v2025_11_25`; a stateless adapter probes with `server/discover`. */
+  readonly protocol?: McpProtocol.ProtocolAdapter | undefined;
+}
+/**
+ * What {@link McpProbe.initialize} observed.
+ *
+ * @public
+ */
+interface McpProbeResult {
+  /** The id-1 response. A refused handshake is still a response: assert `response.error === undefined`. */
+  readonly response: JsonRpcMessage;
+  /** Every raw stdout line, in order. */
+  readonly stdout: ReadonlyArray<string>;
+  /** Everything the child wrote to stderr; a clean boot leaves it empty. */
+  readonly stderr: string;
+  /** The child's exit code after stdin closed; a clean boot exits 0. */
+  readonly exitCode: number;
+}
+/**
+ * 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
+ */
+export declare class McpProbe {
+  private 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 readonly initialize: (command: ChildProcess.Command, options?: McpProbeOptions) => Effect.Effect<McpProbeResult, McpTestFailure | PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner>;
+}
+//#endregion
+//#region src/McpProcess.d.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
+ */
+export declare 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.
+   */
+  readonly send: (message: unknown) => Effect.Effect<void>;
+  /**
+   * 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`.
+   */
+  readonly sendRaw: (text: string | Uint8Array) => Effect.Effect<void>;
+  /** The next non-empty stdout line; fails with `StreamEnded` once stdout ends. */
+  readonly nextLine: Effect.Effect<string, McpTestFailure>;
+  /** Read JSON-RPC lines up to and including the response with this id. */
+  readonly readUntilResponse: (id: string | number) => Effect.Effect<{
+    readonly response: JsonRpcMessage;
+    readonly seen: ReadonlyArray<JsonRpcMessage>;
+  }, McpTestFailure>;
+  /** `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. */
+  readonly handshake: (protocol?: McpProtocol.ProtocolAdapter) => Effect.Effect<JsonRpcMessage, McpTestFailure>;
+  /** End stdin after every frame already sent. */
+  readonly closeStdin: Effect.Effect<void>;
+  /** Wait for the child to exit. */
+  readonly exitCode: Effect.Effect<number, PlatformError.PlatformError>;
+  /** Everything written to stderr so far. */
+  readonly stderrSoFar: Effect.Effect<string>;
+  /** Everything written to stderr, once stderr has ended. Waits for the child to exit. */
+  readonly stderrFinal: Effect.Effect<string>;
+  private constructor();
+  /** Spawn `command` for the life of the current scope. */
+  static readonly spawn: (command: ChildProcess.Command) => Effect.Effect<McpProcess, PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner | Scope.Scope>;
+}
+//#endregion
+//#region src/McpToolAudit.d.ts
+/**
+ * The policy {@link McpToolAudit.check} enforces.
+ *
+ * @public
+ */
+interface McpToolAuditPolicy {
+  /** `"closed"`: every object node rejects unknown keys. `"open"`: none with properties does. `"any"`: not checked. */
+  readonly input: "open" | "closed" | "any";
+  /** Every tool must carry a non-empty `title`, top-level or in `annotations.title`. */
+  readonly requireTitle?: boolean | undefined;
+  /** Every tool must serve an `outputSchema`. The stateful revisions drop a non-object one, so check the revision you serve. */
+  readonly requireOutputSchema?: boolean | undefined;
+  /** A served `outputSchema` must be rooted at `type: "object"`. Defaults to `true` (D10). */
+  readonly objectRootedOutput?: boolean | undefined;
+  /** The longest `description` allowed, in UTF-16 code units; a missing description counts as 0. */
+  readonly maxDescription?: number | undefined;
+  /** All four MCP annotation hints must be present as booleans. */
+  readonly requireHints?: boolean | undefined;
+}
+/**
+ * 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
+ */
+export declare class McpToolAudit {
+  private 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 readonly check: (tools: ReadonlyArray<ServedTool>, policy: McpToolAuditPolicy) => ReadonlyArray<string>;
+}
+//#endregion
+export type { JsonRpcMessage, McpHarnessOptions, McpProbeOptions, McpProbeResult, McpToolAuditPolicy, ServedResource, ServedTool };
+//# sourceMappingURL=testing.d.ts.map