@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
package/src/mcp-server.js CHANGED
@@ -1,5 +1,6 @@
1
1
  "use strict";
2
2
 
3
+ const fs = require("node:fs");
3
4
  const path = require("path");
4
5
  const {
5
6
  McpServer,
@@ -14,6 +15,7 @@ const {
14
15
  conceptSignals,
15
16
  conceptSummary,
16
17
  loadProjectBundles,
18
+ recoverConceptLocator,
17
19
  resolveConcept,
18
20
  validateIndex,
19
21
  } = require("./indexer");
@@ -29,6 +31,7 @@ const {
29
31
  } = require("./live-authoring");
30
32
  const { FileConceptStore } = require("./store");
31
33
  const { loadProjectConfig } = require("./project");
34
+ const { ProducerService, producerReceipt } = require("./producers");
32
35
  const {
33
36
  checkComputationReceipt,
34
37
  getProvenance,
@@ -79,6 +82,18 @@ const REMOTE_LOAD = {
79
82
  idempotentHint: false,
80
83
  openWorldHint: true,
81
84
  };
85
+ const PRODUCER_PREVIEW = {
86
+ readOnlyHint: true,
87
+ destructiveHint: false,
88
+ idempotentHint: true,
89
+ openWorldHint: true,
90
+ };
91
+ const PRODUCER_RUN = {
92
+ readOnlyHint: false,
93
+ destructiveHint: true,
94
+ idempotentHint: false,
95
+ openWorldHint: true,
96
+ };
82
97
 
83
98
  function stringParameter(description, extra) {
84
99
  return Object.assign({ type: "string", description }, extra || {});
@@ -127,6 +142,10 @@ function objectParameter(description, extra) {
127
142
  }, extra || {});
128
143
  }
129
144
 
145
+ function detailParameter(description) {
146
+ return stringParameter(description, { enum: ["compact", "full"], default: "compact" });
147
+ }
148
+
130
149
  function relationParameter(description) {
131
150
  return {
132
151
  type: "object",
@@ -227,6 +246,7 @@ const LIVE_CHANGES_DESCRIPTION = [
227
246
 
228
247
  const LIVE_CHANGE_TOOL_PROPERTIES = {
229
248
  bundle: nonEmptyStringParameter("Writable bundle id; optional when exactly one local root is configured."),
249
+ detail: detailParameter("Receipt detail level; compact removes repeated planning fields while full preserves the v0.7 receipt layout."),
230
250
  message: stringParameter("Optional Git commit summary when automatic commits are enabled.", {
231
251
  maxLength: MAX_COMMIT_MESSAGE_BYTES,
232
252
  }),
@@ -244,10 +264,11 @@ const LIVE_CHANGE_EFFECTS_OUTPUT = {
244
264
  description: "Compact structured summary of the fields changed by this operation.",
245
265
  additionalProperties: true,
246
266
  properties: {
267
+ changedFields: stringArrayParameter("Substantive concept fields changed, excluding server-managed generation provenance."),
247
268
  bodyChanged: optionalBooleanParameter("Whether the Markdown body changed."),
248
269
  tags: objectParameter("Tags added and removed by the operation."),
249
270
  sources: objectParameter("Sources added and removed by the operation."),
250
- relations: objectParameter("Relations added and removed by the operation."),
271
+ relations: objectParameter("Added, removed, and updated relation values as structured { type, target, label?, description? } objects."),
251
272
  metadata: objectParameter("Metadata fields set and removed by the operation."),
252
273
  },
253
274
  };
@@ -263,6 +284,11 @@ const LIVE_CHANGE_SUMMARY_OUTPUT = {
263
284
  absolutePath: stringParameter("Absolute target concept filename."),
264
285
  uri: stringParameter("Canonical concept URI."),
265
286
  title: stringParameter("Resulting concept title."),
287
+ baseRevision: {
288
+ description: "Source revision before the operation; null for creates.",
289
+ oneOf: [{ type: "string" }, { type: "null" }],
290
+ },
291
+ candidateRevision: stringParameter("Revision of the validated candidate bytes."),
266
292
  effects: LIVE_CHANGE_EFFECTS_OUTPUT,
267
293
  },
268
294
  };
@@ -271,8 +297,8 @@ const LIVE_CHANGE_OUTPUT_PROPERTIES = {
271
297
  status: stringParameter("Validation or application outcome."),
272
298
  readyToApply: optionalBooleanParameter("Whether policy, graph, revision, and configured Git preconditions currently allow apply."),
273
299
  filesChanged: optionalBooleanParameter("Whether filesystem changes remain when the request returns."),
274
- snapshot: objectParameter("Time-of-check metadata for this planning result."),
275
- preconditions: objectParameter("Revision and Git preconditions checked for the batch."),
300
+ snapshot: objectParameter("Full-receipt time-of-check metadata for this planning result."),
301
+ preconditions: objectParameter("Full-receipt revision and Git preconditions checked for the batch."),
276
302
  generated: objectParameter("Server-owned generation actor and timestamp."),
277
303
  target: objectParameter("Absolute bundle, repository, and affected-file locations."),
278
304
  durability: objectParameter("Working-tree and automatic-commit durability state."),
@@ -331,6 +357,7 @@ const TOOL_DEFINITIONS = {
331
357
  bundle: nonEmptyStringParameter("Limit results to this bundle id."),
332
358
  type: nonEmptyStringParameter("Limit results to this exact concept type."),
333
359
  tag: nonEmptyStringParameter("Limit results to concepts containing this tag."),
360
+ detail: detailParameter("Compact returns only URI, title, type, and description; full includes navigation metadata and signals."),
334
361
  limit: integerParameter("Maximum number of concepts to return.", 1, 250, 25),
335
362
  offset: integerParameter("Number of matching concepts to skip before returning results.", 0, undefined, 0),
336
363
  },
@@ -377,6 +404,7 @@ const TOOL_DEFINITIONS = {
377
404
  attestationReady: optionalBooleanParameter("Require static Attested Computation readiness."),
378
405
  generatedBy: nonEmptyStringParameter("Limit results to this generator actor."),
379
406
  verifiedBy: nonEmptyStringParameter("Limit results to concepts verified by this actor."),
407
+ detail: detailParameter("Compact returns only URI, title, type, and description; full includes ranking, navigation metadata, and signals."),
380
408
  limit: integerParameter("Maximum number of concepts to return.", 1, 250, 25),
381
409
  offset: integerParameter("Number of matching concepts to skip before returning results.", 0, undefined, 0),
382
410
  },
@@ -616,6 +644,28 @@ const TOOL_DEFINITIONS = {
616
644
  undefined,
617
645
  LIVE_APPLY_OUTPUT,
618
646
  ),
647
+ okf_list_producers: defineTool(
648
+ "List configured producer instances without loading or executing their packages.",
649
+ READ_ONLY,
650
+ ),
651
+ okf_preview_producer: defineTool(
652
+ "Read source metadata, generate a candidate OKF 0.2 bundle, and validate its publication diff without writing files.",
653
+ PRODUCER_PREVIEW,
654
+ {
655
+ producer: nonEmptyStringParameter("Configured producer instance name."),
656
+ detail: detailParameter("Receipt detail level; full includes bounded bundle-relative changed paths."),
657
+ },
658
+ ["producer"],
659
+ ),
660
+ okf_run_producer: defineTool(
661
+ "Regenerate, strictly validate, safely publish, and reindex one configured OKF producer.",
662
+ PRODUCER_RUN,
663
+ {
664
+ producer: nonEmptyStringParameter("Configured producer instance name."),
665
+ detail: detailParameter("Receipt detail level; full includes bounded bundle-relative changed paths."),
666
+ },
667
+ ["producer"],
668
+ ),
619
669
  get_graph: defineTool(
620
670
  "Return a bounded set of OKF graph nodes and edges with optional concept filters.",
621
671
  READ_ONLY,
@@ -724,6 +774,13 @@ const LIVE_WRITE_TOOL_NAMES = new Set([
724
774
  const RUNTIME_REMOTE_TOOL_NAMES = new Set([
725
775
  "load_remote_bundle",
726
776
  ]);
777
+ const PRODUCER_TOOL_NAMES = new Set([
778
+ "okf_list_producers",
779
+ "okf_preview_producer",
780
+ ]);
781
+ const PRODUCER_WRITE_TOOL_NAMES = new Set([
782
+ "okf_run_producer",
783
+ ]);
727
784
 
728
785
  function jsonContent(value, options) {
729
786
  const result = {
@@ -743,7 +800,53 @@ function jsonContent(value, options) {
743
800
  return result;
744
801
  }
745
802
 
803
+ function liveRequest(args) {
804
+ const input = Object.assign({}, args || {});
805
+ const detail = input.detail || "compact";
806
+ delete input.detail;
807
+ return { input, detail };
808
+ }
809
+
810
+ function projectLiveReceipt(receipt, detail) {
811
+ if (detail === "full") return receipt;
812
+ const compact = structuredClone(receipt);
813
+ const preconditionGit = compact.preconditions && compact.preconditions.git;
814
+ if (preconditionGit || compact.git) {
815
+ compact.git = Object.assign({}, preconditionGit || {}, compact.git || {});
816
+ }
817
+ delete compact.snapshot;
818
+ delete compact.preconditions;
819
+ if (compact.target) delete compact.target.absolutePaths;
820
+ if (compact.durability) delete compact.durability.filesChanged;
821
+ (compact.changes || []).forEach((change) => {
822
+ delete change.bundle;
823
+ const effects = change.effects;
824
+ if (!effects) return;
825
+ ["beforeRevision", "afterRevision", "bytesBefore", "bytesAfter"].forEach((key) => delete effects[key]);
826
+ if (effects.bodyChanged === false) delete effects.bodyChanged;
827
+ ["tags", "sources", "relations", "metadata"].forEach((name) => {
828
+ const group = effects[name];
829
+ if (!group) return;
830
+ Object.keys(group).forEach((key) => {
831
+ const list = group[key];
832
+ if (!list || !Array.isArray(list.values)) return;
833
+ if (!list.omitted) delete list.omitted;
834
+ if (!list.values.length && !list.omitted) delete group[key];
835
+ });
836
+ if (!Object.keys(group).length) delete effects[name];
837
+ });
838
+ });
839
+ return compact;
840
+ }
841
+
842
+
746
843
  function toolEnabled(state, name) {
844
+ if (PRODUCER_TOOL_NAMES.has(name)) {
845
+ return Boolean(state && state.producerService);
846
+ }
847
+ if (PRODUCER_WRITE_TOOL_NAMES.has(name)) {
848
+ return Boolean(state && state.producerService && state.allowWrite && state.actor);
849
+ }
747
850
  if (PROJECT_HELPER_TOOL_NAMES.has(name)) {
748
851
  return Boolean(state && state.authoringService);
749
852
  }
@@ -850,7 +953,7 @@ function readResource(index, uri) {
850
953
  }
851
954
 
852
955
  function listConcepts(index, args) {
853
- const options = Object.assign({}, args || {});
956
+ const options = Object.assign({ detail: "compact" }, args || {});
854
957
  if (options.type && !options.types) {
855
958
  options.types = [options.type];
856
959
  }
@@ -860,15 +963,27 @@ function listConcepts(index, args) {
860
963
  return searchConcepts(index, options);
861
964
  }
862
965
 
863
- function getConcept(index, args, repositoryMappings) {
864
- const locator = args && (args.id || args.uri)
966
+ function conceptLocator(args) {
967
+ return args && (args.id || args.uri)
865
968
  ? (args.id || args.uri)
866
969
  : args && args.bundle && args.path
867
970
  ? `okf://${args.bundle}/${args.path}`
868
971
  : null;
972
+ }
973
+
974
+ function getConcept(index, args, repositoryMappings) {
975
+ const locator = conceptLocator(args);
869
976
  const doc = resolveConcept(index, locator);
870
977
  if (!doc) {
871
- throw new ToolExecutionError(`Unknown OKF concept URI or ID: ${locator || "<missing>"}`);
978
+ const recovery = recoverConceptLocator(index, locator, {
979
+ bundle: args && args.bundle,
980
+ limit: 5,
981
+ });
982
+ throw new ToolExecutionError(
983
+ `Unknown OKF concept URI or ID: ${locator || "<missing>"}`,
984
+ recovery.status === "ambiguous" ? "concept_locator_ambiguous" : "concept_not_found",
985
+ { recovery },
986
+ );
872
987
  }
873
988
  if (!doc.valid || doc.reserved) {
874
989
  throw new ToolExecutionError(`Locator is not a valid OKF concept: ${locator}`);
@@ -893,6 +1008,18 @@ function getConcept(index, args, repositoryMappings) {
893
1008
  });
894
1009
  }
895
1010
 
1011
+ function conceptIndexIsStale(index, args) {
1012
+ const doc = resolveConcept(index, conceptLocator(args));
1013
+ if (!doc) return true;
1014
+ const bundle = (index.bundles || []).find((entry) => entry.id === doc.bundle);
1015
+ if (!bundle || bundle.remote) return false;
1016
+ try {
1017
+ return !fs.lstatSync(doc.absolutePath).isFile();
1018
+ } catch (_error) {
1019
+ return true;
1020
+ }
1021
+ }
1022
+
896
1023
  function listTypes(index) {
897
1024
  const counts = {};
898
1025
  index.concepts.forEach((doc) => {
@@ -999,10 +1126,11 @@ async function callTool(state, name, args) {
999
1126
  case "list_concepts":
1000
1127
  return jsonContent(listConcepts(index, args));
1001
1128
  case "get_concept":
1002
- return jsonContent(getConcept(index, args, state.repositoryMappings));
1129
+ if (conceptIndexIsStale(index, args)) rebuildStateIndex(state);
1130
+ return jsonContent(getConcept(state.index, args, state.repositoryMappings));
1003
1131
  case "search_concepts":
1004
1132
  return jsonContent(await expectedToolOperation(
1005
- () => searchConcepts(index, args),
1133
+ () => searchConcepts(index, Object.assign({ detail: "compact" }, args)),
1006
1134
  { translateTypeError: true },
1007
1135
  ));
1008
1136
  case "list_types":
@@ -1145,8 +1273,9 @@ async function callTool(state, name, args) {
1145
1273
  () => requireAuthoring(state).rejectProposal(args),
1146
1274
  ));
1147
1275
  case "okf_validate_changes": {
1276
+ const request = liveRequest(args);
1148
1277
  const result = await expectedToolOperation(
1149
- () => requireLiveAuthoring(state).validateChanges(args, {
1278
+ () => requireLiveAuthoring(state).validateChanges(request.input, {
1150
1279
  additionalBundles: state.remoteBundles,
1151
1280
  }),
1152
1281
  { translateTypeError: true },
@@ -1154,11 +1283,12 @@ async function callTool(state, name, args) {
1154
1283
  if (result.applied || result.filesChanged) {
1155
1284
  rebuildStateIndex(state);
1156
1285
  }
1157
- return jsonContent(result, { structured: true });
1286
+ return jsonContent(projectLiveReceipt(result, request.detail), { structured: true });
1158
1287
  }
1159
1288
  case "okf_apply_changes": {
1289
+ const request = liveRequest(args);
1160
1290
  const result = await expectedToolOperation(
1161
- () => requireLiveAuthoring(state).applyChanges(args, {
1291
+ () => requireLiveAuthoring(state).applyChanges(request.input, {
1162
1292
  additionalBundles: state.remoteBundles,
1163
1293
  }),
1164
1294
  { translateTypeError: true },
@@ -1166,7 +1296,31 @@ async function callTool(state, name, args) {
1166
1296
  if (result.applied || result.filesChanged) {
1167
1297
  rebuildStateIndex(state);
1168
1298
  }
1169
- return jsonContent(result, {
1299
+ return jsonContent(projectLiveReceipt(result, request.detail), {
1300
+ structured: true,
1301
+ isError: result.applied === false,
1302
+ });
1303
+ }
1304
+ case "okf_list_producers":
1305
+ return jsonContent(state.producerService.list(), { structured: true });
1306
+ case "okf_preview_producer": {
1307
+ const result = await expectedToolOperation(
1308
+ () => state.producerService.preview(args.producer, {
1309
+ additionalBundles: state.remoteBundles,
1310
+ }),
1311
+ { translateTypeError: true },
1312
+ );
1313
+ return jsonContent(producerReceipt(result, args.detail || "compact"), { structured: true });
1314
+ }
1315
+ case "okf_run_producer": {
1316
+ const result = await expectedToolOperation(
1317
+ () => state.producerService.run(args.producer, {
1318
+ additionalBundles: state.remoteBundles,
1319
+ }),
1320
+ { translateTypeError: true },
1321
+ );
1322
+ if (result.applied) rebuildStateIndex(state);
1323
+ return jsonContent(producerReceipt(result, args.detail || "compact"), {
1170
1324
  structured: true,
1171
1325
  isError: result.applied === false,
1172
1326
  });
@@ -1257,7 +1411,9 @@ function createState(bundleArgs, options) {
1257
1411
  project,
1258
1412
  authoringService,
1259
1413
  liveAuthoringService: options && options.liveAuthoringService,
1414
+ producerService: options && options.producerService,
1260
1415
  allowWrite: Boolean(options && options.allowWrite),
1416
+ actor: options && options.actor,
1261
1417
  allowAuthoring: Boolean(options && options.allowAuthoring),
1262
1418
  allowRuntimeRemoteLoad: Boolean(options && options.allowRuntimeRemoteLoad),
1263
1419
  allowComputationAuthoring: Boolean(options && options.allowComputationAuthoring),
@@ -1265,6 +1421,17 @@ function createState(bundleArgs, options) {
1265
1421
  allowCustomRelationTypes,
1266
1422
  repositoryMappings: (options && options.repositoryMappings) || new Map(),
1267
1423
  };
1424
+ if (!state.producerService && project && (project.producers || []).length
1425
+ && authoringService && authoringService.store) {
1426
+ state.producerService = new ProducerService({
1427
+ project,
1428
+ store: authoringService.store,
1429
+ bundles: localBundleArgs,
1430
+ loader: options && options.producerLoader,
1431
+ env: options && options.producerEnv,
1432
+ now: options && options.producerNow,
1433
+ });
1434
+ }
1268
1435
  return state;
1269
1436
  }
1270
1437
 
@@ -1292,7 +1459,12 @@ async function createStateAsync(bundleArgs, options) {
1292
1459
  relationTypes: loaded.project.relationTypes,
1293
1460
  authoringService,
1294
1461
  liveAuthoringService,
1462
+ producerService: options.producerService,
1463
+ producerLoader: options.producerLoader,
1464
+ producerEnv: options.producerEnv,
1465
+ producerNow: options.producerNow,
1295
1466
  allowWrite: options.allowWrite,
1467
+ actor: options.actor,
1296
1468
  allowAuthoring: options.allowAuthoring,
1297
1469
  allowRuntimeRemoteLoad: options.allowRuntimeRemoteLoad,
1298
1470
  allowComputationAuthoring: options.allowComputationAuthoring,
@@ -1322,7 +1494,9 @@ async function createStateAsync(bundleArgs, options) {
1322
1494
  relationTypes: store.getRelationTypes(),
1323
1495
  authoringService,
1324
1496
  liveAuthoringService,
1497
+ producerService: options.producerService,
1325
1498
  allowWrite: options.allowWrite,
1499
+ actor: options.actor,
1326
1500
  allowAuthoring: options.allowAuthoring,
1327
1501
  allowRuntimeRemoteLoad: options.allowRuntimeRemoteLoad,
1328
1502
  allowComputationAuthoring: options.allowComputationAuthoring,
@@ -1352,7 +1526,9 @@ async function createStateAsync(bundleArgs, options) {
1352
1526
  initialRemoteBundles: remoteBundles,
1353
1527
  authoringService: options && options.authoringService,
1354
1528
  liveAuthoringService,
1529
+ producerService: options && options.producerService,
1355
1530
  allowWrite: options && options.allowWrite,
1531
+ actor: options && options.actor,
1356
1532
  allowAuthoring: options && options.allowAuthoring,
1357
1533
  allowRuntimeRemoteLoad: options && options.allowRuntimeRemoteLoad,
1358
1534
  allowComputationAuthoring: options && options.allowComputationAuthoring,