@effected/mcp 0.11.0 → 0.12.0

package/McpStdio.js

@@ -16,7 +16,8 @@ import { McpProtocol, McpServer } from "effect/ai";
 * ```
 *
 * - {@link McpStdio.layer} is `McpServer.layerStdio` with `LogToStderr`
-*   provided and merged into its output, and `Layer.orDie`. It answers a
+*   provided and merged into its output, and a bad `protocols` list
+*   turned into a defect. It answers a
 *   stdin line that is not JSON with a JSON-RPC `-32700` parse error, and
 *   JSON that is not a JSON-RPC message with `-32600`, and keeps serving.
 * - {@link McpStdio.launch} reports a launch failure itself, on stderr, and
@@ -57,14 +58,24 @@ var McpStdio = class McpStdio {
 	/**
 	* `McpServer.layerStdio` with `LogToStderr` provided and merged into the
 	* output, so every layer it provides logs to stderr too. A bad
-	* `protocols` list dies: it is the implementer's defect.
+	* `protocols` list dies: it is the implementer's defect. So does a
+	* registration that fails with `Cause.IllegalArgumentError`, which core
+	* reports for the same class of mistake; any other registration error
+	* stays in the error channel.
 	*
 	* @remarks
-	* Only a layer this one provides inherits `LogToStderr`: compose with
-	* `Layer.provideMerge(McpStdio.layer(...))`. A sibling merged beside it
-	* with `Layer.mergeAll` is not provided by it, so its build logs still
+	* Pass the server's registration layers as `options.registrations`: they
+	* are built before the server reads its first request, under
+	* `LogToStderr`. Providing this layer to them, as
+	* `Registrations.pipe(Layer.provideMerge(McpStdio.layer(...)))`, also
+	* serves them, and they inherit `LogToStderr` the same way. A sibling
+	* merged beside it with `Layer.mergeAll` is neither: its build logs still
 	* go through `console.log`, onto the wire.
-	
+	*
+	* The output is `McpServer` and the `McpServer.McpRequest<"Requires", Scope>`
+	* marker the transport discharges. `McpServerClient` is not in it: the
+	* stateless `v2026_07_28` revision has no client session, so a handler
+	* reads the client's details from `McpSchema.McpRequestContext` instead.
 	*
 	* `LogToStderr` only reaches a logger that reads it: Effect's default
 	* logger and `Logger.consolePretty`. `Logger.consoleJson`,
@@ -107,8 +118,8 @@ var McpStdio = class McpStdio {
 	* anywhere under the first one's `Effect.provide`: nested `Layer.build`
 	* and `Effect.provide` fork the ambient memo map rather than starting a
 	* new one. The tool registry is shared the same way. Isolate each server
-	* by wrapping its whole bundle (its toolkit layers together with this
-	* layer) in `Layer.fresh`, or with its own `ManagedRuntime`,
+	* by wrapping its whole bundle (this layer with its `registrations`, or its
+	* toolkit layers together with this layer) in `Layer.fresh`, or with its own `ManagedRuntime`,
 	* `Effect.provide(layer, { local: true })` or its own process. Never put
 	* the `Layer.fresh` boundary between a toolkit and this layer: the server
 	* would serve an empty registry.
@@ -126,8 +137,9 @@ var McpStdio = class McpStdio {
 		version: options.version,
 		instructions: options.instructions,
 		description: options.description,
-		protocols: options.protocols ?? McpStdio.protocols
-	}).pipe(Layer.provide(makeGuardedStdio()), Layer.provideMerge(Layer.succeed(References.LogToStderr, true)), Layer.orDie);
+		protocols: options.protocols ?? McpStdio.protocols,
+		registrations: options.registrations
+	}).pipe(Layer.provide(makeGuardedStdio()), Layer.provideMerge(Layer.succeed(References.LogToStderr, true)), Layer.catchCause((cause) => Layer.effectContext(Effect.failCause(cause).pipe(Effect.catchIf(Cause.isIllegalArgumentError, (error) => Effect.die(error))))));
 	/**
 	* `Layer.launch`, with any failure other than an interrupt logged on
 	* stderr here and re-raised marked as already reported, keeping its exit

package/McpToolkit.js

@@ -232,6 +232,17 @@ var McpToolkit = class {
 	/**
 	* `McpServer.toolkit`'s registration layer, strict by default.
 	* `options.unknownKeyMessage` is deprecated and ignored.
+	*
+	* @remarks
+	* Its requirements are core's `McpServer.ToolkitRequirements` less
+	* `McpServer`, which the layer provides itself: the handlers, any service
+	* a parameter or success schema needs, and each service a tool declares
+	* with `dependencies` or `addDependency` as an
+	* `McpServer.McpRequest<"Requires", S>` marker. A marker is met per
+	* request by MCP middleware (`McpServer.middleware`, its `layer` provided
+	* to this one), never by providing `S`. A service the handlers only need
+	* when they are built is captured by the effect form of
+	* `Toolkit.toLayer` instead, and declared nowhere.
 	*/
 	static layer = (toolkit, options = {}) => Layer.effectDiscard(Effect.gen(function* () {
 		const registry = yield* McpServer.McpServer;

package/README.md

@@ -8,10 +8,10 @@ The boundary layer of an `effect/ai` MCP server: stdio wiring that keeps stdout
 [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
 > **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
+> Effect v4 (`effect` `~4.1.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).
+> [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected).
 >
 > **Stability: unstable.** This package's API surface is not yet considered
 > complete and may change across `0.x` releases. Pin an exact version — even a
@@ -486,7 +486,7 @@ with no child process and no sockets. Pass `server` **without** a `Stdio`
 of its own — a `Stdio` the server provides internally would talk to the
 real terminal instead of the test's queues, including one that arrives
 bundled: `@effect/platform-node`'s `NodeServices.layer` brings its own
-`Stdio` along with `FileSystem`, `Path`, `ChildProcessSpawner`, `Crypto`
+`Stdio` along with `FileSystem`, `Path`, `ChildProcessSpawner`
 and `Terminal`, so composing the server with that bundle loses the harness's
 `Stdio` the same way. Compose the individual platform layers the server
 needs instead and leave `Stdio` out; the harness supplies it. The harness builds the server

package/ToolReplay.js

@@ -15,6 +15,13 @@ import { KeyValueStore } from "effect/persistence";
 * `get` and `set`, for an application's own table. Then `R` carries no
 * `KeyValueStore`.
 *
+* Inside an MCP server, pass the store. A service left in a handler's `R`
+* has to be declared in the tool's `dependencies`, which makes it a
+* request-level dependency that only MCP middleware can meet. Read
+* `KeyValueStore` once when the handlers are built, with the effect form of
+* `Toolkit.toLayer`, and hand it to `wrap` as `store`: a `KeyValueStore`
+* satisfies {@link ToolReplayStore} as is.
+*
 * Semantics, per call:
 *
 * - A key of `Option.none()` runs the handler; nothing is read or stored.

package/index.d.ts

@@ -1,4 +1,4 @@
-import { Array, Context, Effect, JsonSchema, Layer, Option, Runtime, Schema, Stdio, Struct } from "effect";
+import { Array, Cause, Context, Effect, JsonSchema, Layer, Option, Runtime, Schema, Scope, Stdio, Struct } from "effect";
 import { McpProtocol, McpSchema, McpServer, Tool, Toolkit } from "effect/ai";
 import { Remediation } from "@effected/engine";
 import { KeyValueStore } from "effect/persistence";
@@ -7,7 +7,7 @@ import { KeyValueStore } from "effect/persistence";
  *
  * @public
  */
-interface McpStdioOptions {
+interface McpStdioOptions<RA = never, RE = never, RR = never> {
   /** The server name reported to the client. */
   readonly name: string;
   /** The server version reported to the client. */
@@ -18,7 +18,28 @@ interface McpStdioOptions {
   readonly description?: string | undefined;
   /** Defaults to {@link McpStdio.protocols}. Read its ordering rules before overriding. */
   readonly protocols?: Array.NonEmptyReadonlyArray<McpProtocol.ProtocolAdapter> | undefined;
+  /**
+   * The server's registration layers (toolkits, resources, prompts), built
+   * before the server reads its first request and under `LogToStderr`.
+   *
+   * @remarks
+   * Core's `registrations` option of `McpServer.layerStdio`. The transport
+   * discharges each `McpServer.McpRequest<"Requires", Scope>` marker; any
+   * other request-level marker stays in the layer's requirements, to be met
+   * by MCP middleware. A registration that needs `Stdio` when it is built
+   * gets the guarded one this layer serves over.
+   */
+  readonly registrations?: Layer.Layer<RA, RE, RR> | undefined;
 }
+/**
+ * The services a registration layer needs that {@link McpStdio.layer} does
+ * not supply: everything but `McpServer` and `Stdio` (which the layer
+ * requires itself), with each request-level marker but
+ * `McpServer.McpRequest<"Requires", Scope>`, which the transport discharges.
+ *
+ * @public
+ */
+type McpStdioRegistrationServices<RR> = Exclude<McpServer.McpRequest.Without<RR>, McpServer.McpServer> | McpServer.McpRequest.From<"Requires", Exclude<McpServer.McpRequest.Only<"Requires", RR>, Scope.Scope>>;
 /**
  * Options for {@link McpStdio.launch}.
  *
@@ -51,7 +72,8 @@ interface McpLaunchOptions {
  * ```
  *
  * - {@link McpStdio.layer} is `McpServer.layerStdio` with `LogToStderr`
- *   provided and merged into its output, and `Layer.orDie`. It answers a
+ *   provided and merged into its output, and a bad `protocols` list
+ *   turned into a defect. It answers a
  *   stdin line that is not JSON with a JSON-RPC `-32700` parse error, and
  *   JSON that is not a JSON-RPC message with `-32600`, and keeps serving.
  * - {@link McpStdio.launch} reports a launch failure itself, on stderr, and
@@ -88,14 +110,24 @@ export declare class McpStdio {
   /**
    * `McpServer.layerStdio` with `LogToStderr` provided and merged into the
    * output, so every layer it provides logs to stderr too. A bad
-   * `protocols` list dies: it is the implementer's defect.
+   * `protocols` list dies: it is the implementer's defect. So does a
+   * registration that fails with `Cause.IllegalArgumentError`, which core
+   * reports for the same class of mistake; any other registration error
+   * stays in the error channel.
    *
    * @remarks
-   * Only a layer this one provides inherits `LogToStderr`: compose with
-   * `Layer.provideMerge(McpStdio.layer(...))`. A sibling merged beside it
-   * with `Layer.mergeAll` is not provided by it, so its build logs still
+   * Pass the server's registration layers as `options.registrations`: they
+   * are built before the server reads its first request, under
+   * `LogToStderr`. Providing this layer to them, as
+   * `Registrations.pipe(Layer.provideMerge(McpStdio.layer(...)))`, also
+   * serves them, and they inherit `LogToStderr` the same way. A sibling
+   * merged beside it with `Layer.mergeAll` is neither: its build logs still
    * go through `console.log`, onto the wire.
-
+   *
+   * The output is `McpServer` and the `McpServer.McpRequest<"Requires", Scope>`
+   * marker the transport discharges. `McpServerClient` is not in it: the
+   * stateless `v2026_07_28` revision has no client session, so a handler
+   * reads the client's details from `McpSchema.McpRequestContext` instead.
    *
    * `LogToStderr` only reaches a logger that reads it: Effect's default
    * logger and `Logger.consolePretty`. `Logger.consoleJson`,
@@ -138,8 +170,8 @@ export declare class McpStdio {
    * anywhere under the first one's `Effect.provide`: nested `Layer.build`
    * and `Effect.provide` fork the ambient memo map rather than starting a
    * new one. The tool registry is shared the same way. Isolate each server
-   * by wrapping its whole bundle (its toolkit layers together with this
-   * layer) in `Layer.fresh`, or with its own `ManagedRuntime`,
+   * by wrapping its whole bundle (this layer with its `registrations`, or its
+   * toolkit layers together with this layer) in `Layer.fresh`, or with its own `ManagedRuntime`,
    * `Effect.provide(layer, { local: true })` or its own process. Never put
    * the `Layer.fresh` boundary between a toolkit and this layer: the server
    * would serve an empty registry.
@@ -152,7 +184,7 @@ export declare class McpStdio {
    * Each call mints a fresh layer; bind the result to a `const` or the
    * server builds twice.
    */
-  static readonly layer: (options: McpStdioOptions) => Layer.Layer<McpServer.McpServer | McpSchema.McpServerClient, never, Stdio.Stdio>;
+  static readonly layer: <RA = never, RE = never, RR = never>(options: McpStdioOptions<RA, RE, RR>) => Layer.Layer<McpServer.McpServer | McpServer.McpRequest<"Requires", Scope.Scope>, Exclude<RE, Cause.IllegalArgumentError>, Stdio.Stdio | McpStdioRegistrationServices<RR>>;
   /**
    * `Layer.launch`, with any failure other than an interrupt logged on
    * stderr here and re-raised marked as already reported, keeping its exit
@@ -462,8 +494,19 @@ export declare class McpToolkit {
   /**
    * `McpServer.toolkit`'s registration layer, strict by default.
    * `options.unknownKeyMessage` is deprecated and ignored.
-   */
-  static readonly layer: <Tools extends Record<string, Tool.Any>>(toolkit: Toolkit.Toolkit<Tools>, options?: McpToolkitOptions) => Layer.Layer<never, never, Tool.HandlersFor<Tools> | Exclude<Tool.HandlerServices<Tools>, McpSchema.McpRequestContext>>;
+   *
+   * @remarks
+   * Its requirements are core's `McpServer.ToolkitRequirements` less
+   * `McpServer`, which the layer provides itself: the handlers, any service
+   * a parameter or success schema needs, and each service a tool declares
+   * with `dependencies` or `addDependency` as an
+   * `McpServer.McpRequest<"Requires", S>` marker. A marker is met per
+   * request by MCP middleware (`McpServer.middleware`, its `layer` provided
+   * to this one), never by providing `S`. A service the handlers only need
+   * when they are built is captured by the effect form of
+   * `Toolkit.toLayer` instead, and declared nowhere.
+   */
+  static readonly layer: <Tools extends Record<string, Tool.Any>>(toolkit: Toolkit.Toolkit<Tools>, options?: McpToolkitOptions) => Layer.Layer<never, never, Exclude<McpServer.ToolkitRequirements<Tools>, McpServer.McpServer>>;
 }
 /**
  * How a tool's declared failure should read on the wire.
@@ -802,7 +845,7 @@ export declare class ToolRefusal extends ToolRefusal_base {
  * Core's `KeyValueStore` already satisfies it structurally, so a
  * `KeyValueStore` value can be passed as is. An application backed by its
  * own table implements just these two methods, instead of stubbing the
- * `remove`, `clear` and `size` that `KeyValueStore.makeStringOnly` demands.
+ * `remove`, `clear`, `size` and `keys` that `KeyValueStore.makeStringOnly` demands.
  *
  * `get` answers `undefined` for a missing key, the same contract as
  * `KeyValueStore.get`. A failure from either method is never a tool error:
@@ -864,6 +907,13 @@ interface ToolReplayOptions<P, S extends Schema.Top, Store extends ToolReplaySto
  * `get` and `set`, for an application's own table. Then `R` carries no
  * `KeyValueStore`.
  *
+ * Inside an MCP server, pass the store. A service left in a handler's `R`
+ * has to be declared in the tool's `dependencies`, which makes it a
+ * request-level dependency that only MCP middleware can meet. Read
+ * `KeyValueStore` once when the handlers are built, with the effect form of
+ * `Toolkit.toLayer`, and hand it to `wrap` as `store`: a `KeyValueStore`
+ * satisfies {@link ToolReplayStore} as is.
+ *
  * Semantics, per call:
  *
  * - A key of `Option.none()` runs the handler; nothing is read or stored.
@@ -935,5 +985,5 @@ export declare class ToolReplay {
    */
   static readonly wrap: <P, S extends Schema.Top, Store extends ToolReplayStore | undefined = undefined>(options: ToolReplayOptions<P, S, Store>) => (<E, R>(handler: (params: P) => Effect.Effect<S["Type"], E, R>) => (params: P) => Effect.Effect<S["Type"], E, R | ([Store] extends [ToolReplayStore] ? never : KeyValueStore.KeyValueStore) | S["DecodingServices"] | S["EncodingServices"]>);
 }
-export type { FormatUnknownKeysOptions, McpLaunchOptions, McpStdioOptions, McpToolkitOptions, ToolOutcomeEnvelopeOptions, ToolOutcomeErrorInput, ToolOutcomeFailure, ToolOutcomeFailures, ToolReplayOptions, ToolReplayStore, UnionHandlerOptions, UnionTool, UnionToolOptions, UnknownKeysLevel };
+export type { FormatUnknownKeysOptions, McpLaunchOptions, McpStdioOptions, McpStdioRegistrationServices, McpToolkitOptions, ToolOutcomeEnvelopeOptions, ToolOutcomeErrorInput, ToolOutcomeFailure, ToolOutcomeFailures, ToolReplayOptions, ToolReplayStore, UnionHandlerOptions, UnionTool, UnionToolOptions, UnknownKeysLevel };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/mcp",
-	"version": "0.11.0",
+	"version": "0.12.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": [
@@ -52,8 +52,8 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/engine": "^0.10.0",
-		"effect": "^4.0.0"
+		"@effected/engine": "^0.11.0",
+		"effect": "~4.1.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.59.4"
+      "packageVersion": "7.60.0"
     }
   ]
 }