toolmenu 0.11.0 → 0.13.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 +150 -30
  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 +61 -18
  6. package/dist/auto.d.ts +71 -7
  7. package/dist/auto.js +267 -13
  8. package/dist/breakdown.d.ts +35 -6
  9. package/dist/breakdown.js +179 -23
  10. package/dist/catalog.d.ts +87 -10
  11. package/dist/catalog.js +415 -58
  12. package/dist/cli.js +116 -178
  13. package/dist/compare.js +20 -5
  14. package/dist/config.d.ts +5 -1
  15. package/dist/config.js +14 -0
  16. package/dist/connect.d.ts +4 -0
  17. package/dist/connect.js +132 -11
  18. package/dist/diff.d.ts +35 -1
  19. package/dist/diff.js +1132 -121
  20. package/dist/difference.d.ts +2 -0
  21. package/dist/difference.js +13 -12
  22. package/dist/explain.d.ts +103 -0
  23. package/dist/explain.js +434 -0
  24. package/dist/failures.d.ts +55 -0
  25. package/dist/failures.js +103 -0
  26. package/dist/help.d.ts +9 -0
  27. package/dist/help.js +198 -0
  28. package/dist/history.d.ts +13 -0
  29. package/dist/history.js +86 -6
  30. package/dist/init.d.ts +100 -5
  31. package/dist/init.js +520 -26
  32. package/dist/menu.js +10 -2
  33. package/dist/options.d.ts +135 -0
  34. package/dist/options.js +48 -0
  35. package/dist/probe.d.ts +15 -3
  36. package/dist/probe.js +35 -11
  37. package/dist/report.d.ts +1 -1
  38. package/dist/report.js +229 -99
  39. package/dist/rules/description.d.ts +7 -2
  40. package/dist/rules/description.js +89 -43
  41. package/dist/rules/determinism.d.ts +3 -1
  42. package/dist/rules/determinism.js +146 -11
  43. package/dist/rules/ids.d.ts +1 -1
  44. package/dist/rules/ids.js +9 -4
  45. package/dist/rules/index.d.ts +6 -0
  46. package/dist/rules/index.js +15 -5
  47. package/dist/rules/naming.d.ts +1 -1
  48. package/dist/rules/naming.js +66 -19
  49. package/dist/rules/rule.d.ts +18 -0
  50. package/dist/rules/rule.js +25 -1
  51. package/dist/rules/spec.d.ts +2 -0
  52. package/dist/rules/spec.js +61 -8
  53. package/dist/rules/write.d.ts +1 -1
  54. package/dist/rules/write.js +42 -10
  55. package/dist/semver.js +1 -1
  56. package/dist/session.d.ts +56 -7
  57. package/dist/session.js +800 -94
  58. package/dist/snapshot.d.ts +2 -2
  59. package/dist/snapshot.js +25 -7
  60. package/dist/types.d.ts +14 -0
  61. package/dist/words.d.ts +5 -0
  62. package/dist/words.js +14 -0
  63. package/package.json +1 -1
package/dist/cli.js CHANGED
@@ -1,111 +1,27 @@
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
6
  import { diffMenus } from './diff.js';
7
7
  import { loadMenu } from './menu.js';
8
8
  import { history, historyCsv } from './history.js';
9
9
  import { counts, formatDiff, formatHistory, formatPlan, formatSession, formatSnapshot } from './report.js';
10
- import { loadScenario, session, starterScenario } from './session.js';
11
- import { connect, listTools } from './connect.js';
10
+ import { loadScenario, session, starterScenario, unlockListers, valuesFromListing } from './session.js';
11
+ import { listTools } from './connect.js';
12
+ import { patiently, tooMany } from './failures.js';
12
13
  import { buildMenu } from './menu.js';
13
14
  import { existsSync } from 'node:fs';
14
15
  import { loadRoutes } from './routes.js';
15
16
  import { snapshot } from './snapshot.js';
16
- import { MAIN_SEED, probeMenu, seeded } from './probe.js';
17
- import { autoScenario, scenarioYaml } from './auto.js';
17
+ import { connectPatiently, MAIN_SEED, probeMenu, refusedForTooMany, seeded } from './probe.js';
18
+ import { autoScenario, loadValuesFile, parseAssumeReadOnly, parseValueFlag, scenarioYaml } from './auto.js';
18
19
  import { authDir, listLogins, login, logout } from './auth.js';
19
- import { detectProject, secretsNeeded, workflowYaml } from './init.js';
20
+ import { existingMessage, initReport, planInit, writeInit } from './init.js';
20
21
  import { SEVERITY_RANK } from './types.js';
21
22
  import { VERSION } from './version.js';
22
- const HELP = `toolmenu ${VERSION}
23
- Lint your MCP server's tool menu for changes that confuse agents or break caches.
24
-
25
- Usage:
26
- toolmenu init [options] -- <command> | <url> set up CI: a baseline and a workflow
27
- toolmenu snapshot [options] -- <command> [args...] stdio server
28
- toolmenu snapshot [options] <url> Streamable HTTP server
29
- toolmenu diff [options] <old.json> <new.json> compare two snapshots
30
- toolmenu history [options] <npm-package> snapshot and diff published versions
31
- toolmenu auth login <url> | logout <url> | list OAuth logins for HTTP servers
32
- toolmenu session --scenario <file> [options] -- <command> | <url>
33
- run a scripted session, watch the menu
34
- toolmenu session --auto [options] -- <command> | <url>
35
- the same, with steps built from the menu
36
-
37
- Commands:
38
- init snapshot the server into menu.json and write .github/workflows/toolmenu.yml
39
- snapshot establish the menu: list tools twice, write menu.json, run the menu rules
40
- diff compare releases: breaking changes, token change, semver bump
41
- session observe the menu changing while a scripted session runs
42
- history research release history: install, snapshot and diff published npm versions
43
- auth log in to an OAuth-protected server once; snapshot and session then use it
44
-
45
- Options:
46
- --out <path> where to write the menu (default: menu.json)
47
- --no-write don't write the menu file
48
- --routes <path> routes.yml: pin which words route to which tools
49
- --config <path> config file (default: toolmenu.config.json, if present)
50
- --format <fmt> text (default), json, github (annotations) or markdown (PR comments)
51
- --json same as --format json
52
- --fail-on <level> error (default), warn or info
53
- --header <k: v> HTTP header, repeatable (e.g. "Authorization: Bearer ...")
54
- --env <K=V> environment variable for a stdio server, repeatable. The server
55
- only gets a minimal environment (PATH, HOME, ...) plus these
56
- --no-auth don't use a stored OAuth login for this server
57
- --timeout <ms> per-request timeout (default: 30000)
58
- --catalog also read the operations behind a search tool (search and execute:
59
- discover, search_*_tools) and keep them in the menu file for diff
60
- --processes <n> server processes (stdio) or connections (HTTP) to compare,
61
- the main one included (default: 2; 1 turns the check off)
62
- -h, --help show this help
63
- -v, --version show the version
64
-
65
- diff options:
66
- --release <old>..<new> the release versions (npm, git tag) to check the bump
67
- against, e.g. 1.4.0..1.5.0. Without it, the bump isn't
68
- checked: serverInfo.version is often not the release
69
- --server-version-is-release check the bump against serverInfo.version instead
70
-
71
- session options:
72
- --scenario <path> scenario.yml: the steps to run (list, call, wait_for)
73
- --plan print the steps without connecting or running anything
74
- --init write a starter scenario from the server's menu (to --scenario,
75
- default scenario.yml; never overwrites)
76
- --auto build the steps from the menu: every read-only tool whose
77
- required arguments the schema can fill (const, default,
78
- examples, enum, type), then the first call again
79
- --open-world with --auto, also call read-only tools marked openWorldHint:
80
- true (web search, fetch, scraping): they may cost API credits
81
- --max-calls <n> with --auto, at most n calls (default: 20)
82
- --save-scenario <p> with --auto, write the steps it ran as a scenario file
83
- --union-out <path> write every tool the session saw as a menu file, to commit as
84
- the baseline for diff (tools behind unlocks included)
85
-
86
- history options (best effort; installs and runs third-party code, so use a container):
87
- --versions <n|all> number of published versions to inspect (default: 10)
88
- --include-prereleases include versions like 1.2.0-beta.1
89
- --arg <value> argument for the server's bin, repeatable (use --arg=--flag for flags)
90
- --bin <name> which bin to run when the package has several
91
- --cmd <template> command instead of the bin; {bin} and {dir} are filled in
92
- --allow-scripts run install scripts (off by default)
93
- --install-timeout <ms> per-version install timeout (default: 180000)
94
- --csv <path> also write the dataset as CSV
95
- --keep-installs keep each version's install directory
96
- --out <dir> where menus and history.json go (default: toolmenu-history/<package>)
97
-
98
- init options:
99
- --with-session the workflow also runs session --auto (calls read-only tools)
100
-
101
- auth options:
102
- --port <n> loopback port for the login redirect (default: 33418)
103
- --scope <scopes> scopes to ask for (default: the server's)
104
- --client-id <id> a pre-registered client, for servers without dynamic registration
105
- --client-secret <s> its secret, if it has one
106
-
107
- Exit codes: 0 clean · 1 findings at or above --fail-on · 2 couldn't connect or bad usage
108
- `;
23
+ import { CLI_OPTIONS } from './options.js';
24
+ import { commandHelp, isCommand, overview, unknownCommand } from './help.js';
109
25
  class UsageError extends Error {
110
26
  }
111
27
  export async function main(argv) {
@@ -115,59 +31,26 @@ export async function main(argv) {
115
31
  const { values, positionals } = parseArgs({
116
32
  args: before,
117
33
  allowPositionals: true,
118
- options: {
119
- out: { type: 'string' },
120
- 'no-write': { type: 'boolean' },
121
- routes: { type: 'string' },
122
- config: { type: 'string' },
123
- format: { type: 'string' },
124
- json: { type: 'boolean' },
125
- 'fail-on': { type: 'string' },
126
- header: { type: 'string', multiple: true },
127
- env: { type: 'string', multiple: true },
128
- timeout: { type: 'string' },
129
- 'no-auth': { type: 'boolean' },
130
- port: { type: 'string' },
131
- scope: { type: 'string' },
132
- 'client-id': { type: 'string' },
133
- 'client-secret': { type: 'string' },
134
- processes: { type: 'string' },
135
- versions: { type: 'string' },
136
- release: { type: 'string' },
137
- 'server-version-is-release': { type: 'boolean' },
138
- 'include-prereleases': { type: 'boolean' },
139
- arg: { type: 'string', multiple: true },
140
- bin: { type: 'string' },
141
- cmd: { type: 'string' },
142
- 'allow-scripts': { type: 'boolean' },
143
- 'install-timeout': { type: 'string' },
144
- csv: { type: 'string' },
145
- 'keep-installs': { type: 'boolean' },
146
- scenario: { type: 'string' },
147
- plan: { type: 'boolean' },
148
- init: { type: 'boolean' },
149
- 'union-out': { type: 'string' },
150
- auto: { type: 'boolean' },
151
- 'with-session': { type: 'boolean' },
152
- catalog: { type: 'boolean' },
153
- 'open-world': { type: 'boolean' },
154
- 'max-calls': { type: 'string' },
155
- 'save-scenario': { type: 'string' },
156
- help: { type: 'boolean', short: 'h' },
157
- version: { type: 'boolean', short: 'v' },
158
- },
34
+ options: CLI_OPTIONS,
159
35
  });
160
36
  if (values.version) {
161
37
  process.stdout.write(`${VERSION}\n`);
162
38
  return 0;
163
39
  }
164
40
  const [sub, ...rest] = positionals;
41
+ // toolmenu help [command] reads like toolmenu [command] --help.
42
+ if (sub === 'help' && rest.length <= 1) {
43
+ if (rest[0] && !isCommand(rest[0]))
44
+ throw new UsageError(unknownCommand(rest[0]));
45
+ process.stdout.write(rest[0] && isCommand(rest[0]) ? commandHelp(rest[0]) : overview());
46
+ return 0;
47
+ }
48
+ if (sub && !isCommand(sub))
49
+ throw new UsageError(unknownCommand(sub));
165
50
  if (values.help || !sub) {
166
- process.stdout.write(HELP);
51
+ process.stdout.write(sub && isCommand(sub) ? commandHelp(sub) : overview());
167
52
  return sub || values.help ? 0 : 2;
168
53
  }
169
- if (!['init', 'snapshot', 'diff', 'history', 'session', 'auth'].includes(sub))
170
- throw new UsageError(`Unknown command "${sub}". Try --help.`);
171
54
  const format = (values.json ? 'json' : values.format ?? 'text');
172
55
  if (!['text', 'json', 'github', 'markdown'].includes(format))
173
56
  throw new UsageError(`--format must be text, json, github or markdown`);
@@ -230,7 +113,7 @@ export async function main(argv) {
230
113
  });
231
114
  if (values.csv)
232
115
  await writeFile(values.csv, historyCsv(result));
233
- process.stdout.write(formatHistory(result, format, outDir) + '\n');
116
+ process.stdout.write(formatHistory(result, format, outDir, values.csv) + '\n');
234
117
  return result.rows.length > 0 && result.rows.every((r) => r.status === 'failed') ? 1 : 0;
235
118
  }
236
119
  if (sub === 'session' && values.init) {
@@ -238,12 +121,29 @@ export async function main(argv) {
238
121
  if (existsSync(path))
239
122
  throw new UsageError(`${path} already exists. Pick another path with --scenario.`);
240
123
  const initTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
241
- const conn = await connect(seeded(initTarget, MAIN_SEED), { timeoutMs });
124
+ const conn = await connectPatiently(seeded(initTarget, MAIN_SEED), { timeoutMs });
242
125
  try {
243
- const list = await listTools(conn, { timeoutMs });
126
+ const list = await patiently(() => listTools(conn, { timeoutMs }), { error: tooMany });
244
127
  const menu = buildMenu(list.tools, { name: conn.server.name, version: conn.server.version, protocolVersion: conn.protocolVersion });
245
- await writeFile(path, starterScenario(menu));
246
- process.stdout.write(`wrote ${path}: a starter scenario for ${menu.tools.length} tools. Fill in the TODOs, then run toolmenu session --scenario ${path}\n`);
128
+ // An unlock without an enum: its values come from the server's own read-only
129
+ // listing (list_toolsets), so the scenario can unlock every one.
130
+ const unlockValues = {};
131
+ const read = [];
132
+ for (const { unlock, lister } of unlockListers(menu.tools)) {
133
+ try {
134
+ const result = await conn.client.callTool({ name: lister, arguments: {} }, { timeout: timeoutMs });
135
+ const found = result.isError ? [] : valuesFromListing(result);
136
+ if (found.length) {
137
+ unlockValues[unlock] = found;
138
+ read.push(`${found.length} values for ${unlock} from ${lister}`);
139
+ }
140
+ }
141
+ catch {
142
+ // Left as TODO in the scenario.
143
+ }
144
+ }
145
+ await writeFile(path, starterScenario(menu, { values: unlockValues }));
146
+ process.stdout.write(`wrote ${path}: a starter scenario for ${menu.tools.length} tools${read.length ? ` (read ${read.join('; ')})` : ''}. Fill in the TODOs, then run toolmenu session --scenario ${path}\n`);
247
147
  }
248
148
  finally {
249
149
  await conn.close().catch(() => { });
@@ -251,32 +151,13 @@ export async function main(argv) {
251
151
  return 0;
252
152
  }
253
153
  if (sub === 'init') {
254
- const workflow = join('.github', 'workflows', 'toolmenu.yml');
255
- const baseline = values.out ?? 'menu.json';
256
- for (const f of [workflow, baseline])
257
- if (existsSync(f))
258
- throw new UsageError(`${f} already exists; init never overwrites. Remove it, or set things up by hand (README: "In CI").`);
259
154
  const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
155
+ const plan = planInit({ cwd: process.cwd(), target, out: values.out, session: values['with-session'] });
156
+ if (plan.existing.length)
157
+ throw new UsageError(existingMessage(plan));
260
158
  const { menu, findings } = await snapshot(target, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
261
- await writeFile(baseline, JSON.stringify(menu, null, 2) + '\n');
262
- await mkdir(dirname(workflow), { recursive: true });
263
- const project = detectProject('.');
264
- await writeFile(workflow, workflowYaml({ target, project, session: values['with-session'], baseline }));
265
- const c = counts(findings);
266
- const secrets = secretsNeeded(target);
267
- const lines = [
268
- `toolmenu init ${menu.server.name ?? 'server'} · ${menu.tools.length} tools · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)`,
269
- ` wrote ${baseline}: the baseline every pull request is compared with`,
270
- ` wrote ${workflow}${project.kind === 'unknown' ? ' (fill in the TODO: how CI builds your server)' : ` (${project.kind} project)`}`,
271
- ` today's menu: ${c.error} errors, ${c.warn} warnings, ${c.info} info (run toolmenu snapshot to see them)`,
272
- ...(secrets.length ? ['', `Add these repository secrets (Settings → Secrets and variables → Actions): ${secrets.join(', ')}`] : []),
273
- '',
274
- 'Next:',
275
- ` git add ${baseline} ${workflow} && git commit -m "Check the MCP tool menu on every PR"`,
276
- ' Then open a pull request: toolmenu comments on it. Refresh the baseline when a change is intended:',
277
- ` toolmenu snapshot --out ${baseline} ${target.kind === 'stdio' ? '-- ' + [target.command, ...target.args].join(' ') : target.url}`,
278
- ];
279
- process.stdout.write(lines.join('\n') + '\n');
159
+ await writeInit(plan, JSON.stringify(menu, null, 2) + '\n');
160
+ process.stdout.write(initReport(plan, { server: menu.server.name, version: menu.server.version, tools: menu.tools.length, tokens: menu.totalTokens, counts: counts(findings) }, target));
280
161
  return 0;
281
162
  }
282
163
  if (sub === 'session' && values.auto) {
@@ -288,17 +169,36 @@ export async function main(argv) {
288
169
  const savePath = values['save-scenario'];
289
170
  if (savePath && existsSync(savePath))
290
171
  throw new UsageError(`${savePath} already exists. Pick another path for --save-scenario.`);
172
+ // Values and vouched-for tools are checked before anything starts.
173
+ let given = {};
174
+ let assumeReadOnly = [];
175
+ try {
176
+ if (values['values-file'])
177
+ given = await loadValuesFile(values['values-file']);
178
+ for (const v of values.value ?? []) {
179
+ const [key, value] = parseValueFlag(v);
180
+ given[key] = value;
181
+ }
182
+ assumeReadOnly = parseAssumeReadOnly(values['assume-read-only'] ?? []);
183
+ }
184
+ catch (error) {
185
+ throw new UsageError(error instanceof Error ? error.message : String(error));
186
+ }
291
187
  const autoTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
292
- const menu = await probeMenu(seeded(autoTarget, MAIN_SEED), timeoutMs);
293
- const plan = autoScenario(menu, { openWorld: values['open-world'], maxCalls });
188
+ const waited = { ms: 0 };
189
+ const menu = await probeMenu(seeded(autoTarget, MAIN_SEED), timeoutMs, undefined, waited).catch((error) => {
190
+ throw refusedForTooMany(error, waited.ms);
191
+ });
192
+ const plan = autoScenario(menu, { openWorld: values['open-world'], maxCalls, values: given, assumeReadOnly });
294
193
  if (savePath)
295
194
  await writeFile(savePath, scenarioYaml(plan, menu.server.name));
296
195
  if (values.plan) {
297
196
  process.stdout.write(formatPlan(plan.scenario, 'auto') + '\n');
298
197
  return 0;
299
198
  }
300
- const result = await session(autoTarget, plan.scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: 'auto' });
301
- result.auto = { called: plan.called, skipped: plan.skipped };
199
+ const auto = { called: plan.called, skipped: plan.skipped, assumed: plan.assumed, withValues: plan.withValues, ignored: plan.ignored, maxCalls };
200
+ const result = await session(autoTarget, plan.scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: 'auto', unionOut: !!values['union-out'], auto });
201
+ result.auto ??= auto;
302
202
  if (values['union-out'])
303
203
  await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
304
204
  const output = formatSession(result, format);
@@ -307,6 +207,8 @@ export async function main(argv) {
307
207
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
308
208
  }
309
209
  if (sub === 'session') {
210
+ if (values.value || values['values-file'] || values['assume-read-only'])
211
+ 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.');
310
212
  if (!values.scenario)
311
213
  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.');
312
214
  let scenario;
@@ -321,7 +223,7 @@ export async function main(argv) {
321
223
  return 0;
322
224
  }
323
225
  const sessionTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
324
- const result = await session(sessionTarget, scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: values.scenario });
226
+ const result = await session(sessionTarget, scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: values.scenario, unionOut: !!values['union-out'] });
325
227
  if (values['union-out'])
326
228
  await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
327
229
  const output = formatSession(result, format);
@@ -362,17 +264,20 @@ async function authCommand(args, values) {
362
264
  const [action, url, ...extra] = args;
363
265
  if (action === 'list') {
364
266
  const logins = await listLogins();
365
- 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`);
267
+ const width = Math.max(0, ...logins.map((l) => l.serverUrl.length));
268
+ process.stdout.write(logins.length
269
+ ? [`${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'
270
+ : `No logins stored in ${authDir()}.\n→ Next: toolmenu auth login <url> for a server that asks for OAuth.\n`);
366
271
  return 0;
367
272
  }
368
273
  if (action !== 'login' && action !== 'logout')
369
- throw new UsageError('auth takes login <url>, logout <url> or list.');
274
+ throw new UsageError(`${action ? `auth has no action "${action}"` : 'auth needs an action'}: login <url>, logout <url> or list. See toolmenu auth --help.`);
370
275
  if (!url || extra.length)
371
276
  throw new UsageError(`auth ${action} needs one server URL: toolmenu auth ${action} https://example.com/mcp`);
372
277
  if (!/^https?:\/\//.test(url))
373
278
  throw new UsageError(`"${url}" isn't an http(s) URL.`);
374
279
  if (action === 'logout') {
375
- process.stdout.write((await logout(url)) ? `Logged out of ${url}.\n` : `No login stored for ${url}.\n`);
280
+ 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`);
376
281
  return 0;
377
282
  }
378
283
  const port = values.port ? Number(values.port) : undefined;
@@ -381,7 +286,7 @@ async function authCommand(args, values) {
381
286
  if (values['client-secret'] && !values['client-id'])
382
287
  throw new UsageError('--client-secret goes with --client-id');
383
288
  const result = await login(url, { port, scope: values.scope, clientId: values['client-id'], clientSecret: values['client-secret'] });
384
- 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`);
289
+ 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`);
385
290
  return 0;
386
291
  }
387
292
  function parsePairs(items, separator, flag) {
@@ -405,11 +310,44 @@ function exitWhenFlushed(code) {
405
310
  }
406
311
  process.stdout.write('', () => process.stderr.write('', () => process.exit(code)));
407
312
  }
313
+ // stdout carries the report alone (--format json is parsed by CI). Libraries log
314
+ // with console: the MCP SDK prints a console.debug line to stdout when a server
315
+ // has no tools capability. Their lines go to stderr.
316
+ for (const method of ['log', 'info', 'debug']) {
317
+ console[method] = (...args) => console.error(...args);
318
+ }
408
319
  main(process.argv.slice(2)).then(exitWhenFlushed, (error) => {
409
- const message = error instanceof Error ? error.message : String(error);
410
- process.stderr.write(`toolmenu: ${message}\n`);
320
+ process.stderr.write(`toolmenu: ${failureMessage(error)}\n`);
411
321
  exitWhenFlushed(2);
412
322
  });
323
+ /** What stopped the command. A mistyped option gets the nearest real one. */
324
+ function failureMessage(error) {
325
+ const message = error instanceof Error ? error.message : String(error);
326
+ const code = error?.code;
327
+ if (code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
328
+ const option = /Unknown option '([^']+)'/.exec(message)?.[1] ?? '';
329
+ const known = Object.keys(CLI_OPTIONS).map((name) => `--${name}`);
330
+ const guess = known.map((k) => [k, editDistance(option, k)]).sort((a, b) => a[1] - b[1])[0];
331
+ const hint = guess && guess[1] <= 2 ? ` Did you mean ${guess[0]}?` : '';
332
+ return `Unknown option ${option}.${hint}\n → Next: toolmenu --help lists every option. (A server's own flags go after "--".)`;
333
+ }
334
+ if (typeof code === 'string' && code.startsWith('ERR_PARSE_ARGS_'))
335
+ return `${message}\n → Next: toolmenu --help lists every option.`;
336
+ return message;
337
+ }
338
+ function editDistance(a, b) {
339
+ const row = Array.from({ length: b.length + 1 }, (_, i) => i);
340
+ for (let i = 1; i <= a.length; i++) {
341
+ let diagonal = row[0];
342
+ row[0] = i;
343
+ for (let j = 1; j <= b.length; j++) {
344
+ const above = row[j];
345
+ row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
346
+ diagonal = above;
347
+ }
348
+ }
349
+ return row[b.length];
350
+ }
413
351
  function parseRelease(value) {
414
352
  const m = /^(.+?)\.\.(.+)$/.exec(value);
415
353
  if (!m)
package/dist/compare.js CHANGED
@@ -35,18 +35,33 @@ export function toolDiff(before, after) {
35
35
  kinds.push('serialization');
36
36
  return kinds;
37
37
  }
38
+ /**
39
+ * Each tool's identity in a list: its name, and for a name that repeats, which
40
+ * occurrence it is. The second `search` pairs with the second `search`, so a
41
+ * duplicate (menu/duplicate-name) isn't also read as a reorder.
42
+ */
43
+ function identities(tools) {
44
+ const seen = new Map();
45
+ return tools.map((t) => {
46
+ const n = seen.get(t.name) ?? 0;
47
+ seen.set(t.name, n + 1);
48
+ return n === 0 ? t.name : `${t.name}\u0000${n}`;
49
+ });
50
+ }
38
51
  export function compareMenus(before, after) {
39
52
  const changes = [];
40
- const beforeByName = new Map(before.map((t, i) => [t.name, { tool: t, index: i }]));
41
- const afterNames = new Set(after.map((t) => t.name));
53
+ const beforeIds = identities(before);
54
+ const afterIds = identities(after);
55
+ const beforeById = new Map(before.map((t, i) => [beforeIds[i], { tool: t, index: i }]));
56
+ const afterIdSet = new Set(afterIds);
42
57
  before.forEach((t, i) => {
43
- if (!afterNames.has(t.name))
58
+ if (!afterIdSet.has(beforeIds[i]))
44
59
  changes.push({ kind: 'removed', tool: t.name, position: i });
45
60
  });
46
61
  // Tools present in both: the ones outside the longest run that kept its
47
62
  // relative order are the ones that moved.
48
63
  const common = after
49
- .map((t, i) => ({ name: t.name, afterIndex: i, beforeIndex: beforeByName.get(t.name)?.index }))
64
+ .map((t, i) => ({ name: t.name, afterIndex: i, beforeIndex: beforeById.get(afterIds[i])?.index }))
50
65
  .filter((c) => c.beforeIndex !== undefined);
51
66
  const kept = longestIncreasingRun(common.map((c) => c.beforeIndex));
52
67
  common.forEach((c, i) => {
@@ -54,7 +69,7 @@ export function compareMenus(before, after) {
54
69
  changes.push({ kind: 'moved', tool: c.name, position: c.afterIndex });
55
70
  });
56
71
  after.forEach((t, i) => {
57
- const old = beforeByName.get(t.name);
72
+ const old = beforeById.get(afterIds[i]);
58
73
  if (!old) {
59
74
  changes.push({ kind: 'added', tool: t.name, position: i });
60
75
  return;
package/dist/config.d.ts CHANGED
@@ -16,9 +16,13 @@ export interface Config {
16
16
  fullDescriptions?: string[];
17
17
  /** Server processes (stdio) or connections (HTTP) to compare, the main one included (default 2). */
18
18
  processes?: number;
19
- /** snapshot --catalog: which search tool and which queries (default: detected, derived from the menu). */
19
+ /**
20
+ * snapshot --catalog: which search tool and which queries (default: detected,
21
+ * derived from the menu), or which command routers to list (default: detected).
22
+ */
20
23
  catalog?: {
21
24
  tool?: string;
25
+ routers?: string[];
22
26
  queries?: string[];
23
27
  pauseMs?: number;
24
28
  crawl?: boolean;
package/dist/config.js CHANGED
@@ -26,5 +26,19 @@ export async function loadConfig(path) {
26
26
  if (config.processes !== undefined && !(Number.isInteger(config.processes) && config.processes >= 1)) {
27
27
  throw new Error(`${file}: processes must be a whole number, 1 or more`);
28
28
  }
29
+ const catalog = config.catalog;
30
+ if (catalog !== undefined) {
31
+ const names = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === 'string' && x.length > 0);
32
+ if (typeof catalog !== 'object' || catalog === null || Array.isArray(catalog))
33
+ throw new Error(`${file}: catalog must be an object, like { "routers": ["keyvault"] } or { "tool": "search_tools" }`);
34
+ if (catalog.tool !== undefined && !(typeof catalog.tool === 'string' && catalog.tool))
35
+ throw new Error(`${file}: catalog.tool must be the name of the search tool, a string`);
36
+ if (catalog.routers !== undefined && !names(catalog.routers))
37
+ throw new Error(`${file}: catalog.routers must be a list of tool names, like ["keyvault", "storage"]`);
38
+ if (catalog.tool !== undefined && catalog.routers !== undefined)
39
+ 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`);
40
+ if (catalog.queries !== undefined && !names(catalog.queries))
41
+ throw new Error(`${file}: catalog.queries must be a list of search phrases, like ["list issues"]`);
42
+ }
29
43
  return config;
30
44
  }
package/dist/connect.d.ts CHANGED
@@ -47,6 +47,10 @@ export interface Connection {
47
47
  usedAuth: boolean;
48
48
  stderr: () => string;
49
49
  close: () => Promise<void>;
50
+ /** An error from a request on this connection, said with what the connection saw (exit code, stderr, stray stdout). */
51
+ explain?: (error: unknown, stage: string) => unknown;
52
+ /** Resolves once a server that just failed a request has had its say on stderr (all of it, if it exited). */
53
+ stderrSettled?: () => Promise<void>;
50
54
  }
51
55
  export interface ConnectOptions {
52
56
  timeoutMs?: number;