@okfit/mcp 0.8.4 → 0.9.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
@@ -10,7 +10,7 @@ Model Context Protocol server for [okfit](https://github.com/spencerbeggs/okfit)
10
10
  tool or resource ever writes to the bundle, the config, or anywhere else.
11
11
  `validate_bundle` spawns read-only `git log`/`git show` calls for one lint
12
12
  (`generated-at-drift`), and only for a concept that records no
13
- `generated.body_sha256` — a bundle stamped with digests needs no git at
13
+ `integrity.generated.body` — a bundle stamped with digests needs no git at
14
14
  all; a read is not a write, and the promise stands. Six
15
15
  tools cover orientation, discovery, and validation; the bundle index plus
16
16
  one resource per concept expose the bundle's own markdown to a client's
@@ -37,10 +37,10 @@ or `.config/okfit.toml`.
37
37
  | Tool | Returns |
38
38
  | --- | --- |
39
39
  | `describe_vocabulary` | The resolved project and bundle roots, active profile, agent actor, and the config's declared type and tag vocabulary. Call first, before filtering or writing anything. |
40
- | `list_concepts` | Concept summaries, optionally filtered by an exact type, by tags that must all be present, and by status; pages with `limit`/`offset` and reports the total match count. |
41
- | `get_concept` | One concept by id: its whole decoded frontmatter, the file's raw markdown text, its bundle-relative path, and every outgoing link. |
40
+ | `list_concepts` | Concept summaries (each with `tier`, `integrity` and `stale`), optionally filtered by an exact type, by tags that must all be present, by status, by `verified` (`true`: a human's verification is current; `false`: never verified), `drifted` and `stale` (with an optional `now` instant); pages with `limit`/`offset` and reports the total match count. |
41
+ | `get_concept` | One concept by id: its whole decoded frontmatter, the file's raw markdown text, its bundle-relative path, every outgoing link, and the trust signal: `tier`, `integrity`, `stale` and `drift` (reason and who edited it, or null). |
42
42
  | `concept_neighbors` | A concept's graph neighbours — everything it links to and everything that links to it — each with its node kind and, for a concept target, its full summary. |
43
- | `stale_report` | Every concept whose `stale_after` instant has passed, each with its summary and how many whole days past it, as of now or an explicit instant. |
43
+ | `stale_report` | Every concept whose `stale_after` instant has passed, each with its summary and how many whole days past it, as of now or an explicit instant, plus a `drifted` array of concepts edited since a human verified them. |
44
44
  | `validate_bundle` | The same conformance and lint report `okfit validate --format json` produces, unchanged. Its `engine_version` and `okf_version` match the CLI's over one bundle; `okfit_version` is this package's own version and `producer` is `@okfit/mcp`. Optional `documents: [{ path, text }]` validates unsaved text (bundle-relative paths, a new file only under an existing directory) without writing it. |
45
45
 
46
46
  ## Resources
package/index.d.ts CHANGED
@@ -186,6 +186,10 @@ export declare const ListConceptsParams: Schema.Struct<{
186
186
  readonly type: Schema.optionalKey<Schema.String>;
187
187
  readonly tags: Schema.optionalKey<Schema.$Array<Schema.String>>;
188
188
  readonly status: Schema.optionalKey<Schema.Literals<readonly ["draft", "stable", "deprecated"]>>;
189
+ readonly verified: Schema.optionalKey<Schema.Boolean>;
190
+ readonly drifted: Schema.optionalKey<Schema.Boolean>;
191
+ readonly stale: Schema.optionalKey<Schema.Boolean>;
192
+ readonly now: Schema.optionalKey<Schema.String>;
189
193
  readonly limit: Schema.optionalKey<Schema.Int>;
190
194
  readonly offset: Schema.optionalKey<Schema.Int>;
191
195
  }>;
@@ -201,6 +205,9 @@ export declare const ListConceptsSuccess: Schema.Struct<{
201
205
  readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
202
206
  readonly tags: Schema.$Array<Schema.String>;
203
207
  readonly path: Schema.String;
208
+ readonly tier: Schema.Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
209
+ readonly integrity: Schema.Literals<readonly ["current", "drifted", "none"]>;
210
+ readonly stale: Schema.Boolean;
204
211
  }>>;
205
212
  readonly total: Schema.Int;
206
213
  }>;
@@ -223,6 +230,14 @@ export declare const GetConceptSuccess: Schema.Struct<{
223
230
  readonly source: Schema.Literals<readonly ["body", "frontmatter"]>;
224
231
  readonly field: Schema.optionalKey<Schema.String>;
225
232
  }>>;
233
+ readonly tier: Schema.Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
234
+ readonly integrity: Schema.Literals<readonly ["current", "drifted", "none"]>;
235
+ readonly stale: Schema.Boolean;
236
+ readonly drift: Schema.NullOr<Schema.Struct<{
237
+ readonly reason: Schema.Literals<readonly ["content-changed", "unbound", "entry-superseded", "actor-not-allowed"]>;
238
+ readonly edited_by: Schema.NullOr<Schema.String>;
239
+ readonly edited_at: Schema.NullOr<Schema.String>;
240
+ }>>;
226
241
  }>;
227
242
  /** @public */
228
243
  export type GetConceptSuccess = typeof GetConceptSuccess.Type;
@@ -238,6 +253,9 @@ export declare const Neighbor: Schema.Struct<{
238
253
  readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
239
254
  readonly tags: Schema.$Array<Schema.String>;
240
255
  readonly path: Schema.String;
256
+ readonly tier: Schema.Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
257
+ readonly integrity: Schema.Literals<readonly ["current", "drifted", "none"]>;
258
+ readonly stale: Schema.Boolean;
241
259
  }>>;
242
260
  }>;
243
261
  /** @public */
@@ -255,6 +273,9 @@ export declare const ConceptNeighborsSuccess: Schema.Struct<{
255
273
  readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
256
274
  readonly tags: Schema.$Array<Schema.String>;
257
275
  readonly path: Schema.String;
276
+ readonly tier: Schema.Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
277
+ readonly integrity: Schema.Literals<readonly ["current", "drifted", "none"]>;
278
+ readonly stale: Schema.Boolean;
258
279
  }>>;
259
280
  }>>;
260
281
  readonly incoming: Schema.$Array<Schema.Struct<{
@@ -268,6 +289,9 @@ export declare const ConceptNeighborsSuccess: Schema.Struct<{
268
289
  readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
269
290
  readonly tags: Schema.$Array<Schema.String>;
270
291
  readonly path: Schema.String;
292
+ readonly tier: Schema.Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
293
+ readonly integrity: Schema.Literals<readonly ["current", "drifted", "none"]>;
294
+ readonly stale: Schema.Boolean;
271
295
  }>>;
272
296
  }>>;
273
297
  }>;
@@ -291,10 +315,30 @@ export declare const StaleReportSuccess: Schema.Struct<{
291
315
  readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
292
316
  readonly tags: Schema.$Array<Schema.String>;
293
317
  readonly path: Schema.String;
318
+ readonly tier: Schema.Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
319
+ readonly integrity: Schema.Literals<readonly ["current", "drifted", "none"]>;
320
+ readonly stale: Schema.Boolean;
294
321
  }>;
295
322
  readonly stale_after: Schema.String;
296
323
  readonly days_past: Schema.Int;
297
324
  }>>;
325
+ readonly drifted: Schema.$Array<Schema.Struct<{
326
+ readonly summary: Schema.Struct<{
327
+ readonly id: Schema.String;
328
+ readonly type: Schema.String;
329
+ readonly title: Schema.String;
330
+ readonly description: Schema.NullOr<Schema.String>;
331
+ readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
332
+ readonly tags: Schema.$Array<Schema.String>;
333
+ readonly path: Schema.String;
334
+ readonly tier: Schema.Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
335
+ readonly integrity: Schema.Literals<readonly ["current", "drifted", "none"]>;
336
+ readonly stale: Schema.Boolean;
337
+ }>;
338
+ readonly reason: Schema.Literals<readonly ["content-changed", "unbound", "entry-superseded", "actor-not-allowed"]>;
339
+ readonly edited_by: Schema.NullOr<Schema.String>;
340
+ readonly edited_at: Schema.NullOr<Schema.String>;
341
+ }>>;
298
342
  }>;
299
343
  /** @public */
300
344
  export type StaleReportSuccess = typeof StaleReportSuccess.Type;
@@ -414,6 +458,9 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
414
458
  readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
415
459
  readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
416
460
  readonly path: import("effect/Schema").String;
461
+ readonly tier: import("effect/Schema").Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
462
+ readonly integrity: import("effect/Schema").Literals<readonly ["current", "drifted", "none"]>;
463
+ readonly stale: import("effect/Schema").Boolean;
417
464
  }>>;
418
465
  }>>;
419
466
  readonly incoming: import("effect/Schema").$Array<import("effect/Schema").Struct<{
@@ -427,12 +474,15 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
427
474
  readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
428
475
  readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
429
476
  readonly path: import("effect/Schema").String;
477
+ readonly tier: import("effect/Schema").Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
478
+ readonly integrity: import("effect/Schema").Literals<readonly ["current", "drifted", "none"]>;
479
+ readonly stale: import("effect/Schema").Boolean;
430
480
  }>>;
431
481
  }>>;
432
482
  }>;
433
483
  readonly failure: typeof import("@effected/mcp").ToolRefusal;
434
484
  readonly failureMode: "error";
435
- }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
485
+ }, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
436
486
  readonly describe_vocabulary: import("effect/ai/Tool").Tool<"describe_vocabulary", {
437
487
  readonly parameters: import("effect/ai/Tool").EmptyParams;
438
488
  readonly success: import("effect/Schema").Struct<{
@@ -506,15 +556,27 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
506
556
  readonly source: import("effect/Schema").Literals<readonly ["body", "frontmatter"]>;
507
557
  readonly field: import("effect/Schema").optionalKey<import("effect/Schema").String>;
508
558
  }>>;
559
+ readonly tier: import("effect/Schema").Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
560
+ readonly integrity: import("effect/Schema").Literals<readonly ["current", "drifted", "none"]>;
561
+ readonly stale: import("effect/Schema").Boolean;
562
+ readonly drift: import("effect/Schema").NullOr<import("effect/Schema").Struct<{
563
+ readonly reason: import("effect/Schema").Literals<readonly ["content-changed", "unbound", "entry-superseded", "actor-not-allowed"]>;
564
+ readonly edited_by: import("effect/Schema").NullOr<import("effect/Schema").String>;
565
+ readonly edited_at: import("effect/Schema").NullOr<import("effect/Schema").String>;
566
+ }>>;
509
567
  }>;
510
568
  readonly failure: typeof import("@effected/mcp").ToolRefusal;
511
569
  readonly failureMode: "error";
512
- }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
570
+ }, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
513
571
  readonly list_concepts: import("effect/ai/Tool").Tool<"list_concepts", {
514
572
  readonly parameters: import("effect/Schema").Struct<{
515
573
  readonly type: import("effect/Schema").optionalKey<import("effect/Schema").String>;
516
574
  readonly tags: import("effect/Schema").optionalKey<import("effect/Schema").$Array<import("effect/Schema").String>>;
517
575
  readonly status: import("effect/Schema").optionalKey<import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>>;
576
+ readonly verified: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
577
+ readonly drifted: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
578
+ readonly stale: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
579
+ readonly now: import("effect/Schema").optionalKey<import("effect/Schema").String>;
518
580
  readonly limit: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
519
581
  readonly offset: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
520
582
  }>;
@@ -527,12 +589,15 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
527
589
  readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
528
590
  readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
529
591
  readonly path: import("effect/Schema").String;
592
+ readonly tier: import("effect/Schema").Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
593
+ readonly integrity: import("effect/Schema").Literals<readonly ["current", "drifted", "none"]>;
594
+ readonly stale: import("effect/Schema").Boolean;
530
595
  }>>;
531
596
  readonly total: import("effect/Schema").Int;
532
597
  }>;
533
598
  readonly failure: typeof import("@effected/mcp").ToolRefusal;
534
599
  readonly failureMode: "error";
535
- }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
600
+ }, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
536
601
  readonly stale_report: import("effect/ai/Tool").Tool<"stale_report", {
537
602
  readonly parameters: import("effect/Schema").Struct<{
538
603
  readonly now: import("effect/Schema").optionalKey<import("effect/Schema").String>;
@@ -548,14 +613,34 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
548
613
  readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
549
614
  readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
550
615
  readonly path: import("effect/Schema").String;
616
+ readonly tier: import("effect/Schema").Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
617
+ readonly integrity: import("effect/Schema").Literals<readonly ["current", "drifted", "none"]>;
618
+ readonly stale: import("effect/Schema").Boolean;
551
619
  }>;
552
620
  readonly stale_after: import("effect/Schema").String;
553
621
  readonly days_past: import("effect/Schema").Int;
554
622
  }>>;
623
+ readonly drifted: import("effect/Schema").$Array<import("effect/Schema").Struct<{
624
+ readonly summary: import("effect/Schema").Struct<{
625
+ readonly id: import("effect/Schema").String;
626
+ readonly type: import("effect/Schema").String;
627
+ readonly title: import("effect/Schema").String;
628
+ readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
629
+ readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
630
+ readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
631
+ readonly path: import("effect/Schema").String;
632
+ readonly tier: import("effect/Schema").Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
633
+ readonly integrity: import("effect/Schema").Literals<readonly ["current", "drifted", "none"]>;
634
+ readonly stale: import("effect/Schema").Boolean;
635
+ }>;
636
+ readonly reason: import("effect/Schema").Literals<readonly ["content-changed", "unbound", "entry-superseded", "actor-not-allowed"]>;
637
+ readonly edited_by: import("effect/Schema").NullOr<import("effect/Schema").String>;
638
+ readonly edited_at: import("effect/Schema").NullOr<import("effect/Schema").String>;
639
+ }>>;
555
640
  }>;
556
641
  readonly failure: typeof import("@effected/mcp").ToolRefusal;
557
642
  readonly failureMode: "error";
558
- }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
643
+ }, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
559
644
  readonly validate_bundle: import("effect/ai/Tool").Tool<"validate_bundle", {
560
645
  readonly parameters: import("effect/Schema").Struct<{
561
646
  readonly now: import("effect/Schema").optionalKey<import("effect/Schema").String>;
@@ -624,6 +709,9 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
624
709
  readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
625
710
  readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
626
711
  readonly path: import("effect/Schema").String;
712
+ readonly tier: import("effect/Schema").Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
713
+ readonly integrity: import("effect/Schema").Literals<readonly ["current", "drifted", "none"]>;
714
+ readonly stale: import("effect/Schema").Boolean;
627
715
  }>>;
628
716
  }>>;
629
717
  readonly incoming: import("effect/Schema").$Array<import("effect/Schema").Struct<{
@@ -637,12 +725,15 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
637
725
  readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
638
726
  readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
639
727
  readonly path: import("effect/Schema").String;
728
+ readonly tier: import("effect/Schema").Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
729
+ readonly integrity: import("effect/Schema").Literals<readonly ["current", "drifted", "none"]>;
730
+ readonly stale: import("effect/Schema").Boolean;
640
731
  }>>;
641
732
  }>>;
642
733
  }>;
643
734
  readonly failure: typeof import("@effected/mcp").ToolRefusal;
644
735
  readonly failureMode: "error";
645
- }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
736
+ }, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
646
737
  readonly describe_vocabulary: import("effect/ai/Tool").Tool<"describe_vocabulary", {
647
738
  readonly parameters: import("effect/ai/Tool").EmptyParams;
648
739
  readonly success: import("effect/Schema").Struct<{
@@ -716,15 +807,27 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
716
807
  readonly source: import("effect/Schema").Literals<readonly ["body", "frontmatter"]>;
717
808
  readonly field: import("effect/Schema").optionalKey<import("effect/Schema").String>;
718
809
  }>>;
810
+ readonly tier: import("effect/Schema").Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
811
+ readonly integrity: import("effect/Schema").Literals<readonly ["current", "drifted", "none"]>;
812
+ readonly stale: import("effect/Schema").Boolean;
813
+ readonly drift: import("effect/Schema").NullOr<import("effect/Schema").Struct<{
814
+ readonly reason: import("effect/Schema").Literals<readonly ["content-changed", "unbound", "entry-superseded", "actor-not-allowed"]>;
815
+ readonly edited_by: import("effect/Schema").NullOr<import("effect/Schema").String>;
816
+ readonly edited_at: import("effect/Schema").NullOr<import("effect/Schema").String>;
817
+ }>>;
719
818
  }>;
720
819
  readonly failure: typeof import("@effected/mcp").ToolRefusal;
721
820
  readonly failureMode: "error";
722
- }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
821
+ }, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
723
822
  readonly list_concepts: import("effect/ai/Tool").Tool<"list_concepts", {
724
823
  readonly parameters: import("effect/Schema").Struct<{
725
824
  readonly type: import("effect/Schema").optionalKey<import("effect/Schema").String>;
726
825
  readonly tags: import("effect/Schema").optionalKey<import("effect/Schema").$Array<import("effect/Schema").String>>;
727
826
  readonly status: import("effect/Schema").optionalKey<import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>>;
827
+ readonly verified: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
828
+ readonly drifted: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
829
+ readonly stale: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
830
+ readonly now: import("effect/Schema").optionalKey<import("effect/Schema").String>;
728
831
  readonly limit: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
729
832
  readonly offset: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
730
833
  }>;
@@ -737,12 +840,15 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
737
840
  readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
738
841
  readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
739
842
  readonly path: import("effect/Schema").String;
843
+ readonly tier: import("effect/Schema").Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
844
+ readonly integrity: import("effect/Schema").Literals<readonly ["current", "drifted", "none"]>;
845
+ readonly stale: import("effect/Schema").Boolean;
740
846
  }>>;
741
847
  readonly total: import("effect/Schema").Int;
742
848
  }>;
743
849
  readonly failure: typeof import("@effected/mcp").ToolRefusal;
744
850
  readonly failureMode: "error";
745
- }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
851
+ }, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
746
852
  readonly stale_report: import("effect/ai/Tool").Tool<"stale_report", {
747
853
  readonly parameters: import("effect/Schema").Struct<{
748
854
  readonly now: import("effect/Schema").optionalKey<import("effect/Schema").String>;
@@ -758,14 +864,34 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
758
864
  readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
759
865
  readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
760
866
  readonly path: import("effect/Schema").String;
867
+ readonly tier: import("effect/Schema").Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
868
+ readonly integrity: import("effect/Schema").Literals<readonly ["current", "drifted", "none"]>;
869
+ readonly stale: import("effect/Schema").Boolean;
761
870
  }>;
762
871
  readonly stale_after: import("effect/Schema").String;
763
872
  readonly days_past: import("effect/Schema").Int;
764
873
  }>>;
874
+ readonly drifted: import("effect/Schema").$Array<import("effect/Schema").Struct<{
875
+ readonly summary: import("effect/Schema").Struct<{
876
+ readonly id: import("effect/Schema").String;
877
+ readonly type: import("effect/Schema").String;
878
+ readonly title: import("effect/Schema").String;
879
+ readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
880
+ readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
881
+ readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
882
+ readonly path: import("effect/Schema").String;
883
+ readonly tier: import("effect/Schema").Literals<readonly ["unverified", "machine-confirmed", "human-reviewed"]>;
884
+ readonly integrity: import("effect/Schema").Literals<readonly ["current", "drifted", "none"]>;
885
+ readonly stale: import("effect/Schema").Boolean;
886
+ }>;
887
+ readonly reason: import("effect/Schema").Literals<readonly ["content-changed", "unbound", "entry-superseded", "actor-not-allowed"]>;
888
+ readonly edited_by: import("effect/Schema").NullOr<import("effect/Schema").String>;
889
+ readonly edited_at: import("effect/Schema").NullOr<import("effect/Schema").String>;
890
+ }>>;
765
891
  }>;
766
892
  readonly failure: typeof import("@effected/mcp").ToolRefusal;
767
893
  readonly failureMode: "error";
768
- }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
894
+ }, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
769
895
  readonly validate_bundle: import("effect/ai/Tool").Tool<"validate_bundle", {
770
896
  readonly parameters: import("effect/Schema").Struct<{
771
897
  readonly now: import("effect/Schema").optionalKey<import("effect/Schema").String>;
@@ -0,0 +1,16 @@
1
+ import { messageOf } from "./toolContext.js";
2
+ import { ToolRefusal } from "@effected/mcp";
3
+ import { Effect } from "effect";
4
+ import { Trust } from "@okfit/profiles";
5
+
6
+ //#region src/internal/toolSignals.ts
7
+ /**
8
+ * `Trust.signals` with its platform failure (a concept file unreadable while
9
+ * hashing) collapsed to the tools' one declared failure, a `ToolRefusal`.
10
+ *
11
+ * @internal
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." })));
14
+
15
+ //#endregion
16
+ export { toolSignals };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@okfit/mcp",
3
- "version": "0.8.4",
3
+ "version": "0.9.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,24 @@
44
44
  "okfit-mcp": "bin/okfit-mcp.js"
45
45
  },
46
46
  "dependencies": {
47
- "@effect/platform-node": "^4.0.2",
48
- "@effected/config-file": "^0.14.2",
49
- "@effected/engine": "^0.4.0",
50
- "@effected/git": "^0.20.0",
51
- "@effected/glob": "^0.10.0",
52
- "@effected/jsonc": "^0.15.1",
53
- "@effected/markdown": "^0.15.1",
54
- "@effected/mcp": "^0.5.0",
55
- "@effected/schemastore": "^0.21.4",
56
- "@effected/toml": "^0.11.1",
57
- "@effected/walker": "^0.15.0",
58
- "@effected/xdg": "^0.9.0",
59
- "@effected/yaml": "^0.19.1",
60
- "@okfit/core": "0.9.2",
61
- "@okfit/engine": "0.14.1",
62
- "@okfit/profiles": "0.9.0",
63
- "effect": "^4.0.2"
47
+ "@effect/platform-node": "^4.0.3",
48
+ "@effect/platform-node-shared": "^4.0.3",
49
+ "@effected/config-file": "^0.15.0",
50
+ "@effected/engine": "^0.5.0",
51
+ "@effected/git": "^0.21.0",
52
+ "@effected/glob": "^0.11.0",
53
+ "@effected/jsonc": "^0.16.0",
54
+ "@effected/markdown": "^0.16.0",
55
+ "@effected/mcp": "^0.6.0",
56
+ "@effected/schemastore": "^0.22.0",
57
+ "@effected/toml": "^0.12.0",
58
+ "@effected/walker": "^0.16.0",
59
+ "@effected/xdg": "^0.10.0",
60
+ "@effected/yaml": "^0.20.0",
61
+ "@okfit/core": "0.10.0",
62
+ "@okfit/engine": "0.15.0",
63
+ "@okfit/profiles": "0.10.0",
64
+ "effect": "^4.0.3"
64
65
  },
65
66
  "engines": {
66
67
  "node": ">=24.11.0"
package/schema/tools.js CHANGED
@@ -1,7 +1,8 @@
1
1
  import { ConceptSummary } from "./ConceptSummary.js";
2
2
  import { GraphNodeKind, Status } from "@okfit/core";
3
3
  import { Schema } from "effect";
4
- import { ContextTag, ContextType } from "@okfit/engine";
4
+ import { ContextTag, ContextType, TrustDrift } from "@okfit/engine";
5
+ import { DriftReason } from "@okfit/profiles";
5
6
 
6
7
  //#region src/schema/tools.ts
7
8
  /** One Surface template inside a docs preset, as `describe_vocabulary` reports it. @public */
@@ -52,6 +53,10 @@ const ListConceptsParams = Schema.Struct({
52
53
  type: Schema.optionalKey(Schema.String),
53
54
  tags: Schema.optionalKey(Schema.Array(Schema.String)),
54
55
  status: Schema.optionalKey(Status),
56
+ verified: Schema.optionalKey(Schema.Boolean),
57
+ drifted: Schema.optionalKey(Schema.Boolean),
58
+ stale: Schema.optionalKey(Schema.Boolean),
59
+ now: Schema.optionalKey(Schema.String),
55
60
  limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({
56
61
  minimum: 1,
57
62
  maximum: 1e3
@@ -79,7 +84,19 @@ const GetConceptSuccess = Schema.Struct({
79
84
  kind: GraphNodeKind,
80
85
  source: Schema.Literals(["body", "frontmatter"]),
81
86
  field: Schema.optionalKey(Schema.String)
82
- }))
87
+ })),
88
+ tier: Schema.Literals([
89
+ "unverified",
90
+ "machine-confirmed",
91
+ "human-reviewed"
92
+ ]),
93
+ integrity: Schema.Literals([
94
+ "current",
95
+ "drifted",
96
+ "none"
97
+ ]),
98
+ stale: Schema.Boolean,
99
+ drift: Schema.NullOr(TrustDrift)
83
100
  });
84
101
  /** One graph neighbour: flat, with a nullable summary (J-4). @public */
85
102
  const Neighbor = Schema.Struct({
@@ -101,6 +118,12 @@ const StaleReportSuccess = Schema.Struct({
101
118
  summary: ConceptSummary,
102
119
  stale_after: Schema.String,
103
120
  days_past: Schema.Int
121
+ })),
122
+ drifted: Schema.Array(Schema.Struct({
123
+ summary: ConceptSummary,
124
+ reason: DriftReason,
125
+ edited_by: Schema.NullOr(Schema.String),
126
+ edited_at: Schema.NullOr(Schema.String)
104
127
  }))
105
128
  });
106
129
  /** One unsaved document for `validate_bundle`: bundle-relative posix `path`, full `text`. @public */
package/server.js CHANGED
@@ -5,8 +5,8 @@ import { OkfitToolkit, ToolsLayer } from "./toolkit.js";
5
5
  import { McpStdio, McpToolkit } from "@effected/mcp";
6
6
  import { Layer } from "effect";
7
7
  import { McpProtocol } from "effect/ai";
8
- import { Git } from "@effected/git";
9
8
  import { GitHistory } from "@okfit/profiles";
9
+ import { Git } from "@effected/git";
10
10
 
11
11
  //#region src/server.ts
12
12
  /**
@@ -28,6 +28,9 @@ const SERVER_INSTRUCTIONS = [
28
28
  "Every successful tools/call result carries the typed payload in structuredContent and a JSON rendering in",
29
29
  "content[0].text. A failed call is isError: true with the human message and a remediation hint in",
30
30
  "content[0].text and no structuredContent; read that text before retrying.",
31
+ "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
+ "drifted when it changed since (the reason says why), and none when no human verified it; stale means past stale_after.",
33
+ "Drifted concepts are safe to edit and read, but weigh them below current ones; only a human re-verifies.",
31
34
  "Resources: okf://index is the bundle's root index.md, and okf://concept/<id> is one static resource per concept."
32
35
  ].join(" ");
33
36
  /**
@@ -3,9 +3,10 @@ import { loadToolContext } from "../internal/toolContext.js";
3
3
  import { toConceptSummary } from "../schema/ConceptSummary.js";
4
4
  import { ConceptNeighborsSuccess } from "../schema/tools.js";
5
5
  import { toConceptLookupFailure } from "../internal/conceptNotFound.js";
6
- import { Effect, FileSystem, Path, Schema } from "effect";
6
+ import { toolSignals } from "../internal/toolSignals.js";
7
+ import { Crypto, DateTime, Effect, FileSystem, Path, Schema } from "effect";
7
8
  import { Tool } from "effect/ai";
8
- import { ConceptQuery } from "@okfit/engine";
9
+ import { ConceptQuery, signalFor } from "@okfit/engine";
9
10
  import { AppDirs, Xdg } from "@effected/xdg";
10
11
 
11
12
  //#region src/tools/conceptNeighbors.ts
@@ -26,7 +27,8 @@ const conceptNeighbors = Tool.make("concept_neighbors", {
26
27
  FileSystem.FileSystem,
27
28
  Path.Path,
28
29
  AppDirs,
29
- Xdg
30
+ Xdg,
31
+ Crypto.Crypto
30
32
  ]
31
33
  }).annotate(Tool.Title, "Concept graph neighbors").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
32
34
  /**
@@ -41,10 +43,11 @@ const conceptNeighbors = Tool.make("concept_neighbors", {
41
43
  const handleConceptNeighbors = (projectRoot, params) => Effect.gen(function* () {
42
44
  const ctx = yield* loadToolContext(projectRoot);
43
45
  const result = yield* ConceptQuery.neighbors(ctx.bundle, params.id).pipe(Effect.catchTag("QueryConceptNotFoundError", (e) => toConceptLookupFailure(params.id, e)));
46
+ const signals = yield* toolSignals(ctx.bundle, ctx.config, yield* DateTime.now);
44
47
  const project = (neighbor) => ({
45
48
  id: neighbor.id,
46
49
  kind: neighbor.kind,
47
- summary: neighbor.concept === null ? null : toConceptSummary(neighbor.concept)
50
+ summary: neighbor.concept === null ? null : toConceptSummary(neighbor.concept, signalFor(signals, neighbor.concept.id))
48
51
  });
49
52
  return {
50
53
  outgoing: result.outgoing.map(project),
@@ -2,14 +2,15 @@ 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 { toolSignals } from "../internal/toolSignals.js";
5
6
  import { Derive } from "@okfit/core";
6
- import { Effect, FileSystem, Path, Schema } from "effect";
7
+ import { Crypto, DateTime, Effect, FileSystem, Path, Schema } from "effect";
7
8
  import { Tool } from "effect/ai";
8
- import { ConceptQuery } from "@okfit/engine";
9
+ import { ConceptQuery, signalFor, toTrustDrift } from "@okfit/engine";
9
10
  import { AppDirs, Xdg } from "@effected/xdg";
10
11
 
11
12
  //#region src/tools/getConcept.ts
12
- const DESCRIPTION = "Returns one concept by id: its whole decoded frontmatter, the file's raw markdown text, its bundle-relative path, and every outgoing link with where the link was written and whether the target is another concept, an existing file, or missing. Accepts a tolerant id, with or without a leading slash or a trailing .md.";
13
+ const DESCRIPTION = "Returns one concept by id: its decoded frontmatter, raw markdown, bundle-relative path, every outgoing link (with where it was written and whether the target is a concept, a file, or missing), and its okfit trust signal: tier, integrity, stale and drift. Accepts a tolerant id, with or without a leading slash or trailing .md.";
13
14
  /**
14
15
  * `dependencies` mirrors `list_concepts`' and `describe_vocabulary`'s
15
16
  * (Task B1's Deviation 1, carried through Task C1): `loadToolContext` needs
@@ -28,7 +29,8 @@ const getConcept = Tool.make("get_concept", {
28
29
  FileSystem.FileSystem,
29
30
  Path.Path,
30
31
  AppDirs,
31
- Xdg
32
+ Xdg,
33
+ Crypto.Crypto
32
34
  ]
33
35
  }).annotate(Tool.Title, "Get one OKF concept").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
34
36
  /**
@@ -43,6 +45,8 @@ const getConcept = Tool.make("get_concept", {
43
45
  const handleGetConcept = (projectRoot, params) => Effect.gen(function* () {
44
46
  const ctx = yield* loadToolContext(projectRoot);
45
47
  const { concept, links } = yield* ConceptQuery.get(ctx.bundle, params.id).pipe(Effect.catchTag("QueryConceptNotFoundError", (e) => toConceptLookupFailure(params.id, e)));
48
+ const signals = yield* toolSignals(ctx.bundle, ctx.config, yield* DateTime.now);
49
+ const signal = signalFor(signals, concept.id);
46
50
  return {
47
51
  id: concept.id,
48
52
  type: concept.frontmatter.type,
@@ -53,7 +57,11 @@ const handleGetConcept = (projectRoot, params) => Effect.gen(function* () {
53
57
  path: concept.path,
54
58
  frontmatter: concept.frontmatter.raw,
55
59
  raw: concept.document.source,
56
- links
60
+ links,
61
+ tier: signal.tier,
62
+ integrity: signal.integrity,
63
+ stale: signal.stale,
64
+ drift: toTrustDrift(signal)
57
65
  };
58
66
  });
59
67
 
@@ -2,14 +2,16 @@ 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 { toolSignals } from "../internal/toolSignals.js";
6
+ import { resolveNow } from "../internal/resolveNow.js";
5
7
  import { ToolFailure, ToolRefusal } from "@effected/mcp";
6
- import { Effect, FileSystem, Path } from "effect";
8
+ import { Crypto, Effect, FileSystem, Path } from "effect";
7
9
  import { Tool } from "effect/ai";
8
- import { ConceptQuery } from "@okfit/engine";
10
+ import { ConceptQuery, signalFor } from "@okfit/engine";
9
11
  import { AppDirs, Xdg } from "@effected/xdg";
10
12
 
11
13
  //#region src/tools/listConcepts.ts
12
- const DESCRIPTION = "Lists concept summaries from the okf bundle, optionally filtered by an exact type, by tags that must all be present (AND, not OR), and by status. Pages with limit (default 200, max 1000) and offset, and reports the total matching count. Use it to discover what exists before reading one concept with get_concept; an unknown type or tag name fails with the list of valid names.";
14
+ const DESCRIPTION = "Lists concept summaries, filtered by exact type, tags that must all be present (AND), status, verified (true: current human verification; false: never verified), drifted or stale. Each summary carries tier, integrity and stale. now (ISO-8601 with offset) sets the staleness time. Pages by limit (default 200, max 1000) and offset, with total. An unknown type or tag fails with the valid names.";
13
15
  /**
14
16
  * `dependencies` mirrors `describe_vocabulary`'s (Deviation 1 in Task B1's
15
17
  * report): `loadToolContext` needs the same platform services
@@ -29,7 +31,8 @@ const listConcepts = Tool.make("list_concepts", {
29
31
  FileSystem.FileSystem,
30
32
  Path.Path,
31
33
  AppDirs,
32
- Xdg
34
+ Xdg,
35
+ Crypto.Crypto
33
36
  ]
34
37
  }).annotate(Tool.Title, "List OKF concepts").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
35
38
  /**
@@ -52,15 +55,20 @@ const unknown = (kind, requested, valid) => {
52
55
  /** @public */
53
56
  const handleListConcepts = (projectRoot, params) => Effect.gen(function* () {
54
57
  const ctx = yield* loadToolContext(projectRoot);
58
+ const now = yield* resolveNow(params.now);
59
+ const signals = yield* toolSignals(ctx.bundle, ctx.config, now);
55
60
  const filtered = yield* ConceptQuery.list(ctx.bundle, ctx.config, {
56
61
  ...params.type === void 0 ? {} : { types: [params.type] },
57
62
  ...params.tags === void 0 ? {} : { tags: params.tags },
58
- ...params.status === void 0 ? {} : { statuses: [params.status] }
59
- }).pipe(Effect.catchTag("QueryUnknownVocabularyError", (e) => Effect.fail(unknown(e.kind, e.requested, e.valid))));
63
+ ...params.status === void 0 ? {} : { statuses: [params.status] },
64
+ ...params.verified === void 0 ? {} : { verified: params.verified ? "current" : "unverified" },
65
+ ...params.drifted === void 0 ? {} : { drifted: params.drifted },
66
+ ...params.stale === void 0 ? {} : { stale: params.stale }
67
+ }, signals).pipe(Effect.catchTag("QueryUnknownVocabularyError", (e) => Effect.fail(unknown(e.kind, e.requested, e.valid))));
60
68
  const limit = params.limit ?? 200;
61
69
  const offset = params.offset ?? 0;
62
70
  return {
63
- items: filtered.slice(offset, offset + limit).map(toConceptSummary),
71
+ items: filtered.slice(offset, offset + limit).map((c) => toConceptSummary(c, signalFor(signals, c.id))),
64
72
  total: filtered.length
65
73
  };
66
74
  });
@@ -2,14 +2,16 @@ import { McpToolError } from "../errors.js";
2
2
  import { loadToolContext } from "../internal/toolContext.js";
3
3
  import { toConceptSummary } from "../schema/ConceptSummary.js";
4
4
  import { StaleReportParams, StaleReportSuccess } from "../schema/tools.js";
5
+ import { toolSignals } from "../internal/toolSignals.js";
5
6
  import { resolveNow } from "../internal/resolveNow.js";
6
7
  import { Derive } from "@okfit/core";
7
- import { DateTime, Effect, FileSystem, Path } from "effect";
8
+ import { Crypto, DateTime, Effect, FileSystem, Path } from "effect";
8
9
  import { Tool } from "effect/ai";
10
+ import { signalFor, toTrustDrift } from "@okfit/engine";
9
11
  import { AppDirs, Xdg } from "@effected/xdg";
10
12
 
11
13
  //#region src/tools/staleReport.ts
12
- const DESCRIPTION = "Lists every concept whose stale_after instant has passed, each with its summary, the date, and how many whole days past it. Uses the current time by default; pass now as an ISO-8601 instant with an explicit offset to report staleness as of a different moment.";
14
+ const DESCRIPTION = "Lists every stale or drifted concept. items: stale_after passed, each with its summary, the date and whole days past. drifted: human-verified concepts whose content changed since (or was never bound), with the reason and last editor. Uses the current time unless now is given (ISO-8601 with an explicit offset).";
13
15
  /**
14
16
  * `dependencies` mirrors the other tools' (Task B1's Deviation 1):
15
17
  * `loadToolContext` needs the same platform services, and without a
@@ -28,24 +30,37 @@ const staleReport = Tool.make("stale_report", {
28
30
  FileSystem.FileSystem,
29
31
  Path.Path,
30
32
  AppDirs,
31
- Xdg
33
+ Xdg,
34
+ Crypto.Crypto
32
35
  ]
33
36
  }).annotate(Tool.Title, "Stale concepts").annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
34
37
  /** @public */
35
38
  const handleStaleReport = (projectRoot, params) => Effect.gen(function* () {
36
39
  const ctx = yield* loadToolContext(projectRoot);
37
40
  const now = yield* resolveNow(params.now);
41
+ const signals = yield* toolSignals(ctx.bundle, ctx.config, now);
38
42
  const items = Derive.staleReport(ctx.bundle, now).flatMap((entry) => {
39
43
  const concept = ctx.bundle.concepts.get(entry.id);
40
44
  return concept === void 0 ? [] : [{
41
- summary: toConceptSummary(concept),
45
+ summary: toConceptSummary(concept, signalFor(signals, concept.id)),
42
46
  stale_after: DateTime.formatIso(entry.staleAfter),
43
47
  days_past: entry.daysPast
44
48
  }];
45
49
  });
50
+ const drifted = [...ctx.bundle.concepts.values()].flatMap((concept) => {
51
+ const signal = signalFor(signals, concept.id);
52
+ const drift = toTrustDrift(signal);
53
+ return drift === null ? [] : [{
54
+ summary: toConceptSummary(concept, signal),
55
+ reason: drift.reason,
56
+ edited_by: drift.edited_by,
57
+ edited_at: drift.edited_at
58
+ }];
59
+ });
46
60
  return {
47
61
  as_of: DateTime.formatIso(now),
48
- items
62
+ items,
63
+ drifted
49
64
  };
50
65
  });
51
66
 
@@ -8,8 +8,8 @@ import { OKF_SPEC_VERSION } from "@okfit/core";
8
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
- import { Git } from "@effected/git";
12
11
  import { GitHistory } from "@okfit/profiles";
12
+ import { Git } from "@effected/git";
13
13
  import { AppDirs, Xdg } from "@effected/xdg";
14
14
 
15
15
  //#region src/tools/validateBundle.ts
package/version.js CHANGED
@@ -5,7 +5,7 @@
5
5
  *
6
6
  * @public
7
7
  */
8
- const MCP_VERSION = "0.8.4";
8
+ const MCP_VERSION = "0.9.0";
9
9
 
10
10
  //#endregion
11
11
  export { MCP_VERSION };