@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,554 @@
1
+ "use strict";
2
+
3
+ // Command-line option parsing for the okf / okf-mcp binary: the flag grammar,
4
+ // the usage-error type with exit code 2, legacy bundle resolution, project
5
+ // discovery, and the options handed to the stdio MCP server. Split out of
6
+ // src/cli.js (Q-1); src/cli.js keeps the entry point.
7
+
8
+ const fs = require("node:fs");
9
+
10
+ const { findOkfRoot, findProjectConfig } = require("../project");
11
+ const { normalizeLanguages } = require("../search/languages");
12
+ const { loadWritePolicyFile } = require("../policy/write-policy");
13
+ const embeddingCli = require("../search/embedding-cli");
14
+ const { createSearchOptions } = require("../search/cli-options");
15
+ const contextCli = require("../context/cli-options");
16
+ const { validActor } = require("../v02");
17
+ const { createHttpOptions, parseHttpOption } = require("./http-options");
18
+
19
+ const COMMANDS = new Set([
20
+ "mcp",
21
+ "validate",
22
+ "graph",
23
+ "search",
24
+ "context",
25
+ "concept",
26
+ "neighbors",
27
+ "paths",
28
+ "generate",
29
+ "serve",
30
+ "provenance",
31
+ "edge-kinds",
32
+ "computation",
33
+ "asset",
34
+ "source",
35
+ "migrate",
36
+ "producer",
37
+ ]);
38
+ const PRODUCER_ACTIONS = new Set(["list", "preview", "run"]);
39
+ const WRITE_COMMANDS = new Set(["mcp", "producer"]);
40
+
41
+ class UsageError extends Error {
42
+ constructor(message) {
43
+ super(message);
44
+ this.name = "UsageError";
45
+ this.code = "OKF_USAGE_ERROR";
46
+ this.exitCode = 2;
47
+ }
48
+ }
49
+
50
+ function usageError(message) {
51
+ return new UsageError(message);
52
+ }
53
+
54
+ function parseJsonObject(value, label) {
55
+ let parsed;
56
+ try {
57
+ parsed = JSON.parse(value);
58
+ } catch {
59
+ throw usageError(`${label} must be valid JSON.`);
60
+ }
61
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
62
+ throw usageError(`${label} must be a JSON object.`);
63
+ }
64
+ return parsed;
65
+ }
66
+
67
+ function readJsonObjectSource(source, label, runtime) {
68
+ let text;
69
+ try {
70
+ const readFileSync = runtime?.readFileSync ? runtime.readFileSync : fs.readFileSync;
71
+ text = readFileSync(source === "-" ? 0 : source, "utf8");
72
+ } catch {
73
+ throw usageError(`${label} could not be read from ${source === "-" ? "stdin" : source}.`);
74
+ }
75
+ return parseJsonObject(String(text), label);
76
+ }
77
+
78
+ function exitCodeForError(error) {
79
+ return error && error.exitCode === 2 ? 2 : 1;
80
+ }
81
+
82
+ function parseArgs(argv) {
83
+ const bundles = [];
84
+ const remoteBundles = [];
85
+ const repositories = [];
86
+ const positional = [];
87
+ let project = null;
88
+ let root = null;
89
+ let inspect = false;
90
+ let help = false;
91
+ let host = "127.0.0.1";
92
+ let port = 8765;
93
+ let portGiven = false;
94
+ let writeToken = "";
95
+ let proposalRoot = "";
96
+ let version = false;
97
+ let authoring = false;
98
+ let write = false;
99
+ let actor = "";
100
+ let policy = "";
101
+ let gitCommit = false;
102
+ let allowRemoteTool = false;
103
+ let strictLinks = false;
104
+ let languages = "";
105
+ let allowComputationAuthoring = false;
106
+ let includeAssets = false;
107
+ let includeExternal = false;
108
+ let parametersFile = "";
109
+ let receiptFile = "";
110
+ let maxContentBytes = 65536;
111
+ const generatedPaths = [];
112
+ const search = createSearchOptions();
113
+ const http = createHttpOptions();
114
+ for (let index = 0; index < argv.length; index += 1) {
115
+ const arg = argv[index];
116
+ if (arg === "--root" || arg === "-r") {
117
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
118
+ throw usageError(`${arg} requires a value.`);
119
+ }
120
+ if (root) {
121
+ throw usageError("--root may be supplied only once.");
122
+ }
123
+ root = argv[index + 1];
124
+ index += 1;
125
+ continue;
126
+ }
127
+ if (arg.startsWith("--root=")) {
128
+ if (root) {
129
+ throw usageError("--root may be supplied only once.");
130
+ }
131
+ root = arg.slice("--root=".length);
132
+ if (!root) {
133
+ throw usageError("--root requires a value.");
134
+ }
135
+ continue;
136
+ }
137
+ if (arg === "--bundle" || arg === "-b") {
138
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
139
+ throw usageError(`${arg} requires a value.`);
140
+ }
141
+ bundles.push(argv[index + 1]);
142
+ index += 1;
143
+ continue;
144
+ }
145
+ if (arg.startsWith("--bundle=")) {
146
+ const value = arg.slice("--bundle=".length);
147
+ if (!value) {
148
+ throw usageError("--bundle requires a value.");
149
+ }
150
+ bundles.push(value);
151
+ continue;
152
+ }
153
+ if (arg === "--remote-bundle") {
154
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
155
+ throw usageError(`${arg} requires a value.`);
156
+ }
157
+ remoteBundles.push(argv[index + 1]);
158
+ index += 1;
159
+ continue;
160
+ }
161
+ if (arg.startsWith("--remote-bundle=")) {
162
+ const value = arg.slice("--remote-bundle=".length);
163
+ if (!value) {
164
+ throw usageError("--remote-bundle requires a value.");
165
+ }
166
+ remoteBundles.push(value);
167
+ continue;
168
+ }
169
+ if (arg === "--project" || arg === "-p") {
170
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
171
+ throw usageError(`${arg} requires a value.`);
172
+ }
173
+ project = argv[index + 1];
174
+ index += 1;
175
+ continue;
176
+ }
177
+ if (arg.startsWith("--project=")) {
178
+ project = arg.slice("--project=".length);
179
+ if (!project) {
180
+ throw usageError("--project requires a value.");
181
+ }
182
+ continue;
183
+ }
184
+ if (arg === "--repo") {
185
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
186
+ throw usageError("--repo requires concept-id=path.");
187
+ }
188
+ repositories.push(argv[index + 1]);
189
+ index += 1;
190
+ continue;
191
+ }
192
+ if (arg.startsWith("--repo=")) {
193
+ const value = arg.slice("--repo=".length);
194
+ if (!value) {
195
+ throw usageError("--repo requires concept-id=path.");
196
+ }
197
+ repositories.push(value);
198
+ continue;
199
+ }
200
+ if (arg === "--inspect") {
201
+ inspect = true;
202
+ continue;
203
+ }
204
+ if (arg === "--authoring") {
205
+ authoring = true;
206
+ continue;
207
+ }
208
+ if (arg === "--write") {
209
+ write = true;
210
+ continue;
211
+ }
212
+ if (arg === "--actor") {
213
+ if (actor) {
214
+ throw usageError("--actor may be supplied only once.");
215
+ }
216
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
217
+ throw usageError("--actor requires a value.");
218
+ }
219
+ actor = argv[index + 1];
220
+ index += 1;
221
+ continue;
222
+ }
223
+ if (arg.startsWith("--actor=")) {
224
+ if (actor) {
225
+ throw usageError("--actor may be supplied only once.");
226
+ }
227
+ actor = arg.slice("--actor=".length);
228
+ if (!actor) {
229
+ throw usageError("--actor requires a value.");
230
+ }
231
+ continue;
232
+ }
233
+ if (arg === "--git-commit") {
234
+ gitCommit = true;
235
+ continue;
236
+ }
237
+ if (arg === "--policy" || arg.startsWith("--policy=")) {
238
+ const inline = arg.startsWith("--policy=");
239
+ const value = inline ? arg.slice("--policy=".length) : argv[index + 1];
240
+ if (policy) throw usageError("--policy may be supplied only once.");
241
+ if (!value || (!inline && value.startsWith("-")))
242
+ throw usageError("--policy requires a value.");
243
+ policy = value;
244
+ index += inline ? 0 : 1;
245
+ continue;
246
+ }
247
+ if (arg === "--allow-remote-tool") {
248
+ allowRemoteTool = true;
249
+ continue;
250
+ }
251
+ if (arg === "--allow-computation-authoring") {
252
+ allowComputationAuthoring = true;
253
+ continue;
254
+ }
255
+ if (arg === "--strict-links") {
256
+ strictLinks = true;
257
+ continue;
258
+ }
259
+ if (arg === "--languages") {
260
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
261
+ throw usageError("--languages requires auto, none, or language codes such as it,en.");
262
+ }
263
+ try {
264
+ normalizeLanguages(argv[index + 1]);
265
+ } catch (error) {
266
+ throw usageError(`--languages: ${error.message}`);
267
+ }
268
+ languages = argv[index + 1];
269
+ index += 1;
270
+ continue;
271
+ }
272
+ if (arg === "--include-assets") {
273
+ includeAssets = true;
274
+ continue;
275
+ }
276
+ if (arg === "--include-external") {
277
+ includeExternal = true;
278
+ continue;
279
+ }
280
+ if (arg === "--generated-path") {
281
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
282
+ throw usageError(`${arg} requires a value.`);
283
+ }
284
+ generatedPaths.push(argv[index + 1]);
285
+ index += 1;
286
+ continue;
287
+ }
288
+ if (arg === "--parameters-file" || arg === "--receipt-file") {
289
+ const value = argv[index + 1];
290
+ if (!value || (String(value).startsWith("-") && value !== "-")) {
291
+ throw usageError(`${arg} requires a file path or - for stdin.`);
292
+ }
293
+ if (arg === "--parameters-file") {
294
+ parametersFile = value;
295
+ } else {
296
+ receiptFile = value;
297
+ }
298
+ index += 1;
299
+ continue;
300
+ }
301
+ if (arg === "--max-content-bytes") {
302
+ const value = Number(argv[index + 1]);
303
+ if (!Number.isSafeInteger(value) || value < 1 || value > 1048576) {
304
+ throw usageError("--max-content-bytes requires an integer from 1 through 1048576.");
305
+ }
306
+ maxContentBytes = value;
307
+ index += 1;
308
+ continue;
309
+ }
310
+ const httpConsumed = parseHttpOption(arg, argv, index, http, usageError);
311
+ if (httpConsumed >= 0) {
312
+ index += httpConsumed;
313
+ continue;
314
+ }
315
+ const consumed = contextCli.parseCommandOption(arg, argv, index, search, usageError);
316
+ if (consumed >= 0) {
317
+ index += consumed;
318
+ continue;
319
+ }
320
+ if (arg === "--host") {
321
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
322
+ throw usageError(`${arg} requires a value.`);
323
+ }
324
+ host = argv[index + 1];
325
+ index += 1;
326
+ continue;
327
+ }
328
+ if (arg.startsWith("--host=")) {
329
+ host = arg.slice("--host=".length);
330
+ continue;
331
+ }
332
+ if (arg === "--port") {
333
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
334
+ throw usageError(`${arg} requires a value.`);
335
+ }
336
+ port = Number(argv[index + 1]);
337
+ portGiven = true;
338
+ index += 1;
339
+ continue;
340
+ }
341
+ if (arg.startsWith("--port=")) {
342
+ port = Number(arg.slice("--port=".length));
343
+ portGiven = true;
344
+ continue;
345
+ }
346
+ if (arg === "--write-token") {
347
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
348
+ throw usageError(`${arg} requires a value.`);
349
+ }
350
+ writeToken = argv[index + 1];
351
+ index += 1;
352
+ continue;
353
+ }
354
+ if (arg.startsWith("--write-token=")) {
355
+ writeToken = arg.slice("--write-token=".length);
356
+ continue;
357
+ }
358
+ if (arg === "--proposal-root") {
359
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
360
+ throw usageError(`${arg} requires a value.`);
361
+ }
362
+ proposalRoot = argv[index + 1];
363
+ index += 1;
364
+ continue;
365
+ }
366
+ if (arg.startsWith("--proposal-root=")) {
367
+ proposalRoot = arg.slice("--proposal-root=".length);
368
+ continue;
369
+ }
370
+ if (arg === "--help" || arg === "-h") {
371
+ help = true;
372
+ continue;
373
+ }
374
+ if (arg === "--version" || arg === "-v") {
375
+ version = true;
376
+ continue;
377
+ }
378
+ if (arg === "--") {
379
+ positional.push(...argv.slice(index + 1));
380
+ break;
381
+ }
382
+ if (arg?.startsWith("-")) {
383
+ throw usageError(`Unknown option: ${arg}`);
384
+ }
385
+ if (arg && !arg.startsWith("-")) {
386
+ positional.push(arg);
387
+ }
388
+ }
389
+ if (write && !actor) {
390
+ throw usageError("--write requires --actor <human:id|process:id|provider/model>.");
391
+ }
392
+ if (actor && !validActor(actor)) {
393
+ throw usageError("--actor must use human:<id>, process:<id>, or provider/model syntax.");
394
+ }
395
+ if (actor && !write && !authoring) {
396
+ throw usageError("--actor requires --write or --authoring.");
397
+ }
398
+ if (gitCommit && !write) {
399
+ throw usageError("--git-commit requires --write.");
400
+ }
401
+ if (policy && !write && !authoring) {
402
+ throw usageError("--policy requires --write or --authoring.");
403
+ }
404
+ return {
405
+ bundles,
406
+ remoteBundles,
407
+ repositories,
408
+ positional,
409
+ project,
410
+ root,
411
+ inspect,
412
+ help,
413
+ version,
414
+ authoring,
415
+ write,
416
+ actor,
417
+ policy,
418
+ gitCommit,
419
+ allowRemoteTool,
420
+ allowComputationAuthoring,
421
+ strictLinks,
422
+ languages,
423
+ includeAssets,
424
+ includeExternal,
425
+ parametersFile,
426
+ receiptFile,
427
+ maxContentBytes,
428
+ generatedPaths,
429
+ host,
430
+ port,
431
+ portGiven,
432
+ http,
433
+ writeToken,
434
+ proposalRoot,
435
+ search,
436
+ };
437
+ }
438
+
439
+ function resolveLegacyBundles(args) {
440
+ if (args.root) {
441
+ return [args.root];
442
+ }
443
+ if (args.bundles.length) {
444
+ return args.bundles;
445
+ }
446
+ if (!args.positional.length) {
447
+ return [];
448
+ }
449
+ const first = args.positional[0];
450
+ return COMMANDS.has(first) ? [] : args.positional;
451
+ }
452
+
453
+ function parseRepositoryMappings(values) {
454
+ const mappings = new Map();
455
+ (values || []).forEach((value) => {
456
+ const text = String(value || "");
457
+ const separator = text.indexOf("=");
458
+ const conceptId =
459
+ separator > 0 ? text.slice(0, separator).replace(/^\/+/, "").replace(/\.md$/i, "") : "";
460
+ const repositoryPath = separator > 0 ? text.slice(separator + 1) : "";
461
+ if (!conceptId || !repositoryPath) {
462
+ throw usageError("--repo requires repository-concept-id=checkout-or-bare-repository-path.");
463
+ }
464
+ if (mappings.has(conceptId)) {
465
+ throw usageError(`Duplicate --repo mapping: ${conceptId}`);
466
+ }
467
+ mappings.set(conceptId, repositoryPath);
468
+ });
469
+ return mappings;
470
+ }
471
+
472
+ function parseRemoteBundleArg(value) {
473
+ const text = String(value || "");
474
+ const eq = text.indexOf("=");
475
+ if (eq <= 0) {
476
+ throw usageError("--remote-bundle value must use id=https://github.com/... format.");
477
+ }
478
+ return {
479
+ id: text.slice(0, eq),
480
+ provider: "github",
481
+ url: text.slice(eq + 1),
482
+ };
483
+ }
484
+
485
+ function discoverProject(args, startDir) {
486
+ if (
487
+ !args.project &&
488
+ !args.root &&
489
+ !args.bundles.length &&
490
+ !args.remoteBundles.length &&
491
+ !resolveLegacyBundles(args).length
492
+ ) {
493
+ args.root = findOkfRoot(startDir);
494
+ if (!args.root) {
495
+ args.project = findProjectConfig(startDir);
496
+ }
497
+ }
498
+ return args;
499
+ }
500
+
501
+ // --policy: the --root counterpart of writePolicy, for stdio and HTTP alike.
502
+ function writePolicyOption(args) {
503
+ if (args.policy && !args.root) {
504
+ throw usageError("--policy requires --root; declare writePolicy in okf.project.yaml instead.");
505
+ }
506
+ return args.policy ? loadWritePolicyFile(args.policy) : undefined;
507
+ }
508
+
509
+ function stdioServerOptions(args) {
510
+ const repositoryMappings = parseRepositoryMappings(args.repositories);
511
+ const options = {
512
+ remoteBundles: args.remoteBundles.map(parseRemoteBundleArg),
513
+ allowAuthoring: Boolean(args.authoring),
514
+ allowRuntimeRemoteLoad: Boolean(args.allowRemoteTool),
515
+ };
516
+ if (repositoryMappings.size) options.repositoryMappings = repositoryMappings;
517
+ if (args.authoring && args.allowComputationAuthoring) options.allowComputationAuthoring = true;
518
+ if (args.actor) options.actor = args.actor;
519
+ if (args.write) {
520
+ options.allowWrite = true;
521
+ if (args.gitCommit) {
522
+ options.gitCommit = true;
523
+ }
524
+ }
525
+ if (args.strictLinks) options.strictLinks = true;
526
+ if (args.policy) options.writePolicy = writePolicyOption(args);
527
+ if (args.languages) options.languages = args.languages;
528
+ Object.assign(options, embeddingCli.embeddingServerOptions(args));
529
+ if (args.proposalRoot) options.proposalRoot = args.proposalRoot;
530
+ if (args.project) {
531
+ options.projectPath = args.project;
532
+ } else if (args.root) {
533
+ options.rootPath = args.root;
534
+ }
535
+ return options;
536
+ }
537
+
538
+ module.exports = {
539
+ COMMANDS,
540
+ PRODUCER_ACTIONS,
541
+ UsageError,
542
+ WRITE_COMMANDS,
543
+ discoverProject,
544
+ exitCodeForError,
545
+ parseArgs,
546
+ parseJsonObject,
547
+ parseRemoteBundleArg,
548
+ parseRepositoryMappings,
549
+ readJsonObjectSource,
550
+ resolveLegacyBundles,
551
+ stdioServerOptions,
552
+ usageError,
553
+ writePolicyOption,
554
+ };
@@ -0,0 +1,96 @@
1
+ "use strict";
2
+
3
+ // The --help text of the okf / okf-mcp binary.
4
+
5
+ const embeddingCli = require("../search/embedding-cli");
6
+
7
+ function usage() {
8
+ return [
9
+ "okf-mcp / okf",
10
+ "",
11
+ "Usage:",
12
+ " okf-mcp --root <okf-directory> <command>",
13
+ " okf-mcp --root <okf-directory> [--repo <repository-concept-id=path>] mcp",
14
+ " okf-mcp --bundle <path-or-id=path> [--bundle <path>] [--inspect]",
15
+ " okf-mcp --remote-bundle <id=github-tree-url> [--inspect]",
16
+ " okf-mcp --project <okf.project.yaml> <command>",
17
+ " okf-mcp [--project <okf.project.yaml>] [--authoring] [--write --actor <actor>] [--git-commit] mcp",
18
+ " okf-mcp --project <okf.project.yaml> serve [--host 127.0.0.1] [--port 8765]",
19
+ " okf-mcp --root <okf-directory> mcp --http [--host 127.0.0.1] [--port 8766] [--public-url <url>]",
20
+ " okf-mcp --project <okf.project.yaml> producer run <name> --write --actor <actor>",
21
+ " okf-mcp <command> --bundle <path-or-id=path>",
22
+ "",
23
+ "Commands:",
24
+ " mcp Start the stdio MCP server (--http: MCP over Streamable HTTP).",
25
+ " validate Validate project or bundles.",
26
+ " graph [json|dot|mermaid] Export graph.",
27
+ " search <query> Search concepts.",
28
+ " context <query> Budgeted sections; search filters, --budget, --limit, --provenance.",
29
+ " concept <id-or-locator> Print one concept.",
30
+ " neighbors <id-or-locator> Print inbound/outbound neighbors.",
31
+ " paths <from> <to> Find directed paths between concept locators.",
32
+ " provenance <id-or-locator> Trace source provenance without external fetches.",
33
+ " edge-kinds Count graph edge kinds.",
34
+ " computation inspect <uri> Inspect a static computation contract.",
35
+ " computation prepare <uri> --parameters-file <path|->",
36
+ " computation check-receipt <uri> --receipt-file <path|->",
37
+ " asset <okf-asset-uri> Read one indexed referenced asset.",
38
+ " source <concept> <source-id> Read one pinned Git source from a mapped repository.",
39
+ " migrate check [bundle] Check staged v0.2 migration readiness.",
40
+ " migrate preview [bundle] [actor-mappings-json]",
41
+ " generate Run configured generator plugins.",
42
+ " producer list List configured external metadata producers.",
43
+ " producer preview <name> Validate one producer's candidate bundle without writing.",
44
+ " producer run <name> Publish one producer (requires --write --actor).",
45
+ " serve Start the HTTP OKF API server.",
46
+ "",
47
+ "Options:",
48
+ " --root, -r <directory> Load one official OKF bundle root.",
49
+ " --repo <concept-id=path> Map a Git Repository concept to a checkout or bare repo; repeatable.",
50
+ " --authoring Enable MCP proposal authoring tools.",
51
+ " --write Enable direct validated-batch MCP concept writes (requires --actor).",
52
+ " --actor <actor> Stamp live writes, proposals, and producer runs with human:id, process:id, or provider/model.",
53
+ " --git-commit Commit each live write batch when the catalog is in a clean Git repo.",
54
+ " --policy <file> Write policy (YAML) for --root writes and proposals; a project declares writePolicy in okf.project.yaml.",
55
+ " --allow-remote-tool Enable runtime remote-bundle loading over MCP.",
56
+ " --http Serve MCP over Streamable HTTP instead of stdio (default port 8766).",
57
+ " --public-url <url> Public URL of the MCP endpoint (its path is served; its host is allowed).",
58
+ " --allowed-host <host> Accept this Host header besides the localhost names; repeatable.",
59
+ " --allowed-origin <origin> Accept browser requests from this origin besides localhost; repeatable.",
60
+ " --auth tokens:<file> Bearer tokens from a YAML list of SHA-256 hashes with subject, actor, scopes.",
61
+ " --auth introspect:<url> RFC 7662 introspection; credentials from OKF_INTROSPECTION_CLIENT_ID/SECRET.",
62
+ " --authorization-server <issuer> Issuer named in the protected-resource metadata (with introspect).",
63
+ " --refresh-interval <ms> With --http, re-read changed files before a request at most this often (2000).",
64
+ " --allow-computation-authoring Enable coordinated computation proposals (also requires --authoring).",
65
+ " --strict-links Treat broken internal Markdown links as project-invalid.",
66
+ " --languages <codes> Search stemming languages for --root/--bundle mode: auto (default, detected per bundle), none, or codes such as it,en.",
67
+ embeddingCli.EMBEDDING_USAGE,
68
+ " --include-assets Include referenced asset nodes where supported.",
69
+ " --include-external Include external provenance or graph leaves.",
70
+ " --generated-path <path> Mark a generated migration target; repeat as needed.",
71
+ " --parameters-file <path|-> Read computation parameters from a file or stdin.",
72
+ " --receipt-file <path|-> Read a computation receipt from a file or stdin.",
73
+ " --max-content-bytes <n> Bound asset reads to 1..1048576 bytes (default 65536).",
74
+ " Search filters: --status, --trust-tier, --freshness, --as-of, --has-sources,",
75
+ " --runtime, --attestation-ready, --frontmatter key=value,",
76
+ " --mode auto|all|any, --min-coverage <0..1>, --min-relevance <0..1>, --freshness-prior.",
77
+ " Text search matches every term and falls back to any term (mode auto); it accepts at most",
78
+ " 512 characters and 16 terms after stop words, and reports mode, coverage, and lowConfidence.",
79
+ " --version, -v Print the package version.",
80
+ " --help, -h Print this help.",
81
+ " --debug Include stack traces in error output.",
82
+ "",
83
+ "When no source is passed, a nearest version-declaring OKF root is preferred;",
84
+ "the nearest okf.project.yaml remains a legacy compatibility fallback.",
85
+ "",
86
+ "Examples:",
87
+ " node bin/okf-mcp.js --root ./okf/bundles/app validate",
88
+ " node bin/okf-mcp.js --bundle ./okf/bundles/app --inspect",
89
+ " node bin/okf-mcp.js --bundle app=./okf/bundles/app",
90
+ " node bin/okf-mcp.js --remote-bundle docs=https://github.com/org/repo/tree/main/okf/bundles/docs --inspect",
91
+ " node bin/okf-mcp.js --project okf.project.yaml validate",
92
+ "",
93
+ ].join("\n");
94
+ }
95
+
96
+ module.exports = { usage };