toolmenu 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +84 -23
  2. package/dist/args.d.ts +31 -5
  3. package/dist/args.js +91 -14
  4. package/dist/auth.d.ts +4 -2
  5. package/dist/auth.js +59 -21
  6. package/dist/auto.d.ts +80 -6
  7. package/dist/auto.js +255 -19
  8. package/dist/breakdown.d.ts +2 -0
  9. package/dist/breakdown.js +64 -19
  10. package/dist/catalog.d.ts +87 -10
  11. package/dist/catalog.js +415 -58
  12. package/dist/cli.js +170 -185
  13. package/dist/close.d.ts +8 -0
  14. package/dist/close.js +18 -0
  15. package/dist/config.d.ts +7 -1
  16. package/dist/config.js +17 -0
  17. package/dist/connect.d.ts +14 -0
  18. package/dist/connect.js +150 -16
  19. package/dist/diff.d.ts +23 -1
  20. package/dist/diff.js +574 -120
  21. package/dist/difference.d.ts +2 -0
  22. package/dist/difference.js +13 -12
  23. package/dist/explain.d.ts +113 -0
  24. package/dist/explain.js +461 -0
  25. package/dist/failures.d.ts +15 -0
  26. package/dist/failures.js +59 -2
  27. package/dist/help.d.ts +11 -0
  28. package/dist/help.js +205 -0
  29. package/dist/history.d.ts +13 -0
  30. package/dist/history.js +86 -6
  31. package/dist/init.d.ts +93 -2
  32. package/dist/init.js +508 -21
  33. package/dist/menu.js +10 -2
  34. package/dist/options.d.ts +141 -0
  35. package/dist/options.js +50 -0
  36. package/dist/report.d.ts +2 -2
  37. package/dist/report.js +305 -101
  38. package/dist/rules/description.d.ts +7 -2
  39. package/dist/rules/description.js +86 -42
  40. package/dist/rules/determinism.d.ts +4 -1
  41. package/dist/rules/determinism.js +175 -11
  42. package/dist/rules/gated.d.ts +7 -0
  43. package/dist/rules/gated.js +77 -0
  44. package/dist/rules/ids.d.ts +1 -1
  45. package/dist/rules/ids.js +9 -4
  46. package/dist/rules/index.d.ts +6 -0
  47. package/dist/rules/index.js +18 -6
  48. package/dist/rules/naming.d.ts +1 -1
  49. package/dist/rules/naming.js +91 -21
  50. package/dist/rules/rule.d.ts +25 -0
  51. package/dist/rules/rule.js +25 -1
  52. package/dist/rules/spec.d.ts +6 -0
  53. package/dist/rules/spec.js +56 -9
  54. package/dist/rules/write.d.ts +1 -1
  55. package/dist/rules/write.js +64 -14
  56. package/dist/session.d.ts +34 -9
  57. package/dist/session.js +525 -94
  58. package/dist/snapshot.d.ts +8 -2
  59. package/dist/snapshot.js +33 -2
  60. package/dist/types.d.ts +21 -0
  61. package/dist/words.d.ts +5 -0
  62. package/dist/words.js +14 -0
  63. package/package.json +2 -2
package/dist/cli.js CHANGED
@@ -1,8 +1,9 @@
1
1
  #!/usr/bin/env node
2
- import { mkdir, writeFile } from 'node:fs/promises';
3
- import { dirname, join } from 'node:path';
2
+ import { writeFile } from 'node:fs/promises';
3
+ import { join } from 'node:path';
4
4
  import { parseArgs } from 'node:util';
5
5
  import { loadConfig } from './config.js';
6
+ import { PROTOCOLS } from './connect.js';
6
7
  import { diffMenus } from './diff.js';
7
8
  import { loadMenu } from './menu.js';
8
9
  import { history, historyCsv } from './history.js';
@@ -15,161 +16,49 @@ import { existsSync } from 'node:fs';
15
16
  import { loadRoutes } from './routes.js';
16
17
  import { snapshot } from './snapshot.js';
17
18
  import { connectPatiently, MAIN_SEED, probeMenu, refusedForTooMany, seeded } from './probe.js';
18
- import { autoScenario, scenarioYaml } from './auto.js';
19
+ import { autoScenario, loadValuesFile, parseAssumeReadOnly, parseValueFlag, scenarioYaml } from './auto.js';
19
20
  import { authDir, listLogins, login, logout } from './auth.js';
20
- import { detectProject, secretsNeeded, workflowYaml } from './init.js';
21
+ import { existingMessage, initReport, planInit, shellWord, writeInit } from './init.js';
21
22
  import { SEVERITY_RANK } from './types.js';
22
23
  import { VERSION } from './version.js';
23
- const HELP = `toolmenu ${VERSION}
24
- Lint your MCP server's tool menu for changes that confuse agents or break caches.
25
-
26
- Usage:
27
- toolmenu init [options] -- <command> | <url> set up CI: a baseline and a workflow
28
- toolmenu snapshot [options] -- <command> [args...] stdio server
29
- toolmenu snapshot [options] <url> Streamable HTTP server
30
- toolmenu diff [options] <old.json> <new.json> compare two snapshots
31
- toolmenu history [options] <npm-package> snapshot and diff published versions
32
- toolmenu auth login <url> | logout <url> | list OAuth logins for HTTP servers
33
- toolmenu session --scenario <file> [options] -- <command> | <url>
34
- run a scripted session, watch the menu
35
- toolmenu session --auto [options] -- <command> | <url>
36
- the same, with steps built from the menu
37
-
38
- Commands:
39
- init snapshot the server into menu.json and write .github/workflows/toolmenu.yml
40
- snapshot establish the menu: list tools twice, write menu.json, run the menu rules
41
- diff compare releases: breaking changes, token change, semver bump
42
- session observe the menu changing while a scripted session runs
43
- history research release history: install, snapshot and diff published npm versions
44
- auth log in to an OAuth-protected server once; snapshot and session then use it
45
-
46
- Options:
47
- --out <path> where to write the menu (default: menu.json)
48
- --no-write don't write the menu file
49
- --routes <path> routes.yml: pin which words route to which tools
50
- --config <path> config file (default: toolmenu.config.json, if present)
51
- --format <fmt> text (default), json, github (annotations) or markdown (PR comments)
52
- --json same as --format json
53
- --fail-on <level> error (default), warn or info
54
- --header <k: v> HTTP header, repeatable (e.g. "Authorization: Bearer ...")
55
- --env <K=V> environment variable for a stdio server, repeatable. The server
56
- only gets a minimal environment (PATH, HOME, ...) plus these
57
- --no-auth don't use a stored OAuth login for this server
58
- --timeout <ms> per-request timeout (default: 30000)
59
- --catalog also read the operations behind a search tool (search and execute:
60
- discover, search_*_tools) and keep them in the menu file for diff
61
- --processes <n> server processes (stdio) or connections (HTTP) to compare,
62
- the main one included (default: 2; 1 opens no second one, for
63
- session's scope check either: for servers with one session per client)
64
- -h, --help show this help
65
- -v, --version show the version
66
-
67
- diff options:
68
- --release <old>..<new> the release versions (npm, git tag) to check the bump
69
- against, e.g. 1.4.0..1.5.0. Without it, the bump isn't
70
- checked: serverInfo.version is often not the release
71
- --server-version-is-release check the bump against serverInfo.version instead
72
-
73
- session options:
74
- --scenario <path> scenario.yml: the steps to run (list, call, wait_for)
75
- --plan print the steps without connecting or running anything
76
- --init write a starter scenario from the server's menu (to --scenario,
77
- default scenario.yml; never overwrites)
78
- --auto build the steps from the menu: every read-only tool whose
79
- required arguments the schema can fill (const, default,
80
- examples, enum, type), then the first call again
81
- --open-world with --auto, also call read-only tools marked openWorldHint:
82
- true (web search, fetch, scraping): they may cost API credits
83
- --max-calls <n> with --auto, at most n calls (default: 20)
84
- --save-scenario <p> with --auto, write the steps it ran as a scenario file
85
- --union-out <path> write every tool the session saw as a menu file, to commit as
86
- the baseline for diff (tools behind unlocks included)
87
-
88
- history options (best effort; installs and runs third-party code, so use a container):
89
- --versions <n|all> number of published versions to inspect (default: 10)
90
- --include-prereleases include versions like 1.2.0-beta.1
91
- --arg <value> argument for the server's bin, repeatable (use --arg=--flag for flags)
92
- --bin <name> which bin to run when the package has several
93
- --cmd <template> command instead of the bin; {bin} and {dir} are filled in
94
- --allow-scripts run install scripts (off by default)
95
- --install-timeout <ms> per-version install timeout (default: 180000)
96
- --csv <path> also write the dataset as CSV
97
- --keep-installs keep each version's install directory
98
- --out <dir> where menus and history.json go (default: toolmenu-history/<package>)
99
-
100
- init options:
101
- --with-session the workflow also runs session --auto (calls read-only tools)
102
-
103
- auth options:
104
- --port <n> loopback port for the login redirect (default: 33418)
105
- --scope <scopes> scopes to ask for (default: the server's)
106
- --client-id <id> a pre-registered client, for servers without dynamic registration
107
- --client-secret <s> its secret, if it has one
108
-
109
- Exit codes: 0 clean · 1 findings at or above --fail-on · 2 couldn't connect or bad usage
110
- `;
24
+ import { CLI_OPTIONS } from './options.js';
25
+ import { commandHelp, commandOptions, isCommand, overview, unknownCommand } from './help.js';
111
26
  class UsageError extends Error {
112
27
  }
113
28
  export async function main(argv) {
114
29
  const dash = argv.indexOf('--');
115
30
  const before = dash === -1 ? argv : argv.slice(0, dash);
116
31
  const command = dash === -1 ? undefined : argv.slice(dash + 1);
117
- const { values, positionals } = parseArgs({
118
- args: before,
119
- allowPositionals: true,
120
- options: {
121
- out: { type: 'string' },
122
- 'no-write': { type: 'boolean' },
123
- routes: { type: 'string' },
124
- config: { type: 'string' },
125
- format: { type: 'string' },
126
- json: { type: 'boolean' },
127
- 'fail-on': { type: 'string' },
128
- header: { type: 'string', multiple: true },
129
- env: { type: 'string', multiple: true },
130
- timeout: { type: 'string' },
131
- 'no-auth': { type: 'boolean' },
132
- port: { type: 'string' },
133
- scope: { type: 'string' },
134
- 'client-id': { type: 'string' },
135
- 'client-secret': { type: 'string' },
136
- processes: { type: 'string' },
137
- versions: { type: 'string' },
138
- release: { type: 'string' },
139
- 'server-version-is-release': { type: 'boolean' },
140
- 'include-prereleases': { type: 'boolean' },
141
- arg: { type: 'string', multiple: true },
142
- bin: { type: 'string' },
143
- cmd: { type: 'string' },
144
- 'allow-scripts': { type: 'boolean' },
145
- 'install-timeout': { type: 'string' },
146
- csv: { type: 'string' },
147
- 'keep-installs': { type: 'boolean' },
148
- scenario: { type: 'string' },
149
- plan: { type: 'boolean' },
150
- init: { type: 'boolean' },
151
- 'union-out': { type: 'string' },
152
- auto: { type: 'boolean' },
153
- 'with-session': { type: 'boolean' },
154
- catalog: { type: 'boolean' },
155
- 'open-world': { type: 'boolean' },
156
- 'max-calls': { type: 'string' },
157
- 'save-scenario': { type: 'string' },
158
- help: { type: 'boolean', short: 'h' },
159
- version: { type: 'boolean', short: 'v' },
160
- },
161
- });
32
+ let parsed;
33
+ try {
34
+ parsed = parseArgs({ args: before, allowPositionals: true, options: CLI_OPTIONS });
35
+ }
36
+ catch (error) {
37
+ // Which command was meant, so the hint can name its help and its options.
38
+ const meant = commandIn(before);
39
+ if (meant && error && typeof error === 'object')
40
+ error.command = meant;
41
+ throw error;
42
+ }
43
+ const { values, positionals } = parsed;
162
44
  if (values.version) {
163
45
  process.stdout.write(`${VERSION}\n`);
164
46
  return 0;
165
47
  }
166
48
  const [sub, ...rest] = positionals;
49
+ // toolmenu help [command] reads like toolmenu [command] --help.
50
+ if (sub === 'help' && rest.length <= 1) {
51
+ if (rest[0] && !isCommand(rest[0]))
52
+ throw new UsageError(unknownCommand(rest[0]));
53
+ process.stdout.write(rest[0] && isCommand(rest[0]) ? commandHelp(rest[0]) : overview());
54
+ return 0;
55
+ }
56
+ if (sub && !isCommand(sub))
57
+ throw new UsageError(unknownCommand(sub));
167
58
  if (values.help || !sub) {
168
- process.stdout.write(HELP);
59
+ process.stdout.write(sub && isCommand(sub) ? commandHelp(sub) : overview());
169
60
  return sub || values.help ? 0 : 2;
170
61
  }
171
- if (!['init', 'snapshot', 'diff', 'history', 'session', 'auth'].includes(sub))
172
- throw new UsageError(`Unknown command "${sub}". Try --help.`);
173
62
  const format = (values.json ? 'json' : values.format ?? 'text');
174
63
  if (!['text', 'json', 'github', 'markdown'].includes(format))
175
64
  throw new UsageError(`--format must be text, json, github or markdown`);
@@ -181,7 +70,15 @@ export async function main(argv) {
181
70
  throw new UsageError(`--timeout must be a positive number of milliseconds`);
182
71
  if (sub === 'auth')
183
72
  return authCommand(rest, values);
73
+ // The invocation up to the server, for examples in messages: a session example
74
+ // without --auto or --scenario wouldn't run.
75
+ const scenarioFlag = values.scenario ? ` --scenario ${shellWord(values.scenario)}` : '';
76
+ const mode = sub !== 'session' ? '' : values.init ? ` --init${scenarioFlag}` : values.auto ? ' --auto' : scenarioFlag;
77
+ const prefix = `${sub}${mode}`;
184
78
  const config = await loadConfig(values.config);
79
+ const protocol = (values.protocol ?? config.protocol ?? 'auto');
80
+ if (!PROTOCOLS.includes(protocol))
81
+ throw new UsageError(`--protocol must be auto, legacy or modern`);
185
82
  const processes = values.processes !== undefined ? Number(values.processes) : config.processes ?? 2;
186
83
  if (!Number.isInteger(processes) || processes < 1)
187
84
  throw new UsageError('--processes must be a whole number, 1 or more');
@@ -232,14 +129,14 @@ export async function main(argv) {
232
129
  });
233
130
  if (values.csv)
234
131
  await writeFile(values.csv, historyCsv(result));
235
- process.stdout.write(formatHistory(result, format, outDir) + '\n');
132
+ process.stdout.write(formatHistory(result, format, outDir, values.csv) + '\n');
236
133
  return result.rows.length > 0 && result.rows.every((r) => r.status === 'failed') ? 1 : 0;
237
134
  }
238
135
  if (sub === 'session' && values.init) {
239
136
  const path = values.scenario ?? 'scenario.yml';
240
137
  if (existsSync(path))
241
138
  throw new UsageError(`${path} already exists. Pick another path with --scenario.`);
242
- const initTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
139
+ const initTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
243
140
  const conn = await connectPatiently(seeded(initTarget, MAIN_SEED), { timeoutMs });
244
141
  try {
245
142
  const list = await patiently(() => listTools(conn, { timeoutMs }), { error: tooMany });
@@ -270,57 +167,94 @@ export async function main(argv) {
270
167
  return 0;
271
168
  }
272
169
  if (sub === 'init') {
273
- const workflow = join('.github', 'workflows', 'toolmenu.yml');
274
- const baseline = values.out ?? 'menu.json';
275
- for (const f of [workflow, baseline])
276
- if (existsSync(f))
277
- throw new UsageError(`${f} already exists; init never overwrites. Remove it, or set things up by hand (README: "In CI").`);
278
- const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
170
+ const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
171
+ const plan = planInit({ cwd: process.cwd(), target, out: values.out, session: values['with-session'] });
172
+ if (plan.existing.length)
173
+ throw new UsageError(existingMessage(plan));
279
174
  const { menu, findings } = await snapshot(target, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
280
- await writeFile(baseline, JSON.stringify(menu, null, 2) + '\n');
281
- await mkdir(dirname(workflow), { recursive: true });
282
- const project = detectProject('.');
283
- await writeFile(workflow, workflowYaml({ target, project, session: values['with-session'], baseline }));
284
- const c = counts(findings);
285
- const secrets = secretsNeeded(target);
286
- const lines = [
287
- `toolmenu init ${menu.server.name ?? 'server'} · ${menu.tools.length} tools · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)`,
288
- ` wrote ${baseline}: the baseline every pull request is compared with`,
289
- ` wrote ${workflow}${project.kind === 'unknown' ? ' (fill in the TODO: how CI builds your server)' : ` (${project.kind} project)`}`,
290
- ` today's menu: ${c.error} errors, ${c.warn} warnings, ${c.info} info (run toolmenu snapshot to see them)`,
291
- ...(secrets.length ? ['', `Add these repository secrets (Settings → Secrets and variables → Actions): ${secrets.join(', ')}`] : []),
292
- '',
293
- 'Next:',
294
- ` git add ${baseline} ${workflow} && git commit -m "Check the MCP tool menu on every PR"`,
295
- ' Then open a pull request: toolmenu comments on it. Refresh the baseline when a change is intended:',
296
- ` toolmenu snapshot --out ${baseline} ${target.kind === 'stdio' ? '-- ' + [target.command, ...target.args].join(' ') : target.url}`,
297
- ];
298
- process.stdout.write(lines.join('\n') + '\n');
175
+ await writeInit(plan, JSON.stringify(menu, null, 2) + '\n');
176
+ process.stdout.write(initReport(plan, { server: menu.server.name, version: menu.server.version, tools: menu.tools.length, tokens: menu.totalTokens, counts: counts(findings) }, target));
299
177
  return 0;
300
178
  }
301
179
  if (sub === 'session' && values.auto) {
302
180
  if (values.scenario)
303
181
  throw new UsageError('--auto builds the steps itself; drop --scenario (or drop --auto).');
304
- const maxCalls = values['max-calls'] ? Number(values['max-calls']) : 20;
305
- if (!Number.isInteger(maxCalls) || maxCalls < 1)
182
+ const givenMax = values['max-calls'] ? Number(values['max-calls']) : undefined;
183
+ if (givenMax !== undefined && !(Number.isInteger(givenMax) && givenMax >= 1))
306
184
  throw new UsageError('--max-calls must be a whole number, 1 or more');
185
+ const perUnlock = values['max-calls-per-unlock'] ? Number(values['max-calls-per-unlock']) : 5;
186
+ if (!Number.isInteger(perUnlock) || perUnlock < 1)
187
+ throw new UsageError('--max-calls-per-unlock must be a whole number, 1 or more');
307
188
  const savePath = values['save-scenario'];
308
189
  if (savePath && existsSync(savePath))
309
190
  throw new UsageError(`${savePath} already exists. Pick another path for --save-scenario.`);
310
- const autoTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
191
+ // Values and vouched-for tools are checked before anything starts.
192
+ let given = {};
193
+ let assumeReadOnly = [];
194
+ try {
195
+ if (values['values-file'])
196
+ given = await loadValuesFile(values['values-file']);
197
+ for (const v of values.value ?? []) {
198
+ const [key, value] = parseValueFlag(v);
199
+ given[key] = value;
200
+ }
201
+ assumeReadOnly = parseAssumeReadOnly(values['assume-read-only'] ?? []);
202
+ }
203
+ catch (error) {
204
+ throw new UsageError(error instanceof Error ? error.message : String(error));
205
+ }
206
+ const autoTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
311
207
  const waited = { ms: 0 };
312
208
  const menu = await probeMenu(seeded(autoTarget, MAIN_SEED), timeoutMs, undefined, waited).catch((error) => {
313
209
  throw refusedForTooMany(error, waited.ms);
314
210
  });
315
- const plan = autoScenario(menu, { openWorld: values['open-world'], maxCalls });
211
+ const options = { openWorld: values['open-world'], values: given, assumeReadOnly };
212
+ let plan = autoScenario(menu, { ...options, maxCalls: givenMax ?? 20 });
213
+ // Each unlock value gets its own budget for the tools it brings, so the first
214
+ // toolsets can't use up the calls the last ones need. --max-calls, when given,
215
+ // caps every call, and the starting menu leaves up to half of it for the unlocks.
216
+ const reserve = givenMax === undefined ? 0 : Math.min(perUnlock * plan.unlockValues, Math.floor(givenMax / 2));
217
+ if (reserve)
218
+ plan = autoScenario(menu, { ...options, maxCalls: givenMax - reserve });
219
+ const maxCalls = givenMax ?? 20 + perUnlock * plan.unlockValues;
316
220
  if (savePath)
317
221
  await writeFile(savePath, scenarioYaml(plan, menu.server.name));
318
222
  if (values.plan) {
319
223
  process.stdout.write(formatPlan(plan.scenario, 'auto') + '\n');
320
224
  return 0;
321
225
  }
322
- const result = await session(autoTarget, plan.scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: 'auto', unionOut: !!values['union-out'], auto: { called: plan.called, skipped: plan.skipped } });
323
- result.auto = { called: plan.called, skipped: plan.skipped };
226
+ const auto = { called: plan.called, skipped: plan.skipped, assumed: plan.assumed, withValues: plan.withValues, ignored: plan.ignored, maxCalls, maxCallsPerUnlock: perUnlock };
227
+ // Tools that appear mid-session (behind an unlock) are planned when they appear,
228
+ // under the same rules and what's left of --max-calls. Each tool once.
229
+ const planned = new Set([...plan.called, ...plan.skipped.map((s) => s.tool)]);
230
+ let spent = plan.spent;
231
+ const replan = (added) => {
232
+ const fresh = added.filter((t) => !planned.has(t.name));
233
+ for (const t of fresh)
234
+ planned.add(t.name);
235
+ if (!fresh.length)
236
+ return [];
237
+ const left = maxCalls - spent;
238
+ const more = autoScenario({ ...menu, tools: fresh }, { ...options, maxCalls: Math.min(perUnlock, left), callsOnly: true });
239
+ // Left out by this unlock's own budget, not by the total: say which, for the right flag.
240
+ if (perUnlock < left)
241
+ for (const s of more.skipped)
242
+ if (s.reason === 'over the call budget')
243
+ s.reason = 'over the per-unlock budget';
244
+ spent += more.spent;
245
+ auto.called.push(...more.called);
246
+ auto.skipped.push(...more.skipped);
247
+ auto.assumed.push(...more.assumed);
248
+ auto.withValues.push(...more.withValues);
249
+ if (more.assumed.length)
250
+ plan.scenario.assumeReadOnly = [...(plan.scenario.assumeReadOnly ?? []), ...more.assumed];
251
+ return more.scenario.steps;
252
+ };
253
+ const result = await session(autoTarget, plan.scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: 'auto', unionOut: !!values['union-out'], auto, replan });
254
+ // A --value or --assume-read-only for a tool behind an unlock isn't unused: check
255
+ // them against every tool the session saw, not just the starting menu.
256
+ auto.ignored = autoScenario(result.union, { values: given, assumeReadOnly }).ignored;
257
+ result.auto = { ...result.auto, ...auto };
324
258
  if (values['union-out'])
325
259
  await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
326
260
  const output = formatSession(result, format);
@@ -329,6 +263,8 @@ export async function main(argv) {
329
263
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
330
264
  }
331
265
  if (sub === 'session') {
266
+ if (values.value || values['values-file'] || values['assume-read-only'])
267
+ throw new UsageError('--value, --values-file and --assume-read-only go with --auto. In a scenario, write the values into the steps\' args, and list tools under assume_read_only.');
332
268
  if (!values.scenario)
333
269
  throw new UsageError('session needs --scenario <file>. Run session --init for a starter, or see https://github.com/niksa90/toolmenu#session-the-menu-changing-while-the-agent-works for the format.');
334
270
  let scenario;
@@ -342,7 +278,7 @@ export async function main(argv) {
342
278
  process.stdout.write(formatPlan(scenario, values.scenario) + '\n');
343
279
  return 0;
344
280
  }
345
- const sessionTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
281
+ const sessionTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
346
282
  const result = await session(sessionTarget, scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: values.scenario, unionOut: !!values['union-out'] });
347
283
  if (values['union-out'])
348
284
  await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
@@ -351,7 +287,7 @@ export async function main(argv) {
351
287
  process.stdout.write(output + '\n');
352
288
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
353
289
  }
354
- const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
290
+ const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
355
291
  const routesPath = values.routes ?? config.routes;
356
292
  const routes = routesPath ? await loadRoutes(routesPath) : undefined;
357
293
  const { menu, findings } = await snapshot(target, { routes, timeoutMs, processes, catalog: values.catalog ? (config.catalog ?? true) : undefined, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
@@ -363,38 +299,41 @@ export async function main(argv) {
363
299
  process.stdout.write(output + '\n');
364
300
  return findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
365
301
  }
366
- function parseTarget(positionals, command, headers, env, noAuth = false) {
302
+ function parseTarget(positionals, command, headers, env, noAuth, prefix, protocol) {
367
303
  if (command) {
368
304
  if (command.length === 0)
369
305
  throw new UsageError('Nothing after "--": give the command that starts the server.');
370
306
  if (positionals.length)
371
307
  throw new UsageError(`Unexpected "${positionals[0]}" before "--".`);
372
- return { kind: 'stdio', command: command[0], args: command.slice(1), env: parsePairs(env, '=', '--env') };
308
+ return { kind: 'stdio', command: command[0], args: command.slice(1), env: parsePairs(env, '=', '--env'), ...(protocol !== 'auto' ? { protocol } : {}) };
373
309
  }
374
310
  const [url, ...extra] = positionals;
375
311
  if (!url)
376
- throw new UsageError('Give a server URL, or "-- <command>" for a stdio server.');
312
+ throw new UsageError(`Give a server: a URL, or the command that starts it after "--".\n → Next: toolmenu ${prefix} -- node dist/server.js (stdio) or toolmenu ${prefix} https://example.com/mcp (HTTP)`);
377
313
  if (extra.length)
378
314
  throw new UsageError(`Unexpected "${extra[0]}". For a stdio server, put the command after "--".`);
379
315
  if (!/^https?:\/\//.test(url))
380
316
  throw new UsageError(`"${url}" isn't an http(s) URL. For a stdio server, put the command after "--".`);
381
- return { kind: 'http', url, headers: parsePairs(headers, ':', '--header'), ...(noAuth ? { noAuth } : {}) };
317
+ return { kind: 'http', url, headers: parsePairs(headers, ':', '--header'), ...(noAuth ? { noAuth } : {}), ...(protocol !== 'auto' ? { protocol } : {}) };
382
318
  }
383
319
  async function authCommand(args, values) {
384
320
  const [action, url, ...extra] = args;
385
321
  if (action === 'list') {
386
322
  const logins = await listLogins();
387
- process.stdout.write(logins.length ? logins.map((l) => `${l.serverUrl} (issuer ${l.issuer ?? '?'}, saved ${l.savedAt?.slice(0, 10) ?? '?'})`).join('\n') + '\n' : `No logins. Stored in ${authDir()}.\n`);
323
+ const width = Math.max(0, ...logins.map((l) => l.serverUrl.length));
324
+ process.stdout.write(logins.length
325
+ ? [`${logins.length} login${logins.length === 1 ? '' : 's'}, stored in ${authDir()}:`, ...logins.map((l) => ` ${l.serverUrl.padEnd(width)} issuer ${l.issuer ?? 'not recorded'} · saved ${l.savedAt?.slice(0, 10) ?? '?'}`)].join('\n') + '\n'
326
+ : `No logins stored in ${authDir()}.\n→ Next: toolmenu auth login <url> for a server that asks for OAuth.\n`);
388
327
  return 0;
389
328
  }
390
329
  if (action !== 'login' && action !== 'logout')
391
- throw new UsageError('auth takes login <url>, logout <url> or list.');
330
+ throw new UsageError(`${action ? `auth has no action "${action}"` : 'auth needs an action'}: login <url>, logout <url> or list. See toolmenu auth --help.`);
392
331
  if (!url || extra.length)
393
332
  throw new UsageError(`auth ${action} needs one server URL: toolmenu auth ${action} https://example.com/mcp`);
394
333
  if (!/^https?:\/\//.test(url))
395
334
  throw new UsageError(`"${url}" isn't an http(s) URL.`);
396
335
  if (action === 'logout') {
397
- process.stdout.write((await logout(url)) ? `Logged out of ${url}.\n` : `No login stored for ${url}.\n`);
336
+ process.stdout.write((await logout(url)) ? `Logged out of ${url}: its tokens and client registration are removed from ${authDir()}.\n` : `No login stored for ${url} (in ${authDir()}), so nothing to remove. toolmenu auth list shows the stored ones.\n`);
398
337
  return 0;
399
338
  }
400
339
  const port = values.port ? Number(values.port) : undefined;
@@ -403,7 +342,7 @@ async function authCommand(args, values) {
403
342
  if (values['client-secret'] && !values['client-id'])
404
343
  throw new UsageError('--client-secret goes with --client-id');
405
344
  const result = await login(url, { port, scope: values.scope, clientId: values['client-id'], clientSecret: values['client-secret'] });
406
- process.stdout.write(`Logged in to ${result.name ?? url}: ${result.tools} tools. snapshot and session use this login from now on (--no-auth to skip it).\n`);
345
+ process.stdout.write(`Logged in to ${result.name ?? url} (${url}): it lists ${result.tools} tool${result.tools === 1 ? '' : 's'} with this login.\nsnapshot and session use it from now on (--no-auth to skip it); stored in ${authDir()}.\n`);
407
346
  return 0;
408
347
  }
409
348
  function parsePairs(items, separator, flag) {
@@ -434,10 +373,56 @@ for (const method of ['log', 'info', 'debug']) {
434
373
  console[method] = (...args) => console.error(...args);
435
374
  }
436
375
  main(process.argv.slice(2)).then(exitWhenFlushed, (error) => {
437
- const message = error instanceof Error ? error.message : String(error);
438
- process.stderr.write(`toolmenu: ${message}\n`);
376
+ process.stderr.write(`toolmenu: ${failureMessage(error)}\n`);
439
377
  exitWhenFlushed(2);
440
378
  });
379
+ /** What stopped the command. A mistyped option gets the nearest real one. */
380
+ function failureMessage(error) {
381
+ const message = error instanceof Error ? error.message : String(error);
382
+ const code = error?.code;
383
+ const command = error?.command;
384
+ const next = command
385
+ ? `toolmenu ${command} --help lists its options. (A server's own flags go after "--".)`
386
+ : 'toolmenu --help lists the commands; toolmenu <command> --help lists its options.';
387
+ if (code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
388
+ const option = /Unknown option '([^']+)'/.exec(message)?.[1] ?? '';
389
+ const known = (command ? [...commandOptions(command), 'help', 'version'] : Object.keys(CLI_OPTIONS)).map((name) => `--${name}`);
390
+ const guess = known.map((k) => [k, editDistance(option, k)]).sort((a, b) => a[1] - b[1])[0];
391
+ const hint = guess && guess[1] <= 2 ? ` Did you mean ${guess[0]}?` : '';
392
+ return `Unknown option ${option}.${hint}\n → Next: ${next}`;
393
+ }
394
+ if (typeof code === 'string' && code.startsWith('ERR_PARSE_ARGS_'))
395
+ return `${message}\n → Next: ${next}`;
396
+ return message;
397
+ }
398
+ /** The command in arguments parseArgs refused: the first command name that isn't an option's value (--out diff). */
399
+ function commandIn(args) {
400
+ for (let i = 0; i < args.length; i++) {
401
+ const a = args[i];
402
+ if (a.startsWith('--')) {
403
+ const option = CLI_OPTIONS[a.slice(2)];
404
+ if (option?.type === 'string' && !a.includes('='))
405
+ i++;
406
+ continue;
407
+ }
408
+ if (isCommand(a))
409
+ return a;
410
+ }
411
+ return undefined;
412
+ }
413
+ function editDistance(a, b) {
414
+ const row = Array.from({ length: b.length + 1 }, (_, i) => i);
415
+ for (let i = 1; i <= a.length; i++) {
416
+ let diagonal = row[0];
417
+ row[0] = i;
418
+ for (let j = 1; j <= b.length; j++) {
419
+ const above = row[j];
420
+ row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
421
+ diagonal = above;
422
+ }
423
+ }
424
+ return row[b.length];
425
+ }
441
426
  function parseRelease(value) {
442
427
  const m = /^(.+?)\.\.(.+)$/.exec(value);
443
428
  if (!m)
@@ -0,0 +1,8 @@
1
+ import type { Client, Transport } from '@modelcontextprotocol/client';
2
+ /**
3
+ * Close a client and end its HTTP session. Closing the client only drops the
4
+ * connection: the server keeps the session (Mcp-Session-Id) until a DELETE ends
5
+ * it, and servers that keep idle sessions for hours under a cap fill up after a
6
+ * few dozen runs. A server that doesn't allow the DELETE (405) is fine.
7
+ */
8
+ export declare function endSession(client: Client, transport: Transport): Promise<void>;
package/dist/close.js ADDED
@@ -0,0 +1,18 @@
1
+ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
2
+ /** A server that never answers the DELETE must not hold the run up. */
3
+ const END_SESSION_MS = 3000;
4
+ /**
5
+ * Close a client and end its HTTP session. Closing the client only drops the
6
+ * connection: the server keeps the session (Mcp-Session-Id) until a DELETE ends
7
+ * it, and servers that keep idle sessions for hours under a cap fill up after a
8
+ * few dozen runs. A server that doesn't allow the DELETE (405) is fine.
9
+ */
10
+ export async function endSession(client, transport) {
11
+ if (transport instanceof StreamableHTTPClientTransport && transport.sessionId) {
12
+ let timer;
13
+ const gaveUp = new Promise((done) => (timer = setTimeout(done, END_SESSION_MS)));
14
+ await Promise.race([transport.terminateSession().catch(() => { }), gaveUp]);
15
+ clearTimeout(timer);
16
+ }
17
+ await client.close().catch(() => { });
18
+ }
package/dist/config.d.ts CHANGED
@@ -4,6 +4,8 @@ export interface Config {
4
4
  ignore?: string[];
5
5
  routes?: string;
6
6
  baseline?: string;
7
+ /** Which handshake to make: auto (default), legacy (2025 only) or modern (2026-07-28 only). --protocol wins. */
8
+ protocol?: 'auto' | 'legacy' | 'modern';
7
9
  tokenBudget?: number;
8
10
  /** diff checks the semver bump against serverInfo.version (off: it's often not the release version). */
9
11
  serverVersionIsRelease?: boolean;
@@ -16,9 +18,13 @@ export interface Config {
16
18
  fullDescriptions?: string[];
17
19
  /** Server processes (stdio) or connections (HTTP) to compare, the main one included (default 2). */
18
20
  processes?: number;
19
- /** snapshot --catalog: which search tool and which queries (default: detected, derived from the menu). */
21
+ /**
22
+ * snapshot --catalog: which search tool and which queries (default: detected,
23
+ * derived from the menu), or which command routers to list (default: detected).
24
+ */
20
25
  catalog?: {
21
26
  tool?: string;
27
+ routers?: string[];
22
28
  queries?: string[];
23
29
  pauseMs?: number;
24
30
  crawl?: boolean;
package/dist/config.js CHANGED
@@ -19,6 +19,9 @@ export async function loadConfig(path) {
19
19
  throw new Error(`${file}: rules["${id}"] must be error, warn, info or off`);
20
20
  }
21
21
  }
22
+ if (config.protocol !== undefined && !['auto', 'legacy', 'modern'].includes(config.protocol)) {
23
+ throw new Error(`${file}: protocol must be auto, legacy or modern`);
24
+ }
22
25
  const limit = config.descriptionLimit;
23
26
  if (limit !== undefined && !(typeof limit === 'number' && limit > 0) && !(typeof limit === 'string' && limit in CLIENT_LIMITS)) {
24
27
  throw new Error(`${file}: descriptionLimit must be a positive number or one of ${Object.keys(CLIENT_LIMITS).join(', ')}`);
@@ -26,5 +29,19 @@ export async function loadConfig(path) {
26
29
  if (config.processes !== undefined && !(Number.isInteger(config.processes) && config.processes >= 1)) {
27
30
  throw new Error(`${file}: processes must be a whole number, 1 or more`);
28
31
  }
32
+ const catalog = config.catalog;
33
+ if (catalog !== undefined) {
34
+ const names = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === 'string' && x.length > 0);
35
+ if (typeof catalog !== 'object' || catalog === null || Array.isArray(catalog))
36
+ throw new Error(`${file}: catalog must be an object, like { "routers": ["keyvault"] } or { "tool": "search_tools" }`);
37
+ if (catalog.tool !== undefined && !(typeof catalog.tool === 'string' && catalog.tool))
38
+ throw new Error(`${file}: catalog.tool must be the name of the search tool, a string`);
39
+ if (catalog.routers !== undefined && !names(catalog.routers))
40
+ throw new Error(`${file}: catalog.routers must be a list of tool names, like ["keyvault", "storage"]`);
41
+ if (catalog.tool !== undefined && catalog.routers !== undefined)
42
+ throw new Error(`${file}: catalog names both a search tool (tool) and routers (routers); a menu file keeps one catalog, so keep the one the operations are behind`);
43
+ if (catalog.queries !== undefined && !names(catalog.queries))
44
+ throw new Error(`${file}: catalog.queries must be a list of search phrases, like ["list issues"]`);
45
+ }
29
46
  return config;
30
47
  }
package/dist/connect.d.ts CHANGED
@@ -1,17 +1,27 @@
1
1
  import { Client } from '@modelcontextprotocol/client';
2
2
  import type { Transport } from '@modelcontextprotocol/client';
3
3
  import type { Era } from './types.js';
4
+ /**
5
+ * Which handshake to make. auto: try the 2026-07-28 `server/discover` first and fall back
6
+ * to the 2025 one. legacy: the 2025 handshake only. modern: 2026-07-28 only, an error if
7
+ * the server can't speak it.
8
+ */
9
+ export type Protocol = 'auto' | 'legacy' | 'modern';
10
+ export declare const PROTOCOLS: readonly Protocol[];
11
+ export declare const MODERN_VERSION = "2026-07-28";
4
12
  export type Target = {
5
13
  kind: 'stdio';
6
14
  command: string;
7
15
  args: string[];
8
16
  env?: Record<string, string>;
9
17
  cwd?: string;
18
+ protocol?: Protocol;
10
19
  } | {
11
20
  kind: 'http';
12
21
  url: string;
13
22
  headers?: Record<string, string>;
14
23
  noAuth?: boolean;
24
+ protocol?: Protocol;
15
25
  };
16
26
  export interface WireResponse {
17
27
  method: string;
@@ -47,6 +57,10 @@ export interface Connection {
47
57
  usedAuth: boolean;
48
58
  stderr: () => string;
49
59
  close: () => Promise<void>;
60
+ /** An error from a request on this connection, said with what the connection saw (exit code, stderr, stray stdout). */
61
+ explain?: (error: unknown, stage: string) => unknown;
62
+ /** Resolves once a server that just failed a request has had its say on stderr (all of it, if it exited). */
63
+ stderrSettled?: () => Promise<void>;
50
64
  }
51
65
  export interface ConnectOptions {
52
66
  timeoutMs?: number;