@effected/mcp 0.12.0 → 0.14.0

package/index.js

@@ -1,10 +1,3 @@
-import { McpStdio } from "./McpStdio.js";
-import { ToolFailure } from "./ToolFailure.js";
-import { ToolInputSchema } from "./ToolInputSchema.js";
-import { McpToolkit } from "./McpToolkit.js";
-import { ToolOutputSchema } from "./ToolOutputSchema.js";
-import { ToolOutcome } from "./ToolOutcome.js";
-import { ToolRefusal } from "./ToolRefusal.js";
-import { ToolReplay } from "./ToolReplay.js";
+import { MCP_VERSION } from "./version.js";
 
-export { McpStdio, McpToolkit, ToolFailure, ToolInputSchema, ToolOutcome, ToolOutputSchema, ToolRefusal, ToolReplay };
+export { MCP_VERSION };

package/main.d.ts

@@ -0,0 +1,28 @@
+import { Distribution } from "@effected/kit";
+/**
+ * Options a carrier's bin shim passes to `main`. `distribution` names
+ * the package the `effected-mcp` bin was installed through; omitted for a
+ * direct install of `@effected/mcp`.
+ *
+ * @public
+ */
+export interface MainOptions {
+  readonly distribution?: Distribution;
+}
+/**
+ * Run the `effected-mcp` server over stdio. Owns the process.
+ *
+ * `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 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
+ */
+export declare const main: (options?: MainOptions) => Promise<void>;
+//# sourceMappingURL=main.d.ts.map

package/main.js

@@ -0,0 +1,46 @@
+import { McpGuard } from "@effected/mcp-kit/guard";
+
+// src/main.ts
+/**
+* Run the `effected-mcp` server over stdio. Owns the process.
+*
+* `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 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
+*/
+const main = (options = {}) => McpGuard.run({
+	label: "effected-mcp",
+	host: process,
+	policy: {
+		onUncaught: "exitBeforeConnect",
+		onRejection: "exitBeforeConnect"
+	},
+	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,
+				cwd: process.cwd(),
+				confineStdout: capture.capture({ stdout: capture.toStderr })
+			}).pipe(Layer.provide(Layer.mergeAll(NodeStdio.layer, NodeFileSystem.layer, NodePath.layer))),
+			runMain: NodeRuntime.runMain
+		};
+	}
+});
+
+export { main };

package/package.json

@@ -1,14 +1,12 @@
 {
 	"name": "@effected/mcp",
-	"version": "0.12.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",
+	"description": "The effected-mcp server: the tool's MCP tools on the kit's MCP boundary",
 	"keywords": [
 		"effect",
 		"mcp",
 		"model-context-protocol",
-		"stdio",
-		"json-rpc",
 		"effected"
 	],
 	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/mcp#readme",
@@ -34,26 +32,24 @@
 			"import": "./index.js",
 			"default": "./index.js"
 		},
-		"./guard": {
-			"types": "./guard.d.ts",
-			"import": "./guard.js",
-			"default": "./guard.js"
-		},
-		"./node": {
-			"types": "./node.d.ts",
-			"import": "./node.js",
-			"default": "./node.js"
-		},
-		"./testing": {
-			"types": "./testing.d.ts",
-			"import": "./testing.js",
-			"default": "./testing.js"
+		"./main": {
+			"types": "./main.d.ts",
+			"import": "./main.js",
+			"default": "./main.js"
 		},
 		"./package.json": "./package.json"
 	},
-	"peerDependencies": {
-		"@effected/engine": "^0.11.0",
-		"effect": "~4.1.0"
+	"bin": {
+		"effected-mcp": "bin/effected-mcp.js"
+	},
+	"dependencies": {
+		"@effect/platform-node": "~4.1.2",
+		"@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": {
 		"node": ">=24.11.0"

package/server.js

@@ -0,0 +1,48 @@
+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 { Effect, Layer } from "effect";
+import { McpProtocol, Toolkit } from "effect/ai";
+
+// src/server.ts
+/**
+* Agent-facing orientation, surfaced as `instructions` in both the
+* `initialize` and `server/discover` results.
+*
+* @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. 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 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, 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,
+			McpProtocol.v2025_06_18
+		],
+		registrations: McpToolkit.layer(EffectedToolkit).pipe(Layer.provide(handlers))
+	});
+};
+
+export { SERVER_INSTRUCTIONS, ServerLayer };

package/tools/identity.js

@@ -0,0 +1,28 @@
+import { MCP_VERSION } from "../version.js";
+import { Effect } from "effect";
+import { Tool } from "effect/ai";
+import { Identity, IdentityReport } from "@effected/engine";
+
+// src/tools/identity.ts
+/**
+* The `identity` tool: what the `effected` tool reports about itself, the
+* same report the `effected` command prints.
+*
+* @public
+*/
+const identity = Tool.make("identity", {
+	description: "Reports the effected tool's identity: the tool name, this server's version, the carrier distribution it was launched through (null for a direct install), and the resolved effect version.",
+	parameters: Tool.EmptyParams,
+	success: IdentityReport
+}).annotate(Tool.Title, "Effected identity").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
+/**
+* The `identity` handler, closed over the carrier distribution.
+*
+* @public
+*/
+const handleIdentity = (distribution) => Effect.suspend(() => Identity.report({
+	version: MCP_VERSION,
+	distribution: distribution ?? null
+}));
+
+export { handleIdentity, identity };

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/tsdoc-metadata.json

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

package/version.js

@@ -0,0 +1,11 @@
+// src/version.ts
+/**
+* The `effected-mcp` server's version. The bundler replaces the exact expression
+* `process.env.__PACKAGE_VERSION__` with the package version at build time, so
+* it must stay spelled this way.
+*
+* @public
+*/
+const MCP_VERSION = "0.14.0";
+
+export { MCP_VERSION };

package/McpGuard.js

@@ -1,81 +0,0 @@
-import { ProcessGuard } from "@effected/engine/guard";
-
-// src/McpGuard.ts
-/**
-* 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} is `ProcessGuard.run` from `@effected/engine/guard`
-* with an MCP launch in its `load`: it 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. A server on another transport (an LSP over
-* `vscode-languageserver`, say) uses `ProcessGuard.run` directly and calls
-* its `markConnected` itself. This entrypoint statically imports only
-* `@effected/engine/guard`, which imports nothing: 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
-*/
-var McpGuard = class {
-	constructor() {}
-	/**
-	* Parse a test-only crash-injection setting into {@link McpGuardRunOptions.injectCrash}: `<at>:<kind>`, where `at`
-	* is `"load"` or `"connected"` and `kind` is `"uncaughtException"` or `"unhandledRejection"`. Anything else, or no
-	* value, is `undefined`. The same grammar as `ProcessGuard.parseInjectCrash` from `@effected/engine/guard`, which
-	* this is, so an MCP launcher need not import the engine guard for it.
-	*
-	* @example
-	* ```ts
-	* McpGuard.parseInjectCrash("load:uncaughtException"); // => { at: "load", kind: "uncaughtException" }
-	* ```
-	*/
-	static parseInjectCrash = ProcessGuard.parseInjectCrash;
-	/** Install the guards, load the server, and launch it. Resolves once the server is launched. */
-	static run = (options) => ProcessGuard.run({
-		label: options.label,
-		host: options.host,
-		policy: options.policy,
-		injectCrash: options.injectCrash,
-		load: async (guard) => {
-			const server = await options.load();
-			if (server.format !== void 0) guard.useFormat(server.format);
-			const { launchGuarded } = await import("./internal/guardLaunch.js");
-			launchGuarded(server, guard.markConnected);
-		}
-	});
-};
-
-export { McpGuard };