@okfit/mcp 0.9.7 → 0.10.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 +12 -6
- package/index.d.ts +197 -12
- package/index.js +2 -2
- package/internal/conceptNotFound.js +20 -12
- package/package.json +13 -13
- package/schema/tools.js +23 -5
- package/server.js +3 -1
- package/tools/conceptNeighbors.js +10 -7
- package/tools/getConcept.js +11 -7
- package/version.js +1 -1
package/README.md
CHANGED
|
@@ -58,12 +58,18 @@ or `.config/okfit.toml`.
|
|
|
58
58
|
|
|
59
59
|
## Errors
|
|
60
60
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
`
|
|
65
|
-
|
|
66
|
-
|
|
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
|
-
/**
|
|
210
|
-
|
|
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
|
|
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
|
|
2
|
-
import { Effect } from "effect";
|
|
1
|
+
import { ToolFailure } from "@effected/mcp";
|
|
3
2
|
|
|
4
3
|
// src/internal/conceptNotFound.ts
|
|
5
4
|
/**
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
* is empty
|
|
9
|
-
* remediation
|
|
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
|
|
14
|
-
|
|
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
|
-
|
|
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 {
|
|
32
|
+
export { conceptNotFound };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@okfit/mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.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": [
|
|
@@ -45,21 +45,21 @@
|
|
|
45
45
|
},
|
|
46
46
|
"dependencies": {
|
|
47
47
|
"@effect/platform-node": "^4.0.6",
|
|
48
|
-
"@effected/config-file": "^0.
|
|
49
|
-
"@effected/engine": "^0.
|
|
50
|
-
"@effected/git": "^0.
|
|
51
|
-
"@effected/glob": "^0.
|
|
52
|
-
"@effected/jsonc": "^0.20.
|
|
48
|
+
"@effected/config-file": "^0.21.0",
|
|
49
|
+
"@effected/engine": "^0.9.0",
|
|
50
|
+
"@effected/git": "^0.26.0",
|
|
51
|
+
"@effected/glob": "^0.15.0",
|
|
52
|
+
"@effected/jsonc": "^0.20.1",
|
|
53
53
|
"@effected/markdown": "^0.23.0",
|
|
54
|
-
"@effected/mcp": "^0.
|
|
55
|
-
"@effected/schemastore": "^0.26.
|
|
54
|
+
"@effected/mcp": "^0.10.0",
|
|
55
|
+
"@effected/schemastore": "^0.26.3",
|
|
56
56
|
"@effected/toml": "^0.16.0",
|
|
57
|
-
"@effected/walker": "^0.
|
|
58
|
-
"@effected/xdg": "^0.
|
|
57
|
+
"@effected/walker": "^0.21.0",
|
|
58
|
+
"@effected/xdg": "^0.16.0",
|
|
59
59
|
"@effected/yaml": "^0.25.1",
|
|
60
|
-
"@okfit/core": "0.11.
|
|
61
|
-
"@okfit/engine": "0.
|
|
62
|
-
"@okfit/profiles": "0.
|
|
60
|
+
"@okfit/core": "0.11.7",
|
|
61
|
+
"@okfit/engine": "0.18.1",
|
|
62
|
+
"@okfit/profiles": "0.12.0",
|
|
63
63
|
"effect": "^4.0.6"
|
|
64
64
|
},
|
|
65
65
|
"engines": {
|
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
|
-
/**
|
|
72
|
-
|
|
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
|
|
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.
|
|
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 {
|
|
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
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
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(
|
|
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
|
};
|
package/tools/getConcept.js
CHANGED
|
@@ -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 {
|
|
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
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
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
|
|
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),
|