@mfdaves/okf-mcp 0.9.1 → 0.13.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 (115) hide show
  1. package/CHANGELOG.md +100 -0
  2. package/README.md +452 -26
  3. package/bin/okf-mcp.js +6 -1
  4. package/okf/okf-mcp/distribution/reference-bundle.md +10 -3
  5. package/okf/okf-mcp/index.md +2 -1
  6. package/okf/okf-mcp/interfaces/http-authoring-api.md +11 -2
  7. package/okf/okf-mcp/interfaces/mcp-http.md +64 -0
  8. package/okf/okf-mcp/interfaces/mcp-tools.md +25 -6
  9. package/okf/okf-mcp/overview/okf-mcp.md +16 -6
  10. package/okf/okf-mcp/policies/authoring-safety.md +28 -5
  11. package/okf/okf-mcp/runtime/indexer.md +14 -1
  12. package/okf/okf-mcp/runtime/mcp-server.md +16 -8
  13. package/okf/okf-mcp/specs/producer-api.md +16 -2
  14. package/package.json +17 -5
  15. package/server.json +38 -2
  16. package/src/assets.js +165 -73
  17. package/src/authoring/candidates.js +434 -0
  18. package/src/authoring/git-preflight.js +225 -0
  19. package/src/authoring/git-publish.js +783 -0
  20. package/src/authoring/live.js +757 -0
  21. package/src/authoring/paths.js +112 -0
  22. package/src/authoring/policy-hook.js +221 -0
  23. package/src/authoring/proposal-policy.js +159 -0
  24. package/src/authoring/receipts.js +373 -0
  25. package/src/authoring/render.js +38 -0
  26. package/src/authoring/shared.js +75 -0
  27. package/src/authoring/staging.js +216 -0
  28. package/src/authoring.js +386 -287
  29. package/src/cache/files.js +147 -0
  30. package/src/cache/lock.js +201 -0
  31. package/src/cache/paths.js +197 -0
  32. package/src/cache/store.js +703 -0
  33. package/src/catalog-text.js +19 -0
  34. package/src/cli/commands.js +448 -0
  35. package/src/cli/http-options.js +193 -0
  36. package/src/cli/options.js +554 -0
  37. package/src/cli/usage.js +96 -0
  38. package/src/cli.js +18 -932
  39. package/src/computation.js +99 -61
  40. package/src/context/assemble.js +567 -0
  41. package/src/context/cli-options.js +88 -0
  42. package/src/context/score.js +234 -0
  43. package/src/context/sections.js +274 -0
  44. package/src/embed/interface.js +160 -0
  45. package/src/embed/openai.js +715 -0
  46. package/src/embed/prepare.js +182 -0
  47. package/src/embed/units.js +96 -0
  48. package/src/error-details.js +53 -0
  49. package/src/git-source.js +112 -52
  50. package/src/graph.js +95 -37
  51. package/src/http-server.js +36 -17
  52. package/src/index.js +15 -0
  53. package/src/indexer/assemble.js +566 -0
  54. package/src/indexer/build.js +290 -0
  55. package/src/indexer/cache.js +81 -0
  56. package/src/indexer/edges.js +430 -0
  57. package/src/indexer/index.js +44 -0
  58. package/src/indexer/paths.js +178 -0
  59. package/src/indexer/resolve.js +282 -0
  60. package/src/indexer/update.js +720 -0
  61. package/src/indexer.js +3 -1068
  62. package/src/live-authoring.js +4 -2329
  63. package/src/markdown.js +21 -16
  64. package/src/mcp/auth.js +409 -0
  65. package/src/mcp/http.js +317 -0
  66. package/src/mcp/principal.js +59 -0
  67. package/src/mcp/registry.js +356 -0
  68. package/src/mcp/resources.js +45 -0
  69. package/src/mcp/server.js +567 -0
  70. package/src/mcp/tools/catalog.js +247 -0
  71. package/src/mcp/tools/computation.js +83 -0
  72. package/src/mcp/tools/context.js +133 -0
  73. package/src/mcp/tools/graph.js +167 -0
  74. package/src/mcp/tools/live-authoring.js +316 -0
  75. package/src/mcp/tools/migration.js +86 -0
  76. package/src/mcp/tools/producers.js +79 -0
  77. package/src/mcp/tools/proposals.js +225 -0
  78. package/src/mcp/tools/provenance.js +87 -0
  79. package/src/mcp/tools/remote.js +79 -0
  80. package/src/mcp/tools/search.js +242 -0
  81. package/src/mcp-server.js +3 -1611
  82. package/src/migration.js +431 -253
  83. package/src/parser.js +245 -130
  84. package/src/plugins.js +71 -48
  85. package/src/policy/write-policy.js +713 -0
  86. package/src/producer-publisher.js +202 -78
  87. package/src/producers.js +311 -103
  88. package/src/project.js +346 -93
  89. package/src/remote.js +96 -61
  90. package/src/search/cli-options.js +107 -0
  91. package/src/search/confidence.js +61 -0
  92. package/src/search/dense.js +304 -0
  93. package/src/search/embedding-cli.js +57 -0
  94. package/src/search/embedding-config.js +217 -0
  95. package/src/search/fusion.js +249 -0
  96. package/src/search/hybrid.js +526 -0
  97. package/src/search/languages.js +200 -0
  98. package/src/search/lexical.js +695 -0
  99. package/src/search/query.js +620 -0
  100. package/src/search/stem/among.js +43 -0
  101. package/src/search/stem/base-stemmer.js +311 -0
  102. package/src/search/stem/en-regions.js +456 -0
  103. package/src/search/stem/en-suffixes.js +664 -0
  104. package/src/search/stem/en-tables.js +176 -0
  105. package/src/search/stem/en.js +238 -0
  106. package/src/search/stem/it-regions.js +459 -0
  107. package/src/search/stem/it-suffixes.js +471 -0
  108. package/src/search/stem/it-tables.js +257 -0
  109. package/src/search/stem/it.js +155 -0
  110. package/src/search-index.js +2 -81
  111. package/src/search.js +2 -252
  112. package/src/store.js +134 -81
  113. package/src/tool-packs.js +346 -0
  114. package/src/v02.js +301 -105
  115. package/src/validation.js +24 -20
@@ -0,0 +1,282 @@
1
+ "use strict";
2
+
3
+ const path = require("node:path");
4
+ const { normalizeSlashes } = require("../parser");
5
+
6
+ function portableConceptKeys(value) {
7
+ const normalized = normalizeSlashes(String(value || ""))
8
+ .replace(/^\/+/, "")
9
+ .split("#")[0];
10
+ if (!normalized) return [];
11
+ return normalized.toLowerCase().endsWith(".md")
12
+ ? [normalized, normalized.slice(0, -3)]
13
+ : [normalized, `${normalized}.md`];
14
+ }
15
+
16
+ function portableConceptMatches(index, value) {
17
+ for (const key of portableConceptKeys(value)) {
18
+ const matches = (index.documents || []).filter(
19
+ (doc) => doc.conceptId === key || doc.path === key,
20
+ );
21
+ if (matches.length) {
22
+ return matches.sort((left, right) => left.uri.localeCompare(right.uri));
23
+ }
24
+ }
25
+ return [];
26
+ }
27
+
28
+ function resolveConcept(index, locator) {
29
+ const raw = String(locator || "").trim();
30
+ if (!raw || !index) {
31
+ return null;
32
+ }
33
+ const fragmentless = normalizeSlashes(raw).split("#")[0];
34
+ const byUri = index.byUri && (index.byUri.get(raw) || index.byUri.get(fragmentless));
35
+ if (byUri) {
36
+ return byUri;
37
+ }
38
+ if (
39
+ (index.ambiguousAliases || new Set()).has(raw) ||
40
+ (index.ambiguousAliases || new Set()).has(fragmentless)
41
+ ) {
42
+ return null;
43
+ }
44
+ const uriMatch = fragmentless.match(/^okf:\/\/([^/]+)\/(.+)$/);
45
+ if (fragmentless.startsWith("okf://")) {
46
+ if (!uriMatch || (index.bundles || []).some((bundle) => bundle.id === uriMatch[1])) {
47
+ return null;
48
+ }
49
+ }
50
+ for (const key of portableConceptKeys(
51
+ uriMatch ? `${uriMatch[1]}/${uriMatch[2]}` : fragmentless,
52
+ )) {
53
+ if ((index.ambiguousConceptIds || new Set()).has(key)) return null;
54
+ const owner = index.byConceptId?.get(key);
55
+ if (owner) return owner;
56
+ }
57
+ return null;
58
+ }
59
+
60
+ function normalizeConceptTitle(value) {
61
+ return String(value || "")
62
+ .normalize("NFKC")
63
+ .trim()
64
+ .replace(/\s+/gu, " ")
65
+ .toLowerCase();
66
+ }
67
+
68
+ function conceptTitleSlug(value) {
69
+ return normalizeConceptTitle(value)
70
+ .replace(/[^a-z0-9]+/g, "-")
71
+ .replace(/^-+|-+$/g, "");
72
+ }
73
+
74
+ function conceptIsGeneratedFile(doc) {
75
+ const frontmatter = doc?.frontmatter || {};
76
+ return Boolean(
77
+ (doc && (doc.generatedFile === true || doc.isGenerated === true)) ||
78
+ frontmatter.generated_file === true ||
79
+ frontmatter.generatedFile === true,
80
+ );
81
+ }
82
+
83
+ function conceptMatchSummary(doc, matchReasons) {
84
+ const generated = doc?.signals?.generated;
85
+ return {
86
+ uri: doc.uri,
87
+ bundle: doc.bundle,
88
+ path: doc.path,
89
+ conceptId: doc.conceptId || doc.path.replace(/\.md$/i, ""),
90
+ type: doc.type || doc.frontmatter?.type,
91
+ title: doc.title,
92
+ generatedBy: generated?.by || null,
93
+ ...(conceptIsGeneratedFile(doc) ? { generatedFile: true } : {}),
94
+ ...(matchReasons?.length ? { matchReasons } : {}),
95
+ };
96
+ }
97
+
98
+ function findConceptMatches(index, options) {
99
+ const config = options || {};
100
+ const title = config.title === undefined ? null : normalizeConceptTitle(config.title);
101
+ const prefix = normalizeSlashes(String(config.pathPrefix || "")).replace(/^\/+|\/+$/g, "");
102
+ const documents =
103
+ index && Array.isArray(index.concepts)
104
+ ? index.concepts
105
+ : index && Array.isArray(index.documents)
106
+ ? index.documents
107
+ : [];
108
+ return documents
109
+ .filter(
110
+ (doc) =>
111
+ doc &&
112
+ doc.valid !== false &&
113
+ !doc.reserved &&
114
+ typeof doc.path === "string" &&
115
+ (!config.bundle || doc.bundle === config.bundle) &&
116
+ (!config.type || doc.type === config.type) &&
117
+ (title === null || normalizeConceptTitle(doc.title) === title) &&
118
+ (!prefix || doc.path === prefix || doc.path.startsWith(`${prefix}/`)),
119
+ )
120
+ .sort(
121
+ (left, right) => left.path.localeCompare(right.path) || left.uri.localeCompare(right.uri),
122
+ );
123
+ }
124
+
125
+ function recoveryReceipt(locator, entries, limit, allowRetry, forcedAmbiguity) {
126
+ const maximum = Math.max(1, Math.min(Number(limit || 5), 20));
127
+ const candidates = entries
128
+ .slice(0, maximum)
129
+ .map((entry) => conceptMatchSummary(entry.doc, entry.reasons));
130
+ const actionable = entries.length === 1 && entries[0].doc.valid && !entries[0].doc.reserved;
131
+ return {
132
+ status:
133
+ forcedAmbiguity || entries.length > 1
134
+ ? "ambiguous"
135
+ : actionable
136
+ ? "replacement_found"
137
+ : "not_found",
138
+ requestedLocator: locator,
139
+ candidates,
140
+ omitted: Math.max(0, entries.length - candidates.length),
141
+ ...(allowRetry && !forcedAmbiguity && actionable
142
+ ? { retryWith: { uri: entries[0].doc.uri } }
143
+ : {}),
144
+ };
145
+ }
146
+
147
+ function recoverConceptLocator(index, locator, options) {
148
+ const config = options || {};
149
+ const raw = normalizeSlashes(String(locator || "").trim()).split("#")[0];
150
+ const uriMatch = raw.match(/^okf:\/\/([^/]+)\/(.+)$/);
151
+ if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(raw) && !uriMatch) {
152
+ return { status: "not_found", requestedLocator: raw, candidates: [], omitted: 0 };
153
+ }
154
+ const knownBundle = uriMatch && (index.bundles || []).some((entry) => entry.id === uriMatch[1]);
155
+ const bundle = knownBundle ? uriMatch[1] : config.bundle || "";
156
+ const portablePath = (
157
+ uriMatch && knownBundle ? uriMatch[2] : raw.replace(/^okf:\/\//, "")
158
+ ).replace(/^\/+/, "");
159
+ const aliasOwners = (index.documents || [])
160
+ .filter(
161
+ (doc) =>
162
+ (index.ambiguousAliases || new Set()).has(raw) && (doc.uriAliases || []).includes(raw),
163
+ )
164
+ .sort((left, right) => left.uri.localeCompare(right.uri));
165
+ const exact = aliasOwners.length
166
+ ? aliasOwners
167
+ : knownBundle
168
+ ? []
169
+ : portableConceptMatches(index, portablePath);
170
+ if (exact.length) {
171
+ const portableAmbiguous = portableConceptKeys(portablePath).some((key) =>
172
+ (index.ambiguousConceptIds || new Set()).has(key),
173
+ );
174
+ return recoveryReceipt(
175
+ raw,
176
+ exact.map((doc) => ({
177
+ doc,
178
+ reasons: [aliasOwners.length ? "uri_alias" : "portable_id"],
179
+ })),
180
+ config.limit,
181
+ !aliasOwners.length && !portableAmbiguous,
182
+ aliasOwners.length > 0 || portableAmbiguous,
183
+ );
184
+ }
185
+ const requestedPath = portablePath.replace(/\.md$/i, "");
186
+ const requestedBase = path.posix.basename(requestedPath).toLowerCase();
187
+ const requestedSlug = conceptTitleSlug(requestedBase);
188
+ const ranked = [];
189
+ if (!requestedSlug) return recoveryReceipt(raw, [], config.limit, false);
190
+ findConceptMatches(index, { bundle }).forEach((doc) => {
191
+ const base = path.posix.basename(doc.conceptId || doc.path.replace(/\.md$/i, "")).toLowerCase();
192
+ const reasons = [];
193
+ if (base === requestedBase) reasons.push("path_basename");
194
+ if (conceptTitleSlug(doc.title) === requestedSlug) reasons.push("title_slug");
195
+ if ((doc.aliases || []).some((alias) => conceptTitleSlug(alias) === requestedSlug))
196
+ reasons.push("alias");
197
+ if (!reasons.length) return;
198
+ ranked.push({
199
+ doc,
200
+ reasons,
201
+ score:
202
+ (reasons.includes("path_basename") ? 4 : 0) +
203
+ (reasons.includes("title_slug") ? 2 : 0) +
204
+ (reasons.includes("alias") ? 1 : 0),
205
+ });
206
+ });
207
+ ranked.sort(
208
+ (left, right) =>
209
+ right.score - left.score ||
210
+ left.doc.path.localeCompare(right.doc.path) ||
211
+ left.doc.uri.localeCompare(right.doc.uri),
212
+ );
213
+ return recoveryReceipt(raw, ranked, config.limit, true);
214
+ }
215
+
216
+ function conceptSignals(doc, detailed) {
217
+ const signals = doc.signals || {};
218
+ const computation = signals.computation;
219
+ const output = {
220
+ status: signals.status,
221
+ staleAfter: signals.staleAfter,
222
+ freshness: signals.freshness,
223
+ asOf: signals.asOf,
224
+ trustTier: signals.trustTier,
225
+ sourceCount: Array.isArray(signals.sources) ? signals.sources.length : 0,
226
+ hasSources: Array.isArray(signals.sources) && signals.sources.length > 0,
227
+ sourcesOrigin: signals.sourcesOrigin,
228
+ generated: signals.generated,
229
+ generatedOrigin: signals.generatedOrigin,
230
+ computation: computation
231
+ ? {
232
+ runtime: computation.runtime,
233
+ // The computation block is null when the contract has no usable
234
+ // source; the summary keeps that null rather than dropping the key.
235
+ mode: computation.computation ? computation.computation.mode : null,
236
+ attestationReady: Boolean(computation.attestationReady),
237
+ structuralReady: Boolean(computation.structuralReady),
238
+ assetsReady: Boolean(computation.assetsReady),
239
+ }
240
+ : null,
241
+ };
242
+ if (detailed) {
243
+ output.resource = signals.resource;
244
+ output.sources = signals.sources || [];
245
+ output.usageWindow = signals.usageWindow;
246
+ output.verifiedEvents = signals.verifiedEvents || [];
247
+ output.diagnostics = signals.diagnostics || [];
248
+ if (computation) {
249
+ output.computation = Object.assign({}, computation);
250
+ }
251
+ }
252
+ return output;
253
+ }
254
+
255
+ function conceptSummary(doc) {
256
+ return {
257
+ uri: doc.uri,
258
+ bundle: doc.bundle,
259
+ path: doc.path,
260
+ pathUri: doc.pathUri,
261
+ conceptId: doc.conceptId,
262
+ uriAliases: doc.uriAliases || [],
263
+ type: doc.type,
264
+ title: doc.title,
265
+ description: doc.description,
266
+ tags: doc.tags,
267
+ aliases: doc.aliases,
268
+ signals: conceptSignals(doc, false),
269
+ };
270
+ }
271
+
272
+ module.exports = {
273
+ conceptIsGeneratedFile,
274
+ conceptMatchSummary,
275
+ conceptSignals,
276
+ conceptSummary,
277
+ findConceptMatches,
278
+ normalizeConceptTitle,
279
+ portableConceptKeys,
280
+ recoverConceptLocator,
281
+ resolveConcept,
282
+ };