@mfdaves/okf-mcp 0.9.1 → 0.13.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/CHANGELOG.md +100 -0
  2. package/README.md +452 -26
  3. package/bin/okf-mcp.js +6 -1
  4. package/okf/okf-mcp/distribution/reference-bundle.md +10 -3
  5. package/okf/okf-mcp/index.md +2 -1
  6. package/okf/okf-mcp/interfaces/http-authoring-api.md +11 -2
  7. package/okf/okf-mcp/interfaces/mcp-http.md +64 -0
  8. package/okf/okf-mcp/interfaces/mcp-tools.md +25 -6
  9. package/okf/okf-mcp/overview/okf-mcp.md +16 -6
  10. package/okf/okf-mcp/policies/authoring-safety.md +28 -5
  11. package/okf/okf-mcp/runtime/indexer.md +14 -1
  12. package/okf/okf-mcp/runtime/mcp-server.md +16 -8
  13. package/okf/okf-mcp/specs/producer-api.md +16 -2
  14. package/package.json +17 -5
  15. package/server.json +38 -2
  16. package/src/assets.js +165 -73
  17. package/src/authoring/candidates.js +434 -0
  18. package/src/authoring/git-preflight.js +225 -0
  19. package/src/authoring/git-publish.js +783 -0
  20. package/src/authoring/live.js +757 -0
  21. package/src/authoring/paths.js +112 -0
  22. package/src/authoring/policy-hook.js +221 -0
  23. package/src/authoring/proposal-policy.js +159 -0
  24. package/src/authoring/receipts.js +373 -0
  25. package/src/authoring/render.js +38 -0
  26. package/src/authoring/shared.js +75 -0
  27. package/src/authoring/staging.js +216 -0
  28. package/src/authoring.js +386 -287
  29. package/src/cache/files.js +147 -0
  30. package/src/cache/lock.js +201 -0
  31. package/src/cache/paths.js +197 -0
  32. package/src/cache/store.js +703 -0
  33. package/src/catalog-text.js +19 -0
  34. package/src/cli/commands.js +448 -0
  35. package/src/cli/http-options.js +193 -0
  36. package/src/cli/options.js +554 -0
  37. package/src/cli/usage.js +96 -0
  38. package/src/cli.js +18 -932
  39. package/src/computation.js +99 -61
  40. package/src/context/assemble.js +567 -0
  41. package/src/context/cli-options.js +88 -0
  42. package/src/context/score.js +234 -0
  43. package/src/context/sections.js +274 -0
  44. package/src/embed/interface.js +160 -0
  45. package/src/embed/openai.js +715 -0
  46. package/src/embed/prepare.js +182 -0
  47. package/src/embed/units.js +96 -0
  48. package/src/error-details.js +53 -0
  49. package/src/git-source.js +112 -52
  50. package/src/graph.js +95 -37
  51. package/src/http-server.js +36 -17
  52. package/src/index.js +15 -0
  53. package/src/indexer/assemble.js +566 -0
  54. package/src/indexer/build.js +290 -0
  55. package/src/indexer/cache.js +81 -0
  56. package/src/indexer/edges.js +430 -0
  57. package/src/indexer/index.js +44 -0
  58. package/src/indexer/paths.js +178 -0
  59. package/src/indexer/resolve.js +282 -0
  60. package/src/indexer/update.js +720 -0
  61. package/src/indexer.js +3 -1068
  62. package/src/live-authoring.js +4 -2329
  63. package/src/markdown.js +21 -16
  64. package/src/mcp/auth.js +409 -0
  65. package/src/mcp/http.js +317 -0
  66. package/src/mcp/principal.js +59 -0
  67. package/src/mcp/registry.js +356 -0
  68. package/src/mcp/resources.js +45 -0
  69. package/src/mcp/server.js +567 -0
  70. package/src/mcp/tools/catalog.js +247 -0
  71. package/src/mcp/tools/computation.js +83 -0
  72. package/src/mcp/tools/context.js +133 -0
  73. package/src/mcp/tools/graph.js +167 -0
  74. package/src/mcp/tools/live-authoring.js +316 -0
  75. package/src/mcp/tools/migration.js +86 -0
  76. package/src/mcp/tools/producers.js +79 -0
  77. package/src/mcp/tools/proposals.js +225 -0
  78. package/src/mcp/tools/provenance.js +87 -0
  79. package/src/mcp/tools/remote.js +79 -0
  80. package/src/mcp/tools/search.js +242 -0
  81. package/src/mcp-server.js +3 -1611
  82. package/src/migration.js +431 -253
  83. package/src/parser.js +245 -130
  84. package/src/plugins.js +71 -48
  85. package/src/policy/write-policy.js +713 -0
  86. package/src/producer-publisher.js +202 -78
  87. package/src/producers.js +311 -103
  88. package/src/project.js +346 -93
  89. package/src/remote.js +96 -61
  90. package/src/search/cli-options.js +107 -0
  91. package/src/search/confidence.js +61 -0
  92. package/src/search/dense.js +304 -0
  93. package/src/search/embedding-cli.js +57 -0
  94. package/src/search/embedding-config.js +217 -0
  95. package/src/search/fusion.js +249 -0
  96. package/src/search/hybrid.js +526 -0
  97. package/src/search/languages.js +200 -0
  98. package/src/search/lexical.js +695 -0
  99. package/src/search/query.js +620 -0
  100. package/src/search/stem/among.js +43 -0
  101. package/src/search/stem/base-stemmer.js +311 -0
  102. package/src/search/stem/en-regions.js +456 -0
  103. package/src/search/stem/en-suffixes.js +664 -0
  104. package/src/search/stem/en-tables.js +176 -0
  105. package/src/search/stem/en.js +238 -0
  106. package/src/search/stem/it-regions.js +459 -0
  107. package/src/search/stem/it-suffixes.js +471 -0
  108. package/src/search/stem/it-tables.js +257 -0
  109. package/src/search/stem/it.js +155 -0
  110. package/src/search-index.js +2 -81
  111. package/src/search.js +2 -252
  112. package/src/store.js +134 -81
  113. package/src/tool-packs.js +346 -0
  114. package/src/v02.js +301 -105
  115. package/src/validation.js +24 -20
@@ -0,0 +1,225 @@
1
+ "use strict";
2
+
3
+ const {
4
+ DESTRUCTIVE_WRITE,
5
+ GATES,
6
+ LOCAL_WRITE,
7
+ READ_ONLY,
8
+ defineTool,
9
+ expectedToolOperation,
10
+ jsonContent,
11
+ nonEmptyStringParameter,
12
+ objectParameter,
13
+ requireAuthoring,
14
+ stringArrayParameter,
15
+ stringParameter,
16
+ } = require("../registry");
17
+
18
+ const tools = {
19
+ okf_validate_concept: {
20
+ ...defineTool(
21
+ "Validate a proposed new OKF concept without writing a proposal or concept file.",
22
+ READ_ONLY,
23
+ {
24
+ bundle: nonEmptyStringParameter(
25
+ "Writable root id; optional when exactly one local root is configured.",
26
+ ),
27
+ path: nonEmptyStringParameter("Safe bundle relative Markdown path for the concept."),
28
+ frontmatter: objectParameter("Complete YAML frontmatter represented as a JSON object."),
29
+ body: stringParameter("Markdown body for the concept."),
30
+ },
31
+ ["path", "frontmatter"],
32
+ ),
33
+ enabled: GATES.projectHelper,
34
+ handler: async (state, args, principal) =>
35
+ jsonContent(
36
+ await expectedToolOperation(() => requireAuthoring(state, principal).validateConcept(args)),
37
+ ),
38
+ },
39
+ okf_suggest_concept_path: {
40
+ ...defineTool(
41
+ "Suggest a safe bundle relative Markdown path from a concept type and title.",
42
+ READ_ONLY,
43
+ {
44
+ bundle: nonEmptyStringParameter(
45
+ "Writable root id; optional when exactly one local root is configured.",
46
+ ),
47
+ type: nonEmptyStringParameter("Concept type used to build the path."),
48
+ title: nonEmptyStringParameter("Concept title used to build the file name."),
49
+ prefix: stringParameter("Optional bundle relative directory prefix."),
50
+ },
51
+ ["type", "title"],
52
+ ),
53
+ enabled: GATES.projectHelper,
54
+ handler: async (state, args, principal) =>
55
+ jsonContent(
56
+ await expectedToolOperation(() =>
57
+ requireAuthoring(state, principal).suggestConceptPath(args),
58
+ ),
59
+ ),
60
+ },
61
+ okf_propose_concept: {
62
+ ...defineTool(
63
+ "Create a reviewable proposal for a new OKF concept without writing the concept file.",
64
+ LOCAL_WRITE,
65
+ {
66
+ bundle: nonEmptyStringParameter(
67
+ "Writable root id; optional when exactly one local root is configured.",
68
+ ),
69
+ path: nonEmptyStringParameter("Safe bundle relative Markdown path for the new concept."),
70
+ frontmatter: objectParameter("Complete YAML frontmatter represented as a JSON object."),
71
+ body: stringParameter("Markdown body for the new concept."),
72
+ message: stringParameter(
73
+ "Optional review note explaining why the concept should be created.",
74
+ ),
75
+ },
76
+ ["path", "frontmatter"],
77
+ ),
78
+ enabled: GATES.authoringMutation,
79
+ handler: async (state, args, principal) => {
80
+ const result = await expectedToolOperation(() =>
81
+ requireAuthoring(state, principal).proposeConcept(args),
82
+ );
83
+ return jsonContent(result, { isError: result.created === false });
84
+ },
85
+ },
86
+ okf_propose_update: {
87
+ ...defineTool(
88
+ "Create a reviewable update proposal for an existing OKF concept while preserving unspecified content.",
89
+ LOCAL_WRITE,
90
+ {
91
+ uri: nonEmptyStringParameter("Canonical or path based okf URI of the existing concept."),
92
+ frontmatter: objectParameter(
93
+ "Frontmatter fields to add or replace; unspecified fields are preserved.",
94
+ { minProperties: 1 },
95
+ ),
96
+ removeFrontmatterKeys: stringArrayParameter(
97
+ "Frontmatter keys to remove; the id field cannot be removed.",
98
+ { minItems: 1, nonEmptyItems: true },
99
+ ),
100
+ body: stringParameter("Replacement Markdown body; omit it to preserve the current body."),
101
+ message: stringParameter(
102
+ "Optional review note explaining why the concept should be updated.",
103
+ ),
104
+ },
105
+ ["uri"],
106
+ {
107
+ anyOf: [
108
+ { required: ["frontmatter"] },
109
+ { required: ["removeFrontmatterKeys"] },
110
+ { required: ["body"] },
111
+ ],
112
+ },
113
+ ),
114
+ enabled: GATES.authoringMutation,
115
+ handler: async (state, args, principal) => {
116
+ const result = await expectedToolOperation(() =>
117
+ requireAuthoring(state, principal).proposeUpdate(args),
118
+ );
119
+ return jsonContent(result, { isError: result.created === false });
120
+ },
121
+ },
122
+ okf_propose_attested_computation: {
123
+ ...defineTool(
124
+ "Create one coordinated review proposal for an Attested Computation concept and optional external computation file; never execute it.",
125
+ LOCAL_WRITE,
126
+ {
127
+ bundle: nonEmptyStringParameter(
128
+ "Writable root id; optional when exactly one local root is configured.",
129
+ ),
130
+ path: nonEmptyStringParameter(
131
+ "Safe bundle-relative Markdown path for the computation concept.",
132
+ ),
133
+ frontmatter: objectParameter("Complete strict OKF v0.2 Attested Computation frontmatter."),
134
+ body: stringParameter(
135
+ "Markdown body, including inline computation when no computation file is declared.",
136
+ ),
137
+ computationPath: nonEmptyStringParameter(
138
+ "Bundle-relative path of the optional external computation file.",
139
+ ),
140
+ computationContent: stringParameter(
141
+ "Text content for the optional external computation file.",
142
+ ),
143
+ message: stringParameter("Optional review note."),
144
+ },
145
+ ["path", "frontmatter"],
146
+ ),
147
+ enabled: GATES.computationAuthoring,
148
+ handler: async (state, args, principal) => {
149
+ const result = await expectedToolOperation(() =>
150
+ requireAuthoring(state, principal).proposeAttestedComputation(args),
151
+ );
152
+ return jsonContent(result, { isError: result.created === false });
153
+ },
154
+ },
155
+ okf_list_proposals: {
156
+ ...defineTool("List compact metadata for stored authoring proposals.", READ_ONLY, {
157
+ bundle: nonEmptyStringParameter("Limit results to proposals for this bundle id."),
158
+ status: stringParameter("Limit results to this proposal status.", {
159
+ enum: ["proposed", "accepted", "rejected"],
160
+ }),
161
+ }),
162
+ enabled: GATES.proposalRead,
163
+ handler: async (state, args, principal) =>
164
+ jsonContent(
165
+ await expectedToolOperation(() => requireAuthoring(state, principal).listProposals(args)),
166
+ ),
167
+ },
168
+ okf_get_proposal: {
169
+ ...defineTool(
170
+ "Read one authoring proposal, including its candidate content and validation result.",
171
+ READ_ONLY,
172
+ {
173
+ proposalId: nonEmptyStringParameter("Identifier returned when the proposal was created."),
174
+ },
175
+ ["proposalId"],
176
+ ),
177
+ enabled: GATES.proposalRead,
178
+ handler: async (state, args, principal) =>
179
+ jsonContent(
180
+ await expectedToolOperation(() => requireAuthoring(state, principal).getProposal(args)),
181
+ ),
182
+ },
183
+ okf_accept_proposal: {
184
+ ...defineTool(
185
+ "Accept a reviewed proposal and write its new or updated concept file after revalidation.",
186
+ DESTRUCTIVE_WRITE,
187
+ {
188
+ proposalId: nonEmptyStringParameter("Identifier of the proposed change to accept."),
189
+ },
190
+ ["proposalId"],
191
+ ),
192
+ enabled: GATES.authoringMutation,
193
+ handler: async (state, args, principal) => {
194
+ const result = await expectedToolOperation(() =>
195
+ requireAuthoring(state, principal).acceptProposal(
196
+ Object.assign({}, args, {
197
+ allowComputation: state.allowComputationAuthoring,
198
+ }),
199
+ ),
200
+ );
201
+ if (result.accepted) {
202
+ state.rebuildIndex();
203
+ }
204
+ return jsonContent(result, { isError: result.accepted === false });
205
+ },
206
+ },
207
+ okf_reject_proposal: {
208
+ ...defineTool(
209
+ "Reject a reviewed proposal so it can no longer be accepted.",
210
+ DESTRUCTIVE_WRITE,
211
+ {
212
+ proposalId: nonEmptyStringParameter("Identifier of the proposed change to reject."),
213
+ reason: stringParameter("Optional explanation recorded with the rejection."),
214
+ },
215
+ ["proposalId"],
216
+ ),
217
+ enabled: GATES.authoringMutation,
218
+ handler: async (state, args, principal) =>
219
+ jsonContent(
220
+ await expectedToolOperation(() => requireAuthoring(state, principal).rejectProposal(args)),
221
+ ),
222
+ },
223
+ };
224
+
225
+ module.exports = { tools };
@@ -0,0 +1,87 @@
1
+ "use strict";
2
+
3
+ const { getProvenance, readBundleAsset } = require("../../computation");
4
+ const { readConceptGitSource } = require("../../git-source");
5
+ const {
6
+ READ_ONLY,
7
+ booleanParameter,
8
+ defineTool,
9
+ expectedToolOperation,
10
+ integerParameter,
11
+ jsonContent,
12
+ nonEmptyStringParameter,
13
+ } = require("../registry");
14
+
15
+ const tools = {
16
+ get_provenance: {
17
+ ...defineTool(
18
+ "Trace normalized source provenance through internal concepts without fetching external resources.",
19
+ READ_ONLY,
20
+ {
21
+ uri: nonEmptyStringParameter("Canonical or compatibility OKF URI of the root concept."),
22
+ maxDepth: integerParameter("Maximum internal source depth.", 0, 10, 3),
23
+ maxNodes: integerParameter("Maximum provenance nodes.", 1, 1000, 100),
24
+ includeExternal: booleanParameter(
25
+ "Include URL and opaque provenance leaves without fetching them.",
26
+ ),
27
+ },
28
+ ["uri"],
29
+ ),
30
+ handler: async (state, args) =>
31
+ jsonContent(
32
+ await expectedToolOperation(() => getProvenance(state.index, args.uri, args), {
33
+ translateTypeError: true,
34
+ }),
35
+ ),
36
+ },
37
+ read_bundle_asset: {
38
+ ...defineTool(
39
+ "Read one explicitly referenced, already indexed bundle asset with digest verification and byte bounds.",
40
+ READ_ONLY,
41
+ {
42
+ uri: nonEmptyStringParameter("Indexed okf-asset URI."),
43
+ bundle: nonEmptyStringParameter("Bundle id used with path when uri is omitted."),
44
+ path: nonEmptyStringParameter("Bundle-relative indexed asset path used with bundle."),
45
+ maxContentBytes: integerParameter("Maximum asset bytes to return.", 1, 1048576, 65536),
46
+ },
47
+ [],
48
+ { anyOf: [{ required: ["uri"] }, { required: ["bundle", "path"] }] },
49
+ ),
50
+ handler: async (state, args) =>
51
+ jsonContent(
52
+ await expectedToolOperation(() => readBundleAsset(state.index, args), {
53
+ translateTypeError: true,
54
+ }),
55
+ ),
56
+ },
57
+ read_git_source: {
58
+ ...defineTool(
59
+ "Read one pinned sources[].git entry from an explicitly mapped checkout or bare repository without fetching.",
60
+ READ_ONLY,
61
+ {
62
+ concept: nonEmptyStringParameter(
63
+ "Concept ID, Markdown path, custom ID, or compatibility URI declaring the source.",
64
+ ),
65
+ sourceId: nonEmptyStringParameter("Exact sources[].id value to read."),
66
+ maxContentBytes: integerParameter("Maximum Git blob bytes to read.", 1, 1048576, 65536),
67
+ },
68
+ ["concept", "sourceId"],
69
+ ),
70
+ handler: async (state, args) =>
71
+ jsonContent(
72
+ await expectedToolOperation(
73
+ () =>
74
+ readConceptGitSource(
75
+ state.index,
76
+ args.concept,
77
+ args.sourceId,
78
+ state.repositoryMappings,
79
+ { maxBytes: args.maxContentBytes || 65536 },
80
+ ),
81
+ { translateTypeError: true },
82
+ ),
83
+ ),
84
+ },
85
+ };
86
+
87
+ module.exports = { tools };
@@ -0,0 +1,79 @@
1
+ "use strict";
2
+
3
+ const { fetchGitHubBundle, sanitizeRemoteId } = require("../../remote");
4
+ const {
5
+ GATES,
6
+ READ_ONLY,
7
+ REMOTE_LOAD,
8
+ ToolExecutionError,
9
+ defineTool,
10
+ expectedToolOperation,
11
+ jsonContent,
12
+ nonEmptyStringParameter,
13
+ stringArrayParameter,
14
+ stringParameter,
15
+ } = require("../registry");
16
+
17
+ const tools = {
18
+ load_remote_bundle: {
19
+ ...defineTool(
20
+ "Fetch a public GitHub Markdown tree and add it to the in memory index as a read only remote bundle.",
21
+ REMOTE_LOAD,
22
+ {
23
+ id: nonEmptyStringParameter("Unique bundle id to assign to the fetched remote tree."),
24
+ url: nonEmptyStringParameter("Public GitHub tree URL to fetch."),
25
+ provider: stringParameter("Remote provider name. Only github is supported.", {
26
+ enum: ["github"],
27
+ default: "github",
28
+ }),
29
+ include: stringArrayParameter(
30
+ "Optional glob patterns selecting remote Markdown paths to include.",
31
+ { nonEmptyItems: true },
32
+ ),
33
+ exclude: stringArrayParameter(
34
+ "Optional glob patterns selecting remote Markdown paths to exclude.",
35
+ { nonEmptyItems: true },
36
+ ),
37
+ },
38
+ ["id", "url"],
39
+ ),
40
+ enabled: GATES.runtimeRemote,
41
+ handler: async (state, args) => {
42
+ const provider = String(args.provider || "github");
43
+ if (provider !== "github") {
44
+ throw new ToolExecutionError(`Unsupported remote bundle provider: ${provider}`);
45
+ }
46
+ const normalizedId = sanitizeRemoteId(args.id);
47
+ if (normalizedId !== args.id) {
48
+ throw new ToolExecutionError(
49
+ "Remote bundle id may contain only letters, numbers, underscores, dots, and hyphens.",
50
+ );
51
+ }
52
+ if (state.index.bundles.some((bundle) => bundle.id === normalizedId)) {
53
+ throw new ToolExecutionError(`Bundle id already loaded: ${normalizedId}`);
54
+ }
55
+ const remoteBundle = await expectedToolOperation(
56
+ () =>
57
+ fetchGitHubBundle({
58
+ id: normalizedId,
59
+ url: args.url,
60
+ include: args.include || [],
61
+ exclude: args.exclude || [],
62
+ }),
63
+ { translateTypeError: true },
64
+ );
65
+ state.remoteBundles.push(remoteBundle);
66
+ state.rebuildIndex();
67
+ return jsonContent(remoteBundle.remoteSource);
68
+ },
69
+ },
70
+ list_remote_bundles: {
71
+ ...defineTool("List metadata for remote bundles currently loaded into the server.", READ_ONLY),
72
+ handler: (state) =>
73
+ jsonContent(
74
+ state.remoteBundles.map((bundle) => Object.assign({ id: bundle.id }, bundle.remoteSource)),
75
+ ),
76
+ },
77
+ };
78
+
79
+ module.exports = { tools };
@@ -0,0 +1,242 @@
1
+ "use strict";
2
+
3
+ const { MAX_QUERY_CHARACTERS, MAX_QUERY_TERMS } = require("../../search/lexical");
4
+ const { SEARCH_MODES, searchConcepts } = require("../../search/query");
5
+ const {
6
+ READ_ONLY,
7
+ booleanParameter,
8
+ defineTool,
9
+ detailParameter,
10
+ expectedToolOperation,
11
+ integerParameter,
12
+ jsonContent,
13
+ nonEmptyStringParameter,
14
+ objectParameter,
15
+ optionalBooleanParameter,
16
+ stringArrayParameter,
17
+ stringParameter,
18
+ } = require("../registry");
19
+
20
+ // R-11: the description asks for keywords in the catalog's languages and exact
21
+ // identifiers, and explains the confidence fields. It must stay free of
22
+ // catalog text (B-6, S-3): it is composed from constants only.
23
+ const QUERY_GUIDANCE =
24
+ "Write it as keywords in the catalog's languages (Italian and English word endings and " +
25
+ "accents are normalised) and put identifiers, codes, paths, SKUs and exact titles in double " +
26
+ "quotes: quoted text is matched literally (no stemming, accents and single letters kept) " +
27
+ "against ids, paths, aliases, titles and raw tokens, and unquoted tokens with digits or " +
28
+ "hyphens stay literal too. Leave out question words; unquoted stop words and single letters " +
29
+ "are dropped.";
30
+
31
+ const SEARCH_DESCRIPTION =
32
+ "Search OKF concepts with a text query and structured filters; returns ranked summaries " +
33
+ `with match confidence. ${QUERY_GUIDANCE} Mode auto lists the concepts matching every ` +
34
+ "term first and, when there are only a few of them, follows them with concepts matching " +
35
+ "some of the terms (mode auto in the response; any when nothing matches every term). The " +
36
+ "response reports the mode that ran, queryTerms and droppedTerms, allTermsTotal (how many concepts match every term), and " +
37
+ "lowConfidence, true when the any-term fallback produced the page and its best result " +
38
+ "matched fewer than half of the terms: treat such results as weak and rephrase or narrow " +
39
+ "with filters. Each result carries coverage (share of query terms it matched) and relevance " +
40
+ "(score relative to the top result). When the server has an embedder configured, ranking is " +
41
+ "hybrid by default: lexical and semantic similarity are fused, so concepts that use other " +
42
+ "words for the same idea are found too; relevance is then fused, mode and coverage keep " +
43
+ "their lexical meaning (lowConfidence reads the top result shown), and each result adds lexicalScore, denseScore and " +
44
+ "fusedScore. The response then reports hybrid (whether fusion ran) and embedder, whose " +
45
+ "degraded flag says the semantic side could not run and the results are lexical only. " +
46
+ "Hybrid responses also report alphaUsed, the weight of the semantic side for this query, " +
47
+ "and alphaReason: fixed, or under the adaptive weight literal_terms (quoted or " +
48
+ "identifier-like terms and a concept matching every term), all_terms (several concepts " +
49
+ "match every term), weak_lexical " +
50
+ "(nothing matches even half of the terms) or interpolated (in between). Every response to a " +
51
+ "query also carries confidence: { coverage (of the top result), topSimilarity (the best " +
52
+ "semantic similarity when the embedder ran, else null), lowConfidence, reasons }; with an " +
53
+ "embedder lowConfidence is also true when the top result matched fewer than half of the " +
54
+ "terms and no concept reaches the server's similarity threshold (reasons " +
55
+ "weak_lexical_match, low_similarity).";
56
+
57
+ const HYBRID_DESCRIPTION =
58
+ "Fuse lexical and semantic ranking when the server has an embedder configured (the default " +
59
+ "there); false ranks lexically and makes no embedding request. Ignored without an embedder.";
60
+
61
+ // Options only the server supplies; never accepted from tool arguments.
62
+ const RUNTIME_OPTIONS = [
63
+ "autoFill",
64
+ "queryVector",
65
+ "vectorCache",
66
+ "embedUnits",
67
+ "alpha",
68
+ "adaptiveAlpha",
69
+ "minSimilarity",
70
+ "fusionNormalization",
71
+ ];
72
+
73
+ async function runSearch(state, args) {
74
+ const options = Object.assign({ detail: "compact" }, args || {});
75
+ RUNTIME_OPTIONS.forEach((key) => {
76
+ delete options[key];
77
+ });
78
+ if (state.embeddings) {
79
+ return state.embeddings.search(state.index, options);
80
+ }
81
+ const response = searchConcepts(state.index, options);
82
+ if (options.hybrid !== true) {
83
+ return response;
84
+ }
85
+ const results = response.results;
86
+ delete response.results;
87
+ return Object.assign(response, {
88
+ hybrid: false,
89
+ embedder: { id: null, remote: null, dimension: null, degraded: true, code: "not_configured" },
90
+ results,
91
+ });
92
+ }
93
+
94
+ const MODE_DESCRIPTION =
95
+ "auto lists concepts matching every term first and appends concepts matching some terms " +
96
+ "when only a few match all of them; all requires every term (the pre-0.10 behaviour); any " +
97
+ "ranks concepts matching at least one term. The response's mode field says which one ran " +
98
+ "(auto when both kinds are listed).";
99
+
100
+ function modeParameter() {
101
+ return stringParameter(MODE_DESCRIPTION, { enum: SEARCH_MODES.slice(), default: "auto" });
102
+ }
103
+
104
+ function unitIntervalParameter(description) {
105
+ return { type: "number", description, minimum: 0, maximum: 1 };
106
+ }
107
+
108
+ function listConcepts(index, args) {
109
+ const options = Object.assign({ detail: "compact" }, args || {});
110
+ if (options.type && !options.types) {
111
+ options.types = [options.type];
112
+ }
113
+ if (options.tag && !options.tagsAny) {
114
+ options.tagsAny = [options.tag];
115
+ }
116
+ return searchConcepts(index, options);
117
+ }
118
+
119
+ const tools = {
120
+ list_concepts: {
121
+ ...defineTool(
122
+ "List compact OKF concept summaries with optional bundle, type, tag, and text filters.",
123
+ READ_ONLY,
124
+ {
125
+ query: stringParameter(
126
+ `Optional text query applied together with the listing filters; maximum ${MAX_QUERY_TERMS} terms after stop words. ${QUERY_GUIDANCE}`,
127
+ { maxLength: MAX_QUERY_CHARACTERS },
128
+ ),
129
+ mode: modeParameter(),
130
+ bundle: nonEmptyStringParameter("Limit results to this bundle id."),
131
+ type: nonEmptyStringParameter("Limit results to this exact concept type."),
132
+ tag: nonEmptyStringParameter("Limit results to concepts containing this tag."),
133
+ detail: detailParameter(
134
+ "Compact returns only URI, title, type, and description, plus coverage and relevance when a query is given; full includes navigation metadata and signals.",
135
+ ),
136
+ limit: integerParameter("Maximum number of concepts to return.", 1, 250, 25),
137
+ offset: integerParameter(
138
+ "Number of matching concepts to skip before returning results.",
139
+ 0,
140
+ undefined,
141
+ 0,
142
+ ),
143
+ },
144
+ ),
145
+ handler: async (state, args) =>
146
+ jsonContent(
147
+ await expectedToolOperation(() => listConcepts(state.index, args), {
148
+ translateTypeError: true,
149
+ }),
150
+ ),
151
+ },
152
+ search_concepts: {
153
+ ...defineTool(SEARCH_DESCRIPTION, READ_ONLY, {
154
+ query: stringParameter(
155
+ `Text query matched against concept metadata and content; maximum ${MAX_QUERY_TERMS} terms after stop words. ${QUERY_GUIDANCE}`,
156
+ { maxLength: MAX_QUERY_CHARACTERS },
157
+ ),
158
+ mode: modeParameter(),
159
+ minCoverage: unitIntervalParameter(
160
+ "Drop results that matched a smaller share of the query terms than this; off by default. Can leave total at 0.",
161
+ ),
162
+ minRelevance: unitIntervalParameter(
163
+ "Drop results whose score relative to the top result is below this; off by default. Can leave total at 0.",
164
+ ),
165
+ hybrid: optionalBooleanParameter(HYBRID_DESCRIPTION),
166
+ freshnessPrior: booleanParameter(
167
+ "Multiply scores by 0.5 for deprecated, 0.7 for stale, and 0.85 for draft concepts before ranking; off by default.",
168
+ ),
169
+ bundle: nonEmptyStringParameter("Limit results to this bundle id."),
170
+ types: stringArrayParameter("Limit results to any of these concept types.", {
171
+ nonEmptyItems: true,
172
+ }),
173
+ tagsAny: stringArrayParameter("Require at least one of these tags.", {
174
+ nonEmptyItems: true,
175
+ }),
176
+ tagsAll: stringArrayParameter("Require all of these tags.", { nonEmptyItems: true }),
177
+ pathPrefix: stringParameter(
178
+ "Limit results to bundle relative paths beginning with this prefix.",
179
+ ),
180
+ relationType: nonEmptyStringParameter(
181
+ "Limit results to concepts with an outgoing relation of this type.",
182
+ ),
183
+ frontmatter: objectParameter(
184
+ "Exact frontmatter filters; array fields use contains matching.",
185
+ ),
186
+ linkedTo: nonEmptyStringParameter("Require an outgoing edge to this concept URI."),
187
+ linkedFrom: nonEmptyStringParameter("Require an incoming edge from this concept URI."),
188
+ orphanOnly: booleanParameter(
189
+ "Return only concepts without incoming or outgoing resolved edges.",
190
+ ),
191
+ statuses: stringArrayParameter("Limit results to lifecycle statuses.", {
192
+ nonEmptyItems: true,
193
+ }),
194
+ trustTiers: stringArrayParameter(
195
+ "Limit results to unverified, machine-confirmed, or human-reviewed trust tiers.",
196
+ { nonEmptyItems: true },
197
+ ),
198
+ freshness: stringArrayParameter(
199
+ "Limit results to unspecified, fresh, stale, or invalid freshness states.",
200
+ { nonEmptyItems: true },
201
+ ),
202
+ asOf: nonEmptyStringParameter(
203
+ "UTC ISO date or datetime used for deterministic freshness evaluation.",
204
+ ),
205
+ hasSources: optionalBooleanParameter(
206
+ "Require concepts to have or not have normalized sources.",
207
+ ),
208
+ runtime: nonEmptyStringParameter("Limit results to this Attested Computation runtime."),
209
+ attestationReady: optionalBooleanParameter("Require static Attested Computation readiness."),
210
+ generatedBy: nonEmptyStringParameter("Limit results to this generator actor."),
211
+ verifiedBy: nonEmptyStringParameter("Limit results to concepts verified by this actor."),
212
+ detail: detailParameter(
213
+ "Compact returns URI, title, type, description, coverage, and relevance; full adds score, snippet, matchedTerms, navigation metadata, and signals.",
214
+ ),
215
+ limit: integerParameter("Maximum number of concepts to return.", 1, 250, 25),
216
+ offset: integerParameter(
217
+ "Number of matching concepts to skip before returning results.",
218
+ 0,
219
+ undefined,
220
+ 0,
221
+ ),
222
+ }),
223
+ handler: async (state, args) =>
224
+ jsonContent(
225
+ await expectedToolOperation(() => runSearch(state, args), { translateTypeError: true }),
226
+ ),
227
+ },
228
+ embedding_status: {
229
+ ...defineTool(
230
+ "Report the hybrid search embedder: its id, whether text leaves the machine (remote), the " +
231
+ "vector dimension, whether searches are degraded to lexical only and why, the vector " +
232
+ "cache row count, the startup and last preparation receipts, and token usage. Listed " +
233
+ "only when an embedder is configured.",
234
+ READ_ONLY,
235
+ {},
236
+ ),
237
+ enabled: (state) => Boolean(state?.embeddings),
238
+ handler: async (state) => jsonContent(state.embeddings.status()),
239
+ },
240
+ };
241
+
242
+ module.exports = { QUERY_GUIDANCE, tools };