toolmenu 0.14.1 → 0.16.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.
package/README.md CHANGED
@@ -20,6 +20,10 @@ connections and releases, and checks **when** it changes:
20
20
  - **Ready for 2026-07-28.** That protocol version says the tool set **must not** vary
21
21
  per connection or as a side effect of other requests (the 2025 versions allow it).
22
22
  Per-session "unlock" designs, like the one I built, are ruled out. `session` tells you whether yours is one of them.
23
+ It also checks the menu clients will actually show: a broken `x-mcp-header` or a
24
+ `$ref` they can't resolve hides a tool or fails every call to it. And when a tool
25
+ stops to ask the user something, `session` answers "no" and says whether the tool
26
+ can take it.
23
27
  - **Between releases.** `diff` finds breaking changes and token growth, and checks
24
28
  the version bump.
25
29
 
@@ -29,7 +33,7 @@ No LLM anywhere: the same inputs give the same answer, so it can sit in CI.
29
33
  (`history` installs old versions with today's dependencies, so it records what they
30
34
  serve now, which can differ from what they shipped with: FINDINGS F4.)
31
35
 
32
- > **Status: 0.14, early.** Spec in [docs/SPEC.md](https://github.com/niksa90/toolmenu/blob/main/docs/SPEC.md). What it has found on
36
+ > **Status: 0.16, early.** Spec in [docs/SPEC.md](https://github.com/niksa90/toolmenu/blob/main/docs/SPEC.md). What it has found on
33
37
  > real servers: [docs/FINDINGS.md](https://github.com/niksa90/toolmenu/blob/main/docs/FINDINGS.md).
34
38
 
35
39
  ## Start here
@@ -104,7 +108,7 @@ jobs:
104
108
  - uses: actions/setup-node@v7
105
109
  with: { node-version: 22 }
106
110
  - run: npm ci && npm run build
107
- - uses: niksa90/toolmenu@v0.14.1
111
+ - uses: niksa90/toolmenu@v0.16.0
108
112
  with:
109
113
  command: node dist/server.js
110
114
  baseline: menu.json # your committed snapshot
package/dist/breakdown.js CHANGED
@@ -43,15 +43,33 @@ function unusedDefs(menu) {
43
43
  const { $defs: _d, definitions: _df, ...rest } = schema;
44
44
  const used = new Set();
45
45
  const queue = [JSON.stringify(rest)];
46
+ const use = (pool, name) => {
47
+ const id = `${pool}/${name}`;
48
+ if (used.has(id))
49
+ return;
50
+ used.add(id);
51
+ queue.push(JSON.stringify(schema[pool][name] ?? {}));
52
+ };
53
+ // A definition can also be named by its $anchor ("#amount") or its $id.
54
+ const named = (ref) => {
55
+ const [base, fragment] = ref.split('#');
56
+ for (const pool of pools) {
57
+ for (const [name, def] of Object.entries(schema[pool])) {
58
+ const d = (def ?? {});
59
+ const id = typeof d.$id === 'string' ? d.$id.replace(/#$/, '') : undefined;
60
+ if ((!base && fragment && d.$anchor === fragment) || (base && id && (id === base || id.endsWith(`/${base}`))))
61
+ use(pool, name);
62
+ }
63
+ }
64
+ };
46
65
  while (queue.length) {
47
- for (const m of queue.pop().matchAll(/"\$ref"\s*:\s*"#\/(\$defs|definitions)\/([^"/]+)/g)) {
48
- const id = `${m[1]}/${decodeURIComponent(m[2]).replace(/~1/g, '/').replace(/~0/g, '~')}`;
49
- if (used.has(id))
50
- continue;
51
- used.add(id);
52
- const [pool, name] = [m[1], id.slice(m[1].length + 1)];
53
- queue.push(JSON.stringify(schema[pool][name] ?? {}));
66
+ const text = queue.pop();
67
+ for (const m of text.matchAll(/"\$ref"\s*:\s*"#\/(\$defs|definitions)\/([^"/]+)/g)) {
68
+ use(m[1], decodeURIComponent(m[2]).replace(/~1/g, '/').replace(/~0/g, '~'));
54
69
  }
70
+ for (const m of text.matchAll(/"\$(?:dynamic)?[rR]ef"\s*:\s*"([^"]*)"/g))
71
+ if (!m[1].startsWith('#/'))
72
+ named(m[1]);
55
73
  }
56
74
  let unused = 0;
57
75
  for (const pool of pools) {
package/dist/catalog.js CHANGED
@@ -305,6 +305,10 @@ const FAILED_AS = {
305
305
  what: ['answered "not found"', 'answered "not found"'],
306
306
  fix: 'Check the server is set up for this account or site, then rerun.',
307
307
  },
308
+ client: {
309
+ what: ["asked the client for something toolmenu doesn't offer (roots or sampling)", "asked the client for something toolmenu doesn't offer (roots or sampling)"],
310
+ fix: "Nothing to fix in the server: toolmenu doesn't answer roots or sampling requests, so it can't list these routers' commands.",
311
+ },
308
312
  'invalid-arguments': {
309
313
  what: ["rejected the listing call's arguments", "rejected the listing call's arguments"],
310
314
  fix: "Read the router's own words above; if it lists its commands another way, name the right tool in catalog.tool or catalog.routers.",
package/dist/cli.js CHANGED
@@ -3,7 +3,7 @@ import { writeFile } from 'node:fs/promises';
3
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
+ import { ELICITATIONS, PROTOCOLS } from './connect.js';
7
7
  import { diffMenus } from './diff.js';
8
8
  import { loadMenu } from './menu.js';
9
9
  import { history, historyCsv } from './history.js';
@@ -79,6 +79,13 @@ export async function main(argv) {
79
79
  const protocol = (values.protocol ?? config.protocol ?? 'auto');
80
80
  if (!PROTOCOLS.includes(protocol))
81
81
  throw new UsageError(`--protocol must be auto, legacy or modern`);
82
+ const elicitation = (values.elicitation ?? 'decline');
83
+ if (!ELICITATIONS.includes(elicitation))
84
+ throw new UsageError('--elicitation must be decline or cancel');
85
+ if (values.elicitation !== undefined && sub !== 'session')
86
+ throw new UsageError('--elicitation goes with session: only session calls tools.');
87
+ // Only session calls tools, so only its target says how to answer their questions.
88
+ const answering = (t) => (elicitation === 'decline' ? t : { ...t, elicitation });
82
89
  const processes = values.processes !== undefined ? Number(values.processes) : config.processes ?? 2;
83
90
  if (!Number.isInteger(processes) || processes < 1)
84
91
  throw new UsageError('--processes must be a whole number, 1 or more');
@@ -203,7 +210,7 @@ export async function main(argv) {
203
210
  catch (error) {
204
211
  throw new UsageError(error instanceof Error ? error.message : String(error));
205
212
  }
206
- const autoTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
213
+ const autoTarget = answering(parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol));
207
214
  const waited = { ms: 0 };
208
215
  const menu = await probeMenu(seeded(autoTarget, MAIN_SEED), timeoutMs, undefined, waited).catch((error) => {
209
216
  throw refusedForTooMany(error, waited.ms);
@@ -278,7 +285,7 @@ export async function main(argv) {
278
285
  process.stdout.write(formatPlan(scenario, values.scenario) + '\n');
279
286
  return 0;
280
287
  }
281
- const sessionTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
288
+ const sessionTarget = answering(parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol));
282
289
  const result = await session(sessionTarget, scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: values.scenario, unionOut: !!values['union-out'] });
283
290
  if (values['union-out'])
284
291
  await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
package/dist/connect.d.ts CHANGED
@@ -1,14 +1,12 @@
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
4
  export type Protocol = 'auto' | 'legacy' | 'modern';
10
5
  export declare const PROTOCOLS: readonly Protocol[];
11
6
  export declare const MODERN_VERSION = "2026-07-28";
7
+ /** How toolmenu answers every elicitation: the user said no, or dismissed it. Never accept: that needs values, and an LLM or a person to pick them. */
8
+ export type Elicitation = 'decline' | 'cancel';
9
+ export declare const ELICITATIONS: readonly Elicitation[];
12
10
  export type Target = {
13
11
  kind: 'stdio';
14
12
  command: string;
@@ -16,12 +14,14 @@ export type Target = {
16
14
  env?: Record<string, string>;
17
15
  cwd?: string;
18
16
  protocol?: Protocol;
17
+ elicitation?: Elicitation;
19
18
  } | {
20
19
  kind: 'http';
21
20
  url: string;
22
21
  headers?: Record<string, string>;
23
22
  noAuth?: boolean;
24
23
  protocol?: Protocol;
24
+ elicitation?: Elicitation;
25
25
  };
26
26
  export interface WireResponse {
27
27
  method: string;
package/dist/connect.js CHANGED
@@ -5,8 +5,23 @@ import { explain, isCredentialHeader, Trace } from './explain.js';
5
5
  import { endSession } from './close.js';
6
6
  import { eraOf } from './menu.js';
7
7
  import { VERSION } from './version.js';
8
+ /**
9
+ * Which handshake to make. auto: try the 2026-07-28 `server/discover` first and fall back
10
+ * to the 2025 one. legacy: the 2025 handshake only. modern: 2026-07-28 only, an error if
11
+ * the server can't speak it.
12
+ */
13
+ // The SDK client drops a tool with an invalid x-mcp-header from its own tools/list
14
+ // and console.warns about it, once per list. toolmenu reads the list off the wire
15
+ // and reports those tools as spec/x-mcp-header findings, so the warning is noise.
16
+ const sdkWarn = console.warn.bind(console);
17
+ console.warn = (...args) => {
18
+ if (typeof args[0] === 'string' && args[0].startsWith('[mcp-sdk] excluding tool '))
19
+ return;
20
+ sdkWarn(...args);
21
+ };
8
22
  export const PROTOCOLS = ['auto', 'legacy', 'modern'];
9
23
  export const MODERN_VERSION = '2026-07-28';
24
+ export const ELICITATIONS = ['decline', 'cancel'];
10
25
  /** Every response the server sent, matched to the request method, as it came off the wire. */
11
26
  export class WireLog {
12
27
  responses = [];
@@ -50,7 +65,17 @@ export class WireLog {
50
65
  }
51
66
  }
52
67
  export async function connect(target, options = {}) {
53
- const client = new Client({ name: 'toolmenu', version: VERSION }, { versionNegotiation: { mode: target.protocol === 'legacy' ? 'legacy' : target.protocol === 'modern' ? { pin: MODERN_VERSION } : 'auto' } });
68
+ const client = new Client({ name: 'toolmenu', version: VERSION }, {
69
+ versionNegotiation: { mode: target.protocol === 'legacy' ? 'legacy' : target.protocol === 'modern' ? { pin: MODERN_VERSION } : 'auto' },
70
+ // Elicitation, form and URL mode, so a tool that asks the user something runs
71
+ // its "the user said no" path instead of failing (2026-07-28 multi round-trip
72
+ // requests). Every request is answered the same way, with no LLM: see ELICITATION.
73
+ // Not roots or sampling: 2026-07-28 deprecates them (SEP-2577).
74
+ capabilities: { elicitation: { form: {}, url: {} } },
75
+ });
76
+ // A 2025 server asks with an elicitation/create request; 2026-07-28 ones embed it
77
+ // in an input_required result, which session answers itself (mrtr.ts). Same answer.
78
+ client.setRequestHandler('elicitation/create', async () => ({ action: target.elicitation ?? 'decline' }));
54
79
  let transport;
55
80
  let stderrText = '';
56
81
  let oauth = false;
package/dist/diff.js CHANGED
@@ -21,6 +21,10 @@ export const DIFF_RULES = {
21
21
  'diff/param-dropped': { severity: 'info', class: 'notice' },
22
22
  'diff/schema-other': { severity: 'info', class: 'notice' },
23
23
  'diff/param-default': { severity: 'info', class: 'notice' },
24
+ // x-mcp-header (2026-07-28): a parameter mirrored into an Mcp-Param-* HTTP header,
25
+ // added, removed or renamed. Callers don't change; proxies and WAFs routing on the
26
+ // header do.
27
+ 'diff/x-mcp-header': { severity: 'info', class: 'notice' },
24
28
  // Restructured ($ref, $defs) but accepts the same input: bytes and tokens changed.
25
29
  'diff/schema-equivalent': { severity: 'info', class: 'notice' },
26
30
  // Only the declared $schema dialect changed: one finding for the menu.
@@ -813,9 +817,25 @@ function compareSchema(w, at, before, after, depth) {
813
817
  fix: 'If the default is built from the clock or the environment, give a fixed one or none, and say in the description what an absent value means.',
814
818
  });
815
819
  }
820
+ // A header the parameter is mirrored into: who routes on it changes, not the call.
821
+ const [ha, hb] = [before['x-mcp-header'], after['x-mcp-header']];
822
+ if (canonical(ha) !== canonical(hb)) {
823
+ const header = (v) => `Mcp-Param-${String(v)}`;
824
+ const [head, tail] = ha === undefined
825
+ ? [`: now mirrored into the ${header(hb)} HTTP header`, 'Proxies, load balancers and WAFs can route on it from this release.']
826
+ : hb === undefined
827
+ ? [`: no longer mirrored into the ${header(ha)} HTTP header`, 'Anything that routes on that header stops seeing it.']
828
+ : [`: its HTTP header was renamed, ${header(ha)} → ${header(hb)}`, 'Routing rules that match the old header stop matching.'];
829
+ say(w, 'diff/x-mcp-header', at, head, tail, [before, after], {
830
+ ...(ha === undefined
831
+ ? {}
832
+ : { fix: hb === undefined ? `If a proxy, load balancer or WAF rule matches ${header(ha)}, change it before this release ships.` : `Update proxy, load balancer and WAF rules from ${header(ha)} to ${header(hb)} when this release ships.` }),
833
+ });
834
+ }
816
835
  const rest = (s) => {
817
836
  const r = residual(s, { object, items: arrays, union });
818
837
  delete r.default;
838
+ delete r['x-mcp-header'];
819
839
  return r;
820
840
  };
821
841
  if ((union || oldType === newType || accepts(after, before)) && canonical(rest(before)) !== canonical(rest(after))) {
package/dist/explain.d.ts CHANGED
@@ -32,6 +32,8 @@ export declare class Trace {
32
32
  /** stdout lines that aren't JSON-RPC: the first few, and how many in all. */
33
33
  readonly stray: string[];
34
34
  strayCount: number;
35
+ /** The first stray stdout lines, more of them than are shown: a CLI's usage runs long. */
36
+ readonly strayHead: string[];
35
37
  private stdoutPartial;
36
38
  /** The last stderr lines, and how many there were in all. */
37
39
  readonly stderrTail: string[];
@@ -78,6 +80,12 @@ export declare function seconds(ms: number): string;
78
80
  export declare function commandLine(command: string, args: string[]): string;
79
81
  /** The stderr fact: the last lines, and a note of how many came before. */
80
82
  export declare function stderrFact(trace: Trace): [string, string];
83
+ /**
84
+ * What the server's own output says about how it was started, as a next step: a
85
+ * CLI that printed its usage and wants a subcommand, or a server that opened an
86
+ * HTTP port instead of talking on stdio. Undefined when it says neither.
87
+ */
88
+ export declare function startupHint(trace: Trace, command: string): string | undefined;
81
89
  /** A request header that carries credentials: Authorization, a cookie, or a name with key, token, secret or auth in it (x-mcp-api-key). */
82
90
  export declare function isCredentialHeader(name: string): boolean;
83
91
  /**
package/dist/explain.js CHANGED
@@ -21,6 +21,8 @@ export class Trace {
21
21
  /** stdout lines that aren't JSON-RPC: the first few, and how many in all. */
22
22
  stray = [];
23
23
  strayCount = 0;
24
+ /** The first stray stdout lines, more of them than are shown: a CLI's usage runs long. */
25
+ strayHead = [];
24
26
  stdoutPartial = '';
25
27
  /** The last stderr lines, and how many there were in all. */
26
28
  stderrTail = [];
@@ -48,6 +50,8 @@ export class Trace {
48
50
  this.strayCount++;
49
51
  if (this.stray.length < 2)
50
52
  this.stray.push(clean(line, 160));
53
+ if (this.strayHead.length < 60)
54
+ this.strayHead.push(clean(line, 240));
51
55
  }
52
56
  }
53
57
  stderr(chunk) {
@@ -144,6 +148,39 @@ function strayFact(trace) {
144
148
  return ['stdout', `${quoted}${more}`];
145
149
  }
146
150
  const LOG_TO_STDERR = 'Log to stderr; stdout carries the protocol (in Node, console.error rather than console.log; in Python, logging or print(..., file=sys.stderr)).';
151
+ // A CLI's usage: argparse, click, yargs, commander, System.CommandLine, stricli.
152
+ const USAGE = /(?:^|\n)\s*(?:usage|(?:sub)?commands|options|examples|flags):|\bUSAGE\b|\s<command>|\[command\]|\bCOMMAND \[ARGS\]|arguments are required|subcommands? must be present|no command (?:specified|given)|required command was not provided|\b(?:run|see):? \S+ --help\b/i;
153
+ // A table of commands or options, two or more rows: " t3-watch start Run the service",
154
+ // " --version Show version number". Help output, even without a "Usage:" line.
155
+ const HELP_ROWS = /(?:^|\n)\s*(?:[\w.-]+ [\w-]+|-{1,2}[\w-]+(?:, -{1,2}[\w-]+)?) {2,}\S[^\n]*\n\s*(?:[\w.-]+ [\w-]+|-{1,2}[\w-]+(?:, -{1,2}[\w-]+)?) {2,}\S/;
156
+ // The subcommands that usually start the MCP server, most specific first. A word
157
+ // on its own ({mcp}, " mcp Start…", "mcp start [--transport…]"), not part of a
158
+ // name like agentation-mcp.
159
+ const SUBCOMMANDS = ['mcp start', 'mcp serve', 'server start', 'mcp', 'stdio', 'serve', 'server', 'start'];
160
+ // An HTTP server's address in its log: "MCP server listening on http://localhost:3001/mcp",
161
+ // "StreamableHTTP endpoint available at http://127.0.0.1:3333/mcp".
162
+ const HTTP_URL = /\b(?:listening|available|running|serving|started)\b[^\n]{0,60}?(https?:\/\/[^\s"'<>]+)/i;
163
+ const HTTP_PORT = /\blistening on (?:port )?:?(\d{2,5})\b/i;
164
+ /**
165
+ * What the server's own output says about how it was started, as a next step: a
166
+ * CLI that printed its usage and wants a subcommand, or a server that opened an
167
+ * HTTP port instead of talking on stdio. Undefined when it says neither.
168
+ */
169
+ export function startupHint(trace, command) {
170
+ const text = [...trace.strayHead, ...trace.stderrExcerpt().lines].join('\n');
171
+ const url = HTTP_URL.exec(text)?.[1]?.replace(/[.,;)]+$/, '').replace('//0.0.0.0', '//localhost');
172
+ const port = url ? undefined : HTTP_PORT.exec(text)?.[1];
173
+ if (url || port) {
174
+ const flag = /--stdio\b/.test(text) ? '--stdio' : /--transport[ =]?(?:\[?stdio|<)/i.test(text) ? '--transport stdio' : undefined;
175
+ const where = url ?? `http://localhost:${port}/mcp`;
176
+ return `The server started an HTTP server (${where}) instead of talking on its stdin and stdout. Start it in stdio mode (${flag ? `its output mentions ${flag}` : 'often --stdio or --transport stdio'}), or run toolmenu against the address while the server runs: toolmenu snapshot ${where}`;
177
+ }
178
+ if (USAGE.test(text) || HELP_ROWS.test(text)) {
179
+ const sub = SUBCOMMANDS.find((c) => new RegExp(`(?:^|[\\s{,|\\[])${c.replace(' ', '\\s+')}(?=[\\s},|\\]]|$)`, 'm').test(text));
180
+ return `The command printed its usage and exited: it wants a subcommand or an argument it wasn't given. ${sub ? `Its usage lists “${sub}”: try ${command} ${sub}` : 'Its usage (above) or its docs say what starts the MCP server: add that after the command.'}`;
181
+ }
182
+ return undefined;
183
+ }
147
184
  /** The error codes along an error's cause chain, innermost last. */
148
185
  function causes(error) {
149
186
  const out = [];
@@ -286,12 +323,16 @@ function explainStdio(error, trace, context, target) {
286
323
  const stderrText = trace.stderrExcerpt().lines.join('\n');
287
324
  const rejected = rejectedCredentials(stderrText);
288
325
  let next;
326
+ let hint;
289
327
  if (/cannot find (module|package)|ERR_MODULE_NOT_FOUND|ModuleNotFoundError|No module named/i.test(stderrText)) {
290
328
  next = "The server is missing one of its own dependencies (see stderr): reinstall it, or try another version. It's a packaging problem, not your setup.";
291
329
  }
292
330
  else if (rejected) {
293
331
  next = REJECTED_NEXT;
294
332
  }
333
+ else if ((hint = startupHint(trace, command))) {
334
+ next = hint;
335
+ }
295
336
  else if (trace.strayCount) {
296
337
  next = `${LOG_TO_STDERR} Then fix what stderr says.`;
297
338
  }
@@ -329,13 +370,16 @@ function explainStdio(error, trace, context, target) {
329
370
  : rejected
330
371
  ? `${stage} timed out after ${seconds(waitedHere)}: the server is running but never answered; its stderr looks like rejected credentials (“${rejected}”).`
331
372
  : `${stage} timed out after ${seconds(waitedHere)}: the server is running but never answered.`;
332
- const next = trace.strayCount
333
- ? LOG_TO_STDERR
334
- : rejected
335
- ? REJECTED_NEXT
336
- : stage === 'tools/list'
337
- ? 'The server answered initialize, then hung on tools/list: check its logs (stderr above). If building the list is just slow, raise --timeout.'
338
- : 'Check the command starts an MCP server on stdio (some need an argument such as "stdio" or "--stdio"). If it is only slow to start (npx downloading, a first build), raise --timeout.';
373
+ const hint = startupHint(trace, command);
374
+ const next = hint
375
+ ? hint
376
+ : trace.strayCount
377
+ ? LOG_TO_STDERR
378
+ : rejected
379
+ ? REJECTED_NEXT
380
+ : stage === 'tools/list'
381
+ ? 'The server answered initialize, then hung on tools/list: check its logs (stderr above). If building the list is just slow, raise --timeout.'
382
+ : 'Check the command starts an MCP server on stdio (some need an argument such as "stdio" or "--stdio"). If it is only slow to start (npx downloading, a first build), raise --timeout.';
339
383
  return new ConnectError(headline, facts, next, stage, { cause: error });
340
384
  }
341
385
  // Anything else: the transport's words, with what the server said.
@@ -1,4 +1,4 @@
1
- export type FailureClass = 'auth' | 'environment' | 'network' | 'not-found' | 'invalid-arguments' | 'other';
1
+ export type FailureClass = 'auth' | 'environment' | 'network' | 'not-found' | 'client' | 'invalid-arguments' | 'other';
2
2
  /** Failures of the setup (credentials, this machine, the network), not of the server. */
3
3
  export declare const SETUP_FAILURES: Set<FailureClass>;
4
4
  /**
package/dist/failures.js CHANGED
@@ -5,16 +5,23 @@
5
5
  * as a finding.
6
6
  */
7
7
  /** Failures of the setup (credentials, this machine, the network), not of the server. */
8
- export const SETUP_FAILURES = new Set(['auth', 'environment', 'network', 'not-found']);
8
+ export const SETUP_FAILURES = new Set(['auth', 'environment', 'network', 'not-found', 'client']);
9
+ // A tool that asks the client for something toolmenu doesn't offer: "Cannot request
10
+ // input 'roots' (roots/list): the request's client capabilities do not declare the
11
+ // required capability" (server-everything's get-roots-list), sampling, elicitation.
12
+ const CLIENT = /client capabilit(?:y|ies)\b[^.]{0,60}\b(?:do(?:es)? not|don't|doesn't|lack|missing|without)\b|\b(?:roots|sampling|elicitation)\b[^.]{0,40}\bnot (?:supported|declared|available)\b[^.]{0,20}\bclient\b|client does not support (?:roots|sampling|elicitation)/i;
9
13
  // Something this machine lacks: "Could not find Google Chrome executable"
10
- // (Chrome DevTools), "Chromium distribution 'chrome' is not found at" (Playwright).
11
- const ENVIRONMENT = /could not find [^.]{0,40}executable|is not found at \/|\bnot installed\b|command not found|cannot find (module|package)|\bENOENT\b/i;
14
+ // (Chrome DevTools), "Chromium distribution 'chrome' is not found at" (Playwright),
15
+ // or the wrong operating system: "Editmamei runs on Windows and macOS; this process
16
+ // is on "linux"" (editmamei), "Unsupported platform: linux".
17
+ const ENVIRONMENT = /could not find [^.]{0,40}executable|is not found at \/|\bnot installed\b|command not found|cannot find (module|package)|\bENOENT\b|\bruns on [^.;]{0,40}; this (?:process|machine|system) is on\b|\b(?:unsupported|not supported on (?:this|the current)) (?:platform|operating system|OS)\b/i;
12
18
  // "401 Bad credentials" (GitHub), "Authorization Expired" (Sentry), "Invalid
13
19
  // token" (Firecrawl), "authentication token is not valid" (Apify), "Please provide
14
20
  // a valid access token" (Supabase), "NetlifyUnauthError: You're not logged into
15
- // Netlify" (Netlify), "The API key you provided was rejected" (Pinecone). Not a
16
- // bare "token": plenty of errors mention one.
17
- const AUTH = /\b(401|403)\b|unauthori[sz]ed|unauth(enticated|error)|forbidden|bad credentials|authori[sz]ation expired|re-?authori[sz]e|not authenticated|not logged (?:in|into)\b(?! to the browser)|authentication (token|failed|required|error)|(invalid|expired|revoked) (api[ _-]?key|access token|token|credentials)|(token|api[ _-]?key|credentials) (is |are )?(not valid|invalid|expired)|(api[ _-]?key|access token|credentials)\b[^.]{0,30}\b(was|were|is|are) (rejected|refused|revoked)|valid (access )?token/i;
21
+ // Netlify" (Netlify), "The API key you provided was rejected" (Pinecone), "Admin
22
+ // auth is missing", "Runtime credentials are missing" (securenow). Not a bare
23
+ // "token": plenty of errors mention one.
24
+ const AUTH = /\b(?:auth|authentication|credentials?|api[ _-]?key|access token)\b (?:is |are )?missing\b|\b(401|403)\b|unauthori[sz]ed|unauth(enticated|error)|forbidden|bad credentials|authori[sz]ation expired|re-?authori[sz]e|not authenticated|not logged (?:in|into)\b(?! to the browser)|authentication (token|failed|required|error)|(invalid|expired|revoked) (api[ _-]?key|access token|token|credentials)|(token|api[ _-]?key|credentials) (is |are )?(not valid|invalid|expired)|(api[ _-]?key|access token|credentials)\b[^.]{0,30}\b(was|were|is|are) (rejected|refused|revoked)|valid (access )?token/i;
18
25
  const NETWORK = /\b(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ECONNRESET|EHOSTUNREACH)\b|socket hang up|getaddrinfo|network error/i;
19
26
  // "Either 'page_id' OR both 'title' and 'space_key' must be provided" (Atlassian),
20
27
  // "**Input Error**" (Sentry), JSON-RPC's invalid params.
@@ -151,6 +158,9 @@ export async function patiently(request, options = {}) {
151
158
  * with 404; a made-up Jira URL 404s), which is setup, not the server's fault.
152
159
  */
153
160
  export function classifyFailure(text, options = {}) {
161
+ // 2026-07-28's MissingRequiredClientCapabilityError, by its code.
162
+ if (options.code === -32021 || CLIENT.test(text))
163
+ return 'client';
154
164
  if (ENVIRONMENT.test(text))
155
165
  return 'environment';
156
166
  if (AUTH.test(text))
@@ -168,6 +178,7 @@ export const FAILURE_LABELS = {
168
178
  environment: 'something missing on this machine',
169
179
  network: 'the network',
170
180
  'not-found': 'a 404 on a call that named nothing (usually the account or site behind the credentials)',
181
+ client: "a client feature toolmenu doesn't offer (roots or sampling)",
171
182
  'invalid-arguments': 'the arguments',
172
183
  other: 'other errors',
173
184
  };
@@ -184,6 +195,8 @@ export function setupFailureAdvice(classes, transport) {
184
195
  steps.push(`If the errors are about credentials, rerun with real ones (${credentials}); a test account is enough.`);
185
196
  if (set.has('environment'))
186
197
  steps.push('If something is missing on this machine (a browser, a binary, a module), install it where the server runs, or run the server in its own container image.');
198
+ if (set.has('client'))
199
+ steps.push("If a tool needs roots or sampling from the client, toolmenu doesn't provide them (2026-07-28 deprecates both): those calls only checked that the menu stays put, and the server isn't at fault.");
187
200
  if (set.has('network'))
188
201
  steps.push('If the server calls an upstream API, check this machine can reach it (DNS, proxy, firewall).');
189
202
  return { fix: steps.join(' ') || 'Check the quoted errors: they came from before the tool ran.', confidence: 'unsure' };
package/dist/help.js CHANGED
@@ -34,6 +34,7 @@ const OPTIONS = {
34
34
  'values-file': ['--values-file <path>', ['with --auto, the same as a YAML/JSON map']],
35
35
  'assume-read-only': ['--assume-read-only <tools>', ["with --auto, call these tools although the server doesn't", 'mark them readOnlyHint (exact names, comma-separated; tools', 'marked or named as writes are still never called)']],
36
36
  'save-scenario': ['--save-scenario <path>', ['with --auto, write the plan made before the run as a scenario file', '(calls planned later for tools an unlock brings are not in it)']],
37
+ elicitation: ['--elicitation <decline|cancel>', ['how to answer a tool that asks the user something mid-call (2026-07-28):', 'decline (default) or cancel, the same every time']],
37
38
  'union-out': ['--union-out <path>', ['write every tool the session saw as a menu file, to commit as the', 'baseline for diff (tools behind unlocks included)']],
38
39
  versions: ['--versions <n|all>', ['how many of the most recent versions to inspect (default: 10), or all']],
39
40
  'include-prereleases': ['--include-prereleases', ['include versions like 1.2.0-beta.1']],
@@ -106,7 +107,7 @@ const HELP = {
106
107
  'prompt cache, a different menu in a fresh process.',
107
108
  SERVER_NOTE,
108
109
  ],
109
- own: ['scenario', 'auto', 'init', 'plan', 'value', 'values-file', 'assume-read-only', 'open-world', 'max-calls', 'max-calls-per-unlock', 'save-scenario', 'union-out'],
110
+ own: ['scenario', 'auto', 'init', 'plan', 'value', 'values-file', 'assume-read-only', 'open-world', 'max-calls', 'max-calls-per-unlock', 'save-scenario', 'union-out', 'elicitation'],
110
111
  shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
111
112
  examples: [
112
113
  'toolmenu session --auto -- node dist/index.js',
package/dist/mrtr.d.ts ADDED
@@ -0,0 +1,41 @@
1
+ import type { Connection, Elicitation } from './connect.js';
2
+ /** Rounds answered before toolmenu stops: a tool still asking after this is stuck. */
3
+ export declare const MAX_ROUNDS = 3;
4
+ export type InputKind = 'form' | 'url' | 'roots' | 'sampling' | 'other';
5
+ export interface InputTrace {
6
+ /** input_required results answered. */
7
+ rounds: number;
8
+ /** What the tool asked for, in the order first asked. */
9
+ kinds: InputKind[];
10
+ /**
11
+ * none: it asked for nothing. completed: it answered after the decline(s).
12
+ * loop: it asked the same again after a decline, until the round limit.
13
+ * gave-up: still asking (different things) at the round limit.
14
+ * undeclared: it asked for something the request didn't declare (roots, sampling).
15
+ * decline-failed: the retry carrying the decline failed with a protocol error.
16
+ */
17
+ outcome: 'none' | 'completed' | 'loop' | 'gave-up' | 'undeclared' | 'decline-failed';
18
+ /** Kinds asked for that the request didn't declare. */
19
+ undeclared?: InputKind[];
20
+ /** The protocol error a retry failed with (decline-failed). */
21
+ error?: unknown;
22
+ /** A raw result on the wire without resultType, which 2026-07-28 servers MUST send. */
23
+ missingResultType?: boolean;
24
+ }
25
+ type CallResult = Awaited<ReturnType<Connection['client']['callTool']>>;
26
+ /**
27
+ * Call a tool, answering any input it asks for. On a 2025-era connection it's a
28
+ * plain call (the SDK client's elicitation handler answers there). `result` is
29
+ * undefined when the tool never completed (loop, gave-up, undeclared, decline-failed).
30
+ */
31
+ export declare function callWithInput(conn: Connection, params: {
32
+ name: string;
33
+ arguments: Record<string, unknown>;
34
+ }, options: {
35
+ timeoutMs?: number;
36
+ elicitation?: Elicitation;
37
+ }): Promise<{
38
+ result?: CallResult;
39
+ input: InputTrace;
40
+ }>;
41
+ export {};
package/dist/mrtr.js ADDED
@@ -0,0 +1,95 @@
1
+ /** Rounds answered before toolmenu stops: a tool still asking after this is stuck. */
2
+ export const MAX_ROUNDS = 3;
3
+ const DECLARED = new Set(['form', 'url']);
4
+ function kindOf(request) {
5
+ if (request.method === 'elicitation/create')
6
+ return request.params?.mode === 'url' ? 'url' : 'form';
7
+ if (request.method === 'roots/list')
8
+ return 'roots';
9
+ if (request.method === 'sampling/createMessage')
10
+ return 'sampling';
11
+ return 'other';
12
+ }
13
+ /** Keys sorted at every level: the same request asked twice reads the same. */
14
+ function canonical(value) {
15
+ if (Array.isArray(value))
16
+ return `[${value.map(canonical).join(',')}]`;
17
+ if (value && typeof value === 'object') {
18
+ return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
19
+ }
20
+ return JSON.stringify(value);
21
+ }
22
+ /**
23
+ * Call a tool, answering any input it asks for. On a 2025-era connection it's a
24
+ * plain call (the SDK client's elicitation handler answers there). `result` is
25
+ * undefined when the tool never completed (loop, gave-up, undeclared, decline-failed).
26
+ */
27
+ export async function callWithInput(conn, params, options) {
28
+ if (conn.era !== 'modern')
29
+ return { result: await conn.client.callTool(params, { timeout: options.timeoutMs }), input: { rounds: 0, kinds: [], outcome: 'none' } };
30
+ const action = options.elicitation ?? 'decline';
31
+ const kinds = [];
32
+ let missingResultType = false;
33
+ let previous;
34
+ let repeated = false;
35
+ let rounds = 0;
36
+ let call = { ...params };
37
+ const trace = (outcome, more = {}) => ({
38
+ rounds,
39
+ kinds,
40
+ outcome,
41
+ ...(missingResultType ? { missingResultType } : {}),
42
+ ...more,
43
+ });
44
+ for (;;) {
45
+ const mark = conn.wire.responses.length;
46
+ let result;
47
+ try {
48
+ result = (await conn.client.callTool(call, { timeout: options.timeoutMs, allowInputRequired: true }));
49
+ }
50
+ catch (error) {
51
+ // A result without resultType: the SDK client rejects it ("missing required
52
+ // resultType"). The server did answer, so the step did too; the finding says why
53
+ // clients won't take it.
54
+ const answered = conn.wire.since(mark, 'tools/call').at(-1)?.result;
55
+ if (answered && !('resultType' in answered)) {
56
+ missingResultType = true;
57
+ return { result: answered, input: trace(rounds ? 'completed' : 'none') };
58
+ }
59
+ // The first call failing is an ordinary failed step; a retry that carried a
60
+ // decline failing is the server's answer to the decline.
61
+ if (rounds === 0)
62
+ throw error;
63
+ return { input: trace('decline-failed', { error }) };
64
+ }
65
+ const raw = conn.wire.since(mark, 'tools/call').at(-1)?.result;
66
+ if (raw && !('resultType' in raw))
67
+ missingResultType = true;
68
+ if (result.resultType !== 'input_required') {
69
+ return { result: result, input: trace(rounds ? 'completed' : 'none') };
70
+ }
71
+ const asked = result.inputRequests ?? {};
72
+ for (const request of Object.values(asked)) {
73
+ const k = kindOf(request);
74
+ if (!kinds.includes(k))
75
+ kinds.push(k);
76
+ }
77
+ const undeclared = [...new Set(Object.values(asked).map(kindOf).filter((k) => !DECLARED.has(k)))];
78
+ if (undeclared.length)
79
+ return { input: trace('undeclared', { undeclared }) };
80
+ // The same requests again after a decline: the tool didn't take the answer.
81
+ const signature = canonical(asked);
82
+ if (previous !== undefined && signature === previous && Object.keys(asked).length)
83
+ repeated = true;
84
+ if (rounds >= MAX_ROUNDS)
85
+ return { input: trace(repeated ? 'loop' : 'gave-up') };
86
+ previous = signature;
87
+ rounds++;
88
+ const state = result.requestState;
89
+ call = {
90
+ ...params,
91
+ inputResponses: Object.fromEntries(Object.keys(asked).map((key) => [key, { action }])),
92
+ ...(state !== undefined ? { requestState: state } : {}),
93
+ };
94
+ }
95
+ }
package/dist/options.d.ts CHANGED
@@ -34,6 +34,9 @@ export declare const CLI_OPTIONS: {
34
34
  readonly protocol: {
35
35
  readonly type: 'string';
36
36
  };
37
+ readonly elicitation: {
38
+ readonly type: 'string';
39
+ };
37
40
  readonly 'no-auth': {
38
41
  readonly type: 'boolean';
39
42
  };
package/dist/options.js CHANGED
@@ -14,6 +14,7 @@ export const CLI_OPTIONS = {
14
14
  env: { type: 'string', multiple: true },
15
15
  timeout: { type: 'string' },
16
16
  protocol: { type: 'string' },
17
+ elicitation: { type: 'string' },
17
18
  'no-auth': { type: 'boolean' },
18
19
  port: { type: 'string' },
19
20
  scope: { type: 'string' },
@@ -17,7 +17,10 @@ export const gated = {
17
17
  // Only an unlock whose parameter lists what it unlocks (an enum of toolsets or
18
18
  // domains), the kind session --auto walks: "Enables Cross-Region Restore on a
19
19
  // vault" turns on a feature, not tools (Azure, 418 tools).
20
- const found = unlockers(ctx.menu.tools).filter((u) => u.param && u.values.length);
20
+ // And only one whose name or description says it unlocks tools: an enum of
21
+ // domains alone is as often data (Garmin's garmin_sync { domains: [sleep, hrv] }
22
+ // downloads them). session --auto still tries such a tool once.
23
+ const found = unlockers(ctx.menu.tools).filter((u) => u.param && u.values.length && u.claims);
21
24
  if (!found.length)
22
25
  return [];
23
26
  // A value whose tools are already listed adds nothing: the same server started
@@ -0,0 +1,14 @@
1
+ import type { MenuTool } from '../types.js';
2
+ import { type Rule } from './rule.js';
3
+ export interface HeaderFault {
4
+ /** Where the annotation sits: `region`, `filter.region`, `<items>.id`. */
5
+ path: string;
6
+ /** The annotation's value, as written. */
7
+ header: unknown;
8
+ problem: string;
9
+ /** The SDK client drops the tool for this (true), or only the spec forbids it (false: `number`). */
10
+ dropped: boolean;
11
+ }
12
+ /** Every broken x-mcp-header annotation in a tool's input schema; empty when all are valid or there are none. */
13
+ export declare function headerFaults(tool: MenuTool): HeaderFault[];
14
+ export declare const xMcpHeader: Rule;