@effected/mcp 0.1.1 → 0.3.0

package/ToolInputSchema.js

@@ -77,11 +77,15 @@ const collect = (payload, root) => {
 			if (match === void 0) extra.push(key);
 			else patterned.push([key, match[1]]);
 		}
-		if (extra.length > 0 && isClosed) out.push({
-			path,
-			unknown: extra,
-			accepted
-		});
+		if (extra.length > 0 && isClosed) {
+			const acceptedPatterns = patterns.map(([pattern]) => pattern);
+			out.push({
+				path,
+				unknown: extra,
+				accepted,
+				...acceptedPatterns.length > 0 ? { acceptedPatterns } : {}
+			});
+		}
 		for (const key of accepted) if (Object.hasOwn(value, key)) walk(value[key], properties[key], [...path, key], depth + 1);
 		for (const [key, schema] of patterned) walk(value[key], schema, [...path, key], depth + 1);
 		if (additional !== void 0) for (const key of extra) walk(value[key], additional, [...path, key], depth + 1);
@@ -94,10 +98,12 @@ const collect = (payload, root) => {
 * depth, a message naming them all, and an object-rooted form of a union.
 *
 * @remarks
-* Core's `Tool.Strict` rejects unknown keys but reports only the first
-* (effect `unstable/ai/McpServer.ts` decodes without `errors: "all"`), so an
-* agent fixes one typo per round trip. These walkers run over the schema core
-* actually serves, so what they accept matches what the tool advertises:
+* For a `Tool.make` tool, core's strict decode already names every unknown
+* key, with every missing or invalid field, in one response. Core never
+* validates a `Tool.dynamic` tool's raw JSON Schema, so these walkers are
+* for that case: a handler runs them against the schema it registered.
+* They run over the schema as served, so what they accept matches what the
+* tool advertises:
 *
 * - Only `additionalProperties: false` closes a node, as in JSON Schema; core
 *   emits it on every object node of a strict tool and `true` otherwise.
@@ -108,6 +114,9 @@ const collect = (payload, root) => {
 * - `items`, `prefixItems`, `$ref` into `$defs` (JSON Pointer escapes
 *   honoured), and `patternProperties` are followed; a key matched by a
 *   pattern is accepted and walked with the first matching pattern's schema.
+*   Effect serves a pattern-keyed `Schema.Record` with `patternProperties`
+*   only when the key pattern's RegExp has the `u` flag; without it the
+*   record is served open, and every key is accepted.
 * - The payload is untrusted: the walk stops descending at depth 256 rather
 *   than overflowing the stack, so a deeper unknown key goes unreported and
 *   is left for decoding. Every hop counts toward that cap: each property or
@@ -121,17 +130,22 @@ var ToolInputSchema = class {
 	/** Every level of `payload` that carries a key `schema` does not accept. */
 	static unknownKeys = (payload, schema) => collect(payload, schema);
 	/**
-	* `Unrecognized parameter(s): a, b.c. Accepted params: x, y.` per level. Each
-	* echoed key is truncated, and at most 20 keys and 20 levels are named; a
-	* trailing `(and N more levels).` counts the levels left out.
+	* `Unrecognized parameter(s): a, b.c. Accepted params: x, y.` per level,
+	* followed by `Accepted keys matching: ^x-.` when the level also accepts
+	* keys by pattern. A level that accepts keys only by pattern names its
+	* patterns alone, never `Accepted params: (none).` Each echoed key and
+	* pattern is truncated, and at most 20 keys, 20 patterns and 20 levels are
+	* named; a trailing `(and N more levels).` counts the levels left out.
 	*/
 	static formatUnknownKeys = (levels, options = {}) => {
 		const limit = options.echoLimit ?? ToolFailure.ECHO_LIMIT;
 		const sentences = levels.slice(0, MAX_ECHOED).map((level) => {
 			const shown = level.unknown.slice(0, MAX_ECHOED).map((key) => ToolFailure.truncate([...level.path, key].join("."), limit));
 			const more = level.unknown.length > MAX_ECHOED ? ` (and ${level.unknown.length - MAX_ECHOED} more)` : "";
-			const accepted = level.accepted.length === 0 ? "(none)" : level.accepted.join(", ");
-			return `Unrecognized parameter(s): ${shown.join(", ")}${more}. Accepted params: ${accepted}.`;
+			const patterns = (level.acceptedPatterns ?? []).slice(0, MAX_ECHOED).map((pattern) => ToolFailure.truncate(pattern, limit));
+			const params = level.accepted.length > 0 ? ` Accepted params: ${level.accepted.join(", ")}.` : patterns.length === 0 ? " Accepted params: (none)." : "";
+			const matching = patterns.length > 0 ? ` Accepted keys matching: ${patterns.join(", ")}.` : "";
+			return `Unrecognized parameter(s): ${shown.join(", ")}${more}.${params}${matching}`;
 		});
 		const hidden = levels.length > MAX_ECHOED ? ` (and ${levels.length - MAX_ECHOED} more levels).` : "";
 		return `${sentences.join(" ")}${hidden}`;

package/ToolOutputSchema.js

@@ -0,0 +1,66 @@
+import { Schema, SchemaAST } from "effect";
+
+//#region src/ToolOutputSchema.ts
+const MARK = "~effected/mcp/objectRooted";
+/** Always passes; contributes `type: "object"` beside whatever the node already emits. */
+const objectRoot = Schema.makeFilter(() => true, {
+	[MARK]: true,
+	toJsonSchema: () => ({ type: "object" })
+});
+const isObjectRooted = (ast) => ast.checks?.some((check) => check.annotations?.[MARK] === true) === true;
+/**
+* Shaping for a tool's `success` schema, so the `outputSchema` core serves
+* is one every client accepts.
+*
+* @remarks
+* MCP requires a tool's `outputSchema` to be rooted in an object, and a
+* top-level `Schema.Union` emits a bare `anyOf`. Core drops such an
+* `outputSchema` from `tools/list` on the stateful revisions and serves it
+* verbatim on the stateless one, where strict clients reject it.
+* `McpToolAudit`'s `objectRootedOutput` check reports it either way.
+*
+* {@link ToolOutputSchema.objectRooted} is the fix when every member of the
+* union is an object shape; never apply it to a union with a primitive or
+* array member. It works on the Effect
+* schema, not on JSON Schema — unlike `ToolInputSchema.objectRooted`, which
+* rewrites the served input document of a `Tool.dynamic`.
+*
+* @public
+*/
+var ToolOutputSchema = class {
+	constructor() {}
+	/**
+	* `schema` with `type: "object"` added beside the `anyOf` at its JSON
+	* Schema root, through a check that always passes. Decoding, encoding and
+	* the schema's type are unchanged.
+	*
+	* @remarks
+	* Order against `.annotate({ identifier })` does not matter. A check added
+	* after an identifier starts a new node that would drop the definition
+	* name, so the identifier the schema already resolves is carried onto the
+	* new check, and the served documents are equal either way (key order
+	* can differ when the schema carries a title or description). Applying it
+	* twice is a no-op.
+	*
+	* Every union member must be an object shape: the added `type: "object"`
+	* is a claim about the whole union, and nothing checks it. Do not use it
+	* on a union with a primitive or array member — the served schema would
+	* contradict the values the tool returns; give such a tool an object
+	* envelope instead.
+	*
+	* @example
+	* ```ts
+	* const Result = ToolOutputSchema.objectRooted(Schema.Union([Found, Missing])).annotate({ identifier: "Result" })
+	* Tool.make("lookup", { parameters, success: Result })
+	* ```
+	*/
+	static objectRooted = (schema) => {
+		if (isObjectRooted(schema.ast)) return schema;
+		const identifier = SchemaAST.resolveIdentifier(schema.ast);
+		const checked = schema.check(objectRoot);
+		return identifier === void 0 ? checked : checked.annotate({ identifier });
+	};
+};
+
+//#endregion
+export { ToolOutputSchema };

package/ToolRefusal.js

@@ -0,0 +1,42 @@
+import { ToolFailure } from "./ToolFailure.js";
+import { Schema } from "effect";
+
+//#region src/ToolRefusal.ts
+/**
+* A tool call refused for a reason the caller can fix: the kit's ready-made
+* declared failure, built on {@link ToolFailure.fields}.
+*
+* @remarks
+* Core scrubs every undeclared failure and every defect to one generic
+* internal-error sentence, so a refusal the agent must act on (an unknown id,
+* a missing argument, a precondition) reaches it only when the tool declares
+* it. Declare `ToolRefusal` in the tool's `failure` schema and fail with
+* {@link ToolRefusal.refuse}; its message already carries the remediation,
+* because a declared `Error` failure sends `message` and nothing else.
+*
+* Audit every throw path when porting a tool: any failure left undeclared
+* loses its message on the wire, however carefully it was worded.
+*
+* @example
+* ```ts
+* const Lookup = Tool.make("lookup", { parameters, success, failure: ToolRefusal })
+* // in the handler:
+* return yield* ToolRefusal.refuse(`No run "${ToolFailure.truncate(id)}".`, { hint: "List runs first.", suggestedTool: "list_runs" })
+* ```
+*
+* @public
+*/
+var ToolRefusal = class ToolRefusal extends Schema.TaggedError()("ToolRefusal", ToolFailure.fields) {
+	/**
+	* A refusal for `reason`, with `remediation` folded into its message by
+	* {@link ToolFailure.message}. `reason` must already truncate any
+	* caller-supplied value it echoes, with {@link ToolFailure.truncate}.
+	*/
+	static refuse = (reason, remediation) => new ToolRefusal({
+		message: ToolFailure.message(reason, remediation),
+		remediation
+	});
+};
+
+//#endregion
+export { ToolRefusal };

package/guard.d.ts

@@ -0,0 +1,157 @@
+import { Effect, Layer, Runtime } from "effect";
+//#region src/McpGuard.d.ts
+/**
+ * The slice of the host process the guard uses. Node's `process` satisfies it.
+ *
+ * @public
+ */
+interface McpGuardHost {
+  /** Register the `uncaughtException` listener. */
+  on(event: "uncaughtException", listener: (error: Error, origin: string) => void): unknown;
+  /** Register the `unhandledRejection` listener. */
+  on(event: "unhandledRejection", listener: (reason: unknown) => void): unknown;
+  /** Raise an `uncaughtException` to the registered listeners. Used only by {@link McpGuardRunOptions.injectCrash}. */
+  emit(event: "uncaughtException", error: Error, origin: "uncaughtException" | "unhandledRejection"): unknown;
+  /** Raise an `unhandledRejection` to the registered listeners. Used only by {@link McpGuardRunOptions.injectCrash}. */
+  emit(event: "unhandledRejection", reason: unknown, promise: Promise<unknown>): unknown;
+  /** Where every guard report is written. Never stdout: that is the JSON-RPC wire. */
+  readonly stderr: {
+    write(chunk: string): unknown;
+  };
+  /** End the process at once. */
+  exit(code?: number): never;
+}
+/**
+ * When a stray exception or rejection ends the process.
+ *
+ * @remarks
+ * `"exit"` exits 1 whenever it happens. `"exitBeforeConnect"` exits 1 until
+ * the server is serving, then logs and keeps serving: a server that dies
+ * mid-session deregisters every tool from the client. `"log"` never exits.
+ *
+ * @public
+ */
+interface McpGuardPolicy {
+  /** For `uncaughtException`. */
+  readonly onUncaught: "exit" | "exitBeforeConnect";
+  /** For `unhandledRejection`. Defaults to `"exit"`. */
+  readonly onRejection?: "exit" | "exitBeforeConnect" | "log" | undefined;
+}
+/**
+ * What {@link McpGuardRunOptions.load} resolves to: the server and the
+ * platform runner to launch it with.
+ *
+ * @public
+ */
+interface McpGuardedServer<ROut, E> {
+  /** The whole server layer, stdio included, with nothing left to provide. */
+  readonly layer: Layer.Layer<ROut, E, never>;
+  /** The platform's `runMain`, such as `NodeRuntime.runMain` from `@effect/platform-node`. */
+  readonly runMain: (effect: Effect.Effect<never, Error>, options: {
+    readonly teardown: Runtime.Teardown;
+  }) => void;
+  /** Formats a reported error from here on; the guard's own dependency-free formatter until then. */
+  readonly format?: ((error: unknown) => string) | undefined;
+}
+/**
+ * Options for {@link McpGuard.run}.
+ *
+ * @public
+ */
+interface McpGuardRunOptions<ROut, E> {
+  /** Prefixes every report the guard writes, as in `my-server: uncaughtException (…): …`. */
+  readonly label: string;
+  /** The process: pass `process`. */
+  readonly host: McpGuardHost;
+  /** Defaults to `{ onUncaught: "exit", onRejection: "exit" }`. */
+  readonly policy?: McpGuardPolicy | undefined;
+  /**
+   * Import and assemble the server. Everything that can throw while loading
+   * belongs here, behind a dynamic `import()`, so the guards are already
+   * listening when it runs.
+   */
+  readonly load: () => Promise<McpGuardedServer<ROut, E>>;
+  /**
+   * For a test of the guards themselves: raise one stray `kind` at `at`, so
+   * both halves of a policy can be driven end to end in a real process.
+   *
+   * @remarks
+   * - `"load"` raises it once both listeners are installed and before
+   *   `load()` is called, then waits for the guard to handle it: `load()`
+   *   is not called until the listener has run. If a test double's `exit`
+   *   throws instead of ending the process, `run` rejects with what it
+   *   threw and never calls `load()`. The pre-connect half of
+   *   the policy applies, so `"exitBeforeConnect"` exits 1 here, and only
+   *   an `onRejection` of `"log"` lets the process go on to load and serve.
+   *   The report uses the guard's own formatter, since no `format` is
+   *   loaded yet.
+   * - `"connected"` raises it on a timer right after the server is
+   *   serving, where `"exitBeforeConnect"` logs and keeps serving. A throw
+   *   from a test double's `exit` there is dropped.
+   *
+   * Either is raised only through `host.emit`, on a `setTimeout(0)` tick,
+   * never as a real throw or rejection, so the guard's listeners handle it
+   * the same way under the real `process` and under a test double. Under
+   * `process`, every listener registered for the event sees it, not only
+   * the guard's. It carries an `[injected]` message; a rejection is emitted
+   * with an already-handled rejected promise. `undefined`, or
+   * an `at` or `kind` outside these values, does nothing at all. Wire it to
+   * an environment variable only a test sets.
+   */
+  readonly injectCrash?: {
+    readonly at: "load" | "connected";
+    readonly kind: "uncaughtException" | "unhandledRejection";
+  } | undefined;
+}
+/**
+ * Crash guards for an MCP server process, installed before the server's
+ * module graph is loaded. Imported from `@effected/mcp/guard`.
+ *
+ * @remarks
+ * {@link McpGuard.run} registers `uncaughtException` and `unhandledRejection`
+ * listeners on `host`, then awaits `load()`, then launches the server with
+ * `McpStdio.launch` and `McpStdio.teardown` under the `runMain` it returned.
+ * This entrypoint has no static runtime import: it loads `effect` and the
+ * stdio wiring only after the guards are listening, so a throw while any of
+ * it evaluates is still reported on stderr.
+ *
+ * - "Connected" means the whole server layer has built, so stdin is being
+ *   read. That is before any client sends `initialize`.
+ * - `injectCrash` drives either half of the policy from a test, before
+ *   `load()` or once connected; unset, it does nothing.
+ * - A `load()` that rejects is reported as `startup failed` and exits 1
+ *   whatever the policy. Left to a log-only rejection listener, it would
+ *   let the event loop drain and exit 0 with no server.
+ * - Installing an `unhandledRejection` listener switches off Node's default
+ *   of throwing on one, so `"log"` really does keep the process running.
+ * - An exit from a guard skips Effect's finalizers and the teardown.
+ * - Keeping on serving after a crash works because the platform `runMain`
+ *   holds the process open while the server fiber lives.
+ * - A layer that fails to build is still reported by `McpStdio.launch`.
+ *
+ * @example
+ * ```ts
+ * import { McpGuard } from "@effected/mcp/guard";
+ *
+ * await McpGuard.run({
+ *   label: "my-server",
+ *   host: process,
+ *   policy: { onUncaught: "exitBeforeConnect", onRejection: "log" },
+ *   load: async () => {
+ *     const { NodeRuntime } = await import("@effect/platform-node");
+ *     const { Main } = await import("./server.js");
+ *     return { layer: Main, runMain: NodeRuntime.runMain };
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare class McpGuard {
+  private constructor();
+  /** Install the guards, load the server, and launch it. Resolves once the server is launched. */
+  static readonly run: <ROut, E>(options: McpGuardRunOptions<ROut, E>) => Promise<void>;
+}
+//#endregion
+export type { McpGuardHost, McpGuardPolicy, McpGuardRunOptions, McpGuardedServer };
+//# sourceMappingURL=guard.d.ts.map

package/guard.js

@@ -0,0 +1,3 @@
+import { McpGuard } from "./McpGuard.js";
+
+export { McpGuard };