@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
package/src/assets.js CHANGED
@@ -76,11 +76,7 @@ function assetKey(bundle, relativePath) {
76
76
 
77
77
  function isExternalReference(value) {
78
78
  const text = String(value || "").trim();
79
- return (
80
- text.startsWith("//")
81
- || text.startsWith("#")
82
- || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(text)
83
- );
79
+ return text.startsWith("//") || text.startsWith("#") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(text);
84
80
  }
85
81
 
86
82
  function looksLikeExplicitSourcePath(value) {
@@ -89,12 +85,12 @@ function looksLikeExplicitSourcePath(value) {
89
85
  return false;
90
86
  }
91
87
  return (
92
- text.startsWith("/")
93
- || text.startsWith("./")
94
- || text.startsWith("../")
95
- || text.startsWith("references/")
96
- || (text.includes("/") && Boolean(path.posix.extname(text)))
97
- || Object.prototype.hasOwnProperty.call(MIME_TYPES, path.posix.extname(text).toLowerCase())
88
+ text.startsWith("/") ||
89
+ text.startsWith("./") ||
90
+ text.startsWith("../") ||
91
+ text.startsWith("references/") ||
92
+ (text.includes("/") && Boolean(path.posix.extname(text))) ||
93
+ Object.prototype.hasOwnProperty.call(MIME_TYPES, path.posix.extname(text).toLowerCase())
98
94
  );
99
95
  }
100
96
 
@@ -164,24 +160,27 @@ function collectAssetReferences(document) {
164
160
  if (typeof computation === "string") {
165
161
  add("computation", "computation", computation, true);
166
162
  } else if (computation && typeof computation === "object" && !Array.isArray(computation)) {
167
- const fileComputation = computation.mode === "file"
168
- ? computation
169
- : computation.computation && computation.computation.mode === "file"
170
- ? computation.computation
171
- : null;
163
+ const fileComputation =
164
+ computation.mode === "file"
165
+ ? computation
166
+ : computation.computation && computation.computation.mode === "file"
167
+ ? computation.computation
168
+ : null;
172
169
  if (fileComputation) {
173
170
  add("computation", "computation", fileComputation.path, true);
174
171
  }
175
172
  }
176
173
 
177
- const executor = documentValue(document, "executor")
178
- || (computation && typeof computation === "object" && computation.executor);
174
+ const executor =
175
+ documentValue(document, "executor") ||
176
+ (computation && typeof computation === "object" && computation.executor);
179
177
  if (executor && typeof executor === "object" && !Array.isArray(executor)) {
180
178
  add("executor", "executor.resource", executor.resource, true);
181
179
  }
182
180
 
183
- const attester = documentValue(document, "attester")
184
- || (computation && typeof computation === "object" && computation.attester);
181
+ const attester =
182
+ documentValue(document, "attester") ||
183
+ (computation && typeof computation === "object" && computation.attester);
185
184
  if (attester && typeof attester === "object" && !Array.isArray(attester)) {
186
185
  add("attester", "attester.resource", attester.resource, true);
187
186
  }
@@ -196,24 +195,44 @@ function isInsidePath(root, target) {
196
195
 
197
196
  function resolveBundleAssetPath(bundleRoot, fromPath, reference) {
198
197
  if (!bundleRoot) {
199
- throw new AssetRegistryError("asset_bundle_root_missing", "Referenced asset has no local bundle root.");
198
+ throw new AssetRegistryError(
199
+ "asset_bundle_root_missing",
200
+ "Referenced asset has no local bundle root.",
201
+ );
200
202
  }
201
203
  const raw = normalizeSlashes(String(reference || "").trim());
202
204
  if (!raw || raw.includes("\0") || isExternalReference(raw)) {
203
- throw new AssetRegistryError("asset_invalid_reference", "Referenced asset is not a safe bundle-local path.");
205
+ throw new AssetRegistryError(
206
+ "asset_invalid_reference",
207
+ "Referenced asset is not a safe bundle-local path.",
208
+ );
204
209
  }
205
210
 
206
211
  const root = path.resolve(bundleRoot);
207
212
  const relative = raw.startsWith("/")
208
213
  ? path.posix.normalize(raw.slice(1))
209
- : path.posix.normalize(path.posix.join(path.posix.dirname(normalizeSlashes(fromPath || "")), raw));
210
- if (!relative || relative === "." || relative === ".." || relative.startsWith("../") || path.posix.isAbsolute(relative)) {
211
- throw new AssetRegistryError("asset_outside_root", `Referenced asset resolves outside bundle root: ${raw}`);
214
+ : path.posix.normalize(
215
+ path.posix.join(path.posix.dirname(normalizeSlashes(fromPath || "")), raw),
216
+ );
217
+ if (
218
+ !relative ||
219
+ relative === "." ||
220
+ relative === ".." ||
221
+ relative.startsWith("../") ||
222
+ path.posix.isAbsolute(relative)
223
+ ) {
224
+ throw new AssetRegistryError(
225
+ "asset_outside_root",
226
+ `Referenced asset resolves outside bundle root: ${raw}`,
227
+ );
212
228
  }
213
229
 
214
230
  const absolutePath = path.resolve(root, ...relative.split("/"));
215
231
  if (!isInsidePath(root, absolutePath)) {
216
- throw new AssetRegistryError("asset_outside_root", `Referenced asset resolves outside bundle root: ${raw}`);
232
+ throw new AssetRegistryError(
233
+ "asset_outside_root",
234
+ `Referenced asset resolves outside bundle root: ${raw}`,
235
+ );
217
236
  }
218
237
  return {
219
238
  root,
@@ -228,15 +247,24 @@ function inspectAssetPath(root, relativePath) {
228
247
  rootStat = fs.lstatSync(root);
229
248
  } catch (error) {
230
249
  if (error && error.code === "ENOENT") {
231
- throw new AssetRegistryError("asset_bundle_root_missing", `Bundle root does not exist: ${root}`);
250
+ throw new AssetRegistryError(
251
+ "asset_bundle_root_missing",
252
+ `Bundle root does not exist: ${root}`,
253
+ );
232
254
  }
233
255
  throw error;
234
256
  }
235
257
  if (rootStat.isSymbolicLink()) {
236
- throw new AssetRegistryError("asset_symlink", "Referenced assets cannot use a symbolic-link bundle root.");
258
+ throw new AssetRegistryError(
259
+ "asset_symlink",
260
+ "Referenced assets cannot use a symbolic-link bundle root.",
261
+ );
237
262
  }
238
263
  if (!rootStat.isDirectory()) {
239
- throw new AssetRegistryError("asset_bundle_root_invalid", `Bundle root is not a directory: ${root}`);
264
+ throw new AssetRegistryError(
265
+ "asset_bundle_root_invalid",
266
+ `Bundle root is not a directory: ${root}`,
267
+ );
240
268
  }
241
269
 
242
270
  const segments = normalizeSlashes(relativePath).split("/");
@@ -248,28 +276,46 @@ function inspectAssetPath(root, relativePath) {
248
276
  stat = fs.lstatSync(current);
249
277
  } catch (error) {
250
278
  if (error && error.code === "ENOENT") {
251
- throw new AssetRegistryError("asset_missing", `Referenced asset does not exist: ${relativePath}`);
279
+ throw new AssetRegistryError(
280
+ "asset_missing",
281
+ `Referenced asset does not exist: ${relativePath}`,
282
+ );
252
283
  }
253
284
  throw error;
254
285
  }
255
286
  if (stat.isSymbolicLink()) {
256
- throw new AssetRegistryError("asset_symlink", `Referenced asset path traverses a symbolic link: ${relativePath}`);
287
+ throw new AssetRegistryError(
288
+ "asset_symlink",
289
+ `Referenced asset path traverses a symbolic link: ${relativePath}`,
290
+ );
257
291
  }
258
292
  if (index < segments.length - 1 && !stat.isDirectory()) {
259
- throw new AssetRegistryError("asset_path_component_not_directory", `Referenced asset path has a non-directory component: ${relativePath}`);
293
+ throw new AssetRegistryError(
294
+ "asset_path_component_not_directory",
295
+ `Referenced asset path has a non-directory component: ${relativePath}`,
296
+ );
260
297
  }
261
298
  if (index === segments.length - 1 && !stat.isFile()) {
262
- throw new AssetRegistryError("asset_not_file", `Referenced asset is not a regular file: ${relativePath}`);
299
+ throw new AssetRegistryError(
300
+ "asset_not_file",
301
+ `Referenced asset is not a regular file: ${relativePath}`,
302
+ );
263
303
  }
264
304
  }
265
305
  }
266
306
 
267
307
  function mimeTypeForPath(relativePath) {
268
- return MIME_TYPES[path.posix.extname(String(relativePath || "")).toLowerCase()] || "application/octet-stream";
308
+ return (
309
+ MIME_TYPES[path.posix.extname(String(relativePath || "")).toLowerCase()] ||
310
+ "application/octet-stream"
311
+ );
269
312
  }
270
313
 
271
314
  function mimeIsDefinitelyBinary(mimeType) {
272
- return BINARY_MIME_TYPES.has(mimeType) || BINARY_MIME_PREFIXES.some((prefix) => mimeType.startsWith(prefix));
315
+ return (
316
+ BINARY_MIME_TYPES.has(mimeType) ||
317
+ BINARY_MIME_PREFIXES.some((prefix) => mimeType.startsWith(prefix))
318
+ );
273
319
  }
274
320
 
275
321
  function mimeIsText(mimeType) {
@@ -307,16 +353,19 @@ function bundleMapFor(bundles) {
307
353
 
308
354
  function diagnosticFor(error, reference, extra) {
309
355
  const known = error instanceof AssetRegistryError;
310
- return Object.assign({
311
- code: known ? error.code : "asset_read_error",
312
- severity: "warning",
313
- layer: "project",
314
- bundle: reference.bundle,
315
- path: reference.fromPath,
316
- field: reference.field,
317
- target: reference.value,
318
- message: error && error.message ? error.message : String(error),
319
- }, extra || {});
356
+ return Object.assign(
357
+ {
358
+ code: known ? error.code : "asset_read_error",
359
+ severity: "warning",
360
+ layer: "project",
361
+ bundle: reference.bundle,
362
+ path: reference.fromPath,
363
+ field: reference.field,
364
+ target: reference.value,
365
+ message: error && error.message ? error.message : String(error),
366
+ },
367
+ extra || {},
368
+ );
320
369
  }
321
370
 
322
371
  function publicReference(reference) {
@@ -331,9 +380,8 @@ function publicReference(reference) {
331
380
 
332
381
  function buildAssetRegistry(documents, bundles, options) {
333
382
  const config = options || {};
334
- const maxAssetBytes = config.maxAssetBytes === undefined
335
- ? DEFAULT_MAX_ASSET_BYTES
336
- : Number(config.maxAssetBytes);
383
+ const maxAssetBytes =
384
+ config.maxAssetBytes === undefined ? DEFAULT_MAX_ASSET_BYTES : Number(config.maxAssetBytes);
337
385
  if (!Number.isSafeInteger(maxAssetBytes) || maxAssetBytes < 1) {
338
386
  throw new TypeError("maxAssetBytes must be a positive safe integer.");
339
387
  }
@@ -353,16 +401,33 @@ function buildAssetRegistry(documents, bundles, options) {
353
401
  diagnostics.push(diagnosticFor(error, reference));
354
402
  return;
355
403
  }
356
- if (typeof config.skipResolvedPath === "function"
357
- && config.skipResolvedPath(configuredBundle || { id: reference.bundle }, resolved.path, reference)) {
404
+ if (
405
+ typeof config.skipResolvedPath === "function" &&
406
+ config.skipResolvedPath(
407
+ configuredBundle || { id: reference.bundle },
408
+ resolved.path,
409
+ reference,
410
+ )
411
+ ) {
358
412
  return;
359
413
  }
360
- if (typeof config.allowResolvedPath === "function"
361
- && !config.allowResolvedPath(configuredBundle || { id: reference.bundle }, resolved.path, reference)) {
362
- diagnostics.push(diagnosticFor(
363
- new AssetRegistryError("asset_excluded", `Referenced asset is excluded by bundle policy: ${resolved.path}`),
414
+ if (
415
+ typeof config.allowResolvedPath === "function" &&
416
+ !config.allowResolvedPath(
417
+ configuredBundle || { id: reference.bundle },
418
+ resolved.path,
364
419
  reference,
365
- ));
420
+ )
421
+ ) {
422
+ diagnostics.push(
423
+ diagnosticFor(
424
+ new AssetRegistryError(
425
+ "asset_excluded",
426
+ `Referenced asset is excluded by bundle policy: ${resolved.path}`,
427
+ ),
428
+ reference,
429
+ ),
430
+ );
366
431
  return;
367
432
  }
368
433
  const groupKey = `${reference.bundle}\u0000${resolved.path}`;
@@ -382,7 +447,10 @@ function buildAssetRegistry(documents, bundles, options) {
382
447
 
383
448
  const assets = [];
384
449
  Array.from(groups.values())
385
- .sort((left, right) => left.bundle.localeCompare(right.bundle) || left.path.localeCompare(right.path))
450
+ .sort(
451
+ (left, right) =>
452
+ left.bundle.localeCompare(right.bundle) || left.path.localeCompare(right.path),
453
+ )
386
454
  .forEach((group) => {
387
455
  const first = group.references[0];
388
456
  let content;
@@ -390,11 +458,17 @@ function buildAssetRegistry(documents, bundles, options) {
390
458
  inspectAssetPath(group.root, group.path);
391
459
  const stat = fs.statSync(group.absolutePath);
392
460
  if (stat.size > maxAssetBytes) {
393
- throw new AssetRegistryError("asset_too_large", `Referenced asset exceeds the ${maxAssetBytes} byte limit: ${group.path}`);
461
+ throw new AssetRegistryError(
462
+ "asset_too_large",
463
+ `Referenced asset exceeds the ${maxAssetBytes} byte limit: ${group.path}`,
464
+ );
394
465
  }
395
466
  let descriptor;
396
467
  try {
397
- descriptor = fs.openSync(group.absolutePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
468
+ descriptor = fs.openSync(
469
+ group.absolutePath,
470
+ fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0),
471
+ );
398
472
  content = fs.readFileSync(descriptor);
399
473
  } finally {
400
474
  if (descriptor !== undefined) {
@@ -402,23 +476,36 @@ function buildAssetRegistry(documents, bundles, options) {
402
476
  }
403
477
  }
404
478
  if (content.length > maxAssetBytes) {
405
- throw new AssetRegistryError("asset_too_large", `Referenced asset exceeds the ${maxAssetBytes} byte limit: ${group.path}`);
479
+ throw new AssetRegistryError(
480
+ "asset_too_large",
481
+ `Referenced asset exceeds the ${maxAssetBytes} byte limit: ${group.path}`,
482
+ );
406
483
  }
407
484
  } catch (error) {
408
- const normalizedError = error && error.code === "ELOOP"
409
- ? new AssetRegistryError("asset_symlink", `Referenced asset is a symbolic link: ${group.path}`)
410
- : error;
411
- diagnostics.push(diagnosticFor(normalizedError, first, {
412
- referencedBy: group.references.map(publicReference),
413
- }));
485
+ const normalizedError =
486
+ error && error.code === "ELOOP"
487
+ ? new AssetRegistryError(
488
+ "asset_symlink",
489
+ `Referenced asset is a symbolic link: ${group.path}`,
490
+ )
491
+ : error;
492
+ diagnostics.push(
493
+ diagnosticFor(normalizedError, first, {
494
+ referencedBy: group.references.map(publicReference),
495
+ }),
496
+ );
414
497
  return;
415
498
  }
416
499
 
417
500
  const mimeType = mimeTypeForPath(group.path);
418
501
  const classification = classifyAssetContent(content, mimeType);
419
- const referencedBy = group.references.map(publicReference).sort((left, right) => (
420
- String(left.uri).localeCompare(String(right.uri)) || left.field.localeCompare(right.field)
421
- ));
502
+ const referencedBy = group.references
503
+ .map(publicReference)
504
+ .sort(
505
+ (left, right) =>
506
+ String(left.uri).localeCompare(String(right.uri)) ||
507
+ left.field.localeCompare(right.field),
508
+ );
422
509
  const roles = Array.from(new Set(group.references.map((reference) => reference.role))).sort();
423
510
  const asset = {
424
511
  key: assetKey(group.bundle, group.path),
@@ -442,11 +529,16 @@ function buildAssetRegistry(documents, bundles, options) {
442
529
  assets.push(asset);
443
530
 
444
531
  if (mimeIsText(mimeType) && !classification.validUtf8) {
445
- diagnostics.push(diagnosticFor(
446
- new AssetRegistryError("asset_invalid_utf8", `Text asset is not valid UTF-8: ${group.path}`),
447
- first,
448
- { referencedBy },
449
- ));
532
+ diagnostics.push(
533
+ diagnosticFor(
534
+ new AssetRegistryError(
535
+ "asset_invalid_utf8",
536
+ `Text asset is not valid UTF-8: ${group.path}`,
537
+ ),
538
+ first,
539
+ { referencedBy },
540
+ ),
541
+ );
450
542
  }
451
543
  });
452
544