@okfit/mcp 0.7.0 → 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 +26 -81
- package/index.js +2 -2
- 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 +13 -13
- package/resources/conceptResource.js +1 -1
- package/schema/tools.js +1 -1
- 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
|
-
/**
|
|
30
|
-
* The configured bundle root does not exist or could not be read. @public
|
|
31
|
-
*/
|
|
32
|
-
export declare class BundleNotFound extends BundleNotFound_base {}
|
|
33
|
-
declare const ConceptNotFound_base: Schema.Class<ConceptNotFound, Schema.TaggedStruct<"ConceptNotFound", {
|
|
34
|
-
readonly message: Schema.String;
|
|
35
|
-
readonly remediation: Schema.Struct<{
|
|
36
|
-
readonly hint: Schema.String;
|
|
37
|
-
readonly suggestedTool: Schema.optionalKey<Schema.String>;
|
|
38
|
-
readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
|
|
39
|
-
}>;
|
|
40
|
-
readonly id: Schema.String;
|
|
41
|
-
}>, import("effect/Cause").YieldableError>;
|
|
42
9
|
/**
|
|
43
|
-
*
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
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
|
/**
|
|
@@ -485,7 +430,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
|
|
|
485
430
|
}>>;
|
|
486
431
|
}>>;
|
|
487
432
|
}>;
|
|
488
|
-
readonly failure: import("
|
|
433
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
489
434
|
readonly failureMode: "error";
|
|
490
435
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
491
436
|
readonly describe_vocabulary: import("effect/ai/Tool").Tool<"describe_vocabulary", {
|
|
@@ -538,7 +483,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
|
|
|
538
483
|
}>>;
|
|
539
484
|
}>>;
|
|
540
485
|
}>;
|
|
541
|
-
readonly failure: import("
|
|
486
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
542
487
|
readonly failureMode: "error";
|
|
543
488
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
544
489
|
readonly get_concept: import("effect/ai/Tool").Tool<"get_concept", {
|
|
@@ -562,7 +507,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
|
|
|
562
507
|
readonly field: import("effect/Schema").optionalKey<import("effect/Schema").String>;
|
|
563
508
|
}>>;
|
|
564
509
|
}>;
|
|
565
|
-
readonly failure: import("
|
|
510
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
566
511
|
readonly failureMode: "error";
|
|
567
512
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
568
513
|
readonly list_concepts: import("effect/ai/Tool").Tool<"list_concepts", {
|
|
@@ -585,7 +530,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
|
|
|
585
530
|
}>>;
|
|
586
531
|
readonly total: import("effect/Schema").Int;
|
|
587
532
|
}>;
|
|
588
|
-
readonly failure: import("
|
|
533
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
589
534
|
readonly failureMode: "error";
|
|
590
535
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
591
536
|
readonly stale_report: import("effect/ai/Tool").Tool<"stale_report", {
|
|
@@ -608,7 +553,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
|
|
|
608
553
|
readonly days_past: import("effect/Schema").Int;
|
|
609
554
|
}>>;
|
|
610
555
|
}>;
|
|
611
|
-
readonly failure: import("
|
|
556
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
612
557
|
readonly failureMode: "error";
|
|
613
558
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
614
559
|
readonly validate_bundle: import("effect/ai/Tool").Tool<"validate_bundle", {
|
|
@@ -649,7 +594,7 @@ export declare const OkfitToolkit: Toolkit.Toolkit<{
|
|
|
649
594
|
readonly range: import("effect/Schema").optionalKey<typeof import("@okfit/core").DiagnosticRange>;
|
|
650
595
|
}>>;
|
|
651
596
|
}>;
|
|
652
|
-
readonly failure: import("
|
|
597
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
653
598
|
readonly failureMode: "error";
|
|
654
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>;
|
|
655
600
|
}>;
|
|
@@ -695,7 +640,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
|
|
|
695
640
|
}>>;
|
|
696
641
|
}>>;
|
|
697
642
|
}>;
|
|
698
|
-
readonly failure: import("
|
|
643
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
699
644
|
readonly failureMode: "error";
|
|
700
645
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
701
646
|
readonly describe_vocabulary: import("effect/ai/Tool").Tool<"describe_vocabulary", {
|
|
@@ -748,7 +693,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
|
|
|
748
693
|
}>>;
|
|
749
694
|
}>>;
|
|
750
695
|
}>;
|
|
751
|
-
readonly failure: import("
|
|
696
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
752
697
|
readonly failureMode: "error";
|
|
753
698
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
754
699
|
readonly get_concept: import("effect/ai/Tool").Tool<"get_concept", {
|
|
@@ -772,7 +717,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
|
|
|
772
717
|
readonly field: import("effect/Schema").optionalKey<import("effect/Schema").String>;
|
|
773
718
|
}>>;
|
|
774
719
|
}>;
|
|
775
|
-
readonly failure: import("
|
|
720
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
776
721
|
readonly failureMode: "error";
|
|
777
722
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
778
723
|
readonly list_concepts: import("effect/ai/Tool").Tool<"list_concepts", {
|
|
@@ -795,7 +740,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
|
|
|
795
740
|
}>>;
|
|
796
741
|
readonly total: import("effect/Schema").Int;
|
|
797
742
|
}>;
|
|
798
|
-
readonly failure: import("
|
|
743
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
799
744
|
readonly failureMode: "error";
|
|
800
745
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
801
746
|
readonly stale_report: import("effect/ai/Tool").Tool<"stale_report", {
|
|
@@ -818,7 +763,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
|
|
|
818
763
|
readonly days_past: import("effect/Schema").Int;
|
|
819
764
|
}>>;
|
|
820
765
|
}>;
|
|
821
|
-
readonly failure: import("
|
|
766
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
822
767
|
readonly failureMode: "error";
|
|
823
768
|
}, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
|
|
824
769
|
readonly validate_bundle: import("effect/ai/Tool").Tool<"validate_bundle", {
|
|
@@ -859,7 +804,7 @@ export declare const ToolsLayer: (projectRoot: string, distribution?: Distributi
|
|
|
859
804
|
readonly range: import("effect/Schema").optionalKey<typeof import("@okfit/core").DiagnosticRange>;
|
|
860
805
|
}>>;
|
|
861
806
|
}>;
|
|
862
|
-
readonly failure: import("
|
|
807
|
+
readonly failure: typeof import("@effected/mcp").ToolRefusal;
|
|
863
808
|
readonly failureMode: "error";
|
|
864
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>;
|
|
865
810
|
}>, never, never>;
|
package/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
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";
|
|
@@ -7,4 +7,4 @@ 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.9.
|
|
61
|
-
"@okfit/engine": "0.
|
|
59
|
+
"@effected/yaml": "^0.19.1",
|
|
60
|
+
"@okfit/core": "0.9.1",
|
|
61
|
+
"@okfit/engine": "0.13.0",
|
|
62
62
|
"@okfit/profiles": "0.9.0",
|
|
63
|
-
"effect": "^4.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,6 +1,6 @@
|
|
|
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
|
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);
|