@okfit/mcp 0.9.8 → 0.10.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
@@ -58,12 +58,18 @@ or `.config/okfit.toml`.
58
58
 
59
59
  ## Errors
60
60
 
61
- A failing tool call reaches the client as `isError: true`, with the
62
- remediation text folded directly into the message — there is no separate
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.
61
+ An id that names no concept is not a failed call. `get_concept` and
62
+ `concept_neighbors` answer it with `structuredContent` `{ ok: false, error:
63
+ { _tag: "QueryConceptNotFoundError", id, reason, message, remediation } }`
64
+ (`reason` is `empty-id` or `not-a-concept`), and a found result carries
65
+ `ok: true`.
66
+
67
+ Every other failing tool call reaches the client as `isError: true`, with
68
+ the remediation text folded directly into the message and no structured
69
+ error field. `McpToolError` is `@effected/mcp`'s `ToolRefusal`: config
70
+ failures, an unreadable bundle root, an undeclared type or tag, and an
71
+ invalid argument all refuse with a message that names the problem and
72
+ what to do next.
67
73
 
68
74
  ## License
69
75
 
package/index.d.ts CHANGED
@@ -206,8 +206,31 @@ export declare const ListConceptsSuccess: Schema.Struct<{
206
206
  }>;
207
207
  /** @public */
208
208
  export type ListConceptsSuccess = typeof ListConceptsSuccess.Type;
209
- /** `get_concept`'s result (§5.4). @public */
210
- export declare const GetConceptSuccess: Schema.Struct<{
209
+ /**
210
+ * The expected not-found outcome `get_concept` and `concept_neighbors` share,
211
+ * an `ok: false` envelope member (`ToolOutcome`): the id was empty, or no
212
+ * concept has it. `_tag` is the engine's error tag.
213
+ *
214
+ * @public
215
+ */
216
+ export declare const ConceptNotFound: Schema.Struct<{
217
+ readonly _tag: Schema.Literal<"QueryConceptNotFoundError">;
218
+ } & {
219
+ readonly message: Schema.String;
220
+ readonly remediation: Schema.Struct<{
221
+ readonly hint: Schema.String;
222
+ readonly suggestedTool: Schema.optionalKey<Schema.String>;
223
+ readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
224
+ }>;
225
+ } & {
226
+ readonly id: Schema.String;
227
+ readonly reason: Schema.Literals<readonly ["empty-id", "not-a-concept"]>;
228
+ }>;
229
+ /** @public */
230
+ export type ConceptNotFound = typeof ConceptNotFound.Type;
231
+ /** `get_concept`'s found result (§5.4), the `ok: true` member. @public */
232
+ export declare const GetConceptFound: Schema.Struct<{
233
+ readonly ok: Schema.Literal<true>;
211
234
  readonly id: Schema.String;
212
235
  readonly type: Schema.String;
213
236
  readonly title: Schema.String;
@@ -233,6 +256,50 @@ export declare const GetConceptSuccess: Schema.Struct<{
233
256
  }>>;
234
257
  }>;
235
258
  /** @public */
259
+ export type GetConceptFound = typeof GetConceptFound.Type;
260
+ /** `get_concept`'s result: the concept, or `ConceptNotFound`. @public */
261
+ export declare const GetConceptSuccess: Schema.Union<readonly [Schema.Struct<{
262
+ readonly ok: Schema.Literal<true>;
263
+ readonly id: Schema.String;
264
+ readonly type: Schema.String;
265
+ readonly title: Schema.String;
266
+ readonly description: Schema.NullOr<Schema.String>;
267
+ readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
268
+ readonly tags: Schema.$Array<Schema.String>;
269
+ readonly path: Schema.String;
270
+ readonly frontmatter: Schema.$Record<Schema.String, Schema.Unknown>;
271
+ readonly raw: Schema.String;
272
+ readonly links: Schema.$Array<Schema.Struct<{
273
+ readonly to: Schema.String;
274
+ readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
275
+ readonly source: Schema.Literals<readonly ["body", "frontmatter"]>;
276
+ readonly field: Schema.optionalKey<Schema.String>;
277
+ }>>;
278
+ readonly tier: Schema.Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
279
+ readonly integrity: Schema.Literals<readonly ["current", "drifted", "none"]>;
280
+ readonly stale: Schema.Boolean;
281
+ readonly drift: Schema.NullOr<Schema.Struct<{
282
+ readonly reason: Schema.Literals<readonly ["content-changed", "unbound", "entry-superseded", "actor-not-allowed"]>;
283
+ readonly edited_by: Schema.NullOr<Schema.String>;
284
+ readonly edited_at: Schema.NullOr<Schema.String>;
285
+ }>>;
286
+ }>, Schema.Struct<{
287
+ readonly ok: Schema.Literal<false>;
288
+ readonly error: Schema.Union<readonly [Schema.Struct<{
289
+ readonly _tag: Schema.Literal<"QueryConceptNotFoundError">;
290
+ } & {
291
+ readonly message: Schema.String;
292
+ readonly remediation: Schema.Struct<{
293
+ readonly hint: Schema.String;
294
+ readonly suggestedTool: Schema.optionalKey<Schema.String>;
295
+ readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
296
+ }>;
297
+ } & {
298
+ readonly id: Schema.String;
299
+ readonly reason: Schema.Literals<readonly ["empty-id", "not-a-concept"]>;
300
+ }>]>;
301
+ }>]>;
302
+ /** @public */
236
303
  export type GetConceptSuccess = typeof GetConceptSuccess.Type;
237
304
  /** One graph neighbour: flat, with a nullable summary (J-4). @public */
238
305
  export declare const Neighbor: Schema.Struct<{
@@ -253,8 +320,9 @@ export declare const Neighbor: Schema.Struct<{
253
320
  }>;
254
321
  /** @public */
255
322
  export type Neighbor = typeof Neighbor.Type;
256
- /** `concept_neighbors`' result (§5.5). @public */
257
- export declare const ConceptNeighborsSuccess: Schema.Struct<{
323
+ /** `concept_neighbors`' found result (§5.5), the `ok: true` member. @public */
324
+ export declare const ConceptNeighborsFound: Schema.Struct<{
325
+ readonly ok: Schema.Literal<true>;
258
326
  readonly outgoing: Schema.$Array<Schema.Struct<{
259
327
  readonly id: Schema.String;
260
328
  readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
@@ -289,6 +357,59 @@ export declare const ConceptNeighborsSuccess: Schema.Struct<{
289
357
  }>>;
290
358
  }>;
291
359
  /** @public */
360
+ export type ConceptNeighborsFound = typeof ConceptNeighborsFound.Type;
361
+ /** `concept_neighbors`' result: the neighbours, or `ConceptNotFound`. @public */
362
+ export declare const ConceptNeighborsSuccess: Schema.Union<readonly [Schema.Struct<{
363
+ readonly ok: Schema.Literal<true>;
364
+ readonly outgoing: Schema.$Array<Schema.Struct<{
365
+ readonly id: Schema.String;
366
+ readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
367
+ readonly summary: Schema.NullOr<Schema.Struct<{
368
+ readonly id: Schema.String;
369
+ readonly type: Schema.String;
370
+ readonly title: Schema.String;
371
+ readonly description: Schema.NullOr<Schema.String>;
372
+ readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
373
+ readonly tags: Schema.$Array<Schema.String>;
374
+ readonly path: Schema.String;
375
+ readonly tier: Schema.Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
376
+ readonly integrity: Schema.Literals<readonly ["current", "drifted", "none"]>;
377
+ readonly stale: Schema.Boolean;
378
+ }>>;
379
+ }>>;
380
+ readonly incoming: Schema.$Array<Schema.Struct<{
381
+ readonly id: Schema.String;
382
+ readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
383
+ readonly summary: Schema.NullOr<Schema.Struct<{
384
+ readonly id: Schema.String;
385
+ readonly type: Schema.String;
386
+ readonly title: Schema.String;
387
+ readonly description: Schema.NullOr<Schema.String>;
388
+ readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
389
+ readonly tags: Schema.$Array<Schema.String>;
390
+ readonly path: Schema.String;
391
+ readonly tier: Schema.Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
392
+ readonly integrity: Schema.Literals<readonly ["current", "drifted", "none"]>;
393
+ readonly stale: Schema.Boolean;
394
+ }>>;
395
+ }>>;
396
+ }>, Schema.Struct<{
397
+ readonly ok: Schema.Literal<false>;
398
+ readonly error: Schema.Union<readonly [Schema.Struct<{
399
+ readonly _tag: Schema.Literal<"QueryConceptNotFoundError">;
400
+ } & {
401
+ readonly message: Schema.String;
402
+ readonly remediation: Schema.Struct<{
403
+ readonly hint: Schema.String;
404
+ readonly suggestedTool: Schema.optionalKey<Schema.String>;
405
+ readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
406
+ }>;
407
+ } & {
408
+ readonly id: Schema.String;
409
+ readonly reason: Schema.Literals<readonly ["empty-id", "not-a-concept"]>;
410
+ }>]>;
411
+ }>]>;
412
+ /** @public */
292
413
  export type ConceptNeighborsSuccess = typeof ConceptNeighborsSuccess.Type;
293
414
  /** `stale_report`'s arguments: an optional ISO instant, decoded in the handler (J-5). @public */
294
415
  export declare const StaleReportParams: Schema.Struct<{
@@ -435,7 +556,8 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
435
556
  readonly parameters: import("effect/Schema").Struct<{
436
557
  readonly id: import("effect/Schema").String;
437
558
  }>;
438
- readonly success: import("effect/Schema").Struct<{
559
+ readonly success: import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
560
+ readonly ok: import("effect/Schema").Literal<true>;
439
561
  readonly outgoing: import("effect/Schema").$Array<import("effect/Schema").Struct<{
440
562
  readonly id: import("effect/Schema").String;
441
563
  readonly kind: import("effect/Schema").Literals<readonly ["concept", "file", "missing"]>;
@@ -468,7 +590,22 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
468
590
  readonly stale: import("effect/Schema").Boolean;
469
591
  }>>;
470
592
  }>>;
471
- }>;
593
+ }>, import("effect/Schema").Struct<{
594
+ readonly ok: import("effect/Schema").Literal<false>;
595
+ readonly error: import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
596
+ readonly _tag: import("effect/Schema").Literal<"QueryConceptNotFoundError">;
597
+ } & {
598
+ readonly message: import("effect/Schema").String;
599
+ readonly remediation: import("effect/Schema").Struct<{
600
+ readonly hint: import("effect/Schema").String;
601
+ readonly suggestedTool: import("effect/Schema").optionalKey<import("effect/Schema").String>;
602
+ readonly suggestedArgs: import("effect/Schema").optionalKey<import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").Unknown>>;
603
+ }>;
604
+ } & {
605
+ readonly id: import("effect/Schema").String;
606
+ readonly reason: import("effect/Schema").Literals<readonly ["empty-id", "not-a-concept"]>;
607
+ }>]>;
608
+ }>]>;
472
609
  readonly failure: typeof import("@effected/mcp").ToolRefusal;
473
610
  readonly failureMode: "error";
474
611
  }, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
@@ -529,7 +666,8 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
529
666
  readonly parameters: import("effect/Schema").Struct<{
530
667
  readonly id: import("effect/Schema").String;
531
668
  }>;
532
- readonly success: import("effect/Schema").Struct<{
669
+ readonly success: import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
670
+ readonly ok: import("effect/Schema").Literal<true>;
533
671
  readonly id: import("effect/Schema").String;
534
672
  readonly type: import("effect/Schema").String;
535
673
  readonly title: import("effect/Schema").String;
@@ -553,7 +691,22 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
553
691
  readonly edited_by: import("effect/Schema").NullOr<import("effect/Schema").String>;
554
692
  readonly edited_at: import("effect/Schema").NullOr<import("effect/Schema").String>;
555
693
  }>>;
556
- }>;
694
+ }>, import("effect/Schema").Struct<{
695
+ readonly ok: import("effect/Schema").Literal<false>;
696
+ readonly error: import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
697
+ readonly _tag: import("effect/Schema").Literal<"QueryConceptNotFoundError">;
698
+ } & {
699
+ readonly message: import("effect/Schema").String;
700
+ readonly remediation: import("effect/Schema").Struct<{
701
+ readonly hint: import("effect/Schema").String;
702
+ readonly suggestedTool: import("effect/Schema").optionalKey<import("effect/Schema").String>;
703
+ readonly suggestedArgs: import("effect/Schema").optionalKey<import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").Unknown>>;
704
+ }>;
705
+ } & {
706
+ readonly id: import("effect/Schema").String;
707
+ readonly reason: import("effect/Schema").Literals<readonly ["empty-id", "not-a-concept"]>;
708
+ }>]>;
709
+ }>]>;
557
710
  readonly failure: typeof import("@effected/mcp").ToolRefusal;
558
711
  readonly failureMode: "error";
559
712
  }, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
@@ -686,7 +839,8 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
686
839
  readonly parameters: import("effect/Schema").Struct<{
687
840
  readonly id: import("effect/Schema").String;
688
841
  }>;
689
- readonly success: import("effect/Schema").Struct<{
842
+ readonly success: import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
843
+ readonly ok: import("effect/Schema").Literal<true>;
690
844
  readonly outgoing: import("effect/Schema").$Array<import("effect/Schema").Struct<{
691
845
  readonly id: import("effect/Schema").String;
692
846
  readonly kind: import("effect/Schema").Literals<readonly ["concept", "file", "missing"]>;
@@ -719,7 +873,22 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
719
873
  readonly stale: import("effect/Schema").Boolean;
720
874
  }>>;
721
875
  }>>;
722
- }>;
876
+ }>, import("effect/Schema").Struct<{
877
+ readonly ok: import("effect/Schema").Literal<false>;
878
+ readonly error: import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
879
+ readonly _tag: import("effect/Schema").Literal<"QueryConceptNotFoundError">;
880
+ } & {
881
+ readonly message: import("effect/Schema").String;
882
+ readonly remediation: import("effect/Schema").Struct<{
883
+ readonly hint: import("effect/Schema").String;
884
+ readonly suggestedTool: import("effect/Schema").optionalKey<import("effect/Schema").String>;
885
+ readonly suggestedArgs: import("effect/Schema").optionalKey<import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").Unknown>>;
886
+ }>;
887
+ } & {
888
+ readonly id: import("effect/Schema").String;
889
+ readonly reason: import("effect/Schema").Literals<readonly ["empty-id", "not-a-concept"]>;
890
+ }>]>;
891
+ }>]>;
723
892
  readonly failure: typeof import("@effected/mcp").ToolRefusal;
724
893
  readonly failureMode: "error";
725
894
  }, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
@@ -780,7 +949,8 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
780
949
  readonly parameters: import("effect/Schema").Struct<{
781
950
  readonly id: import("effect/Schema").String;
782
951
  }>;
783
- readonly success: import("effect/Schema").Struct<{
952
+ readonly success: import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
953
+ readonly ok: import("effect/Schema").Literal<true>;
784
954
  readonly id: import("effect/Schema").String;
785
955
  readonly type: import("effect/Schema").String;
786
956
  readonly title: import("effect/Schema").String;
@@ -804,7 +974,22 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
804
974
  readonly edited_by: import("effect/Schema").NullOr<import("effect/Schema").String>;
805
975
  readonly edited_at: import("effect/Schema").NullOr<import("effect/Schema").String>;
806
976
  }>>;
807
- }>;
977
+ }>, import("effect/Schema").Struct<{
978
+ readonly ok: import("effect/Schema").Literal<false>;
979
+ readonly error: import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
980
+ readonly _tag: import("effect/Schema").Literal<"QueryConceptNotFoundError">;
981
+ } & {
982
+ readonly message: import("effect/Schema").String;
983
+ readonly remediation: import("effect/Schema").Struct<{
984
+ readonly hint: import("effect/Schema").String;
985
+ readonly suggestedTool: import("effect/Schema").optionalKey<import("effect/Schema").String>;
986
+ readonly suggestedArgs: import("effect/Schema").optionalKey<import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").Unknown>>;
987
+ }>;
988
+ } & {
989
+ readonly id: import("effect/Schema").String;
990
+ readonly reason: import("effect/Schema").Literals<readonly ["empty-id", "not-a-concept"]>;
991
+ }>]>;
992
+ }>]>;
808
993
  readonly failure: typeof import("@effected/mcp").ToolRefusal;
809
994
  readonly failureMode: "error";
810
995
  }, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
package/index.js CHANGED
@@ -2,9 +2,9 @@ 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, DocsPreset, DocsPresetSurface, GetConceptSuccess, ListConceptsParams, ListConceptsSuccess, Neighbor, StaleReportParams, StaleReportSuccess, ValidateBundleParams } from "./schema/tools.js";
5
+ import { ConceptNeighborsFound, ConceptNeighborsSuccess, ConceptNotFound, DescribeVocabularySuccess, DocsPreset, DocsPresetSurface, GetConceptFound, 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 { ConceptNeighborsSuccess, ConceptResources, ConceptSummary, DescribeVocabularySuccess, DocsPreset, DocsPresetSurface, GetConceptSuccess, IndexResource, ListConceptsParams, ListConceptsSuccess, MCP_VERSION, McpToolError, Neighbor, OkfitToolkit, Remediation, SERVER_INSTRUCTIONS, ServerLayer, StaleReportParams, StaleReportSuccess, ToolsLayer, ValidateBundleParams, toConceptSummary };
10
+ export { ConceptNeighborsFound, ConceptNeighborsSuccess, ConceptNotFound, ConceptResources, ConceptSummary, DescribeVocabularySuccess, DocsPreset, DocsPresetSurface, GetConceptFound, GetConceptSuccess, IndexResource, ListConceptsParams, ListConceptsSuccess, MCP_VERSION, McpToolError, Neighbor, OkfitToolkit, Remediation, SERVER_INSTRUCTIONS, ServerLayer, StaleReportParams, StaleReportSuccess, ToolsLayer, ValidateBundleParams, toConceptSummary };
@@ -1,24 +1,32 @@
1
- import { ToolFailure, ToolRefusal } from "@effected/mcp";
2
- import { Effect } from "effect";
1
+ import { ToolFailure } from "@effected/mcp";
3
2
 
4
3
  // src/internal/conceptNotFound.ts
5
4
  /**
6
- * Maps the engine's `QueryConceptNotFoundError` to the tool-facing failure
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.
5
+ * The `ConceptNotFound` envelope error `get_concept` and `concept_neighbors`
6
+ * share, for `ToolOutcome.catchAsEnvelope`: the engine's `id` and `reason`,
7
+ * a message saying the id is empty or that no concept has it, and a
8
+ * remediation pointing at `list_concepts`. An unknown id is an expected
9
+ * outcome the agent branches on, not a wrong call, so it rides the success
10
+ * channel (`isError: false`, `structuredContent.ok: false`).
10
11
  *
11
12
  * @internal
12
13
  */
13
- const toConceptLookupFailure = (id, error) => {
14
- if (error.reason === "empty-id") return Effect.fail(ToolRefusal.refuse("id must not be empty", {
14
+ const conceptNotFound = (requested, error) => error.reason === "empty-id" ? {
15
+ id: error.id,
16
+ reason: error.reason,
17
+ message: "id must not be empty",
18
+ remediation: {
15
19
  hint: "Pass a bundle-relative concept id such as decisions/cli-exit-codes.",
16
20
  suggestedTool: "list_concepts"
17
- }));
18
- return Effect.fail(ToolRefusal.refuse(`no concept "${ToolFailure.truncate(id)}" in this bundle`, {
21
+ }
22
+ } : {
23
+ id: error.id,
24
+ reason: error.reason,
25
+ message: `no concept "${ToolFailure.truncate(requested)}" in this bundle`,
26
+ remediation: {
19
27
  hint: "Call list_concepts to see the ids this bundle contains.",
20
28
  suggestedTool: "list_concepts"
21
- }));
29
+ }
22
30
  };
23
31
 
24
- export { toConceptLookupFailure };
32
+ export { conceptNotFound };
@@ -1,21 +1,10 @@
1
+ import { ErrorText } from "@effected/engine";
1
2
  import { ToolRefusal } from "@effected/mcp";
2
3
  import { Bundle } from "@okfit/core";
3
4
  import { Effect, Option } from "effect";
4
5
  import { provideConfig, resolveProjectConfig } from "@okfit/engine";
5
6
 
6
7
  // src/internal/toolContext.ts
7
- /**
8
- * The error's `message` when it has one as a string, else `String(error)`.
9
- * A four-line local copy of `CLI/render/json.ts`'s own helper, which is
10
- * module-private there and cannot be imported.
11
- */
12
- const messageOf = (error) => {
13
- if (typeof error === "object" && error !== null && "message" in error) {
14
- const message = error.message;
15
- if (typeof message === "string") return message;
16
- }
17
- return String(error);
18
- };
19
8
  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.";
20
9
  /**
21
10
  * Config resolution alone, with every failure collapsed to a `ToolRefusal`.
@@ -42,7 +31,7 @@ const resolveConfigOnly = (projectRoot) => resolveProjectConfig({
42
31
  hint: CONFIG_HINT,
43
32
  suggestedTool: "describe_vocabulary"
44
33
  };
45
- return ToolRefusal.refuse(messageOf(cause), remediation);
34
+ return ToolRefusal.refuse(ErrorText.describe(cause), remediation);
46
35
  }));
47
36
  /**
48
37
  * Resolve config and load the bundle, fresh, for one tool call (N-9). No
@@ -66,4 +55,4 @@ const loadToolContext = (projectRoot) => Effect.gen(function* () {
66
55
  };
67
56
  });
68
57
 
69
- export { loadToolContext, messageOf, resolveConfigOnly };
58
+ export { loadToolContext, resolveConfigOnly };
@@ -1,4 +1,4 @@
1
- import { messageOf } from "./toolContext.js";
1
+ import { ErrorText } from "@effected/engine";
2
2
  import { ToolRefusal } from "@effected/mcp";
3
3
  import { Effect } from "effect";
4
4
  import { Trust } from "@okfit/profiles";
@@ -10,6 +10,6 @@ import { Trust } from "@okfit/profiles";
10
10
  *
11
11
  * @internal
12
12
  */
13
- const toolSignals = (bundle, config, now) => Trust.signals(bundle, config, now).pipe(Effect.mapError((cause) => ToolRefusal.refuse(messageOf(cause), { hint: "A concept file could not be read to check its verification; retry once the bundle is readable." })));
13
+ const toolSignals = (bundle, config, now) => Trust.signals(bundle, config, now).pipe(Effect.mapError((cause) => ToolRefusal.refuse(ErrorText.describe(cause), { hint: "A concept file could not be read to check its verification; retry once the bundle is readable." })));
14
14
 
15
15
  export { toolSignals };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@okfit/mcp",
3
- "version": "0.9.8",
3
+ "version": "0.10.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,24 @@
44
44
  "okfit-mcp": "bin/okfit-mcp.js"
45
45
  },
46
46
  "dependencies": {
47
- "@effect/platform-node": "^4.0.6",
48
- "@effected/config-file": "^0.20.1",
49
- "@effected/engine": "^0.8.0",
50
- "@effected/git": "^0.25.1",
51
- "@effected/glob": "^0.14.0",
52
- "@effected/jsonc": "^0.20.0",
53
- "@effected/markdown": "^0.23.0",
54
- "@effected/mcp": "^0.9.0",
55
- "@effected/schemastore": "^0.26.2",
56
- "@effected/toml": "^0.16.0",
57
- "@effected/walker": "^0.20.1",
58
- "@effected/xdg": "^0.15.1",
59
- "@effected/yaml": "^0.25.1",
60
- "@okfit/core": "0.11.6",
61
- "@okfit/engine": "0.18.0",
62
- "@okfit/profiles": "0.11.0",
63
- "effect": "^4.0.6"
47
+ "@effect/platform-node": "^4.0.7",
48
+ "@effected/config-file": "^0.22.0",
49
+ "@effected/engine": "^0.10.0",
50
+ "@effected/git": "^0.27.0",
51
+ "@effected/glob": "^0.16.0",
52
+ "@effected/jsonc": "^0.21.0",
53
+ "@effected/markdown": "^0.24.0",
54
+ "@effected/mcp": "^0.11.0",
55
+ "@effected/schemastore": "^0.27.0",
56
+ "@effected/source": "^0.1.0",
57
+ "@effected/toml": "^0.17.0",
58
+ "@effected/walker": "^0.22.0",
59
+ "@effected/xdg": "^0.17.0",
60
+ "@effected/yaml": "^0.26.0",
61
+ "@okfit/core": "0.11.8",
62
+ "@okfit/engine": "0.18.2",
63
+ "@okfit/profiles": "0.13.0",
64
+ "effect": "^4.0.7"
64
65
  },
65
66
  "engines": {
66
67
  "node": ">=24.11.0"
package/schema/tools.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import { ConceptSummary } from "./ConceptSummary.js";
2
+ import { ToolOutcome } from "@effected/mcp";
2
3
  import { GraphNodeKind, Status } from "@okfit/core";
3
4
  import { Schema } from "effect";
4
5
  import { ContextTag, ContextType, TrustDrift } from "@okfit/engine";
@@ -68,8 +69,20 @@ const ListConceptsSuccess = Schema.Struct({
68
69
  items: Schema.Array(ConceptSummary),
69
70
  total: Schema.Int
70
71
  });
71
- /** `get_concept`'s result (§5.4). @public */
72
- const GetConceptSuccess = Schema.Struct({
72
+ /**
73
+ * The expected not-found outcome `get_concept` and `concept_neighbors` share,
74
+ * an `ok: false` envelope member (`ToolOutcome`): the id was empty, or no
75
+ * concept has it. `_tag` is the engine's error tag.
76
+ *
77
+ * @public
78
+ */
79
+ const ConceptNotFound = ToolOutcome.error("QueryConceptNotFoundError", {
80
+ id: Schema.String,
81
+ reason: Schema.Literals(["empty-id", "not-a-concept"])
82
+ });
83
+ /** `get_concept`'s found result (§5.4), the `ok: true` member. @public */
84
+ const GetConceptFound = Schema.Struct({
85
+ ...ToolOutcome.ok,
73
86
  id: Schema.String,
74
87
  type: Schema.String,
75
88
  title: Schema.String,
@@ -98,17 +111,22 @@ const GetConceptSuccess = Schema.Struct({
98
111
  stale: Schema.Boolean,
99
112
  drift: Schema.NullOr(TrustDrift)
100
113
  });
114
+ /** `get_concept`'s result: the concept, or `ConceptNotFound`. @public */
115
+ const GetConceptSuccess = ToolOutcome.envelope(GetConceptFound, [ConceptNotFound], { identifier: "ConceptNotFound" });
101
116
  /** One graph neighbour: flat, with a nullable summary (J-4). @public */
102
117
  const Neighbor = Schema.Struct({
103
118
  id: Schema.String,
104
119
  kind: GraphNodeKind,
105
120
  summary: Schema.NullOr(ConceptSummary)
106
121
  });
107
- /** `concept_neighbors`' result (§5.5). @public */
108
- const ConceptNeighborsSuccess = Schema.Struct({
122
+ /** `concept_neighbors`' found result (§5.5), the `ok: true` member. @public */
123
+ const ConceptNeighborsFound = Schema.Struct({
124
+ ...ToolOutcome.ok,
109
125
  outgoing: Schema.Array(Neighbor),
110
126
  incoming: Schema.Array(Neighbor)
111
127
  });
128
+ /** `concept_neighbors`' result: the neighbours, or `ConceptNotFound`. @public */
129
+ const ConceptNeighborsSuccess = ToolOutcome.envelope(ConceptNeighborsFound, [ConceptNotFound], { identifier: "ConceptNotFound" });
112
130
  /** `stale_report`'s arguments: an optional ISO instant, decoded in the handler (J-5). @public */
113
131
  const StaleReportParams = Schema.Struct({ now: Schema.optionalKey(Schema.String) });
114
132
  /** `stale_report`'s result (§5.6). @public */
@@ -137,4 +155,4 @@ const ValidateBundleParams = Schema.Struct({
137
155
  documents: Schema.optionalKey(Schema.Array(ValidateBundleDocument))
138
156
  });
139
157
 
140
- export { ConceptNeighborsSuccess, DescribeVocabularySuccess, DocsPreset, DocsPresetSurface, GetConceptSuccess, ListConceptsParams, ListConceptsSuccess, Neighbor, StaleReportParams, StaleReportSuccess, ValidateBundleDocument, ValidateBundleParams };
158
+ export { ConceptNeighborsFound, ConceptNeighborsSuccess, ConceptNotFound, DescribeVocabularySuccess, DocsPreset, DocsPresetSurface, GetConceptFound, GetConceptSuccess, ListConceptsParams, ListConceptsSuccess, Neighbor, StaleReportParams, StaleReportSuccess, ValidateBundleDocument, ValidateBundleParams };
package/server.js CHANGED
@@ -26,7 +26,9 @@ const SERVER_INSTRUCTIONS = [
26
26
  "list_concepts to find ids; get_concept, concept_neighbors, stale_report and validate_bundle take those ids.",
27
27
  "Concept ids are bundle-relative paths without the .md extension (for example decisions/cli-exit-codes).",
28
28
  "Every successful tools/call result carries the typed payload in structuredContent and a JSON rendering in",
29
- "content[0].text. A failed call is isError: true with the human message and a remediation hint in",
29
+ "content[0].text. An id that names no concept is not a failed call: get_concept and concept_neighbors answer",
30
+ "structuredContent { ok: false, error: { _tag, id, reason, message, remediation } }, and ok: true otherwise.",
31
+ "A failed call is isError: true with the human message and a remediation hint in",
30
32
  "content[0].text and no structuredContent; read that text before retrying.",
31
33
  "Each concept carries an okfit trust signal next to its OKF trust tier: integrity is current when a human verified exactly the current content,",
32
34
  "drifted when it changed since (the reason says why), and none when no human verified it; stale means past stale_after.",
@@ -2,8 +2,9 @@ import { McpToolError } from "../errors.js";
2
2
  import { loadToolContext } from "../internal/toolContext.js";
3
3
  import { toConceptSummary } from "../schema/ConceptSummary.js";
4
4
  import { ConceptNeighborsSuccess } from "../schema/tools.js";
5
- import { toConceptLookupFailure } from "../internal/conceptNotFound.js";
5
+ import { conceptNotFound } from "../internal/conceptNotFound.js";
6
6
  import { toolSignals } from "../internal/toolSignals.js";
7
+ import { ToolOutcome } from "@effected/mcp";
7
8
  import { Crypto, DateTime, Effect, FileSystem, Path, Schema } from "effect";
8
9
  import { Tool } from "effect/ai";
9
10
  import { ConceptQuery, signalFor } from "@okfit/engine";
@@ -32,17 +33,18 @@ const conceptNeighbors = Tool.make("concept_neighbors", {
32
33
  ]
33
34
  }).annotate(Tool.Title, "Concept graph neighbors").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
34
35
  /**
35
- * Deviation from the brief's literal snippet, matching the ruling binding
36
- * every C task (progress.md): `message` is composed through
37
- * `ToolFailure.message` (`@effected/mcp`) at construction, since a declared
38
- * typed failure under `failureMode: "error"` never reaches the wire with
39
- * `structuredContent` — only `error.message` does.
36
+ * An unknown or empty id is an expected outcome, not a wrong call: it is
37
+ * answered on the success channel as `ToolOutcome`'s `{ ok: false, error }`
38
+ * envelope (`ConceptNotFound`), so the agent reads `_tag`, `reason` and the
39
+ * remediation from `structuredContent`. Infrastructure failures (no config,
40
+ * an unreadable bundle) stay declared `McpToolError` refusals.
40
41
  *
41
42
  * @public
42
43
  */
43
44
  const handleConceptNeighbors = (projectRoot, params) => Effect.gen(function* () {
44
45
  const ctx = yield* loadToolContext(projectRoot);
45
- const result = yield* ConceptQuery.neighbors(ctx.bundle, params.id).pipe(Effect.catchTag("QueryConceptNotFoundError", (e) => toConceptLookupFailure(params.id, e)));
46
+ const result = yield* ConceptQuery.neighbors(ctx.bundle, params.id).pipe(ToolOutcome.catchAsEnvelope({ QueryConceptNotFoundError: (e) => conceptNotFound(params.id, e) }));
47
+ if (ToolOutcome.isFailure(result)) return result;
46
48
  const signals = yield* toolSignals(ctx.bundle, ctx.config, yield* DateTime.now);
47
49
  const project = (neighbor) => ({
48
50
  id: neighbor.id,
@@ -50,6 +52,7 @@ const handleConceptNeighbors = (projectRoot, params) => Effect.gen(function* ()
50
52
  summary: neighbor.concept === null ? null : toConceptSummary(neighbor.concept, signalFor(signals, neighbor.concept.id))
51
53
  });
52
54
  return {
55
+ ok: true,
53
56
  outgoing: result.outgoing.map(project),
54
57
  incoming: result.incoming.map(project)
55
58
  };
@@ -1,8 +1,9 @@
1
1
  import { McpToolError } from "../errors.js";
2
2
  import { loadToolContext } from "../internal/toolContext.js";
3
3
  import { GetConceptSuccess } from "../schema/tools.js";
4
- import { toConceptLookupFailure } from "../internal/conceptNotFound.js";
4
+ import { conceptNotFound } from "../internal/conceptNotFound.js";
5
5
  import { toolSignals } from "../internal/toolSignals.js";
6
+ import { ToolOutcome } from "@effected/mcp";
6
7
  import { Derive } from "@okfit/core";
7
8
  import { Crypto, DateTime, Effect, FileSystem, Path, Schema } from "effect";
8
9
  import { Tool } from "effect/ai";
@@ -34,20 +35,23 @@ const getConcept = Tool.make("get_concept", {
34
35
  ]
35
36
  }).annotate(Tool.Title, "Get one OKF concept").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
36
37
  /**
37
- * Deviation from the brief's literal snippet, matching the ruling binding
38
- * every C task (progress.md): `message` is composed through
39
- * `ToolFailure.message` (`@effected/mcp`) at construction, since a declared
40
- * typed failure under `failureMode: "error"` never reaches the wire with
41
- * `structuredContent` — only `error.message` does.
38
+ * An unknown or empty id is an expected outcome, not a wrong call: it is
39
+ * answered on the success channel as `ToolOutcome`'s `{ ok: false, error }`
40
+ * envelope (`ConceptNotFound`), so the agent reads `_tag`, `reason` and the
41
+ * remediation from `structuredContent`. Infrastructure failures (no config,
42
+ * an unreadable bundle) stay declared `McpToolError` refusals.
42
43
  *
43
44
  * @public
44
45
  */
45
46
  const handleGetConcept = (projectRoot, params) => Effect.gen(function* () {
46
47
  const ctx = yield* loadToolContext(projectRoot);
47
- const { concept, links } = yield* ConceptQuery.get(ctx.bundle, params.id).pipe(Effect.catchTag("QueryConceptNotFoundError", (e) => toConceptLookupFailure(params.id, e)));
48
+ const found = yield* ConceptQuery.get(ctx.bundle, params.id).pipe(ToolOutcome.catchAsEnvelope({ QueryConceptNotFoundError: (e) => conceptNotFound(params.id, e) }));
49
+ if (ToolOutcome.isFailure(found)) return found;
50
+ const { concept, links } = found;
48
51
  const signals = yield* toolSignals(ctx.bundle, ctx.config, yield* DateTime.now);
49
52
  const signal = signalFor(signals, concept.id);
50
53
  return {
54
+ ok: true,
51
55
  id: concept.id,
52
56
  type: concept.frontmatter.type,
53
57
  title: Derive.title(concept),
@@ -5,7 +5,7 @@
5
5
  "toolPackages": [
6
6
  {
7
7
  "packageName": "@microsoft/api-extractor",
8
- "packageVersion": "7.59.4"
8
+ "packageVersion": "7.60.0"
9
9
  }
10
10
  ]
11
11
  }
package/version.js CHANGED
@@ -5,6 +5,6 @@
5
5
  *
6
6
  * @public
7
7
  */
8
- const MCP_VERSION = "0.9.8";
8
+ const MCP_VERSION = "0.10.1";
9
9
 
10
10
  export { MCP_VERSION };