@mfdaves/okf-mcp 0.6.0 → 0.7.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.
package/src/mcp-server.js CHANGED
@@ -22,7 +22,11 @@ const { MAX_QUERY_CHARACTERS, MAX_QUERY_TERMS } = require("./search-index");
22
22
  const { exportGraph, findPaths, getGraph, getNeighbors, getSubgraph, graphSummary } = require("./graph");
23
23
  const { fetchGitHubBundle, fetchRemoteBundles, sanitizeRemoteId } = require("./remote");
24
24
  const { ConceptAuthoringService } = require("./authoring");
25
- const { LiveAuthoringService, MAX_CHANGES } = require("./live-authoring");
25
+ const {
26
+ LiveAuthoringService,
27
+ MAX_CHANGES,
28
+ MAX_COMMIT_MESSAGE_BYTES,
29
+ } = require("./live-authoring");
26
30
  const { FileConceptStore } = require("./store");
27
31
  const { loadProjectConfig } = require("./project");
28
32
  const {
@@ -39,9 +43,15 @@ const packageMetadata = require("../package.json");
39
43
  const MAX_MCP_MESSAGE_BYTES = 1024 * 1024;
40
44
 
41
45
  class ToolExecutionError extends Error {
42
- constructor(message) {
46
+ constructor(message, code, details) {
43
47
  super(message);
44
48
  this.name = "ToolExecutionError";
49
+ if (typeof code === "string" && code) {
50
+ this.code = code;
51
+ }
52
+ if (details !== undefined) {
53
+ this.details = details;
54
+ }
45
55
  }
46
56
  }
47
57
 
@@ -147,11 +157,11 @@ function collectionPatchParameter(description, item) {
147
157
  type: "object",
148
158
  description,
149
159
  additionalProperties: false,
160
+ minProperties: 1,
150
161
  properties: {
151
162
  add: { type: "array", items: item },
152
163
  remove: { type: "array", items: item },
153
164
  },
154
- anyOf: [{ required: ["add"] }, { required: ["remove"] }],
155
165
  };
156
166
  }
157
167
 
@@ -184,6 +194,7 @@ const LIVE_CREATE_CHANGE = {
184
194
  const LIVE_UPDATE_CHANGE = {
185
195
  type: "object",
186
196
  additionalProperties: false,
197
+ minProperties: 3,
187
198
  properties: {
188
199
  op: { type: "string", const: "update", description: "Update an existing concept in place." },
189
200
  uri: nonEmptyStringParameter("Canonical or compatible URI of the existing concept."),
@@ -206,19 +217,93 @@ const LIVE_UPDATE_CHANGE = {
206
217
  removeMetadataKeys: stringArrayParameter("Extension frontmatter keys to remove; managed fields are rejected.", { nonEmptyItems: true }),
207
218
  },
208
219
  required: ["op", "uri"],
209
- anyOf: [
210
- { required: ["title"] },
211
- { required: ["description"] },
212
- { required: ["body"] },
213
- { required: ["tags"] },
214
- { required: ["sources"] },
215
- { required: ["relations"] },
216
- { required: ["metadata"] },
217
- { required: ["removeMetadataKeys"] },
218
- ],
219
220
  };
220
221
 
221
- function defineTool(description, annotations, properties, required, schemaExtras) {
222
+ const LIVE_CHANGES_DESCRIPTION = [
223
+ `One through ${MAX_CHANGES} concept create or update operations handled as one batch.`,
224
+ "Create grammar: { op: 'create', type, title, path?, description?, body?, tags?: string[], sources?: (string | structured source object)[], relations?: { type, target, label?, description? }[], metadata?: object }.",
225
+ "Update grammar: { op: 'update', uri, title?, description?, body?, tags?: { add?: string[], remove?: string[] }, sources?: { add?: (string | source object)[], remove?: (string | { id } | { resource })[] }, relations?: { add?: relation[], remove?: relation[] }, metadata?, removeMetadataKeys? }; relation = { type, target, label?, description? }; include at least one update field.",
226
+ ].join(" ");
227
+
228
+ const LIVE_CHANGE_TOOL_PROPERTIES = {
229
+ bundle: nonEmptyStringParameter("Writable bundle id; optional when exactly one local root is configured."),
230
+ message: stringParameter("Optional Git commit summary when automatic commits are enabled.", {
231
+ maxLength: MAX_COMMIT_MESSAGE_BYTES,
232
+ }),
233
+ changes: {
234
+ type: "array",
235
+ description: LIVE_CHANGES_DESCRIPTION,
236
+ minItems: 1,
237
+ maxItems: MAX_CHANGES,
238
+ items: { oneOf: [LIVE_CREATE_CHANGE, LIVE_UPDATE_CHANGE] },
239
+ },
240
+ };
241
+
242
+ const LIVE_CHANGE_EFFECTS_OUTPUT = {
243
+ type: "object",
244
+ description: "Compact structured summary of the fields changed by this operation.",
245
+ additionalProperties: true,
246
+ properties: {
247
+ bodyChanged: optionalBooleanParameter("Whether the Markdown body changed."),
248
+ tags: objectParameter("Tags added and removed by the operation."),
249
+ sources: objectParameter("Sources added and removed by the operation."),
250
+ relations: objectParameter("Relations added and removed by the operation."),
251
+ metadata: objectParameter("Metadata fields set and removed by the operation."),
252
+ },
253
+ };
254
+
255
+ const LIVE_CHANGE_SUMMARY_OUTPUT = {
256
+ type: "object",
257
+ description: "Compact receipt for one validated or applied concept operation.",
258
+ additionalProperties: true,
259
+ properties: {
260
+ op: stringParameter("Operation kind."),
261
+ bundle: stringParameter("Target bundle id."),
262
+ path: stringParameter("Bundle-relative concept path."),
263
+ absolutePath: stringParameter("Absolute target concept filename."),
264
+ uri: stringParameter("Canonical concept URI."),
265
+ title: stringParameter("Resulting concept title."),
266
+ effects: LIVE_CHANGE_EFFECTS_OUTPUT,
267
+ },
268
+ };
269
+
270
+ const LIVE_CHANGE_OUTPUT_PROPERTIES = {
271
+ status: stringParameter("Validation or application outcome."),
272
+ readyToApply: optionalBooleanParameter("Whether policy, graph, revision, and configured Git preconditions currently allow apply."),
273
+ 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."),
276
+ generated: objectParameter("Server-owned generation actor and timestamp."),
277
+ target: objectParameter("Absolute bundle, repository, and affected-file locations."),
278
+ durability: objectParameter("Working-tree and automatic-commit durability state."),
279
+ changes: {
280
+ type: "array",
281
+ description: "Compact operation receipts.",
282
+ items: LIVE_CHANGE_SUMMARY_OUTPUT,
283
+ },
284
+ validation: objectParameter("Complete future-graph validation result."),
285
+ git: objectParameter("Git policy and commit result."),
286
+ };
287
+
288
+ const LIVE_VALIDATE_OUTPUT = {
289
+ type: "object",
290
+ description: "Read-only validation receipt for a structured concept batch.",
291
+ additionalProperties: true,
292
+ properties: Object.assign({
293
+ valid: optionalBooleanParameter("Whether authoring policy and the complete future graph are valid, independent of transient Git readiness."),
294
+ }, LIVE_CHANGE_OUTPUT_PROPERTIES),
295
+ };
296
+
297
+ const LIVE_APPLY_OUTPUT = {
298
+ type: "object",
299
+ description: "Application, target, durability, and validation receipt for a structured concept batch.",
300
+ additionalProperties: true,
301
+ properties: Object.assign({
302
+ applied: optionalBooleanParameter("Whether the complete batch was applied."),
303
+ }, LIVE_CHANGE_OUTPUT_PROPERTIES),
304
+ };
305
+
306
+ function defineTool(description, annotations, properties, required, schemaExtras, outputSchema) {
222
307
  return {
223
308
  description,
224
309
  annotations,
@@ -229,6 +314,7 @@ function defineTool(description, annotations, properties, required, schemaExtras
229
314
  ...(required && required.length ? { required } : {}),
230
315
  ...(schemaExtras || {}),
231
316
  },
317
+ ...(outputSchema ? { outputSchema } : {}),
232
318
  };
233
319
  }
234
320
 
@@ -514,21 +600,21 @@ const TOOL_DEFINITIONS = {
514
600
  },
515
601
  ["proposalId"],
516
602
  ),
603
+ okf_validate_changes: defineTool(
604
+ "Validate a complete structured concept create or update batch without changing files.",
605
+ READ_ONLY,
606
+ LIVE_CHANGE_TOOL_PROPERTIES,
607
+ ["changes"],
608
+ undefined,
609
+ LIVE_VALIDATE_OUTPUT,
610
+ ),
517
611
  okf_apply_changes: defineTool(
518
- "Validate and atomically apply one or more structured concept creates or updates to one local bundle.",
612
+ "Validate and apply one or more structured concept creates or updates to one local bundle as one batch.",
519
613
  DESTRUCTIVE_WRITE,
520
- {
521
- bundle: nonEmptyStringParameter("Writable bundle id; optional when exactly one local root is configured."),
522
- message: stringParameter("Optional Git commit summary when automatic commits are enabled."),
523
- changes: {
524
- type: "array",
525
- description: "One through 100 concept create or update operations applied as one batch.",
526
- minItems: 1,
527
- maxItems: MAX_CHANGES,
528
- items: { oneOf: [LIVE_CREATE_CHANGE, LIVE_UPDATE_CHANGE] },
529
- },
530
- },
614
+ LIVE_CHANGE_TOOL_PROPERTIES,
531
615
  ["changes"],
616
+ undefined,
617
+ LIVE_APPLY_OUTPUT,
532
618
  ),
533
619
  get_graph: defineTool(
534
620
  "Return a bounded set of OKF graph nodes and edges with optional concept filters.",
@@ -632,6 +718,7 @@ const COMPUTATION_AUTHORING_TOOL_NAMES = new Set([
632
718
  "okf_propose_attested_computation",
633
719
  ]);
634
720
  const LIVE_WRITE_TOOL_NAMES = new Set([
721
+ "okf_validate_changes",
635
722
  "okf_apply_changes",
636
723
  ]);
637
724
  const RUNTIME_REMOTE_TOOL_NAMES = new Set([
@@ -647,6 +734,9 @@ function jsonContent(value, options) {
647
734
  },
648
735
  ],
649
736
  };
737
+ if (options && options.structured) {
738
+ result.structuredContent = value;
739
+ }
650
740
  if (options && options.isError) {
651
741
  result.isError = true;
652
742
  }
@@ -696,7 +786,7 @@ function canonicalResourceUri(uri) {
696
786
  }
697
787
  }
698
788
 
699
- function publicBundles(index) {
789
+ function publicBundles(index, options) {
700
790
  return index.bundles.map((bundle) => {
701
791
  const documentCount = index.documents.filter((doc) => doc.bundle === bundle.id).length;
702
792
  const conceptCount = index.concepts.filter((doc) => doc.bundle === bundle.id).length;
@@ -720,12 +810,17 @@ function publicBundles(index) {
720
810
  exclude: bundle.exclude || [],
721
811
  };
722
812
  }
723
- const root = index.project && index.project.root
724
- ? path.relative(index.project.root, bundle.root).replace(/\\/g, "/") || "."
813
+ const absoluteRoot = path.resolve(bundle.root);
814
+ const projectRoot = index.project && index.project.root
815
+ ? path.resolve(index.project.root)
816
+ : null;
817
+ const root = projectRoot
818
+ ? path.relative(projectRoot, absoluteRoot).replace(/\\/g, "/") || "."
725
819
  : "<configured>";
726
820
  return {
727
821
  id: bundle.id,
728
822
  root,
823
+ ...((options && options.includeAbsolutePaths) ? { absoluteRoot, projectRoot } : {}),
729
824
  documentCount,
730
825
  conceptCount,
731
826
  assetCount,
@@ -877,7 +972,11 @@ async function expectedToolOperation(operation, options) {
877
972
  if (programmingError) {
878
973
  throw error;
879
974
  }
880
- throw new ToolExecutionError(error && error.message ? error.message : String(error));
975
+ throw new ToolExecutionError(
976
+ error && error.message ? error.message : String(error),
977
+ error && error.code,
978
+ error && error.details,
979
+ );
881
980
  }
882
981
  }
883
982
 
@@ -894,7 +993,9 @@ async function callTool(state, name, args) {
894
993
  try {
895
994
  switch (name) {
896
995
  case "list_bundles":
897
- return jsonContent(publicBundles(index));
996
+ return jsonContent(publicBundles(index, {
997
+ includeAbsolutePaths: Boolean(state.allowWrite),
998
+ }));
898
999
  case "list_concepts":
899
1000
  return jsonContent(listConcepts(index, args));
900
1001
  case "get_concept":
@@ -1043,6 +1144,18 @@ async function callTool(state, name, args) {
1043
1144
  return jsonContent(await expectedToolOperation(
1044
1145
  () => requireAuthoring(state).rejectProposal(args),
1045
1146
  ));
1147
+ case "okf_validate_changes": {
1148
+ const result = await expectedToolOperation(
1149
+ () => requireLiveAuthoring(state).validateChanges(args, {
1150
+ additionalBundles: state.remoteBundles,
1151
+ }),
1152
+ { translateTypeError: true },
1153
+ );
1154
+ if (result.applied || result.filesChanged) {
1155
+ rebuildStateIndex(state);
1156
+ }
1157
+ return jsonContent(result, { structured: true });
1158
+ }
1046
1159
  case "okf_apply_changes": {
1047
1160
  const result = await expectedToolOperation(
1048
1161
  () => requireLiveAuthoring(state).applyChanges(args, {
@@ -1050,10 +1163,13 @@ async function callTool(state, name, args) {
1050
1163
  }),
1051
1164
  { translateTypeError: true },
1052
1165
  );
1053
- if (result.applied) {
1166
+ if (result.applied || result.filesChanged) {
1054
1167
  rebuildStateIndex(state);
1055
1168
  }
1056
- return jsonContent(result, { isError: result.applied === false });
1169
+ return jsonContent(result, {
1170
+ structured: true,
1171
+ isError: result.applied === false,
1172
+ });
1057
1173
  }
1058
1174
  case "get_graph":
1059
1175
  return jsonContent(getGraph(index, args));
@@ -1094,11 +1210,14 @@ async function callTool(state, name, args) {
1094
1210
  if (!(error instanceof ToolExecutionError)) {
1095
1211
  throw error;
1096
1212
  }
1097
- return jsonContent({
1213
+ const failure = {
1098
1214
  error: "Tool execution failed",
1099
1215
  tool: name,
1100
1216
  message: error.message,
1101
- }, { isError: true });
1217
+ ...(error.code ? { code: error.code } : {}),
1218
+ ...(error.details !== undefined ? { details: error.details } : {}),
1219
+ };
1220
+ return jsonContent(failure, { isError: true, structured: true });
1102
1221
  }
1103
1222
  }
1104
1223
 
@@ -1274,6 +1393,9 @@ function registerMcpInterface(state) {
1274
1393
  description: definition.description,
1275
1394
  annotations: definition.annotations,
1276
1395
  inputSchema: fromJsonSchema(definition.inputSchema),
1396
+ ...(definition.outputSchema
1397
+ ? { outputSchema: fromJsonSchema(definition.outputSchema) }
1398
+ : {}),
1277
1399
  },
1278
1400
  async (args) => {
1279
1401
  const current = pendingToolCall.then(async () => {