@mfdaves/okf-mcp 0.9.1 → 0.12.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 (97) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.md +172 -17
  3. package/bin/okf-mcp.js +6 -1
  4. package/okf/okf-mcp/policies/authoring-safety.md +11 -1
  5. package/package.json +17 -5
  6. package/server.json +2 -2
  7. package/src/assets.js +165 -73
  8. package/src/authoring/candidates.js +391 -0
  9. package/src/authoring/git-preflight.js +225 -0
  10. package/src/authoring/git-publish.js +776 -0
  11. package/src/authoring/live.js +789 -0
  12. package/src/authoring/paths.js +112 -0
  13. package/src/authoring/policy-hook.js +221 -0
  14. package/src/authoring/proposal-policy.js +137 -0
  15. package/src/authoring/receipts.js +329 -0
  16. package/src/authoring/render.js +38 -0
  17. package/src/authoring/shared.js +75 -0
  18. package/src/authoring/staging.js +216 -0
  19. package/src/authoring.js +386 -287
  20. package/src/cache/files.js +147 -0
  21. package/src/cache/lock.js +201 -0
  22. package/src/cache/paths.js +197 -0
  23. package/src/cache/store.js +703 -0
  24. package/src/catalog-text.js +19 -0
  25. package/src/cli.js +184 -151
  26. package/src/computation.js +99 -61
  27. package/src/context/assemble.js +567 -0
  28. package/src/context/cli-options.js +88 -0
  29. package/src/context/score.js +234 -0
  30. package/src/context/sections.js +274 -0
  31. package/src/embed/interface.js +160 -0
  32. package/src/embed/openai.js +715 -0
  33. package/src/embed/prepare.js +182 -0
  34. package/src/embed/units.js +96 -0
  35. package/src/git-source.js +112 -52
  36. package/src/graph.js +95 -37
  37. package/src/http-server.js +36 -17
  38. package/src/index.js +15 -0
  39. package/src/indexer/assemble.js +566 -0
  40. package/src/indexer/build.js +290 -0
  41. package/src/indexer/cache.js +81 -0
  42. package/src/indexer/edges.js +430 -0
  43. package/src/indexer/index.js +44 -0
  44. package/src/indexer/paths.js +178 -0
  45. package/src/indexer/resolve.js +282 -0
  46. package/src/indexer/update.js +720 -0
  47. package/src/indexer.js +3 -1068
  48. package/src/live-authoring.js +4 -2329
  49. package/src/markdown.js +21 -16
  50. package/src/mcp/registry.js +328 -0
  51. package/src/mcp/resources.js +45 -0
  52. package/src/mcp/server.js +472 -0
  53. package/src/mcp/tools/catalog.js +244 -0
  54. package/src/mcp/tools/computation.js +83 -0
  55. package/src/mcp/tools/context.js +133 -0
  56. package/src/mcp/tools/graph.js +167 -0
  57. package/src/mcp/tools/live-authoring.js +316 -0
  58. package/src/mcp/tools/migration.js +86 -0
  59. package/src/mcp/tools/producers.js +79 -0
  60. package/src/mcp/tools/proposals.js +213 -0
  61. package/src/mcp/tools/provenance.js +87 -0
  62. package/src/mcp/tools/remote.js +79 -0
  63. package/src/mcp/tools/search.js +242 -0
  64. package/src/mcp-server.js +3 -1611
  65. package/src/migration.js +431 -253
  66. package/src/parser.js +245 -130
  67. package/src/plugins.js +71 -48
  68. package/src/policy/write-policy.js +713 -0
  69. package/src/producer-publisher.js +195 -77
  70. package/src/producers.js +265 -101
  71. package/src/project.js +277 -93
  72. package/src/remote.js +96 -61
  73. package/src/search/cli-options.js +107 -0
  74. package/src/search/confidence.js +61 -0
  75. package/src/search/dense.js +304 -0
  76. package/src/search/embedding-cli.js +57 -0
  77. package/src/search/embedding-config.js +217 -0
  78. package/src/search/fusion.js +249 -0
  79. package/src/search/hybrid.js +526 -0
  80. package/src/search/languages.js +200 -0
  81. package/src/search/lexical.js +695 -0
  82. package/src/search/query.js +620 -0
  83. package/src/search/stem/among.js +43 -0
  84. package/src/search/stem/base-stemmer.js +311 -0
  85. package/src/search/stem/en-regions.js +456 -0
  86. package/src/search/stem/en-suffixes.js +664 -0
  87. package/src/search/stem/en-tables.js +176 -0
  88. package/src/search/stem/en.js +238 -0
  89. package/src/search/stem/it-regions.js +459 -0
  90. package/src/search/stem/it-suffixes.js +471 -0
  91. package/src/search/stem/it-tables.js +257 -0
  92. package/src/search/stem/it.js +155 -0
  93. package/src/search-index.js +2 -81
  94. package/src/search.js +2 -252
  95. package/src/store.js +134 -81
  96. package/src/v02.js +301 -105
  97. package/src/validation.js +24 -20
@@ -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 };