@mfdaves/okf-mcp 0.9.1 → 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 +172 -17
  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/graph.js CHANGED
@@ -52,7 +52,16 @@ function boundedInteger(value, fallback, min, max) {
52
52
  function docsByFilter(index, options) {
53
53
  const includeReserved = Boolean(options && options.includeReserved);
54
54
  const docs = includeReserved ? index.documents : index.concepts;
55
- if (!options || (!options.bundle && !options.type && !options.types && !options.tag && !options.tagsAny && !options.tagsAll && !options.pathPrefix)) {
55
+ if (
56
+ !options ||
57
+ (!options.bundle &&
58
+ !options.type &&
59
+ !options.types &&
60
+ !options.tag &&
61
+ !options.tagsAny &&
62
+ !options.tagsAll &&
63
+ !options.pathPrefix)
64
+ ) {
56
65
  return docs;
57
66
  }
58
67
  const conceptUris = new Set(applyFilters(index, options).map((doc) => doc.uri));
@@ -134,7 +143,13 @@ function getNeighbors(index, uri, options) {
134
143
  outbound.push({ edge, node: nodeFor(index.byUri.get(edge.target)) });
135
144
  } else if (edge.source === canonical && edge.external && options && options.includeExternal) {
136
145
  outbound.push({ edge, node: externalNodeFor(edge.target) });
137
- } else if (edge.source === canonical && options && options.includeAssets && index.byAssetUri && index.byAssetUri.has(edge.target)) {
146
+ } else if (
147
+ edge.source === canonical &&
148
+ options &&
149
+ options.includeAssets &&
150
+ index.byAssetUri &&
151
+ index.byAssetUri.has(edge.target)
152
+ ) {
138
153
  outbound.push({ edge, node: assetNodeFor(index.byAssetUri.get(edge.target)) });
139
154
  }
140
155
  if (edge.target === canonical && index.byUri.has(edge.source)) {
@@ -145,31 +160,51 @@ function getNeighbors(index, uri, options) {
145
160
  }
146
161
 
147
162
  function getSubgraph(index, options) {
148
- const requestedSeeds = Array.isArray(options && options.seeds) ? options.seeds : [options && options.uri].filter(Boolean);
163
+ const requestedSeeds = Array.isArray(options && options.seeds)
164
+ ? options.seeds
165
+ : [options && options.uri].filter(Boolean);
149
166
  const seeds = Array.from(new Set(requestedSeeds.map((uri) => canonicalUri(index, uri))));
150
167
  const depth = boundedInteger(options && options.depth, 1, 0, 10);
151
168
  const maxNodes = boundedInteger(options && options.maxNodes, 50, 1, 1000);
152
- const allowedUris = new Set((options && options.includeReserved ? index.documents : index.concepts).map((doc) => doc.uri));
169
+ const allowedUris = new Set(
170
+ (options && options.includeReserved ? index.documents : index.concepts).map((doc) => doc.uri),
171
+ );
153
172
  const seen = new Set();
154
173
  let frontier = seeds.filter((uri) => allowedUris.has(uri));
155
174
  frontier.forEach((uri) => seen.add(uri));
156
175
  for (let level = 0; level < depth && frontier.length && seen.size < maxNodes; level += 1) {
157
176
  const next = [];
158
- index.edges.filter((edge) => !edge.broken && edgeAllowed(edge, options)).forEach((edge) => {
159
- if (frontier.includes(edge.source) && allowedUris.has(edge.target) && !seen.has(edge.target)) {
160
- seen.add(edge.target);
161
- next.push(edge.target);
162
- }
163
- if (frontier.includes(edge.target) && allowedUris.has(edge.source) && !seen.has(edge.source)) {
164
- seen.add(edge.source);
165
- next.push(edge.source);
166
- }
167
- });
177
+ index.edges
178
+ .filter((edge) => !edge.broken && edgeAllowed(edge, options))
179
+ .forEach((edge) => {
180
+ if (
181
+ frontier.includes(edge.source) &&
182
+ allowedUris.has(edge.target) &&
183
+ !seen.has(edge.target)
184
+ ) {
185
+ seen.add(edge.target);
186
+ next.push(edge.target);
187
+ }
188
+ if (
189
+ frontier.includes(edge.target) &&
190
+ allowedUris.has(edge.source) &&
191
+ !seen.has(edge.source)
192
+ ) {
193
+ seen.add(edge.source);
194
+ next.push(edge.source);
195
+ }
196
+ });
168
197
  frontier = next.slice(0, Math.max(0, maxNodes - seen.size));
169
198
  }
170
- const nodes = Array.from(seen).map((uri) => index.byUri.get(uri)).filter(Boolean).map(nodeFor);
199
+ const nodes = Array.from(seen)
200
+ .map((uri) => index.byUri.get(uri))
201
+ .filter(Boolean)
202
+ .map(nodeFor);
171
203
  const uris = new Set(nodes.map((node) => node.id));
172
- const edges = index.edges.filter((edge) => !edge.broken && edgeAllowed(edge, options) && uris.has(edge.source) && uris.has(edge.target));
204
+ const edges = index.edges.filter(
205
+ (edge) =>
206
+ !edge.broken && edgeAllowed(edge, options) && uris.has(edge.source) && uris.has(edge.target),
207
+ );
173
208
  return trimGraph(nodes, edges, Object.assign({}, options, { maxNodes }));
174
209
  }
175
210
 
@@ -178,12 +213,14 @@ function findPaths(index, source, target, maxPaths, options) {
178
213
  const canonicalTarget = canonicalUri(index, target);
179
214
  const limit = boundedInteger(maxPaths, 3, 1, 50);
180
215
  const adjacency = new Map();
181
- index.edges.filter((edge) => !edge.broken && edgeAllowed(edge, options)).forEach((edge) => {
182
- if (!adjacency.has(edge.source)) {
183
- adjacency.set(edge.source, new Set());
184
- }
185
- adjacency.get(edge.source).add(edge.target);
186
- });
216
+ index.edges
217
+ .filter((edge) => !edge.broken && edgeAllowed(edge, options))
218
+ .forEach((edge) => {
219
+ if (!adjacency.has(edge.source)) {
220
+ adjacency.set(edge.source, new Set());
221
+ }
222
+ adjacency.get(edge.source).add(edge.target);
223
+ });
187
224
  const queue = [[canonicalSource]];
188
225
  const paths = [];
189
226
  const bestDepth = new Map([[canonicalSource, 0]]);
@@ -225,8 +262,10 @@ function graphSummary(index) {
225
262
  byBundle[doc.bundle] = (byBundle[doc.bundle] || 0) + 1;
226
263
  const signals = doc.signals || {};
227
264
  byStatus[signals.status || "unknown"] = (byStatus[signals.status || "unknown"] || 0) + 1;
228
- byTrustTier[signals.trustTier || "unverified"] = (byTrustTier[signals.trustTier || "unverified"] || 0) + 1;
229
- byFreshness[signals.freshness || "unspecified"] = (byFreshness[signals.freshness || "unspecified"] || 0) + 1;
265
+ byTrustTier[signals.trustTier || "unverified"] =
266
+ (byTrustTier[signals.trustTier || "unverified"] || 0) + 1;
267
+ byFreshness[signals.freshness || "unspecified"] =
268
+ (byFreshness[signals.freshness || "unspecified"] || 0) + 1;
230
269
  if (signals.computation) {
231
270
  const runtime = signals.computation.runtime || "invalid";
232
271
  byRuntime[runtime] = (byRuntime[runtime] || 0) + 1;
@@ -240,19 +279,24 @@ function graphSummary(index) {
240
279
  });
241
280
  const inbound = new Map();
242
281
  const outbound = new Map();
243
- index.edges.filter((edge) => !edge.broken).forEach((edge) => {
244
- byEdgeKind[edge.kind] = (byEdgeKind[edge.kind] || 0) + 1;
245
- outbound.set(edge.source, (outbound.get(edge.source) || 0) + 1);
246
- inbound.set(edge.target, (inbound.get(edge.target) || 0) + 1);
247
- if (edge.kind === "relation") {
248
- byRelationType[edge.relationType] = (byRelationType[edge.relationType] || 0) + 1;
249
- }
250
- });
282
+ index.edges
283
+ .filter((edge) => !edge.broken)
284
+ .forEach((edge) => {
285
+ byEdgeKind[edge.kind] = (byEdgeKind[edge.kind] || 0) + 1;
286
+ outbound.set(edge.source, (outbound.get(edge.source) || 0) + 1);
287
+ inbound.set(edge.target, (inbound.get(edge.target) || 0) + 1);
288
+ if (edge.kind === "relation") {
289
+ byRelationType[edge.relationType] = (byRelationType[edge.relationType] || 0) + 1;
290
+ }
291
+ });
251
292
  const orphanConcepts = index.concepts
252
293
  .filter((doc) => !inbound.get(doc.uri) && !outbound.get(doc.uri))
253
294
  .map((doc) => doc.uri);
254
295
  const topLinkedConcepts = index.concepts
255
- .map((doc) => ({ uri: doc.uri, links: (inbound.get(doc.uri) || 0) + (outbound.get(doc.uri) || 0) }))
296
+ .map((doc) => ({
297
+ uri: doc.uri,
298
+ links: (inbound.get(doc.uri) || 0) + (outbound.get(doc.uri) || 0),
299
+ }))
256
300
  .filter((entry) => entry.links > 0)
257
301
  .sort((a, b) => b.links - a.links || a.uri.localeCompare(b.uri))
258
302
  .slice(0, 10);
@@ -266,7 +310,11 @@ function graphSummary(index) {
266
310
  brokenLinks: index.edges.filter((edge) => edge.kind === "markdown_link" && edge.broken).length,
267
311
  brokenRelations: index.edges.filter((edge) => edge.kind === "relation" && edge.broken).length,
268
312
  relations: index.edges.filter((edge) => edge.kind === "relation").length,
269
- brokenSemanticReferences: index.edges.filter((edge) => ["resource", "source", "computation", "executor", "attester"].includes(edge.kind) && edge.broken).length,
313
+ brokenSemanticReferences: index.edges.filter(
314
+ (edge) =>
315
+ ["resource", "source", "computation", "executor", "attester"].includes(edge.kind) &&
316
+ edge.broken,
317
+ ).length,
270
318
  attestationReady,
271
319
  externalReferences: index.externalReferences ? index.externalReferences.length : 0,
272
320
  byBundle,
@@ -292,19 +340,29 @@ function exportGraph(index, options) {
292
340
  return JSON.stringify(graph, null, 2);
293
341
  }
294
342
  if (format === "dot") {
295
- const dot = (value) => String(value || "").replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r?\n/g, "\\n");
343
+ const dot = (value) =>
344
+ String(value || "")
345
+ .replace(/\\/g, "\\\\")
346
+ .replace(/"/g, '\\"')
347
+ .replace(/\r?\n/g, "\\n");
296
348
  const lines = ["digraph OKF {"];
297
349
  graph.nodes.forEach((node) => {
298
350
  lines.push(` "${dot(node.id)}" [label="${dot(node.title)}"];`);
299
351
  });
300
352
  graph.edges.forEach((edge) => {
301
- lines.push(` "${dot(edge.source)}" -> "${dot(edge.target)}" [label="${dot(edge.text || edge.relationType || edge.kind)}"];`);
353
+ lines.push(
354
+ ` "${dot(edge.source)}" -> "${dot(edge.target)}" [label="${dot(edge.text || edge.relationType || edge.kind)}"];`,
355
+ );
302
356
  });
303
357
  lines.push("}");
304
358
  return lines.join("\n");
305
359
  }
306
360
  if (format === "mermaid") {
307
- const mermaidLabel = (value) => String(value || "").replace(/"/g, "#quot;").replace(/\]/g, "#93;").replace(/\r?\n/g, " ");
361
+ const mermaidLabel = (value) =>
362
+ String(value || "")
363
+ .replace(/"/g, "#quot;")
364
+ .replace(/\]/g, "#93;")
365
+ .replace(/\r?\n/g, " ");
308
366
  const ids = new Map();
309
367
  graph.nodes.forEach((node, index) => ids.set(node.id, `N${index + 1}`));
310
368
  const lines = ["graph TD"];
@@ -65,11 +65,15 @@ function createHttpHandler(service, options) {
65
65
  return;
66
66
  }
67
67
  if (req.method === "GET" && url.pathname === "/v1/bundles") {
68
- sendJson(res, 200, service.store.getBundles().map((bundle) => ({
69
- id: bundle.id,
70
- include: bundle.include || [],
71
- exclude: bundle.exclude || [],
72
- })));
68
+ sendJson(
69
+ res,
70
+ 200,
71
+ service.store.getBundles().map((bundle) => ({
72
+ id: bundle.id,
73
+ include: bundle.include || [],
74
+ exclude: bundle.exclude || [],
75
+ })),
76
+ );
73
77
  return;
74
78
  }
75
79
  if (req.method === "POST" && url.pathname === "/v1/concepts/validate") {
@@ -92,10 +96,14 @@ function createHttpHandler(service, options) {
92
96
  }
93
97
  if (req.method === "GET" && url.pathname === "/v1/proposals") {
94
98
  requireWriteAuth(req, writeToken);
95
- sendJson(res, 200, await service.listProposals({
96
- bundle: url.searchParams.get("bundle") || "",
97
- status: url.searchParams.get("status") || "",
98
- }));
99
+ sendJson(
100
+ res,
101
+ 200,
102
+ await service.listProposals({
103
+ bundle: url.searchParams.get("bundle") || "",
104
+ status: url.searchParams.get("status") || "",
105
+ }),
106
+ );
99
107
  return;
100
108
  }
101
109
  const proposalMatch = url.pathname.match(/^\/v1\/proposals\/([^/]+)(?:\/(accept|reject))?$/);
@@ -112,7 +120,11 @@ function createHttpHandler(service, options) {
112
120
  if (proposalMatch && req.method === "POST" && proposalMatch[2] === "reject") {
113
121
  requireWriteAuth(req, writeToken);
114
122
  const body = await readBody(req);
115
- sendJson(res, 200, await service.rejectProposal({ proposalId: proposalMatch[1], reason: body.reason || "" }));
123
+ sendJson(
124
+ res,
125
+ 200,
126
+ await service.rejectProposal({ proposalId: proposalMatch[1], reason: body.reason || "" }),
127
+ );
116
128
  return;
117
129
  }
118
130
  sendJson(res, 404, { error: "Not found." });
@@ -124,13 +136,20 @@ function createHttpHandler(service, options) {
124
136
 
125
137
  async function runHttpServer(options) {
126
138
  const config = options || {};
127
- const store = config.store || (config.rootPath
128
- ? FileConceptStore.fromRoot(config.rootPath, {
129
- proposalRoot: config.proposalRoot,
130
- strictLinks: config.strictLinks,
131
- })
132
- : FileConceptStore.fromProject(config.projectPath, { proposalRoot: config.proposalRoot }));
133
- const service = config.service || new ConceptAuthoringService(store);
139
+ const store =
140
+ config.store ||
141
+ (config.rootPath
142
+ ? FileConceptStore.fromRoot(config.rootPath, {
143
+ proposalRoot: config.proposalRoot,
144
+ strictLinks: config.strictLinks,
145
+ })
146
+ : FileConceptStore.fromProject(config.projectPath, { proposalRoot: config.proposalRoot }));
147
+ // HTTP calls carry no actor: proposals are unattributed unless a host
148
+ // passes one, and the write policy (writePolicy in okf.project.yaml, or a
149
+ // parsed policy from the host) still applies to them.
150
+ const service =
151
+ config.service ||
152
+ new ConceptAuthoringService(store, { actor: config.actor, writePolicy: config.writePolicy });
134
153
  const server = http.createServer(createHttpHandler(service, { writeToken: config.writeToken }));
135
154
  const host = config.host || "127.0.0.1";
136
155
  const port = config.port === undefined || config.port === "" ? 8765 : Number(config.port);
package/src/index.js CHANGED
@@ -20,4 +20,19 @@ module.exports = {
20
20
  ...require("./store"),
21
21
  ...require("./http-server"),
22
22
  ...require("./mcp-server"),
23
+ ...require("./embed/interface"),
24
+ ...require("./embed/units"),
25
+ ...require("./embed/openai"),
26
+ ...require("./embed/prepare"),
27
+ ...require("./cache/store"),
28
+ ...require("./policy/write-policy"),
29
+ ...require("./context/sections"),
30
+ ...require("./context/assemble"),
31
+ // Hybrid retrieval (WP3c): dense scoring, fusion, the embedding runtime.
32
+ denseSearch: require("./search/dense").denseSearch,
33
+ DEFAULT_FUSION_ALPHA: require("./search/fusion").DEFAULT_FUSION_ALPHA,
34
+ fuseRankings: require("./search/fusion").fuseRankings,
35
+ openEmbeddingRuntime: require("./search/hybrid").openEmbeddingRuntime,
36
+ loadEmbeddingConfigFile: require("./search/embedding-config").loadEmbeddingConfigFile,
37
+ normalizeEmbeddingConfig: require("./search/embedding-config").normalizeEmbeddingConfig,
23
38
  };