@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
package/src/remote.js CHANGED
@@ -22,7 +22,11 @@ function normalizeSlashes(value) {
22
22
  }
23
23
 
24
24
  function encodePath(value) {
25
- return String(value || "").split("/").filter(Boolean).map(encodeURIComponent).join("/");
25
+ return String(value || "")
26
+ .split("/")
27
+ .filter(Boolean)
28
+ .map(encodeURIComponent)
29
+ .join("/");
26
30
  }
27
31
 
28
32
  function sanitizeRemoteId(value, fallback) {
@@ -37,23 +41,33 @@ function parseGitHubBundleUrl(url) {
37
41
  } catch (error) {
38
42
  throw new Error(`Invalid GitHub bundle URL: ${url || "<missing>"}`);
39
43
  }
40
- if (parsed.protocol !== "https:"
41
- || parsed.hostname !== "github.com"
42
- || parsed.username
43
- || parsed.password
44
- || parsed.search
45
- || parsed.hash) {
44
+ if (
45
+ parsed.protocol !== "https:" ||
46
+ parsed.hostname !== "github.com" ||
47
+ parsed.username ||
48
+ parsed.password ||
49
+ parsed.search ||
50
+ parsed.hash
51
+ ) {
46
52
  throw new Error("Remote OKF v1 supports only https://github.com URLs.");
47
53
  }
48
54
  const parts = parsed.pathname.split("/").filter(Boolean);
49
55
  if (parts.length < 5 || parts[2] !== "tree") {
50
- throw new Error("GitHub bundle URL must be a repository tree URL: https://github.com/<owner>/<repo>/tree/<ref>/<path>");
56
+ throw new Error(
57
+ "GitHub bundle URL must be a repository tree URL: https://github.com/<owner>/<repo>/tree/<ref>/<path>",
58
+ );
51
59
  }
52
60
  const owner = parts[0];
53
61
  const repo = parts[1];
54
62
  const ref = parts[3];
55
63
  const bundlePath = normalizeSlashes(parts.slice(4).join("/"));
56
- if (!owner || !repo || !ref || !bundlePath || bundlePath.split("/").some((part) => part === "." || part === "..")) {
64
+ if (
65
+ !owner ||
66
+ !repo ||
67
+ !ref ||
68
+ !bundlePath ||
69
+ bundlePath.split("/").some((part) => part === "." || part === "..")
70
+ ) {
57
71
  throw new Error("GitHub bundle URL must include owner, repo, ref, and a safe bundle path.");
58
72
  }
59
73
  return { owner, repo, ref, path: bundlePath, url: String(parsed) };
@@ -67,7 +81,9 @@ async function fetchJson(fetchImpl, url) {
67
81
  },
68
82
  });
69
83
  if (!response || !response.ok) {
70
- const status = response ? `${response.status} ${response.statusText || ""}`.trim() : "no response";
84
+ const status = response
85
+ ? `${response.status} ${response.statusText || ""}`.trim()
86
+ : "no response";
71
87
  throw new Error(`GitHub request failed: ${status}`);
72
88
  }
73
89
  return response.json();
@@ -81,7 +97,9 @@ async function fetchBytes(fetchImpl, url) {
81
97
  },
82
98
  });
83
99
  if (!response || !response.ok) {
84
- const status = response ? `${response.status} ${response.statusText || ""}`.trim() : "no response";
100
+ const status = response
101
+ ? `${response.status} ${response.statusText || ""}`.trim()
102
+ : "no response";
85
103
  throw new Error(`GitHub raw file request failed: ${status}`);
86
104
  }
87
105
  if (typeof response.arrayBuffer === "function") {
@@ -117,17 +135,21 @@ function patternToRegex(pattern) {
117
135
  function matchesPattern(relativePath, pattern) {
118
136
  const normalizedPath = normalizeSlashes(relativePath);
119
137
  const normalizedPattern = normalizeSlashes(pattern);
120
- return normalizedPath === normalizedPattern
121
- || (normalizedPattern.endsWith("/") && normalizedPath.startsWith(normalizedPattern))
122
- || (normalizedPattern.includes("*") && patternToRegex(normalizedPattern).test(normalizedPath))
123
- || (!normalizedPattern.includes("*") && normalizedPath.startsWith(`${normalizedPattern}/`));
138
+ return (
139
+ normalizedPath === normalizedPattern ||
140
+ (normalizedPattern.endsWith("/") && normalizedPath.startsWith(normalizedPattern)) ||
141
+ (normalizedPattern.includes("*") && patternToRegex(normalizedPattern).test(normalizedPath)) ||
142
+ (!normalizedPattern.includes("*") && normalizedPath.startsWith(`${normalizedPattern}/`))
143
+ );
124
144
  }
125
145
 
126
146
  function allowsRemotePath(config, relativePath) {
127
147
  const include = Array.isArray(config.include) ? config.include : [];
128
148
  const exclude = Array.isArray(config.exclude) ? config.exclude : [];
129
- return (!include.length || include.some((pattern) => matchesPattern(relativePath, pattern)))
130
- && !exclude.some((pattern) => matchesPattern(relativePath, pattern));
149
+ return (
150
+ (!include.length || include.some((pattern) => matchesPattern(relativePath, pattern))) &&
151
+ !exclude.some((pattern) => matchesPattern(relativePath, pattern))
152
+ );
131
153
  }
132
154
 
133
155
  function excludesRemotePath(config, relativePath) {
@@ -140,7 +162,13 @@ function remoteReferencePath(fromPath, reference) {
140
162
  const relative = raw.startsWith("/")
141
163
  ? path.posix.normalize(raw.slice(1))
142
164
  : path.posix.normalize(path.posix.join(path.posix.dirname(fromPath), raw));
143
- if (!relative || relative === "." || relative === ".." || relative.startsWith("../") || path.posix.isAbsolute(relative)) {
165
+ if (
166
+ !relative ||
167
+ relative === "." ||
168
+ relative === ".." ||
169
+ relative.startsWith("../") ||
170
+ path.posix.isAbsolute(relative)
171
+ ) {
144
172
  return null;
145
173
  }
146
174
  return relative;
@@ -201,7 +229,9 @@ async function fetchGitHubBundle(config, options) {
201
229
  continue;
202
230
  }
203
231
  if (inventory.size >= limits.maxInventoryFiles) {
204
- throw new Error(`Remote bundle exceeds inventory limit of ${limits.maxInventoryFiles} files.`);
232
+ throw new Error(
233
+ `Remote bundle exceeds inventory limit of ${limits.maxInventoryFiles} files.`,
234
+ );
205
235
  }
206
236
  const relativePath = relativeRemotePath(source.path, entry.path);
207
237
  inventory.set(relativePath, entry);
@@ -212,42 +242,44 @@ async function fetchGitHubBundle(config, options) {
212
242
  if (documents.length + assets.length >= limits.maxFiles) {
213
243
  throw new Error(`Remote bundle exceeds file limit of ${limits.maxFiles}.`);
214
244
  }
215
- if (Number(entry.size || 0) > limits.maxFileBytes) {
216
- throw new Error(`Remote file exceeds byte limit: ${entry.path}`);
217
- }
218
- if (!entry.download_url) {
219
- throw new Error(`Remote file has no download URL: ${entry.path}`);
220
- }
221
- const content = await fetchBytes(fetchImpl, entry.download_url);
222
- const bytes = content.length;
223
- if (bytes > limits.maxFileBytes) {
224
- throw new Error(`Remote file exceeds byte limit after download: ${entry.path}`);
225
- }
226
- totalBytes += bytes;
227
- if (totalBytes > limits.maxTotalBytes) {
228
- throw new Error(`Remote bundle exceeds total byte limit of ${limits.maxTotalBytes}.`);
229
- }
230
- if (/^[0-9a-f]{40}$/i.test(String(entry.sha || ""))
231
- && gitBlobSha(content).toLowerCase() !== String(entry.sha).toLowerCase()) {
232
- throw new Error(`Remote file content does not match its Git blob SHA: ${entry.path}`);
233
- }
234
- if (kind === "document") {
235
- let text;
236
- try {
237
- text = new TextDecoder("utf-8", { fatal: true }).decode(content);
238
- } catch {
239
- throw new Error(`Remote Markdown document is not valid UTF-8: ${entry.path}`);
240
- }
241
- const document = {
242
- path: relativePath,
243
- text,
244
- source: `github://${source.owner}/${source.repo}/${pinnedRef}/${entry.path}`,
245
- blobSha: entry.sha || null,
246
- };
247
- documents.push(document);
248
- return document;
245
+ if (Number(entry.size || 0) > limits.maxFileBytes) {
246
+ throw new Error(`Remote file exceeds byte limit: ${entry.path}`);
247
+ }
248
+ if (!entry.download_url) {
249
+ throw new Error(`Remote file has no download URL: ${entry.path}`);
250
+ }
251
+ const content = await fetchBytes(fetchImpl, entry.download_url);
252
+ const bytes = content.length;
253
+ if (bytes > limits.maxFileBytes) {
254
+ throw new Error(`Remote file exceeds byte limit after download: ${entry.path}`);
255
+ }
256
+ totalBytes += bytes;
257
+ if (totalBytes > limits.maxTotalBytes) {
258
+ throw new Error(`Remote bundle exceeds total byte limit of ${limits.maxTotalBytes}.`);
259
+ }
260
+ if (
261
+ /^[0-9a-f]{40}$/i.test(String(entry.sha || "")) &&
262
+ gitBlobSha(content).toLowerCase() !== String(entry.sha).toLowerCase()
263
+ ) {
264
+ throw new Error(`Remote file content does not match its Git blob SHA: ${entry.path}`);
265
+ }
266
+ if (kind === "document") {
267
+ let text;
268
+ try {
269
+ text = new TextDecoder("utf-8", { fatal: true }).decode(content);
270
+ } catch {
271
+ throw new Error(`Remote Markdown document is not valid UTF-8: ${entry.path}`);
249
272
  }
250
- return { content, bytes };
273
+ const document = {
274
+ path: relativePath,
275
+ text,
276
+ source: `github://${source.owner}/${source.repo}/${pinnedRef}/${entry.path}`,
277
+ blobSha: entry.sha || null,
278
+ };
279
+ documents.push(document);
280
+ return document;
281
+ }
282
+ return { content, bytes };
251
283
  }
252
284
 
253
285
  await walk(source.path);
@@ -306,13 +338,16 @@ async function fetchGitHubBundle(config, options) {
306
338
  for (const [relativePath, references] of referenceGroups) {
307
339
  const entry = inventory.get(relativePath);
308
340
  if (!entry) {
309
- unresolvedReferences.push.apply(unresolvedReferences, references.map((reference) => ({
310
- path: reference.fromPath,
311
- field: reference.field,
312
- target: reference.value,
313
- resolvedPath: relativePath,
314
- code: "asset_missing",
315
- })));
341
+ unresolvedReferences.push.apply(
342
+ unresolvedReferences,
343
+ references.map((reference) => ({
344
+ path: reference.fromPath,
345
+ field: reference.field,
346
+ target: reference.value,
347
+ resolvedPath: relativePath,
348
+ code: "asset_missing",
349
+ })),
350
+ );
316
351
  continue;
317
352
  }
318
353
  const fetched = await fetchInventoryEntry(entry, relativePath, "asset");
@@ -0,0 +1,107 @@
1
+ "use strict";
2
+
3
+ // Command-line flags of the `search` command (owned with the search output,
4
+ // plan section 12). `parseSearchOption` consumes one flag at `argv[index]`
5
+ // into `search` and returns how many extra arguments it used, or -1 when the
6
+ // flag is not a search option; `fail` builds the CLI usage error.
7
+
8
+ const LIST_OPTIONS = Object.freeze({
9
+ "--type": "types",
10
+ "--tag": "tagsAny",
11
+ "--status": "statuses",
12
+ "--trust-tier": "trustTiers",
13
+ "--freshness": "freshness",
14
+ });
15
+
16
+ const SCALAR_OPTIONS = Object.freeze({
17
+ "--as-of": "asOf",
18
+ "--runtime": "runtime",
19
+ "--linked-to": "linkedTo",
20
+ "--linked-from": "linkedFrom",
21
+ "--relation-type": "relationType",
22
+ "--path-prefix": "pathPrefix",
23
+ "--mode": "mode",
24
+ "--min-coverage": "minCoverage",
25
+ "--min-relevance": "minRelevance",
26
+ });
27
+
28
+ const FLAG_OPTIONS = Object.freeze({
29
+ "--has-sources": (search) => {
30
+ search.hasSources = true;
31
+ },
32
+ "--no-sources": (search) => {
33
+ search.hasSources = false;
34
+ },
35
+ "--attestation-ready": (search) => {
36
+ search.attestationReady = true;
37
+ },
38
+ "--orphan-only": (search) => {
39
+ search.orphanOnly = true;
40
+ },
41
+ "--freshness-prior": (search) => {
42
+ search.freshnessPrior = true;
43
+ },
44
+ });
45
+
46
+ function createSearchOptions() {
47
+ return {
48
+ types: [],
49
+ tagsAny: [],
50
+ statuses: [],
51
+ trustTiers: [],
52
+ freshness: [],
53
+ frontmatter: {},
54
+ };
55
+ }
56
+
57
+ function hasOwn(object, key) {
58
+ return Object.hasOwn(object, key);
59
+ }
60
+
61
+ function requireValue(arg, argv, index, fail) {
62
+ const value = argv[index + 1];
63
+ if (!value || String(value).startsWith("-")) {
64
+ throw fail(`${arg} requires a value.`);
65
+ }
66
+ return value;
67
+ }
68
+
69
+ function parseSearchOption(arg, argv, index, search, fail) {
70
+ if (hasOwn(LIST_OPTIONS, arg)) {
71
+ search[LIST_OPTIONS[arg]].push(requireValue(arg, argv, index, fail));
72
+ return 1;
73
+ }
74
+ if (hasOwn(SCALAR_OPTIONS, arg)) {
75
+ search[SCALAR_OPTIONS[arg]] = requireValue(arg, argv, index, fail);
76
+ return 1;
77
+ }
78
+ if (arg === "--frontmatter") {
79
+ const value = argv[index + 1];
80
+ const separator = value?.indexOf("=");
81
+ if (!value || separator <= 0) {
82
+ throw fail("--frontmatter requires key=value.");
83
+ }
84
+ search.frontmatter[value.slice(0, separator)] = value.slice(separator + 1);
85
+ return 1;
86
+ }
87
+ if (hasOwn(FLAG_OPTIONS, arg)) {
88
+ FLAG_OPTIONS[arg](search);
89
+ return 0;
90
+ }
91
+ return -1;
92
+ }
93
+
94
+ // Search stemming languages for an index built by the CLI: --languages wins,
95
+ // then the project config; the lexical index detects per bundle otherwise.
96
+ function withSearchLanguages(index, languages) {
97
+ if (languages !== undefined && languages !== "") {
98
+ index.languages = languages;
99
+ }
100
+ return index;
101
+ }
102
+
103
+ module.exports = {
104
+ createSearchOptions,
105
+ parseSearchOption,
106
+ withSearchLanguages,
107
+ };
@@ -0,0 +1,61 @@
1
+ "use strict";
2
+
3
+ // Abstention signals (docs/plan-1.0.md R-4; WP3c-2 abstention v2). Every response to a query
4
+ // carries `confidence: { coverage, topSimilarity, lowConfidence, reasons }`:
5
+ //
6
+ // coverage share of the query terms the top result matched (lexical evidence, also for
7
+ // a semantic neighbour), null when nothing was returned;
8
+ // topSimilarity the best cosine similarity between the query and any candidate's units when
9
+ // the semantic side ran, null otherwise;
10
+ // lowConfidence (mode is any and coverage < 0.5) or (topSimilarity < minSimilarity and
11
+ // coverage < 0.5);
12
+ // reasons which clauses fired: weak_lexical_match, low_similarity.
13
+ //
14
+ // Lexical-only responses have no similarity, so the rule reduces to the 0.10 one. minSimilarity
15
+ // depends on the embedding model; the default was tuned for text-embedding-3-small on the
16
+ // development split of both fixtures (the most no-answer queries flagged while at most 3% of
17
+ // answerable queries with a relevant top result are) and is configurable per deployment as
18
+ // `confidence.minSimilarity` (test/fixtures/retrieval/reports/hybrid-0.12-2026-10-25.md).
19
+
20
+ const LOW_CONFIDENCE_COVERAGE = 0.5;
21
+ // Dev choice: every value from 0 to 0.8 flags the same no-answer queries and the same answerable
22
+ // queries with a relevant top result on both development splits (no no-answer query there has a
23
+ // top coverage below 0.5 without already being an any-term fallback), so the pre-registered
24
+ // tie-break, the smallest, applies: the similarity clause only fires on a negative cosine unless
25
+ // a deployment sets its own threshold.
26
+ const DEFAULT_MIN_SIMILARITY = 0;
27
+ const CONFIDENCE_REASONS = Object.freeze(["weak_lexical_match", "low_similarity"]);
28
+
29
+ function minSimilarityOption(value) {
30
+ if (value === undefined || value === null) return DEFAULT_MIN_SIMILARITY;
31
+ const number = Number(value);
32
+ if (typeof value === "boolean" || !Number.isFinite(number) || number < -1 || number > 1) {
33
+ throw new TypeError("minSimilarity must be a number between -1 and 1.");
34
+ }
35
+ return number;
36
+ }
37
+
38
+ // signals: { mode, coverage (top result, or null), topSimilarity (or null) }.
39
+ function assessConfidence(signals, minSimilarity) {
40
+ const source = signals || {};
41
+ const coverage = typeof source.coverage === "number" ? source.coverage : null;
42
+ const topSimilarity =
43
+ typeof source.topSimilarity === "number" && Number.isFinite(source.topSimilarity)
44
+ ? source.topSimilarity
45
+ : null;
46
+ const weak = coverage !== null && coverage < LOW_CONFIDENCE_COVERAGE;
47
+ const reasons = [];
48
+ if (weak && source.mode === "any") reasons.push("weak_lexical_match");
49
+ if (weak && topSimilarity !== null && topSimilarity < minSimilarityOption(minSimilarity)) {
50
+ reasons.push("low_similarity");
51
+ }
52
+ return { coverage, topSimilarity, lowConfidence: reasons.length > 0, reasons };
53
+ }
54
+
55
+ module.exports = {
56
+ CONFIDENCE_REASONS,
57
+ DEFAULT_MIN_SIMILARITY,
58
+ LOW_CONFIDENCE_COVERAGE,
59
+ assessConfidence,
60
+ minSimilarityOption,
61
+ };