@effected/mcp 0.2.0 → 0.4.0

package/testing.d.ts

@@ -1,9 +1,11 @@
 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", {
+  /** 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>;
 /**
@@ -23,8 +25,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 +142,27 @@ 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.
+ *
+ * @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
  */
@@ -173,7 +191,7 @@ export declare class McpHarness {
   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>;
@@ -236,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
@@ -251,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 {
@@ -283,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 {
@@ -347,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