@effected/mcp 0.13.0 → 0.14.0

package/main.d.ts

@@ -15,11 +15,12 @@ export interface MainOptions {
  * `McpGuard.run` installs the crash guards before `load` evaluates the server
  * graph, so a throw during module evaluation is still reported on stderr; this
  * module therefore carries no static runtime import (`Distribution` is
- * type-only). Policy is `exitBeforeConnect` for both events: the one tool is
- * read-only and stateless, so a stray error while serving has no state to
- * corrupt and the guard logs and keeps serving, while the same error before
- * serving means a broken boot and exits `1`. Nothing here writes to stdout;
- * it is the JSON-RPC wire.
+ * type-only). Policy is `exitBeforeConnect` for both events: the server holds
+ * no state between calls, and a stray error while serving is likely a config's
+ * own (config modules run in this process), so the guard logs and keeps
+ * serving, while the same error before serving means a broken boot and exits
+ * `1`. Nothing here writes to stdout; it is the JSON-RPC wire. A config can, so
+ * a tool call runs under `StdioCapture`, its stdout diverted to stderr.
  *
  * @public
  */

package/main.js

@@ -7,11 +7,12 @@ import { McpGuard } from "@effected/mcp-kit/guard";
 * `McpGuard.run` installs the crash guards before `load` evaluates the server
 * graph, so a throw during module evaluation is still reported on stderr; this
 * module therefore carries no static runtime import (`Distribution` is
-* type-only). Policy is `exitBeforeConnect` for both events: the one tool is
-* read-only and stateless, so a stray error while serving has no state to
-* corrupt and the guard logs and keeps serving, while the same error before
-* serving means a broken boot and exits `1`. Nothing here writes to stdout;
-* it is the JSON-RPC wire.
+* type-only). Policy is `exitBeforeConnect` for both events: the server holds
+* no state between calls, and a stray error while serving is likely a config's
+* own (config modules run in this process), so the guard logs and keeps
+* serving, while the same error before serving means a broken boot and exits
+* `1`. Nothing here writes to stdout; it is the JSON-RPC wire. A config can, so
+* a tool call runs under `StdioCapture`, its stdout diverted to stderr.
 *
 * @public
 */
@@ -25,10 +26,18 @@ const main = (options = {}) => McpGuard.run({
 	load: async () => {
 		const NodeRuntime = await import("@effect/platform-node/NodeRuntime");
 		const NodeStdio = await import("@effect/platform-node/NodeStdio");
+		const NodeFileSystem = await import("@effect/platform-node/NodeFileSystem");
+		const NodePath = await import("@effect/platform-node/NodePath");
+		const { StdioCapture } = await import("@effected/mcp-kit/node");
 		const { Layer } = await import("effect");
 		const { ServerLayer } = await import("./server.js");
+		const capture = StdioCapture.install(process);
 		return {
-			layer: ServerLayer(options).pipe(Layer.provide(NodeStdio.layer)),
+			layer: ServerLayer({
+				...options,
+				cwd: process.cwd(),
+				confineStdout: capture.capture({ stdout: capture.toStderr })
+			}).pipe(Layer.provide(Layer.mergeAll(NodeStdio.layer, NodeFileSystem.layer, NodePath.layer))),
 			runMain: NodeRuntime.runMain
 		};
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/mcp",
-	"version": "0.13.0",
+	"version": "0.14.0",
 	"private": false,
 	"description": "The effected-mcp server: the tool's MCP tools on the kit's MCP boundary",
 	"keywords": [
@@ -44,9 +44,11 @@
 	},
 	"dependencies": {
 		"@effect/platform-node": "~4.1.2",
-		"@effected/engine": "^0.12.0",
-		"@effected/kit": "^0.12.0",
-		"@effected/mcp-kit": "^0.13.0",
+		"@effected/engine": "0.13.0",
+		"@effected/glob": "^0.19.0",
+		"@effected/kit": "^0.13.0",
+		"@effected/mcp-kit": "^0.14.0",
+		"@effected/walker": "^0.25.1",
 		"effect": "~4.1.2"
 	},
 	"engines": {

package/server.js

@@ -1,7 +1,8 @@
 import { handleIdentity, identity } from "./tools/identity.js";
+import { makeSchemaHandlers, schemaBuild, schemaCheck, schemaValidate } from "./tools/schema.js";
 import { MCP_VERSION } from "./version.js";
 import { McpStdio, McpToolkit } from "@effected/mcp-kit";
-import { Layer } from "effect";
+import { Effect, Layer } from "effect";
 import { McpProtocol, Toolkit } from "effect/ai";
 
 // src/server.ts
@@ -11,22 +12,30 @@ import { McpProtocol, Toolkit } from "effect/ai";
 *
 * @public
 */
-const SERVER_INSTRUCTIONS = "effected-mcp serves the effected tool. Call identity to learn the tool name, this server's version, the distribution it was launched through and the resolved effect version.";
+const SERVER_INSTRUCTIONS = "effected-mcp serves the effected tool. Call identity to learn the tool name, this server's version, the distribution it was launched through and the resolved effect version. schema_check reports whether the generated schema documents match the config and writes nothing, schema_build writes them, and schema_validate checks a JSON payload against one. Drift, staleness and a failed validation arrive as results (a verdict, or valid: false), not as errors; an error means the config could not be found or loaded, a path was outside the workspace root, or the run could not finish. Each call reloads the config and the TypeScript and JSON it imports, but an imported .mjs, .cjs or built .js under type: module stays cached, so restart this server after rebuilding a sibling package the config uses.";
 /**
-* The whole server as one layer: the `identity` toolkit over the kit's
-* `McpStdio.layer`. The adapters are listed newest first, as the kit's
+* The whole server as one layer: the toolkit over the kit's `McpStdio.layer`,
+* its schema handlers capturing `FileSystem` and `Path` when they are built.
+* The adapters are listed newest first, as the kit's
 * default lists them; a client that opens with `initialize` needs the
 * stateful ones.
 *
 * @public
 */
 const ServerLayer = (options = {}) => {
-	const EffectedToolkit = Toolkit.make(identity);
-	const handlers = EffectedToolkit.toLayer({ identity: () => handleIdentity(options.distribution) });
+	const EffectedToolkit = Toolkit.make(identity, schemaCheck, schemaBuild, schemaValidate);
+	const handlers = EffectedToolkit.toLayer(Effect.map(makeSchemaHandlers(options), (schema) => ({
+		identity: () => handleIdentity(options.distribution),
+		...schema
+	})));
 	return McpStdio.layer({
 		name: "effected",
 		version: MCP_VERSION,
 		instructions: SERVER_INSTRUCTIONS,
+		cacheHints: { tools: {
+			ttl: "1 hour",
+			cacheScope: "private"
+		} },
 		protocols: [
 			McpProtocol.v2026_07_28,
 			McpProtocol.v2025_11_25,

package/tools/schema.js

@@ -0,0 +1,158 @@
+import { ToolFailure, ToolRefusal } from "@effected/mcp-kit";
+import { Effect, FileSystem, Option, Path, Ref, Schema } from "effect";
+import { Tool } from "effect/ai";
+import { ConfigLoader, SchemaRun, SchemaRunResult, SchemaValidate, ValidateReport } from "@effected/engine/schema";
+import { Exclusive, PathContainment } from "@effected/kit";
+import { Walker } from "@effected/walker";
+
+// src/tools/schema.ts
+const CONFIG_DESCRIPTION = "The schemastore config, resolved against the workspace root and refused outside it. Omitted, discovery walks upward from the server's working directory, stopping at the workspace root.";
+const RunParameters = Schema.Struct({
+	config: Schema.optionalKey(Schema.String.annotate({ description: CONFIG_DESCRIPTION })),
+	drift: Schema.optionalKey(Schema.Literals([
+		"strict",
+		"semantic",
+		"allow"
+	]).annotate({ description: "One drift tolerance over every schema's own." })),
+	onDrift: Schema.optionalKey(Schema.Literals(["error", "warn"]).annotate({ description: "Overrides the config's onDrift." })),
+	force: Schema.optionalKey(Schema.Boolean.annotate({ description: "Shorthand for drift \"allow\", and refused beside any other drift." }))
+});
+/**
+* The `schema_check` tool: what `schema_build` would do, writing nothing.
+*
+* @public
+*/
+const schemaCheck = Tool.make("schema_check", {
+	description: "Checks the generated schema documents against the config, writing nothing. Drift and staleness arrive as the result's verdict, with each changed document's full diff; they are not errors. Reloads the config on every call.",
+	parameters: RunParameters,
+	success: SchemaRunResult,
+	failure: ToolRefusal
+}).annotate(Tool.Title, "Check schema documents").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
+/**
+* The `schema_build` tool: writes the generated documents and catalogs.
+*
+* @public
+*/
+const schemaBuild = Tool.make("schema_build", {
+	description: "Generates the schema documents and catalogs the config declares and writes the ones that changed, wherever the config puts them. A refused drift or a failed gate writes nothing and arrives as the result's verdict. Reloads the config on every call.",
+	parameters: RunParameters,
+	success: SchemaRunResult,
+	failure: ToolRefusal
+}).annotate(Tool.Title, "Build schema documents").annotate(Tool.Readonly, false).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
+/**
+* The `schema_validate` tool: does one payload conform to a published document.
+*
+* @public
+*/
+const schemaValidate = Tool.make("schema_validate", {
+	description: "Validates a JSON payload file against a local schema document, with each finding's line and column. A payload that does not conform is valid: false, not an error.",
+	parameters: Schema.Struct({
+		payload: Schema.String.annotate({ description: "The payload file, resolved against the workspace root and refused outside it." }),
+		config: Schema.optionalKey(Schema.String.annotate({ description: CONFIG_DESCRIPTION })),
+		schema: Schema.optionalKey(Schema.String.annotate({ description: "The document: a file path under the workspace root, or an $id or url the config derives. Omitted, the payload's own $schema." }))
+	}),
+	success: ValidateReport,
+	failure: ToolRefusal
+}).annotate(Tool.Title, "Validate a payload").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
+const WALK_TIMEOUT = "2 minutes";
+const findRoot = (cwd) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const chain = yield* Walker.ascend(cwd);
+	const holding = (marker) => Walker.findRoot(chain, (dir) => fs.exists(path.join(dir, marker)));
+	const workspace = yield* holding("pnpm-workspace.yaml");
+	return Option.isSome(workspace) ? workspace.value : Option.getOrElse(yield* holding(".git"), () => cwd);
+});
+const refusalOf = (error, root, mismatch) => {
+	const refuse = (reason, hint, suggestedTool) => ToolRefusal.refuse([ToolFailure.truncate(reason, ToolFailure.ENGINE_ECHO_LIMIT), ...mismatch !== void 0 ? [`Version mismatch: ${mismatch.message}`] : []].join(" "), {
+		hint,
+		...suggestedTool !== void 0 ? { suggestedTool } : {}
+	});
+	switch (error._tag) {
+		case "ConfigNotFoundError": return refuse(error.message, `Add a schemastore.config.ts, or pass config with its path under the workspace root ${root}.`);
+		case "ConfigLoadError": return refuse(`Failed to load schemastore config ${error.path}: ${error.reason.split("\n", 1)[0]}`, "Fix the config and call the tool again; it reloads on every call.");
+		case "ConflictingFlagsError": return refuse(`force means drift "allow", so it conflicts with drift "${error.policy}".`, "Pass one or the other.");
+		case "MissingSchemaRefError": return refuse(`Payload ${error.path} has no "$schema" property.`, "Name the document with the schema parameter: a file path, or an $id or url the config derives.");
+		case "ExclusiveTimeout": return refuse(error.message, "Documents may be part-written; call the tool to see what differs.", "schema_check");
+		default: return refuse(error.message, "Fix what the message names and call the tool again.");
+	}
+};
+const payloadRef = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Struct({ $schema: Schema.String })));
+/**
+* The three handlers, closed over the filesystem and path the server was built with, the workspace root found once
+* from `options.cwd`, and one lane.
+*
+* @remarks
+* `schema_build` and `schema_check` load the config OUTSIDE the lane and hand the engine what was loaded. A timed-out
+* lane interrupts its body, and the engine's `Effect.tryPromise` around the import abandons the promise on interrupt,
+* so a load inside would leave a config still evaluating while the next call holds the permit. A hanging config
+* therefore never holds up another call. `schema_validate` stays out: it only reads one document, and each document is
+* replaced atomically, so it sees the old text or the new.
+*
+* @public
+*/
+const makeSchemaHandlers = (options = {}) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const cwd = path.resolve(options.cwd ?? ".");
+	const root = yield* findRoot(cwd);
+	const lane = yield* Exclusive.make;
+	const importer = options.importModule !== void 0 ? { importModule: options.importModule } : {};
+	const inside = (label, candidate) => Effect.flatMap(PathContainment.isWithin(root, candidate), (within) => within ? Effect.void : Effect.fail(ToolRefusal.refuse(`The ${label} "${ToolFailure.truncate(candidate)}" is outside the workspace root ${root}.`, { hint: `Pass a path under ${root}.` })));
+	const configOf = (config) => config !== void 0 ? Effect.as(inside("config", config), { config }) : Effect.match(ConfigLoader.discover(cwd, root), {
+		onFailure: () => ({}),
+		onSuccess: (found) => ({ config: found })
+	});
+	const call = (run) => Effect.gen(function* () {
+		const warned = yield* Ref.make(void 0);
+		return yield* run((event) => event._tag === "Started" && event.versionMismatch !== void 0 ? Ref.set(warned, event.versionMismatch) : Effect.void).pipe(Effect.catch((error) => error._tag === "ToolRefusal" ? Effect.fail(error) : Effect.gen(function* () {
+			yield* Effect.logDebug("schema tool refused", { error: error.message });
+			return yield* Effect.fail(refusalOf(error, root, yield* Ref.get(warned)));
+		})));
+	}).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path), options.confineStdout ?? ((self) => self));
+	const walk = (mode) => (params) => call((onProgress) => Effect.gen(function* () {
+		const scoped = yield* configOf(params.config);
+		const loaded = yield* ConfigLoader.load({
+			cwd: root,
+			ceiling: root,
+			...scoped.config !== void 0 ? { explicit: scoped.config } : {},
+			...importer
+		});
+		return yield* lane.run(SchemaRun.run({
+			mode,
+			config: loaded.path,
+			...params.drift !== void 0 ? { drift: params.drift } : {},
+			...params.onDrift !== void 0 ? { onDrift: params.onDrift } : {},
+			force: params.force ?? false,
+			versionMismatch: "warn"
+		}, {
+			cwd: root,
+			discoveryCeiling: root,
+			importModule: () => Promise.resolve(loaded.config),
+			onProgress
+		}), { timeout: WALK_TIMEOUT });
+	}));
+	return {
+		schema_check: walk("check"),
+		schema_build: walk("build"),
+		schema_validate: (params) => call((onProgress) => Effect.gen(function* () {
+			yield* inside("payload", params.payload);
+			const ref = params.schema ?? Option.getOrUndefined(Option.map(yield* fs.readFileString(path.resolve(root, params.payload)).pipe(Effect.map((text) => payloadRef(text)), Effect.orElseSucceed(() => Option.none())), (payload) => payload.$schema));
+			if (ref !== void 0) yield* inside("schema", ref);
+			const scoped = yield* configOf(params.config);
+			return yield* SchemaValidate.run({
+				payload: params.payload,
+				...ref !== void 0 ? { schema: ref } : {},
+				...scoped,
+				versionMismatch: "warn"
+			}, {
+				cwd: root,
+				discoveryCeiling: root,
+				...importer,
+				onProgress
+			});
+		}))
+	};
+});
+
+export { makeSchemaHandlers, schemaBuild, schemaCheck, schemaValidate };

package/version.js

@@ -6,6 +6,6 @@
 *
 * @public
 */
-const MCP_VERSION = "0.13.0";
+const MCP_VERSION = "0.14.0";
 
 export { MCP_VERSION };