@effected/mcp-kit 0.13.0 → 0.14.0

package/McpHarness.js

@@ -92,6 +92,24 @@ const showArg = (arg) => {
 * }).pipe(Effect.scoped);
 * ```
 *
+* Services the test also seeds go in `options.services`, built once. End the
+* session with `harness.close` (the server answers what is in flight, then
+* stops) or, when a request may never complete, `harness.stop` (the server is
+* interrupted at once):
+*
+* ```ts
+* import { McpHarness } from "@effected/mcp-kit/testing";
+* import { Context, Effect } from "effect";
+*
+* // `Database` is a service the server's tools need, and the test seeds it.
+* const program = Effect.gen(function* () {
+* 	const database = yield* makeDatabase;
+* 	const harness = yield* McpHarness.make(ServerLayer, { services: Context.make(Database, database) });
+* 	yield* harness.initialize;
+* 	yield* harness.stop;
+* }).pipe(Effect.scoped);
+* ```
+*
 * @public
 */
 var McpHarness = class McpHarness {
@@ -224,7 +242,8 @@ var McpHarness = class McpHarness {
 			error: toStderr,
 			warn: toStderr
 		};
-		const provided = options.captureLogs === false ? server.pipe(Layer.provide(stdio)) : server.pipe(Layer.provide(stdio), Layer.provide(Layer.succeed(Console.Console, captured)));
+		const withLogs = options.captureLogs === false ? server.pipe(Layer.provide(stdio)) : server.pipe(Layer.provide(stdio), Layer.provide(Layer.succeed(Console.Console, captured)));
+		const provided = options.services === void 0 ? withLogs : withLogs.pipe(Layer.provide(Layer.succeedContext(options.services)));
 		const route = (line) => {
 			const parsed = parseFrame(line);
 			if (!isJsonRpcMessage(parsed)) return strictStdout ? Effect.asVoid(Deferred.die(corrupt, /* @__PURE__ */ new Error(`stdout carried a line that is not JSON-RPC: ${ToolFailure.truncate(line)}`))) : Effect.void;

package/McpStdio.js

@@ -137,6 +137,10 @@ var McpStdio = class McpStdio {
 		version: options.version,
 		instructions: options.instructions,
 		description: options.description,
+		websiteUrl: options.websiteUrl,
+		icons: options.icons,
+		extensions: options.extensions,
+		cacheHints: options.cacheHints,
 		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))))));

package/McpToolkit.js

@@ -252,6 +252,47 @@ var McpToolkit = class {
 		});
 		yield* McpServer.registerToolkit(strictened(toolkit, options.strict ?? DEFAULT_STRICT)).pipe(Effect.provideService(McpServer.McpServer, decorated));
 	})).pipe(Layer.provide(McpServer.McpServer.layer));
+	/**
+	* Meet the request-level dependencies a tool declares with `dependencies`
+	* or `addDependency` from a layer built once for the server's lifetime.
+	* Provide the result to {@link McpToolkit.layer}.
+	*
+	* @remarks
+	* The layer builds with the server's graph, so a failure fails the server
+	* build rather than a request, and its finalizers run at server shutdown.
+	* It builds in that graph's memo map: a layer the graph also builds is
+	* shared, and two servers each wrapped whole in `Layer.fresh` build their
+	* own.
+	*
+	* It captures what the layer outputs and nothing else, so a key the build
+	* merely ran under (a span, a request-level reference) never shadows the
+	* request's own, which capturing `Effect.context` in hand-written
+	* middleware does. The outputs are taken as given: a layer that outputs
+	* `Effect.context()` wholesale, through `Layer.effectContext`, still leaks
+	* everything it read.
+	*
+	* A service that varies per request still needs its own
+	* `McpServer.middleware`. A service only the handlers' construction needs
+	* is captured by the effect form of `Toolkit.toLayer` and declared nowhere.
+	*
+	* Each call mints a fresh layer; bind the result to a `const` or the
+	* middleware builds again.
+	*
+	* @example
+	* ```ts
+	* import { McpToolkit } from "@effected/mcp-kit";
+	* import { Layer } from "effect";
+	*
+	* // `Kit` declares `dependencies: [Inspector]`; `InspectorLive` builds it once.
+	* const Lifetime = McpToolkit.provideLifetime(InspectorLive);
+	* const ToolsLayer = McpToolkit.layer(Kit).pipe(Layer.provide(Lifetime), Layer.provide(KitHandlers));
+	* ```
+	*/
+	static provideLifetime = (layer) => {
+		const Lifetime = Context.Service("@effected/mcp-kit/LifetimeContext");
+		const capture = Layer.fromBuild((memoMap, scope) => Effect.map(Layer.buildWithMemoMap(layer, memoMap, scope), (context) => Context.make(Lifetime, Context.omit(Layer.CurrentMemoMap)(context))));
+		return McpServer.middleware()(Effect.map(Effect.service(Lifetime), (context) => (effect) => Effect.updateContext(effect, (current) => Context.merge(current, context)))).layer.pipe(Layer.provide(capture));
+	};
 };
 
 export { McpToolkit, guardRegistration };

package/README.md

@@ -291,6 +291,11 @@ scopes:
   `options.unknownKeyMessage` is deprecated and ignored. Pass `{ strict: "annotated" }` to leave
   unannotated tools lenient, or annotate an individual tool
   `Tool.Strict` false to opt it out under the default.
+- **`McpToolkit.provideLifetime(layer)`** — meets the services tools declare
+  in `dependencies` from a layer built once with the server's graph. Provide
+  the result to `McpToolkit.layer`. It captures what the layer outputs and
+  nothing else, so nothing the build ran under shadows a request's own span
+  or references; a layer that outputs `Effect.context()` wholesale still leaks.
 
 ```ts
 import { McpToolkit } from "@effected/mcp-kit";

package/ToolReplay.js

@@ -88,6 +88,13 @@ var ToolReplay = class ToolReplay {
 	/**
 	* Wraps a handler with replay. Throws at wrap time when `tool` contains
 	* `:`, a wiring mistake, so it surfaces when the server is built.
+	*
+	* @remarks
+	* Call it where the handler is built, once: the effect form of
+	* `Toolkit.toLayer`, reading the store's services there and passing them as
+	* `store`. Calling it per request, inside the handler, rebuilds the JSON
+	* codec on every call and turns the wiring check's throw into a defect at
+	* the first call instead of a failure when the server is built.
 	*/
 	static wrap = (options) => {
 		if (options.tool.includes(":")) throw new Error(`ToolReplay.wrap: tool name "${options.tool}" contains ":", the stored-key separator.`);

package/index.d.ts

@@ -16,6 +16,21 @@ interface McpStdioOptions<RA = never, RE = never, RR = never> {
   readonly instructions?: string | undefined;
   /** A one-line description of the server, reported to the client. */
   readonly description?: string | undefined;
+  /** The server's website, reported in `server/discover` and `initialize`. */
+  readonly websiteUrl?: string | undefined;
+  /** Icons for the server, reported to the client. */
+  readonly icons?: ReadonlyArray<McpSchema.Icon> | undefined;
+  /** Capability extensions the server advertises, keyed `vendor/name`. */
+  readonly extensions?: (typeof McpSchema.ServerCapabilities)["Type"]["extensions"] | undefined;
+  /**
+   * How long a client may treat each list result as fresh, per result kind.
+   *
+   * @remarks
+   * Core's `cacheHints`, forwarded unchanged. Only the stateless `2026-07-28` revision carries them; earlier
+   * revisions ignore the option. Omitted kinds keep a zero `ttl`. A positive `ttl` lets a client keep showing a list
+   * after registrations change, until it expires: raise it only for a list that is fixed for the server's lifetime.
+   */
+  readonly cacheHints?: McpServer.CacheHints | undefined;
   /** Defaults to {@link McpStdio.protocols}. Read its ordering rules before overriding. */
   readonly protocols?: Array.NonEmptyReadonlyArray<McpProtocol.ProtocolAdapter> | undefined;
   /**
@@ -507,6 +522,43 @@ export declare class McpToolkit {
    * `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>>;
+  /**
+   * Meet the request-level dependencies a tool declares with `dependencies`
+   * or `addDependency` from a layer built once for the server's lifetime.
+   * Provide the result to {@link McpToolkit.layer}.
+   *
+   * @remarks
+   * The layer builds with the server's graph, so a failure fails the server
+   * build rather than a request, and its finalizers run at server shutdown.
+   * It builds in that graph's memo map: a layer the graph also builds is
+   * shared, and two servers each wrapped whole in `Layer.fresh` build their
+   * own.
+   *
+   * It captures what the layer outputs and nothing else, so a key the build
+   * merely ran under (a span, a request-level reference) never shadows the
+   * request's own, which capturing `Effect.context` in hand-written
+   * middleware does. The outputs are taken as given: a layer that outputs
+   * `Effect.context()` wholesale, through `Layer.effectContext`, still leaks
+   * everything it read.
+   *
+   * A service that varies per request still needs its own
+   * `McpServer.middleware`. A service only the handlers' construction needs
+   * is captured by the effect form of `Toolkit.toLayer` and declared nowhere.
+   *
+   * Each call mints a fresh layer; bind the result to a `const` or the
+   * middleware builds again.
+   *
+   * @example
+   * ```ts
+   * import { McpToolkit } from "@effected/mcp-kit";
+   * import { Layer } from "effect";
+   *
+   * // `Kit` declares `dependencies: [Inspector]`; `InspectorLive` builds it once.
+   * const Lifetime = McpToolkit.provideLifetime(InspectorLive);
+   * const ToolsLayer = McpToolkit.layer(Kit).pipe(Layer.provide(Lifetime), Layer.provide(KitHandlers));
+   * ```
+   */
+  static readonly provideLifetime: <S, E, R>(layer: Layer.Layer<S, E, R>) => Layer.Layer<McpServer.McpRequest.From<"Requires", S>, E, R>;
 }
 /**
  * How a tool's declared failure should read on the wire.
@@ -982,6 +1034,13 @@ export declare class ToolReplay {
   /**
    * Wraps a handler with replay. Throws at wrap time when `tool` contains
    * `:`, a wiring mistake, so it surfaces when the server is built.
+   *
+   * @remarks
+   * Call it where the handler is built, once: the effect form of
+   * `Toolkit.toLayer`, reading the store's services there and passing them as
+   * `store`. Calling it per request, inside the handler, rebuilds the JSON
+   * codec on every call and turns the wiring check's throw into a defect at
+   * the first call instead of a failure when the server is built.
    */
   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"]>);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/mcp-kit",
-	"version": "0.13.0",
+	"version": "0.14.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,7 +52,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/kit": "^0.12.0",
+		"@effected/kit": "^0.13.0",
 		"effect": "~4.1.0"
 	},
 	"engines": {

package/testing.d.ts

@@ -1,4 +1,4 @@
-import { Duration, Effect, JsonSchema, Layer, PlatformError, Schema, Scope, Stdio } from "effect";
+import { Context, 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", {
@@ -94,7 +94,7 @@ interface ServedResource {
  *
  * @public
  */
-interface McpHarnessOptions {
+interface McpHarnessOptions<S = never> {
   /** 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`. */
@@ -106,6 +106,17 @@ interface McpHarnessOptions {
   readonly captureLogs?: boolean | undefined;
   /** Treat any stdout line that is not JSON-RPC as a defect. Defaults to `true`. */
   readonly strictStdout?: boolean | undefined;
+  /**
+   * A pre-built context of the services the server needs, provided to it as built.
+   *
+   * @remarks
+   * Build the services once, seed them from the test, and pass them here: the tools then read the instance the test
+   * wrote to, where providing the services' layer instead would build a second one. The harness's queue-backed
+   * `Stdio` always serves the server, because the services are provided outside it: a `Stdio` in the context,
+   * such as a platform layer's real process one, never reaches the server. The type removes `S` from the
+   * server's requirements.
+   */
+  readonly services?: Context.Context<S> | undefined;
 }
 /**
  * An in-process MCP client for a real server layer, over queue-backed stdio.
@@ -164,6 +175,24 @@ interface McpHarnessOptions {
  * }).pipe(Effect.scoped);
  * ```
  *
+ * Services the test also seeds go in `options.services`, built once. End the
+ * session with `harness.close` (the server answers what is in flight, then
+ * stops) or, when a request may never complete, `harness.stop` (the server is
+ * interrupted at once):
+ *
+ * ```ts
+ * import { McpHarness } from "@effected/mcp-kit/testing";
+ * import { Context, Effect } from "effect";
+ *
+ * // `Database` is a service the server's tools need, and the test seeds it.
+ * const program = Effect.gen(function* () {
+ * 	const database = yield* makeDatabase;
+ * 	const harness = yield* McpHarness.make(ServerLayer, { services: Context.make(Database, database) });
+ * 	yield* harness.initialize;
+ * 	yield* harness.stop;
+ * }).pipe(Effect.scoped);
+ * ```
+ *
  * @public
  */
 export declare class McpHarness {
@@ -239,7 +268,7 @@ export declare class McpHarness {
   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>>;
+  static readonly make: <ROut, E, R, S = never>(server: Layer.Layer<ROut, E, R>, options?: McpHarnessOptions<S>) => Effect.Effect<McpHarness, E, Scope.Scope | Exclude<R, Stdio.Stdio | S>>;
 }
 /**
  * Options for {@link McpProbe.initialize}.