@effected/mcp 0.1.0 → 0.2.0

package/testing.d.ts

@@ -25,8 +25,9 @@ declare const McpTestFailure_base: Schema.Class<McpTestFailure, Schema.TaggedStr
  *   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
- *   is never written; the server would only have refused it with an opaque
- *   `Invalid request metadata`.
+ *   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.
@@ -140,8 +141,10 @@ interface McpHarnessOptions {
  *   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: the server would only answer an opaque
- *   `Invalid request metadata`, `ping` included.
+ *   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.
  *
  * @public
  */
@@ -150,6 +153,22 @@ 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. */
@@ -173,6 +192,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. */
@@ -318,9 +339,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;