@effected/mcp-kit 0.0.0-stage → 0.14.0

package/McpToolkit.js

@@ -0,0 +1,298 @@
+import { ToolFailure } from "./ToolFailure.js";
+import { ToolInputSchema } from "./ToolInputSchema.js";
+import { Context, Effect, Layer, Schema } from "effect";
+import { McpSchema, McpServer, Tool, Toolkit } from "effect/ai";
+
+// src/McpToolkit.ts
+/** The union a {@link McpToolkit.unionTool} decodes with; read by the `McpToolkit.layer` decorator. */
+const UnionParameters = Context.Reference("@effected/mcp-kit/UnionParameters", { defaultValue: () => void 0 });
+/**
+* Effect's strict JSON Schema document for `parameters`, definitions attached
+* as `$defs`, then object-rooted: the served input schema of a union tool.
+*/
+const unionInputJsonSchema = (parameters) => {
+	const document = Schema.toJsonSchemaDocument(parameters, { onExcessProperty: "error" });
+	return ToolInputSchema.objectRooted(Object.keys(document.definitions).length === 0 ? document.schema : {
+		...document.schema,
+		$defs: document.definitions
+	});
+};
+const invalidParameters = (name, message) => new McpSchema.InvalidParams({ message: `Invalid parameters for tool '${name}': ${message}` });
+const MAX_ACCEPTED_LINES = 20;
+/**
+* `path` as core renders an issue path, `["a"][0]["b"]`: a segment indexing
+* an array in `payload` is bare, any other is a JSON string. Truncated, since
+* the segments are the caller's keys.
+*/
+const issuePath = (payload, path) => {
+	let node = payload;
+	let out = "";
+	for (const segment of path) {
+		out += Array.isArray(node) ? `[${segment}]` : `[${JSON.stringify(segment)}]`;
+		node = typeof node === "object" && node !== null ? node[segment] : void 0;
+	}
+	return ToolFailure.truncate(out);
+};
+/**
+* One line per level of `payload` that carries a key the served
+* `inputSchema` does not accept: `Accepted params at <path>: a, b.`, with
+* `keys matching <pattern>` for a level that also accepts keys by
+* `patternProperties`, and `This tool accepts no params.` for a
+* zero-parameter root. At most 20 lines; empty when no level has an
+* unknown key.
+*/
+const acceptedParamsLines = (payload, inputSchema) => ToolInputSchema.unknownKeys(payload, inputSchema).slice(0, MAX_ACCEPTED_LINES).map((level) => {
+	const patterns = level.acceptedPatterns ?? [];
+	if (level.path.length === 0 && level.accepted.length === 0 && patterns.length === 0) return "This tool accepts no params.";
+	const parts = [...level.accepted.length > 0 ? [level.accepted.join(", ")] : [], ...patterns.length > 0 ? [`keys matching ${patterns.join(", ")}`] : []];
+	return `Accepted params at ${level.path.length === 0 ? "the root" : issuePath(payload, level.path)}: ${parts.length > 0 ? parts.join("; ") : "(none)"}.`;
+});
+/**
+* `error` with {@link acceptedParamsLines} appended to its message, one per
+* line after core's own report; `error` itself when there is nothing to add.
+* Core stays the decoder: this only annotates the report it produced.
+*/
+const withAcceptedParams = (error, payload, inputSchema) => {
+	const lines = acceptedParamsLines(payload, inputSchema);
+	return lines.length === 0 ? error : new McpSchema.InvalidParams({
+		message: [error.message, ...lines].join("\n"),
+		...error.data !== void 0 ? { data: error.data } : {}
+	});
+};
+/**
+* The one decode a union tool's payload gets, shared by the `McpToolkit.layer`
+* decorator and {@link McpToolkit.unionHandler}: the union's strict decode
+* with the options core decodes a strict `Tool.make` tool with
+* (`onExcessProperty: "error"`, `errors: "all"`), so every excess, missing and
+* invalid field of the matched member is reported together, worded as core
+* words a `Tool.make` failure, with the accepted params appended as the layer
+* appends them to core's own report.
+*/
+const decodeUnionPayload = (name, union, inputSchema) => {
+	const decode = Schema.decodeUnknownEffect(union);
+	return (payload) => {
+		const raw = payload ?? {};
+		return decode(raw, {
+			onExcessProperty: "error",
+			errors: "all"
+		}).pipe(Effect.mapError((error) => withAcceptedParams(invalidParameters(name, error.message), raw, inputSchema)));
+	};
+};
+/**
+* The registration `McpToolkit.layer` hands core in place of `registration`:
+* a union tool gets its payload decoded first, with the wrapped handler built
+* only after the decode passes, so a rejected payload never reaches it.
+* Anything else is decoded by core as before, and core's parameter failure,
+* the only `InvalidParams` its `handle` fails with, gets the accepted params
+* appended.
+*
+* @internal
+*/
+const guardRegistration = (registration) => {
+	const union = Context.get(registration.annotations, UnionParameters);
+	if (union === void 0) return {
+		...registration,
+		handle: (payload) => registration.handle(payload).pipe(Effect.catchTag("InvalidParams", (error) => Effect.fail(withAcceptedParams(error, payload ?? {}, registration.tool.inputSchema))))
+	};
+	const check = decodeUnionPayload(registration.tool.name, union, registration.tool.inputSchema);
+	return {
+		...registration,
+		handle: (payload) => check(payload).pipe(Effect.flatMap(() => registration.handle(payload)))
+	};
+};
+const DEFAULT_STRICT = "all";
+const strictened = (toolkit, mode) => mode === "annotated" ? toolkit : Toolkit.make(...Object.values(toolkit.tools).map((tool) => Tool.isDynamic(tool) || Tool.getStrictMode(tool) !== void 0 ? tool : tool.annotate(Tool.Strict, true)));
+/**
+* Register a toolkit exactly as core's `McpServer.toolkit` does, except that
+* every tool is strict by default and a {@link McpToolkit.unionTool} gets its
+* union decoded.
+*
+* @remarks
+* Rejection and reporting are core's: a tool annotated `Tool.Strict` is
+* served with `additionalProperties: false` on every object node and decoded
+* with `onExcessProperty: "error"` and `errors: "all"`, so one
+* `InvalidParams` names every excess key at every depth together with every
+* missing or invalid field. The layer appends to that report, never in place
+* of it: for every object level of the payload that carries a key the served
+* input schema does not accept, one line naming what that level does accept,
+* `Accepted params at the root: query, filter.` or
+* `Accepted params at ["filter"]: kind, tag.` (the path as core writes it),
+* with `keys matching <pattern>` for keys a `patternProperties` level
+* accepts, and `This tool accepts no params.` for a zero-parameter tool. An
+* agent can fix the call from the reply alone. A failure with no unknown key
+* (a missing or mistyped field only) is core's report unchanged. The lines
+* are appended to core's `InvalidParams` as it leaves the tool's registered
+* handler, the one failure that handler has for bad parameters.
+*
+* On top of that is the policy: under
+* `strict: "all"` (the default) it annotates every tool that carries no
+* `Tool.Strict` annotation of its own as strict, skipping `Tool.dynamic`
+* tools (core dies at registration on a strict dynamic tool). It runs core's
+* `registerToolkit` unchanged under a registration-scoped `McpServer` whose
+* `addTool` puts the union decode in front of a union tool's handler and
+* passes every other registration through untouched. It patches no core
+* internals: it uses only `McpServer.registerToolkit` and `addTool`.
+*
+* Registration goes through core's module-level `McpServer.McpServer.layer`,
+* shared by reference with `McpStdio.layer`'s own copy — provide both into
+* the same graph, as with `McpServer.toolkit`. Never wrap that layer in
+* `Layer.fresh`: tools would register into a second registry nobody serves.
+* To give two servers separate registries, wrap each whole bundle (this
+* layer together with `McpStdio.layer`) in `Layer.fresh` instead.
+*
+* Each call mints a fresh layer; bind the result to a `const` or the
+* registration runs twice.
+*
+* @example
+* ```ts
+* import { Layer } from "effect";
+* import { McpStdio, McpToolkit } from "@effected/mcp-kit";
+*
+* const ToolsLayer = McpToolkit.layer(MyToolkit).pipe(Layer.provide(MyHandlers));
+* const ServerLayer = ToolsLayer.pipe(Layer.provideMerge(McpStdio.layer({ name: "my-server", version: "1.0.0" })));
+* ```
+*
+* @public
+*/
+var McpToolkit = class {
+	constructor() {}
+	/**
+	* A tool whose parameters are a `Schema.Union` of objects, which
+	* `Tool.make` cannot take: core dies at registration on a non-object
+	* `parameters` root.
+	*
+	* @remarks
+	* The tool is a `Tool.dynamic` served with Effect's strict JSON Schema
+	* document for `parameters` (`additionalProperties: false` on every
+	* object node, definitions as `$defs`), rewritten by
+	* `ToolInputSchema.objectRooted` to an object root carrying `type`,
+	* `oneOf` and `x-discriminator`. Write its handler with
+	* {@link McpToolkit.unionHandler}, which receives the decoded member.
+	*
+	* Registered through {@link McpToolkit.layer}, a union tool gets the same
+	* treatment as a strict `Tool.make` tool: a strict decode with
+	* `errors: "all"` before the handler runs, reporting every excess, missing
+	* and invalid field of the matched member in one `InvalidParams`, with the
+	* same `Accepted params at <path>: …` lines appended, so bad
+	* arguments answer JSON-RPC `-32602` on `2025-06-18` and an `isError`
+	* result on the later revisions, exactly as a `Tool.make` decode failure
+	* does. Registered through core's `McpServer.toolkit` it still decodes
+	* strictly, in the handler, but the `InvalidParams` is then a declared
+	* failure: an `isError` result on every revision.
+	*
+	* Never annotate it `Tool.Strict` true: core dies at registration on a
+	* strict tool with a raw JSON Schema.
+	*
+	* @example
+	* ```ts
+	* import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp-kit";
+	* import { Schema } from "effect";
+	* import { Tool } from "effect/ai";
+	*
+	* // `AddNote`, `ListNotes`, `Added`, `Listed` are object schemas; `Kit` is a Toolkit that includes `Note`.
+	* const Note = McpToolkit.unionTool("note", {
+	*   parameters: Schema.Union([AddNote, ListNotes]),
+	*   success: ToolOutputSchema.objectRooted(Schema.Union([Added, Listed])),
+	*   failure: ToolRefusal,
+	* }).annotate(Tool.Title, "Note")
+	* const handlers = Kit.toLayer({ note: McpToolkit.unionHandler(Note, (params) => handleNote(params)) })
+	* ```
+	*/
+	static unionTool = (name, options) => {
+		const tool = Tool.dynamic(name, {
+			description: options.description,
+			parameters: unionInputJsonSchema(options.parameters),
+			success: options.success ?? Schema.Void,
+			failure: Schema.Union([options.failure ?? Schema.Never, McpSchema.InvalidParams])
+		}).annotate(UnionParameters, options.parameters);
+		return Object.assign(tool, { unionParameters: options.parameters });
+	};
+	/**
+	* The handler for a {@link McpToolkit.unionTool}: decodes the raw payload
+	* exactly as {@link McpToolkit.layer} does, and passes the decoded member
+	* to `handler`.
+	*
+	* @remarks
+	* A payload that does not decode strictly fails with one
+	* `McpSchema.InvalidParams`, worded as core words a `Tool.make` decode
+	* failure, naming every excess key at every depth together with every
+	* missing or invalid field of the matched member, then one
+	* `Accepted params at <path>: …` line per level with an unknown key. It
+	* is the same
+	* implementation the layer runs, so a handler called directly (a test
+	* helper, or a toolkit registered through core's `McpServer.toolkit`)
+	* reports what a client of the layer sees. Under {@link McpToolkit.layer}
+	* the layer has already rejected a bad call before the handler runs.
+	* `options.unknownKeyMessage` is deprecated and ignored.
+	*/
+	static unionHandler = (tool, handler, _options = {}) => {
+		const check = decodeUnionPayload(tool.name, tool.unionParameters, tool.jsonSchema);
+		return (payload) => check(payload).pipe(Effect.flatMap(handler));
+	};
+	/**
+	* `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;
+		const decorated = McpServer.McpServer.of({
+			...registry,
+			addTool: (registration) => registry.addTool(guardRegistration(registration))
+		});
+		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 };