@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,249 @@
1
+ "use strict";
2
+
3
+ // Hybrid fusion by convex combination of min-max normalised scores
4
+ // (docs/plan-1.0.md R-10; Bruch, Gai and Ingber, "An Analysis of Fusion
5
+ // Functions for Hybrid Retrieval", arXiv:2210.11934):
6
+ //
7
+ // fused = alpha * norm(dense) + (1 - alpha) * norm(lexical)
8
+ //
9
+ // Each side is normalised over its own ranked list to [0, 1] with its
10
+ // observed maximum as the upper bound; the lower bound is the observed
11
+ // minimum ("minmax") or the scoring function's theoretical minimum ("tmm":
12
+ // 0 for the BM25-style lexical score, -1 for cosine; Bruch et al. section 4),
13
+ // or the theoretical minimum on the lexical side only ("lexical-tmm"). Under
14
+ // plain min-max the weakest lexical hit maps to 0, the same as a candidate the
15
+ // lexical side never returned, which matters when the all-term set is small.
16
+ // A candidate missing from one list contributes 0 from that side. alpha 0 returns the
17
+ // lexical list and alpha 1 the dense list exactly (the other side is not
18
+ // merged in), so both ends reduce to a single retriever. Ties are broken by
19
+ // the dominant side's rank, then the other side's, then id, so the order is deterministic.
20
+
21
+ // Chosen with the default concept units on the development split of both fixtures with
22
+ // text-embedding-3-small at 512 dimensions: the pre-registered rule over alpha 0..1 under
23
+ // minmax, tmm and lexical-tmm (best mean dev Recall@5, ties within 0.005 by mean nDCG@10,
24
+ // then the smaller alpha) (test/fixtures/retrieval/reports/hybrid-0.11-2026-10-24.md).
25
+ const DEFAULT_FUSION_ALPHA = 0.4;
26
+ const FUSION_NORMALIZATIONS = Object.freeze(["minmax", "tmm", "lexical-tmm"]);
27
+ const DEFAULT_FUSION_NORMALIZATION = "tmm";
28
+ // Theoretical lower bounds per side, used by "tmm" and "lexical-tmm".
29
+ const THEORETICAL_MIN = Object.freeze({ lexical: 0, dense: -1 });
30
+
31
+ // Adaptive weight (WP3c-2): `fusion.alpha: "adaptive"` decides the weight once per query from
32
+ // signals the lexical pass has already computed, so every page of a query uses the same one:
33
+ //
34
+ // literal terms (quoted or identifier-like) matched by the all-term pass -> low (the literal
35
+ // guard keeps the all-term hits ahead as before);
36
+ // at least `autoFill` all-term hits and a best lexical coverage of 1 -> mid;
37
+ // no all-term hit and a best lexical coverage below 0.5 -> high;
38
+ // otherwise linear in the best lexical coverage, from high at 0.5 to mid at 1.
39
+ //
40
+ // With high >= mid the weight never grows with the lexical coverage. The weights are tuned on
41
+ // the development split (test/fixtures/retrieval/reports/hybrid-0.12-2026-10-25.md).
42
+ const ADAPTIVE_ALPHA = "adaptive";
43
+ // Dev-split choice over low {0.1, 0.2, 0.3} x mid {0.3, 0.4, 0.5} x high {0.6, 0.75, 0.9}
44
+ // (best mean Recall@5, ties within 0.005 by mean nDCG@10, then the smallest sum). The fixed
45
+ // 0.4 stays the default: the adaptive weight did not meet its pre-registered conditions.
46
+ const DEFAULT_ADAPTIVE_WEIGHTS = Object.freeze({ low: 0.1, mid: 0.5, high: 0.9 });
47
+ const ADAPTIVE_WEAK_COVERAGE = 0.5;
48
+ // The fusion weight used when none is configured: a number, or ADAPTIVE_ALPHA.
49
+ const DEFAULT_ALPHA_SETTING = DEFAULT_FUSION_ALPHA;
50
+ const ALPHA_REASONS = Object.freeze([
51
+ "fixed",
52
+ "literal_terms",
53
+ "all_terms",
54
+ "weak_lexical",
55
+ "interpolated",
56
+ ]);
57
+
58
+ function fusionNormalization(value) {
59
+ if (value === undefined || value === null) return DEFAULT_FUSION_NORMALIZATION;
60
+ if (!FUSION_NORMALIZATIONS.includes(value)) {
61
+ throw new TypeError(`fusion normalization must be one of ${FUSION_NORMALIZATIONS.join(", ")}.`);
62
+ }
63
+ return value;
64
+ }
65
+
66
+ function fusionAlpha(value) {
67
+ if (value === undefined || value === null) return DEFAULT_FUSION_ALPHA;
68
+ const alpha = Number(value);
69
+ if (typeof value === "boolean" || !Number.isFinite(alpha) || alpha < 0 || alpha > 1) {
70
+ throw new TypeError("fusion alpha must be a number between 0 and 1.");
71
+ }
72
+ return alpha;
73
+ }
74
+
75
+ // A configured weight: ADAPTIVE_ALPHA or a number in [0, 1] (DEFAULT_ALPHA_SETTING when unset).
76
+ function fusionAlphaSetting(value) {
77
+ if (value === undefined || value === null) return DEFAULT_ALPHA_SETTING;
78
+ if (value === ADAPTIVE_ALPHA) return ADAPTIVE_ALPHA;
79
+ try {
80
+ return fusionAlpha(value);
81
+ } catch {
82
+ throw new TypeError(`fusion alpha must be "${ADAPTIVE_ALPHA}" or a number between 0 and 1.`);
83
+ }
84
+ }
85
+
86
+ // { low, mid, high } over the defaults; every weight in [0, 1] and high >= mid.
87
+ function adaptiveWeights(value) {
88
+ if (value === undefined || value === null) return DEFAULT_ADAPTIVE_WEIGHTS;
89
+ const unknown =
90
+ typeof value === "object" && !Array.isArray(value)
91
+ ? Object.keys(value).filter((key) => !Object.hasOwn(DEFAULT_ADAPTIVE_WEIGHTS, key))
92
+ : ["value"];
93
+ if (unknown.length) {
94
+ throw new TypeError("fusion adaptive weights must be an object of low, mid and high.");
95
+ }
96
+ const weights = {};
97
+ Object.keys(DEFAULT_ADAPTIVE_WEIGHTS).forEach((key) => {
98
+ weights[key] =
99
+ value[key] === undefined ? DEFAULT_ADAPTIVE_WEIGHTS[key] : fusionAlpha(value[key]);
100
+ });
101
+ if (weights.high < weights.mid) {
102
+ throw new TypeError("fusion adaptive weights need high >= mid.");
103
+ }
104
+ return Object.freeze(weights);
105
+ }
106
+
107
+ const roundWeight = (value) => Math.round(value * 1e6) / 1e6;
108
+
109
+ // signals: { literal, allTermsTotal, autoFill, topCoverage } -> { alpha, reason }.
110
+ function adaptiveAlpha(signals, weights) {
111
+ const config = adaptiveWeights(weights);
112
+ const source = signals || {};
113
+ const coverage = Math.min(1, Math.max(0, Number(source.topCoverage) || 0));
114
+ const allTerms = Number(source.allTermsTotal) || 0;
115
+ const autoFill = Number(source.autoFill) || 0;
116
+ if (source.literal) return { alpha: config.low, reason: "literal_terms" };
117
+ if (allTerms > 0 && allTerms >= autoFill && coverage >= 1) {
118
+ return { alpha: config.mid, reason: "all_terms" };
119
+ }
120
+ if (allTerms === 0 && coverage < ADAPTIVE_WEAK_COVERAGE) {
121
+ return { alpha: config.high, reason: "weak_lexical" };
122
+ }
123
+ const share = Math.min(
124
+ 1,
125
+ Math.max(0, (coverage - ADAPTIVE_WEAK_COVERAGE) / (1 - ADAPTIVE_WEAK_COVERAGE)),
126
+ );
127
+ return {
128
+ alpha: roundWeight(config.high + (config.mid - config.high) * share),
129
+ reason: "interpolated",
130
+ };
131
+ }
132
+
133
+ // The weight of one query: a fixed setting as configured, or the adaptive rule's choice.
134
+ function resolveAlpha(setting, signals, weights) {
135
+ const value = fusionAlphaSetting(setting);
136
+ if (value === ADAPTIVE_ALPHA) return adaptiveAlpha(signals, weights);
137
+ return { alpha: value, reason: "fixed" };
138
+ }
139
+
140
+ // [{ id, score }] in rank order -> Map(id -> { rank, score, norm }). With
141
+ // `floor` null the observed minimum is the lower bound; a list whose scores
142
+ // are all equal then normalises to 1 (every entry is the best).
143
+ function normalise(list, floor) {
144
+ const entries = new Map();
145
+ if (!Array.isArray(list) || !list.length) return entries;
146
+ let min = Infinity;
147
+ let max = -Infinity;
148
+ list.forEach((entry) => {
149
+ if (entry.score < min) min = entry.score;
150
+ if (entry.score > max) max = entry.score;
151
+ });
152
+ if (floor !== null && floor !== undefined) min = Math.min(floor, min);
153
+ const span = max - min;
154
+ list.forEach((entry, rank) => {
155
+ if (entries.has(entry.id)) return;
156
+ entries.set(entry.id, {
157
+ rank,
158
+ score: entry.score,
159
+ norm: span > 0 ? (entry.score - min) / span : 1,
160
+ });
161
+ });
162
+ return entries;
163
+ }
164
+
165
+ function assertList(list, name) {
166
+ if (list === undefined || list === null) return [];
167
+ if (
168
+ !Array.isArray(list) ||
169
+ list.some((entry) => !entry || typeof entry.id !== "string" || !Number.isFinite(entry.score))
170
+ ) {
171
+ throw new TypeError(`${name} must be an array of { id, score } entries.`);
172
+ }
173
+ return list;
174
+ }
175
+
176
+ // lexical, dense: [{ id, score }] each in its own rank order (best first).
177
+ // Returns [{ id, lexicalScore, denseScore, lexicalNorm, denseNorm, fusedScore }]
178
+ // sorted by fusedScore; a score is null when the candidate is absent from
179
+ // that list.
180
+ function fuseRankings(options) {
181
+ const config = options || {};
182
+ const alpha = fusionAlpha(config.alpha);
183
+ const normalization = fusionNormalization(config.normalization);
184
+ const lexical = normalise(
185
+ assertList(config.lexical, "lexical"),
186
+ normalization === "minmax" ? null : THEORETICAL_MIN.lexical,
187
+ );
188
+ const dense = normalise(
189
+ assertList(config.dense, "dense"),
190
+ normalization === "tmm" ? THEORETICAL_MIN.dense : null,
191
+ );
192
+ const ids = [];
193
+ const seen = new Set();
194
+ const take = (map) => {
195
+ map.forEach((_value, id) => {
196
+ if (!seen.has(id)) {
197
+ seen.add(id);
198
+ ids.push(id);
199
+ }
200
+ });
201
+ };
202
+ if (alpha < 1) take(lexical);
203
+ if (alpha > 0) take(dense);
204
+ const fused = ids.map((id) => {
205
+ const left = lexical.get(id);
206
+ const right = dense.get(id);
207
+ const lexicalNorm = left ? left.norm : 0;
208
+ const denseNorm = right ? right.norm : 0;
209
+ return {
210
+ id,
211
+ lexicalScore: left ? left.score : null,
212
+ denseScore: right ? right.score : null,
213
+ lexicalNorm,
214
+ denseNorm,
215
+ fusedScore: alpha * denseNorm + (1 - alpha) * lexicalNorm,
216
+ lexicalRank: left ? left.rank : Infinity,
217
+ denseRank: right ? right.rank : Infinity,
218
+ };
219
+ });
220
+ // Ties follow the dominant side's order first (dense when alpha > 0.5), so
221
+ // alpha 1 keeps dense ties in dense order and alpha 0 lexical ties in
222
+ // lexical order. Infinity - Infinity is NaN, which falls through.
223
+ const [first, second] = alpha > 0.5 ? ["denseRank", "lexicalRank"] : ["lexicalRank", "denseRank"];
224
+ fused.sort(
225
+ (a, b) =>
226
+ b.fusedScore - a.fusedScore ||
227
+ a[first] - b[first] ||
228
+ a[second] - b[second] ||
229
+ (a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
230
+ );
231
+ return fused.map(({ lexicalRank, denseRank, ...entry }) => entry);
232
+ }
233
+
234
+ module.exports = {
235
+ ADAPTIVE_ALPHA,
236
+ ALPHA_REASONS,
237
+ DEFAULT_ADAPTIVE_WEIGHTS,
238
+ DEFAULT_ALPHA_SETTING,
239
+ DEFAULT_FUSION_ALPHA,
240
+ DEFAULT_FUSION_NORMALIZATION,
241
+ FUSION_NORMALIZATIONS,
242
+ adaptiveAlpha,
243
+ adaptiveWeights,
244
+ fuseRankings,
245
+ fusionAlpha,
246
+ fusionAlphaSetting,
247
+ fusionNormalization,
248
+ resolveAlpha,
249
+ };