@effected/mcp 0.3.0 → 0.4.0

package/McpHarness.js

@@ -46,6 +46,20 @@ import { McpProtocol } from "effect/ai";
 *   first (as in `McpStdio.protocols`), or `-32603 Internal error` when
 *   only stateful revisions are served.
 *
+* @example
+* ```ts
+* import { McpHarness } from "@effected/mcp/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);
+* ```
+*
 * @public
 */
 var McpHarness = class McpHarness {

package/McpProbe.js

@@ -12,8 +12,7 @@ import { McpProtocol } from "effect/ai";
 *
 * @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
+* after writing 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
@@ -27,6 +26,20 @@ import { McpProtocol } from "effect/ai";
 * - 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/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 {

package/McpProcess.js

@@ -25,6 +25,23 @@ import { ChildProcessSpawner } from "effect/process";
 * - A request in flight when stdin closes is dropped by an Effect server:
 *   read its response first.
 *
+* @example
+* ```ts
+* import { McpProcess } from "@effected/mcp/testing";
+* import { Effect } from "effect";
+* import { ChildProcess } from "effect/process";
+*
+* const program = Effect.gen(function* () {
+* 	const child = yield* McpProcess.spawn(ChildProcess.make(process.execPath, ["./bin/server.js"]));
+* 	yield* child.handshake();
+* 	yield* child.send({ jsonrpc: "2.0", id: 2, method: "tools/list" });
+* 	const { response } = yield* child.readUntilResponse(2);
+* 	yield* child.closeStdin;
+* 	return response;
+* }).pipe(Effect.scoped);
+* // Requires a `ChildProcessSpawner` from the platform layer.
+* ```
+*
 * @public
 */
 var McpProcess = class McpProcess {

package/McpStdio.js

@@ -39,10 +39,9 @@ var McpStdio = class McpStdio {
 	* first, then the two newest stateful ones.
 	*
 	* @remarks
-	* Real clients open with either handshake: Claude Code 2.1.281 was
-	* measured opening a stdio server with the stateless `server/discover`,
-	* while most other shipping clients still send `initialize`. The order
-	* is load-bearing:
+	* Real clients open with either handshake: some (Claude Code, for one)
+	* open a stdio server with the stateless `server/discover`, while others
+	* still send `initialize`. The order is load-bearing:
 	*
 	* - Stateless first: a request with no session and no `_meta` falls to
 	*   `protocols[0]`.

package/McpTestFailure.js

@@ -30,6 +30,7 @@ import { Schema } from "effect";
 * @public
 */
 var McpTestFailure = class extends Schema.TaggedError()("McpTestFailure", {
+	/** Which failure occurred; see the list above for which client raises which. */
 	reason: Schema.Literals([
 		"StreamEnded",
 		"ServerStopped",
@@ -37,6 +38,7 @@ var McpTestFailure = class extends Schema.TaggedError()("McpTestFailure", {
 		"NotInitialized",
 		"ErrorResponse"
 	]),
+	/** A human-readable description of what went wrong. */
 	message: Schema.String
 }) {};
 

package/McpToolkit.js

@@ -185,6 +185,11 @@ var McpToolkit = class {
 	*
 	* @example
 	* ```ts
+	* import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
+	* import { Schema } from "effect";
+	* import { Tool } from "effect/ai";
+	*
+	* // `AddNote`, `ListNotes`, `Added`, `Listed` are object schemas; `Kit` is a Toolkit that includes `Note`.
 	* const Note = McpToolkit.unionTool("note", {
 	*   parameters: Schema.Union([AddNote, ListNotes]),
 	*   success: ToolOutputSchema.objectRooted(Schema.Union([Added, Listed])),

package/README.md

@@ -7,10 +7,10 @@ The boundary layer of an `effect/ai` MCP server: stdio wiring that keeps stdout
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered

package/ToolFailure.js

@@ -26,6 +26,9 @@ const isHighSurrogate = (code) => code >= 55296 && code <= 56319;
 *
 * @example
 * ```ts
+* import { ToolFailure } from "@effected/mcp";
+* import { Schema } from "effect";
+*
 * class NotFound extends Schema.TaggedError<NotFound>()("NotFound", { ...ToolFailure.fields, id: Schema.String }) {}
 * const remediation = { hint: "List the ids first.", suggestedTool: "list_things" }
 * new NotFound({ id, remediation, message: ToolFailure.message(`No thing "${ToolFailure.truncate(id)}".`, remediation) })

package/ToolRefusal.js

@@ -14,11 +14,14 @@ import { Schema } from "effect";
 * {@link ToolRefusal.refuse}; its message already carries the remediation,
 * because a declared `Error` failure sends `message` and nothing else.
 *
-* Audit every throw path when porting a tool: any failure left undeclared
-* loses its message on the wire, however carefully it was worded.
+* Audit every throw path of a tool: any failure left undeclared loses its
+* message on the wire, however carefully it was worded.
 *
 * @example
 * ```ts
+* import { ToolFailure, ToolRefusal } from "@effected/mcp";
+* import { Tool } from "effect/ai";
+*
 * const Lookup = Tool.make("lookup", { parameters, success, failure: ToolRefusal })
 * // in the handler:
 * return yield* ToolRefusal.refuse(`No run "${ToolFailure.truncate(id)}".`, { hint: "List runs first.", suggestedTool: "list_runs" })

package/index.d.ts

@@ -74,10 +74,9 @@ export declare class McpStdio {
    * first, then the two newest stateful ones.
    *
    * @remarks
-   * Real clients open with either handshake: Claude Code 2.1.281 was
-   * measured opening a stdio server with the stateless `server/discover`,
-   * while most other shipping clients still send `initialize`. The order
-   * is load-bearing:
+   * Real clients open with either handshake: some (Claude Code, for one)
+   * open a stdio server with the stateless `server/discover`, while others
+   * still send `initialize`. The order is load-bearing:
    *
    * - Stateless first: a request with no session and no `_meta` falls to
    *   `protocols[0]`.
@@ -429,6 +428,11 @@ export declare class McpToolkit {
    *
    * @example
    * ```ts
+   * import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
+   * import { Schema } from "effect";
+   * import { Tool } from "effect/ai";
+   *
+   * // `AddNote`, `ListNotes`, `Added`, `Listed` are object schemas; `Kit` is a Toolkit that includes `Note`.
    * const Note = McpToolkit.unionTool("note", {
    *   parameters: Schema.Union([AddNote, ListNotes]),
    *   success: ToolOutputSchema.objectRooted(Schema.Union([Added, Listed])),
@@ -488,6 +492,9 @@ export declare class McpToolkit {
  *
  * @example
  * ```ts
+ * import { ToolFailure } from "@effected/mcp";
+ * import { Schema } from "effect";
+ *
  * class NotFound extends Schema.TaggedError<NotFound>()("NotFound", { ...ToolFailure.fields, id: Schema.String }) {}
  * const remediation = { hint: "List the ids first.", suggestedTool: "list_things" }
  * new NotFound({ id, remediation, message: ToolFailure.message(`No thing "${ToolFailure.truncate(id)}".`, remediation) })
@@ -594,11 +601,14 @@ declare const ToolRefusal_base: Schema.Class<ToolRefusal, Schema.TaggedStruct<"T
  * {@link ToolRefusal.refuse}; its message already carries the remediation,
  * because a declared `Error` failure sends `message` and nothing else.
  *
- * Audit every throw path when porting a tool: any failure left undeclared
- * loses its message on the wire, however carefully it was worded.
+ * Audit every throw path of a tool: any failure left undeclared loses its
+ * message on the wire, however carefully it was worded.
  *
  * @example
  * ```ts
+ * import { ToolFailure, ToolRefusal } from "@effected/mcp";
+ * import { Tool } from "effect/ai";
+ *
  * const Lookup = Tool.make("lookup", { parameters, success, failure: ToolRefusal })
  * // in the handler:
  * return yield* ToolRefusal.refuse(`No run "${ToolFailure.truncate(id)}".`, { hint: "List runs first.", suggestedTool: "list_runs" })

package/internal/LaunchFailed.js

@@ -7,15 +7,27 @@ import { Runtime } from "effect";
 * 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 {
-	[Runtime.errorReported] = false;
-	[Runtime.errorExitCode];
+	#code;
 	constructor(code) {
 		super(`the MCP server failed to launch (exit ${code})`);
 		this.name = "LaunchFailed";
-		this[Runtime.errorExitCode] = code;
+		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;
 	}
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/mcp",
-	"version": "0.3.0",
+	"version": "0.4.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": [
@@ -47,8 +47,8 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/engine": "^0.2.0",
-		"effect": "4.0.0-rc.118"
+		"@effected/engine": "^0.3.0",
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/testing.d.ts

@@ -3,7 +3,9 @@ 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", {
+  /** Which failure occurred; see the list above for which client raises which. */
   readonly reason: Schema.Literals<readonly ["StreamEnded", "ServerStopped", "NotJsonRpc", "NotInitialized", "ErrorResponse"]>;
+  /** A human-readable description of what went wrong. */
   readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /**
@@ -148,6 +150,20 @@ interface McpHarnessOptions {
  *   first (as in `McpStdio.protocols`), or `-32603 Internal error` when
  *   only stateful revisions are served.
  *
+ * @example
+ * ```ts
+ * import { McpHarness } from "@effected/mcp/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);
+ * ```
+ *
  * @public
  */
 export declare class McpHarness {
@@ -238,8 +254,7 @@ interface McpProbeResult {
  *
  * @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
+ * after writing 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
@@ -253,6 +268,20 @@ interface McpProbeResult {
  * - 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/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
  */
 export declare class McpProbe {
@@ -285,6 +314,23 @@ export declare class McpProbe {
  * - A request in flight when stdin closes is dropped by an Effect server:
  *   read its response first.
  *
+ * @example
+ * ```ts
+ * import { McpProcess } from "@effected/mcp/testing";
+ * import { Effect } from "effect";
+ * import { ChildProcess } from "effect/process";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const child = yield* McpProcess.spawn(ChildProcess.make(process.execPath, ["./bin/server.js"]));
+ * 	yield* child.handshake();
+ * 	yield* child.send({ jsonrpc: "2.0", id: 2, method: "tools/list" });
+ * 	const { response } = yield* child.readUntilResponse(2);
+ * 	yield* child.closeStdin;
+ * 	return response;
+ * }).pipe(Effect.scoped);
+ * // Requires a `ChildProcessSpawner` from the platform layer.
+ * ```
+ *
  * @public
  */
 export declare class McpProcess {
@@ -349,7 +395,7 @@ interface McpToolAuditPolicy {
   readonly requireOutputSchema?: boolean | undefined;
   /**
    * A served `outputSchema` must be rooted at `type: "object"`. Defaults to
-   * `true` (D10). Only the stateless revision serves a non-object root, so
+   * `true`. 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