@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.
- package/CHANGELOG.md +100 -0
- package/README.md +452 -26
- package/bin/okf-mcp.js +6 -1
- package/okf/okf-mcp/distribution/reference-bundle.md +10 -3
- package/okf/okf-mcp/index.md +2 -1
- package/okf/okf-mcp/interfaces/http-authoring-api.md +11 -2
- package/okf/okf-mcp/interfaces/mcp-http.md +64 -0
- package/okf/okf-mcp/interfaces/mcp-tools.md +25 -6
- package/okf/okf-mcp/overview/okf-mcp.md +16 -6
- package/okf/okf-mcp/policies/authoring-safety.md +28 -5
- package/okf/okf-mcp/runtime/indexer.md +14 -1
- package/okf/okf-mcp/runtime/mcp-server.md +16 -8
- package/okf/okf-mcp/specs/producer-api.md +16 -2
- package/package.json +17 -5
- package/server.json +38 -2
- package/src/assets.js +165 -73
- package/src/authoring/candidates.js +434 -0
- package/src/authoring/git-preflight.js +225 -0
- package/src/authoring/git-publish.js +783 -0
- package/src/authoring/live.js +757 -0
- package/src/authoring/paths.js +112 -0
- package/src/authoring/policy-hook.js +221 -0
- package/src/authoring/proposal-policy.js +159 -0
- package/src/authoring/receipts.js +373 -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/commands.js +448 -0
- package/src/cli/http-options.js +193 -0
- package/src/cli/options.js +554 -0
- package/src/cli/usage.js +96 -0
- package/src/cli.js +18 -932
- 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/error-details.js +53 -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/auth.js +409 -0
- package/src/mcp/http.js +317 -0
- package/src/mcp/principal.js +59 -0
- package/src/mcp/registry.js +356 -0
- package/src/mcp/resources.js +45 -0
- package/src/mcp/server.js +567 -0
- package/src/mcp/tools/catalog.js +247 -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 +225 -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 +202 -78
- package/src/producers.js +311 -103
- package/src/project.js +346 -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/tool-packs.js +346 -0
- package/src/v02.js +301 -105
- package/src/validation.js +24 -20
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const fs = require("node:fs");
|
|
4
|
+
const path = require("path");
|
|
5
|
+
const {
|
|
6
|
+
conceptSignals,
|
|
7
|
+
conceptSummary,
|
|
8
|
+
recoverConceptLocator,
|
|
9
|
+
resolveConcept,
|
|
10
|
+
validateIndex,
|
|
11
|
+
} = require("../../indexer");
|
|
12
|
+
const { describeConceptGitSources } = require("../../git-source");
|
|
13
|
+
const { canWrite } = require("../principal");
|
|
14
|
+
const {
|
|
15
|
+
READ_ONLY,
|
|
16
|
+
ToolExecutionError,
|
|
17
|
+
defineTool,
|
|
18
|
+
jsonContent,
|
|
19
|
+
nonEmptyStringParameter,
|
|
20
|
+
} = require("../registry");
|
|
21
|
+
|
|
22
|
+
function publicBundles(index, options) {
|
|
23
|
+
return index.bundles.map((bundle) => {
|
|
24
|
+
const documentCount = index.documents.filter((doc) => doc.bundle === bundle.id).length;
|
|
25
|
+
const conceptCount = index.concepts.filter((doc) => doc.bundle === bundle.id).length;
|
|
26
|
+
const assetCount = (index.assets || []).filter((asset) => asset.bundle === bundle.id).length;
|
|
27
|
+
if (bundle.remote) {
|
|
28
|
+
return {
|
|
29
|
+
id: bundle.id,
|
|
30
|
+
remote: true,
|
|
31
|
+
provider: bundle.remoteSource && bundle.remoteSource.provider,
|
|
32
|
+
url: bundle.remoteSource && bundle.remoteSource.url,
|
|
33
|
+
ref: bundle.remoteSource && bundle.remoteSource.ref,
|
|
34
|
+
path: bundle.remoteSource && bundle.remoteSource.path,
|
|
35
|
+
fileCount: bundle.remoteSource && bundle.remoteSource.fileCount,
|
|
36
|
+
documentCount,
|
|
37
|
+
conceptCount,
|
|
38
|
+
assetCount,
|
|
39
|
+
okfVersion: bundle.okfVersion || null,
|
|
40
|
+
versionStatus: bundle.versionStatus,
|
|
41
|
+
revision: bundle.remoteSource && (bundle.remoteSource.commitSha || bundle.remoteSource.ref),
|
|
42
|
+
include: bundle.include || [],
|
|
43
|
+
exclude: bundle.exclude || [],
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
const absoluteRoot = path.resolve(bundle.root);
|
|
47
|
+
const projectRoot =
|
|
48
|
+
index.project && index.project.root ? path.resolve(index.project.root) : null;
|
|
49
|
+
const root = projectRoot
|
|
50
|
+
? path.relative(projectRoot, absoluteRoot).replace(/\\/g, "/") || "."
|
|
51
|
+
: "<configured>";
|
|
52
|
+
return {
|
|
53
|
+
id: bundle.id,
|
|
54
|
+
root,
|
|
55
|
+
...(options && options.includeAbsolutePaths ? { absoluteRoot, projectRoot } : {}),
|
|
56
|
+
documentCount,
|
|
57
|
+
conceptCount,
|
|
58
|
+
assetCount,
|
|
59
|
+
okfVersion: bundle.okfVersion || null,
|
|
60
|
+
versionStatus: bundle.versionStatus,
|
|
61
|
+
include: bundle.include || [],
|
|
62
|
+
exclude: bundle.exclude || [],
|
|
63
|
+
};
|
|
64
|
+
});
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function conceptLocator(args) {
|
|
68
|
+
return args && (args.id || args.uri)
|
|
69
|
+
? args.id || args.uri
|
|
70
|
+
: args && args.bundle && args.path
|
|
71
|
+
? `okf://${args.bundle}/${args.path}`
|
|
72
|
+
: null;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
function getConcept(index, args, repositoryMappings) {
|
|
76
|
+
const locator = conceptLocator(args);
|
|
77
|
+
const doc = resolveConcept(index, locator);
|
|
78
|
+
if (!doc) {
|
|
79
|
+
const recovery = recoverConceptLocator(index, locator, {
|
|
80
|
+
bundle: args && args.bundle,
|
|
81
|
+
limit: 5,
|
|
82
|
+
});
|
|
83
|
+
throw new ToolExecutionError(
|
|
84
|
+
`Unknown OKF concept URI or ID: ${locator || "<missing>"}`,
|
|
85
|
+
recovery.status === "ambiguous" ? "concept_locator_ambiguous" : "concept_not_found",
|
|
86
|
+
{ recovery },
|
|
87
|
+
);
|
|
88
|
+
}
|
|
89
|
+
if (!doc.valid || doc.reserved) {
|
|
90
|
+
throw new ToolExecutionError(`Locator is not a valid OKF concept: ${locator}`);
|
|
91
|
+
}
|
|
92
|
+
return Object.assign(conceptSummary(doc), {
|
|
93
|
+
frontmatter: doc.frontmatter,
|
|
94
|
+
body: doc.body,
|
|
95
|
+
links: doc.links,
|
|
96
|
+
signals: conceptSignals(doc, true),
|
|
97
|
+
referencedAssets: (index.assets || [])
|
|
98
|
+
.filter((asset) => (asset.referencedBy || []).some((reference) => reference.uri === doc.uri))
|
|
99
|
+
.map((asset) => ({
|
|
100
|
+
uri: asset.uri,
|
|
101
|
+
bundle: asset.bundle,
|
|
102
|
+
path: asset.path,
|
|
103
|
+
mimeType: asset.mimeType,
|
|
104
|
+
size: asset.size,
|
|
105
|
+
sha256: asset.sha256,
|
|
106
|
+
roles: asset.roles,
|
|
107
|
+
})),
|
|
108
|
+
gitSources: describeConceptGitSources(index, doc, repositoryMappings),
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
function conceptIndexIsStale(index, args) {
|
|
113
|
+
const doc = resolveConcept(index, conceptLocator(args));
|
|
114
|
+
if (!doc) return true;
|
|
115
|
+
const bundle = (index.bundles || []).find((entry) => entry.id === doc.bundle);
|
|
116
|
+
if (!bundle || bundle.remote) return false;
|
|
117
|
+
try {
|
|
118
|
+
return !fs.lstatSync(doc.absolutePath).isFile();
|
|
119
|
+
} catch (_error) {
|
|
120
|
+
return true;
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
function listTypes(index) {
|
|
125
|
+
const counts = {};
|
|
126
|
+
index.concepts.forEach((doc) => {
|
|
127
|
+
counts[doc.type] = (counts[doc.type] || 0) + 1;
|
|
128
|
+
});
|
|
129
|
+
return counts;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
function listTags(index) {
|
|
133
|
+
const counts = {};
|
|
134
|
+
index.concepts.forEach((doc) => {
|
|
135
|
+
doc.tags.forEach((tag) => {
|
|
136
|
+
counts[tag] = (counts[tag] || 0) + 1;
|
|
137
|
+
});
|
|
138
|
+
});
|
|
139
|
+
return counts;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
function listRelationTypes(index) {
|
|
143
|
+
const counts = {};
|
|
144
|
+
index.edges
|
|
145
|
+
.filter((edge) => edge.kind === "relation")
|
|
146
|
+
.forEach((edge) => {
|
|
147
|
+
counts[edge.relationType] = (counts[edge.relationType] || 0) + 1;
|
|
148
|
+
});
|
|
149
|
+
return counts;
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
function listEdgeKinds(index) {
|
|
153
|
+
const counts = {};
|
|
154
|
+
index.edges.forEach((edge) => {
|
|
155
|
+
if (!counts[edge.kind]) {
|
|
156
|
+
counts[edge.kind] = { total: 0, resolved: 0, broken: 0 };
|
|
157
|
+
}
|
|
158
|
+
counts[edge.kind].total += 1;
|
|
159
|
+
counts[edge.kind][edge.broken ? "broken" : "resolved"] += 1;
|
|
160
|
+
});
|
|
161
|
+
return counts;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
const tools = {
|
|
165
|
+
list_bundles: {
|
|
166
|
+
...defineTool(
|
|
167
|
+
"List the local and remote OKF bundles currently loaded by the server.",
|
|
168
|
+
READ_ONLY,
|
|
169
|
+
),
|
|
170
|
+
// Absolute server paths are for principals that may write (over stdio,
|
|
171
|
+
// --write); a read-only HTTP caller gets bundle-relative ones only.
|
|
172
|
+
handler: (state, _args, principal) =>
|
|
173
|
+
jsonContent(
|
|
174
|
+
publicBundles(state.index, {
|
|
175
|
+
includeAbsolutePaths: canWrite(principal),
|
|
176
|
+
}),
|
|
177
|
+
),
|
|
178
|
+
},
|
|
179
|
+
get_concept: {
|
|
180
|
+
...defineTool(
|
|
181
|
+
"Read one valid OKF concept, including its frontmatter, Markdown body, and links.",
|
|
182
|
+
READ_ONLY,
|
|
183
|
+
{
|
|
184
|
+
id: nonEmptyStringParameter(
|
|
185
|
+
"Portable extensionless Concept ID or bundle-relative Markdown path.",
|
|
186
|
+
),
|
|
187
|
+
uri: nonEmptyStringParameter("Canonical or path based okf URI for the concept."),
|
|
188
|
+
bundle: nonEmptyStringParameter("Bundle id used with path when uri is not supplied."),
|
|
189
|
+
path: nonEmptyStringParameter(
|
|
190
|
+
"Bundle relative Markdown path used with bundle when uri is not supplied.",
|
|
191
|
+
),
|
|
192
|
+
},
|
|
193
|
+
[],
|
|
194
|
+
{
|
|
195
|
+
anyOf: [{ required: ["id"] }, { required: ["uri"] }, { required: ["bundle", "path"] }],
|
|
196
|
+
},
|
|
197
|
+
),
|
|
198
|
+
handler: (state, args) => {
|
|
199
|
+
if (conceptIndexIsStale(state.index, args)) state.rebuildIndex();
|
|
200
|
+
return jsonContent(getConcept(state.index, args, state.repositoryMappings));
|
|
201
|
+
},
|
|
202
|
+
},
|
|
203
|
+
list_types: {
|
|
204
|
+
...defineTool("Count the concept types present in the current OKF index.", READ_ONLY),
|
|
205
|
+
handler: (state) => jsonContent(listTypes(state.index)),
|
|
206
|
+
},
|
|
207
|
+
list_tags: {
|
|
208
|
+
...defineTool("Count the tags present on concepts in the current OKF index.", READ_ONLY),
|
|
209
|
+
handler: (state) => jsonContent(listTags(state.index)),
|
|
210
|
+
},
|
|
211
|
+
list_relation_types: {
|
|
212
|
+
...defineTool("Count the typed relations present in the current OKF graph.", READ_ONLY),
|
|
213
|
+
handler: (state) => jsonContent(listRelationTypes(state.index)),
|
|
214
|
+
},
|
|
215
|
+
list_edge_kinds: {
|
|
216
|
+
...defineTool(
|
|
217
|
+
"Count standard semantic and extension edge kinds in the current graph.",
|
|
218
|
+
READ_ONLY,
|
|
219
|
+
),
|
|
220
|
+
handler: (state) => jsonContent(listEdgeKinds(state.index)),
|
|
221
|
+
},
|
|
222
|
+
validate_bundle: {
|
|
223
|
+
...defineTool(
|
|
224
|
+
"Report OKF conformance separately from project validity for one bundle or the full current index.",
|
|
225
|
+
READ_ONLY,
|
|
226
|
+
{
|
|
227
|
+
bundle: nonEmptyStringParameter("Optional bundle id to validate in isolation."),
|
|
228
|
+
},
|
|
229
|
+
),
|
|
230
|
+
handler: (state, args) => {
|
|
231
|
+
const index = state.index;
|
|
232
|
+
if (args.bundle && !index.bundles.some((bundle) => bundle.id === args.bundle)) {
|
|
233
|
+
throw new ToolExecutionError(`Unknown OKF bundle: ${args.bundle}`);
|
|
234
|
+
}
|
|
235
|
+
return jsonContent(validateIndex(index, args.bundle));
|
|
236
|
+
},
|
|
237
|
+
},
|
|
238
|
+
validate_project: {
|
|
239
|
+
...defineTool(
|
|
240
|
+
"Report OKF conformance, project validity, and structured diagnostics for the complete configured project.",
|
|
241
|
+
READ_ONLY,
|
|
242
|
+
),
|
|
243
|
+
handler: (state) => jsonContent(validateIndex(state.index)),
|
|
244
|
+
},
|
|
245
|
+
};
|
|
246
|
+
|
|
247
|
+
module.exports = { tools };
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const {
|
|
4
|
+
checkComputationReceipt,
|
|
5
|
+
inspectAttestedComputation,
|
|
6
|
+
prepareAttestedComputation,
|
|
7
|
+
} = require("../../computation");
|
|
8
|
+
const {
|
|
9
|
+
READ_ONLY,
|
|
10
|
+
booleanParameter,
|
|
11
|
+
defineTool,
|
|
12
|
+
expectedToolOperation,
|
|
13
|
+
integerParameter,
|
|
14
|
+
jsonContent,
|
|
15
|
+
nonEmptyStringParameter,
|
|
16
|
+
objectParameter,
|
|
17
|
+
} = require("../registry");
|
|
18
|
+
|
|
19
|
+
const tools = {
|
|
20
|
+
inspect_attested_computation: {
|
|
21
|
+
...defineTool(
|
|
22
|
+
"Statically inspect an Attested Computation contract and indexed inert artifacts; never execute it.",
|
|
23
|
+
READ_ONLY,
|
|
24
|
+
{
|
|
25
|
+
uri: nonEmptyStringParameter("Canonical or compatibility URI of the Attested Computation."),
|
|
26
|
+
asOf: nonEmptyStringParameter("UTC ISO date or datetime for freshness evaluation."),
|
|
27
|
+
includeComputation: booleanParameter("Include bounded inline or text computation content."),
|
|
28
|
+
maxContentBytes: integerParameter(
|
|
29
|
+
"Maximum computation bytes to include.",
|
|
30
|
+
1,
|
|
31
|
+
1048576,
|
|
32
|
+
65536,
|
|
33
|
+
),
|
|
34
|
+
},
|
|
35
|
+
["uri"],
|
|
36
|
+
),
|
|
37
|
+
handler: async (state, args) =>
|
|
38
|
+
jsonContent(
|
|
39
|
+
await expectedToolOperation(() => inspectAttestedComputation(state.index, args.uri, args), {
|
|
40
|
+
translateTypeError: true,
|
|
41
|
+
}),
|
|
42
|
+
),
|
|
43
|
+
},
|
|
44
|
+
prepare_attested_computation: {
|
|
45
|
+
...defineTool(
|
|
46
|
+
"Check declared parameters and produce non-executing digests without echoing parameter values.",
|
|
47
|
+
READ_ONLY,
|
|
48
|
+
{
|
|
49
|
+
uri: nonEmptyStringParameter("Canonical or compatibility URI of the Attested Computation."),
|
|
50
|
+
parameters: objectParameter("Parameter values keyed only by declared names."),
|
|
51
|
+
asOf: nonEmptyStringParameter("UTC ISO date or datetime for freshness evaluation."),
|
|
52
|
+
},
|
|
53
|
+
["uri", "parameters"],
|
|
54
|
+
),
|
|
55
|
+
handler: async (state, args) =>
|
|
56
|
+
jsonContent(
|
|
57
|
+
await expectedToolOperation(
|
|
58
|
+
() => prepareAttestedComputation(state.index, args.uri, args.parameters, args),
|
|
59
|
+
{ translateTypeError: true },
|
|
60
|
+
),
|
|
61
|
+
),
|
|
62
|
+
},
|
|
63
|
+
check_computation_receipt: {
|
|
64
|
+
...defineTool(
|
|
65
|
+
"Check receipt field presence only; never attest, echo values, or persist the receipt.",
|
|
66
|
+
READ_ONLY,
|
|
67
|
+
{
|
|
68
|
+
uri: nonEmptyStringParameter("Canonical or compatibility URI of the Attested Computation."),
|
|
69
|
+
receipt: objectParameter("Ephemeral receipt object; only its field names are returned."),
|
|
70
|
+
},
|
|
71
|
+
["uri", "receipt"],
|
|
72
|
+
),
|
|
73
|
+
handler: async (state, args) =>
|
|
74
|
+
jsonContent(
|
|
75
|
+
await expectedToolOperation(
|
|
76
|
+
() => checkComputationReceipt(state.index, args.uri, args.receipt),
|
|
77
|
+
{ translateTypeError: true },
|
|
78
|
+
),
|
|
79
|
+
),
|
|
80
|
+
},
|
|
81
|
+
};
|
|
82
|
+
|
|
83
|
+
module.exports = { tools };
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const { CONTEXT_LIMITS, PROVENANCE_MODES, assembleContext } = require("../../context/assemble");
|
|
4
|
+
const { MAX_QUERY_CHARACTERS, MAX_QUERY_TERMS } = require("../../search/lexical");
|
|
5
|
+
const {
|
|
6
|
+
READ_ONLY,
|
|
7
|
+
defineTool,
|
|
8
|
+
expectedToolOperation,
|
|
9
|
+
integerParameter,
|
|
10
|
+
stringParameter,
|
|
11
|
+
} = require("../registry");
|
|
12
|
+
const { QUERY_GUIDANCE, tools: searchTools } = require("./search");
|
|
13
|
+
|
|
14
|
+
// C-1, C-3: the description explains the budget, the anchors and the
|
|
15
|
+
// provenance and repeats the search guidance (R-11). It is composed from
|
|
16
|
+
// constants only and never carries catalog text (B-6, S-3).
|
|
17
|
+
const CONTEXT_DESCRIPTION =
|
|
18
|
+
"Assemble a token-budgeted context for a question from the sections of the best-matching OKF " +
|
|
19
|
+
"concepts. Candidates come from the same search as search_concepts (every filter applies; the " +
|
|
20
|
+
"response repeats mode, lowConfidence, queryTerms and droppedTerms and lists the candidate " +
|
|
21
|
+
"concepts); their sections are ranked, deduplicated and packed in rank order while they fit " +
|
|
22
|
+
"budgetTokens. Ranking follows the candidate concept order; within a concept, sections whose " +
|
|
23
|
+
"own text matches the query come first, and a strongly matching section may move ahead of a " +
|
|
24
|
+
"few weaker concepts. The budget covers what is delivered, the whole response as returned: " +
|
|
25
|
+
"usedTokens is ceil(characters / 4) of the entire JSON result, every field included (the " +
|
|
26
|
+
"candidate concepts, queryTerms, the counters and every section field), and the budget is " +
|
|
27
|
+
"never exceeded unless it is smaller than the query echo and the field names alone; when " +
|
|
28
|
+
"the fields around the sections do not fit, the candidate concept list is shortened from " +
|
|
29
|
+
"its tail (omittedConcepts). Each section's tokens is the same estimate for that section; " +
|
|
30
|
+
"the estimator is named in the response. Provenance is compact by default " +
|
|
31
|
+
"(status, freshness, verified, sourceCount); set provenance to full for staleAfter, " +
|
|
32
|
+
"trustTier, the verified and generated events and the sources, or to none to spend all of " +
|
|
33
|
+
"the budget on text. When the best section alone is larger than what the rest of the response " +
|
|
34
|
+
"leaves it is returned on its own, its " +
|
|
35
|
+
"text cut at a sentence boundary, with truncated true; omittedSections counts what did not " +
|
|
36
|
+
"fit. Each section carries uri, " +
|
|
37
|
+
"anchor (the concept URI for the text before the first heading, uri#heading-slug otherwise; " +
|
|
38
|
+
"an okf-mcp extension: body and whitespace edits leave it unchanged, renaming the heading or " +
|
|
39
|
+
"adding a same-named heading before it changes it), heading, title, text, tokens, score, " +
|
|
40
|
+
"relevance, coverage, matchedTerms and the concept's provenance. The response also carries " +
|
|
41
|
+
"confidence: { coverage, topSimilarity, lowConfidence, reasons } from the candidate search " +
|
|
42
|
+
"(as in search_concepts); with abstainOnLowConfidence a low-confidence query returns no " +
|
|
43
|
+
"sections and abstained true. For the query, " +
|
|
44
|
+
`${QUERY_GUIDANCE.charAt(0).toLowerCase()}${QUERY_GUIDANCE.slice(1)}`;
|
|
45
|
+
|
|
46
|
+
// Filters shared with search_concepts, taken with their descriptions so the
|
|
47
|
+
// two tools read the same way and one sentinel test covers both.
|
|
48
|
+
const SHARED_PARAMETERS = [
|
|
49
|
+
"mode",
|
|
50
|
+
"minCoverage",
|
|
51
|
+
"minRelevance",
|
|
52
|
+
"freshnessPrior",
|
|
53
|
+
"bundle",
|
|
54
|
+
"types",
|
|
55
|
+
"tagsAny",
|
|
56
|
+
"tagsAll",
|
|
57
|
+
"pathPrefix",
|
|
58
|
+
"relationType",
|
|
59
|
+
"frontmatter",
|
|
60
|
+
"linkedTo",
|
|
61
|
+
"linkedFrom",
|
|
62
|
+
"orphanOnly",
|
|
63
|
+
"statuses",
|
|
64
|
+
"trustTiers",
|
|
65
|
+
"freshness",
|
|
66
|
+
"asOf",
|
|
67
|
+
"hasSources",
|
|
68
|
+
"runtime",
|
|
69
|
+
"attestationReady",
|
|
70
|
+
"generatedBy",
|
|
71
|
+
"verifiedBy",
|
|
72
|
+
];
|
|
73
|
+
|
|
74
|
+
function sharedParameters() {
|
|
75
|
+
const source = searchTools.search_concepts.inputSchema.properties;
|
|
76
|
+
return Object.fromEntries(SHARED_PARAMETERS.map((name) => [name, source[name]]));
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const tools = {
|
|
80
|
+
get_context: {
|
|
81
|
+
...defineTool(
|
|
82
|
+
CONTEXT_DESCRIPTION,
|
|
83
|
+
READ_ONLY,
|
|
84
|
+
Object.assign(
|
|
85
|
+
{
|
|
86
|
+
query: stringParameter(
|
|
87
|
+
`Text to assemble context for, matched against concept metadata and section text; maximum ${MAX_QUERY_TERMS} terms after stop words. ${QUERY_GUIDANCE}`,
|
|
88
|
+
{ minLength: 1, maxLength: MAX_QUERY_CHARACTERS },
|
|
89
|
+
),
|
|
90
|
+
budgetTokens: integerParameter(
|
|
91
|
+
"Token budget for the whole response, estimated as ceil(characters / 4) of its JSON and never exceeded.",
|
|
92
|
+
1,
|
|
93
|
+
CONTEXT_LIMITS.budgetTokens.maximum,
|
|
94
|
+
CONTEXT_LIMITS.budgetTokens.default,
|
|
95
|
+
),
|
|
96
|
+
limit: integerParameter(
|
|
97
|
+
"Maximum number of sections to return; the budget is the primary constraint.",
|
|
98
|
+
1,
|
|
99
|
+
CONTEXT_LIMITS.limit.maximum,
|
|
100
|
+
CONTEXT_LIMITS.limit.default,
|
|
101
|
+
),
|
|
102
|
+
includeProvenance: {
|
|
103
|
+
type: "boolean",
|
|
104
|
+
description:
|
|
105
|
+
"Attach each section's concept provenance (false is the same as provenance none); it counts against the budget.",
|
|
106
|
+
default: true,
|
|
107
|
+
},
|
|
108
|
+
provenance: stringParameter(
|
|
109
|
+
"compact (default): status, freshness, verified (boolean) and sourceCount; full: status, staleAfter, freshness, trustTier, verified, generated, sources; none: no provenance.",
|
|
110
|
+
{ enum: PROVENANCE_MODES.slice(), default: "compact" },
|
|
111
|
+
),
|
|
112
|
+
abstainOnLowConfidence: {
|
|
113
|
+
type: "boolean",
|
|
114
|
+
description:
|
|
115
|
+
"Return no sections when the candidate search is low-confidence (lowConfidence true); the response keeps the confidence block, the candidate concepts and abstained true. Off by default.",
|
|
116
|
+
default: false,
|
|
117
|
+
},
|
|
118
|
+
},
|
|
119
|
+
sharedParameters(),
|
|
120
|
+
),
|
|
121
|
+
["query"],
|
|
122
|
+
),
|
|
123
|
+
// Compact JSON: the text returned is the serialisation usedTokens measures.
|
|
124
|
+
handler: async (state, args) => {
|
|
125
|
+
const result = await expectedToolOperation(() => assembleContext(state.index, args), {
|
|
126
|
+
translateTypeError: true,
|
|
127
|
+
});
|
|
128
|
+
return { content: [{ type: "text", text: JSON.stringify(result) }] };
|
|
129
|
+
},
|
|
130
|
+
},
|
|
131
|
+
};
|
|
132
|
+
|
|
133
|
+
module.exports = { tools };
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const { resolveConcept } = require("../../indexer");
|
|
4
|
+
const {
|
|
5
|
+
exportGraph,
|
|
6
|
+
findPaths,
|
|
7
|
+
getGraph,
|
|
8
|
+
getNeighbors,
|
|
9
|
+
getSubgraph,
|
|
10
|
+
graphSummary,
|
|
11
|
+
} = require("../../graph");
|
|
12
|
+
const {
|
|
13
|
+
READ_ONLY,
|
|
14
|
+
ToolExecutionError,
|
|
15
|
+
booleanParameter,
|
|
16
|
+
defineTool,
|
|
17
|
+
integerParameter,
|
|
18
|
+
jsonContent,
|
|
19
|
+
nonEmptyStringParameter,
|
|
20
|
+
stringArrayParameter,
|
|
21
|
+
stringParameter,
|
|
22
|
+
} = require("../registry");
|
|
23
|
+
|
|
24
|
+
function requireGraphConcept(index, uri) {
|
|
25
|
+
const doc = resolveConcept(index, uri);
|
|
26
|
+
if (!doc || !doc.valid || doc.reserved) {
|
|
27
|
+
throw new ToolExecutionError(`Unknown valid OKF concept: ${uri || "<missing>"}`);
|
|
28
|
+
}
|
|
29
|
+
return doc;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
const tools = {
|
|
33
|
+
get_graph: {
|
|
34
|
+
...defineTool(
|
|
35
|
+
"Return a bounded set of OKF graph nodes and edges with optional concept filters.",
|
|
36
|
+
READ_ONLY,
|
|
37
|
+
{
|
|
38
|
+
bundle: nonEmptyStringParameter("Limit graph nodes to this bundle id."),
|
|
39
|
+
type: nonEmptyStringParameter("Limit graph nodes to this exact concept type."),
|
|
40
|
+
tag: nonEmptyStringParameter("Limit graph nodes to concepts containing this tag."),
|
|
41
|
+
pathPrefix: stringParameter(
|
|
42
|
+
"Limit graph nodes to bundle relative paths beginning with this prefix.",
|
|
43
|
+
),
|
|
44
|
+
includeExternal: booleanParameter("Include opaque external relation targets in the graph."),
|
|
45
|
+
includeAssets: booleanParameter(
|
|
46
|
+
"Include explicitly referenced bundle assets as graph nodes.",
|
|
47
|
+
),
|
|
48
|
+
edgeKinds: stringArrayParameter("Limit returned edges to these edge kinds.", {
|
|
49
|
+
nonEmptyItems: true,
|
|
50
|
+
}),
|
|
51
|
+
maxNodes: integerParameter("Maximum number of graph nodes to return.", 1, 1000, 100),
|
|
52
|
+
maxEdges: integerParameter("Maximum number of graph edges to return.", 1, 5000, 300),
|
|
53
|
+
},
|
|
54
|
+
),
|
|
55
|
+
handler: (state, args) => jsonContent(getGraph(state.index, args)),
|
|
56
|
+
},
|
|
57
|
+
get_neighbors: {
|
|
58
|
+
...defineTool(
|
|
59
|
+
"Return the incoming and outgoing graph relationships for one OKF concept.",
|
|
60
|
+
READ_ONLY,
|
|
61
|
+
{
|
|
62
|
+
uri: nonEmptyStringParameter("Canonical or path based okf URI of the center concept."),
|
|
63
|
+
includeExternal: booleanParameter(
|
|
64
|
+
"Include opaque external neighbors without fetching them.",
|
|
65
|
+
),
|
|
66
|
+
includeAssets: booleanParameter("Include referenced asset neighbors."),
|
|
67
|
+
edgeKinds: stringArrayParameter("Limit neighbors to these edge kinds.", {
|
|
68
|
+
nonEmptyItems: true,
|
|
69
|
+
}),
|
|
70
|
+
},
|
|
71
|
+
["uri"],
|
|
72
|
+
),
|
|
73
|
+
handler: (state, args) => {
|
|
74
|
+
requireGraphConcept(state.index, args.uri);
|
|
75
|
+
return jsonContent(getNeighbors(state.index, args.uri, args));
|
|
76
|
+
},
|
|
77
|
+
},
|
|
78
|
+
get_subgraph: {
|
|
79
|
+
...defineTool(
|
|
80
|
+
"Traverse a bounded OKF subgraph outward from one or more seed concepts.",
|
|
81
|
+
READ_ONLY,
|
|
82
|
+
{
|
|
83
|
+
uri: nonEmptyStringParameter("Single canonical or path based okf URI to use as a seed."),
|
|
84
|
+
seeds: stringArrayParameter("One or more okf URIs to use as traversal seeds.", {
|
|
85
|
+
minItems: 1,
|
|
86
|
+
nonEmptyItems: true,
|
|
87
|
+
}),
|
|
88
|
+
depth: integerParameter("Maximum relationship depth to traverse from the seeds.", 0, 10, 1),
|
|
89
|
+
maxNodes: integerParameter("Maximum number of graph nodes to return.", 1, 1000, 50),
|
|
90
|
+
edgeKinds: stringArrayParameter("Limit traversal to these edge kinds.", {
|
|
91
|
+
nonEmptyItems: true,
|
|
92
|
+
}),
|
|
93
|
+
},
|
|
94
|
+
[],
|
|
95
|
+
{
|
|
96
|
+
anyOf: [{ required: ["uri"] }, { required: ["seeds"] }],
|
|
97
|
+
},
|
|
98
|
+
),
|
|
99
|
+
handler: (state, args) => {
|
|
100
|
+
const seeds = args.seeds || [args.uri];
|
|
101
|
+
seeds.forEach((uri) => requireGraphConcept(state.index, uri));
|
|
102
|
+
return jsonContent(getSubgraph(state.index, args));
|
|
103
|
+
},
|
|
104
|
+
},
|
|
105
|
+
find_paths: {
|
|
106
|
+
...defineTool(
|
|
107
|
+
"Find bounded relationship paths between two OKF concepts.",
|
|
108
|
+
READ_ONLY,
|
|
109
|
+
{
|
|
110
|
+
source: nonEmptyStringParameter(
|
|
111
|
+
"Canonical or path based okf URI where path search begins.",
|
|
112
|
+
),
|
|
113
|
+
target: nonEmptyStringParameter("Canonical or path based okf URI where path search ends."),
|
|
114
|
+
maxPaths: integerParameter("Maximum number of distinct paths to return.", 1, 50, 3),
|
|
115
|
+
edgeKinds: stringArrayParameter("Limit path traversal to these edge kinds.", {
|
|
116
|
+
nonEmptyItems: true,
|
|
117
|
+
}),
|
|
118
|
+
},
|
|
119
|
+
["source", "target"],
|
|
120
|
+
),
|
|
121
|
+
handler: (state, args) => {
|
|
122
|
+
requireGraphConcept(state.index, args.source);
|
|
123
|
+
requireGraphConcept(state.index, args.target);
|
|
124
|
+
return jsonContent(findPaths(state.index, args.source, args.target, args.maxPaths, args));
|
|
125
|
+
},
|
|
126
|
+
},
|
|
127
|
+
graph_summary: {
|
|
128
|
+
...defineTool(
|
|
129
|
+
"Summarize bundle, concept, edge, type, tag, and graph health counts.",
|
|
130
|
+
READ_ONLY,
|
|
131
|
+
),
|
|
132
|
+
handler: (state) => jsonContent(graphSummary(state.index)),
|
|
133
|
+
},
|
|
134
|
+
export_graph: {
|
|
135
|
+
...defineTool(
|
|
136
|
+
"Render the current OKF graph as JSON, Graphviz DOT, or Mermaid text.",
|
|
137
|
+
READ_ONLY,
|
|
138
|
+
{
|
|
139
|
+
format: stringParameter("Output format for the graph.", {
|
|
140
|
+
enum: ["json", "dot", "mermaid"],
|
|
141
|
+
default: "json",
|
|
142
|
+
}),
|
|
143
|
+
includeExternal: booleanParameter(
|
|
144
|
+
"Include opaque external relation targets in the export.",
|
|
145
|
+
),
|
|
146
|
+
includeAssets: booleanParameter(
|
|
147
|
+
"Include explicitly referenced bundle assets in the export.",
|
|
148
|
+
),
|
|
149
|
+
edgeKinds: stringArrayParameter("Limit exported edges to these edge kinds.", {
|
|
150
|
+
nonEmptyItems: true,
|
|
151
|
+
}),
|
|
152
|
+
maxNodes: integerParameter("Maximum number of graph nodes to export.", 1, 1000, 100),
|
|
153
|
+
maxEdges: integerParameter("Maximum number of graph edges to export.", 1, 5000, 300),
|
|
154
|
+
},
|
|
155
|
+
),
|
|
156
|
+
handler: (state, args) => ({
|
|
157
|
+
content: [
|
|
158
|
+
{
|
|
159
|
+
type: "text",
|
|
160
|
+
text: exportGraph(state.index, args),
|
|
161
|
+
},
|
|
162
|
+
],
|
|
163
|
+
}),
|
|
164
|
+
},
|
|
165
|
+
};
|
|
166
|
+
|
|
167
|
+
module.exports = { tools };
|