@okfit/mcp 0.7.0 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -60,16 +60,10 @@ or `.config/okfit.toml`.
60
60
 
61
61
  A failing tool call reaches the client as `isError: true`, with the
62
62
  remediation text folded directly into the message — there is no separate
63
- structured error field on the wire. The five `McpToolError` members:
64
-
65
- - `ConfigError` — config discovery, parsing, or validation failed.
66
- - `BundleNotFound` — the configured bundle root does not exist or could
67
- not be read.
68
- - `ConceptNotFound` — no concept in the bundle has the requested id.
69
- - `UnknownVocabulary` — a requested type or tag name is not declared in
70
- the resolved config.
71
- - `InvalidArgument` — a tool argument was structurally acceptable but
72
- semantically invalid.
63
+ structured error field on the wire. `McpToolError` is `@effected/mcp`'s
64
+ `ToolRefusal`: config failures, an unreadable bundle root, an unknown
65
+ concept id, an undeclared type or tag, and an invalid argument all refuse
66
+ with a message that names the problem and what to do next.
73
67
 
74
68
  ## License
75
69
 
package/errors.js CHANGED
@@ -1,52 +1,21 @@
1
1
  import { Remediation } from "@effected/engine";
2
- import { ToolFailure } from "@effected/mcp";
3
- import { Schema } from "effect";
2
+ import { ToolRefusal } from "@effected/mcp";
4
3
 
5
4
  //#region src/errors.ts
6
5
  /**
7
- * Config discovery, parsing, or validation failed. @public
8
- */
9
- var ConfigError = class extends Schema.TaggedError()("ConfigError", { ...ToolFailure.fields }) {};
10
- /**
11
- * The configured bundle root does not exist or could not be read. @public
12
- */
13
- var BundleNotFound = class extends Schema.TaggedError()("BundleNotFound", {
14
- ...ToolFailure.fields,
15
- root: Schema.String
16
- }) {};
17
- /**
18
- * No concept in the bundle has the requested id. @public
19
- */
20
- var ConceptNotFound = class extends Schema.TaggedError()("ConceptNotFound", {
21
- ...ToolFailure.fields,
22
- id: Schema.String
23
- }) {};
24
- /**
25
- * A requested type or tag name is not declared in the resolved config.
26
- * @public
27
- */
28
- var UnknownVocabulary = class extends Schema.TaggedError()("UnknownVocabulary", {
29
- ...ToolFailure.fields,
30
- kind: Schema.Literals(["type", "tag"]),
31
- requested: Schema.String,
32
- valid: Schema.Array(Schema.String)
33
- }) {};
34
- /**
35
- * A tool argument was structurally acceptable but semantically invalid.
6
+ * The one failure schema every tool declares (N-14): `ToolRefusal` from
7
+ * `@effected/mcp`.
8
+ *
9
+ * @remarks
10
+ * Replaces five bespoke tagged errors. Under `failureMode: "error"` a declared
11
+ * failure reaches the agent as `error.message` alone, so the structured fields
12
+ * they carried were never on the wire; the reason text names them and
13
+ * `ToolRefusal.refuse` folds the remediation in. Callers discriminate on the
14
+ * message, never on a tag.
15
+ *
36
16
  * @public
37
17
  */
38
- var InvalidArgument = class extends Schema.TaggedError()("InvalidArgument", {
39
- ...ToolFailure.fields,
40
- argument: Schema.String
41
- }) {};
42
- /** The one failure schema every tool declares (N-14). @public */
43
- const McpToolError = Schema.Union([
44
- ConfigError,
45
- BundleNotFound,
46
- ConceptNotFound,
47
- UnknownVocabulary,
48
- InvalidArgument
49
- ]);
18
+ const McpToolError = ToolRefusal;
50
19
 
51
20
  //#endregion
52
- export { BundleNotFound, ConceptNotFound, ConfigError, InvalidArgument, McpToolError, Remediation, UnknownVocabulary };
21
+ export { McpToolError, Remediation };
package/index.d.ts CHANGED
@@ -1,82 +1,27 @@
1
1
  import { Remediation } from "@effected/engine";
2
- import { FileSystem, Layer, Path, Schema, Stdio } from "effect";
2
+ import { ToolRefusal } from "@effected/mcp";
3
3
  import { AppDirs, Xdg } from "@effected/xdg";
4
+ import { FileSystem, Layer, Path, Schema, Stdio } from "effect";
4
5
  import { ConceptSummary, Distribution, toConceptSummary } from "@okfit/engine";
5
6
  import { ChildProcessSpawner } from "effect/process";
6
7
  import { Toolkit } from "effect/ai";
7
8
  //#region src/errors.d.ts
8
- declare const ConfigError_base: Schema.Class<ConfigError, Schema.TaggedStruct<"ConfigError", {
9
- readonly message: Schema.String;
10
- readonly remediation: Schema.Struct<{
11
- readonly hint: Schema.String;
12
- readonly suggestedTool: Schema.optionalKey<Schema.String>;
13
- readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
14
- }>;
15
- }>, import("effect/Cause").YieldableError>;
16
- /**
17
- * Config discovery, parsing, or validation failed. @public
18
- */
19
- export declare class ConfigError extends ConfigError_base {}
20
- declare const BundleNotFound_base: Schema.Class<BundleNotFound, Schema.TaggedStruct<"BundleNotFound", {
21
- readonly message: Schema.String;
22
- readonly remediation: Schema.Struct<{
23
- readonly hint: Schema.String;
24
- readonly suggestedTool: Schema.optionalKey<Schema.String>;
25
- readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
26
- }>;
27
- readonly root: Schema.String;
28
- }>, import("effect/Cause").YieldableError>;
29
- /**
30
- * The configured bundle root does not exist or could not be read. @public
31
- */
32
- export declare class BundleNotFound extends BundleNotFound_base {}
33
- declare const ConceptNotFound_base: Schema.Class<ConceptNotFound, Schema.TaggedStruct<"ConceptNotFound", {
34
- readonly message: Schema.String;
35
- readonly remediation: Schema.Struct<{
36
- readonly hint: Schema.String;
37
- readonly suggestedTool: Schema.optionalKey<Schema.String>;
38
- readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
39
- }>;
40
- readonly id: Schema.String;
41
- }>, import("effect/Cause").YieldableError>;
42
9
  /**
43
- * No concept in the bundle has the requested id. @public
44
- */
45
- export declare class ConceptNotFound extends ConceptNotFound_base {}
46
- declare const UnknownVocabulary_base: Schema.Class<UnknownVocabulary, Schema.TaggedStruct<"UnknownVocabulary", {
47
- readonly message: Schema.String;
48
- readonly remediation: Schema.Struct<{
49
- readonly hint: Schema.String;
50
- readonly suggestedTool: Schema.optionalKey<Schema.String>;
51
- readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
52
- }>;
53
- readonly kind: Schema.Literals<readonly ["type", "tag"]>;
54
- readonly requested: Schema.String;
55
- readonly valid: Schema.$Array<Schema.String>;
56
- }>, import("effect/Cause").YieldableError>;
57
- /**
58
- * A requested type or tag name is not declared in the resolved config.
59
- * @public
60
- */
61
- export declare class UnknownVocabulary extends UnknownVocabulary_base {}
62
- declare const InvalidArgument_base: Schema.Class<InvalidArgument, Schema.TaggedStruct<"InvalidArgument", {
63
- readonly message: Schema.String;
64
- readonly remediation: Schema.Struct<{
65
- readonly hint: Schema.String;
66
- readonly suggestedTool: Schema.optionalKey<Schema.String>;
67
- readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
68
- }>;
69
- readonly argument: Schema.String;
70
- }>, import("effect/Cause").YieldableError>;
71
- /**
72
- * A tool argument was structurally acceptable but semantically invalid.
10
+ * The one failure schema every tool declares (N-14): `ToolRefusal` from
11
+ * `@effected/mcp`.
12
+ *
13
+ * @remarks
14
+ * Replaces five bespoke tagged errors. Under `failureMode: "error"` a declared
15
+ * failure reaches the agent as `error.message` alone, so the structured fields
16
+ * they carried were never on the wire; the reason text names them and
17
+ * `ToolRefusal.refuse` folds the remediation in. Callers discriminate on the
18
+ * message, never on a tag.
19
+ *
73
20
  * @public
74
21
  */
75
- export declare class InvalidArgument extends InvalidArgument_base {}
76
- /** The one failure schema every tool declares (N-14). @public */
77
- export declare const McpToolError: Schema.Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
22
+ export declare const McpToolError: typeof ToolRefusal;
78
23
  /** @public */
79
- export type McpToolError = typeof McpToolError.Type;
24
+ export type McpToolError = ToolRefusal;
80
25
  //#endregion
81
26
  //#region src/resources/conceptResource.d.ts
82
27
  /**
@@ -485,7 +430,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
485
430
  }>>;
486
431
  }>>;
487
432
  }>;
488
- readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
433
+ readonly failure: typeof import("@effected/mcp").ToolRefusal;
489
434
  readonly failureMode: "error";
490
435
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
491
436
  readonly describe_vocabulary: import("effect/ai/Tool").Tool<"describe_vocabulary", {
@@ -538,7 +483,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
538
483
  }>>;
539
484
  }>>;
540
485
  }>;
541
- readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
486
+ readonly failure: typeof import("@effected/mcp").ToolRefusal;
542
487
  readonly failureMode: "error";
543
488
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
544
489
  readonly get_concept: import("effect/ai/Tool").Tool<"get_concept", {
@@ -562,7 +507,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
562
507
  readonly field: import("effect/Schema").optionalKey<import("effect/Schema").String>;
563
508
  }>>;
564
509
  }>;
565
- readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
510
+ readonly failure: typeof import("@effected/mcp").ToolRefusal;
566
511
  readonly failureMode: "error";
567
512
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
568
513
  readonly list_concepts: import("effect/ai/Tool").Tool<"list_concepts", {
@@ -585,7 +530,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
585
530
  }>>;
586
531
  readonly total: import("effect/Schema").Int;
587
532
  }>;
588
- readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
533
+ readonly failure: typeof import("@effected/mcp").ToolRefusal;
589
534
  readonly failureMode: "error";
590
535
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
591
536
  readonly stale_report: import("effect/ai/Tool").Tool<"stale_report", {
@@ -608,7 +553,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
608
553
  readonly days_past: import("effect/Schema").Int;
609
554
  }>>;
610
555
  }>;
611
- readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
556
+ readonly failure: typeof import("@effected/mcp").ToolRefusal;
612
557
  readonly failureMode: "error";
613
558
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
614
559
  readonly validate_bundle: import("effect/ai/Tool").Tool<"validate_bundle", {
@@ -649,7 +594,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
649
594
  readonly range: import("effect/Schema").optionalKey<typeof import("@okfit/core").DiagnosticRange>;
650
595
  }>>;
651
596
  }>;
652
- readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
597
+ readonly failure: typeof import("@effected/mcp").ToolRefusal;
653
598
  readonly failureMode: "error";
654
599
  }, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("@effected/git").Git | import("@okfit/profiles").GitHistory | import("effect/Path").Path | import("@effected/xdg").Xdg>;
655
600
  }>;
@@ -695,7 +640,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
695
640
  }>>;
696
641
  }>>;
697
642
  }>;
698
- readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
643
+ readonly failure: typeof import("@effected/mcp").ToolRefusal;
699
644
  readonly failureMode: "error";
700
645
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
701
646
  readonly describe_vocabulary: import("effect/ai/Tool").Tool<"describe_vocabulary", {
@@ -748,7 +693,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
748
693
  }>>;
749
694
  }>>;
750
695
  }>;
751
- readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
696
+ readonly failure: typeof import("@effected/mcp").ToolRefusal;
752
697
  readonly failureMode: "error";
753
698
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
754
699
  readonly get_concept: import("effect/ai/Tool").Tool<"get_concept", {
@@ -772,7 +717,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
772
717
  readonly field: import("effect/Schema").optionalKey<import("effect/Schema").String>;
773
718
  }>>;
774
719
  }>;
775
- readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
720
+ readonly failure: typeof import("@effected/mcp").ToolRefusal;
776
721
  readonly failureMode: "error";
777
722
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
778
723
  readonly list_concepts: import("effect/ai/Tool").Tool<"list_concepts", {
@@ -795,7 +740,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
795
740
  }>>;
796
741
  readonly total: import("effect/Schema").Int;
797
742
  }>;
798
- readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
743
+ readonly failure: typeof import("@effected/mcp").ToolRefusal;
799
744
  readonly failureMode: "error";
800
745
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
801
746
  readonly stale_report: import("effect/ai/Tool").Tool<"stale_report", {
@@ -818,7 +763,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
818
763
  readonly days_past: import("effect/Schema").Int;
819
764
  }>>;
820
765
  }>;
821
- readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
766
+ readonly failure: typeof import("@effected/mcp").ToolRefusal;
822
767
  readonly failureMode: "error";
823
768
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
824
769
  readonly validate_bundle: import("effect/ai/Tool").Tool<"validate_bundle", {
@@ -859,7 +804,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
859
804
  readonly range: import("effect/Schema").optionalKey<typeof import("@okfit/core").DiagnosticRange>;
860
805
  }>>;
861
806
  }>;
862
- readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
807
+ readonly failure: typeof import("@effected/mcp").ToolRefusal;
863
808
  readonly failureMode: "error";
864
809
  }, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("@effected/git").Git | import("@okfit/profiles").GitHistory | import("effect/Path").Path | import("@effected/xdg").Xdg>;
865
810
  }>, never, never>;
package/index.js CHANGED
@@ -1,4 +1,4 @@
1
- import { BundleNotFound, ConceptNotFound, ConfigError, InvalidArgument, McpToolError, Remediation, UnknownVocabulary } from "./errors.js";
1
+ import { McpToolError, Remediation } from "./errors.js";
2
2
  import { ConceptResources } from "./resources/conceptResource.js";
3
3
  import { IndexResource } from "./resources/indexResource.js";
4
4
  import { ConceptSummary, toConceptSummary } from "./schema/ConceptSummary.js";
@@ -7,4 +7,4 @@ import { MCP_VERSION } from "./version.js";
7
7
  import { OkfitToolkit, ToolsLayer } from "./toolkit.js";
8
8
  import { SERVER_INSTRUCTIONS, ServerLayer } from "./server.js";
9
9
 
10
- export { BundleNotFound, ConceptNeighborsSuccess, ConceptNotFound, ConceptResources, ConceptSummary, ConfigError, DescribeVocabularySuccess, DocsPreset, DocsPresetSurface, GetConceptSuccess, IndexResource, InvalidArgument, ListConceptsParams, ListConceptsSuccess, MCP_VERSION, McpToolError, Neighbor, OkfitToolkit, Remediation, SERVER_INSTRUCTIONS, ServerLayer, StaleReportParams, StaleReportSuccess, ToolsLayer, UnknownVocabulary, ValidateBundleParams, toConceptSummary };
10
+ export { ConceptNeighborsSuccess, ConceptResources, ConceptSummary, DescribeVocabularySuccess, DocsPreset, DocsPresetSurface, GetConceptSuccess, IndexResource, ListConceptsParams, ListConceptsSuccess, MCP_VERSION, McpToolError, Neighbor, OkfitToolkit, Remediation, SERVER_INSTRUCTIONS, ServerLayer, StaleReportParams, StaleReportSuccess, ToolsLayer, ValidateBundleParams, toConceptSummary };
@@ -1,37 +1,23 @@
1
- import { ConceptNotFound, InvalidArgument } from "../errors.js";
2
- import { ToolFailure } from "@effected/mcp";
1
+ import { ToolFailure, ToolRefusal } from "@effected/mcp";
3
2
  import { Effect } from "effect";
4
3
 
5
4
  //#region src/internal/conceptNotFound.ts
6
5
  /**
7
6
  * Maps the engine's `QueryConceptNotFoundError` to the tool-facing failure
8
- * `get_concept` and `concept_neighbors` share: `InvalidArgument` for an empty
9
- * id, `ConceptNotFound` otherwise. `message` is composed through
10
- * `ToolFailure.message` at construction, since a declared typed failure under
11
- * `failureMode: "error"` reaches the wire as `error.message` alone.
7
+ * `get_concept` and `concept_neighbors` share: a `ToolRefusal` saying the id
8
+ * is empty, or that no concept has it. `ToolRefusal.refuse` folds the
9
+ * remediation into the message, which is all a declared failure sends.
12
10
  *
13
11
  * @internal
14
12
  */
15
13
  const toConceptLookupFailure = (id, error) => {
16
- if (error.reason === "empty-id") {
17
- const remediation = {
18
- hint: "Pass a bundle-relative concept id such as decisions/cli-exit-codes.",
19
- suggestedTool: "list_concepts"
20
- };
21
- return Effect.fail(new InvalidArgument({
22
- argument: "id",
23
- message: ToolFailure.message("id must not be empty", remediation),
24
- remediation
25
- }));
26
- }
27
- const remediation = {
14
+ if (error.reason === "empty-id") return Effect.fail(ToolRefusal.refuse("id must not be empty", {
15
+ hint: "Pass a bundle-relative concept id such as decisions/cli-exit-codes.",
16
+ suggestedTool: "list_concepts"
17
+ }));
18
+ return Effect.fail(ToolRefusal.refuse(`no concept "${ToolFailure.truncate(id)}" in this bundle`, {
28
19
  hint: "Call list_concepts to see the ids this bundle contains.",
29
20
  suggestedTool: "list_concepts"
30
- };
31
- return Effect.fail(new ConceptNotFound({
32
- id,
33
- message: ToolFailure.message(`no concept "${ToolFailure.truncate(id)}" in this bundle`, remediation),
34
- remediation
35
21
  }));
36
22
  };
37
23
 
@@ -1,13 +1,12 @@
1
- import { InvalidArgument } from "../errors.js";
2
- import { ToolFailure } from "@effected/mcp";
3
- import { DateTime, Effect, Schema } from "effect";
1
+ import { ToolRefusal } from "@effected/mcp";
4
2
  import { Timestamp } from "@okfit/core";
3
+ import { DateTime, Effect, Schema } from "effect";
5
4
 
6
5
  //#region src/internal/resolveNow.ts
7
6
  /**
8
7
  * An optional ISO-8601 `now` argument, else the Effect clock. Decoding
9
8
  * happens here rather than in the parameter schema so a malformed value
10
- * becomes this contract's `InvalidArgument` — with a remediation hint —
9
+ * becomes this contract's `ToolRefusal` — with a remediation hint —
11
10
  * instead of Effect's generic protocol-level `InvalidParams` (J-5).
12
11
  * `OKFIT_NOW` is deliberately NOT read: it is the CLI's own test hook
13
12
  * (F-17), never the server's.
@@ -15,12 +14,7 @@ import { Timestamp } from "@okfit/core";
15
14
  * @internal
16
15
  */
17
16
  const resolveNow = (input) => input === void 0 ? DateTime.now : Schema.decodeUnknownEffect(Timestamp)(input).pipe(Effect.mapError((issue) => {
18
- const remediation = { hint: "now must be an ISO-8601 instant with an explicit offset, for example 2026-09-06T00:00:00Z." };
19
- return new InvalidArgument({
20
- argument: "now",
21
- message: ToolFailure.message(String(issue), remediation),
22
- remediation
23
- });
17
+ return ToolRefusal.refuse(String(issue), { hint: "now must be an ISO-8601 instant with an explicit offset, for example 2026-09-06T00:00:00Z." });
24
18
  }));
25
19
 
26
20
  //#endregion
@@ -1,7 +1,6 @@
1
- import { BundleNotFound, ConfigError } from "../errors.js";
2
- import { ToolFailure } from "@effected/mcp";
3
- import { Effect, Option } from "effect";
1
+ import { ToolRefusal } from "@effected/mcp";
4
2
  import { Bundle } from "@okfit/core";
3
+ import { Effect, Option } from "effect";
5
4
  import { provideConfig, resolveProjectConfig } from "@okfit/engine";
6
5
 
7
6
  //#region src/internal/toolContext.ts
@@ -19,7 +18,7 @@ const messageOf = (error) => {
19
18
  };
20
19
  const CONFIG_HINT = "Check the project's .okfit.toml, okfit.toml, or .config/okfit.toml for a syntax or schema error; remove it to fall back to defaults.";
21
20
  /**
22
- * Config resolution alone, with every failure collapsed to `ConfigError`.
21
+ * Config resolution alone, with every failure collapsed to a `ToolRefusal`.
23
22
  * `describe_vocabulary` and `validate_bundle` use this; every other tool
24
23
  * goes through {@link loadToolContext}.
25
24
  *
@@ -43,10 +42,7 @@ const resolveConfigOnly = (projectRoot) => resolveProjectConfig({
43
42
  hint: CONFIG_HINT,
44
43
  suggestedTool: "describe_vocabulary"
45
44
  };
46
- return new ConfigError({
47
- message: ToolFailure.message(messageOf(cause), remediation),
48
- remediation
49
- });
45
+ return ToolRefusal.refuse(messageOf(cause), remediation);
50
46
  }));
51
47
  /**
52
48
  * Resolve config and load the bundle, fresh, for one tool call (N-9). No
@@ -59,11 +55,7 @@ const loadToolContext = (projectRoot) => Effect.gen(function* () {
59
55
  const resolved = yield* resolveConfigOnly(projectRoot);
60
56
  const bundle = yield* Bundle.load({ root: resolved.bundleRoot }).pipe(Effect.mapError((cause) => {
61
57
  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\`.` };
62
- return new BundleNotFound({
63
- root: resolved.bundleRoot,
64
- message: ToolFailure.message(cause.message, remediation),
65
- remediation
66
- });
58
+ return ToolRefusal.refuse(cause.message, remediation);
67
59
  }));
68
60
  return {
69
61
  projectRoot,
package/main.d.ts CHANGED
@@ -14,25 +14,19 @@ export interface MainOptions {
14
14
  /**
15
15
  * Run the okfit MCP server over stdio. Owns the process.
16
16
  *
17
- * This module deliberately carries NO static imports of the server graph:
18
- * the `uncaughtException` and `unhandledRejection` handlers are registered
19
- * before `NodeRuntime`, `@effected/mcp` and `ServerLayer` are ever
20
- * evaluated, so a throw during module evaluation is still reported on
21
- * stderr rather than crashing silently. Adding a static import here would
22
- * defeat that -- `Distribution` above is a type-only import, so it carries
23
- * no runtime import at all. `@effected/mcp`'s `McpStdio.launch`/`teardown`
24
- * sits AROUND this requirement, not in place of it (design-patterns'
25
- * `carrier-entry-contract.md`).
17
+ * `McpGuard.run` (`@effected/mcp/guard`, itself free of static runtime
18
+ * imports) installs the crash guards before `load` evaluates the server
19
+ * graph, so a throw during module evaluation is still reported on stderr.
20
+ * This module therefore carries no other static runtime import (`Distribution`
21
+ * is type-only). The guard launches the server with `McpStdio.launch` and
22
+ * `McpStdio.teardown` (stdin EOF exits `0`, not `130`).
26
23
  *
27
- * Assembled with `McpStdio.launch`/`McpStdio.teardown` (effect-v4-mcp's
28
- * `server-wiring.md`): `launch` reports a launch failure itself, on
29
- * stderr, before `NodeRuntime.runMain`'s own out-of-scope report could
30
- * print it to stdout -- the JSON-RPC wire; `teardown` maps stdin EOF (a
31
- * normal client disconnect) to exit `0` instead of the default `130`. Both
32
- * replace this module's own hand-rolled equivalents. `ServerLayer`'s stdio
33
- * server (`server.ts`) is built on `McpStdio.layer`, which already merges
34
- * `LogToStderr` into everything it provides, so this module no longer
35
- * assembles a logger itself either.
24
+ * Policy is `exitBeforeConnect` for both events. Every tool is read-only and
25
+ * reloads the bundle per call, so a stray error while serving has no state to
26
+ * corrupt, and dying mid-session would only deregister the tools from the
27
+ * client: the guard logs and keeps serving. Before serving the same error means
28
+ * a broken boot, so it exits `1`. A `load()` that rejects is `startup failed`,
29
+ * exit `1`, whatever the policy.
36
30
  *
37
31
  * @public
38
32
  */
package/main.js CHANGED
@@ -1,54 +1,50 @@
1
+ import { McpGuard } from "@effected/mcp/guard";
2
+
1
3
  //#region src/main.ts
2
- const FATAL_FALLBACK = "okfit-mcp: a fatal error occurred and could not be described.";
3
- const describe = (error) => {
4
- try {
5
- if (error instanceof Error) return error.stack ?? error.message;
6
- return String(error);
7
- } catch {
8
- return FATAL_FALLBACK;
9
- }
10
- };
11
- const fatal = (label, error) => {
12
- process.stderr.write(`okfit-mcp: ${label}: ${describe(error)}\n`);
13
- process.exit(1);
14
- };
4
+ /**
5
+ * The assembled okfit MCP server program.
6
+ *
7
+ * @packageDocumentation
8
+ */
15
9
  /**
16
10
  * Run the okfit MCP server over stdio. Owns the process.
17
11
  *
18
- * This module deliberately carries NO static imports of the server graph:
19
- * the `uncaughtException` and `unhandledRejection` handlers are registered
20
- * before `NodeRuntime`, `@effected/mcp` and `ServerLayer` are ever
21
- * evaluated, so a throw during module evaluation is still reported on
22
- * stderr rather than crashing silently. Adding a static import here would
23
- * defeat that -- `Distribution` above is a type-only import, so it carries
24
- * no runtime import at all. `@effected/mcp`'s `McpStdio.launch`/`teardown`
25
- * sits AROUND this requirement, not in place of it (design-patterns'
26
- * `carrier-entry-contract.md`).
12
+ * `McpGuard.run` (`@effected/mcp/guard`, itself free of static runtime
13
+ * imports) installs the crash guards before `load` evaluates the server
14
+ * graph, so a throw during module evaluation is still reported on stderr.
15
+ * This module therefore carries no other static runtime import (`Distribution`
16
+ * is type-only). The guard launches the server with `McpStdio.launch` and
17
+ * `McpStdio.teardown` (stdin EOF exits `0`, not `130`).
27
18
  *
28
- * Assembled with `McpStdio.launch`/`McpStdio.teardown` (effect-v4-mcp's
29
- * `server-wiring.md`): `launch` reports a launch failure itself, on
30
- * stderr, before `NodeRuntime.runMain`'s own out-of-scope report could
31
- * print it to stdout -- the JSON-RPC wire; `teardown` maps stdin EOF (a
32
- * normal client disconnect) to exit `0` instead of the default `130`. Both
33
- * replace this module's own hand-rolled equivalents. `ServerLayer`'s stdio
34
- * server (`server.ts`) is built on `McpStdio.layer`, which already merges
35
- * `LogToStderr` into everything it provides, so this module no longer
36
- * assembles a logger itself either.
19
+ * Policy is `exitBeforeConnect` for both events. Every tool is read-only and
20
+ * reloads the bundle per call, so a stray error while serving has no state to
21
+ * corrupt, and dying mid-session would only deregister the tools from the
22
+ * client: the guard logs and keeps serving. Before serving the same error means
23
+ * a broken boot, so it exits `1`. A `load()` that rejects is `startup failed`,
24
+ * exit `1`, whatever the policy.
37
25
  *
38
26
  * @public
39
27
  */
40
- const main = async (options = {}) => {
41
- process.on("uncaughtException", (error) => fatal("uncaught exception", error));
42
- process.on("unhandledRejection", (reason) => fatal("unhandled rejection", reason));
43
- const { McpStdio } = await import("@effected/mcp");
44
- const NodeRuntime = await import("@effect/platform-node/NodeRuntime");
45
- const { OkfitPlatform } = await import("@okfit/engine");
46
- const { Layer } = await import("effect");
47
- const { resolveMcpProjectRoot } = await import("./internal/projectRoot.js");
48
- const { ServerLayer } = await import("./server.js");
49
- const Main = ServerLayer(resolveMcpProjectRoot(process.env, process.cwd()), options).pipe(Layer.provide(OkfitPlatform));
50
- NodeRuntime.runMain(McpStdio.launch(Main), { teardown: McpStdio.teardown });
51
- };
28
+ const main = (options = {}) => McpGuard.run({
29
+ label: "okfit-mcp",
30
+ host: process,
31
+ policy: {
32
+ onUncaught: "exitBeforeConnect",
33
+ onRejection: "exitBeforeConnect"
34
+ },
35
+ injectCrash: McpGuard.parseInjectCrash(process.env.OKFIT_MCP_TEST_INJECT_CRASH),
36
+ load: async () => {
37
+ const NodeRuntime = await import("@effect/platform-node/NodeRuntime");
38
+ const { OkfitPlatform } = await import("@okfit/engine");
39
+ const { Layer } = await import("effect");
40
+ const { resolveMcpProjectRoot } = await import("./internal/projectRoot.js");
41
+ const { ServerLayer } = await import("./server.js");
42
+ return {
43
+ layer: ServerLayer(resolveMcpProjectRoot(process.env, process.cwd()), options).pipe(Layer.provide(OkfitPlatform)),
44
+ runMain: NodeRuntime.runMain
45
+ };
46
+ }
47
+ });
52
48
 
53
49
  //#endregion
54
50
  export { main };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@okfit/mcp",
3
- "version": "0.7.0",
3
+ "version": "0.8.1",
4
4
  "private": false,
5
5
  "description": "Model Context Protocol server for okfit: query and understand Open Knowledge Format (OKF) bundles from an agent.",
6
6
  "keywords": [
@@ -44,23 +44,23 @@
44
44
  "okfit-mcp": "bin/okfit-mcp.js"
45
45
  },
46
46
  "dependencies": {
47
- "@effect/platform-node": "^4.0.0",
48
- "@effected/config-file": "^0.14.0",
49
- "@effected/engine": "^0.3.0",
47
+ "@effect/platform-node": "^4.0.2",
48
+ "@effected/config-file": "^0.14.2",
49
+ "@effected/engine": "^0.4.0",
50
50
  "@effected/git": "^0.20.0",
51
51
  "@effected/glob": "^0.10.0",
52
- "@effected/jsonc": "^0.15.0",
53
- "@effected/markdown": "^0.15.0",
54
- "@effected/mcp": "^0.4.0",
55
- "@effected/schemastore": "^0.20.0",
56
- "@effected/toml": "^0.11.0",
52
+ "@effected/jsonc": "^0.15.1",
53
+ "@effected/markdown": "^0.15.1",
54
+ "@effected/mcp": "^0.5.0",
55
+ "@effected/schemastore": "^0.21.2",
56
+ "@effected/toml": "^0.11.1",
57
57
  "@effected/walker": "^0.15.0",
58
58
  "@effected/xdg": "^0.9.0",
59
- "@effected/yaml": "^0.19.0",
60
- "@okfit/core": "0.9.0",
61
- "@okfit/engine": "0.12.0",
59
+ "@effected/yaml": "^0.19.1",
60
+ "@okfit/core": "0.9.1",
61
+ "@okfit/engine": "0.13.1",
62
62
  "@okfit/profiles": "0.9.0",
63
- "effect": "^4.0.0"
63
+ "effect": "^4.0.2"
64
64
  },
65
65
  "engines": {
66
66
  "node": ">=24.11.0"
@@ -1,6 +1,6 @@
1
1
  import { loadToolContext } from "../internal/toolContext.js";
2
- import { Effect, FileSystem, Layer, Path } from "effect";
3
2
  import { Derive } from "@okfit/core";
3
+ import { Effect, FileSystem, Layer, Path } from "effect";
4
4
  import { McpSchema, McpServer } from "effect/ai";
5
5
 
6
6
  //#region src/resources/conceptResource.ts
package/schema/tools.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { ConceptSummary } from "./ConceptSummary.js";
2
- import { Schema } from "effect";
3
2
  import { GraphNodeKind, Status } from "@okfit/core";
3
+ import { Schema } from "effect";
4
4
  import { ContextTag, ContextType } from "@okfit/engine";
5
5
 
6
6
  //#region src/schema/tools.ts
@@ -2,8 +2,8 @@ import { McpToolError } from "../errors.js";
2
2
  import { loadToolContext } from "../internal/toolContext.js";
3
3
  import { GetConceptSuccess } from "../schema/tools.js";
4
4
  import { toConceptLookupFailure } from "../internal/conceptNotFound.js";
5
- import { Effect, FileSystem, Path, Schema } from "effect";
6
5
  import { Derive } from "@okfit/core";
6
+ import { Effect, FileSystem, Path, Schema } from "effect";
7
7
  import { Tool } from "effect/ai";
8
8
  import { ConceptQuery } from "@okfit/engine";
9
9
  import { AppDirs, Xdg } from "@effected/xdg";
@@ -1,8 +1,8 @@
1
- import { McpToolError, UnknownVocabulary } from "../errors.js";
1
+ import { McpToolError } from "../errors.js";
2
2
  import { loadToolContext } from "../internal/toolContext.js";
3
3
  import { toConceptSummary } from "../schema/ConceptSummary.js";
4
4
  import { ListConceptsParams, ListConceptsSuccess } from "../schema/tools.js";
5
- import { ToolFailure } from "@effected/mcp";
5
+ import { ToolFailure, ToolRefusal } from "@effected/mcp";
6
6
  import { Effect, FileSystem, Path } from "effect";
7
7
  import { Tool } from "effect/ai";
8
8
  import { ConceptQuery } from "@okfit/engine";
@@ -47,13 +47,7 @@ const unknown = (kind, requested, valid) => {
47
47
  suggestedTool: "describe_vocabulary"
48
48
  };
49
49
  const rawMessage = `"${ToolFailure.truncate(requested)}" is not a ${kind} declared by this project's okfit config. Valid ${kind}s: ${valid.join(", ")}.`;
50
- return new UnknownVocabulary({
51
- kind,
52
- requested,
53
- valid,
54
- message: ToolFailure.message(rawMessage, remediation),
55
- remediation
56
- });
50
+ return ToolRefusal.refuse(rawMessage, remediation);
57
51
  };
58
52
  /** @public */
59
53
  const handleListConcepts = (projectRoot, params) => Effect.gen(function* () {
@@ -3,8 +3,8 @@ import { loadToolContext } from "../internal/toolContext.js";
3
3
  import { toConceptSummary } from "../schema/ConceptSummary.js";
4
4
  import { StaleReportParams, StaleReportSuccess } from "../schema/tools.js";
5
5
  import { resolveNow } from "../internal/resolveNow.js";
6
- import { DateTime, Effect, FileSystem, Path } from "effect";
7
6
  import { Derive } from "@okfit/core";
7
+ import { DateTime, Effect, FileSystem, Path } from "effect";
8
8
  import { Tool } from "effect/ai";
9
9
  import { AppDirs, Xdg } from "@effected/xdg";
10
10
 
@@ -1,11 +1,11 @@
1
- import { BundleNotFound, InvalidArgument, McpToolError } from "../errors.js";
1
+ import { McpToolError } from "../errors.js";
2
2
  import { resolveConfigOnly } from "../internal/toolContext.js";
3
3
  import { ValidateBundleParams } from "../schema/tools.js";
4
4
  import { resolveNow } from "../internal/resolveNow.js";
5
5
  import { MCP_VERSION } from "../version.js";
6
- import { ToolFailure } from "@effected/mcp";
7
- import { Crypto, Effect, FileSystem, Option, Path } from "effect";
6
+ import { ToolRefusal } from "@effected/mcp";
8
7
  import { OKF_SPEC_VERSION } from "@okfit/core";
8
+ import { Crypto, Effect, FileSystem, Option, Path } from "effect";
9
9
  import { Tool } from "effect/ai";
10
10
  import { DocumentPathError, JsonEnvelope, collect, forDiagnostics, json, provideDocuments, run } from "@okfit/engine";
11
11
  import { Git } from "@effected/git";
@@ -77,20 +77,9 @@ const handleValidateBundle = (projectRoot, params, distribution) => Effect.gen(f
77
77
  profile: resolved.profile,
78
78
  now
79
79
  }).pipe(provideDocuments(resolved.bundleRoot, params.documents ?? []), Effect.mapError((cause) => {
80
- if (cause instanceof DocumentPathError) {
81
- 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)." };
82
- return new InvalidArgument({
83
- argument: "documents",
84
- message: ToolFailure.message(cause.message, remediation),
85
- remediation
86
- });
87
- }
80
+ if (cause instanceof DocumentPathError) return ToolRefusal.refuse(cause.message, { hint: "Give each document path relative to the bundle root, in posix form, naming a .md file once (for example metrics/churn.md)." });
88
81
  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\`.` };
89
- return new BundleNotFound({
90
- root: resolved.bundleRoot,
91
- message: ToolFailure.message(cause.message, remediation),
92
- remediation
93
- });
82
+ return ToolRefusal.refuse(cause.message, remediation);
94
83
  }));
95
84
  const diagnostics = collect(result.report.conformance, result.report.lint, result.profileDiagnostics);
96
85
  const code = forDiagnostics(diagnostics);
package/version.js CHANGED
@@ -5,7 +5,7 @@
5
5
  *
6
6
  * @public
7
7
  */
8
- const MCP_VERSION = "0.7.0";
8
+ const MCP_VERSION = "0.8.1";
9
9
 
10
10
  //#endregion
11
11
  export { MCP_VERSION };