@effected/mcp 0.1.1 → 0.3.0

package/McpGuard.js

@@ -0,0 +1,121 @@
+//#region src/McpGuard.ts
+const isInjectedKind = (kind) => kind === "uncaughtException" || kind === "unhandledRejection";
+/** Emit one injected crash through the host, to the listeners the guard installed there. */
+const emitInjected = (host, kind) => {
+	const error = /* @__PURE__ */ new Error(`[injected] ${kind}`);
+	if (kind === "uncaughtException") {
+		host.emit("uncaughtException", error, "uncaughtException");
+		return;
+	}
+	const promise = Promise.reject(error);
+	promise.catch(() => void 0);
+	host.emit("unhandledRejection", error, promise);
+};
+const fallbackFormat = (error) => error instanceof Error ? error.stack ?? error.message : String(error);
+/**
+* Crash guards for an MCP server process, installed before the server's
+* module graph is loaded. Imported from `@effected/mcp/guard`.
+*
+* @remarks
+* {@link McpGuard.run} 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.
+* This entrypoint has no static runtime import: 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/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() {}
+	/** Install the guards, load the server, and launch it. Resolves once the server is launched. */
+	static run = async (options) => {
+		const { host, label } = options;
+		const onUncaught = options.policy?.onUncaught ?? "exit";
+		const onRejection = options.policy?.onRejection ?? "exit";
+		let connected = false;
+		let format = fallbackFormat;
+		const describe = (error) => {
+			try {
+				return format(error);
+			} catch {
+				try {
+					return fallbackFormat(error);
+				} catch {
+					return "<unformattable error value>";
+				}
+			}
+		};
+		const exits = (mode) => mode === "exit" || mode === "exitBeforeConnect" && !connected;
+		host.on("uncaughtException", (error, origin) => {
+			host.stderr.write(`${label}: uncaughtException (${origin}): ${describe(error)}\n`);
+			if (exits(onUncaught)) host.exit(1);
+		});
+		host.on("unhandledRejection", (reason) => {
+			host.stderr.write(`${label}: unhandledRejection: ${describe(reason)}\n`);
+			if (exits(onRejection)) host.exit(1);
+		});
+		const inject = options.injectCrash;
+		const injectKind = isInjectedKind(inject?.kind) ? inject.kind : void 0;
+		if (inject?.at === "load" && injectKind !== void 0) await new Promise((resolve, reject) => {
+			setTimeout(() => {
+				try {
+					emitInjected(host, injectKind);
+					resolve();
+				} catch (error) {
+					reject(error);
+				}
+			}, 0);
+		});
+		const onReady = () => {
+			connected = true;
+			if (inject?.at === "connected" && injectKind !== void 0) setTimeout(() => {
+				try {
+					emitInjected(host, injectKind);
+				} catch {}
+			}, 0);
+		};
+		try {
+			const server = await options.load();
+			if (server.format !== void 0) format = server.format;
+			const { launchGuarded } = await import("./internal/guardLaunch.js");
+			launchGuarded(server, onReady);
+		} catch (error) {
+			host.stderr.write(`${label}: startup failed: ${describe(error)}\n`);
+			host.exit(1);
+		}
+	};
+};
+
+//#endregion
+export { McpGuard };

package/McpHarness.js

@@ -2,7 +2,7 @@ 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";
+import { McpProtocol } from "effect/ai";
 
 //#region src/McpHarness.ts
 /**
@@ -38,11 +38,13 @@ import { McpProtocol } from "effect/unstable/ai";
 *   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, `ping` included: 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.
+*   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.
 *
 * @public
 */
@@ -51,11 +53,27 @@ var McpHarness = class McpHarness {
 	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`. */
+	/** 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;
@@ -71,6 +89,8 @@ var McpHarness = class McpHarness {
 	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. */
@@ -80,6 +100,7 @@ var McpHarness = class McpHarness {
 	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;
@@ -90,6 +111,7 @@ var McpHarness = class McpHarness {
 		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;
@@ -164,12 +186,16 @@ var McpHarness = class McpHarness {
 		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(() => {
-			if (isJsonRpcMessage(message) && message.method === "initialize") initializeSent = true;
-			return Effect.asVoid(Queue.offer(stdin, encoder.encode(`${JSON.stringify(message)}\n`)));
+			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") return yield* new McpTestFailure({
+			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}`
 			});
@@ -190,6 +216,14 @@ var McpHarness = class McpHarness {
 			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))}`
@@ -212,6 +246,7 @@ var McpHarness = class McpHarness {
 		return new McpHarness({
 			protocol,
 			initialize,
+			initializeWith,
 			discover,
 			request,
 			startRequest,
@@ -225,6 +260,7 @@ var McpHarness = class McpHarness {
 			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))

package/McpProbe.js

@@ -3,7 +3,7 @@ import { DEFAULT_CLIENT_INFO, STDERR_HINT, frame, initializeParams, isJsonRpcMes
 import { McpTestFailure } from "./McpTestFailure.js";
 import { McpProcess } from "./McpProcess.js";
 import { Effect } from "effect";
-import { McpProtocol } from "effect/unstable/ai";
+import { McpProtocol } from "effect/ai";
 
 //#region src/McpProbe.ts
 /**

package/McpProcess.js

@@ -2,8 +2,8 @@ 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";
+import { McpProtocol } from "effect/ai";
+import { ChildProcessSpawner } from "effect/process";
 
 //#region src/McpProcess.ts
 /**

package/McpStdio.js

@@ -1,7 +1,7 @@
 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";
+import { McpProtocol, McpServer } from "effect/ai";
 
 //#region src/McpStdio.ts
 /**
@@ -68,26 +68,35 @@ var McpStdio = class McpStdio {
 	*
 	* 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.
+	* only at the start of the stream, lines split on `\n`. Core itself skips
+	* a line it cannot use and keeps serving, but sends no reply, where
+	* JSON-RPC 2.0 requires one; the guard supplies it. A line that is not
+	* JSON is answered on stdout with a parse error, code `-32700` and
+	* `id: null`, and never reaches core. 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 (core would
+	* log it on stderr and drop it). 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.
+	* core: a value that is neither an object nor an array, an object whose
+	* `method` is not a string and whose `id` is absent or `null`, and an
+	* object with neither `method` nor `id`, which is neither a request nor a
+	* response.
+	*
+	* A line whose `method` starts with `@effect/rpc/` never reaches core,
+	* whose JSON-RPC decoder would read one without an `id` as its own RPC
+	* control message: `@effect/rpc/Eof` alone silently stops the server
+	* (Effect-TS/effect#8499, open upstream). Such a request is answered
+	* `-32601` Method not found, echoing its `id`; such a notification is
+	* dropped. The guard stops doing this once core no longer treats a
+	* client's `@effect/rpc/` frame as a control message.
+	*
+	* 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
@@ -96,8 +105,12 @@ var McpStdio = class McpStdio {
 	* 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.
+	* new one. The tool registry is shared the same way. Isolate each server
+	* by wrapping its whole bundle (its toolkit layers together with this
+	* layer) in `Layer.fresh`, or with its own `ManagedRuntime`,
+	* `Effect.provide(layer, { local: true })` or its own process. Never put
+	* the `Layer.fresh` boundary between a toolkit and this layer: the server
+	* would serve an empty registry.
 	*
 	* 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
@@ -124,8 +137,11 @@ var McpStdio = class McpStdio {
 	* `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.
+	*
+	* `options.onReady` runs after the layer has built and before the launch
+	* waits forever, as {@link McpLaunchOptions.onReady} describes.
 	*/
-	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));
+	static launch = (layer, options = {}) => (options.onReady === void 0 ? Layer.launch(layer) : Effect.scoped(Layer.build(layer).pipe(Effect.andThen(options.onReady), Effect.andThen(Effect.never)))).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`.

package/McpTestFailure.js

@@ -18,8 +18,8 @@ import { Schema } from "effect";
 *   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
+* - `NotInitialized` (`McpHarness`): a request other than `initialize` or
+*   `ping` was made on a stateful revision before `initialize` was sent. The request
 *   is never written; the server would only have refused it opaquely:
 *   `-32602 Invalid request metadata` when a stateless adapter is listed
 *   first, `-32603 Internal error` when only stateful revisions are served.

package/McpToolAudit.js

@@ -24,10 +24,12 @@ const objectNodes = (schema) => {
 			return acc;
 		}, Object.create(null));
 		const closed = merged.some((part) => part.additionalProperties === false);
+		const droppedKeyCheck = merged.some((part) => isNode(part.additionalProperties) && isNode(part.propertyNames));
 		if (isNode(properties) || merged.some((part) => part.type === "object")) out.push({
 			path,
 			properties,
-			closed
+			closed,
+			droppedKeyCheck
 		});
 		if (isNode(properties)) for (const [key, child] of Object.entries(properties)) visit(child, join(path, key));
 		visit(node.items, join(path, "items"));
@@ -81,15 +83,18 @@ var McpToolAudit = class {
 			};
 			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)) {
+			if (policy.input !== "any") for (const { path, properties, closed, droppedKeyCheck } 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 === "closed" && !closed) report(`input schema is open at ${where}${droppedKeyCheck ? " (a Record whose key check was not served; a key pattern is served closed, as patternProperties, only when its RegExp has the u flag, e.g. Schema.isPattern(/^x-/u))" : ""}`);
 				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")})`);
+			if (policy.requireOutputSchema === true && tool.outputSchema === void 0) report("no outputSchema (a union success schema is dropped on stateful revisions; see ToolOutputSchema.objectRooted)");
+			if ((policy.objectRootedOutput ?? true) && tool.outputSchema !== void 0 && tool.outputSchema.type !== "object") {
+				const union = Array.isArray(tool.outputSchema.anyOf) || Array.isArray(tool.outputSchema.oneOf);
+				report(`outputSchema is not object-rooted (root type: ${String(tool.outputSchema.type ?? "none")})${union ? "; if every union member is an object, wrap the union success schema in ToolOutputSchema.objectRooted" : ""}`);
+			}
 			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) {