@mfdaves/okf-mcp 0.5.1 → 0.6.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 +58 -16
- package/okf/bundles/okf-mcp/interfaces/mcp-tools.md +5 -1
- package/okf/bundles/okf-mcp/policies/authoring-safety.md +7 -1
- package/okf/bundles/okf-mcp/runtime/file-concept-store.md +4 -2
- package/okf/bundles/okf-mcp/workflows/concept-authoring.md +9 -3
- package/package.json +1 -1
- package/server.json +2 -2
- package/src/cli.js +62 -1
- package/src/index.js +1 -0
- package/src/indexer.js +40 -6
- package/src/live-authoring.js +945 -0
- package/src/mcp-server.js +168 -0
- package/src/store.js +10 -1
- package/src/v02.js +1 -0
package/src/mcp-server.js
CHANGED
|
@@ -22,6 +22,7 @@ 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
26
|
const { FileConceptStore } = require("./store");
|
|
26
27
|
const { loadProjectConfig } = require("./project");
|
|
27
28
|
const {
|
|
@@ -116,6 +117,107 @@ function objectParameter(description, extra) {
|
|
|
116
117
|
}, extra || {});
|
|
117
118
|
}
|
|
118
119
|
|
|
120
|
+
function relationParameter(description) {
|
|
121
|
+
return {
|
|
122
|
+
type: "object",
|
|
123
|
+
description,
|
|
124
|
+
additionalProperties: false,
|
|
125
|
+
properties: {
|
|
126
|
+
type: nonEmptyStringParameter("Typed relation name."),
|
|
127
|
+
target: nonEmptyStringParameter("Relation target URI or bundle-local path."),
|
|
128
|
+
label: stringParameter("Optional human-readable relation label."),
|
|
129
|
+
description: stringParameter("Optional relation explanation."),
|
|
130
|
+
},
|
|
131
|
+
required: ["type", "target"],
|
|
132
|
+
};
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
function sourceParameter(description) {
|
|
136
|
+
return {
|
|
137
|
+
description,
|
|
138
|
+
anyOf: [
|
|
139
|
+
nonEmptyStringParameter("Source resource URI or bundle-local path."),
|
|
140
|
+
objectParameter("Structured OKF source entry."),
|
|
141
|
+
],
|
|
142
|
+
};
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
function collectionPatchParameter(description, item) {
|
|
146
|
+
return {
|
|
147
|
+
type: "object",
|
|
148
|
+
description,
|
|
149
|
+
additionalProperties: false,
|
|
150
|
+
properties: {
|
|
151
|
+
add: { type: "array", items: item },
|
|
152
|
+
remove: { type: "array", items: item },
|
|
153
|
+
},
|
|
154
|
+
anyOf: [{ required: ["add"] }, { required: ["remove"] }],
|
|
155
|
+
};
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
const LIVE_CREATE_CHANGE = {
|
|
159
|
+
type: "object",
|
|
160
|
+
additionalProperties: false,
|
|
161
|
+
properties: {
|
|
162
|
+
op: { type: "string", const: "create", description: "Create a new concept." },
|
|
163
|
+
path: nonEmptyStringParameter("Optional safe bundle-relative Markdown path; derived from type and title when omitted."),
|
|
164
|
+
type: nonEmptyStringParameter("Concept type."),
|
|
165
|
+
title: nonEmptyStringParameter("Concept title."),
|
|
166
|
+
description: stringParameter("Optional concept description."),
|
|
167
|
+
body: stringParameter("Optional Markdown body; defaults to an H1 using the title."),
|
|
168
|
+
tags: stringArrayParameter("Initial tags.", { nonEmptyItems: true }),
|
|
169
|
+
sources: {
|
|
170
|
+
type: "array",
|
|
171
|
+
description: "Initial source resources or structured source entries.",
|
|
172
|
+
items: sourceParameter("Source entry."),
|
|
173
|
+
},
|
|
174
|
+
relations: {
|
|
175
|
+
type: "array",
|
|
176
|
+
description: "Initial typed relationships.",
|
|
177
|
+
items: relationParameter("Typed relation."),
|
|
178
|
+
},
|
|
179
|
+
metadata: objectParameter("Optional extension frontmatter; managed concept fields are rejected."),
|
|
180
|
+
},
|
|
181
|
+
required: ["op", "type", "title"],
|
|
182
|
+
};
|
|
183
|
+
|
|
184
|
+
const LIVE_UPDATE_CHANGE = {
|
|
185
|
+
type: "object",
|
|
186
|
+
additionalProperties: false,
|
|
187
|
+
properties: {
|
|
188
|
+
op: { type: "string", const: "update", description: "Update an existing concept in place." },
|
|
189
|
+
uri: nonEmptyStringParameter("Canonical or compatible URI of the existing concept."),
|
|
190
|
+
title: nonEmptyStringParameter("Replacement title."),
|
|
191
|
+
description: stringParameter("Replacement description."),
|
|
192
|
+
body: stringParameter("Replacement Markdown body."),
|
|
193
|
+
tags: collectionPatchParameter(
|
|
194
|
+
"Tags to add and/or remove; additions win when a tag appears in both lists.",
|
|
195
|
+
nonEmptyStringParameter("Tag."),
|
|
196
|
+
),
|
|
197
|
+
sources: collectionPatchParameter(
|
|
198
|
+
"Sources to add/replace and/or remove by id or resource.",
|
|
199
|
+
sourceParameter("Source entry or selector."),
|
|
200
|
+
),
|
|
201
|
+
relations: collectionPatchParameter(
|
|
202
|
+
"Relations to add/replace and/or remove by exact type plus target.",
|
|
203
|
+
relationParameter("Typed relation."),
|
|
204
|
+
),
|
|
205
|
+
metadata: objectParameter("Extension frontmatter fields to add or replace; managed fields are rejected."),
|
|
206
|
+
removeMetadataKeys: stringArrayParameter("Extension frontmatter keys to remove; managed fields are rejected.", { nonEmptyItems: true }),
|
|
207
|
+
},
|
|
208
|
+
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
|
+
|
|
119
221
|
function defineTool(description, annotations, properties, required, schemaExtras) {
|
|
120
222
|
return {
|
|
121
223
|
description,
|
|
@@ -412,6 +514,22 @@ const TOOL_DEFINITIONS = {
|
|
|
412
514
|
},
|
|
413
515
|
["proposalId"],
|
|
414
516
|
),
|
|
517
|
+
okf_apply_changes: defineTool(
|
|
518
|
+
"Validate and atomically apply one or more structured concept creates or updates to one local bundle.",
|
|
519
|
+
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
|
+
},
|
|
531
|
+
["changes"],
|
|
532
|
+
),
|
|
415
533
|
get_graph: defineTool(
|
|
416
534
|
"Return a bounded set of OKF graph nodes and edges with optional concept filters.",
|
|
417
535
|
READ_ONLY,
|
|
@@ -513,6 +631,9 @@ const AUTHORING_MUTATION_TOOL_NAMES = new Set([
|
|
|
513
631
|
const COMPUTATION_AUTHORING_TOOL_NAMES = new Set([
|
|
514
632
|
"okf_propose_attested_computation",
|
|
515
633
|
]);
|
|
634
|
+
const LIVE_WRITE_TOOL_NAMES = new Set([
|
|
635
|
+
"okf_apply_changes",
|
|
636
|
+
]);
|
|
516
637
|
const RUNTIME_REMOTE_TOOL_NAMES = new Set([
|
|
517
638
|
"load_remote_bundle",
|
|
518
639
|
]);
|
|
@@ -547,6 +668,9 @@ function toolEnabled(state, name) {
|
|
|
547
668
|
&& state.allowComputationAuthoring,
|
|
548
669
|
);
|
|
549
670
|
}
|
|
671
|
+
if (LIVE_WRITE_TOOL_NAMES.has(name)) {
|
|
672
|
+
return Boolean(state && state.allowWrite && state.liveAuthoringService);
|
|
673
|
+
}
|
|
550
674
|
if (RUNTIME_REMOTE_TOOL_NAMES.has(name)) {
|
|
551
675
|
return Boolean(state && state.allowRuntimeRemoteLoad);
|
|
552
676
|
}
|
|
@@ -719,6 +843,13 @@ function requireAuthoring(state) {
|
|
|
719
843
|
return state.authoringService;
|
|
720
844
|
}
|
|
721
845
|
|
|
846
|
+
function requireLiveAuthoring(state) {
|
|
847
|
+
if (!state.allowWrite || !state.liveAuthoringService) {
|
|
848
|
+
throw new Error("Live OKF authoring is not configured. Start the server with --write and --actor.");
|
|
849
|
+
}
|
|
850
|
+
return state.liveAuthoringService;
|
|
851
|
+
}
|
|
852
|
+
|
|
722
853
|
function rebuildStateIndex(state) {
|
|
723
854
|
const index = buildIndex(
|
|
724
855
|
state.localBundleArgs.concat(state.remoteBundles),
|
|
@@ -912,6 +1043,18 @@ async function callTool(state, name, args) {
|
|
|
912
1043
|
return jsonContent(await expectedToolOperation(
|
|
913
1044
|
() => requireAuthoring(state).rejectProposal(args),
|
|
914
1045
|
));
|
|
1046
|
+
case "okf_apply_changes": {
|
|
1047
|
+
const result = await expectedToolOperation(
|
|
1048
|
+
() => requireLiveAuthoring(state).applyChanges(args, {
|
|
1049
|
+
additionalBundles: state.remoteBundles,
|
|
1050
|
+
}),
|
|
1051
|
+
{ translateTypeError: true },
|
|
1052
|
+
);
|
|
1053
|
+
if (result.applied) {
|
|
1054
|
+
rebuildStateIndex(state);
|
|
1055
|
+
}
|
|
1056
|
+
return jsonContent(result, { isError: result.applied === false });
|
|
1057
|
+
}
|
|
915
1058
|
case "get_graph":
|
|
916
1059
|
return jsonContent(getGraph(index, args));
|
|
917
1060
|
case "get_neighbors":
|
|
@@ -994,6 +1137,8 @@ function createState(bundleArgs, options) {
|
|
|
994
1137
|
relationTypes,
|
|
995
1138
|
project,
|
|
996
1139
|
authoringService,
|
|
1140
|
+
liveAuthoringService: options && options.liveAuthoringService,
|
|
1141
|
+
allowWrite: Boolean(options && options.allowWrite),
|
|
997
1142
|
allowAuthoring: Boolean(options && options.allowAuthoring),
|
|
998
1143
|
allowRuntimeRemoteLoad: Boolean(options && options.allowRuntimeRemoteLoad),
|
|
999
1144
|
allowComputationAuthoring: Boolean(options && options.allowComputationAuthoring),
|
|
@@ -1012,6 +1157,9 @@ async function createStateAsync(bundleArgs, options) {
|
|
|
1012
1157
|
const localBundleArgs = (loaded.bundles || []).filter((bundle) => !bundle.remote);
|
|
1013
1158
|
const store = options.authoringStore || FileConceptStore.fromProject(options.projectPath, { proposalRoot: options.proposalRoot });
|
|
1014
1159
|
const authoringService = options.authoringService || new ConceptAuthoringService(store);
|
|
1160
|
+
const liveAuthoringService = options.liveAuthoringService || (options.allowWrite
|
|
1161
|
+
? new LiveAuthoringService(store, { actor: options.actor, gitCommit: options.gitCommit })
|
|
1162
|
+
: null);
|
|
1015
1163
|
const initialIndex = attachProject(
|
|
1016
1164
|
buildIndex(localBundleArgs.concat(initialRemoteBundles), {
|
|
1017
1165
|
relationTypes: loaded.project.relationTypes,
|
|
@@ -1024,6 +1172,8 @@ async function createStateAsync(bundleArgs, options) {
|
|
|
1024
1172
|
initialRemoteBundles,
|
|
1025
1173
|
relationTypes: loaded.project.relationTypes,
|
|
1026
1174
|
authoringService,
|
|
1175
|
+
liveAuthoringService,
|
|
1176
|
+
allowWrite: options.allowWrite,
|
|
1027
1177
|
allowAuthoring: options.allowAuthoring,
|
|
1028
1178
|
allowRuntimeRemoteLoad: options.allowRuntimeRemoteLoad,
|
|
1029
1179
|
allowComputationAuthoring: options.allowComputationAuthoring,
|
|
@@ -1037,6 +1187,9 @@ async function createStateAsync(bundleArgs, options) {
|
|
|
1037
1187
|
strictLinks: options.strictLinks,
|
|
1038
1188
|
});
|
|
1039
1189
|
const authoringService = options.authoringService || new ConceptAuthoringService(store);
|
|
1190
|
+
const liveAuthoringService = options.liveAuthoringService || (options.allowWrite
|
|
1191
|
+
? new LiveAuthoringService(store, { actor: options.actor, gitCommit: options.gitCommit })
|
|
1192
|
+
: null);
|
|
1040
1193
|
const localBundleArgs = store.getBundles();
|
|
1041
1194
|
const remoteBundles = await fetchRemoteBundles(options.remoteBundles || []);
|
|
1042
1195
|
const initialIndex = attachProject(buildIndex(localBundleArgs.concat(remoteBundles), {
|
|
@@ -1049,6 +1202,8 @@ async function createStateAsync(bundleArgs, options) {
|
|
|
1049
1202
|
initialRemoteBundles: remoteBundles,
|
|
1050
1203
|
relationTypes: store.getRelationTypes(),
|
|
1051
1204
|
authoringService,
|
|
1205
|
+
liveAuthoringService,
|
|
1206
|
+
allowWrite: options.allowWrite,
|
|
1052
1207
|
allowAuthoring: options.allowAuthoring,
|
|
1053
1208
|
allowRuntimeRemoteLoad: options.allowRuntimeRemoteLoad,
|
|
1054
1209
|
allowComputationAuthoring: options.allowComputationAuthoring,
|
|
@@ -1059,6 +1214,17 @@ async function createStateAsync(bundleArgs, options) {
|
|
|
1059
1214
|
}
|
|
1060
1215
|
const remoteBundles = await fetchRemoteBundles((options && options.remoteBundles) || []);
|
|
1061
1216
|
const localBundleArgs = (bundleArgs || []).slice();
|
|
1217
|
+
const liveAuthoringService = options && options.liveAuthoringService
|
|
1218
|
+
? options.liveAuthoringService
|
|
1219
|
+
: options && options.allowWrite && options.authoringService && options.authoringService.store
|
|
1220
|
+
? new LiveAuthoringService(options.authoringService.store, {
|
|
1221
|
+
actor: options.actor,
|
|
1222
|
+
gitCommit: options.gitCommit,
|
|
1223
|
+
})
|
|
1224
|
+
: null;
|
|
1225
|
+
if (options && options.allowWrite && !liveAuthoringService) {
|
|
1226
|
+
throw new Error("Live OKF authoring requires --root or --project and a configured actor.");
|
|
1227
|
+
}
|
|
1062
1228
|
return createState(localBundleArgs, {
|
|
1063
1229
|
initialIndex: buildIndex(localBundleArgs.concat(remoteBundles), {
|
|
1064
1230
|
strictLinks: options && options.strictLinks,
|
|
@@ -1066,6 +1232,8 @@ async function createStateAsync(bundleArgs, options) {
|
|
|
1066
1232
|
}),
|
|
1067
1233
|
initialRemoteBundles: remoteBundles,
|
|
1068
1234
|
authoringService: options && options.authoringService,
|
|
1235
|
+
liveAuthoringService,
|
|
1236
|
+
allowWrite: options && options.allowWrite,
|
|
1069
1237
|
allowAuthoring: options && options.allowAuthoring,
|
|
1070
1238
|
allowRuntimeRemoteLoad: options && options.allowRuntimeRemoteLoad,
|
|
1071
1239
|
allowComputationAuthoring: options && options.allowComputationAuthoring,
|
package/src/store.js
CHANGED
|
@@ -169,6 +169,7 @@ class FileConceptStore {
|
|
|
169
169
|
throw new Error("Proposal root cannot be a symbolic link.");
|
|
170
170
|
}
|
|
171
171
|
this.proposalLocks = new Map();
|
|
172
|
+
this.writeQueue = Promise.resolve();
|
|
172
173
|
}
|
|
173
174
|
|
|
174
175
|
static fromProject(projectPath, options) {
|
|
@@ -357,6 +358,12 @@ class FileConceptStore {
|
|
|
357
358
|
}
|
|
358
359
|
}
|
|
359
360
|
|
|
361
|
+
async withWriteLock(operation) {
|
|
362
|
+
const current = this.writeQueue.then(operation, operation);
|
|
363
|
+
this.writeQueue = current.catch(() => {});
|
|
364
|
+
return current;
|
|
365
|
+
}
|
|
366
|
+
|
|
360
367
|
listProposalFiles() {
|
|
361
368
|
const root = this.proposalDirectory("", false);
|
|
362
369
|
if (!fs.existsSync(root)) {
|
|
@@ -454,7 +461,9 @@ class FileConceptStore {
|
|
|
454
461
|
}
|
|
455
462
|
|
|
456
463
|
async acceptProposal(id, authoringService, options) {
|
|
457
|
-
return this.
|
|
464
|
+
return this.withWriteLock(() => (
|
|
465
|
+
this.withProposalLock(id, (canonicalId) => this.acceptProposalUnlocked(canonicalId, authoringService, options))
|
|
466
|
+
));
|
|
458
467
|
}
|
|
459
468
|
|
|
460
469
|
async acceptProposalUnlocked(id, authoringService, options) {
|