@effected/mcp 0.11.0 → 0.13.0

package/testing.d.ts

@@ -1,490 +0,0 @@
-import { Duration, Effect, JsonSchema, Layer, PlatformError, Schema, Scope, Stdio } from "effect";
-import { McpProtocol } from "effect/ai";
-import { ChildProcess, ChildProcessSpawner } from "effect/process";
-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", "TimedOut"]>;
-  /** A human-readable description of what went wrong. */
-  readonly message: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-/**
- * Why an MCP test client could not produce what was asked of it.
- *
- * @remarks
- * Each reason is raised by a specific client, and not every client raises
- * every reason:
- *
- * - `StreamEnded` (`McpProcess`, `McpProbe`): the spawned child's stdout
- *   ended first, because the child exited. `McpProbe` folds the exit code
- *   and stderr into the message. `McpProcess.stderrUntil` raises it when
- *   stderr ends before its predicate holds.
- * - `TimedOut` (`McpProcess.stderrUntil`): the predicate did not hold
- *   within the given timeout. The message carries the stderr seen so far.
- * - `NotJsonRpc` (`McpProcess.readUntilResponse`, `McpProbe`): a spawned
- *   child's stdout line was not a JSON-RPC frame. `McpHarness` never raises
- *   it: under `strictStdout` a non-JSON-RPC line DIES the pending wait as a
- *   defect instead, so assert it with `Effect.exit` and `Cause.hasDies`,
- *   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` 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.
- * - `ErrorResponse` (`McpHarness.listTools`): the server answered with a
- *   JSON-RPC error where a result was required. Every other request method
- *   returns the whole response, error included, as data.
- *
- * @public
- */
-export declare class McpTestFailure extends McpTestFailure_base {}
-/**
- * One JSON-RPC 2.0 frame as an MCP test client sees it.
- *
- * @public
- */
-interface JsonRpcMessage {
-  readonly jsonrpc: "2.0";
-  readonly id?: string | number | null | undefined;
-  readonly method?: string | undefined;
-  readonly params?: unknown;
-  readonly result?: unknown;
-  readonly error?: unknown;
-}
-/**
- * One entry of a `tools/list` result.
- *
- * @public
- */
-interface ServedTool {
-  readonly name: string;
-  readonly title?: string | undefined;
-  readonly description?: string | undefined;
-  readonly inputSchema: JsonSchema.JsonSchema;
-  readonly outputSchema?: JsonSchema.JsonSchema | undefined;
-  readonly annotations?: {
-    readonly [key: string]: unknown;
-  } | undefined;
-  readonly _meta?: {
-    readonly [key: string]: unknown;
-  } | undefined;
-}
-/**
- * One entry of a `resources/list` result.
- *
- * @public
- */
-interface ServedResource {
-  readonly uri: string;
-  readonly name: string;
-  readonly title?: string | undefined;
-  readonly description?: string | undefined;
-  readonly mimeType?: string | undefined;
-  readonly annotations?: {
-    readonly [key: string]: unknown;
-  } | undefined;
-  readonly size?: number | undefined;
-  readonly _meta?: {
-    readonly [key: string]: unknown;
-  } | undefined;
-}
-/**
- * Options for {@link McpHarness.make}.
- *
- * @public
- */
-interface McpHarnessOptions {
-  /** The revision this client speaks. Defaults to `McpProtocol.v2025_11_25`; a stateless adapter switches to `server/discover` and per-request `_meta`. */
-  readonly protocol?: McpProtocol.ProtocolAdapter | undefined;
-  /** The `clientInfo` sent in `initialize` and in stateless `_meta`. */
-  readonly clientInfo?: {
-    readonly name: string;
-    readonly version: string;
-  } | undefined;
-  /** Capture the server's console so logs are asserted, not printed. Defaults to `true`. */
-  readonly captureLogs?: boolean | undefined;
-  /** Treat any stdout line that is not JSON-RPC as a defect. Defaults to `true`. */
-  readonly strictStdout?: boolean | undefined;
-}
-/**
- * An in-process MCP client for a real server layer, over queue-backed stdio.
- *
- * @remarks
- * Builds your server with a queue-backed `Stdio.layerTest` that satisfies the
- * server's `Stdio` requirement, so tests see the exact served schemas and wire
- * results a real client would, with no child and no sockets. Pass the server
- * WITHOUT a `Stdio` of its own: a `Stdio` the server provides internally wins,
- * and talks to the real terminal. A bundled platform layer such as
- * `NodeServices.layer` (`@effect/platform-node`) brings its own `Stdio` along
- * with `FileSystem`, `Path`, `ChildProcessSpawner`, `Crypto` and `Terminal` —
- * providing it to the server loses `Stdio` the same way, and every wait
- * hangs to timeout with no error naming why. Compose the individual layers
- * the server needs instead and leave `Stdio` out; this harness supplies it.
- *
- * The server is built with a fresh layer memo map, never the ambient one, so
- * a harness made under another stdio server's `Effect.provide` still serves
- * its own. Never pass a server layer that provides a layer the test also
- * provides and then reads — `McpHarness.make(server.pipe(Layer.provide(AppLayer)))`
- * under `Effect.provide(AppLayer)` builds `AppLayer` twice, so the tools write
- * to one instance and the test reads the other. Leave the service in the
- * server layer's requirements and provide it once from the test, or build it
- * once and pass `Layer.succeed(Tag, value)`.
- *
- * - Responses are matched by id, so notifications may interleave freely.
- * - Every response wait and `awaitOutboundMethod` fails with `ServerStopped`
- *   when the server stops, and dies when `strictStdout` sees a line that is
- *   not JSON-RPC. `stop` stops the server at once; `close` ends stdin and lets
- *   in-flight requests answer first, so only `stop` releases a wait on a
- *   request that never completes.
- * - With `captureLogs`, the server's console is captured: `stderrSoFar`
- *   holds stderr writes and every log line, and `consoleLogSoFar` holds
- *   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. `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
- */
-export declare class McpHarness {
-  /** The revision this client speaks. */
-  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` (`ping` excepted). */
-  readonly startRequest: (method: string, params?: unknown) => Effect.Effect<{
-    readonly id: number;
-    readonly response: Effect.Effect<JsonRpcMessage, McpTestFailure>;
-  }, McpTestFailure>;
-  /** Send a notification. */
-  readonly notify: (method: string, params?: unknown) => Effect.Effect<void>;
-  /** `tools/call`, returning the whole response: a JSON-RPC error is data here. */
-  readonly callTool: (name: string, args?: unknown) => Effect.Effect<JsonRpcMessage, McpTestFailure>;
-  /** `tools/list`'s tools; a JSON-RPC error fails with `ErrorResponse`. */
-  readonly listTools: Effect.Effect<ReadonlyArray<ServedTool>, McpTestFailure>;
-  /** `resources/list`'s resources; a JSON-RPC error fails with `ErrorResponse`. */
-  readonly listResources: Effect.Effect<ReadonlyArray<ServedResource>, McpTestFailure>;
-  /** `resources/read`, returning the whole response. */
-  readonly readResource: (uri: string) => Effect.Effect<JsonRpcMessage, McpTestFailure>;
-  /** Write any value as one newline-framed line. Never gated; a raw `initialize` counts as sent. */
-  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, its arguments joined with a space, each rendered close to
-   * what the console would show: a string as itself, a value with its own string form as that form (an `Error` as
-   * `Error: boom`, a number, a date), an array or a plain object as JSON (`{"message":"x"}`, not just `x`).
-   *
-   * @remarks
-   * Rendering never throws inside the server's own call. A value whose string form throws (an object with no
-   * prototype, a throwing `toString`) and has no JSON falls back to `ErrorText.describe` from `@effected/engine`.
-   */
-  readonly consoleLogSoFar: Effect.Effect<ReadonlyArray<string>>;
-  /**
-   * End stdin, as a client disconnecting does. The server drains first:
-   * requests already in flight still answer, and the server stops once they
-   * have, so a wait on a request that never completes keeps waiting. Use
-   * {@link McpHarness.stop} to end the server regardless.
-   */
-  readonly close: Effect.Effect<void>;
-  /**
-   * Interrupt the server without draining, as a client killing the process
-   * does: every pending response wait and `awaitOutboundMethod` fails with
-   * `ServerStopped`.
-   */
-  readonly stop: Effect.Effect<void>;
-  private constructor();
-  /** Build `server` over queue-backed stdio and return a client for it; fails with the layer's own error if it cannot build. */
-  static readonly make: <ROut, E, R>(server: Layer.Layer<ROut, E, R>, options?: McpHarnessOptions) => Effect.Effect<McpHarness, E, Scope.Scope | Exclude<R, Stdio.Stdio>>;
-}
-/**
- * Options for {@link McpProbe.initialize}.
- *
- * @public
- */
-interface McpProbeOptions {
-  /** Defaults to `McpProtocol.v2025_11_25`; a stateless adapter probes with `server/discover`. */
-  readonly protocol?: McpProtocol.ProtocolAdapter | undefined;
-}
-/**
- * What {@link McpProbe.initialize} observed.
- *
- * @public
- */
-interface McpProbeResult {
-  /** The id-1 response. A refused handshake is still a response: assert `response.error === undefined`. */
-  readonly response: JsonRpcMessage;
-  /** Every raw stdout line, in order. */
-  readonly stdout: ReadonlyArray<string>;
-  /** Everything the child wrote to stderr; a clean boot leaves it empty. */
-  readonly stderr: string;
-  /** The child's exit code after stdin closed; a clean boot exits 0. */
-  readonly exitCode: number;
-}
-/**
- * The smallest proof that an installed MCP bin boots: one initialize, a clean
- * close, and exit 0.
- *
- * @remarks
- * Stdin stays open until the id-1 response has arrived. Closing it right
- * after writing proves nothing against a server that stops at stdin EOF
- * without answering what is in flight: it replies nothing and exits 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
- * the handshake with a JSON-RPC error, exits 0 and writes nothing.
- *
- * - Any stdout line that is not JSON-RPC fails with `NotJsonRpc`, naming the
- *   line: a server that logs to stdout corrupts the wire, so the probe fails
- *   rather than skipping the line.
- * - A child that exits before responding fails with `StreamEnded`, and the
- *   message carries its exit code and stderr.
- * - 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 {
-  private constructor();
-  /**
-   * Spawn `command`, send one `initialize` (or `server/discover` on a
-   * stateless revision) as id 1, wait for its response, close stdin, and
-   * collect stdout, stderr and the exit code.
-   */
-  static readonly initialize: (command: ChildProcess.Command, options?: McpProbeOptions) => Effect.Effect<McpProbeResult, McpTestFailure | PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner>;
-}
-/**
- * Options for {@link McpProcess.stderrUntil}.
- *
- * @public
- */
-interface McpProcessStderrUntilOptions {
-  /**
-   * How long to wait for the predicate to hold before failing with
-   * `TimedOut`. Real time: under `it.effect`'s `TestClock` it never fires,
-   * so a test that waits on stderr runs under `it.live`. Keep it below the
-   * test runner's own timeout, or the runner kills the test first.
-   */
-  readonly timeout: Duration.Input;
-}
-/**
- * A spawned MCP server bin a test writes to while it runs.
- *
- * @remarks
- * Build the command in the test file with `execPath` and an explicit `env`:
- * `ChildProcess.make(process.execPath, [bin], { env })`.
- *
- * - `nextLine` fails with `StreamEnded` when stdout ends, so a child that
- *   exits early fails the test instead of hanging it.
- * - `send` writes one JSON-encoded line; `sendRaw` writes a string or bytes
- *   exactly as given, for a malformed frame or one frame split across
- *   writes, even mid-character.
- * - `readUntilResponse` reads past interleaved notifications, such as
- *   `list_changed`, to the matching id and returns what it saw.
- * - `closeStdin` is `Queue.end`, never `Queue.shutdown`, so every frame
- *   already sent is delivered before stdin closes.
- * - A request in flight when stdin closes still answers from an Effect
- *   server, which drains before it exits; a server that does not drain
- *   drops it, so a portable client reads the 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 {
-  /**
-   * Write one JSON-encoded, newline-framed message to the child's stdin.
-   *
-   * @remarks
-   * Never fails. A frame sent after `closeStdin` is dropped, and a write the
-   * child can no longer receive fails the stdin pump instead; the next
-   * `StreamEnded` message names that failure.
-   */
-  readonly send: (message: unknown) => Effect.Effect<void>;
-  /**
-   * Write `text` to the child's stdin exactly as given: a string as UTF-8,
-   * bytes unchanged, with no JSON encoding and no newline added.
-   *
-   * @remarks
-   * For frames `send` cannot produce: a line that is not JSON, a blank line,
-   * or one frame split across several writes, including mid-character by
-   * passing bytes. Include the `\n` yourself.
-   * Never fails, on the same terms as `send`.
-   */
-  readonly sendRaw: (text: string | Uint8Array) => Effect.Effect<void>;
-  /** The next non-empty stdout line; fails with `StreamEnded` once stdout ends. */
-  readonly nextLine: Effect.Effect<string, McpTestFailure>;
-  /** Read JSON-RPC lines up to and including the response with this id. */
-  readonly readUntilResponse: (id: string | number) => Effect.Effect<{
-    readonly response: JsonRpcMessage;
-    readonly seen: ReadonlyArray<JsonRpcMessage>;
-  }, McpTestFailure>;
-  /** `initialize` (id 1) then `notifications/initialized`, or `server/discover` (id 1) on a stateless revision. Use ids of 2 or more for your own requests. */
-  readonly handshake: (protocol?: McpProtocol.ProtocolAdapter) => Effect.Effect<JsonRpcMessage, McpTestFailure>;
-  /** End stdin after every frame already sent. */
-  readonly closeStdin: Effect.Effect<void>;
-  /** Wait for the child to exit. */
-  readonly exitCode: Effect.Effect<number, PlatformError.PlatformError>;
-  /** Everything written to stderr so far. */
-  readonly stderrSoFar: Effect.Effect<string>;
-  /**
-   * Wait until everything written to stderr so far satisfies `predicate`,
-   * and return that text.
-   *
-   * @remarks
-   * Event-driven: the predicate is checked against the current text at once,
-   * then again on every chunk the child writes, never on a polling timer.
-   * Fails with `StreamEnded` when stderr ends (the child exited) without the
-   * predicate holding, and with `TimedOut` once `options.timeout` passes;
-   * both messages carry the stderr seen so far. Reach for it whenever a
-   * report lands on a later tick than the responses a test reads, such as
-   * `McpGuard`'s `injectCrash: { at: "connected" }` report, instead of
-   * reading `stderrSoFar` once. `options.timeout` is real time: run the test
-   * under `it.live`.
-   */
-  readonly stderrUntil: (predicate: (stderr: string) => boolean, options: McpProcessStderrUntilOptions) => Effect.Effect<string, McpTestFailure>;
-  /** Everything written to stderr, once stderr has ended. Waits for the child to exit. */
-  readonly stderrFinal: Effect.Effect<string>;
-  private constructor();
-  /** Spawn `command` for the life of the current scope. */
-  static readonly spawn: (command: ChildProcess.Command) => Effect.Effect<McpProcess, PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner | Scope.Scope>;
-}
-/**
- * The policy {@link McpToolAudit.check} enforces.
- *
- * @public
- */
-interface McpToolAuditPolicy {
-  /** `"closed"`: every object node rejects unknown keys. `"open"`: none with properties does. `"any"`: not checked. */
-  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; 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`. 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;
-  /** All four MCP annotation hints must be present as booleans. */
-  readonly requireHints?: boolean | undefined;
-}
-/**
- * A pure sweep over a served `tools/list` that returns every policy
- * violation, as `"<tool>: <what>"` strings.
- *
- * @remarks
- * Run it against what a real server serves (`McpHarness.listTools`), not
- * against your own schemas: the served document is what a client sees, and
- * it differs by protocol revision. The stateless `2026-07-28` adapter passes a
- * non-object output through, while the stateful adapters drop it — which is
- * why `objectRootedOutput` defaults to `true`.
- *
- * `"closed"` is only as sound as the walk. It follows `properties`,
- * `items`, a schema-valued `additionalProperties`, `prefixItems`, `anyOf`,
- * `oneOf` and `$defs`, and merges an `allOf` member's `properties` and
- * `additionalProperties: false` onto its node. It does not visit
- * `patternProperties` values, an `allOf` member's `items` or
- * `additionalProperties` schema, or an `allOf` nested inside another; and
- * a key declared in two `allOf` members is last-write-wins. A hand-authored
- * or `Tool.dynamic` schema can therefore pass `"closed"` with an open node
- * the walk never reached. Core-emitted strict schemas close every node, so
- * a strict `Tool.make` tool is reported faithfully.
- *
- * @public
- */
-export declare class McpToolAudit {
-  private constructor();
-  /**
-   * Every violation of `policy` across `tools`, as `"<tool>: <what>"`, in
-   * tool order. Empty means the sweep passed. A duplicate tool name is
-   * reported under every policy, `input: "any"` included.
-   */
-  static readonly check: (tools: ReadonlyArray<ServedTool>, policy: McpToolAuditPolicy) => ReadonlyArray<string>;
-}
-export type { JsonRpcMessage, McpHarnessOptions, McpProbeOptions, McpProbeResult, McpProcessStderrUntilOptions, McpToolAuditPolicy, ServedResource, ServedTool };
-//# sourceMappingURL=testing.d.ts.map

package/testing.js

@@ -1,7 +0,0 @@
-import { McpTestFailure } from "./McpTestFailure.js";
-import { McpHarness } from "./McpHarness.js";
-import { McpProcess } from "./McpProcess.js";
-import { McpProbe } from "./McpProbe.js";
-import { McpToolAudit } from "./McpToolAudit.js";
-
-export { McpHarness, McpProbe, McpProcess, McpTestFailure, McpToolAudit };