@okfit/mcp 0.6.8 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +4 -10
- package/errors.js +13 -44
- package/index.d.ts +127 -81
- package/index.js +3 -3
- package/internal/conceptNotFound.js +9 -23
- package/internal/resolveNow.js +4 -10
- package/internal/toolContext.js +5 -13
- package/main.d.ts +12 -18
- package/main.js +39 -43
- package/package.json +14 -14
- package/resources/conceptResource.js +1 -1
- package/schema/tools.js +35 -3
- package/tools/describeVocabulary.js +16 -2
- package/tools/getConcept.js +1 -1
- package/tools/listConcepts.js +3 -9
- package/tools/staleReport.js +1 -1
- package/tools/validateBundle.js +5 -16
- package/version.js +1 -1
package/README.md
CHANGED
|
@@ -60,16 +60,10 @@ or `.config/okfit.toml`.
|
|
|
60
60
|
|
|
61
61
|
A failing tool call reaches the client as `isError: true`, with the
|
|
62
62
|
remediation text folded directly into the message — there is no separate
|
|
63
|
-
structured error field on the wire.
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
not be read.
|
|
68
|
-
- `ConceptNotFound` — no concept in the bundle has the requested id.
|
|
69
|
-
- `UnknownVocabulary` — a requested type or tag name is not declared in
|
|
70
|
-
the resolved config.
|
|
71
|
-
- `InvalidArgument` — a tool argument was structurally acceptable but
|
|
72
|
-
semantically invalid.
|
|
63
|
+
structured error field on the wire. `McpToolError` is `@effected/mcp`'s
|
|
64
|
+
`ToolRefusal`: config failures, an unreadable bundle root, an unknown
|
|
65
|
+
concept id, an undeclared type or tag, and an invalid argument all refuse
|
|
66
|
+
with a message that names the problem and what to do next.
|
|
73
67
|
|
|
74
68
|
## License
|
|
75
69
|
|
package/errors.js
CHANGED
|
@@ -1,52 +1,21 @@
|
|
|
1
1
|
import { Remediation } from "@effected/engine";
|
|
2
|
-
import {
|
|
3
|
-
import { Schema } from "effect";
|
|
2
|
+
import { ToolRefusal } from "@effected/mcp";
|
|
4
3
|
|
|
5
4
|
//#region src/errors.ts
|
|
6
5
|
/**
|
|
7
|
-
*
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
*
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
/**
|
|
18
|
-
* No concept in the bundle has the requested id. @public
|
|
19
|
-
*/
|
|
20
|
-
var ConceptNotFound = class extends Schema.TaggedError()("ConceptNotFound", {
|
|
21
|
-
...ToolFailure.fields,
|
|
22
|
-
id: Schema.String
|
|
23
|
-
}) {};
|
|
24
|
-
/**
|
|
25
|
-
* A requested type or tag name is not declared in the resolved config.
|
|
26
|
-
* @public
|
|
27
|
-
*/
|
|
28
|
-
var UnknownVocabulary = class extends Schema.TaggedError()("UnknownVocabulary", {
|
|
29
|
-
...ToolFailure.fields,
|
|
30
|
-
kind: Schema.Literals(["type", "tag"]),
|
|
31
|
-
requested: Schema.String,
|
|
32
|
-
valid: Schema.Array(Schema.String)
|
|
33
|
-
}) {};
|
|
34
|
-
/**
|
|
35
|
-
* A tool argument was structurally acceptable but semantically invalid.
|
|
6
|
+
* The one failure schema every tool declares (N-14): `ToolRefusal` from
|
|
7
|
+
* `@effected/mcp`.
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* Replaces five bespoke tagged errors. Under `failureMode: "error"` a declared
|
|
11
|
+
* failure reaches the agent as `error.message` alone, so the structured fields
|
|
12
|
+
* they carried were never on the wire; the reason text names them and
|
|
13
|
+
* `ToolRefusal.refuse` folds the remediation in. Callers discriminate on the
|
|
14
|
+
* message, never on a tag.
|
|
15
|
+
*
|
|
36
16
|
* @public
|
|
37
17
|
*/
|
|
38
|
-
|
|
39
|
-
...ToolFailure.fields,
|
|
40
|
-
argument: Schema.String
|
|
41
|
-
}) {};
|
|
42
|
-
/** The one failure schema every tool declares (N-14). @public */
|
|
43
|
-
const McpToolError = Schema.Union([
|
|
44
|
-
ConfigError,
|
|
45
|
-
BundleNotFound,
|
|
46
|
-
ConceptNotFound,
|
|
47
|
-
UnknownVocabulary,
|
|
48
|
-
InvalidArgument
|
|
49
|
-
]);
|
|
18
|
+
const McpToolError = ToolRefusal;
|
|
50
19
|
|
|
51
20
|
//#endregion
|
|
52
|
-
export {
|
|
21
|
+
export { McpToolError, Remediation };
|
package/index.d.ts
CHANGED
|
@@ -1,82 +1,27 @@
|
|
|
1
1
|
import { Remediation } from "@effected/engine";
|
|
2
|
-
import {
|
|
2
|
+
import { ToolRefusal } from "@effected/mcp";
|
|
3
3
|
import { AppDirs, Xdg } from "@effected/xdg";
|
|
4
|
+
import { FileSystem, Layer, Path, Schema, Stdio } from "effect";
|
|
4
5
|
import { ConceptSummary, Distribution, toConceptSummary } from "@okfit/engine";
|
|
5
6
|
import { ChildProcessSpawner } from "effect/process";
|
|
6
7
|
import { Toolkit } from "effect/ai";
|
|
7
8
|
//#region src/errors.d.ts
|
|
8
|
-
declare const ConfigError_base: Schema.Class<ConfigError, Schema.TaggedStruct<"ConfigError", {
|
|
9
|
-
readonly message: Schema.String;
|
|
10
|
-
readonly remediation: Schema.Struct<{
|
|
11
|
-
readonly hint: Schema.String;
|
|
12
|
-
readonly suggestedTool: Schema.optionalKey<Schema.String>;
|
|
13
|
-
readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
|
|
14
|
-
}>;
|
|
15
|
-
}>, import("effect/Cause").YieldableError>;
|
|
16
|
-
/**
|
|
17
|
-
* Config discovery, parsing, or validation failed. @public
|
|
18
|
-
*/
|
|
19
|
-
export declare class ConfigError extends ConfigError_base {}
|
|
20
|
-
declare const BundleNotFound_base: Schema.Class<BundleNotFound, Schema.TaggedStruct<"BundleNotFound", {
|
|
21
|
-
readonly message: Schema.String;
|
|
22
|
-
readonly remediation: Schema.Struct<{
|
|
23
|
-
readonly hint: Schema.String;
|
|
24
|
-
readonly suggestedTool: Schema.optionalKey<Schema.String>;
|
|
25
|
-
readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
|
|
26
|
-
}>;
|
|
27
|
-
readonly root: Schema.String;
|
|
28
|
-
}>, import("effect/Cause").YieldableError>;
|
|
29
9
|
/**
|
|
30
|
-
* The
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
readonly id: Schema.String;
|
|
41
|
-
}>, import("effect/Cause").YieldableError>;
|
|
42
|
-
/**
|
|
43
|
-
* No concept in the bundle has the requested id. @public
|
|
44
|
-
*/
|
|
45
|
-
export declare class ConceptNotFound extends ConceptNotFound_base {}
|
|
46
|
-
declare const UnknownVocabulary_base: Schema.Class<UnknownVocabulary, Schema.TaggedStruct<"UnknownVocabulary", {
|
|
47
|
-
readonly message: Schema.String;
|
|
48
|
-
readonly remediation: Schema.Struct<{
|
|
49
|
-
readonly hint: Schema.String;
|
|
50
|
-
readonly suggestedTool: Schema.optionalKey<Schema.String>;
|
|
51
|
-
readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
|
|
52
|
-
}>;
|
|
53
|
-
readonly kind: Schema.Literals<readonly ["type", "tag"]>;
|
|
54
|
-
readonly requested: Schema.String;
|
|
55
|
-
readonly valid: Schema.$Array<Schema.String>;
|
|
56
|
-
}>, import("effect/Cause").YieldableError>;
|
|
57
|
-
/**
|
|
58
|
-
* A requested type or tag name is not declared in the resolved config.
|
|
59
|
-
* @public
|
|
60
|
-
*/
|
|
61
|
-
export declare class UnknownVocabulary extends UnknownVocabulary_base {}
|
|
62
|
-
declare const InvalidArgument_base: Schema.Class<InvalidArgument, Schema.TaggedStruct<"InvalidArgument", {
|
|
63
|
-
readonly message: Schema.String;
|
|
64
|
-
readonly remediation: Schema.Struct<{
|
|
65
|
-
readonly hint: Schema.String;
|
|
66
|
-
readonly suggestedTool: Schema.optionalKey<Schema.String>;
|
|
67
|
-
readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
|
|
68
|
-
}>;
|
|
69
|
-
readonly argument: Schema.String;
|
|
70
|
-
}>, import("effect/Cause").YieldableError>;
|
|
71
|
-
/**
|
|
72
|
-
* A tool argument was structurally acceptable but semantically invalid.
|
|
10
|
+
* The one failure schema every tool declares (N-14): `ToolRefusal` from
|
|
11
|
+
* `@effected/mcp`.
|
|
12
|
+
*
|
|
13
|
+
* @remarks
|
|
14
|
+
* Replaces five bespoke tagged errors. Under `failureMode: "error"` a declared
|
|
15
|
+
* failure reaches the agent as `error.message` alone, so the structured fields
|
|
16
|
+
* they carried were never on the wire; the reason text names them and
|
|
17
|
+
* `ToolRefusal.refuse` folds the remediation in. Callers discriminate on the
|
|
18
|
+
* message, never on a tag.
|
|
19
|
+
*
|
|
73
20
|
* @public
|
|
74
21
|
*/
|
|
75
|
-
export declare
|
|
76
|
-
/** The one failure schema every tool declares (N-14). @public */
|
|
77
|
-
export declare const McpToolError: Schema.Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
|
|
22
|
+
export declare const McpToolError: typeof ToolRefusal;
|
|
78
23
|
/** @public */
|
|
79
|
-
export type McpToolError =
|
|
24
|
+
export type McpToolError = ToolRefusal;
|
|
80
25
|
//#endregion
|
|
81
26
|
//#region src/resources/conceptResource.d.ts
|
|
82
27
|
/**
|
|
@@ -144,6 +89,47 @@ export declare const ConceptResources: (projectRoot: string) => Layer.Layer<neve
|
|
|
144
89
|
export declare const IndexResource: (projectRoot: string) => import("effect/Layer").Layer<never, never, import("@effected/xdg").AppDirs | FileSystem.FileSystem | Path.Path | import("@effected/xdg").Xdg>;
|
|
145
90
|
//#endregion
|
|
146
91
|
//#region src/schema/tools.d.ts
|
|
92
|
+
/** One Surface template inside a docs preset, as `describe_vocabulary` reports it. @public */
|
|
93
|
+
export declare const DocsPresetSurface: Schema.Struct<{
|
|
94
|
+
readonly file: Schema.String;
|
|
95
|
+
readonly frontmatter: Schema.Struct<{
|
|
96
|
+
readonly type: Schema.Literal<"Surface">;
|
|
97
|
+
readonly status: Schema.Literal<"draft">;
|
|
98
|
+
readonly title: Schema.String;
|
|
99
|
+
readonly description: Schema.String;
|
|
100
|
+
readonly kind: Schema.Literals<readonly ["site", "repo", "readme"]>;
|
|
101
|
+
readonly audience: Schema.Literals<readonly ["users", "contributors", "agents"]>;
|
|
102
|
+
readonly resource: Schema.String;
|
|
103
|
+
readonly links_to: Schema.optionalKey<Schema.String>;
|
|
104
|
+
readonly url: Schema.optionalKey<Schema.String>;
|
|
105
|
+
}>;
|
|
106
|
+
readonly body: Schema.String;
|
|
107
|
+
}>;
|
|
108
|
+
/** @public */
|
|
109
|
+
export type DocsPresetSurface = typeof DocsPresetSurface.Type;
|
|
110
|
+
/** One docs-surface preset the active profile offers. @public */
|
|
111
|
+
export declare const DocsPreset: Schema.Struct<{
|
|
112
|
+
readonly name: Schema.String;
|
|
113
|
+
readonly description: Schema.String;
|
|
114
|
+
readonly additive: Schema.Boolean;
|
|
115
|
+
readonly surfaces: Schema.$Array<Schema.Struct<{
|
|
116
|
+
readonly file: Schema.String;
|
|
117
|
+
readonly frontmatter: Schema.Struct<{
|
|
118
|
+
readonly type: Schema.Literal<"Surface">;
|
|
119
|
+
readonly status: Schema.Literal<"draft">;
|
|
120
|
+
readonly title: Schema.String;
|
|
121
|
+
readonly description: Schema.String;
|
|
122
|
+
readonly kind: Schema.Literals<readonly ["site", "repo", "readme"]>;
|
|
123
|
+
readonly audience: Schema.Literals<readonly ["users", "contributors", "agents"]>;
|
|
124
|
+
readonly resource: Schema.String;
|
|
125
|
+
readonly links_to: Schema.optionalKey<Schema.String>;
|
|
126
|
+
readonly url: Schema.optionalKey<Schema.String>;
|
|
127
|
+
}>;
|
|
128
|
+
readonly body: Schema.String;
|
|
129
|
+
}>>;
|
|
130
|
+
}>;
|
|
131
|
+
/** @public */
|
|
132
|
+
export type DocsPreset = typeof DocsPreset.Type;
|
|
147
133
|
/** `describe_vocabulary`'s result (§5.2). @public */
|
|
148
134
|
export declare const DescribeVocabularySuccess: Schema.Struct<{
|
|
149
135
|
readonly project_root: Schema.String;
|
|
@@ -172,6 +158,26 @@ export declare const DescribeVocabularySuccess: Schema.Struct<{
|
|
|
172
158
|
readonly name: Schema.String;
|
|
173
159
|
readonly description: Schema.NullOr<Schema.String>;
|
|
174
160
|
}>>;
|
|
161
|
+
readonly docs_presets: Schema.$Array<Schema.Struct<{
|
|
162
|
+
readonly name: Schema.String;
|
|
163
|
+
readonly description: Schema.String;
|
|
164
|
+
readonly additive: Schema.Boolean;
|
|
165
|
+
readonly surfaces: Schema.$Array<Schema.Struct<{
|
|
166
|
+
readonly file: Schema.String;
|
|
167
|
+
readonly frontmatter: Schema.Struct<{
|
|
168
|
+
readonly type: Schema.Literal<"Surface">;
|
|
169
|
+
readonly status: Schema.Literal<"draft">;
|
|
170
|
+
readonly title: Schema.String;
|
|
171
|
+
readonly description: Schema.String;
|
|
172
|
+
readonly kind: Schema.Literals<readonly ["site", "repo", "readme"]>;
|
|
173
|
+
readonly audience: Schema.Literals<readonly ["users", "contributors", "agents"]>;
|
|
174
|
+
readonly resource: Schema.String;
|
|
175
|
+
readonly links_to: Schema.optionalKey<Schema.String>;
|
|
176
|
+
readonly url: Schema.optionalKey<Schema.String>;
|
|
177
|
+
}>;
|
|
178
|
+
readonly body: Schema.String;
|
|
179
|
+
}>>;
|
|
180
|
+
}>>;
|
|
175
181
|
}>;
|
|
176
182
|
/** @public */
|
|
177
183
|
export type DescribeVocabularySuccess = typeof DescribeVocabularySuccess.Type;
|
|
@@ -424,7 +430,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
|
|
|
424
430
|
}>>;
|
|
425
431
|
}>>;
|
|
426
432
|
}>;
|
|
427
|
-
readonly failure: import("
|
|
433
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
428
434
|
readonly failureMode: "error";
|
|
429
435
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
430
436
|
readonly describe_vocabulary: import("effect/ai/Tool").Tool<"describe_vocabulary", {
|
|
@@ -456,8 +462,28 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
|
|
|
456
462
|
readonly name: import("effect/Schema").String;
|
|
457
463
|
readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
|
|
458
464
|
}>>;
|
|
465
|
+
readonly docs_presets: import("effect/Schema").$Array<import("effect/Schema").Struct<{
|
|
466
|
+
readonly name: import("effect/Schema").String;
|
|
467
|
+
readonly description: import("effect/Schema").String;
|
|
468
|
+
readonly additive: import("effect/Schema").Boolean;
|
|
469
|
+
readonly surfaces: import("effect/Schema").$Array<import("effect/Schema").Struct<{
|
|
470
|
+
readonly file: import("effect/Schema").String;
|
|
471
|
+
readonly frontmatter: import("effect/Schema").Struct<{
|
|
472
|
+
readonly type: import("effect/Schema").Literal<"Surface">;
|
|
473
|
+
readonly status: import("effect/Schema").Literal<"draft">;
|
|
474
|
+
readonly title: import("effect/Schema").String;
|
|
475
|
+
readonly description: import("effect/Schema").String;
|
|
476
|
+
readonly kind: import("effect/Schema").Literals<readonly ["site", "repo", "readme"]>;
|
|
477
|
+
readonly audience: import("effect/Schema").Literals<readonly ["users", "contributors", "agents"]>;
|
|
478
|
+
readonly resource: import("effect/Schema").String;
|
|
479
|
+
readonly links_to: import("effect/Schema").optionalKey<import("effect/Schema").String>;
|
|
480
|
+
readonly url: import("effect/Schema").optionalKey<import("effect/Schema").String>;
|
|
481
|
+
}>;
|
|
482
|
+
readonly body: import("effect/Schema").String;
|
|
483
|
+
}>>;
|
|
484
|
+
}>>;
|
|
459
485
|
}>;
|
|
460
|
-
readonly failure: import("
|
|
486
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
461
487
|
readonly failureMode: "error";
|
|
462
488
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
463
489
|
readonly get_concept: import("effect/ai/Tool").Tool<"get_concept", {
|
|
@@ -481,7 +507,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
|
|
|
481
507
|
readonly field: import("effect/Schema").optionalKey<import("effect/Schema").String>;
|
|
482
508
|
}>>;
|
|
483
509
|
}>;
|
|
484
|
-
readonly failure: import("
|
|
510
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
485
511
|
readonly failureMode: "error";
|
|
486
512
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
487
513
|
readonly list_concepts: import("effect/ai/Tool").Tool<"list_concepts", {
|
|
@@ -504,7 +530,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
|
|
|
504
530
|
}>>;
|
|
505
531
|
readonly total: import("effect/Schema").Int;
|
|
506
532
|
}>;
|
|
507
|
-
readonly failure: import("
|
|
533
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
508
534
|
readonly failureMode: "error";
|
|
509
535
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
510
536
|
readonly stale_report: import("effect/ai/Tool").Tool<"stale_report", {
|
|
@@ -527,7 +553,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
|
|
|
527
553
|
readonly days_past: import("effect/Schema").Int;
|
|
528
554
|
}>>;
|
|
529
555
|
}>;
|
|
530
|
-
readonly failure: import("
|
|
556
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
531
557
|
readonly failureMode: "error";
|
|
532
558
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
533
559
|
readonly validate_bundle: import("effect/ai/Tool").Tool<"validate_bundle", {
|
|
@@ -568,7 +594,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
|
|
|
568
594
|
readonly range: import("effect/Schema").optionalKey<typeof import("@okfit/core").DiagnosticRange>;
|
|
569
595
|
}>>;
|
|
570
596
|
}>;
|
|
571
|
-
readonly failure: import("
|
|
597
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
572
598
|
readonly failureMode: "error";
|
|
573
599
|
}, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("@effected/git").Git | import("@okfit/profiles").GitHistory | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
574
600
|
}>;
|
|
@@ -614,7 +640,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
|
|
|
614
640
|
}>>;
|
|
615
641
|
}>>;
|
|
616
642
|
}>;
|
|
617
|
-
readonly failure: import("
|
|
643
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
618
644
|
readonly failureMode: "error";
|
|
619
645
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
620
646
|
readonly describe_vocabulary: import("effect/ai/Tool").Tool<"describe_vocabulary", {
|
|
@@ -646,8 +672,28 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
|
|
|
646
672
|
readonly name: import("effect/Schema").String;
|
|
647
673
|
readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
|
|
648
674
|
}>>;
|
|
675
|
+
readonly docs_presets: import("effect/Schema").$Array<import("effect/Schema").Struct<{
|
|
676
|
+
readonly name: import("effect/Schema").String;
|
|
677
|
+
readonly description: import("effect/Schema").String;
|
|
678
|
+
readonly additive: import("effect/Schema").Boolean;
|
|
679
|
+
readonly surfaces: import("effect/Schema").$Array<import("effect/Schema").Struct<{
|
|
680
|
+
readonly file: import("effect/Schema").String;
|
|
681
|
+
readonly frontmatter: import("effect/Schema").Struct<{
|
|
682
|
+
readonly type: import("effect/Schema").Literal<"Surface">;
|
|
683
|
+
readonly status: import("effect/Schema").Literal<"draft">;
|
|
684
|
+
readonly title: import("effect/Schema").String;
|
|
685
|
+
readonly description: import("effect/Schema").String;
|
|
686
|
+
readonly kind: import("effect/Schema").Literals<readonly ["site", "repo", "readme"]>;
|
|
687
|
+
readonly audience: import("effect/Schema").Literals<readonly ["users", "contributors", "agents"]>;
|
|
688
|
+
readonly resource: import("effect/Schema").String;
|
|
689
|
+
readonly links_to: import("effect/Schema").optionalKey<import("effect/Schema").String>;
|
|
690
|
+
readonly url: import("effect/Schema").optionalKey<import("effect/Schema").String>;
|
|
691
|
+
}>;
|
|
692
|
+
readonly body: import("effect/Schema").String;
|
|
693
|
+
}>>;
|
|
694
|
+
}>>;
|
|
649
695
|
}>;
|
|
650
|
-
readonly failure: import("
|
|
696
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
651
697
|
readonly failureMode: "error";
|
|
652
698
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
653
699
|
readonly get_concept: import("effect/ai/Tool").Tool<"get_concept", {
|
|
@@ -671,7 +717,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
|
|
|
671
717
|
readonly field: import("effect/Schema").optionalKey<import("effect/Schema").String>;
|
|
672
718
|
}>>;
|
|
673
719
|
}>;
|
|
674
|
-
readonly failure: import("
|
|
720
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
675
721
|
readonly failureMode: "error";
|
|
676
722
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
677
723
|
readonly list_concepts: import("effect/ai/Tool").Tool<"list_concepts", {
|
|
@@ -694,7 +740,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
|
|
|
694
740
|
}>>;
|
|
695
741
|
readonly total: import("effect/Schema").Int;
|
|
696
742
|
}>;
|
|
697
|
-
readonly failure: import("
|
|
743
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
698
744
|
readonly failureMode: "error";
|
|
699
745
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
700
746
|
readonly stale_report: import("effect/ai/Tool").Tool<"stale_report", {
|
|
@@ -717,7 +763,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
|
|
|
717
763
|
readonly days_past: import("effect/Schema").Int;
|
|
718
764
|
}>>;
|
|
719
765
|
}>;
|
|
720
|
-
readonly failure: import("
|
|
766
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
721
767
|
readonly failureMode: "error";
|
|
722
768
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
723
769
|
readonly validate_bundle: import("effect/ai/Tool").Tool<"validate_bundle", {
|
|
@@ -758,7 +804,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
|
|
|
758
804
|
readonly range: import("effect/Schema").optionalKey<typeof import("@okfit/core").DiagnosticRange>;
|
|
759
805
|
}>>;
|
|
760
806
|
}>;
|
|
761
|
-
readonly failure: import("
|
|
807
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
762
808
|
readonly failureMode: "error";
|
|
763
809
|
}, import("@effected/xdg").AppDirs | import("effect/Crypto").Crypto | import("effect/FileSystem").FileSystem | import("@effected/git").Git | import("@okfit/profiles").GitHistory | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
764
810
|
}>, never, never>;
|
package/index.js
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { McpToolError, Remediation } from "./errors.js";
|
|
2
2
|
import { ConceptResources } from "./resources/conceptResource.js";
|
|
3
3
|
import { IndexResource } from "./resources/indexResource.js";
|
|
4
4
|
import { ConceptSummary, toConceptSummary } from "./schema/ConceptSummary.js";
|
|
5
|
-
import { ConceptNeighborsSuccess, DescribeVocabularySuccess, GetConceptSuccess, ListConceptsParams, ListConceptsSuccess, Neighbor, StaleReportParams, StaleReportSuccess, ValidateBundleParams } from "./schema/tools.js";
|
|
5
|
+
import { ConceptNeighborsSuccess, DescribeVocabularySuccess, DocsPreset, DocsPresetSurface, GetConceptSuccess, ListConceptsParams, ListConceptsSuccess, Neighbor, StaleReportParams, StaleReportSuccess, ValidateBundleParams } from "./schema/tools.js";
|
|
6
6
|
import { MCP_VERSION } from "./version.js";
|
|
7
7
|
import { OkfitToolkit, ToolsLayer } from "./toolkit.js";
|
|
8
8
|
import { SERVER_INSTRUCTIONS, ServerLayer } from "./server.js";
|
|
9
9
|
|
|
10
|
-
export {
|
|
10
|
+
export { ConceptNeighborsSuccess, ConceptResources, ConceptSummary, DescribeVocabularySuccess, DocsPreset, DocsPresetSurface, GetConceptSuccess, IndexResource, ListConceptsParams, ListConceptsSuccess, MCP_VERSION, McpToolError, Neighbor, OkfitToolkit, Remediation, SERVER_INSTRUCTIONS, ServerLayer, StaleReportParams, StaleReportSuccess, ToolsLayer, ValidateBundleParams, toConceptSummary };
|
|
@@ -1,37 +1,23 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { ToolFailure } from "@effected/mcp";
|
|
1
|
+
import { ToolFailure, ToolRefusal } from "@effected/mcp";
|
|
3
2
|
import { Effect } from "effect";
|
|
4
3
|
|
|
5
4
|
//#region src/internal/conceptNotFound.ts
|
|
6
5
|
/**
|
|
7
6
|
* Maps the engine's `QueryConceptNotFoundError` to the tool-facing failure
|
|
8
|
-
* `get_concept` and `concept_neighbors` share: `
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
* `failureMode: "error"` reaches the wire as `error.message` alone.
|
|
7
|
+
* `get_concept` and `concept_neighbors` share: a `ToolRefusal` saying the id
|
|
8
|
+
* is empty, or that no concept has it. `ToolRefusal.refuse` folds the
|
|
9
|
+
* remediation into the message, which is all a declared failure sends.
|
|
12
10
|
*
|
|
13
11
|
* @internal
|
|
14
12
|
*/
|
|
15
13
|
const toConceptLookupFailure = (id, error) => {
|
|
16
|
-
if (error.reason === "empty-id") {
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
return Effect.fail(new InvalidArgument({
|
|
22
|
-
argument: "id",
|
|
23
|
-
message: ToolFailure.message("id must not be empty", remediation),
|
|
24
|
-
remediation
|
|
25
|
-
}));
|
|
26
|
-
}
|
|
27
|
-
const remediation = {
|
|
14
|
+
if (error.reason === "empty-id") return Effect.fail(ToolRefusal.refuse("id must not be empty", {
|
|
15
|
+
hint: "Pass a bundle-relative concept id such as decisions/cli-exit-codes.",
|
|
16
|
+
suggestedTool: "list_concepts"
|
|
17
|
+
}));
|
|
18
|
+
return Effect.fail(ToolRefusal.refuse(`no concept "${ToolFailure.truncate(id)}" in this bundle`, {
|
|
28
19
|
hint: "Call list_concepts to see the ids this bundle contains.",
|
|
29
20
|
suggestedTool: "list_concepts"
|
|
30
|
-
};
|
|
31
|
-
return Effect.fail(new ConceptNotFound({
|
|
32
|
-
id,
|
|
33
|
-
message: ToolFailure.message(`no concept "${ToolFailure.truncate(id)}" in this bundle`, remediation),
|
|
34
|
-
remediation
|
|
35
21
|
}));
|
|
36
22
|
};
|
|
37
23
|
|
package/internal/resolveNow.js
CHANGED
|
@@ -1,13 +1,12 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { ToolFailure } from "@effected/mcp";
|
|
3
|
-
import { DateTime, Effect, Schema } from "effect";
|
|
1
|
+
import { ToolRefusal } from "@effected/mcp";
|
|
4
2
|
import { Timestamp } from "@okfit/core";
|
|
3
|
+
import { DateTime, Effect, Schema } from "effect";
|
|
5
4
|
|
|
6
5
|
//#region src/internal/resolveNow.ts
|
|
7
6
|
/**
|
|
8
7
|
* An optional ISO-8601 `now` argument, else the Effect clock. Decoding
|
|
9
8
|
* happens here rather than in the parameter schema so a malformed value
|
|
10
|
-
* becomes this contract's `
|
|
9
|
+
* becomes this contract's `ToolRefusal` — with a remediation hint —
|
|
11
10
|
* instead of Effect's generic protocol-level `InvalidParams` (J-5).
|
|
12
11
|
* `OKFIT_NOW` is deliberately NOT read: it is the CLI's own test hook
|
|
13
12
|
* (F-17), never the server's.
|
|
@@ -15,12 +14,7 @@ import { Timestamp } from "@okfit/core";
|
|
|
15
14
|
* @internal
|
|
16
15
|
*/
|
|
17
16
|
const resolveNow = (input) => input === void 0 ? DateTime.now : Schema.decodeUnknownEffect(Timestamp)(input).pipe(Effect.mapError((issue) => {
|
|
18
|
-
|
|
19
|
-
return new InvalidArgument({
|
|
20
|
-
argument: "now",
|
|
21
|
-
message: ToolFailure.message(String(issue), remediation),
|
|
22
|
-
remediation
|
|
23
|
-
});
|
|
17
|
+
return ToolRefusal.refuse(String(issue), { hint: "now must be an ISO-8601 instant with an explicit offset, for example 2026-09-06T00:00:00Z." });
|
|
24
18
|
}));
|
|
25
19
|
|
|
26
20
|
//#endregion
|
package/internal/toolContext.js
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { ToolFailure } from "@effected/mcp";
|
|
3
|
-
import { Effect, Option } from "effect";
|
|
1
|
+
import { ToolRefusal } from "@effected/mcp";
|
|
4
2
|
import { Bundle } from "@okfit/core";
|
|
3
|
+
import { Effect, Option } from "effect";
|
|
5
4
|
import { provideConfig, resolveProjectConfig } from "@okfit/engine";
|
|
6
5
|
|
|
7
6
|
//#region src/internal/toolContext.ts
|
|
@@ -19,7 +18,7 @@ const messageOf = (error) => {
|
|
|
19
18
|
};
|
|
20
19
|
const CONFIG_HINT = "Check the project's .okfit.toml, okfit.toml, or .config/okfit.toml for a syntax or schema error; remove it to fall back to defaults.";
|
|
21
20
|
/**
|
|
22
|
-
* Config resolution alone, with every failure collapsed to `
|
|
21
|
+
* Config resolution alone, with every failure collapsed to a `ToolRefusal`.
|
|
23
22
|
* `describe_vocabulary` and `validate_bundle` use this; every other tool
|
|
24
23
|
* goes through {@link loadToolContext}.
|
|
25
24
|
*
|
|
@@ -43,10 +42,7 @@ const resolveConfigOnly = (projectRoot) => resolveProjectConfig({
|
|
|
43
42
|
hint: CONFIG_HINT,
|
|
44
43
|
suggestedTool: "describe_vocabulary"
|
|
45
44
|
};
|
|
46
|
-
return
|
|
47
|
-
message: ToolFailure.message(messageOf(cause), remediation),
|
|
48
|
-
remediation
|
|
49
|
-
});
|
|
45
|
+
return ToolRefusal.refuse(messageOf(cause), remediation);
|
|
50
46
|
}));
|
|
51
47
|
/**
|
|
52
48
|
* Resolve config and load the bundle, fresh, for one tool call (N-9). No
|
|
@@ -59,11 +55,7 @@ const loadToolContext = (projectRoot) => Effect.gen(function* () {
|
|
|
59
55
|
const resolved = yield* resolveConfigOnly(projectRoot);
|
|
60
56
|
const bundle = yield* Bundle.load({ root: resolved.bundleRoot }).pipe(Effect.mapError((cause) => {
|
|
61
57
|
const remediation = { hint: `The bundle root "${resolved.bundleRoot}" does not exist or could not be read; check the config's [bundle].path, or run \`okfit init\`.` };
|
|
62
|
-
return
|
|
63
|
-
root: resolved.bundleRoot,
|
|
64
|
-
message: ToolFailure.message(cause.message, remediation),
|
|
65
|
-
remediation
|
|
66
|
-
});
|
|
58
|
+
return ToolRefusal.refuse(cause.message, remediation);
|
|
67
59
|
}));
|
|
68
60
|
return {
|
|
69
61
|
projectRoot,
|
package/main.d.ts
CHANGED
|
@@ -14,25 +14,19 @@ export interface MainOptions {
|
|
|
14
14
|
/**
|
|
15
15
|
* Run the okfit MCP server over stdio. Owns the process.
|
|
16
16
|
*
|
|
17
|
-
*
|
|
18
|
-
* the
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
* no runtime import at all. `@effected/mcp`'s `McpStdio.launch`/`teardown`
|
|
24
|
-
* sits AROUND this requirement, not in place of it (design-patterns'
|
|
25
|
-
* `carrier-entry-contract.md`).
|
|
17
|
+
* `McpGuard.run` (`@effected/mcp/guard`, itself free of static runtime
|
|
18
|
+
* imports) installs the crash guards before `load` evaluates the server
|
|
19
|
+
* graph, so a throw during module evaluation is still reported on stderr.
|
|
20
|
+
* This module therefore carries no other static runtime import (`Distribution`
|
|
21
|
+
* is type-only). The guard launches the server with `McpStdio.launch` and
|
|
22
|
+
* `McpStdio.teardown` (stdin EOF exits `0`, not `130`).
|
|
26
23
|
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
* server (`server.ts`) is built on `McpStdio.layer`, which already merges
|
|
34
|
-
* `LogToStderr` into everything it provides, so this module no longer
|
|
35
|
-
* assembles a logger itself either.
|
|
24
|
+
* Policy is `exitBeforeConnect` for both events. Every tool is read-only and
|
|
25
|
+
* reloads the bundle per call, so a stray error while serving has no state to
|
|
26
|
+
* corrupt, and dying mid-session would only deregister the tools from the
|
|
27
|
+
* client: the guard logs and keeps serving. Before serving the same error means
|
|
28
|
+
* a broken boot, so it exits `1`. A `load()` that rejects is `startup failed`,
|
|
29
|
+
* exit `1`, whatever the policy.
|
|
36
30
|
*
|
|
37
31
|
* @public
|
|
38
32
|
*/
|
package/main.js
CHANGED
|
@@ -1,54 +1,50 @@
|
|
|
1
|
+
import { McpGuard } from "@effected/mcp/guard";
|
|
2
|
+
|
|
1
3
|
//#region src/main.ts
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
} catch {
|
|
8
|
-
return FATAL_FALLBACK;
|
|
9
|
-
}
|
|
10
|
-
};
|
|
11
|
-
const fatal = (label, error) => {
|
|
12
|
-
process.stderr.write(`okfit-mcp: ${label}: ${describe(error)}\n`);
|
|
13
|
-
process.exit(1);
|
|
14
|
-
};
|
|
4
|
+
/**
|
|
5
|
+
* The assembled okfit MCP server program.
|
|
6
|
+
*
|
|
7
|
+
* @packageDocumentation
|
|
8
|
+
*/
|
|
15
9
|
/**
|
|
16
10
|
* Run the okfit MCP server over stdio. Owns the process.
|
|
17
11
|
*
|
|
18
|
-
*
|
|
19
|
-
* the
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
* no runtime import at all. `@effected/mcp`'s `McpStdio.launch`/`teardown`
|
|
25
|
-
* sits AROUND this requirement, not in place of it (design-patterns'
|
|
26
|
-
* `carrier-entry-contract.md`).
|
|
12
|
+
* `McpGuard.run` (`@effected/mcp/guard`, itself free of static runtime
|
|
13
|
+
* imports) installs the crash guards before `load` evaluates the server
|
|
14
|
+
* graph, so a throw during module evaluation is still reported on stderr.
|
|
15
|
+
* This module therefore carries no other static runtime import (`Distribution`
|
|
16
|
+
* is type-only). The guard launches the server with `McpStdio.launch` and
|
|
17
|
+
* `McpStdio.teardown` (stdin EOF exits `0`, not `130`).
|
|
27
18
|
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
* server (`server.ts`) is built on `McpStdio.layer`, which already merges
|
|
35
|
-
* `LogToStderr` into everything it provides, so this module no longer
|
|
36
|
-
* assembles a logger itself either.
|
|
19
|
+
* Policy is `exitBeforeConnect` for both events. Every tool is read-only and
|
|
20
|
+
* reloads the bundle per call, so a stray error while serving has no state to
|
|
21
|
+
* corrupt, and dying mid-session would only deregister the tools from the
|
|
22
|
+
* client: the guard logs and keeps serving. Before serving the same error means
|
|
23
|
+
* a broken boot, so it exits `1`. A `load()` that rejects is `startup failed`,
|
|
24
|
+
* exit `1`, whatever the policy.
|
|
37
25
|
*
|
|
38
26
|
* @public
|
|
39
27
|
*/
|
|
40
|
-
const main =
|
|
41
|
-
|
|
42
|
-
process
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
};
|
|
28
|
+
const main = (options = {}) => McpGuard.run({
|
|
29
|
+
label: "okfit-mcp",
|
|
30
|
+
host: process,
|
|
31
|
+
policy: {
|
|
32
|
+
onUncaught: "exitBeforeConnect",
|
|
33
|
+
onRejection: "exitBeforeConnect"
|
|
34
|
+
},
|
|
35
|
+
injectCrash: McpGuard.parseInjectCrash(process.env.OKFIT_MCP_TEST_INJECT_CRASH),
|
|
36
|
+
load: async () => {
|
|
37
|
+
const NodeRuntime = await import("@effect/platform-node/NodeRuntime");
|
|
38
|
+
const { OkfitPlatform } = await import("@okfit/engine");
|
|
39
|
+
const { Layer } = await import("effect");
|
|
40
|
+
const { resolveMcpProjectRoot } = await import("./internal/projectRoot.js");
|
|
41
|
+
const { ServerLayer } = await import("./server.js");
|
|
42
|
+
return {
|
|
43
|
+
layer: ServerLayer(resolveMcpProjectRoot(process.env, process.cwd()), options).pipe(Layer.provide(OkfitPlatform)),
|
|
44
|
+
runMain: NodeRuntime.runMain
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
});
|
|
52
48
|
|
|
53
49
|
//#endregion
|
|
54
50
|
export { main };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@okfit/mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Model Context Protocol server for okfit: query and understand Open Knowledge Format (OKF) bundles from an agent.",
|
|
6
6
|
"keywords": [
|
|
@@ -44,23 +44,23 @@
|
|
|
44
44
|
"okfit-mcp": "bin/okfit-mcp.js"
|
|
45
45
|
},
|
|
46
46
|
"dependencies": {
|
|
47
|
-
"@effect/platform-node": "^4.0.
|
|
48
|
-
"@effected/config-file": "^0.14.
|
|
49
|
-
"@effected/engine": "^0.
|
|
47
|
+
"@effect/platform-node": "^4.0.1",
|
|
48
|
+
"@effected/config-file": "^0.14.2",
|
|
49
|
+
"@effected/engine": "^0.4.0",
|
|
50
50
|
"@effected/git": "^0.20.0",
|
|
51
51
|
"@effected/glob": "^0.10.0",
|
|
52
|
-
"@effected/jsonc": "^0.15.
|
|
53
|
-
"@effected/markdown": "^0.15.
|
|
54
|
-
"@effected/mcp": "^0.
|
|
55
|
-
"@effected/schemastore": "^0.
|
|
56
|
-
"@effected/toml": "^0.11.
|
|
52
|
+
"@effected/jsonc": "^0.15.1",
|
|
53
|
+
"@effected/markdown": "^0.15.1",
|
|
54
|
+
"@effected/mcp": "^0.5.0",
|
|
55
|
+
"@effected/schemastore": "^0.21.1",
|
|
56
|
+
"@effected/toml": "^0.11.1",
|
|
57
57
|
"@effected/walker": "^0.15.0",
|
|
58
58
|
"@effected/xdg": "^0.9.0",
|
|
59
|
-
"@effected/yaml": "^0.19.
|
|
60
|
-
"@okfit/core": "0.
|
|
61
|
-
"@okfit/engine": "0.
|
|
62
|
-
"@okfit/profiles": "0.
|
|
63
|
-
"effect": "^4.0.
|
|
59
|
+
"@effected/yaml": "^0.19.1",
|
|
60
|
+
"@okfit/core": "0.9.1",
|
|
61
|
+
"@okfit/engine": "0.13.0",
|
|
62
|
+
"@okfit/profiles": "0.9.0",
|
|
63
|
+
"effect": "^4.0.1"
|
|
64
64
|
},
|
|
65
65
|
"engines": {
|
|
66
66
|
"node": ">=24.11.0"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { loadToolContext } from "../internal/toolContext.js";
|
|
2
|
-
import { Effect, FileSystem, Layer, Path } from "effect";
|
|
3
2
|
import { Derive } from "@okfit/core";
|
|
3
|
+
import { Effect, FileSystem, Layer, Path } from "effect";
|
|
4
4
|
import { McpSchema, McpServer } from "effect/ai";
|
|
5
5
|
|
|
6
6
|
//#region src/resources/conceptResource.ts
|
package/schema/tools.js
CHANGED
|
@@ -1,9 +1,40 @@
|
|
|
1
1
|
import { ConceptSummary } from "./ConceptSummary.js";
|
|
2
|
-
import { Schema } from "effect";
|
|
3
2
|
import { GraphNodeKind, Status } from "@okfit/core";
|
|
3
|
+
import { Schema } from "effect";
|
|
4
4
|
import { ContextTag, ContextType } from "@okfit/engine";
|
|
5
5
|
|
|
6
6
|
//#region src/schema/tools.ts
|
|
7
|
+
/** One Surface template inside a docs preset, as `describe_vocabulary` reports it. @public */
|
|
8
|
+
const DocsPresetSurface = Schema.Struct({
|
|
9
|
+
file: Schema.String,
|
|
10
|
+
frontmatter: Schema.Struct({
|
|
11
|
+
type: Schema.Literal("Surface"),
|
|
12
|
+
status: Schema.Literal("draft"),
|
|
13
|
+
title: Schema.String,
|
|
14
|
+
description: Schema.String,
|
|
15
|
+
kind: Schema.Literals([
|
|
16
|
+
"site",
|
|
17
|
+
"repo",
|
|
18
|
+
"readme"
|
|
19
|
+
]),
|
|
20
|
+
audience: Schema.Literals([
|
|
21
|
+
"users",
|
|
22
|
+
"contributors",
|
|
23
|
+
"agents"
|
|
24
|
+
]),
|
|
25
|
+
resource: Schema.String,
|
|
26
|
+
links_to: Schema.optionalKey(Schema.String),
|
|
27
|
+
url: Schema.optionalKey(Schema.String)
|
|
28
|
+
}),
|
|
29
|
+
body: Schema.String
|
|
30
|
+
});
|
|
31
|
+
/** One docs-surface preset the active profile offers. @public */
|
|
32
|
+
const DocsPreset = Schema.Struct({
|
|
33
|
+
name: Schema.String,
|
|
34
|
+
description: Schema.String,
|
|
35
|
+
additive: Schema.Boolean,
|
|
36
|
+
surfaces: Schema.Array(DocsPresetSurface)
|
|
37
|
+
});
|
|
7
38
|
/** `describe_vocabulary`'s result (§5.2). @public */
|
|
8
39
|
const DescribeVocabularySuccess = Schema.Struct({
|
|
9
40
|
project_root: Schema.String,
|
|
@@ -13,7 +44,8 @@ const DescribeVocabularySuccess = Schema.Struct({
|
|
|
13
44
|
profile_requested: Schema.NullOr(Schema.String),
|
|
14
45
|
agent: Schema.NullOr(Schema.String),
|
|
15
46
|
types: Schema.Array(ContextType),
|
|
16
|
-
tags: Schema.Array(ContextTag)
|
|
47
|
+
tags: Schema.Array(ContextTag),
|
|
48
|
+
docs_presets: Schema.Array(DocsPreset)
|
|
17
49
|
});
|
|
18
50
|
/** `list_concepts`' arguments (§5.3). @public */
|
|
19
51
|
const ListConceptsParams = Schema.Struct({
|
|
@@ -83,4 +115,4 @@ const ValidateBundleParams = Schema.Struct({
|
|
|
83
115
|
});
|
|
84
116
|
|
|
85
117
|
//#endregion
|
|
86
|
-
export { ConceptNeighborsSuccess, DescribeVocabularySuccess, GetConceptSuccess, ListConceptsParams, ListConceptsSuccess, Neighbor, StaleReportParams, StaleReportSuccess, ValidateBundleDocument, ValidateBundleParams };
|
|
118
|
+
export { ConceptNeighborsSuccess, DescribeVocabularySuccess, DocsPreset, DocsPresetSurface, GetConceptSuccess, ListConceptsParams, ListConceptsSuccess, Neighbor, StaleReportParams, StaleReportSuccess, ValidateBundleDocument, ValidateBundleParams };
|
|
@@ -7,7 +7,7 @@ import { contextEnvelope } from "@okfit/engine";
|
|
|
7
7
|
import { AppDirs, Xdg } from "@effected/xdg";
|
|
8
8
|
|
|
9
9
|
//#region src/tools/describeVocabulary.ts
|
|
10
|
-
const DESCRIPTION = "Returns this project's resolved okfit configuration:
|
|
10
|
+
const DESCRIPTION = "Returns this project's resolved okfit configuration: project root, bundle root, active profile, agent actor, every concept type and tag the config declares, and docs_presets, the active profile's Surface templates (empty without a profile). Call this first, before filtering or writing any concept, to learn which names exist.";
|
|
11
11
|
/**
|
|
12
12
|
* `dependencies` names the platform services `handleDescribeVocabulary`
|
|
13
13
|
* needs (`resolveConfigOnly` -> `resolveProjectConfig`/`provideConfig`);
|
|
@@ -57,6 +57,10 @@ const handleDescribeVocabulary = (projectRoot) => Effect.gen(function* () {
|
|
|
57
57
|
indexExists: false,
|
|
58
58
|
config: resolved.config
|
|
59
59
|
});
|
|
60
|
+
const docsPresets = Option.match(resolved.profile, {
|
|
61
|
+
onNone: () => [],
|
|
62
|
+
onSome: (p) => p.docsPresets
|
|
63
|
+
});
|
|
60
64
|
return {
|
|
61
65
|
project_root: envelope.project_root,
|
|
62
66
|
bundle_root: envelope.bundle_root,
|
|
@@ -65,7 +69,17 @@ const handleDescribeVocabulary = (projectRoot) => Effect.gen(function* () {
|
|
|
65
69
|
profile_requested: envelope.profile_requested,
|
|
66
70
|
agent: envelope.actors.agent,
|
|
67
71
|
types: envelope.types,
|
|
68
|
-
tags: envelope.tags
|
|
72
|
+
tags: envelope.tags,
|
|
73
|
+
docs_presets: docsPresets.map((preset) => ({
|
|
74
|
+
name: preset.name,
|
|
75
|
+
description: preset.description,
|
|
76
|
+
additive: preset.additive,
|
|
77
|
+
surfaces: preset.surfaces.map((s) => ({
|
|
78
|
+
file: s.file,
|
|
79
|
+
frontmatter: s.frontmatter,
|
|
80
|
+
body: s.body
|
|
81
|
+
}))
|
|
82
|
+
}))
|
|
69
83
|
};
|
|
70
84
|
});
|
|
71
85
|
|
package/tools/getConcept.js
CHANGED
|
@@ -2,8 +2,8 @@ import { McpToolError } from "../errors.js";
|
|
|
2
2
|
import { loadToolContext } from "../internal/toolContext.js";
|
|
3
3
|
import { GetConceptSuccess } from "../schema/tools.js";
|
|
4
4
|
import { toConceptLookupFailure } from "../internal/conceptNotFound.js";
|
|
5
|
-
import { Effect, FileSystem, Path, Schema } from "effect";
|
|
6
5
|
import { Derive } from "@okfit/core";
|
|
6
|
+
import { Effect, FileSystem, Path, Schema } from "effect";
|
|
7
7
|
import { Tool } from "effect/ai";
|
|
8
8
|
import { ConceptQuery } from "@okfit/engine";
|
|
9
9
|
import { AppDirs, Xdg } from "@effected/xdg";
|
package/tools/listConcepts.js
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
import { McpToolError
|
|
1
|
+
import { McpToolError } from "../errors.js";
|
|
2
2
|
import { loadToolContext } from "../internal/toolContext.js";
|
|
3
3
|
import { toConceptSummary } from "../schema/ConceptSummary.js";
|
|
4
4
|
import { ListConceptsParams, ListConceptsSuccess } from "../schema/tools.js";
|
|
5
|
-
import { ToolFailure } from "@effected/mcp";
|
|
5
|
+
import { ToolFailure, ToolRefusal } from "@effected/mcp";
|
|
6
6
|
import { Effect, FileSystem, Path } from "effect";
|
|
7
7
|
import { Tool } from "effect/ai";
|
|
8
8
|
import { ConceptQuery } from "@okfit/engine";
|
|
@@ -47,13 +47,7 @@ const unknown = (kind, requested, valid) => {
|
|
|
47
47
|
suggestedTool: "describe_vocabulary"
|
|
48
48
|
};
|
|
49
49
|
const rawMessage = `"${ToolFailure.truncate(requested)}" is not a ${kind} declared by this project's okfit config. Valid ${kind}s: ${valid.join(", ")}.`;
|
|
50
|
-
return
|
|
51
|
-
kind,
|
|
52
|
-
requested,
|
|
53
|
-
valid,
|
|
54
|
-
message: ToolFailure.message(rawMessage, remediation),
|
|
55
|
-
remediation
|
|
56
|
-
});
|
|
50
|
+
return ToolRefusal.refuse(rawMessage, remediation);
|
|
57
51
|
};
|
|
58
52
|
/** @public */
|
|
59
53
|
const handleListConcepts = (projectRoot, params) => Effect.gen(function* () {
|
package/tools/staleReport.js
CHANGED
|
@@ -3,8 +3,8 @@ import { loadToolContext } from "../internal/toolContext.js";
|
|
|
3
3
|
import { toConceptSummary } from "../schema/ConceptSummary.js";
|
|
4
4
|
import { StaleReportParams, StaleReportSuccess } from "../schema/tools.js";
|
|
5
5
|
import { resolveNow } from "../internal/resolveNow.js";
|
|
6
|
-
import { DateTime, Effect, FileSystem, Path } from "effect";
|
|
7
6
|
import { Derive } from "@okfit/core";
|
|
7
|
+
import { DateTime, Effect, FileSystem, Path } from "effect";
|
|
8
8
|
import { Tool } from "effect/ai";
|
|
9
9
|
import { AppDirs, Xdg } from "@effected/xdg";
|
|
10
10
|
|
package/tools/validateBundle.js
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { McpToolError } from "../errors.js";
|
|
2
2
|
import { resolveConfigOnly } from "../internal/toolContext.js";
|
|
3
3
|
import { ValidateBundleParams } from "../schema/tools.js";
|
|
4
4
|
import { resolveNow } from "../internal/resolveNow.js";
|
|
5
5
|
import { MCP_VERSION } from "../version.js";
|
|
6
|
-
import {
|
|
7
|
-
import { Crypto, Effect, FileSystem, Option, Path } from "effect";
|
|
6
|
+
import { ToolRefusal } from "@effected/mcp";
|
|
8
7
|
import { OKF_SPEC_VERSION } from "@okfit/core";
|
|
8
|
+
import { Crypto, Effect, FileSystem, Option, Path } from "effect";
|
|
9
9
|
import { Tool } from "effect/ai";
|
|
10
10
|
import { DocumentPathError, JsonEnvelope, collect, forDiagnostics, json, provideDocuments, run } from "@okfit/engine";
|
|
11
11
|
import { Git } from "@effected/git";
|
|
@@ -77,20 +77,9 @@ const handleValidateBundle = (projectRoot, params, distribution) => Effect.gen(f
|
|
|
77
77
|
profile: resolved.profile,
|
|
78
78
|
now
|
|
79
79
|
}).pipe(provideDocuments(resolved.bundleRoot, params.documents ?? []), Effect.mapError((cause) => {
|
|
80
|
-
if (cause instanceof DocumentPathError) {
|
|
81
|
-
const remediation = { hint: "Give each document path relative to the bundle root, in posix form, naming a .md file once (for example metrics/churn.md)." };
|
|
82
|
-
return new InvalidArgument({
|
|
83
|
-
argument: "documents",
|
|
84
|
-
message: ToolFailure.message(cause.message, remediation),
|
|
85
|
-
remediation
|
|
86
|
-
});
|
|
87
|
-
}
|
|
80
|
+
if (cause instanceof DocumentPathError) return ToolRefusal.refuse(cause.message, { hint: "Give each document path relative to the bundle root, in posix form, naming a .md file once (for example metrics/churn.md)." });
|
|
88
81
|
const remediation = { hint: `The bundle root "${resolved.bundleRoot}" does not exist or could not be read; check the config's [bundle].path, or run \`okfit init\`.` };
|
|
89
|
-
return
|
|
90
|
-
root: resolved.bundleRoot,
|
|
91
|
-
message: ToolFailure.message(cause.message, remediation),
|
|
92
|
-
remediation
|
|
93
|
-
});
|
|
82
|
+
return ToolRefusal.refuse(cause.message, remediation);
|
|
94
83
|
}));
|
|
95
84
|
const diagnostics = collect(result.report.conformance, result.report.lint, result.profileDiagnostics);
|
|
96
85
|
const code = forDiagnostics(diagnostics);
|