@effected/mcp-kit 0.0.0-stage → 0.14.0

package/index.js

@@ -0,0 +1,10 @@
+import { McpStdio } from "./McpStdio.js";
+import { McpToolkit } from "./McpToolkit.js";
+import { ToolFailure } from "./ToolFailure.js";
+import { ToolInputSchema } from "./ToolInputSchema.js";
+import { ToolOutcome } from "./ToolOutcome.js";
+import { ToolOutputSchema } from "./ToolOutputSchema.js";
+import { ToolRefusal } from "./ToolRefusal.js";
+import { ToolReplay } from "./ToolReplay.js";
+
+export { McpStdio, McpToolkit, ToolFailure, ToolInputSchema, ToolOutcome, ToolOutputSchema, ToolRefusal, ToolReplay };

package/internal/LaunchFailed.js

@@ -0,0 +1,34 @@
+import { Runtime } from "effect";
+
+// src/internal/LaunchFailed.ts
+/**
+* The failure `McpStdio.launch` re-raises after reporting a launch failure on
+* stderr itself. `errorReported: false` keeps `runMain` from reporting it a
+* second time — through a logger that writes to stdout — and the original exit
+* code rides along for the teardown.
+*
+* @remarks
+* Both runtime markers are prototype getters rather than own fields, so a JSON
+* or logger dump of the error does not carry them; the code lives in a private
+* field.
+*
+* @internal
+*/
+var LaunchFailed = class extends Error {
+	#code;
+	constructor(code) {
+		super(`the MCP server failed to launch (exit ${code})`);
+		this.name = "LaunchFailed";
+		this.#code = code;
+	}
+	/** Already reported on stderr: `runMain` must not report it again. */
+	get [Runtime.errorReported]() {
+		return false;
+	}
+	/** The exit code the launch failed with. */
+	get [Runtime.errorExitCode]() {
+		return this.#code;
+	}
+};
+
+export { LaunchFailed };

package/internal/StdinFrames.js

@@ -0,0 +1,201 @@
+import { Effect, Layer, Stdio, Stream } from "effect";
+import { McpSchema } from "effect/ai";
+
+// 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 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/` is an ordinary request or
+* notification to core, which serves MCP with Effect's RPC control messages
+* turned off: a notification is ignored and a request answered `-32601`.
+*
+* 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 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.
+*
+* - 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));
+
+export { INVALID_REQUEST_FRAME, MAX_FRAME_LENGTH, PARSE_ERROR_FRAME, guardStdin, makeFrameGuard, makeGuardedStdio };

package/internal/guardLaunch.js

@@ -0,0 +1,13 @@
+import { McpStdio } from "../McpStdio.js";
+import { Effect } from "effect";
+
+// 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 });
+
+export { launchGuarded };

package/internal/wire.js

@@ -0,0 +1,65 @@
+import { Result } from "effect";
+
+// 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
+});
+
+export { DEFAULT_CLIENT_INFO, STDERR_HINT, frame, initializeParams, isJsonRpcMessage, isResponse, isStateless, parseFrame, requestKey };

package/node.d.ts

@@ -0,0 +1,126 @@
+import { Writable } from "node:stream";
+import { Effect } from "effect";
+/**
+ * Anything with a replaceable `write`: a patched stream (Node's
+ * `process.stdout` and `process.stderr`) and a sink captured writes go to (a
+ * Node `Writable`, {@link StdioCapture.nullWritable}, {@link StdioCapture.discard},
+ * {@link StdioCapture.toStderr}).
+ *
+ * @remarks
+ * A sink's `write` receives exactly the arguments the patched stream's
+ * `write` was called with, including any trailing callback, so a sink must
+ * call that callback itself, as a `Writable` does.
+ *
+ * @public
+ */
+interface StdioSink {
+  write(chunk: any, ...rest: Array<any>): boolean;
+}
+/**
+ * The two streams {@link StdioCapture.install} patches. Node's `process`
+ * satisfies it; pass it in from `main.ts`.
+ *
+ * @public
+ */
+interface StdioCaptureHost {
+  readonly stdout: StdioSink;
+  readonly stderr: StdioSink;
+}
+/**
+ * The sinks for one capture. `stderr` passes through to the real stream when
+ * omitted.
+ *
+ * @public
+ */
+interface StdioCaptureOptions {
+  readonly stdout: StdioSink;
+  readonly stderr?: StdioSink | undefined;
+}
+/**
+ * Diverts a host's stdout (and optionally stderr) writes to a sink, for code
+ * running inside one async context only, while every other context keeps
+ * writing to the real streams.
+ *
+ * @remarks
+ * For an MCP server over stdio, stdout is the JSON-RPC wire. A chatty library
+ * run in-process (a test runner, a bundler, a linter) must keep its output off
+ * it while other handlers, and the transport itself, keep writing normally.
+ *
+ * `install` patches the host's `write` methods once, keeping the unbound
+ * originals, and routes every write through an `AsyncLocalStorage`: inside a
+ * {@link StdioCapture.run} or {@link StdioCapture.capture} context a write goes
+ * to that context's sink, and outside it to the original stream.
+ *
+ * An Effect fiber resumes in the async context it suspended in, not the
+ * context of whatever woke it, so a server fiber woken by code inside a
+ * capture (its response written to a queue, say) keeps writing to the wire.
+ *
+ * Two kinds of write escape a capture and reach the original stream:
+ *
+ * - **Writes from a context the capture lost.** Callbacks registered outside the
+ *   capture keep the context they were registered in: native addons, worker
+ *   thread output relayed by the main thread, listeners on a child process's
+ *   pipes attached earlier. On stdout, that is the wire.
+ * - **Fibers started inside the capture keep capturing after it ends.** A fiber
+ *   forked inside it (`Effect.forkDetach`, a memoized layer first built inside
+ *   it, a background fiber a library starts) keeps writing to the sink, even
+ *   after the capture's own work is done.
+ *
+ * @example
+ * ```ts
+ * import { StdioCapture } from "@effected/mcp-kit/node"
+ *
+ * const capture = StdioCapture.install(process)
+ * // in a tool handler: keep the runner's own console output off the wire
+ * const report = yield* runTests(files).pipe(capture.capture({ stdout: capture.toStderr }))
+ * ```
+ *
+ * @public
+ */
+export declare class StdioCapture {
+  /** A sink that writes through the host's original, unpatched stderr: captured output stays visible off the wire. */
+  readonly toStderr: StdioSink;
+  private constructor();
+  /**
+   * Patches `host`'s two streams. Idempotent per stream, across every installed
+   * copy of this package: a stream already patched (through another host
+   * object, or another copy) keeps its one patch and its original `write`.
+   */
+  static readonly install: (host: StdioCaptureHost) => StdioCapture;
+  /**
+   * A write-only sink that drops every write and calls the write's callback.
+   *
+   * @remarks
+   * It is a {@link StdioSink}, not a stream: it has no `on`, `pipe` target
+   * protocol or `setMaxListeners`, so it cannot stand in where a library
+   * expects a `Writable` (a test runner's logger stream that worker output
+   * is piped into, for one). Use {@link StdioCapture.nullWritable} there; it
+   * serves as a capture sink too.
+   */
+  static readonly discard: StdioSink;
+  /**
+   * A new Node `Writable` that drops everything written to it: a real stream,
+   * so it works as a `pipe` target, takes `setMaxListeners`, emits `drain`
+   * and `finish`, and is also a {@link StdioSink} for a capture.
+   *
+   * @remarks
+   * A factory, not a shared value: a stream ends once, and a source piped in
+   * with the default `{ end: true }` ends its destination. Build one per
+   * consumer.
+   */
+  static readonly nullWritable: () => Writable;
+  /**
+   * Runs `evaluate` with its writes captured, for code that is not Effect.
+   * A synchronous throw from `evaluate` rejects the returned promise.
+   */
+  run<A>(options: StdioCaptureOptions, evaluate: () => PromiseLike<A>): Promise<A>;
+  /**
+   * Runs an effect with its writes captured: on its own fiber, started inside
+   * the capture's context, so the context survives every suspension of that
+   * fiber. Interrupting the returned effect interrupts that fiber and waits
+   * for it.
+   */
+  capture(options: StdioCaptureOptions): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}
+export type { StdioCaptureHost, StdioCaptureOptions, StdioSink };
+//# sourceMappingURL=node.d.ts.map

package/node.js

@@ -0,0 +1,3 @@
+import { StdioCapture } from "./StdioCapture.js";
+
+export { StdioCapture };

package/package.json

@@ -1,6 +1,61 @@
 {
-  "name": "@effected/mcp-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@effected/mcp-kit",
+	"version": "0.14.0",
+	"private": false,
+	"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",
+		"model-context-protocol",
+		"stdio",
+		"json-rpc",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/mcp-kit#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/mcp-kit"
+	},
+	"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"
+		},
+		"./guard": {
+			"types": "./guard.d.ts",
+			"import": "./guard.js",
+			"default": "./guard.js"
+		},
+		"./node": {
+			"types": "./node.d.ts",
+			"import": "./node.js",
+			"default": "./node.js"
+		},
+		"./testing": {
+			"types": "./testing.d.ts",
+			"import": "./testing.js",
+			"default": "./testing.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"@effected/kit": "^0.13.0",
+		"effect": "~4.1.0"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}