@okfit/mcp 0.5.3 → 0.6.0

package/errors.js

@@ -1,100 +1,43 @@
+import { Remediation } from "@effected/engine";
+import { ToolFailure } from "@effected/mcp";
 import { Schema } from "effect";
 
 //#region src/errors.ts
-/** What a caller should do next about a failed tool call. @public */
-const Remediation = Schema.Struct({
-	hint: Schema.String,
-	suggestedTool: Schema.optionalKey(Schema.String)
-});
 /**
-* Compose a self-contained wire message from a raw cause message and its
-* remediation: the human message, then the hint, then `Try <suggestedTool>.`
-* when one is present. Every `McpToolError` member's `message` field is
-* built through this at construction — under `failureMode: "error"` (the
-* only mode this contract's tools use), `McpServer`'s own `registerToolkit`
-* collapses a caught typed failure to
-* `{ isError: true, content: [{ type: "text", text: error.message }] }`
-* and never surfaces `structuredContent` for it
-* (`.repos/effect/packages/effect/src/unstable/ai/McpServer.ts:1774-1778,1842-1846`
-* at `effect@4.0.0-rc.116`: `toolErrorResult` and `declaredFailureResult`'s
-* `error instanceof Error` branch; confirmed empirically in Task B1's own
-* build). Since rc.116 that declared branch is rendered WITHOUT a log line
-* — only an internal failure goes through `Effect.logError` — so the
-* message text is the whole of what a client ever sees. `remediation` itself is
-* left on the schema unchanged, both for anything that inspects the typed
-* error directly (a defect handler, a future in-process caller) and
-* because it is what this function reads to build `message`.
-*
-* @public
+* Config discovery, parsing, or validation failed. @public
 */
-const composeRemediatedMessage = (message, remediation) => remediation.suggestedTool === void 0 ? `${message} ${remediation.hint}` : `${message} ${remediation.hint} Try ${remediation.suggestedTool}.`;
-const ECHO_LIMIT = 200;
+var ConfigError = class extends Schema.TaggedError()("ConfigError", { ...ToolFailure.fields }) {};
 /**
-* Truncate a caller-supplied value before it is echoed back inside an
-* error's `message` — the only field a `failureMode: "error"` failure
-* actually delivers to the wire (see {@link composeRemediatedMessage}'s
-* doc comment). Without this, a pathological argument (a multi-megabyte
-* `id`, say) is echoed once in the response's `content[0].text` and once
-* more in the corresponding log line, wasting an agent's context on what
-* is usually a pure typo (final whole-branch review, Minor finding 5).
-*
-* @public
-*/
-const truncateEchoed = (value, limit = ECHO_LIMIT) => value.length > limit ? `${value.slice(0, limit)}…` : value;
-/**
-* Config discovery, parsing, or validation failed. `message` is composed
-* through {@link composeRemediatedMessage} at construction, so it is what
-* reaches the wire as `tools/call`'s `content[0].text` (see that
-* function's doc comment for why). @public
-*/
-var ConfigError = class extends Schema.TaggedError()("ConfigError", {
-	message: Schema.String,
-	remediation: Remediation
-}) {};
-/**
-* The configured bundle root does not exist or could not be read.
-* `message` is composed through {@link composeRemediatedMessage} at
-* construction, so it is what reaches the wire as `tools/call`'s
-* `content[0].text`. @public
+* The configured bundle root does not exist or could not be read. @public
 */
 var BundleNotFound = class extends Schema.TaggedError()("BundleNotFound", {
-	root: Schema.String,
-	message: Schema.String,
-	remediation: Remediation
+	...ToolFailure.fields,
+	root: Schema.String
 }) {};
 /**
-* No concept in the bundle has the requested id. `message` is composed
-* through {@link composeRemediatedMessage} at construction, so it is what
-* reaches the wire as `tools/call`'s `content[0].text`. @public
+* No concept in the bundle has the requested id. @public
 */
 var ConceptNotFound = class extends Schema.TaggedError()("ConceptNotFound", {
-	id: Schema.String,
-	message: Schema.String,
-	remediation: Remediation
+	...ToolFailure.fields,
+	id: Schema.String
 }) {};
 /**
 * A requested type or tag name is not declared in the resolved config.
-* `message` is composed through {@link composeRemediatedMessage} at
-* construction, so it is what reaches the wire as `tools/call`'s
-* `content[0].text`. @public
+* @public
 */
 var UnknownVocabulary = class extends Schema.TaggedError()("UnknownVocabulary", {
+	...ToolFailure.fields,
 	kind: Schema.Literals(["type", "tag"]),
 	requested: Schema.String,
-	valid: Schema.Array(Schema.String),
-	message: Schema.String,
-	remediation: Remediation
+	valid: Schema.Array(Schema.String)
 }) {};
 /**
 * A tool argument was structurally acceptable but semantically invalid.
-* `message` is composed through {@link composeRemediatedMessage} at
-* construction, so it is what reaches the wire as `tools/call`'s
-* `content[0].text`. @public
+* @public
 */
 var InvalidArgument = class extends Schema.TaggedError()("InvalidArgument", {
-	argument: Schema.String,
-	message: Schema.String,
-	remediation: Remediation
+	...ToolFailure.fields,
+	argument: Schema.String
 }) {};
 /** The one failure schema every tool declares (N-14). @public */
 const McpToolError = Schema.Union([
@@ -106,4 +49,4 @@ const McpToolError = Schema.Union([
 ]);
 
 //#endregion
-export { BundleNotFound, ConceptNotFound, ConfigError, InvalidArgument, McpToolError, Remediation, UnknownVocabulary, composeRemediatedMessage, truncateEchoed };
+export { BundleNotFound, ConceptNotFound, ConfigError, InvalidArgument, McpToolError, Remediation, UnknownVocabulary };

package/index.d.ts

@@ -1,3 +1,4 @@
+import { Remediation } from "@effected/engine";
 import { FileSystem, Layer, Path, Schema, Stdio } from "effect";
 import { AppDirs, Xdg } from "@effected/xdg";
 import { LoadedConcept } from "@okfit/core";
@@ -5,120 +6,72 @@ import { Distribution } from "@okfit/engine";
 import { ChildProcessSpawner } from "effect/unstable/process";
 import { Toolkit } from "effect/unstable/ai";
 //#region src/errors.d.ts
-/** What a caller should do next about a failed tool call. @public */
-export declare const Remediation: Schema.Struct<{
-  readonly hint: Schema.String;
-  readonly suggestedTool: Schema.optionalKey<Schema.String>;
-}>;
-/** @public */
-export type Remediation = typeof Remediation.Type;
-/**
- * Compose a self-contained wire message from a raw cause message and its
- * remediation: the human message, then the hint, then `Try <suggestedTool>.`
- * when one is present. Every `McpToolError` member's `message` field is
- * built through this at construction — under `failureMode: "error"` (the
- * only mode this contract's tools use), `McpServer`'s own `registerToolkit`
- * collapses a caught typed failure to
- * `{ isError: true, content: [{ type: "text", text: error.message }] }`
- * and never surfaces `structuredContent` for it
- * (`.repos/effect/packages/effect/src/unstable/ai/McpServer.ts:1774-1778,1842-1846`
- * at `effect@4.0.0-rc.116`: `toolErrorResult` and `declaredFailureResult`'s
- * `error instanceof Error` branch; confirmed empirically in Task B1's own
- * build). Since rc.116 that declared branch is rendered WITHOUT a log line
- * — only an internal failure goes through `Effect.logError` — so the
- * message text is the whole of what a client ever sees. `remediation` itself is
- * left on the schema unchanged, both for anything that inspects the typed
- * error directly (a defect handler, a future in-process caller) and
- * because it is what this function reads to build `message`.
- *
- * @public
- */
-export declare const composeRemediatedMessage: (message: string, remediation: Remediation) => string;
-/**
- * Truncate a caller-supplied value before it is echoed back inside an
- * error's `message` — the only field a `failureMode: "error"` failure
- * actually delivers to the wire (see {@link composeRemediatedMessage}'s
- * doc comment). Without this, a pathological argument (a multi-megabyte
- * `id`, say) is echoed once in the response's `content[0].text` and once
- * more in the corresponding log line, wasting an agent's context on what
- * is usually a pure typo (final whole-branch review, Minor finding 5).
- *
- * @public
- */
-export declare const truncateEchoed: (value: string, limit?: number) => string;
 declare const ConfigError_base: Schema.Class<ConfigError, Schema.TaggedStruct<"ConfigError", {
   readonly message: Schema.String;
   readonly remediation: Schema.Struct<{
     readonly hint: Schema.String;
     readonly suggestedTool: Schema.optionalKey<Schema.String>;
+    readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
   }>;
 }>, import("effect/Cause").YieldableError>;
 /**
- * Config discovery, parsing, or validation failed. `message` is composed
- * through {@link composeRemediatedMessage} at construction, so it is what
- * reaches the wire as `tools/call`'s `content[0].text` (see that
- * function's doc comment for why). @public
+ * Config discovery, parsing, or validation failed. @public
  */
 export declare class ConfigError extends ConfigError_base {}
 declare const BundleNotFound_base: Schema.Class<BundleNotFound, Schema.TaggedStruct<"BundleNotFound", {
-  readonly root: Schema.String;
   readonly message: Schema.String;
   readonly remediation: Schema.Struct<{
     readonly hint: Schema.String;
     readonly suggestedTool: Schema.optionalKey<Schema.String>;
+    readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
   }>;
+  readonly root: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /**
- * The configured bundle root does not exist or could not be read.
- * `message` is composed through {@link composeRemediatedMessage} at
- * construction, so it is what reaches the wire as `tools/call`'s
- * `content[0].text`. @public
+ * The configured bundle root does not exist or could not be read. @public
  */
 export declare class BundleNotFound extends BundleNotFound_base {}
 declare const ConceptNotFound_base: Schema.Class<ConceptNotFound, Schema.TaggedStruct<"ConceptNotFound", {
-  readonly id: Schema.String;
   readonly message: Schema.String;
   readonly remediation: Schema.Struct<{
     readonly hint: Schema.String;
     readonly suggestedTool: Schema.optionalKey<Schema.String>;
+    readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
   }>;
+  readonly id: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /**
- * No concept in the bundle has the requested id. `message` is composed
- * through {@link composeRemediatedMessage} at construction, so it is what
- * reaches the wire as `tools/call`'s `content[0].text`. @public
+ * No concept in the bundle has the requested id. @public
  */
 export declare class ConceptNotFound extends ConceptNotFound_base {}
 declare const UnknownVocabulary_base: Schema.Class<UnknownVocabulary, Schema.TaggedStruct<"UnknownVocabulary", {
-  readonly kind: Schema.Literals<readonly ["type", "tag"]>;
-  readonly requested: Schema.String;
-  readonly valid: Schema.$Array<Schema.String>;
   readonly message: Schema.String;
   readonly remediation: Schema.Struct<{
     readonly hint: Schema.String;
     readonly suggestedTool: Schema.optionalKey<Schema.String>;
+    readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
   }>;
+  readonly kind: Schema.Literals<readonly ["type", "tag"]>;
+  readonly requested: Schema.String;
+  readonly valid: Schema.$Array<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * A requested type or tag name is not declared in the resolved config.
- * `message` is composed through {@link composeRemediatedMessage} at
- * construction, so it is what reaches the wire as `tools/call`'s
- * `content[0].text`. @public
+ * @public
  */
 export declare class UnknownVocabulary extends UnknownVocabulary_base {}
 declare const InvalidArgument_base: Schema.Class<InvalidArgument, Schema.TaggedStruct<"InvalidArgument", {
-  readonly argument: Schema.String;
   readonly message: Schema.String;
   readonly remediation: Schema.Struct<{
     readonly hint: Schema.String;
     readonly suggestedTool: Schema.optionalKey<Schema.String>;
+    readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
   }>;
+  readonly argument: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /**
  * A tool argument was structurally acceptable but semantically invalid.
- * `message` is composed through {@link composeRemediatedMessage} at
- * construction, so it is what reaches the wire as `tools/call`'s
- * `content[0].text`. @public
+ * @public
  */
 export declare class InvalidArgument extends InvalidArgument_base {}
 /** The one failure schema every tool declares (N-14). @public */
@@ -371,9 +324,8 @@ export type ValidateBundleParams = typeof ValidateBundleParams.Type;
 /**
  * Everything `ServerLayer` still needs from the platform: the four services
  * `describe_vocabulary`'s declared `Tool.make` dependencies pull through
- * `McpServer.toolkit`'s own `Tool.HandlerServices<Tools>` requirement, plus
- * `Stdio`, which `McpServer.layerStdio` itself requires
- * (`unstable/ai/McpServer.ts:1207-1216`) and which the brief's own
+ * `McpToolkit.layer`'s own `Tool.HandlerServices<Tools>` requirement, plus
+ * `Stdio`, which `McpStdio.layer` itself requires and which the brief's own
  * `PlatformServices` literal omitted.
  *
  * `ChildProcessSpawner` is new (contract §10.3, S-16): `validate_bundle`'s
@@ -415,24 +367,34 @@ export declare const SERVER_INSTRUCTIONS: string;
  * The whole server as one layer: the toolkit, one static resource per
  * concept (`okf://concept/<id>`, built once at boot — see
  * {@link ConceptResources}), and `okf://index` (re-read from disk on every
- * call), over `McpServer.layerStdio`.
+ * call), over `@effected/mcp`'s `McpStdio.layer`.
  *
- * `protocols` ships three adapters, newest first. `McpProtocol.v2026_07_28`
- * is the stateless adapter (SEP-2575): no `initialize`, no session, every
- * request self-identifies through `params._meta`, and the client discovers
- * the server with `server/discover`. The two stateful adapters stay
- * because `initialize` matches stateful adapters only — a client that
- * opens with `initialize` (Claude Code by default, Copilot, Cursor, the
- * Inspector) would otherwise get `METHOD_NOT_FOUND`. Array order is
- * load-bearing: a request with no session and no `_meta` protocol version
- * falls to `protocols[0]`, and `server/discover` advertises every listed
- * adapter in `supportedVersions`. The runtime allows at most one stateless
- * adapter; a second fails the layer with `Cause.IllegalArgumentError`.
- * Never reduce this to one entry.
+ * `McpStdio.layer` (not core's own `McpServer.layerStdio`, hand-wired) is
+ * load-bearing, not a style choice: it wraps core's stdin decoder with a
+ * guard that answers a non-JSON line with a JSON-RPC `-32700` and keeps
+ * serving, where hand-wiring `layerStdio` directly wedges permanently on
+ * the first bad line (effect-v4-mcp's `server-wiring.md#stdin-guard`). It
+ * also merges `LogToStderr` into everything it provides, so `main.ts` no
+ * longer assembles a logger of its own. `McpToolkit.layer` (not core's
+ * `McpServer.toolkit`) reports every unknown argument key a strict tool
+ * call carries, at every depth, in one response, instead of only the
+ * first.
  *
- * `Cause.IllegalArgumentError` in `layerStdio`'s signature is left
- * unhandled: `protocols` is a static literal, so it is an implementer-time
- * defect, not a runtime condition.
+ * `protocols` ships three adapters, newest first -- the same list
+ * `McpStdio.protocols` defaults to, spelled out here since the decision
+ * behind the exact order is this package's own
+ * (`okf/decisions/mcp-stateless-first-protocol-list.md`), not the kit's.
+ * `McpProtocol.v2026_07_28` is the stateless adapter (SEP-2575): no
+ * `initialize`, no session, every request self-identifies through
+ * `params._meta`, and the client discovers the server with
+ * `server/discover`. The two stateful adapters stay because `initialize`
+ * matches stateful adapters only — a client that opens with `initialize`
+ * (Claude Code by default, Copilot, Cursor, the Inspector) would otherwise
+ * get `METHOD_NOT_FOUND`. Array order is load-bearing: a request with no
+ * session and no `_meta` protocol version falls to `protocols[0]`, and
+ * `server/discover` advertises every listed adapter in `supportedVersions`.
+ * The runtime allows at most one stateless adapter; a second fails the
+ * layer. Never reduce this to one entry.
  *
  * @public
  */
@@ -827,5 +789,5 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
  */
 export declare const MCP_VERSION: string;
 //#endregion
-export type { PlatformServices, ServerOptions };
+export { type PlatformServices, Remediation, type ServerOptions };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,4 +1,4 @@
-import { BundleNotFound, ConceptNotFound, ConfigError, InvalidArgument, McpToolError, Remediation, UnknownVocabulary, composeRemediatedMessage, truncateEchoed } from "./errors.js";
+import { BundleNotFound, ConceptNotFound, ConfigError, InvalidArgument, McpToolError, Remediation, UnknownVocabulary } from "./errors.js";
 import { ConceptResources } from "./resources/conceptResource.js";
 import { IndexResource } from "./resources/indexResource.js";
 import { ConceptSummary, toConceptSummary } from "./schema/ConceptSummary.js";
@@ -7,4 +7,4 @@ import { MCP_VERSION } from "./version.js";
 import { OkfitToolkit, ToolsLayer } from "./toolkit.js";
 import { SERVER_INSTRUCTIONS, ServerLayer } from "./server.js";
 
-export { BundleNotFound, ConceptNeighborsSuccess, ConceptNotFound, ConceptResources, ConceptSummary, ConfigError, DescribeVocabularySuccess, GetConceptSuccess, IndexResource, InvalidArgument, ListConceptsParams, ListConceptsSuccess, MCP_VERSION, McpToolError, Neighbor, OkfitToolkit, Remediation, SERVER_INSTRUCTIONS, ServerLayer, StaleReportParams, StaleReportSuccess, ToolsLayer, UnknownVocabulary, ValidateBundleParams, composeRemediatedMessage, toConceptSummary, truncateEchoed };
+export { BundleNotFound, ConceptNeighborsSuccess, ConceptNotFound, ConceptResources, ConceptSummary, ConfigError, DescribeVocabularySuccess, GetConceptSuccess, IndexResource, InvalidArgument, ListConceptsParams, ListConceptsSuccess, MCP_VERSION, McpToolError, Neighbor, OkfitToolkit, Remediation, SERVER_INSTRUCTIONS, ServerLayer, StaleReportParams, StaleReportSuccess, ToolsLayer, UnknownVocabulary, ValidateBundleParams, toConceptSummary };

package/internal/projectRoot.js

@@ -1,14 +1,29 @@
+import { LaunchContext } from "@effected/engine";
+
 //#region src/internal/projectRoot.ts
 /**
-* N-21's precedence, exactly: `OKFIT_PROJECT_DIR`, else
-* `CLAUDE_PROJECT_DIR`, else the process's working directory. Pure over
-* its `env` argument so tests never touch `process.env`. No argv flags:
-* `start-mcp.sh` forwards `"$@"` with nothing in it, and the manifest's
-* `cwd` field is unused.
+* N-21's precedence: `OKFIT_PROJECT_DIR`, else `CLAUDE_PROJECT_DIR`, else
+* `cwd`. Pure over its `env`/`cwd` arguments so tests never touch
+* `process.env`/`process.cwd()` -- both are read once, in `main.ts`, and
+* passed down as plain values (`main.ts` is the only place this package
+* reads `process`).
+*
+* Built on `@effected/engine`'s `LaunchContext.projectDir` with an empty
+* `argv`: this server has no command parser and `start-mcp.sh` forwards no
+* positional arguments, so the only candidates are the two env keys and the
+* cwd fallback. `LaunchContext.projectDir` additionally treats a value
+* still carrying a literal `${VAR}` placeholder as unusable -- protection
+* the old hand-rolled `??` chain did not have -- against an agent host that
+* leaves `CLAUDE_PROJECT_DIR` unexpanded in some launch paths.
 *
 * @internal
 */
-const resolveMcpProjectRoot = (env) => env.OKFIT_PROJECT_DIR ?? env.CLAUDE_PROJECT_DIR ?? process.cwd();
+const resolveMcpProjectRoot = (env, cwd) => LaunchContext.projectDir({
+	argv: [],
+	env,
+	keys: ["OKFIT_PROJECT_DIR", "CLAUDE_PROJECT_DIR"],
+	cwd
+});
 
 //#endregion
 export { resolveMcpProjectRoot };

package/internal/resolveNow.js

@@ -1,4 +1,5 @@
-import { InvalidArgument, composeRemediatedMessage } from "../errors.js";
+import { InvalidArgument } from "../errors.js";
+import { ToolFailure } from "@effected/mcp";
 import { DateTime, Effect, Schema } from "effect";
 import { Timestamp } from "@okfit/core";
 
@@ -17,7 +18,7 @@ const resolveNow = (input) => input === void 0 ? DateTime.now : Schema.decodeUnk
 	const remediation = { hint: "now must be an ISO-8601 instant with an explicit offset, for example 2026-09-06T00:00:00Z." };
 	return new InvalidArgument({
 		argument: "now",
-		message: composeRemediatedMessage(String(issue), remediation),
+		message: ToolFailure.message(String(issue), remediation),
 		remediation
 	});
 }));

package/internal/toolContext.js

@@ -1,4 +1,5 @@
-import { BundleNotFound, ConfigError, composeRemediatedMessage } from "../errors.js";
+import { BundleNotFound, ConfigError } from "../errors.js";
+import { ToolFailure } from "@effected/mcp";
 import { Effect, Option } from "effect";
 import { Bundle } from "@okfit/core";
 import { provideConfig, resolveProjectConfig } from "@okfit/engine";
@@ -43,7 +44,7 @@ const resolveConfigOnly = (projectRoot) => resolveProjectConfig({
 		suggestedTool: "describe_vocabulary"
 	};
 	return new ConfigError({
-		message: composeRemediatedMessage(messageOf(cause), remediation),
+		message: ToolFailure.message(messageOf(cause), remediation),
 		remediation
 	});
 }));
@@ -60,7 +61,7 @@ const loadToolContext = (projectRoot) => Effect.gen(function* () {
 		const remediation = { hint: `The bundle root "${resolved.bundleRoot}" does not exist or could not be read; check the config's [bundle].path, or run \`okfit init\`.` };
 		return new BundleNotFound({
 			root: resolved.bundleRoot,
-			message: composeRemediatedMessage(cause.message, remediation),
+			message: ToolFailure.message(cause.message, remediation),
 			remediation
 		});
 	}));

package/main.d.ts

@@ -16,11 +16,23 @@ export interface MainOptions {
  *
  * This module deliberately carries NO static imports of the server graph:
  * the `uncaughtException` and `unhandledRejection` handlers are registered
- * before `NodeRuntime`, the logger and `ServerLayer` are ever evaluated, so
- * a throw during module evaluation is still reported on stderr rather than
- * crashing silently. Adding a static import here would defeat that --
- * `Distribution` above is a type-only import, so it carries no runtime
- * import at all.
+ * before `NodeRuntime`, `@effected/mcp` and `ServerLayer` are ever
+ * evaluated, so a throw during module evaluation is still reported on
+ * stderr rather than crashing silently. Adding a static import here would
+ * defeat that -- `Distribution` above is a type-only import, so it carries
+ * no runtime import at all. `@effected/mcp`'s `McpStdio.launch`/`teardown`
+ * sits AROUND this requirement, not in place of it (design-patterns'
+ * `carrier-entry-contract.md`).
+ *
+ * Assembled with `McpStdio.launch`/`McpStdio.teardown` (effect-v4-mcp's
+ * `server-wiring.md`): `launch` reports a launch failure itself, on
+ * stderr, before `NodeRuntime.runMain`'s own out-of-scope report could
+ * print it to stdout -- the JSON-RPC wire; `teardown` maps stdin EOF (a
+ * normal client disconnect) to exit `0` instead of the default `130`. Both
+ * replace this module's own hand-rolled equivalents. `ServerLayer`'s stdio
+ * server (`server.ts`) is built on `McpStdio.layer`, which already merges
+ * `LogToStderr` into everything it provides, so this module no longer
+ * assembles a logger itself either.
  *
  * @public
  */

package/main.js

@@ -17,25 +17,37 @@ const fatal = (label, error) => {
 *
 * This module deliberately carries NO static imports of the server graph:
 * the `uncaughtException` and `unhandledRejection` handlers are registered
-* before `NodeRuntime`, the logger and `ServerLayer` are ever evaluated, so
-* a throw during module evaluation is still reported on stderr rather than
-* crashing silently. Adding a static import here would defeat that --
-* `Distribution` above is a type-only import, so it carries no runtime
-* import at all.
+* before `NodeRuntime`, `@effected/mcp` and `ServerLayer` are ever
+* evaluated, so a throw during module evaluation is still reported on
+* stderr rather than crashing silently. Adding a static import here would
+* defeat that -- `Distribution` above is a type-only import, so it carries
+* no runtime import at all. `@effected/mcp`'s `McpStdio.launch`/`teardown`
+* sits AROUND this requirement, not in place of it (design-patterns'
+* `carrier-entry-contract.md`).
+*
+* Assembled with `McpStdio.launch`/`McpStdio.teardown` (effect-v4-mcp's
+* `server-wiring.md`): `launch` reports a launch failure itself, on
+* stderr, before `NodeRuntime.runMain`'s own out-of-scope report could
+* print it to stdout -- the JSON-RPC wire; `teardown` maps stdin EOF (a
+* normal client disconnect) to exit `0` instead of the default `130`. Both
+* replace this module's own hand-rolled equivalents. `ServerLayer`'s stdio
+* server (`server.ts`) is built on `McpStdio.layer`, which already merges
+* `LogToStderr` into everything it provides, so this module no longer
+* assembles a logger itself either.
 *
 * @public
 */
 const main = async (options = {}) => {
 	process.on("uncaughtException", (error) => fatal("uncaught exception", error));
 	process.on("unhandledRejection", (reason) => fatal("unhandled rejection", reason));
+	const { McpStdio } = await import("@effected/mcp");
 	const NodeRuntime = await import("@effect/platform-node/NodeRuntime");
 	const { OkfitPlatform } = await import("@okfit/engine");
-	const { Cause, Exit, Layer, Logger, Runtime } = await import("effect");
+	const { Layer } = await import("effect");
 	const { resolveMcpProjectRoot } = await import("./internal/projectRoot.js");
 	const { ServerLayer } = await import("./server.js");
-	const projectRoot = resolveMcpProjectRoot(process.env);
-	const program = Layer.launch(ServerLayer(projectRoot, options).pipe(Layer.provide(OkfitPlatform), Layer.provide(Logger.layer([Logger.consolePretty()])), Layer.provide(Layer.succeed(Logger.LogToStderr, true))));
-	NodeRuntime.runMain(program, { teardown: (exit, onExit) => Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause) ? onExit(0) : Runtime.defaultTeardown(exit, onExit) });
+	const Main = ServerLayer(resolveMcpProjectRoot(process.env, process.cwd()), options).pipe(Layer.provide(OkfitPlatform));
+	NodeRuntime.runMain(McpStdio.launch(Main), { teardown: McpStdio.teardown });
 };
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/mcp",
-	"version": "0.5.3",
+	"version": "0.6.0",
 	"private": false,
 	"description": "Model Context Protocol server for okfit: query and understand Open Knowledge Format (OKF) bundles from an agent.",
 	"keywords": [
@@ -45,10 +45,12 @@
 	},
 	"dependencies": {
 		"@effect/platform-node": "4.0.0-rc.117",
+		"@effected/engine": "^0.1.0",
 		"@effected/git": "^0.17.0",
+		"@effected/mcp": "^0.1.1",
 		"@effected/xdg": "^0.7.0",
 		"@okfit/core": "0.8.0",
-		"@okfit/engine": "0.8.0",
+		"@okfit/engine": "0.9.0",
 		"@okfit/profiles": "0.8.0",
 		"effect": "4.0.0-rc.117"
 	},

package/server.js

@@ -2,8 +2,9 @@ import { ConceptResources } from "./resources/conceptResource.js";
 import { IndexResource } from "./resources/indexResource.js";
 import { MCP_VERSION } from "./version.js";
 import { OkfitToolkit, ToolsLayer } from "./toolkit.js";
+import { McpStdio, McpToolkit } from "@effected/mcp";
 import { Layer } from "effect";
-import { McpProtocol, McpServer } from "effect/unstable/ai";
+import { McpProtocol } from "effect/unstable/ai";
 import { Git } from "@effected/git";
 import { GitHistory } from "@okfit/profiles";
 
@@ -33,28 +34,38 @@ const SERVER_INSTRUCTIONS = [
 * The whole server as one layer: the toolkit, one static resource per
 * concept (`okf://concept/<id>`, built once at boot — see
 * {@link ConceptResources}), and `okf://index` (re-read from disk on every
-* call), over `McpServer.layerStdio`.
+* call), over `@effected/mcp`'s `McpStdio.layer`.
 *
-* `protocols` ships three adapters, newest first. `McpProtocol.v2026_07_28`
-* is the stateless adapter (SEP-2575): no `initialize`, no session, every
-* request self-identifies through `params._meta`, and the client discovers
-* the server with `server/discover`. The two stateful adapters stay
-* because `initialize` matches stateful adapters only — a client that
-* opens with `initialize` (Claude Code by default, Copilot, Cursor, the
-* Inspector) would otherwise get `METHOD_NOT_FOUND`. Array order is
-* load-bearing: a request with no session and no `_meta` protocol version
-* falls to `protocols[0]`, and `server/discover` advertises every listed
-* adapter in `supportedVersions`. The runtime allows at most one stateless
-* adapter; a second fails the layer with `Cause.IllegalArgumentError`.
-* Never reduce this to one entry.
+* `McpStdio.layer` (not core's own `McpServer.layerStdio`, hand-wired) is
+* load-bearing, not a style choice: it wraps core's stdin decoder with a
+* guard that answers a non-JSON line with a JSON-RPC `-32700` and keeps
+* serving, where hand-wiring `layerStdio` directly wedges permanently on
+* the first bad line (effect-v4-mcp's `server-wiring.md#stdin-guard`). It
+* also merges `LogToStderr` into everything it provides, so `main.ts` no
+* longer assembles a logger of its own. `McpToolkit.layer` (not core's
+* `McpServer.toolkit`) reports every unknown argument key a strict tool
+* call carries, at every depth, in one response, instead of only the
+* first.
 *
-* `Cause.IllegalArgumentError` in `layerStdio`'s signature is left
-* unhandled: `protocols` is a static literal, so it is an implementer-time
-* defect, not a runtime condition.
+* `protocols` ships three adapters, newest first -- the same list
+* `McpStdio.protocols` defaults to, spelled out here since the decision
+* behind the exact order is this package's own
+* (`okf/decisions/mcp-stateless-first-protocol-list.md`), not the kit's.
+* `McpProtocol.v2026_07_28` is the stateless adapter (SEP-2575): no
+* `initialize`, no session, every request self-identifies through
+* `params._meta`, and the client discovers the server with
+* `server/discover`. The two stateful adapters stay because `initialize`
+* matches stateful adapters only — a client that opens with `initialize`
+* (Claude Code by default, Copilot, Cursor, the Inspector) would otherwise
+* get `METHOD_NOT_FOUND`. Array order is load-bearing: a request with no
+* session and no `_meta` protocol version falls to `protocols[0]`, and
+* `server/discover` advertises every listed adapter in `supportedVersions`.
+* The runtime allows at most one stateless adapter; a second fails the
+* layer. Never reduce this to one entry.
 *
 * @public
 */
-const ServerLayer = (projectRoot, options = {}) => Layer.mergeAll(McpServer.toolkit(OkfitToolkit).pipe(Layer.provideMerge(ToolsLayer(projectRoot, options.distribution))), ConceptResources(projectRoot), IndexResource(projectRoot)).pipe(Layer.provide(Layer.mergeAll(Git.layer, GitHistory.layer)), Layer.provide(McpServer.layerStdio({
+const ServerLayer = (projectRoot, options = {}) => Layer.mergeAll(McpToolkit.layer(OkfitToolkit).pipe(Layer.provideMerge(ToolsLayer(projectRoot, options.distribution))), ConceptResources(projectRoot), IndexResource(projectRoot)).pipe(Layer.provide(Layer.mergeAll(Git.layer, GitHistory.layer)), Layer.provide(McpStdio.layer({
 	name: "okfit",
 	version: MCP_VERSION,
 	instructions: SERVER_INSTRUCTIONS,
@@ -63,7 +74,7 @@ const ServerLayer = (projectRoot, options = {}) => Layer.mergeAll(McpServer.tool
 		McpProtocol.v2025_11_25,
 		McpProtocol.v2025_06_18
 	]
-})), Layer.orDie);
+})));
 
 //#endregion
 export { SERVER_INSTRUCTIONS, ServerLayer };

package/tools/conceptNeighbors.js

@@ -1,7 +1,8 @@
-import { ConceptNotFound, InvalidArgument, McpToolError, composeRemediatedMessage, truncateEchoed } from "../errors.js";
+import { ConceptNotFound, InvalidArgument, McpToolError } from "../errors.js";
 import { loadToolContext } from "../internal/toolContext.js";
 import { toConceptSummary } from "../schema/ConceptSummary.js";
 import { ConceptNeighborsSuccess } from "../schema/tools.js";
+import { ToolFailure } from "@effected/mcp";
 import { Effect, FileSystem, Option, Path, Schema } from "effect";
 import { ConceptId, Graph } from "@okfit/core";
 import { Tool } from "effect/unstable/ai";
@@ -31,8 +32,8 @@ const conceptNeighbors = Tool.make("concept_neighbors", {
 /**
 * Deviation from the brief's literal snippet, matching the ruling binding
 * every C task (progress.md): `message` is composed through
-* {@link composeRemediatedMessage} at construction, since a declared typed
-* failure under `failureMode: "error"` never reaches the wire with
+* `ToolFailure.message` (`@effected/mcp`) at construction, since a declared
+* typed failure under `failureMode: "error"` never reaches the wire with
 * `structuredContent` — only `error.message` does.
 *
 * @public
@@ -47,7 +48,7 @@ const handleConceptNeighbors = (projectRoot, params) => Effect.gen(function* ()
 		};
 		return yield* Effect.fail(new InvalidArgument({
 			argument: "id",
-			message: composeRemediatedMessage("id must not be empty", remediation),
+			message: ToolFailure.message("id must not be empty", remediation),
 			remediation
 		}));
 	}
@@ -59,7 +60,7 @@ const handleConceptNeighbors = (projectRoot, params) => Effect.gen(function* ()
 		};
 		return yield* Effect.fail(new ConceptNotFound({
 			id: params.id,
-			message: composeRemediatedMessage(`no concept "${truncateEchoed(params.id)}" in this bundle`, remediation),
+			message: ToolFailure.message(`no concept "${ToolFailure.truncate(params.id)}" in this bundle`, remediation),
 			remediation
 		}));
 	}

package/tools/getConcept.js

@@ -1,6 +1,7 @@
-import { ConceptNotFound, InvalidArgument, McpToolError, composeRemediatedMessage, truncateEchoed } from "../errors.js";
+import { ConceptNotFound, InvalidArgument, McpToolError } from "../errors.js";
 import { loadToolContext } from "../internal/toolContext.js";
 import { GetConceptSuccess } from "../schema/tools.js";
+import { ToolFailure } from "@effected/mcp";
 import { Effect, FileSystem, Option, Path, Schema } from "effect";
 import { ConceptId, Derive, Graph } from "@okfit/core";
 import { Tool } from "effect/unstable/ai";
@@ -32,8 +33,8 @@ const getConcept = Tool.make("get_concept", {
 /**
 * Deviation from the brief's literal snippet, matching the ruling binding
 * every C task (progress.md): `message` is composed through
-* {@link composeRemediatedMessage} at construction, since a declared typed
-* failure under `failureMode: "error"` never reaches the wire with
+* `ToolFailure.message` (`@effected/mcp`) at construction, since a declared
+* typed failure under `failureMode: "error"` never reaches the wire with
 * `structuredContent` — only `error.message` does.
 *
 * @public
@@ -48,7 +49,7 @@ const handleGetConcept = (projectRoot, params) => Effect.gen(function* () {
 		};
 		return yield* Effect.fail(new InvalidArgument({
 			argument: "id",
-			message: composeRemediatedMessage("id must not be empty", remediation),
+			message: ToolFailure.message("id must not be empty", remediation),
 			remediation
 		}));
 	}
@@ -61,7 +62,7 @@ const handleGetConcept = (projectRoot, params) => Effect.gen(function* () {
 		};
 		return yield* Effect.fail(new ConceptNotFound({
 			id: params.id,
-			message: composeRemediatedMessage(`no concept "${truncateEchoed(params.id)}" in this bundle`, remediation),
+			message: ToolFailure.message(`no concept "${ToolFailure.truncate(params.id)}" in this bundle`, remediation),
 			remediation
 		}));
 	}

package/tools/listConcepts.js

@@ -1,7 +1,8 @@
-import { McpToolError, UnknownVocabulary, composeRemediatedMessage, truncateEchoed } from "../errors.js";
+import { McpToolError, UnknownVocabulary } from "../errors.js";
 import { loadToolContext } from "../internal/toolContext.js";
 import { toConceptSummary } from "../schema/ConceptSummary.js";
 import { ListConceptsParams, ListConceptsSuccess } from "../schema/tools.js";
+import { ToolFailure } from "@effected/mcp";
 import { Effect, FileSystem, Path } from "effect";
 import { Derive } from "@okfit/core";
 import { Tool } from "effect/unstable/ai";
@@ -33,24 +34,24 @@ const listConcepts = Tool.make("list_concepts", {
 }).annotate(Tool.Title, "List OKF concepts").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
 /**
 * Deviation from the brief's literal snippet: `message` is composed through
-* {@link composeRemediatedMessage} (per the controller's ruling binding every
-* C task, progress.md), and the raw message embeds the full `valid` list
-* rather than leaving it only on the schema's `valid` field — a declared
-* typed failure under `failureMode: "error"` never reaches the wire with
-* `structuredContent` (B1's finding), so `valid` would otherwise be
-* unreachable to a real caller reading only `content[0].text`.
+* `ToolFailure.message` (`@effected/mcp`), and the raw message embeds the
+* full `valid` list rather than leaving it only on the schema's `valid`
+* field — a declared typed failure under `failureMode: "error"` never
+* reaches the wire with `structuredContent` (B1's finding), so `valid`
+* would otherwise be unreachable to a real caller reading only
+* `content[0].text`.
 */
 const unknown = (kind, requested, valid) => {
 	const remediation = {
 		hint: "Use one of the listed type names, or call describe_vocabulary.",
 		suggestedTool: "describe_vocabulary"
 	};
-	const rawMessage = `"${truncateEchoed(requested)}" is not a ${kind} declared by this project's okfit config. Valid ${kind}s: ${valid.join(", ")}.`;
+	const rawMessage = `"${ToolFailure.truncate(requested)}" is not a ${kind} declared by this project's okfit config. Valid ${kind}s: ${valid.join(", ")}.`;
 	return new UnknownVocabulary({
 		kind,
 		requested,
 		valid,
-		message: composeRemediatedMessage(rawMessage, remediation),
+		message: ToolFailure.message(rawMessage, remediation),
 		remediation
 	});
 };

package/tools/validateBundle.js

@@ -1,8 +1,9 @@
-import { BundleNotFound, InvalidArgument, McpToolError, composeRemediatedMessage } from "../errors.js";
+import { BundleNotFound, InvalidArgument, McpToolError } from "../errors.js";
 import { resolveConfigOnly } from "../internal/toolContext.js";
 import { ValidateBundleParams } from "../schema/tools.js";
 import { resolveNow } from "../internal/resolveNow.js";
 import { MCP_VERSION } from "../version.js";
+import { ToolFailure } from "@effected/mcp";
 import { Crypto, Effect, FileSystem, Option, Path } from "effect";
 import { OKF_SPEC_VERSION } from "@okfit/core";
 import { Tool } from "effect/unstable/ai";
@@ -80,14 +81,14 @@ const handleValidateBundle = (projectRoot, params, distribution) => Effect.gen(f
 			const remediation = { hint: "Give each document path relative to the bundle root, in posix form, naming a .md file once (for example metrics/churn.md)." };
 			return new InvalidArgument({
 				argument: "documents",
-				message: composeRemediatedMessage(cause.message, remediation),
+				message: ToolFailure.message(cause.message, remediation),
 				remediation
 			});
 		}
 		const remediation = { hint: `The bundle root "${resolved.bundleRoot}" does not exist or could not be read; check the config's [bundle].path, or run \`okfit init\`.` };
 		return new BundleNotFound({
 			root: resolved.bundleRoot,
-			message: composeRemediatedMessage(cause.message, remediation),
+			message: ToolFailure.message(cause.message, remediation),
 			remediation
 		});
 	}));

package/tsdoc-metadata.json

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

package/version.js

@@ -5,7 +5,7 @@
 *
 * @public
 */
-const MCP_VERSION = "0.5.3";
+const MCP_VERSION = "0.6.0";
 
 //#endregion
 export { MCP_VERSION };