@effected/mcp 0.1.1 → 0.3.0

package/internal/StdinFrames.js

@@ -1,5 +1,5 @@
 import { Effect, Layer, Stdio, Stream } from "effect";
-import { McpSchema } from "effect/unstable/ai";
+import { McpSchema } from "effect/ai";
 
 //#region src/internal/StdinFrames.ts
 /**
@@ -40,27 +40,59 @@ const INVALID_REQUEST_FRAME = `${JSON.stringify({
 		message: "Invalid Request"
 	}
 })}\n`;
+/**
+* The JSON-RPC 2.0 answer to a request whose method is one of Effect's
+* internal `@effect/rpc/` control messages, newline-framed, echoing the
+* request's `id`.
+*
+* @internal
+*/
+const methodNotFoundFrame = (id) => `${JSON.stringify({
+	jsonrpc: "2.0",
+	id,
+	error: {
+		code: McpSchema.METHOD_NOT_FOUND_ERROR_CODE,
+		message: "Method not found"
+	}
+})}\n`;
+/**
+* The method prefix core's JSON-RPC decoder reserves for its own RPC control
+* messages (`Eof`, `Interrupt`, `Ack`, …).
+*
+* @internal
+*/
+const RPC_CONTROL_PREFIX = "@effect/rpc/";
 /** JSON's insignificant whitespace, minus the newline that ends the line. */
 const BLANK = /^[ \t\r]*$/;
 const isNullish = (value) => value === null || value === void 0;
+/** {@link answerFor}'s verdict for a line that is neither forwarded nor answered. */
+const DROP = "";
 /**
-* The guard's answer to one non-blank line within the cap, or `undefined` to
-* forward it to core.
+* The guard's answer to one non-blank line within the cap, `DROP` to swallow
+* it silently, 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);
+* A frame that parses is forwarded unless core would skip it without a
+* reply, where JSON-RPC 2.0 requires an Invalid Request:
+*
+* - a value that is neither an object nor an array;
+* - an object with a `method` that is not a string and no usable `id` (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.
 *
+* A frame whose `method` starts with `@effect/rpc/` never reaches core. Core's
+* JSON-RPC decoder reads such a frame with no `id` as one of its own RPC
+* control messages, so `{"jsonrpc":"2.0","method":"@effect/rpc/Eof"}` from
+* any client silently stops the server (Effect-TS/effect#8499). A
+* notification of that shape is dropped; a request, which carries an `id`,
+* is answered `-32601` Method not found, as no MCP method has that prefix.
+* Remove this branch once Effect-TS/effect#8499 is fixed in the installed
+* `effect` (the open PR #8509 proposes the fix) and a probe shows an
+* unguarded server still answering a ping sent after an `@effect/rpc/Eof`
+* notification.
+*
 * 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.
@@ -75,7 +107,10 @@ const answerFor = (line) => {
 	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;
+	if (Object.hasOwn(message, "method")) {
+		if (typeof message.method === "string" && message.method.startsWith("@effect/rpc/")) return isNullish(message.id) ? DROP : methodNotFoundFrame(message.id);
+		return typeof message.method !== "string" && isNullish(message.id) ? INVALID_REQUEST_FRAME : void 0;
+	}
 	return Object.hasOwn(message, "id") ? void 0 : INVALID_REQUEST_FRAME;
 };
 /**
@@ -83,15 +118,15 @@ const answerFor = (line) => {
 * 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
+* Core's stdio decoder skips a line it cannot use and keeps serving
+* (Effect-TS/effect PR #8541): a line that is not JSON, a JSON value that is
+* not an object, or an object that is no JSON-RPC message is dropped without
+* a reply, and a line past its buffer cap is logged on stderr and dropped.
+* JSON-RPC 2.0 requires a reply to each of them, so 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.
+* to write. It also keeps `@effect/rpc/` control methods away from core (see
+* `answerFor`), which would otherwise let one client line stop the server.
 *
 * - 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
@@ -101,7 +136,10 @@ const answerFor = (line) => {
 * - 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.
+*   when it has neither `method` nor `id`.
+* - A line whose `method` starts with `@effect/rpc/` is answered `-32601`
+*   when it carries an `id` and dropped when it does not.
+* - 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.
@@ -143,7 +181,7 @@ const makeFrameGuard = (maxFrameLength = MAX_FRAME_LENGTH) => {
 			if (BLANK.test(line)) continue;
 			const answer = answerFor(line);
 			if (answer === void 0) forward += `${line}\n`;
-			else replies.push(answer);
+			else if (answer !== DROP) replies.push(answer);
 		}
 		pending += text.slice(start);
 		if (pending.length > maxFrameLength) {
@@ -198,4 +236,4 @@ const guardStdin = (stdio) => {
 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 };
+export { INVALID_REQUEST_FRAME, MAX_FRAME_LENGTH, PARSE_ERROR_FRAME, RPC_CONTROL_PREFIX, guardStdin, makeFrameGuard, makeGuardedStdio, methodNotFoundFrame };

package/internal/guardLaunch.js

@@ -0,0 +1,14 @@
+import { McpStdio } from "../McpStdio.js";
+import { Effect } from "effect";
+
+//#region src/internal/guardLaunch.ts
+/**
+* The server half of `McpGuard.run`, reached only through a dynamic import so
+* the guard module itself evaluates nothing but its own code.
+*
+* @internal
+*/
+const launchGuarded = (server, onReady) => server.runMain(McpStdio.launch(server.layer, { onReady: Effect.sync(onReady) }), { teardown: McpStdio.teardown });
+
+//#endregion
+export { launchGuarded };

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "@effected/mcp",
-	"version": "0.1.1",
+	"version": "0.3.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",
+	"description": "The boundary layer of an effect/ai MCP server: stdio wiring that keeps stdout the wire, tool-failure shaping, strict-input walkers, and test clients",
 	"keywords": [
 		"effect",
 		"mcp",
@@ -34,6 +34,11 @@
 			"import": "./index.js",
 			"default": "./index.js"
 		},
+		"./guard": {
+			"types": "./guard.d.ts",
+			"import": "./guard.js",
+			"default": "./guard.js"
+		},
 		"./testing": {
 			"types": "./testing.d.ts",
 			"import": "./testing.js",
@@ -42,8 +47,8 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/engine": "^0.1.0",
-		"effect": "4.0.0-rc.117"
+		"@effected/engine": "^0.2.0",
+		"effect": "4.0.0-rc.118"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/testing.d.ts

@@ -1,6 +1,6 @@
 import { Effect, JsonSchema, Layer, PlatformError, Schema, Scope, Stdio } from "effect";
-import { McpProtocol } from "effect/unstable/ai";
-import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { McpProtocol } from "effect/ai";
+import { ChildProcess, ChildProcessSpawner } from "effect/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"]>;
@@ -23,8 +23,8 @@ declare const McpTestFailure_base: Schema.Class<McpTestFailure, Schema.TaggedStr
  *   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.
@@ -140,11 +140,13 @@ interface McpHarnessOptions {
  *   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
  */
@@ -153,11 +155,27 @@ export declare class McpHarness {
   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>;
+  /**
+   * `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.
+   */
+  readonly initializeWith: (protocolVersion: string) => 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`. */
+  /** Send a request now; wait for its response later. Fails with `NotInitialized`, sending nothing, on a stateful revision before `initialize` (`ping` excepted). */
   readonly startRequest: (method: string, params?: unknown) => Effect.Effect<{
     readonly id: number;
     readonly response: Effect.Effect<JsonRpcMessage, McpTestFailure>;
@@ -176,6 +194,8 @@ export declare class McpHarness {
   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>;
+  /** 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. */
+  readonly sentSoFar: Effect.Effect<ReadonlyArray<unknown>>;
   /** Everything written to stderr, plus every captured log line. */
   readonly stderrSoFar: Effect.Effect<string>;
   /** Every captured `console.log`, `info` or `debug` call. */
@@ -321,9 +341,21 @@ interface McpToolAuditPolicy {
   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. */
+  /**
+   * Every tool must serve an `outputSchema`. The stateful revisions drop a
+   * non-object one, so check the revision you serve; the violation names
+   * the likely cause, a union success schema, and `ToolOutputSchema.objectRooted`.
+   */
   readonly requireOutputSchema?: boolean | undefined;
-  /** A served `outputSchema` must be rooted at `type: "object"`. Defaults to `true` (D10). */
+  /**
+   * A served `outputSchema` must be rooted at `type: "object"`. Defaults to
+   * `true` (D10). Only the stateless revision serves a non-object root, so
+   * only there does this fire; a union root (`anyOf` or `oneOf`) names
+   * `ToolOutputSchema.objectRooted` as the fix for a union whose members are
+   * all objects (a union with a primitive member needs an object envelope
+   * instead). On a stateful revision the
+   * same schema is dropped, and `requireOutputSchema` reports it instead.
+   */
   readonly objectRootedOutput?: boolean | undefined;
   /** The longest `description` allowed, in UTF-16 code units; a missing description counts as 0. */
   readonly maxDescription?: number | undefined;