@mfdaves/okf-mcp 0.9.0 → 0.12.0-rc.1

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 (97) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.md +176 -19
  3. package/bin/okf-mcp.js +6 -1
  4. package/okf/okf-mcp/policies/authoring-safety.md +11 -1
  5. package/package.json +17 -5
  6. package/server.json +2 -2
  7. package/src/assets.js +165 -73
  8. package/src/authoring/candidates.js +391 -0
  9. package/src/authoring/git-preflight.js +225 -0
  10. package/src/authoring/git-publish.js +776 -0
  11. package/src/authoring/live.js +789 -0
  12. package/src/authoring/paths.js +112 -0
  13. package/src/authoring/policy-hook.js +221 -0
  14. package/src/authoring/proposal-policy.js +137 -0
  15. package/src/authoring/receipts.js +329 -0
  16. package/src/authoring/render.js +38 -0
  17. package/src/authoring/shared.js +75 -0
  18. package/src/authoring/staging.js +216 -0
  19. package/src/authoring.js +386 -287
  20. package/src/cache/files.js +147 -0
  21. package/src/cache/lock.js +201 -0
  22. package/src/cache/paths.js +197 -0
  23. package/src/cache/store.js +703 -0
  24. package/src/catalog-text.js +19 -0
  25. package/src/cli.js +184 -151
  26. package/src/computation.js +99 -61
  27. package/src/context/assemble.js +567 -0
  28. package/src/context/cli-options.js +88 -0
  29. package/src/context/score.js +234 -0
  30. package/src/context/sections.js +274 -0
  31. package/src/embed/interface.js +160 -0
  32. package/src/embed/openai.js +715 -0
  33. package/src/embed/prepare.js +182 -0
  34. package/src/embed/units.js +96 -0
  35. package/src/git-source.js +112 -52
  36. package/src/graph.js +95 -37
  37. package/src/http-server.js +36 -17
  38. package/src/index.js +15 -0
  39. package/src/indexer/assemble.js +566 -0
  40. package/src/indexer/build.js +290 -0
  41. package/src/indexer/cache.js +81 -0
  42. package/src/indexer/edges.js +430 -0
  43. package/src/indexer/index.js +44 -0
  44. package/src/indexer/paths.js +178 -0
  45. package/src/indexer/resolve.js +282 -0
  46. package/src/indexer/update.js +720 -0
  47. package/src/indexer.js +3 -1068
  48. package/src/live-authoring.js +4 -2329
  49. package/src/markdown.js +21 -16
  50. package/src/mcp/registry.js +328 -0
  51. package/src/mcp/resources.js +45 -0
  52. package/src/mcp/server.js +472 -0
  53. package/src/mcp/tools/catalog.js +244 -0
  54. package/src/mcp/tools/computation.js +83 -0
  55. package/src/mcp/tools/context.js +133 -0
  56. package/src/mcp/tools/graph.js +167 -0
  57. package/src/mcp/tools/live-authoring.js +316 -0
  58. package/src/mcp/tools/migration.js +86 -0
  59. package/src/mcp/tools/producers.js +79 -0
  60. package/src/mcp/tools/proposals.js +213 -0
  61. package/src/mcp/tools/provenance.js +87 -0
  62. package/src/mcp/tools/remote.js +79 -0
  63. package/src/mcp/tools/search.js +242 -0
  64. package/src/mcp-server.js +3 -1611
  65. package/src/migration.js +431 -253
  66. package/src/parser.js +245 -130
  67. package/src/plugins.js +71 -48
  68. package/src/policy/write-policy.js +713 -0
  69. package/src/producer-publisher.js +195 -77
  70. package/src/producers.js +265 -101
  71. package/src/project.js +277 -93
  72. package/src/remote.js +96 -61
  73. package/src/search/cli-options.js +107 -0
  74. package/src/search/confidence.js +61 -0
  75. package/src/search/dense.js +304 -0
  76. package/src/search/embedding-cli.js +57 -0
  77. package/src/search/embedding-config.js +217 -0
  78. package/src/search/fusion.js +249 -0
  79. package/src/search/hybrid.js +526 -0
  80. package/src/search/languages.js +200 -0
  81. package/src/search/lexical.js +695 -0
  82. package/src/search/query.js +620 -0
  83. package/src/search/stem/among.js +43 -0
  84. package/src/search/stem/base-stemmer.js +311 -0
  85. package/src/search/stem/en-regions.js +456 -0
  86. package/src/search/stem/en-suffixes.js +664 -0
  87. package/src/search/stem/en-tables.js +176 -0
  88. package/src/search/stem/en.js +238 -0
  89. package/src/search/stem/it-regions.js +459 -0
  90. package/src/search/stem/it-suffixes.js +471 -0
  91. package/src/search/stem/it-tables.js +257 -0
  92. package/src/search/stem/it.js +155 -0
  93. package/src/search-index.js +2 -81
  94. package/src/search.js +2 -252
  95. package/src/store.js +134 -81
  96. package/src/v02.js +301 -105
  97. package/src/validation.js +24 -20
package/src/markdown.js CHANGED
@@ -22,11 +22,11 @@ function isDocumentChild(node) {
22
22
 
23
23
  function isTopLevelItem(node) {
24
24
  return Boolean(
25
- node
26
- && node.parent
27
- && node.parent.type === "list"
28
- && node.parent.parent
29
- && node.parent.parent.type === "document",
25
+ node &&
26
+ node.parent &&
27
+ node.parent.type === "list" &&
28
+ node.parent.parent &&
29
+ node.parent.parent.type === "document",
30
30
  );
31
31
  }
32
32
 
@@ -63,9 +63,11 @@ function markdownStructure(body) {
63
63
  const fenceLength = Number(node._fenceLength || 0);
64
64
  const closingLine = lines[node.sourcepos[1][0] - 1] || "";
65
65
  const closed = Boolean(
66
- node._isFenced
67
- && fenceCharacter
68
- && new RegExp(`^ {0,3}${fenceCharacter === "`" ? "`" : "~"}{${fenceLength},}\\s*$`).test(closingLine),
66
+ node._isFenced &&
67
+ fenceCharacter &&
68
+ new RegExp(`^ {0,3}${fenceCharacter === "`" ? "`" : "~"}{${fenceLength},}\\s*$`).test(
69
+ closingLine,
70
+ ),
69
71
  );
70
72
  codeBlocks.push({
71
73
  node,
@@ -73,7 +75,10 @@ function markdownStructure(body) {
73
75
  endLine: node.sourcepos[1][0],
74
76
  fenced: Boolean(node._isFenced),
75
77
  closed,
76
- language: String(node.info || "").trim().split(/\s+/)[0] || "",
78
+ language:
79
+ String(node.info || "")
80
+ .trim()
81
+ .split(/\s+/)[0] || "",
77
82
  content: String(node.literal || "").replace(/\n$/, ""),
78
83
  });
79
84
  }
@@ -89,9 +94,9 @@ function markdownStructure(body) {
89
94
  }
90
95
 
91
96
  function sectionEndLine(structure, heading) {
92
- const next = structure.headings.find((entry) => (
93
- entry.startLine > heading.startLine && entry.level <= heading.level
94
- ));
97
+ const next = structure.headings.find(
98
+ (entry) => entry.startLine > heading.startLine && entry.level <= heading.level,
99
+ );
95
100
  return next ? next.startLine : Number.POSITIVE_INFINITY;
96
101
  }
97
102
 
@@ -99,10 +104,10 @@ function sectionNodes(heading, options) {
99
104
  const nodes = [];
100
105
  let current = heading && heading.node ? heading.node.next : null;
101
106
  while (current) {
102
- if (current.type === "heading" && (
103
- options && options.stopAtAnyHeading
104
- || current.level <= heading.level
105
- )) {
107
+ if (
108
+ current.type === "heading" &&
109
+ ((options && options.stopAtAnyHeading) || current.level <= heading.level)
110
+ ) {
106
111
  break;
107
112
  }
108
113
  nodes.push(current);
@@ -0,0 +1,328 @@
1
+ "use strict";
2
+
3
+ class ToolExecutionError extends Error {
4
+ constructor(message, code, details) {
5
+ super(message);
6
+ this.name = "ToolExecutionError";
7
+ if (typeof code === "string" && code) {
8
+ this.code = code;
9
+ }
10
+ if (details !== undefined) {
11
+ this.details = details;
12
+ }
13
+ }
14
+ }
15
+
16
+ const READ_ONLY = {
17
+ readOnlyHint: true,
18
+ destructiveHint: false,
19
+ idempotentHint: true,
20
+ openWorldHint: false,
21
+ };
22
+ const LOCAL_WRITE = {
23
+ readOnlyHint: false,
24
+ destructiveHint: false,
25
+ idempotentHint: false,
26
+ openWorldHint: false,
27
+ };
28
+ const DESTRUCTIVE_WRITE = {
29
+ readOnlyHint: false,
30
+ destructiveHint: true,
31
+ idempotentHint: false,
32
+ openWorldHint: false,
33
+ };
34
+ const REMOTE_LOAD = {
35
+ readOnlyHint: false,
36
+ destructiveHint: false,
37
+ idempotentHint: false,
38
+ openWorldHint: true,
39
+ };
40
+ const PRODUCER_PREVIEW = {
41
+ readOnlyHint: true,
42
+ destructiveHint: false,
43
+ idempotentHint: true,
44
+ openWorldHint: true,
45
+ };
46
+ const PRODUCER_RUN = {
47
+ readOnlyHint: false,
48
+ destructiveHint: true,
49
+ idempotentHint: false,
50
+ openWorldHint: true,
51
+ };
52
+
53
+ function stringParameter(description, extra) {
54
+ return Object.assign({ type: "string", description }, extra || {});
55
+ }
56
+
57
+ function nonEmptyStringParameter(description, extra) {
58
+ return stringParameter(description, Object.assign({ minLength: 1 }, extra || {}));
59
+ }
60
+
61
+ function integerParameter(description, minimum, maximum, defaultValue) {
62
+ return {
63
+ type: "integer",
64
+ description,
65
+ minimum,
66
+ ...(maximum === undefined ? {} : { maximum }),
67
+ default: defaultValue,
68
+ };
69
+ }
70
+
71
+ function booleanParameter(description) {
72
+ return { type: "boolean", description, default: false };
73
+ }
74
+
75
+ function optionalBooleanParameter(description) {
76
+ return { type: "boolean", description };
77
+ }
78
+
79
+ function stringArrayParameter(description, options) {
80
+ const config = options || {};
81
+ return {
82
+ type: "array",
83
+ description,
84
+ items: Object.assign({ type: "string" }, config.nonEmptyItems ? { minLength: 1 } : {}),
85
+ ...(config.minItems === undefined ? {} : { minItems: config.minItems }),
86
+ };
87
+ }
88
+
89
+ function objectParameter(description, extra) {
90
+ return Object.assign(
91
+ {
92
+ type: "object",
93
+ description,
94
+ additionalProperties: true,
95
+ },
96
+ extra || {},
97
+ );
98
+ }
99
+
100
+ function detailParameter(description) {
101
+ return stringParameter(description, { enum: ["compact", "full"], default: "compact" });
102
+ }
103
+
104
+ function relationParameter(description) {
105
+ return {
106
+ type: "object",
107
+ description,
108
+ additionalProperties: false,
109
+ properties: {
110
+ type: nonEmptyStringParameter("Typed relation name."),
111
+ target: nonEmptyStringParameter("Relation target URI or bundle-local path."),
112
+ label: stringParameter("Optional human-readable relation label."),
113
+ description: stringParameter("Optional relation explanation."),
114
+ },
115
+ required: ["type", "target"],
116
+ };
117
+ }
118
+
119
+ function sourceParameter(description) {
120
+ return {
121
+ description,
122
+ anyOf: [
123
+ nonEmptyStringParameter("Source resource URI or bundle-local path."),
124
+ objectParameter("Structured OKF source entry."),
125
+ ],
126
+ };
127
+ }
128
+
129
+ function collectionPatchParameter(description, item) {
130
+ return {
131
+ type: "object",
132
+ description,
133
+ additionalProperties: false,
134
+ minProperties: 1,
135
+ properties: {
136
+ add: { type: "array", items: item },
137
+ remove: { type: "array", items: item },
138
+ },
139
+ };
140
+ }
141
+
142
+ function defineTool(description, annotations, properties, required, schemaExtras, outputSchema) {
143
+ return {
144
+ description,
145
+ annotations,
146
+ inputSchema: {
147
+ type: "object",
148
+ additionalProperties: false,
149
+ properties: properties || {},
150
+ ...(required && required.length ? { required } : {}),
151
+ ...(schemaExtras || {}),
152
+ },
153
+ ...(outputSchema ? { outputSchema } : {}),
154
+ };
155
+ }
156
+
157
+ // Availability gates. A tool names one as its `enabled` predicate; tools/list
158
+ // advertises only the tools whose gate passes for the running server state.
159
+ const GATES = {
160
+ always: () => true,
161
+ producer: (state) => Boolean(state && state.producerService),
162
+ producerWrite: (state) =>
163
+ Boolean(state && state.producerService && state.allowWrite && state.actor),
164
+ projectHelper: (state) => Boolean(state && state.authoringService),
165
+ authoringMutation: (state) => Boolean(state && state.authoringService && state.allowAuthoring),
166
+ computationAuthoring: (state) =>
167
+ Boolean(
168
+ state && state.authoringService && state.allowAuthoring && state.allowComputationAuthoring,
169
+ ),
170
+ liveWrite: (state) => Boolean(state && state.allowWrite && state.liveAuthoringService),
171
+ runtimeRemote: (state) => Boolean(state && state.allowRuntimeRemoteLoad),
172
+ };
173
+
174
+ function toolEnabled(tool, state) {
175
+ return (tool.enabled || GATES.always)(state);
176
+ }
177
+
178
+ // Advertised tools/list order. It predates the split into area modules and is
179
+ // kept verbatim so clients that cache the listing see the same sequence;
180
+ // composition fails fast when a module and this list disagree.
181
+ const TOOL_ORDER = [
182
+ "list_bundles",
183
+ "list_concepts",
184
+ "get_concept",
185
+ "search_concepts",
186
+ "get_context",
187
+ "list_types",
188
+ "list_tags",
189
+ "list_relation_types",
190
+ "list_edge_kinds",
191
+ "get_provenance",
192
+ "inspect_attested_computation",
193
+ "read_bundle_asset",
194
+ "read_git_source",
195
+ "prepare_attested_computation",
196
+ "check_computation_receipt",
197
+ "check_v02_migration",
198
+ "load_remote_bundle",
199
+ "list_remote_bundles",
200
+ "okf_validate_concept",
201
+ "okf_suggest_concept_path",
202
+ "okf_propose_concept",
203
+ "okf_propose_update",
204
+ "okf_propose_attested_computation",
205
+ "okf_propose_v02_migration",
206
+ "okf_list_proposals",
207
+ "okf_get_proposal",
208
+ "okf_accept_proposal",
209
+ "okf_reject_proposal",
210
+ "okf_validate_changes",
211
+ "okf_apply_changes",
212
+ "okf_list_producers",
213
+ "okf_preview_producer",
214
+ "okf_run_producer",
215
+ "get_graph",
216
+ "get_neighbors",
217
+ "get_subgraph",
218
+ "find_paths",
219
+ "graph_summary",
220
+ "validate_bundle",
221
+ "validate_project",
222
+ "export_graph",
223
+ // Gated on a configured embedder (WP3c); appended so existing positions hold.
224
+ "embedding_status",
225
+ ];
226
+
227
+ function composeRegistry(modules) {
228
+ const tools = {};
229
+ modules.forEach((module) => {
230
+ Object.keys(module.tools).forEach((name) => {
231
+ if (tools[name]) {
232
+ throw new Error(`Duplicate MCP tool definition: ${name}`);
233
+ }
234
+ if (typeof module.tools[name].handler !== "function") {
235
+ throw new Error(`MCP tool ${name} has no handler.`);
236
+ }
237
+ tools[name] = module.tools[name];
238
+ });
239
+ });
240
+ const missing = TOOL_ORDER.filter((name) => !tools[name]);
241
+ const unlisted = Object.keys(tools).filter((name) => !TOOL_ORDER.includes(name));
242
+ if (missing.length || unlisted.length) {
243
+ throw new Error(
244
+ `MCP tool registry mismatch: missing ${missing.join(", ") || "none"}; ` +
245
+ `unlisted ${unlisted.join(", ") || "none"}`,
246
+ );
247
+ }
248
+ return { names: TOOL_ORDER.slice(), tools };
249
+ }
250
+
251
+ function jsonContent(value, options) {
252
+ const result = {
253
+ content: [
254
+ {
255
+ type: "text",
256
+ text: JSON.stringify(value, null, 2),
257
+ },
258
+ ],
259
+ };
260
+ if (options && options.structured) {
261
+ result.structuredContent = value;
262
+ }
263
+ if (options && options.isError) {
264
+ result.isError = true;
265
+ }
266
+ return result;
267
+ }
268
+
269
+ async function expectedToolOperation(operation, options) {
270
+ try {
271
+ return await operation();
272
+ } catch (error) {
273
+ if (error instanceof ToolExecutionError) {
274
+ throw error;
275
+ }
276
+ const programmingError =
277
+ error instanceof ReferenceError ||
278
+ error instanceof SyntaxError ||
279
+ error instanceof RangeError ||
280
+ (error instanceof TypeError && !(options && options.translateTypeError));
281
+ if (programmingError) {
282
+ throw error;
283
+ }
284
+ throw new ToolExecutionError(
285
+ error && error.message ? error.message : String(error),
286
+ error && error.code,
287
+ error && error.details,
288
+ );
289
+ }
290
+ }
291
+
292
+ function requireAuthoring(state) {
293
+ if (!state.authoringService) {
294
+ throw new Error(
295
+ "OKF authoring is not configured. Start the server with --root or --project to enable writable concept proposals.",
296
+ );
297
+ }
298
+ return state.authoringService;
299
+ }
300
+
301
+ module.exports = {
302
+ DESTRUCTIVE_WRITE,
303
+ GATES,
304
+ LOCAL_WRITE,
305
+ PRODUCER_PREVIEW,
306
+ PRODUCER_RUN,
307
+ READ_ONLY,
308
+ REMOTE_LOAD,
309
+ TOOL_ORDER,
310
+ ToolExecutionError,
311
+ booleanParameter,
312
+ collectionPatchParameter,
313
+ composeRegistry,
314
+ defineTool,
315
+ detailParameter,
316
+ expectedToolOperation,
317
+ integerParameter,
318
+ jsonContent,
319
+ nonEmptyStringParameter,
320
+ objectParameter,
321
+ optionalBooleanParameter,
322
+ relationParameter,
323
+ requireAuthoring,
324
+ sourceParameter,
325
+ stringArrayParameter,
326
+ stringParameter,
327
+ toolEnabled,
328
+ };
@@ -0,0 +1,45 @@
1
+ "use strict";
2
+
3
+ const { ResourceNotFoundError } = require("@modelcontextprotocol/server");
4
+
5
+ function canonicalResourceUri(uri) {
6
+ try {
7
+ return new URL(uri).href;
8
+ } catch {
9
+ return uri;
10
+ }
11
+ }
12
+
13
+ function listResources(index) {
14
+ return {
15
+ resources: index.documents.map((doc) => ({
16
+ uri: canonicalResourceUri(doc.uri),
17
+ name: doc.title,
18
+ description: doc.description || `${doc.kind} ${doc.path}`,
19
+ mimeType: "text/markdown",
20
+ })),
21
+ };
22
+ }
23
+
24
+ function readResource(index, uri) {
25
+ const doc =
26
+ index.byUri.get(uri) ||
27
+ index.documents.find((candidate) => canonicalResourceUri(candidate.uri) === uri);
28
+ if (!doc) {
29
+ throw new ResourceNotFoundError(uri);
30
+ }
31
+ return {
32
+ contents: [
33
+ {
34
+ uri: canonicalResourceUri(doc.uri),
35
+ mimeType: "text/markdown",
36
+ text: doc.text,
37
+ },
38
+ ],
39
+ };
40
+ }
41
+
42
+ module.exports = {
43
+ listResources,
44
+ readResource,
45
+ };