@okfit/mcp 0.6.8 → 0.8.0

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
9
  /**
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
- /**
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
  /**
@@ -144,6 +89,47 @@ export declare const ConceptResources: (projectRoot: string) => Layer.Layer<neve
144
89
  export declare const IndexResource: (projectRoot: string) => import("effect/Layer").Layer<never, never, import("@effected/xdg").AppDirs | FileSystem.FileSystem | Path.Path | import("@effected/xdg").Xdg>;
145
90
  //#endregion
146
91
  //#region src/schema/tools.d.ts
92
+ /** One Surface template inside a docs preset, as `describe_vocabulary` reports it. @public */
93
+ export declare const DocsPresetSurface: Schema.Struct<{
94
+ readonly file: Schema.String;
95
+ readonly frontmatter: Schema.Struct<{
96
+ readonly type: Schema.Literal<"Surface">;
97
+ readonly status: Schema.Literal<"draft">;
98
+ readonly title: Schema.String;
99
+ readonly description: Schema.String;
100
+ readonly kind: Schema.Literals<readonly ["site", "repo", "readme"]>;
101
+ readonly audience: Schema.Literals<readonly ["users", "contributors", "agents"]>;
102
+ readonly resource: Schema.String;
103
+ readonly links_to: Schema.optionalKey<Schema.String>;
104
+ readonly url: Schema.optionalKey<Schema.String>;
105
+ }>;
106
+ readonly body: Schema.String;
107
+ }>;
108
+ /** @public */
109
+ export type DocsPresetSurface = typeof DocsPresetSurface.Type;
110
+ /** One docs-surface preset the active profile offers. @public */
111
+ export declare const DocsPreset: Schema.Struct<{
112
+ readonly name: Schema.String;
113
+ readonly description: Schema.String;
114
+ readonly additive: Schema.Boolean;
115
+ readonly surfaces: Schema.$Array<Schema.Struct<{
116
+ readonly file: Schema.String;
117
+ readonly frontmatter: Schema.Struct<{
118
+ readonly type: Schema.Literal<"Surface">;
119
+ readonly status: Schema.Literal<"draft">;
120
+ readonly title: Schema.String;
121
+ readonly description: Schema.String;
122
+ readonly kind: Schema.Literals<readonly ["site", "repo", "readme"]>;
123
+ readonly audience: Schema.Literals<readonly ["users", "contributors", "agents"]>;
124
+ readonly resource: Schema.String;
125
+ readonly links_to: Schema.optionalKey<Schema.String>;
126
+ readonly url: Schema.optionalKey<Schema.String>;
127
+ }>;
128
+ readonly body: Schema.String;
129
+ }>>;
130
+ }>;
131
+ /** @public */
132
+ export type DocsPreset = typeof DocsPreset.Type;
147
133
  /** `describe_vocabulary`'s result (§5.2). @public */
148
134
  export declare const DescribeVocabularySuccess: Schema.Struct<{
149
135
  readonly project_root: Schema.String;
@@ -172,6 +158,26 @@ export declare const DescribeVocabularySuccess: Schema.Struct<{
172
158
  readonly name: Schema.String;
173
159
  readonly description: Schema.NullOr<Schema.String>;
174
160
  }>>;
161
+ readonly docs_presets: Schema.$Array<Schema.Struct<{
162
+ readonly name: Schema.String;
163
+ readonly description: Schema.String;
164
+ readonly additive: Schema.Boolean;
165
+ readonly surfaces: Schema.$Array<Schema.Struct<{
166
+ readonly file: Schema.String;
167
+ readonly frontmatter: Schema.Struct<{
168
+ readonly type: Schema.Literal<"Surface">;
169
+ readonly status: Schema.Literal<"draft">;
170
+ readonly title: Schema.String;
171
+ readonly description: Schema.String;
172
+ readonly kind: Schema.Literals<readonly ["site", "repo", "readme"]>;
173
+ readonly audience: Schema.Literals<readonly ["users", "contributors", "agents"]>;
174
+ readonly resource: Schema.String;
175
+ readonly links_to: Schema.optionalKey<Schema.String>;
176
+ readonly url: Schema.optionalKey<Schema.String>;
177
+ }>;
178
+ readonly body: Schema.String;
179
+ }>>;
180
+ }>>;
175
181
  }>;
176
182
  /** @public */
177
183
  export type DescribeVocabularySuccess = typeof DescribeVocabularySuccess.Type;
@@ -424,7 +430,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
424
430
  }>>;
425
431
  }>>;
426
432
  }>;
427
- 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;
428
434
  readonly failureMode: "error";
429
435
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
430
436
  readonly describe_vocabulary: import("effect/ai/Tool").Tool<"describe_vocabulary", {
@@ -456,8 +462,28 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
456
462
  readonly name: import("effect/Schema").String;
457
463
  readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
458
464
  }>>;
465
+ readonly docs_presets: import("effect/Schema").$Array<import("effect/Schema").Struct<{
466
+ readonly name: import("effect/Schema").String;
467
+ readonly description: import("effect/Schema").String;
468
+ readonly additive: import("effect/Schema").Boolean;
469
+ readonly surfaces: import("effect/Schema").$Array<import("effect/Schema").Struct<{
470
+ readonly file: import("effect/Schema").String;
471
+ readonly frontmatter: import("effect/Schema").Struct<{
472
+ readonly type: import("effect/Schema").Literal<"Surface">;
473
+ readonly status: import("effect/Schema").Literal<"draft">;
474
+ readonly title: import("effect/Schema").String;
475
+ readonly description: import("effect/Schema").String;
476
+ readonly kind: import("effect/Schema").Literals<readonly ["site", "repo", "readme"]>;
477
+ readonly audience: import("effect/Schema").Literals<readonly ["users", "contributors", "agents"]>;
478
+ readonly resource: import("effect/Schema").String;
479
+ readonly links_to: import("effect/Schema").optionalKey<import("effect/Schema").String>;
480
+ readonly url: import("effect/Schema").optionalKey<import("effect/Schema").String>;
481
+ }>;
482
+ readonly body: import("effect/Schema").String;
483
+ }>>;
484
+ }>>;
459
485
  }>;
460
- 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;
461
487
  readonly failureMode: "error";
462
488
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
463
489
  readonly get_concept: import("effect/ai/Tool").Tool<"get_concept", {
@@ -481,7 +507,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
481
507
  readonly field: import("effect/Schema").optionalKey<import("effect/Schema").String>;
482
508
  }>>;
483
509
  }>;
484
- 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;
485
511
  readonly failureMode: "error";
486
512
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
487
513
  readonly list_concepts: import("effect/ai/Tool").Tool<"list_concepts", {
@@ -504,7 +530,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
504
530
  }>>;
505
531
  readonly total: import("effect/Schema").Int;
506
532
  }>;
507
- 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;
508
534
  readonly failureMode: "error";
509
535
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
510
536
  readonly stale_report: import("effect/ai/Tool").Tool<"stale_report", {
@@ -527,7 +553,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
527
553
  readonly days_past: import("effect/Schema").Int;
528
554
  }>>;
529
555
  }>;
530
- 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;
531
557
  readonly failureMode: "error";
532
558
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
533
559
  readonly validate_bundle: import("effect/ai/Tool").Tool<"validate_bundle", {
@@ -568,7 +594,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
568
594
  readonly range: import("effect/Schema").optionalKey<typeof import("@okfit/core").DiagnosticRange>;
569
595
  }>>;
570
596
  }>;
571
- 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;
572
598
  readonly failureMode: "error";
573
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>;
574
600
  }>;
@@ -614,7 +640,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
614
640
  }>>;
615
641
  }>>;
616
642
  }>;
617
- 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;
618
644
  readonly failureMode: "error";
619
645
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
620
646
  readonly describe_vocabulary: import("effect/ai/Tool").Tool<"describe_vocabulary", {
@@ -646,8 +672,28 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
646
672
  readonly name: import("effect/Schema").String;
647
673
  readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
648
674
  }>>;
675
+ readonly docs_presets: import("effect/Schema").$Array<import("effect/Schema").Struct<{
676
+ readonly name: import("effect/Schema").String;
677
+ readonly description: import("effect/Schema").String;
678
+ readonly additive: import("effect/Schema").Boolean;
679
+ readonly surfaces: import("effect/Schema").$Array<import("effect/Schema").Struct<{
680
+ readonly file: import("effect/Schema").String;
681
+ readonly frontmatter: import("effect/Schema").Struct<{
682
+ readonly type: import("effect/Schema").Literal<"Surface">;
683
+ readonly status: import("effect/Schema").Literal<"draft">;
684
+ readonly title: import("effect/Schema").String;
685
+ readonly description: import("effect/Schema").String;
686
+ readonly kind: import("effect/Schema").Literals<readonly ["site", "repo", "readme"]>;
687
+ readonly audience: import("effect/Schema").Literals<readonly ["users", "contributors", "agents"]>;
688
+ readonly resource: import("effect/Schema").String;
689
+ readonly links_to: import("effect/Schema").optionalKey<import("effect/Schema").String>;
690
+ readonly url: import("effect/Schema").optionalKey<import("effect/Schema").String>;
691
+ }>;
692
+ readonly body: import("effect/Schema").String;
693
+ }>>;
694
+ }>>;
649
695
  }>;
650
- 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;
651
697
  readonly failureMode: "error";
652
698
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
653
699
  readonly get_concept: import("effect/ai/Tool").Tool<"get_concept", {
@@ -671,7 +717,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
671
717
  readonly field: import("effect/Schema").optionalKey<import("effect/Schema").String>;
672
718
  }>>;
673
719
  }>;
674
- 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;
675
721
  readonly failureMode: "error";
676
722
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
677
723
  readonly list_concepts: import("effect/ai/Tool").Tool<"list_concepts", {
@@ -694,7 +740,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
694
740
  }>>;
695
741
  readonly total: import("effect/Schema").Int;
696
742
  }>;
697
- 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;
698
744
  readonly failureMode: "error";
699
745
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
700
746
  readonly stale_report: import("effect/ai/Tool").Tool<"stale_report", {
@@ -717,7 +763,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
717
763
  readonly days_past: import("effect/Schema").Int;
718
764
  }>>;
719
765
  }>;
720
- 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;
721
767
  readonly failureMode: "error";
722
768
  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
723
769
  readonly validate_bundle: import("effect/ai/Tool").Tool<"validate_bundle", {
@@ -758,7 +804,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
758
804
  readonly range: import("effect/Schema").optionalKey<typeof import("@okfit/core").DiagnosticRange>;
759
805
  }>>;
760
806
  }>;
761
- 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;
762
808
  readonly failureMode: "error";
763
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>;
764
810
  }>, never, never>;
package/index.js CHANGED
@@ -1,10 +1,10 @@
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";
5
- import { ConceptNeighborsSuccess, DescribeVocabularySuccess, GetConceptSuccess, ListConceptsParams, ListConceptsSuccess, Neighbor, StaleReportParams, StaleReportSuccess, ValidateBundleParams } from "./schema/tools.js";
5
+ import { ConceptNeighborsSuccess, DescribeVocabularySuccess, DocsPreset, DocsPresetSurface, GetConceptSuccess, ListConceptsParams, ListConceptsSuccess, Neighbor, StaleReportParams, StaleReportSuccess, ValidateBundleParams } from "./schema/tools.js";
6
6
  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, 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.6.8",
3
+ "version": "0.8.0",
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.1",
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.1",
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.8.5",
61
- "@okfit/engine": "0.11.1",
62
- "@okfit/profiles": "0.8.3",
63
- "effect": "^4.0.0"
59
+ "@effected/yaml": "^0.19.1",
60
+ "@okfit/core": "0.9.1",
61
+ "@okfit/engine": "0.13.0",
62
+ "@okfit/profiles": "0.9.0",
63
+ "effect": "^4.0.1"
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,9 +1,40 @@
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
7
+ /** One Surface template inside a docs preset, as `describe_vocabulary` reports it. @public */
8
+ const DocsPresetSurface = Schema.Struct({
9
+ file: Schema.String,
10
+ frontmatter: Schema.Struct({
11
+ type: Schema.Literal("Surface"),
12
+ status: Schema.Literal("draft"),
13
+ title: Schema.String,
14
+ description: Schema.String,
15
+ kind: Schema.Literals([
16
+ "site",
17
+ "repo",
18
+ "readme"
19
+ ]),
20
+ audience: Schema.Literals([
21
+ "users",
22
+ "contributors",
23
+ "agents"
24
+ ]),
25
+ resource: Schema.String,
26
+ links_to: Schema.optionalKey(Schema.String),
27
+ url: Schema.optionalKey(Schema.String)
28
+ }),
29
+ body: Schema.String
30
+ });
31
+ /** One docs-surface preset the active profile offers. @public */
32
+ const DocsPreset = Schema.Struct({
33
+ name: Schema.String,
34
+ description: Schema.String,
35
+ additive: Schema.Boolean,
36
+ surfaces: Schema.Array(DocsPresetSurface)
37
+ });
7
38
  /** `describe_vocabulary`'s result (§5.2). @public */
8
39
  const DescribeVocabularySuccess = Schema.Struct({
9
40
  project_root: Schema.String,
@@ -13,7 +44,8 @@ const DescribeVocabularySuccess = Schema.Struct({
13
44
  profile_requested: Schema.NullOr(Schema.String),
14
45
  agent: Schema.NullOr(Schema.String),
15
46
  types: Schema.Array(ContextType),
16
- tags: Schema.Array(ContextTag)
47
+ tags: Schema.Array(ContextTag),
48
+ docs_presets: Schema.Array(DocsPreset)
17
49
  });
18
50
  /** `list_concepts`' arguments (§5.3). @public */
19
51
  const ListConceptsParams = Schema.Struct({
@@ -83,4 +115,4 @@ const ValidateBundleParams = Schema.Struct({
83
115
  });
84
116
 
85
117
  //#endregion
86
- export { ConceptNeighborsSuccess, DescribeVocabularySuccess, GetConceptSuccess, ListConceptsParams, ListConceptsSuccess, Neighbor, StaleReportParams, StaleReportSuccess, ValidateBundleDocument, ValidateBundleParams };
118
+ export { ConceptNeighborsSuccess, DescribeVocabularySuccess, DocsPreset, DocsPresetSurface, GetConceptSuccess, ListConceptsParams, ListConceptsSuccess, Neighbor, StaleReportParams, StaleReportSuccess, ValidateBundleDocument, ValidateBundleParams };
@@ -7,7 +7,7 @@ import { contextEnvelope } from "@okfit/engine";
7
7
  import { AppDirs, Xdg } from "@effected/xdg";
8
8
 
9
9
  //#region src/tools/describeVocabulary.ts
10
- const DESCRIPTION = "Returns this project's resolved okfit configuration: the project root, bundle root, active profile, configured agent actor, and the full set of concept types and tags the config declares, each with its description. Call this first, before filtering or writing any concept, to learn which type and tag names actually exist in this project.";
10
+ const DESCRIPTION = "Returns this project's resolved okfit configuration: project root, bundle root, active profile, agent actor, every concept type and tag the config declares, and docs_presets, the active profile's Surface templates (empty without a profile). Call this first, before filtering or writing any concept, to learn which names exist.";
11
11
  /**
12
12
  * `dependencies` names the platform services `handleDescribeVocabulary`
13
13
  * needs (`resolveConfigOnly` -> `resolveProjectConfig`/`provideConfig`);
@@ -57,6 +57,10 @@ const handleDescribeVocabulary = (projectRoot) => Effect.gen(function* () {
57
57
  indexExists: false,
58
58
  config: resolved.config
59
59
  });
60
+ const docsPresets = Option.match(resolved.profile, {
61
+ onNone: () => [],
62
+ onSome: (p) => p.docsPresets
63
+ });
60
64
  return {
61
65
  project_root: envelope.project_root,
62
66
  bundle_root: envelope.bundle_root,
@@ -65,7 +69,17 @@ const handleDescribeVocabulary = (projectRoot) => Effect.gen(function* () {
65
69
  profile_requested: envelope.profile_requested,
66
70
  agent: envelope.actors.agent,
67
71
  types: envelope.types,
68
- tags: envelope.tags
72
+ tags: envelope.tags,
73
+ docs_presets: docsPresets.map((preset) => ({
74
+ name: preset.name,
75
+ description: preset.description,
76
+ additive: preset.additive,
77
+ surfaces: preset.surfaces.map((s) => ({
78
+ file: s.file,
79
+ frontmatter: s.frontmatter,
80
+ body: s.body
81
+ }))
82
+ }))
69
83
  };
70
84
  });
71
85
 
@@ -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.6.8";
8
+ const MCP_VERSION = "0.8.0";
9
9
 
10
10
  //#endregion
11
11
  export { MCP_VERSION };