@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/README.md +17 -14
- package/okf/bundles/okf-mcp/interfaces/mcp-tools.md +9 -3
- package/okf/bundles/okf-mcp/policies/authoring-safety.md +8 -2
- package/okf/bundles/okf-mcp/runtime/file-concept-store.md +1 -1
- package/okf/bundles/okf-mcp/runtime/mcp-server.md +2 -2
- package/okf/bundles/okf-mcp/specs/git-sources.md +1 -1
- package/okf/bundles/okf-mcp/workflows/concept-authoring.md +1 -1
- package/package.json +1 -1
- package/server.json +2 -2
- package/src/authoring.js +77 -11
- package/src/cli.js +1 -1
- package/src/git-source.js +13 -4
- package/src/live-authoring.js +1427 -123
- package/src/mcp-server.js +157 -35
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 {
|
|
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
|
-
|
|
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
|
|
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
|
|
724
|
-
|
|
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(
|
|
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, {
|
|
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
|
-
|
|
1213
|
+
const failure = {
|
|
1098
1214
|
error: "Tool execution failed",
|
|
1099
1215
|
tool: name,
|
|
1100
1216
|
message: error.message,
|
|
1101
|
-
|
|
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 () => {
|