@mfdaves/okf-mcp 0.3.3 → 0.5.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/.agents/skills/okf-v02-migration/SKILL.md +37 -0
- package/.agents/skills/okf-v02-migration/agents/openai.yaml +6 -0
- package/.agents/skills/okf-v02-migration/references/field-mapping.md +26 -0
- package/README.md +217 -79
- package/okf/bundles/okf-mcp/distribution/reference-bundle.md +2 -2
- package/okf/bundles/okf-mcp/index.md +7 -0
- package/okf/bundles/okf-mcp/interfaces/http-authoring-api.md +2 -2
- package/okf/bundles/okf-mcp/interfaces/mcp-tools.md +9 -5
- package/okf/bundles/okf-mcp/overview/okf-mcp.md +2 -2
- package/okf/bundles/okf-mcp/policies/authoring-safety.md +5 -3
- package/okf/bundles/okf-mcp/runtime/file-concept-store.md +7 -5
- package/okf/bundles/okf-mcp/runtime/indexer.md +6 -4
- package/okf/bundles/okf-mcp/runtime/mcp-server.md +7 -7
- package/okf/bundles/okf-mcp/specs/attested-computation.md +24 -0
- package/okf/bundles/okf-mcp/specs/concept-format.md +5 -3
- package/okf/bundles/okf-mcp/specs/git-sources.md +23 -0
- package/okf/bundles/okf-mcp/workflows/v02-migration.md +24 -0
- package/package.json +10 -3
- package/server.json +5 -5
- package/src/assets.js +469 -0
- package/src/authoring.js +492 -20
- package/src/cli.js +468 -37
- package/src/computation.js +366 -0
- package/src/git-source.js +551 -0
- package/src/graph.js +71 -18
- package/src/http-server.js +8 -1
- package/src/index.js +5 -0
- package/src/indexer.js +428 -24
- package/src/markdown.js +129 -0
- package/src/mcp-server.js +450 -315
- package/src/migration.js +687 -0
- package/src/parser.js +135 -54
- package/src/plugins.js +30 -50
- package/src/project.js +74 -17
- package/src/remote.js +232 -17
- package/src/search-index.js +83 -0
- package/src/search.js +103 -47
- package/src/store.js +421 -25
- package/src/v02.js +545 -0
- package/src/validation.js +13 -2
- package/src/mcp-protocol.js +0 -283
|
@@ -0,0 +1,366 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const crypto = require("crypto");
|
|
4
|
+
const { mimeIsText } = require("./assets");
|
|
5
|
+
const { conceptSignals, resolveConcept } = require("./indexer");
|
|
6
|
+
const { normalizeV02Signals } = require("./v02");
|
|
7
|
+
|
|
8
|
+
function requireConcept(index, uri) {
|
|
9
|
+
const doc = resolveConcept(index, uri);
|
|
10
|
+
if (!doc || !doc.valid || doc.reserved) {
|
|
11
|
+
throw new Error(`Unknown valid OKF concept: ${uri || "<missing>"}`);
|
|
12
|
+
}
|
|
13
|
+
return doc;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
function sha256(value) {
|
|
17
|
+
return `sha256:${crypto.createHash("sha256").update(value).digest("hex")}`;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
function stableJson(value) {
|
|
21
|
+
if (Array.isArray(value)) {
|
|
22
|
+
return `[${value.map(stableJson).join(",")}]`;
|
|
23
|
+
}
|
|
24
|
+
if (value && typeof value === "object") {
|
|
25
|
+
return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
|
|
26
|
+
}
|
|
27
|
+
return JSON.stringify(value);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
function contractEdges(index, doc) {
|
|
31
|
+
return index.edges.filter((edge) => (
|
|
32
|
+
edge.source === doc.uri
|
|
33
|
+
&& ["computation", "executor", "attester"].includes(edge.kind)
|
|
34
|
+
));
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function targetMetadata(index, edge) {
|
|
38
|
+
if (!edge) {
|
|
39
|
+
return { resolved: false, resolvedAs: "missing", uri: null };
|
|
40
|
+
}
|
|
41
|
+
const asset = index.byAssetUri && index.byAssetUri.get(edge.target);
|
|
42
|
+
if (asset) {
|
|
43
|
+
const resolved = !edge.broken && (!mimeIsText(asset.mimeType) || asset.kind === "text");
|
|
44
|
+
return {
|
|
45
|
+
resolved,
|
|
46
|
+
resolvedAs: resolved ? "asset" : "invalid_text_asset",
|
|
47
|
+
uri: asset.uri,
|
|
48
|
+
bundle: asset.bundle,
|
|
49
|
+
path: asset.path,
|
|
50
|
+
mimeType: asset.mimeType,
|
|
51
|
+
bytes: asset.size,
|
|
52
|
+
sha256: asset.sha256,
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
const concept = index.byUri && index.byUri.get(edge.target);
|
|
56
|
+
if (concept) {
|
|
57
|
+
const resolved = !edge.broken && !concept.reserved && concept.valid;
|
|
58
|
+
return {
|
|
59
|
+
resolved,
|
|
60
|
+
resolvedAs: resolved ? "concept" : "invalid_concept",
|
|
61
|
+
uri: concept.uri,
|
|
62
|
+
bundle: concept.bundle,
|
|
63
|
+
path: concept.path,
|
|
64
|
+
mimeType: "text/markdown",
|
|
65
|
+
bytes: Buffer.byteLength(concept.text, "utf8"),
|
|
66
|
+
sha256: sha256(concept.text),
|
|
67
|
+
};
|
|
68
|
+
}
|
|
69
|
+
return {
|
|
70
|
+
resolved: !edge.broken && ["asset", "concept"].includes(edge.resolvedAs),
|
|
71
|
+
resolvedAs: edge.resolvedAs || (edge.external ? "external" : "unresolved"),
|
|
72
|
+
uri: edge.target,
|
|
73
|
+
externalDeclared: Boolean(edge.external),
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function signalsFor(index, doc, asOf) {
|
|
78
|
+
if (!asOf) {
|
|
79
|
+
return doc.signals;
|
|
80
|
+
}
|
|
81
|
+
const normalized = normalizeV02Signals(doc, { asOf });
|
|
82
|
+
if (normalized.computation && doc.signals && doc.signals.computation) {
|
|
83
|
+
normalized.computation.structuralReady = normalized.computation.ready;
|
|
84
|
+
normalized.computation.assetsReady = doc.signals.computation.assetsReady;
|
|
85
|
+
normalized.computation.attestationReady = Boolean(
|
|
86
|
+
normalized.computation.structuralReady && normalized.computation.assetsReady,
|
|
87
|
+
);
|
|
88
|
+
normalized.computation.ready = normalized.computation.attestationReady;
|
|
89
|
+
}
|
|
90
|
+
return normalized;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
function inspectAttestedComputation(index, uri, options) {
|
|
94
|
+
const config = options || {};
|
|
95
|
+
const doc = requireConcept(index, uri);
|
|
96
|
+
const signals = signalsFor(index, doc, config.asOf);
|
|
97
|
+
const contract = signals && signals.computation;
|
|
98
|
+
if (!contract) {
|
|
99
|
+
throw new Error(`Concept is not an Attested Computation: ${doc.uri}`);
|
|
100
|
+
}
|
|
101
|
+
const edges = contractEdges(index, doc);
|
|
102
|
+
const computationEdge = edges.find((edge) => edge.kind === "computation");
|
|
103
|
+
const executorEdge = edges.find((edge) => edge.kind === "executor");
|
|
104
|
+
const attesterEdge = edges.find((edge) => edge.kind === "attester");
|
|
105
|
+
let computation;
|
|
106
|
+
if (contract.computation && contract.computation.mode === "inline") {
|
|
107
|
+
const content = contract.computation.content || "";
|
|
108
|
+
const bytes = Buffer.byteLength(content, "utf8");
|
|
109
|
+
const maxContentBytes = Number(config.maxContentBytes || 65536);
|
|
110
|
+
computation = {
|
|
111
|
+
mode: "inline",
|
|
112
|
+
language: contract.computation.language || "",
|
|
113
|
+
resolved: true,
|
|
114
|
+
bytes,
|
|
115
|
+
sha256: sha256(content),
|
|
116
|
+
contentIncluded: Boolean(config.includeComputation && bytes <= maxContentBytes),
|
|
117
|
+
...(config.includeComputation && bytes <= maxContentBytes ? { content } : {}),
|
|
118
|
+
};
|
|
119
|
+
} else {
|
|
120
|
+
computation = Object.assign({
|
|
121
|
+
mode: contract.computation && contract.computation.mode || "missing",
|
|
122
|
+
resource: contract.computation && contract.computation.path || null,
|
|
123
|
+
contentIncluded: false,
|
|
124
|
+
}, targetMetadata(index, computationEdge));
|
|
125
|
+
if (config.includeComputation && computation.resolvedAs === "asset") {
|
|
126
|
+
const asset = index.byAssetUri.get(computation.uri);
|
|
127
|
+
const maxContentBytes = Number(config.maxContentBytes || 65536);
|
|
128
|
+
if (asset.kind === "text" && asset.size <= maxContentBytes) {
|
|
129
|
+
computation.content = asset.text;
|
|
130
|
+
computation.contentIncluded = true;
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
const executor = Object.assign({
|
|
135
|
+
resource: contract.executor && contract.executor.resource || null,
|
|
136
|
+
receiptFields: contract.executor && contract.executor.receipt || [],
|
|
137
|
+
}, targetMetadata(index, executorEdge));
|
|
138
|
+
const attester = Object.assign({
|
|
139
|
+
resource: contract.attester && contract.attester.resource || null,
|
|
140
|
+
}, targetMetadata(index, attesterEdge));
|
|
141
|
+
const assetDiagnostics = (index.warnings || []).filter((entry) => (
|
|
142
|
+
entry.bundle === doc.bundle
|
|
143
|
+
&& entry.path === doc.path
|
|
144
|
+
&& String(entry.code || "").startsWith("asset_")
|
|
145
|
+
));
|
|
146
|
+
return {
|
|
147
|
+
uri: doc.uri,
|
|
148
|
+
requestedUri: uri,
|
|
149
|
+
runtime: contract.runtime,
|
|
150
|
+
parameters: contract.parameters || [],
|
|
151
|
+
computation,
|
|
152
|
+
executor,
|
|
153
|
+
attester,
|
|
154
|
+
signals: conceptSignals(Object.assign({}, doc, { signals }), false),
|
|
155
|
+
readiness: {
|
|
156
|
+
structuralContractValid: Boolean(contract.structuralReady),
|
|
157
|
+
assetsResolved: Boolean(contract.assetsReady),
|
|
158
|
+
attestationReady: Boolean(contract.attestationReady),
|
|
159
|
+
},
|
|
160
|
+
capabilities: {
|
|
161
|
+
execution: "not_supported",
|
|
162
|
+
attestation: "not_supported",
|
|
163
|
+
},
|
|
164
|
+
diagnostics: (signals.diagnostics || []).concat(assetDiagnostics),
|
|
165
|
+
};
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
function prepareAttestedComputation(index, uri, parameters, options) {
|
|
169
|
+
const inspection = inspectAttestedComputation(index, uri, options);
|
|
170
|
+
if (!inspection.readiness.attestationReady) {
|
|
171
|
+
throw new Error("Attested Computation is not statically ready.");
|
|
172
|
+
}
|
|
173
|
+
if (!inspection.computation.sha256) {
|
|
174
|
+
throw new Error("Attested Computation has no statically verified computation digest.");
|
|
175
|
+
}
|
|
176
|
+
if (!parameters || typeof parameters !== "object" || Array.isArray(parameters)) {
|
|
177
|
+
throw new Error("parameters must be an object keyed by declared parameter name.");
|
|
178
|
+
}
|
|
179
|
+
const declared = inspection.parameters || [];
|
|
180
|
+
const declaredNames = declared.map((entry) => entry.name);
|
|
181
|
+
const presentNames = Object.keys(parameters).sort();
|
|
182
|
+
const missing = declared.filter((entry) => entry.required && !Object.prototype.hasOwnProperty.call(parameters, entry.name)).map((entry) => entry.name);
|
|
183
|
+
const unexpected = presentNames.filter((name) => !declaredNames.includes(name));
|
|
184
|
+
if (missing.length || unexpected.length) {
|
|
185
|
+
throw new Error(`Parameter contract mismatch (missing: ${missing.join(", ") || "none"}; unexpected: ${unexpected.join(", ") || "none"}).`);
|
|
186
|
+
}
|
|
187
|
+
return {
|
|
188
|
+
prepared: true,
|
|
189
|
+
uri: inspection.uri,
|
|
190
|
+
runtime: inspection.runtime,
|
|
191
|
+
parameterNames: presentNames,
|
|
192
|
+
parameterDigest: sha256(stableJson(parameters)),
|
|
193
|
+
computationDigest: inspection.computation.sha256 || null,
|
|
194
|
+
expectedReceiptFields: inspection.executor.receiptFields,
|
|
195
|
+
lifecycle: {
|
|
196
|
+
status: inspection.signals.status,
|
|
197
|
+
freshness: inspection.signals.freshness,
|
|
198
|
+
asOf: inspection.signals.asOf,
|
|
199
|
+
},
|
|
200
|
+
executionPerformed: false,
|
|
201
|
+
valuesReturned: false,
|
|
202
|
+
};
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
function checkComputationReceipt(index, uri, receipt) {
|
|
206
|
+
const inspection = inspectAttestedComputation(index, uri);
|
|
207
|
+
if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
|
|
208
|
+
throw new Error("receipt must be an object.");
|
|
209
|
+
}
|
|
210
|
+
const expectedFields = inspection.executor.receiptFields || [];
|
|
211
|
+
const presentFields = Object.keys(receipt).sort();
|
|
212
|
+
const missingFields = expectedFields.filter((field) => !Object.prototype.hasOwnProperty.call(receipt, field));
|
|
213
|
+
const unexpectedFields = presentFields.filter((field) => !expectedFields.includes(field));
|
|
214
|
+
return {
|
|
215
|
+
uri: inspection.uri,
|
|
216
|
+
shapeComplete: missingFields.length === 0 && unexpectedFields.length === 0,
|
|
217
|
+
expectedFields,
|
|
218
|
+
presentFields,
|
|
219
|
+
missingFields,
|
|
220
|
+
unexpectedFields,
|
|
221
|
+
attestationPerformed: false,
|
|
222
|
+
receiptPersisted: false,
|
|
223
|
+
valuesReturned: false,
|
|
224
|
+
};
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
function readBundleAsset(index, input) {
|
|
228
|
+
const args = input || {};
|
|
229
|
+
const asset = args.uri
|
|
230
|
+
? index.byAssetUri && index.byAssetUri.get(args.uri)
|
|
231
|
+
: index.byAssetKey && index.byAssetKey.get(`${args.bundle}\u0000${String(args.path || "").replace(/\\/g, "/")}`);
|
|
232
|
+
if (!asset) {
|
|
233
|
+
throw new Error("Unknown or unreferenced bundle asset.");
|
|
234
|
+
}
|
|
235
|
+
const maxContentBytes = Number(args.maxContentBytes || 65536);
|
|
236
|
+
if (!Number.isSafeInteger(maxContentBytes) || maxContentBytes < 1 || maxContentBytes > 1024 * 1024) {
|
|
237
|
+
throw new Error("maxContentBytes must be between 1 and 1048576.");
|
|
238
|
+
}
|
|
239
|
+
if (asset.size > maxContentBytes) {
|
|
240
|
+
throw new Error(`Asset exceeds requested content limit of ${maxContentBytes} bytes.`);
|
|
241
|
+
}
|
|
242
|
+
let content;
|
|
243
|
+
let contentEncoding;
|
|
244
|
+
if (asset.kind === "text") {
|
|
245
|
+
content = asset.text;
|
|
246
|
+
contentEncoding = "utf-8";
|
|
247
|
+
} else if (asset.base64) {
|
|
248
|
+
content = asset.base64;
|
|
249
|
+
contentEncoding = "base64";
|
|
250
|
+
} else if (asset._contentBytes) {
|
|
251
|
+
const bytes = asset._contentBytes;
|
|
252
|
+
if (bytes.length !== asset.size || sha256(bytes) !== asset.sha256) {
|
|
253
|
+
throw new Error("Indexed asset content does not match its recorded digest.");
|
|
254
|
+
}
|
|
255
|
+
content = bytes.toString("base64");
|
|
256
|
+
contentEncoding = "base64";
|
|
257
|
+
} else {
|
|
258
|
+
throw new Error("Indexed asset content is unavailable.");
|
|
259
|
+
}
|
|
260
|
+
return {
|
|
261
|
+
uri: asset.uri,
|
|
262
|
+
bundle: asset.bundle,
|
|
263
|
+
path: asset.path,
|
|
264
|
+
mimeType: asset.mimeType,
|
|
265
|
+
size: asset.size,
|
|
266
|
+
sha256: asset.sha256,
|
|
267
|
+
kind: asset.kind,
|
|
268
|
+
contentEncoding,
|
|
269
|
+
content,
|
|
270
|
+
referencedBy: asset.referencedBy || [],
|
|
271
|
+
remote: Boolean(asset.remote),
|
|
272
|
+
};
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
function getProvenance(index, uri, options) {
|
|
276
|
+
const config = options || {};
|
|
277
|
+
const root = requireConcept(index, uri);
|
|
278
|
+
const maxDepth = Math.max(0, Math.min(Number(config.maxDepth === undefined ? 3 : config.maxDepth), 10));
|
|
279
|
+
const maxNodes = Math.max(1, Math.min(Number(config.maxNodes || 100), 1000));
|
|
280
|
+
const includeExternal = config.includeExternal === true;
|
|
281
|
+
const nodes = [];
|
|
282
|
+
const edges = [];
|
|
283
|
+
const cycles = [];
|
|
284
|
+
const unresolved = [];
|
|
285
|
+
const seen = new Set();
|
|
286
|
+
const queue = [{ uri: root.uri, depth: 0, ancestry: [root.uri] }];
|
|
287
|
+
let truncated = false;
|
|
288
|
+
while (queue.length) {
|
|
289
|
+
const current = queue.shift();
|
|
290
|
+
if (seen.has(current.uri)) {
|
|
291
|
+
continue;
|
|
292
|
+
}
|
|
293
|
+
if (nodes.length >= maxNodes) {
|
|
294
|
+
truncated = true;
|
|
295
|
+
break;
|
|
296
|
+
}
|
|
297
|
+
seen.add(current.uri);
|
|
298
|
+
const doc = index.byUri.get(current.uri);
|
|
299
|
+
nodes.push({
|
|
300
|
+
id: doc.uri,
|
|
301
|
+
kind: "concept",
|
|
302
|
+
bundle: doc.bundle,
|
|
303
|
+
path: doc.path,
|
|
304
|
+
title: doc.title,
|
|
305
|
+
signals: conceptSignals(doc, false),
|
|
306
|
+
});
|
|
307
|
+
if (current.depth >= maxDepth) {
|
|
308
|
+
continue;
|
|
309
|
+
}
|
|
310
|
+
index.edges.filter((edge) => edge.source === doc.uri && edge.kind === "source").forEach((edge) => {
|
|
311
|
+
const targetDoc = index.byUri.get(edge.target);
|
|
312
|
+
const targetAsset = index.byAssetUri && index.byAssetUri.get(edge.target);
|
|
313
|
+
if (targetDoc) {
|
|
314
|
+
edges.push(edge);
|
|
315
|
+
if (current.ancestry.includes(targetDoc.uri)) {
|
|
316
|
+
cycles.push(current.ancestry.concat(targetDoc.uri));
|
|
317
|
+
} else {
|
|
318
|
+
queue.push({ uri: targetDoc.uri, depth: current.depth + 1, ancestry: current.ancestry.concat(targetDoc.uri) });
|
|
319
|
+
}
|
|
320
|
+
} else if (targetAsset) {
|
|
321
|
+
edges.push(edge);
|
|
322
|
+
if (!seen.has(targetAsset.uri) && nodes.length < maxNodes) {
|
|
323
|
+
seen.add(targetAsset.uri);
|
|
324
|
+
nodes.push({
|
|
325
|
+
id: targetAsset.uri,
|
|
326
|
+
kind: "asset",
|
|
327
|
+
bundle: targetAsset.bundle,
|
|
328
|
+
path: targetAsset.path,
|
|
329
|
+
mimeType: targetAsset.mimeType,
|
|
330
|
+
size: targetAsset.size,
|
|
331
|
+
sha256: targetAsset.sha256,
|
|
332
|
+
});
|
|
333
|
+
}
|
|
334
|
+
} else if (edge.external || edge.resolvedAs === "opaque") {
|
|
335
|
+
if (includeExternal) {
|
|
336
|
+
edges.push(edge);
|
|
337
|
+
if (!seen.has(edge.target) && nodes.length < maxNodes) {
|
|
338
|
+
seen.add(edge.target);
|
|
339
|
+
nodes.push({ id: edge.target, kind: edge.resolvedAs === "opaque" ? "opaque" : "external" });
|
|
340
|
+
}
|
|
341
|
+
}
|
|
342
|
+
} else {
|
|
343
|
+
unresolved.push({ source: edge.source, resource: edge.reference, field: edge.field });
|
|
344
|
+
}
|
|
345
|
+
});
|
|
346
|
+
}
|
|
347
|
+
return {
|
|
348
|
+
root: root.uri,
|
|
349
|
+
requestedUri: uri,
|
|
350
|
+
nodes,
|
|
351
|
+
edges,
|
|
352
|
+
cycles,
|
|
353
|
+
unresolved,
|
|
354
|
+
truncated,
|
|
355
|
+
externalFetched: false,
|
|
356
|
+
};
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
module.exports = {
|
|
360
|
+
checkComputationReceipt,
|
|
361
|
+
getProvenance,
|
|
362
|
+
inspectAttestedComputation,
|
|
363
|
+
prepareAttestedComputation,
|
|
364
|
+
readBundleAsset,
|
|
365
|
+
requireConcept,
|
|
366
|
+
};
|