@mfdaves/okf-mcp 0.7.0 → 0.9.0

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 (34) hide show
  1. package/README.md +79 -18
  2. package/okf/{bundles/okf-mcp → okf-mcp}/distribution/reference-bundle.md +1 -1
  3. package/okf/{bundles/okf-mcp → okf-mcp}/index.md +3 -0
  4. package/okf/{bundles/okf-mcp → okf-mcp}/interfaces/mcp-tools.md +13 -5
  5. package/okf/{bundles/okf-mcp → okf-mcp}/overview/okf-mcp.md +5 -3
  6. package/okf/{bundles/okf-mcp → okf-mcp}/policies/authoring-safety.md +9 -1
  7. package/okf/{bundles/okf-mcp → okf-mcp}/runtime/file-concept-store.md +1 -1
  8. package/okf/{bundles/okf-mcp → okf-mcp}/runtime/mcp-server.md +6 -2
  9. package/okf/okf-mcp/runtime/producer-host.md +28 -0
  10. package/okf/{bundles/okf-mcp → okf-mcp}/specs/concept-format.md +1 -1
  11. package/okf/okf-mcp/specs/producer-api.md +26 -0
  12. package/okf/{bundles/okf-mcp → okf-mcp}/workflows/concept-authoring.md +1 -1
  13. package/okf/okf-mcp/workflows/producer-publication.md +28 -0
  14. package/okf.project.yaml +1 -1
  15. package/package.json +2 -2
  16. package/server.json +11 -3
  17. package/src/authoring.js +47 -11
  18. package/src/cli.js +46 -4
  19. package/src/graph.js +2 -2
  20. package/src/index.js +2 -0
  21. package/src/indexer.js +166 -8
  22. package/src/live-authoring.js +132 -50
  23. package/src/mcp-server.js +189 -13
  24. package/src/producer-publisher.js +462 -0
  25. package/src/producers.js +507 -0
  26. package/src/project.js +65 -0
  27. package/src/search.js +19 -0
  28. package/src/store.js +1 -0
  29. /package/okf/{bundles/okf-mcp → okf-mcp}/interfaces/http-authoring-api.md +0 -0
  30. /package/okf/{bundles/okf-mcp → okf-mcp}/runtime/indexer.md +0 -0
  31. /package/okf/{bundles/okf-mcp → okf-mcp}/specs/attested-computation.md +0 -0
  32. /package/okf/{bundles/okf-mcp → okf-mcp}/specs/git-sources.md +0 -0
  33. /package/okf/{bundles/okf-mcp → okf-mcp}/workflows/concept-update.md +0 -0
  34. /package/okf/{bundles/okf-mcp → okf-mcp}/workflows/v02-migration.md +0 -0
@@ -8,6 +8,7 @@ const { isDeepStrictEqual } = require("node:util");
8
8
 
9
9
  const {
10
10
  deriveConceptPathSuggestion,
11
+ isConfiguredGeneratorOutput,
11
12
  normalizeConceptPath,
12
13
  renderConceptMarkdown,
13
14
  } = require("./authoring");
@@ -15,6 +16,10 @@ const {
15
16
  attachProject,
16
17
  buildIndex,
17
18
  bundleAllowsPath,
19
+ conceptIsGeneratedFile,
20
+ conceptMatchSummary,
21
+ normalizeConceptTitle,
22
+ recoverConceptLocator,
18
23
  resolveConcept,
19
24
  validateIndex,
20
25
  } = require("./indexer");
@@ -43,9 +48,11 @@ const MANAGED_METADATA_KEYS = new Set([
43
48
  ]);
44
49
 
45
50
  class AuthoringPolicyError extends Error {
46
- constructor(message) {
51
+ constructor(message, code, details) {
47
52
  super(message);
48
53
  this.name = "AuthoringPolicyError";
54
+ if (code) this.code = code;
55
+ if (details !== undefined) this.details = details;
49
56
  }
50
57
  }
51
58
 
@@ -339,11 +346,6 @@ function actorValue(value) {
339
346
  return actor;
340
347
  }
341
348
 
342
- function isInside(root, candidate) {
343
- const relative = path.relative(path.resolve(root), path.resolve(candidate));
344
- return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
345
- }
346
-
347
349
  function generatedOwners(document) {
348
350
  const owners = [];
349
351
  const generated = document && document.frontmatter && document.frontmatter.generated;
@@ -383,18 +385,37 @@ function sortedUnique(values) {
383
385
  return Array.from(new Set(values)).sort();
384
386
  }
385
387
 
386
- function boundedEffectList(values) {
387
- const normalized = sortedUnique(values).map((value) => {
388
- const text = String(value);
389
- return text.length > MAX_EFFECT_TEXT ? `${text.slice(0, MAX_EFFECT_TEXT - 1)}…` : text;
390
- });
388
+ function boundedEffectList(values, project) {
389
+ const normalized = project
390
+ ? values.map(project)
391
+ : sortedUnique(values).map(boundedEffectText);
391
392
  return {
392
393
  values: normalized.slice(0, MAX_EFFECT_ITEMS),
393
394
  omitted: Math.max(0, normalized.length - MAX_EFFECT_ITEMS),
394
395
  };
395
396
  }
396
397
 
397
- function collectionEffects(before, after, identity) {
398
+ function boundedEffectText(value) {
399
+ const text = String(value || "");
400
+ return text.length > MAX_EFFECT_TEXT ? `${text.slice(0, MAX_EFFECT_TEXT - 1)}…` : text;
401
+ }
402
+
403
+ function relationEffectValue(value) {
404
+ const parts = relationParts(value);
405
+ const result = {
406
+ type: boundedEffectText(parts.type),
407
+ target: boundedEffectText(parts.target),
408
+ };
409
+ if (isPlainObject(value) && hasOwn(value, "label")) {
410
+ result.label = boundedEffectText(value.label);
411
+ }
412
+ if (isPlainObject(value) && hasOwn(value, "description")) {
413
+ result.description = boundedEffectText(value.description);
414
+ }
415
+ return result;
416
+ }
417
+
418
+ function collectionEffects(before, after, identity, project) {
398
419
  const previous = new Map((before || []).map((value) => [identity(value), value]));
399
420
  const next = new Map((after || []).map((value) => [identity(value), value]));
400
421
  const added = Array.from(next.keys()).filter((key) => !previous.has(key)).sort();
@@ -402,10 +423,14 @@ function collectionEffects(before, after, identity) {
402
423
  const updated = Array.from(next.keys()).filter((key) => (
403
424
  previous.has(key) && !isDeepStrictEqual(previous.get(key), next.get(key))
404
425
  )).sort();
426
+ const effectList = (keys, values) => boundedEffectList(
427
+ project ? keys.map((key) => values.get(key)) : keys,
428
+ project,
429
+ );
405
430
  return {
406
- added: boundedEffectList(added),
407
- removed: boundedEffectList(removed),
408
- updated: boundedEffectList(updated),
431
+ added: effectList(added, next),
432
+ removed: effectList(removed, previous),
433
+ updated: effectList(updated, next),
409
434
  };
410
435
  }
411
436
 
@@ -424,7 +449,7 @@ function effectsForCandidate(candidate) {
424
449
  const after = candidate.frontmatter;
425
450
  const tags = collectionEffects(before.tags, after.tags, (value) => String(value));
426
451
  const sources = collectionEffects(before.sources, after.sources, sourceIdentity);
427
- const relations = collectionEffects(before.relations, after.relations, relationKey);
452
+ const relations = collectionEffects(before.relations, after.relations, relationKey, relationEffectValue);
428
453
  const metadata = metadataEffects(before, after);
429
454
  const bodyChanged = candidate.op === "create"
430
455
  ? true
@@ -436,7 +461,6 @@ function effectsForCandidate(candidate) {
436
461
  if (hasEffect(sources.added) || hasEffect(sources.removed) || hasEffect(sources.updated)) changedFields.push("sources");
437
462
  if (hasEffect(relations.added) || hasEffect(relations.removed) || hasEffect(relations.updated)) changedFields.push("relations");
438
463
  if (hasEffect(metadata.set) || hasEffect(metadata.removed)) changedFields.push("metadata");
439
- if (!isDeepStrictEqual(before.generated, after.generated)) changedFields.push("generated");
440
464
  return {
441
465
  changedFields,
442
466
  bodyChanged,
@@ -451,6 +475,47 @@ function effectsForCandidate(candidate) {
451
475
  };
452
476
  }
453
477
 
478
+ function semanticConceptKey(type, title) {
479
+ return `${String(type || "")}\u0000${normalizeConceptTitle(title)}`;
480
+ }
481
+
482
+ function conceptIsManaged(doc, project) {
483
+ return conceptIsGeneratedFile(doc)
484
+ || generatedOwners(doc).some((owner) => owner.startsWith("process:"))
485
+ || isConfiguredGeneratorOutput(project, doc && doc.absolutePath);
486
+ }
487
+
488
+ function conceptConflictDetails(matches, project) {
489
+ const candidates = matches.slice(0, 5).map((doc) => conceptMatchSummary(doc));
490
+ const only = candidates.length === 1 ? candidates[0] : null;
491
+ const generated = matches.length === 1 && conceptIsManaged(matches[0], project);
492
+ const updateable = only && !generated && only.type !== "Attested Computation";
493
+ return {
494
+ reason: "same_type_title",
495
+ candidates,
496
+ omitted: Math.max(0, matches.length - candidates.length),
497
+ recommendedOperation: updateable ? "update" : generated ? "change_generator" : "review",
498
+ ...(updateable ? { retryWith: { op: "update", uri: only.uri } } : {}),
499
+ };
500
+ }
501
+
502
+ function staleUpdateDetails(index, uri, bundle, project) {
503
+ const recovery = recoverConceptLocator(index, uri, { bundle, limit: 5 });
504
+ const only = recovery.candidates.length === 1 ? recovery.candidates[0] : null;
505
+ const matched = only && resolveConcept(index, only.uri);
506
+ if (only && (conceptIsManaged(matched, project)
507
+ || only.type === "Attested Computation")) {
508
+ delete recovery.retryWith;
509
+ recovery.recommendedOperation = only.type === "Attested Computation"
510
+ ? "review_computation_owner"
511
+ : "change_generator";
512
+ } else if (recovery.retryWith) {
513
+ recovery.retryWith.op = "update";
514
+ recovery.recommendedOperation = "update";
515
+ }
516
+ return { recovery };
517
+ }
518
+
454
519
  function policyCode(message) {
455
520
  const text = String(message || "");
456
521
  if (/generated|generator/i.test(text)) return "generated_owner_protected";
@@ -473,19 +538,23 @@ function policyCode(message) {
473
538
  return "authoring_policy_rejected";
474
539
  }
475
540
 
476
- function policyValidation(message) {
477
- const code = policyCode(message);
541
+ function policyValidation(error) {
542
+ const message = error && error.message ? error.message : String(error);
543
+ const code = error && error.code || policyCode(message);
544
+ const details = error && error.details;
545
+ const diagnostic = {
546
+ code,
547
+ severity: "error",
548
+ layer: "authoring",
549
+ message,
550
+ ...(details !== undefined ? { details } : {}),
551
+ };
478
552
  return {
479
553
  valid: false,
480
554
  conformant: false,
481
555
  validForProject: false,
482
- diagnostics: [{
483
- code,
484
- severity: "error",
485
- layer: "authoring",
486
- message,
487
- }],
488
- errors: [{ code, message }],
556
+ diagnostics: [diagnostic],
557
+ errors: [{ code, message, ...(details !== undefined ? { details } : {}) }],
489
558
  warnings: [],
490
559
  };
491
560
  }
@@ -547,32 +616,13 @@ class LiveAuthoringService {
547
616
  return this.store.project ? attachProject(index, this.store.project) : index;
548
617
  }
549
618
 
550
- generatedOutputDirectories() {
551
- const project = this.store.project;
552
- if (!project || !project.root) {
553
- return [];
554
- }
555
- return (project.plugins || [])
556
- .filter((plugin) => plugin && plugin.output)
557
- .map((plugin) => path.resolve(project.root, String(plugin.output)));
558
- }
559
-
560
619
  assertWritableTarget(bundle, conceptPath, existing) {
561
620
  const target = this.store.resolveConceptFile(bundle.id, conceptPath);
562
- if (this.generatedOutputDirectories().some((output) => isInside(output, target.absolutePath))) {
621
+ if (isConfiguredGeneratorOutput(this.store.project, target.absolutePath)) {
563
622
  throw new Error(`Concept is inside a configured generator output and must be changed through its generator: ${conceptPath}`);
564
623
  }
565
- if (existing) {
566
- const frontmatter = existing.frontmatter || {};
567
- if (existing.generatedFile === true
568
- || existing.isGenerated === true
569
- || frontmatter.generated_file === true
570
- || frontmatter.generatedFile === true) {
571
- throw new Error(`Generated concept must be changed through its generator: ${existing.uri}`);
572
- }
573
- if (generatedOwners(existing).some((owner) => owner.startsWith("process:"))) {
574
- throw new Error(`Process-generated concept must be changed through its generator: ${existing.uri}`);
575
- }
624
+ if (existing && conceptIsManaged(existing, this.store.project)) {
625
+ throw new Error(`Generated concept must be changed through its generator: ${existing.uri}`);
576
626
  }
577
627
  return target;
578
628
  }
@@ -636,7 +686,12 @@ class LiveAuthoringService {
636
686
  const uri = nonEmptyString(change.uri, "changes[].uri");
637
687
  const existing = resolveConcept(currentIndex, uri);
638
688
  if (!existing || !existing.valid || existing.reserved) {
639
- throw new Error(`Unknown valid OKF concept: ${uri}`);
689
+ const details = staleUpdateDetails(currentIndex, uri, bundle.id, this.store.project);
690
+ throw new AuthoringPolicyError(
691
+ `Unknown valid OKF concept: ${uri}`,
692
+ details.recovery.status === "ambiguous" ? "concept_locator_ambiguous" : "concept_not_found",
693
+ details,
694
+ );
640
695
  }
641
696
  if (existing.bundle !== bundle.id) {
642
697
  throw new Error(`All changes must target writable bundle ${bundle.id}: ${uri}`);
@@ -1940,6 +1995,31 @@ class LiveAuthoringService {
1940
1995
  }
1941
1996
  }
1942
1997
  }
1998
+ const currentConcepts = currentIndex.concepts.filter((doc) => doc.bundle === bundle.id);
1999
+ const replacedPaths = new Set(candidates.filter((entry) => entry.op === "update").map((entry) => entry.path));
2000
+ const finalConcepts = currentConcepts.filter((doc) => !replacedPaths.has(doc.path)).concat(candidates);
2001
+ for (const candidate of candidates) {
2002
+ const key = semanticConceptKey(candidate.frontmatter.type, candidate.title);
2003
+ const before = currentConcepts.filter((doc) => semanticConceptKey(doc.type, doc.title) === key);
2004
+ const after = finalConcepts.filter((doc) => (
2005
+ semanticConceptKey(doc.type || doc.frontmatter.type, doc.title) === key
2006
+ ));
2007
+ if (after.length <= Math.max(1, before.length)) continue;
2008
+ const existing = after.filter((doc) => !candidates.includes(doc));
2009
+ const details = candidate.op === "create" && existing.length === 1 && after.length === 2
2010
+ ? conceptConflictDetails(existing, this.store.project)
2011
+ : {
2012
+ reason: before.length ? "same_type_title" : "same_batch_type_title",
2013
+ candidates: after.slice(0, 5).map((doc) => conceptMatchSummary(doc)),
2014
+ omitted: Math.max(0, after.length - 5),
2015
+ recommendedOperation: "merge_batch_changes",
2016
+ };
2017
+ throw new AuthoringPolicyError(
2018
+ `The batch would leave more than one ${candidate.frontmatter.type} titled "${candidate.title}".`,
2019
+ "concept_already_exists",
2020
+ details,
2021
+ );
2022
+ }
1943
2023
  const message = this.commitMessage(input, candidates);
1944
2024
  const overrides = new Map(candidates.map((candidate) => [
1945
2025
  `${candidate.bundle}\u0000${candidate.path}`,
@@ -1998,7 +2078,7 @@ class LiveAuthoringService {
1998
2078
  }
1999
2079
 
2000
2080
  invalidValidationReceipt(error) {
2001
- const validation = policyValidation(error && error.message ? error.message : String(error));
2081
+ const validation = policyValidation(error);
2002
2082
  const generated = this.generatedStamp();
2003
2083
  return {
2004
2084
  valid: false,
@@ -2027,6 +2107,8 @@ class LiveAuthoringService {
2027
2107
  durability: this.durabilityReceipt(null, false),
2028
2108
  changes: [],
2029
2109
  validation,
2110
+ ...(error && error.code ? { code: error.code } : {}),
2111
+ ...(error && error.details !== undefined ? { details: error.details } : {}),
2030
2112
  git: {
2031
2113
  enabled: this.gitCommit,
2032
2114
  repository: false,