@mfdaves/okf-mcp 0.6.0 → 0.8.0
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/README.md +24 -18
- package/okf/bundles/okf-mcp/interfaces/mcp-tools.md +12 -6
- package/okf/bundles/okf-mcp/policies/authoring-safety.md +9 -3
- package/okf/bundles/okf-mcp/runtime/file-concept-store.md +1 -1
- package/okf/bundles/okf-mcp/runtime/mcp-server.md +2 -2
- package/okf/bundles/okf-mcp/specs/concept-format.md +1 -1
- package/okf/bundles/okf-mcp/specs/git-sources.md +1 -1
- package/okf/bundles/okf-mcp/workflows/concept-authoring.md +1 -1
- package/package.json +1 -1
- package/server.json +2 -2
- package/src/authoring.js +105 -11
- package/src/cli.js +1 -1
- package/src/git-source.js +13 -4
- package/src/graph.js +2 -2
- package/src/indexer.js +158 -7
- package/src/live-authoring.js +1537 -151
- package/src/mcp-server.js +245 -42
- package/src/search.js +19 -0
package/src/indexer.js
CHANGED
|
@@ -171,23 +171,169 @@ function registerPortableConceptId(map, ambiguous, key, document) {
|
|
|
171
171
|
map.set(normalized, document);
|
|
172
172
|
}
|
|
173
173
|
|
|
174
|
+
function portableConceptKeys(value) {
|
|
175
|
+
const normalized = normalizeSlashes(String(value || ""))
|
|
176
|
+
.replace(/^\/+/, "")
|
|
177
|
+
.split("#")[0];
|
|
178
|
+
if (!normalized) return [];
|
|
179
|
+
return normalized.toLowerCase().endsWith(".md")
|
|
180
|
+
? [normalized, normalized.slice(0, -3)]
|
|
181
|
+
: [normalized, `${normalized}.md`];
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
function portableConceptMatches(index, value) {
|
|
185
|
+
for (const key of portableConceptKeys(value)) {
|
|
186
|
+
const matches = (index.documents || []).filter((doc) => doc.conceptId === key || doc.path === key);
|
|
187
|
+
if (matches.length) {
|
|
188
|
+
return matches.sort((left, right) => left.uri.localeCompare(right.uri));
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
return [];
|
|
192
|
+
}
|
|
193
|
+
|
|
174
194
|
function resolveConcept(index, locator) {
|
|
175
195
|
const raw = String(locator || "").trim();
|
|
176
196
|
if (!raw || !index) {
|
|
177
197
|
return null;
|
|
178
198
|
}
|
|
179
|
-
const
|
|
199
|
+
const fragmentless = normalizeSlashes(raw).split("#")[0];
|
|
200
|
+
const byUri = index.byUri && (index.byUri.get(raw) || index.byUri.get(fragmentless));
|
|
180
201
|
if (byUri) {
|
|
181
202
|
return byUri;
|
|
182
203
|
}
|
|
183
|
-
|
|
184
|
-
|
|
204
|
+
if ((index.ambiguousAliases || new Set()).has(raw)
|
|
205
|
+
|| (index.ambiguousAliases || new Set()).has(fragmentless)) {
|
|
185
206
|
return null;
|
|
186
207
|
}
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|| index.
|
|
190
|
-
|
|
208
|
+
const uriMatch = fragmentless.match(/^okf:\/\/([^/]+)\/(.+)$/);
|
|
209
|
+
if (fragmentless.startsWith("okf://")) {
|
|
210
|
+
if (!uriMatch || (index.bundles || []).some((bundle) => bundle.id === uriMatch[1])) {
|
|
211
|
+
return null;
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
for (const key of portableConceptKeys(uriMatch ? `${uriMatch[1]}/${uriMatch[2]}` : fragmentless)) {
|
|
215
|
+
if ((index.ambiguousConceptIds || new Set()).has(key)) return null;
|
|
216
|
+
const owner = index.byConceptId && index.byConceptId.get(key);
|
|
217
|
+
if (owner) return owner;
|
|
218
|
+
}
|
|
219
|
+
return null;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
function normalizeConceptTitle(value) {
|
|
223
|
+
return String(value || "").normalize("NFKC").trim().replace(/\s+/gu, " ").toLowerCase();
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
function conceptTitleSlug(value) {
|
|
227
|
+
return normalizeConceptTitle(value)
|
|
228
|
+
.replace(/[^a-z0-9]+/g, "-")
|
|
229
|
+
.replace(/^-+|-+$/g, "");
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
function conceptIsGeneratedFile(doc) {
|
|
233
|
+
const frontmatter = doc && doc.frontmatter || {};
|
|
234
|
+
return Boolean(doc && (doc.generatedFile === true || doc.isGenerated === true)
|
|
235
|
+
|| frontmatter.generated_file === true || frontmatter.generatedFile === true);
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
function conceptMatchSummary(doc, matchReasons) {
|
|
239
|
+
const generated = doc && doc.signals && doc.signals.generated;
|
|
240
|
+
return {
|
|
241
|
+
uri: doc.uri,
|
|
242
|
+
bundle: doc.bundle,
|
|
243
|
+
path: doc.path,
|
|
244
|
+
conceptId: doc.conceptId || doc.path.replace(/\.md$/i, ""),
|
|
245
|
+
type: doc.type || doc.frontmatter && doc.frontmatter.type,
|
|
246
|
+
title: doc.title,
|
|
247
|
+
generatedBy: generated && generated.by || null,
|
|
248
|
+
...(conceptIsGeneratedFile(doc) ? { generatedFile: true } : {}),
|
|
249
|
+
...(matchReasons && matchReasons.length ? { matchReasons } : {}),
|
|
250
|
+
};
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
function findConceptMatches(index, options) {
|
|
254
|
+
const config = options || {};
|
|
255
|
+
const title = config.title === undefined ? null : normalizeConceptTitle(config.title);
|
|
256
|
+
const prefix = normalizeSlashes(String(config.pathPrefix || "")).replace(/^\/+|\/+$/g, "");
|
|
257
|
+
const documents = index && Array.isArray(index.concepts)
|
|
258
|
+
? index.concepts
|
|
259
|
+
: index && Array.isArray(index.documents) ? index.documents : [];
|
|
260
|
+
return documents
|
|
261
|
+
.filter((doc) => (
|
|
262
|
+
doc && doc.valid !== false && !doc.reserved
|
|
263
|
+
&& typeof doc.path === "string"
|
|
264
|
+
&& (!config.bundle || doc.bundle === config.bundle)
|
|
265
|
+
&& (!config.type || doc.type === config.type)
|
|
266
|
+
&& (title === null || normalizeConceptTitle(doc.title) === title)
|
|
267
|
+
&& (!prefix || doc.path === prefix || doc.path.startsWith(`${prefix}/`))
|
|
268
|
+
))
|
|
269
|
+
.sort((left, right) => left.path.localeCompare(right.path) || left.uri.localeCompare(right.uri));
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
function recoveryReceipt(locator, entries, limit, allowRetry, forcedAmbiguity) {
|
|
273
|
+
const maximum = Math.max(1, Math.min(Number(limit || 5), 20));
|
|
274
|
+
const candidates = entries.slice(0, maximum)
|
|
275
|
+
.map((entry) => conceptMatchSummary(entry.doc, entry.reasons));
|
|
276
|
+
const actionable = entries.length === 1 && entries[0].doc.valid && !entries[0].doc.reserved;
|
|
277
|
+
return {
|
|
278
|
+
status: forcedAmbiguity || entries.length > 1 ? "ambiguous"
|
|
279
|
+
: actionable ? "replacement_found" : "not_found",
|
|
280
|
+
requestedLocator: locator,
|
|
281
|
+
candidates,
|
|
282
|
+
omitted: Math.max(0, entries.length - candidates.length),
|
|
283
|
+
...(allowRetry && !forcedAmbiguity && actionable
|
|
284
|
+
? { retryWith: { uri: entries[0].doc.uri } } : {}),
|
|
285
|
+
};
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
function recoverConceptLocator(index, locator, options) {
|
|
289
|
+
const config = options || {};
|
|
290
|
+
const raw = normalizeSlashes(String(locator || "").trim()).split("#")[0];
|
|
291
|
+
const uriMatch = raw.match(/^okf:\/\/([^/]+)\/(.+)$/);
|
|
292
|
+
if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(raw) && !uriMatch) {
|
|
293
|
+
return { status: "not_found", requestedLocator: raw, candidates: [], omitted: 0 };
|
|
294
|
+
}
|
|
295
|
+
const knownBundle = uriMatch && (index.bundles || []).some((entry) => entry.id === uriMatch[1]);
|
|
296
|
+
const bundle = knownBundle ? uriMatch[1] : config.bundle || "";
|
|
297
|
+
const portablePath = (uriMatch && knownBundle
|
|
298
|
+
? uriMatch[2]
|
|
299
|
+
: raw.replace(/^okf:\/\//, ""))
|
|
300
|
+
.replace(/^\/+/, "");
|
|
301
|
+
const aliasOwners = (index.documents || []).filter((doc) => (
|
|
302
|
+
(index.ambiguousAliases || new Set()).has(raw) && (doc.uriAliases || []).includes(raw)
|
|
303
|
+
)).sort((left, right) => left.uri.localeCompare(right.uri));
|
|
304
|
+
const exact = aliasOwners.length ? aliasOwners : knownBundle ? [] : portableConceptMatches(index, portablePath);
|
|
305
|
+
if (exact.length) {
|
|
306
|
+
const portableAmbiguous = portableConceptKeys(portablePath)
|
|
307
|
+
.some((key) => (index.ambiguousConceptIds || new Set()).has(key));
|
|
308
|
+
return recoveryReceipt(raw, exact.map((doc) => ({
|
|
309
|
+
doc, reasons: [aliasOwners.length ? "uri_alias" : "portable_id"],
|
|
310
|
+
})), config.limit, !aliasOwners.length && !portableAmbiguous,
|
|
311
|
+
aliasOwners.length > 0 || portableAmbiguous);
|
|
312
|
+
}
|
|
313
|
+
const requestedPath = portablePath.replace(/\.md$/i, "");
|
|
314
|
+
const requestedBase = path.posix.basename(requestedPath).toLowerCase();
|
|
315
|
+
const requestedSlug = conceptTitleSlug(requestedBase);
|
|
316
|
+
const ranked = [];
|
|
317
|
+
if (!requestedSlug) return recoveryReceipt(raw, [], config.limit, false);
|
|
318
|
+
findConceptMatches(index, { bundle }).forEach((doc) => {
|
|
319
|
+
const base = path.posix.basename(doc.conceptId || doc.path.replace(/\.md$/i, "")).toLowerCase();
|
|
320
|
+
const reasons = [];
|
|
321
|
+
if (base === requestedBase) reasons.push("path_basename");
|
|
322
|
+
if (conceptTitleSlug(doc.title) === requestedSlug) reasons.push("title_slug");
|
|
323
|
+
if ((doc.aliases || []).some((alias) => conceptTitleSlug(alias) === requestedSlug)) reasons.push("alias");
|
|
324
|
+
if (!reasons.length) return;
|
|
325
|
+
ranked.push({
|
|
326
|
+
doc,
|
|
327
|
+
reasons,
|
|
328
|
+
score: (reasons.includes("path_basename") ? 4 : 0)
|
|
329
|
+
+ (reasons.includes("title_slug") ? 2 : 0)
|
|
330
|
+
+ (reasons.includes("alias") ? 1 : 0),
|
|
331
|
+
});
|
|
332
|
+
});
|
|
333
|
+
ranked.sort((left, right) => right.score - left.score
|
|
334
|
+
|| left.doc.path.localeCompare(right.doc.path)
|
|
335
|
+
|| left.doc.uri.localeCompare(right.doc.uri));
|
|
336
|
+
return recoveryReceipt(raw, ranked, config.limit, true);
|
|
191
337
|
}
|
|
192
338
|
|
|
193
339
|
function resolveIndexedLink(bundleId, resolved, href, documentsByPath) {
|
|
@@ -900,10 +1046,15 @@ module.exports = {
|
|
|
900
1046
|
attachProject,
|
|
901
1047
|
conceptSummary,
|
|
902
1048
|
conceptSignals,
|
|
1049
|
+
conceptIsGeneratedFile,
|
|
1050
|
+
conceptMatchSummary,
|
|
903
1051
|
bundleAllowsPath,
|
|
904
1052
|
bundleExcludesPath,
|
|
1053
|
+
findConceptMatches,
|
|
905
1054
|
loadProjectBundles,
|
|
1055
|
+
normalizeConceptTitle,
|
|
906
1056
|
parseBundleArg,
|
|
1057
|
+
recoverConceptLocator,
|
|
907
1058
|
resolveLinkPath,
|
|
908
1059
|
resolveConcept,
|
|
909
1060
|
semanticReferences,
|