@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,346 @@
1
+ "use strict";
2
+
3
+ // Tool packs (plan D1; experimental, outside the 1.0 freeze): npm packages
4
+ // that add read tools to the MCP server, loaded like producers. The trusted
5
+ // project config lists them as `toolPacks: [{ package, config, timeoutMs? }]`;
6
+ // each exact bare package name is resolved under the project's node_modules
7
+ // and must export
8
+ //
9
+ // okfToolPack = { apiVersion: "1", id, validateConfig(config), tools,
10
+ // serialize? }
11
+ // tools[name] = { description, annotations, inputSchema, outputSchema?,
12
+ // scope, requiresSubjectToken?, handler(args, ctx) }
13
+ // ctx = { principal, subjectToken, config, getSecret, signal }
14
+ //
15
+ // Tool names match ^[a-z][a-z0-9_]{2,63}$ and may not repeat a core tool or
16
+ // another pack's tool; both are startup errors. Descriptions and schemas come
17
+ // from the package, never from config (B-6). A principal sees a pack tool
18
+ // when it holds okf.read and the tool's scope. A handler returns a JSON value;
19
+ // an error it throws reaches the caller only as a bounded code and scalar
20
+ // details (src/error-details.js), never its message. Calls are bounded by
21
+ // `timeoutMs` (default 30 s) and the request's abort signal. Pack tools are
22
+ // read tools: they run outside the knowledge call queue unless the pack sets
23
+ // `serialize: true`.
24
+
25
+ const { fromJsonSchema } = require("@modelcontextprotocol/server");
26
+
27
+ const { TOOL_PACK_DETAILS, boundedErrorDetails, publicErrorCode } = require("./error-details");
28
+ const { loadInstalledPackage } = require("./producers");
29
+
30
+ const TOOL_NAME = /^[a-z][a-z0-9_]{2,63}$/;
31
+ const SCOPE = /^[a-z][a-z0-9_.:-]{0,63}$/;
32
+ const MAX_DESCRIPTION_CHARS = 4096;
33
+ const MAX_RESULT_BYTES = 1024 * 1024;
34
+ // Config keys that would hold a secret inline; secrets are named by `*Env`
35
+ // keys and read with ctx.getSecret instead.
36
+ const INLINE_SECRET_KEYS = new Set([
37
+ "apikey",
38
+ "credential",
39
+ "credentials",
40
+ "password",
41
+ "secret",
42
+ "token",
43
+ ]);
44
+
45
+ class ToolPackError extends Error {
46
+ constructor(message, code, details) {
47
+ super(message);
48
+ this.name = "ToolPackError";
49
+ this.code = code;
50
+ if (details !== undefined) this.details = details;
51
+ }
52
+ }
53
+
54
+ // The environment variable names the config may read through getSecret:
55
+ // the string values of keys ending in "Env". Inline secret keys are refused.
56
+ function secretNames(config, field, names) {
57
+ for (const [key, value] of Object.entries(config || {})) {
58
+ const at = `${field}.${key}`;
59
+ if (INLINE_SECRET_KEYS.has(key.toLowerCase().replace(/[^a-z0-9]/g, ""))) {
60
+ throw new ToolPackError(
61
+ "Tool pack config holds a secret inline.",
62
+ "unsafe_tool_pack_config",
63
+ {
64
+ field: at,
65
+ },
66
+ );
67
+ }
68
+ if (/env$/i.test(key)) {
69
+ if (typeof value !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
70
+ throw new ToolPackError(
71
+ "Tool pack secret references must be environment variable names.",
72
+ "invalid_tool_pack_secret_reference",
73
+ { field: at },
74
+ );
75
+ }
76
+ names.add(value);
77
+ } else if (value && typeof value === "object") {
78
+ secretNames(value, at, names);
79
+ }
80
+ }
81
+ return names;
82
+ }
83
+
84
+ function plainObject(value) {
85
+ return Boolean(value) && typeof value === "object" && !Array.isArray(value);
86
+ }
87
+
88
+ // The descriptor's tools, checked, in the order the package declares them.
89
+ function packTools(packageName, descriptor) {
90
+ const incompatible = (tool) =>
91
+ new ToolPackError(
92
+ "Tool pack descriptor is incompatible with this host.",
93
+ "incompatible_tool_pack",
94
+ {
95
+ package: packageName,
96
+ ...(tool ? { tool } : {}),
97
+ },
98
+ );
99
+ if (
100
+ !plainObject(descriptor) ||
101
+ descriptor.apiVersion !== "1" ||
102
+ typeof descriptor.id !== "string" ||
103
+ !TOOL_NAME.test(descriptor.id) ||
104
+ typeof descriptor.validateConfig !== "function" ||
105
+ !plainObject(descriptor.tools) ||
106
+ (descriptor.serialize !== undefined && typeof descriptor.serialize !== "boolean")
107
+ ) {
108
+ throw incompatible();
109
+ }
110
+ return Object.entries(descriptor.tools).map(([name, tool]) => {
111
+ if (!TOOL_NAME.test(name)) throw incompatible(name.slice(0, 64));
112
+ const valid =
113
+ plainObject(tool) &&
114
+ typeof tool.description === "string" &&
115
+ tool.description.trim().length > 0 &&
116
+ tool.description.length <= MAX_DESCRIPTION_CHARS &&
117
+ plainObject(tool.annotations) &&
118
+ plainObject(tool.inputSchema) &&
119
+ tool.inputSchema.type === "object" &&
120
+ (tool.outputSchema === undefined ||
121
+ (plainObject(tool.outputSchema) && tool.outputSchema.type === "object")) &&
122
+ typeof tool.scope === "string" &&
123
+ SCOPE.test(tool.scope) &&
124
+ (tool.requiresSubjectToken === undefined || typeof tool.requiresSubjectToken === "boolean") &&
125
+ typeof tool.handler === "function";
126
+ if (!valid) throw incompatible(name);
127
+ try {
128
+ fromJsonSchema(tool.inputSchema);
129
+ if (tool.outputSchema) fromJsonSchema(tool.outputSchema);
130
+ } catch {
131
+ throw incompatible(name);
132
+ }
133
+ // Copies taken now: nothing the package or its config does later changes
134
+ // what is advertised.
135
+ return Object.freeze({
136
+ name,
137
+ description: tool.description,
138
+ annotations: structuredClone(tool.annotations),
139
+ inputSchema: structuredClone(tool.inputSchema),
140
+ outputSchema: tool.outputSchema ? structuredClone(tool.outputSchema) : undefined,
141
+ scope: tool.scope,
142
+ requiresSubjectToken: tool.requiresSubjectToken === true,
143
+ handler: tool.handler,
144
+ });
145
+ });
146
+ }
147
+
148
+ // Loads every configured tool pack, or throws a ToolPackError naming the
149
+ // package and tool involved. `coreNames` are the core tool names; `loader`
150
+ // and `env` stand in for the installed-package loader and process.env.
151
+ async function loadToolPacks(project, options) {
152
+ const config = options || {};
153
+ const entries = project?.toolPacks || [];
154
+ if (!entries.length) return [];
155
+ const problems = (project.errors || []).filter((entry) => /tool_pack/.test(entry.code));
156
+ if (problems.length) {
157
+ throw new ToolPackError("The project's toolPacks configuration is invalid.", problems[0].code, {
158
+ field: problems[0].field,
159
+ });
160
+ }
161
+ const loader = config.loader || ((proj, name) => loadInstalledPackage(proj, name, "tool pack"));
162
+ const env = config.env || process.env;
163
+ const taken = new Set(config.coreNames || []);
164
+ const packs = [];
165
+ for (const entry of entries) {
166
+ let moduleValue;
167
+ try {
168
+ moduleValue = await loader(project, entry.package);
169
+ } catch (error) {
170
+ throw new ToolPackError(
171
+ "The configured tool pack package could not be loaded.",
172
+ /^(invalid_tool_pack_package|tool_pack_package_not_installed)$/.test(error?.code)
173
+ ? error.code
174
+ : "tool_pack_load_failed",
175
+ { package: entry.package },
176
+ );
177
+ }
178
+ const descriptor = moduleValue?.okfToolPack;
179
+ const tools = packTools(entry.package, descriptor);
180
+ for (const tool of tools) {
181
+ if (taken.has(tool.name)) {
182
+ throw new ToolPackError(
183
+ "A tool pack tool repeats an existing tool name.",
184
+ "tool_pack_name_collision",
185
+ {
186
+ package: entry.package,
187
+ tool: tool.name,
188
+ },
189
+ );
190
+ }
191
+ taken.add(tool.name);
192
+ }
193
+ const names = secretNames(entry.config, "config", new Set());
194
+ let validation;
195
+ try {
196
+ validation = await descriptor.validateConfig(structuredClone(entry.config));
197
+ } catch {
198
+ validation = null;
199
+ }
200
+ if (validation?.valid !== true) {
201
+ throw new ToolPackError(
202
+ "The tool pack refused its configuration.",
203
+ "invalid_tool_pack_config",
204
+ {
205
+ package: entry.package,
206
+ },
207
+ );
208
+ }
209
+ const packConfig = validation.config === undefined ? entry.config : validation.config;
210
+ const secrets = new Set();
211
+ packs.push({
212
+ id: descriptor.id,
213
+ package: entry.package,
214
+ serialize: descriptor.serialize === true,
215
+ timeoutMs: entry.timeoutMs,
216
+ config: packConfig,
217
+ tools,
218
+ secrets,
219
+ getSecret(name) {
220
+ if (!names.has(name)) {
221
+ throw new ToolPackError(
222
+ "The tool pack asked for a secret its config does not name.",
223
+ "tool_pack_secret_not_allowed",
224
+ );
225
+ }
226
+ const value = env[name];
227
+ if (typeof value !== "string" || !value) {
228
+ throw new ToolPackError(
229
+ "A configured tool pack secret is unavailable.",
230
+ "tool_pack_secret_unavailable",
231
+ );
232
+ }
233
+ secrets.add(value);
234
+ return value;
235
+ },
236
+ });
237
+ }
238
+ return packs;
239
+ }
240
+
241
+ // Every scope a client may need: okf.read and okf.write, then the scopes
242
+ // the pack tools declare, in config and declaration order, each once. It is
243
+ // what an HTTP server advertises, so that a client signing in asks for them.
244
+ function advertisedScopes(packs) {
245
+ return [
246
+ ...new Set(
247
+ ["okf.read", "okf.write"].concat(
248
+ (packs || []).flatMap((pack) => pack.tools.map((tool) => tool.scope)),
249
+ ),
250
+ ),
251
+ ];
252
+ }
253
+
254
+ // The scopes the pack tools declare beyond okf.*, which the stdio
255
+ // principal, the process's own operator, holds.
256
+ function toolPackScopes(packs) {
257
+ return [...new Set((packs || []).flatMap((pack) => pack.tools.map((tool) => tool.scope)))].filter(
258
+ (scope) => !scope.startsWith("okf."),
259
+ );
260
+ }
261
+
262
+ // A failed pack call. The text leads with the fixed message, for clients that
263
+ // show only the start of it, followed by one JSON line with the bounded code
264
+ // and details: the same as the structured content, and nothing else from
265
+ // the handler.
266
+ function failure(name, code, details) {
267
+ const message = "The tool pack could not complete the call.";
268
+ const value = {
269
+ error: "Tool execution failed",
270
+ tool: name,
271
+ message,
272
+ code,
273
+ ...(details ? { details } : {}),
274
+ };
275
+ const line = JSON.stringify({ code, ...(details ? { details } : {}) });
276
+ return {
277
+ content: [{ type: "text", text: `${message}\n${line}` }],
278
+ structuredContent: value,
279
+ isError: true,
280
+ };
281
+ }
282
+
283
+ // Runs one pack tool for a principal and returns the MCP tool result.
284
+ // `options`: subjectToken (HTTP only) and the request's abort signal.
285
+ async function callPackTool(pack, tool, args, principal, options) {
286
+ const config = options || {};
287
+ const timeout = new AbortController();
288
+ const signals = [timeout.signal, config.signal].filter(Boolean);
289
+ const signal = AbortSignal.any(signals);
290
+ const timer = setTimeout(
291
+ () => timeout.abort(new ToolPackError("Tool pack call timed out.", "tool_pack_timeout")),
292
+ pack.timeoutMs,
293
+ );
294
+ const ctx = Object.freeze({
295
+ principal: Object.freeze({
296
+ subject: principal.subject,
297
+ actor: principal.actor,
298
+ scopes: [...principal.scopes],
299
+ ...(principal.name ? { name: principal.name } : {}),
300
+ ...(principal.email ? { email: principal.email } : {}),
301
+ }),
302
+ subjectToken: config.subjectToken,
303
+ config: structuredClone(pack.config),
304
+ getSecret: pack.getSecret,
305
+ signal,
306
+ });
307
+ const hidden = [config.subjectToken, ...pack.secrets].filter(Boolean);
308
+ try {
309
+ const stopped = new Promise((_, reject) => {
310
+ if (signal.aborted) reject(signal.reason);
311
+ signal.addEventListener("abort", () => reject(signal.reason), { once: true });
312
+ });
313
+ const value = await Promise.race([
314
+ Promise.resolve().then(() => tool.handler(args, ctx)),
315
+ stopped,
316
+ ]);
317
+ const text = JSON.stringify(value === undefined ? null : value, null, 2);
318
+ if (Buffer.byteLength(text) > MAX_RESULT_BYTES) {
319
+ return failure(tool.name, "tool_pack_result_too_large");
320
+ }
321
+ return {
322
+ content: [{ type: "text", text }],
323
+ ...(tool.outputSchema ? { structuredContent: JSON.parse(text) } : {}),
324
+ };
325
+ } catch (error) {
326
+ if (timeout.signal.aborted) return failure(tool.name, "tool_pack_timeout");
327
+ if (config.signal?.aborted) return failure(tool.name, "tool_pack_cancelled");
328
+ const code = publicErrorCode(error);
329
+ if (!code) return failure(tool.name, "tool_pack_execution_failed");
330
+ return failure(
331
+ tool.name,
332
+ code,
333
+ boundedErrorDetails(error, [...hidden, ...pack.secrets], TOOL_PACK_DETAILS),
334
+ );
335
+ } finally {
336
+ clearTimeout(timer);
337
+ }
338
+ }
339
+
340
+ module.exports = {
341
+ ToolPackError,
342
+ advertisedScopes,
343
+ callPackTool,
344
+ loadToolPacks,
345
+ toolPackScopes,
346
+ };