@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
@@ -0,0 +1,472 @@
1
+ "use strict";
2
+
3
+ const { McpServer, ResourceTemplate, fromJsonSchema } = require("@modelcontextprotocol/server");
4
+ const { StdioServerTransport, serveStdio } = require("@modelcontextprotocol/server/stdio");
5
+ const path = require("node:path");
6
+ const { isDeepStrictEqual } = require("node:util");
7
+ const {
8
+ attachProject,
9
+ buildIndex,
10
+ indexInputs,
11
+ indexUpdateStats,
12
+ loadProjectBundles,
13
+ parseBundleArg,
14
+ refreshIndex,
15
+ updateIndex,
16
+ } = require("../indexer");
17
+ const { fetchRemoteBundles } = require("../remote");
18
+ const { ConceptAuthoringService } = require("../authoring");
19
+ const { LiveAuthoringService } = require("../live-authoring");
20
+ const { FileConceptStore } = require("../store");
21
+ const { DEFAULT_RELATION_TYPES, loadProjectConfig } = require("../project");
22
+ const { ProducerService } = require("../producers");
23
+ const { loadEmbeddingConfigFile } = require("../search/embedding-config");
24
+ const { openEmbeddingRuntime } = require("../search/hybrid");
25
+ const packageMetadata = require("../../package.json");
26
+ const { ToolExecutionError, composeRegistry, jsonContent, toolEnabled } = require("./registry");
27
+ const { listResources, readResource } = require("./resources");
28
+
29
+ const MAX_MCP_MESSAGE_BYTES = 1024 * 1024;
30
+
31
+ // Each area module exports its tools with schema, annotations, gate, and
32
+ // handler together; the registry fixes the advertised order and rejects
33
+ // duplicates or tools missing from that order.
34
+ const registry = composeRegistry([
35
+ require("./tools/catalog"),
36
+ require("./tools/search"),
37
+ require("./tools/context"),
38
+ require("./tools/graph"),
39
+ require("./tools/provenance"),
40
+ require("./tools/computation"),
41
+ require("./tools/migration"),
42
+ require("./tools/remote"),
43
+ require("./tools/proposals"),
44
+ require("./tools/live-authoring"),
45
+ require("./tools/producers"),
46
+ ]);
47
+
48
+ // Whether the server's index was built from exactly what the live authoring
49
+ // service would build its own from (the service's bundles with their include
50
+ // and exclude patterns plus the server's remote snapshots, its relation
51
+ // types and flags, a floating date, the server's languages), so the two can
52
+ // share one index object instead of each keeping a copy. The check reads the
53
+ // index's own build record, so an index a host built from other arguments
54
+ // is never shared.
55
+ function liveIndexCompatible(state) {
56
+ const service = state.liveAuthoringService;
57
+ const store = service?.store;
58
+ if (!store || typeof service.adoptIndex !== "function" || store.project !== state.project) {
59
+ return false;
60
+ }
61
+ const built = indexInputs(state.index);
62
+ if (!built) {
63
+ return false;
64
+ }
65
+ const expected = {
66
+ bundles: store
67
+ .getBundles()
68
+ .concat(state.remoteBundles || [])
69
+ .map(parseBundleArg)
70
+ .map((bundle) => ({
71
+ id: bundle.id,
72
+ root: bundle.root,
73
+ remote: Boolean(bundle.remote),
74
+ include: (bundle.include || []).map(String),
75
+ exclude: (bundle.exclude || []).map(String),
76
+ })),
77
+ relationTypes: Array.from(
78
+ new Set((store.getRelationTypes() || DEFAULT_RELATION_TYPES).map(String)),
79
+ ),
80
+ allowCustomRelationTypes: Boolean(store.allowCustomRelationTypes),
81
+ strictLinks: Boolean(store.strictLinks),
82
+ asOf: null,
83
+ // The server stamps its --languages on the index; the service reads none.
84
+ languages: state.languages === undefined ? null : state.languages,
85
+ };
86
+ return isDeepStrictEqual(built, expected);
87
+ }
88
+
89
+ function shareIndexWithLiveAuthoring(state) {
90
+ if (state.shareLiveIndex) {
91
+ state.liveAuthoringService.adoptIndex(state.index, state.remoteBundles);
92
+ }
93
+ }
94
+
95
+ // After a live batch the service hands over what it published: the server
96
+ // adopts the service's index when the two share one, applies the batch to its
97
+ // own index otherwise (brought up to date with the files first, as the
98
+ // service's own index was), and only rebuilds from scratch when there is no
99
+ // batch to apply (producer runs, proposals, remote loads, a stale concept
100
+ // file).
101
+ function rebuildStateIndex(state) {
102
+ const service = state.liveAuthoringService;
103
+ const publication =
104
+ service && typeof service.takePublication === "function" ? service.takePublication() : null;
105
+ if (publication) {
106
+ if (publication.hostOwned && publication.index) {
107
+ state.index = publication.index;
108
+ return state.index;
109
+ }
110
+ if (indexUpdateStats(state.index)) {
111
+ state.index = updateIndex(refreshIndex(state.index), publication.changes);
112
+ return state.index;
113
+ }
114
+ }
115
+ const index = buildIndex(state.localBundleArgs.concat(state.remoteBundles), {
116
+ relationTypes: state.relationTypes,
117
+ strictLinks: state.strictLinks,
118
+ allowCustomRelationTypes: state.allowCustomRelationTypes,
119
+ });
120
+ state.index = state.project ? attachProject(index, state.project) : index;
121
+ if (state.languages) {
122
+ state.index.languages = state.languages;
123
+ }
124
+ shareIndexWithLiveAuthoring(state);
125
+ return state.index;
126
+ }
127
+
128
+ async function callTool(state, name, args) {
129
+ const tool = registry.tools[name];
130
+ try {
131
+ if (!tool) {
132
+ throw new Error(`Unknown registered MCP tool: ${name}`);
133
+ }
134
+ return await tool.handler(state, args);
135
+ } catch (error) {
136
+ if (!(error instanceof ToolExecutionError)) {
137
+ throw error;
138
+ }
139
+ const failure = {
140
+ error: "Tool execution failed",
141
+ tool: name,
142
+ message: error.message,
143
+ ...(error.code ? { code: error.code } : {}),
144
+ ...(error.details !== undefined ? { details: error.details } : {}),
145
+ };
146
+ return jsonContent(failure, { isError: true, structured: true });
147
+ }
148
+ }
149
+
150
+ function createState(bundleArgs, options) {
151
+ const authoringService = options?.authoringService;
152
+ let project = null;
153
+ if (authoringService?.store) {
154
+ project = authoringService.store.project;
155
+ } else if (options?.projectPath) {
156
+ project = loadProjectConfig(options.projectPath);
157
+ }
158
+ const localBundleArgs = project
159
+ ? project.bundles.filter((bundle) => !bundle.remote)
160
+ : (bundleArgs || []).slice();
161
+ const relationTypes = options?.relationTypes || project?.relationTypes;
162
+ const allowCustomRelationTypes = Boolean(options?.allowCustomRelationTypes || project?.rootMode);
163
+ let initialIndex = options?.initialIndex;
164
+ if (!initialIndex) {
165
+ initialIndex = buildIndex(localBundleArgs, {
166
+ relationTypes,
167
+ strictLinks: Boolean(options?.strictLinks || project?.strictLinks),
168
+ allowCustomRelationTypes,
169
+ });
170
+ if (project) {
171
+ initialIndex = attachProject(initialIndex, project);
172
+ }
173
+ }
174
+ const state = {
175
+ index: initialIndex,
176
+ localBundleArgs,
177
+ remoteBundles: options?.initialRemoteBundles || [],
178
+ relationTypes,
179
+ project,
180
+ authoringService,
181
+ liveAuthoringService: options?.liveAuthoringService,
182
+ producerService: options?.producerService,
183
+ allowWrite: Boolean(options?.allowWrite),
184
+ actor: options?.actor,
185
+ allowAuthoring: Boolean(options?.allowAuthoring),
186
+ allowRuntimeRemoteLoad: Boolean(options?.allowRuntimeRemoteLoad),
187
+ allowComputationAuthoring: Boolean(options?.allowComputationAuthoring),
188
+ strictLinks: Boolean(options?.strictLinks || project?.strictLinks),
189
+ allowCustomRelationTypes,
190
+ repositoryMappings: options?.repositoryMappings || new Map(),
191
+ // Search stemming languages from --languages; the project config's value
192
+ // travels on index.project (attachProject) and detection covers the rest.
193
+ languages: options?.languages || undefined,
194
+ };
195
+ if (state.languages) {
196
+ state.index.languages = state.languages;
197
+ }
198
+ // Tool handlers refresh the index through the state so index construction
199
+ // stays in this module; handlers never see bundle arguments or build options.
200
+ state.rebuildIndex = () => rebuildStateIndex(state);
201
+ state.shareLiveIndex = liveIndexCompatible(state);
202
+ shareIndexWithLiveAuthoring(state);
203
+ if (
204
+ !state.producerService &&
205
+ project &&
206
+ (project.producers || []).length &&
207
+ authoringService?.store
208
+ ) {
209
+ state.producerService = new ProducerService({
210
+ project,
211
+ store: authoringService.store,
212
+ bundles: localBundleArgs,
213
+ loader: options?.producerLoader,
214
+ env: options?.producerEnv,
215
+ now: options?.producerNow,
216
+ });
217
+ }
218
+ return state;
219
+ }
220
+
221
+ // Hybrid search settings (WP3c): a library caller's settings object, the
222
+ // --embedder-config file of --root mode, or the project's own; --cache-dir
223
+ // (relative to the working directory) overrides the cache location.
224
+ function embeddingSettings(projectSettings, options) {
225
+ const given = options?.embedding || {};
226
+ const base = given.embedder
227
+ ? given
228
+ : given.configPath
229
+ ? loadEmbeddingConfigFile(given.configPath)
230
+ : projectSettings;
231
+ if (!base) return null;
232
+ return given.cacheDir
233
+ ? Object.assign({}, base, { cacheDir: path.resolve(given.cacheDir) })
234
+ : base;
235
+ }
236
+
237
+ // Opens the embedding runtime (never throws: failures leave it degraded) and
238
+ // prepares the missing vectors in the background, so a large first embed
239
+ // never delays the server's start; searches stay lexical until rows exist.
240
+ async function attachEmbeddings(state, settings, context) {
241
+ if (!settings) return state;
242
+ state.embeddings = await openEmbeddingRuntime(settings, context);
243
+ state.embeddings.scheduleSync(state.index);
244
+ return state;
245
+ }
246
+
247
+ async function createStateAsync(bundleArgs, options) {
248
+ if (options?.projectPath) {
249
+ const loaded = await loadProjectBundles(options.projectPath);
250
+ const extraRemoteBundles = await fetchRemoteBundles(options.remoteBundles || []);
251
+ const initialRemoteBundles = loaded.remoteBundles.concat(extraRemoteBundles);
252
+ const localBundleArgs = (loaded.bundles || []).filter((bundle) => !bundle.remote);
253
+ const store =
254
+ options.authoringStore ||
255
+ FileConceptStore.fromProject(options.projectPath, { proposalRoot: options.proposalRoot });
256
+ const authoringService =
257
+ options.authoringService ||
258
+ new ConceptAuthoringService(store, {
259
+ actor: options.actor,
260
+ writePolicy: options.writePolicy,
261
+ });
262
+ const liveAuthoringService =
263
+ options.liveAuthoringService ||
264
+ (options.allowWrite
265
+ ? new LiveAuthoringService(store, {
266
+ actor: options.actor,
267
+ gitCommit: options.gitCommit,
268
+ writePolicy: options.writePolicy,
269
+ })
270
+ : null);
271
+ const initialIndex = attachProject(
272
+ buildIndex(localBundleArgs.concat(initialRemoteBundles), {
273
+ relationTypes: loaded.project.relationTypes,
274
+ strictLinks: options.strictLinks || loaded.project.strictLinks,
275
+ }),
276
+ loaded.project,
277
+ );
278
+ const projectState = createState(localBundleArgs, {
279
+ initialIndex,
280
+ initialRemoteBundles,
281
+ relationTypes: loaded.project.relationTypes,
282
+ authoringService,
283
+ liveAuthoringService,
284
+ producerService: options.producerService,
285
+ producerLoader: options.producerLoader,
286
+ producerEnv: options.producerEnv,
287
+ producerNow: options.producerNow,
288
+ allowWrite: options.allowWrite,
289
+ actor: options.actor,
290
+ allowAuthoring: options.allowAuthoring,
291
+ allowRuntimeRemoteLoad: options.allowRuntimeRemoteLoad,
292
+ allowComputationAuthoring: options.allowComputationAuthoring,
293
+ strictLinks: options.strictLinks || loaded.project.strictLinks,
294
+ repositoryMappings: options.repositoryMappings,
295
+ languages: options.languages,
296
+ });
297
+ return attachEmbeddings(projectState, embeddingSettings(loaded.project.embedding, options), {
298
+ root: loaded.project.root,
299
+ write: Boolean(options.allowWrite),
300
+ });
301
+ }
302
+ if (options?.rootPath) {
303
+ const store =
304
+ options.authoringStore ||
305
+ FileConceptStore.fromRoot(options.rootPath, {
306
+ proposalRoot: options.proposalRoot,
307
+ strictLinks: options.strictLinks,
308
+ });
309
+ const authoringService =
310
+ options.authoringService ||
311
+ new ConceptAuthoringService(store, {
312
+ actor: options.actor,
313
+ writePolicy: options.writePolicy,
314
+ });
315
+ const liveAuthoringService =
316
+ options.liveAuthoringService ||
317
+ (options.allowWrite
318
+ ? new LiveAuthoringService(store, {
319
+ actor: options.actor,
320
+ gitCommit: options.gitCommit,
321
+ writePolicy: options.writePolicy,
322
+ })
323
+ : null);
324
+ const localBundleArgs = store.getBundles();
325
+ const remoteBundles = await fetchRemoteBundles(options.remoteBundles || []);
326
+ const initialIndex = attachProject(
327
+ buildIndex(localBundleArgs.concat(remoteBundles), {
328
+ relationTypes: store.getRelationTypes(),
329
+ strictLinks: options.strictLinks,
330
+ allowCustomRelationTypes: true,
331
+ }),
332
+ store.project,
333
+ );
334
+ const rootState = createState(localBundleArgs, {
335
+ initialIndex,
336
+ initialRemoteBundles: remoteBundles,
337
+ relationTypes: store.getRelationTypes(),
338
+ authoringService,
339
+ liveAuthoringService,
340
+ producerService: options.producerService,
341
+ allowWrite: options.allowWrite,
342
+ actor: options.actor,
343
+ allowAuthoring: options.allowAuthoring,
344
+ allowRuntimeRemoteLoad: options.allowRuntimeRemoteLoad,
345
+ allowComputationAuthoring: options.allowComputationAuthoring,
346
+ strictLinks: options.strictLinks,
347
+ allowCustomRelationTypes: true,
348
+ repositoryMappings: options.repositoryMappings,
349
+ languages: options.languages,
350
+ });
351
+ return attachEmbeddings(rootState, embeddingSettings(null, options), {
352
+ root: options.rootPath,
353
+ write: Boolean(options.allowWrite),
354
+ });
355
+ }
356
+ const remoteBundles = await fetchRemoteBundles(options?.remoteBundles || []);
357
+ const localBundleArgs = (bundleArgs || []).slice();
358
+ const liveAuthoringService = options?.liveAuthoringService
359
+ ? options.liveAuthoringService
360
+ : options?.allowWrite && options.authoringService?.store
361
+ ? new LiveAuthoringService(options.authoringService.store, {
362
+ actor: options.actor,
363
+ gitCommit: options.gitCommit,
364
+ writePolicy: options.writePolicy,
365
+ })
366
+ : null;
367
+ if (options?.allowWrite && !liveAuthoringService) {
368
+ throw new Error("Live OKF authoring requires --root or --project and a configured actor.");
369
+ }
370
+ return createState(localBundleArgs, {
371
+ initialIndex: buildIndex(localBundleArgs.concat(remoteBundles), {
372
+ strictLinks: options?.strictLinks,
373
+ allowCustomRelationTypes: true,
374
+ }),
375
+ initialRemoteBundles: remoteBundles,
376
+ authoringService: options?.authoringService,
377
+ liveAuthoringService,
378
+ producerService: options?.producerService,
379
+ allowWrite: options?.allowWrite,
380
+ actor: options?.actor,
381
+ allowAuthoring: options?.allowAuthoring,
382
+ allowRuntimeRemoteLoad: options?.allowRuntimeRemoteLoad,
383
+ allowComputationAuthoring: options?.allowComputationAuthoring,
384
+ strictLinks: options?.strictLinks,
385
+ allowCustomRelationTypes: true,
386
+ repositoryMappings: options?.repositoryMappings,
387
+ languages: options?.languages,
388
+ });
389
+ }
390
+
391
+ function registerMcpInterface(state) {
392
+ const server = new McpServer(
393
+ {
394
+ name: "okf-mcp",
395
+ version: packageMetadata.version,
396
+ },
397
+ {
398
+ capabilities: {
399
+ resources: { listChanged: false },
400
+ tools: { listChanged: false },
401
+ },
402
+ },
403
+ );
404
+ let pendingToolCall = Promise.resolve();
405
+ const resources = new ResourceTemplate("okf://{+locator}", {
406
+ list: async () => listResources(state.index),
407
+ });
408
+ server.registerResource(
409
+ "okf-documents",
410
+ resources,
411
+ {
412
+ description: "Markdown documents in the loaded Open Knowledge Format catalog.",
413
+ mimeType: "text/markdown",
414
+ },
415
+ async (uri) => readResource(state.index, uri.href),
416
+ );
417
+ registry.names
418
+ .filter((name) => toolEnabled(registry.tools[name], state))
419
+ .forEach((name) => {
420
+ const definition = registry.tools[name];
421
+ server.registerTool(
422
+ name,
423
+ {
424
+ description: definition.description,
425
+ annotations: definition.annotations,
426
+ inputSchema: fromJsonSchema(definition.inputSchema),
427
+ ...(definition.outputSchema
428
+ ? { outputSchema: fromJsonSchema(definition.outputSchema) }
429
+ : {}),
430
+ },
431
+ async (args) => {
432
+ const current = pendingToolCall.then(async () => {
433
+ try {
434
+ return await callTool(state, name, args);
435
+ } catch {
436
+ return jsonContent(
437
+ {
438
+ error: "Internal tool error",
439
+ tool: name,
440
+ },
441
+ { isError: true },
442
+ );
443
+ }
444
+ });
445
+ pendingToolCall = current.catch(() => {});
446
+ return current;
447
+ },
448
+ );
449
+ });
450
+ return server;
451
+ }
452
+
453
+ async function createMcpServer(bundleArgs, options) {
454
+ return registerMcpInterface(await createStateAsync(bundleArgs, options));
455
+ }
456
+
457
+ async function runStdioServer(bundleArgs, input, output, options) {
458
+ const state = await createStateAsync(bundleArgs, options);
459
+ const transport = new StdioServerTransport(input, output, {
460
+ maxBufferSize: MAX_MCP_MESSAGE_BYTES,
461
+ });
462
+ return serveStdio(() => registerMcpInterface(state), { legacy: "serve", transport });
463
+ }
464
+
465
+ module.exports = {
466
+ createMcpServer,
467
+ runStdioServer,
468
+ /** @internal Exposed for tests that need the server state behind a tool call. */
469
+ callTool,
470
+ /** @internal */
471
+ createStateAsync,
472
+ };