@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.
- package/CHANGELOG.md +69 -0
- package/README.md +176 -19
- package/bin/okf-mcp.js +6 -1
- package/okf/okf-mcp/policies/authoring-safety.md +11 -1
- package/package.json +17 -5
- package/server.json +2 -2
- package/src/assets.js +165 -73
- package/src/authoring/candidates.js +391 -0
- package/src/authoring/git-preflight.js +225 -0
- package/src/authoring/git-publish.js +776 -0
- package/src/authoring/live.js +789 -0
- package/src/authoring/paths.js +112 -0
- package/src/authoring/policy-hook.js +221 -0
- package/src/authoring/proposal-policy.js +137 -0
- package/src/authoring/receipts.js +329 -0
- package/src/authoring/render.js +38 -0
- package/src/authoring/shared.js +75 -0
- package/src/authoring/staging.js +216 -0
- package/src/authoring.js +386 -287
- package/src/cache/files.js +147 -0
- package/src/cache/lock.js +201 -0
- package/src/cache/paths.js +197 -0
- package/src/cache/store.js +703 -0
- package/src/catalog-text.js +19 -0
- package/src/cli.js +184 -151
- package/src/computation.js +99 -61
- package/src/context/assemble.js +567 -0
- package/src/context/cli-options.js +88 -0
- package/src/context/score.js +234 -0
- package/src/context/sections.js +274 -0
- package/src/embed/interface.js +160 -0
- package/src/embed/openai.js +715 -0
- package/src/embed/prepare.js +182 -0
- package/src/embed/units.js +96 -0
- package/src/git-source.js +112 -52
- package/src/graph.js +95 -37
- package/src/http-server.js +36 -17
- package/src/index.js +15 -0
- package/src/indexer/assemble.js +566 -0
- package/src/indexer/build.js +290 -0
- package/src/indexer/cache.js +81 -0
- package/src/indexer/edges.js +430 -0
- package/src/indexer/index.js +44 -0
- package/src/indexer/paths.js +178 -0
- package/src/indexer/resolve.js +282 -0
- package/src/indexer/update.js +720 -0
- package/src/indexer.js +3 -1068
- package/src/live-authoring.js +4 -2329
- package/src/markdown.js +21 -16
- package/src/mcp/registry.js +328 -0
- package/src/mcp/resources.js +45 -0
- package/src/mcp/server.js +472 -0
- package/src/mcp/tools/catalog.js +244 -0
- package/src/mcp/tools/computation.js +83 -0
- package/src/mcp/tools/context.js +133 -0
- package/src/mcp/tools/graph.js +167 -0
- package/src/mcp/tools/live-authoring.js +316 -0
- package/src/mcp/tools/migration.js +86 -0
- package/src/mcp/tools/producers.js +79 -0
- package/src/mcp/tools/proposals.js +213 -0
- package/src/mcp/tools/provenance.js +87 -0
- package/src/mcp/tools/remote.js +79 -0
- package/src/mcp/tools/search.js +242 -0
- package/src/mcp-server.js +3 -1611
- package/src/migration.js +431 -253
- package/src/parser.js +245 -130
- package/src/plugins.js +71 -48
- package/src/policy/write-policy.js +713 -0
- package/src/producer-publisher.js +195 -77
- package/src/producers.js +265 -101
- package/src/project.js +277 -93
- package/src/remote.js +96 -61
- package/src/search/cli-options.js +107 -0
- package/src/search/confidence.js +61 -0
- package/src/search/dense.js +304 -0
- package/src/search/embedding-cli.js +57 -0
- package/src/search/embedding-config.js +217 -0
- package/src/search/fusion.js +249 -0
- package/src/search/hybrid.js +526 -0
- package/src/search/languages.js +200 -0
- package/src/search/lexical.js +695 -0
- package/src/search/query.js +620 -0
- package/src/search/stem/among.js +43 -0
- package/src/search/stem/base-stemmer.js +311 -0
- package/src/search/stem/en-regions.js +456 -0
- package/src/search/stem/en-suffixes.js +664 -0
- package/src/search/stem/en-tables.js +176 -0
- package/src/search/stem/en.js +238 -0
- package/src/search/stem/it-regions.js +459 -0
- package/src/search/stem/it-suffixes.js +471 -0
- package/src/search/stem/it-tables.js +257 -0
- package/src/search/stem/it.js +155 -0
- package/src/search-index.js +2 -81
- package/src/search.js +2 -252
- package/src/store.js +134 -81
- package/src/v02.js +301 -105
- 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
|
+
};
|