toolmenu 0.15.0 → 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.15, 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.15.0
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
@@ -306,8 +306,8 @@ const FAILED_AS = {
306
306
  fix: 'Check the server is set up for this account or site, then rerun.',
307
307
  },
308
308
  client: {
309
- what: ["asked the client for something toolmenu doesn't offer (roots, sampling or elicitation)", "asked the client for something toolmenu doesn't offer (roots, sampling or elicitation)"],
310
- fix: "Nothing to fix in the server: toolmenu doesn't answer roots, sampling or elicitation requests, so it can't list these routers' commands.",
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
311
  },
312
312
  'invalid-arguments': {
313
313
  what: ["rejected the listing call's arguments", "rejected the listing call's arguments"],
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/failures.js CHANGED
@@ -158,7 +158,8 @@ export async function patiently(request, options = {}) {
158
158
  * with 404; a made-up Jira URL 404s), which is setup, not the server's fault.
159
159
  */
160
160
  export function classifyFailure(text, options = {}) {
161
- if (CLIENT.test(text))
161
+ // 2026-07-28's MissingRequiredClientCapabilityError, by its code.
162
+ if (options.code === -32021 || CLIENT.test(text))
162
163
  return 'client';
163
164
  if (ENVIRONMENT.test(text))
164
165
  return 'environment';
@@ -177,7 +178,7 @@ export const FAILURE_LABELS = {
177
178
  environment: 'something missing on this machine',
178
179
  network: 'the network',
179
180
  'not-found': 'a 404 on a call that named nothing (usually the account or site behind the credentials)',
180
- client: "a client feature toolmenu doesn't offer (roots, sampling or elicitation)",
181
+ client: "a client feature toolmenu doesn't offer (roots or sampling)",
181
182
  'invalid-arguments': 'the arguments',
182
183
  other: 'other errors',
183
184
  };
@@ -195,7 +196,7 @@ export function setupFailureAdvice(classes, transport) {
195
196
  if (set.has('environment'))
196
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.');
197
198
  if (set.has('client'))
198
- steps.push("If a tool asks the client for roots, sampling or elicitation, toolmenu doesn't provide them: those calls only checked that the menu stays put, and the server isn't at fault.");
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.");
199
200
  if (set.has('network'))
200
201
  steps.push('If the server calls an upstream API, check this machine can reach it (DNS, proxy, firewall).');
201
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' },
@@ -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;
@@ -0,0 +1,116 @@
1
+ import { count, names } from './rule.js';
2
+ /*
3
+ * x-mcp-header (2026-07-28, SEP-2243): a tool parameter mirrored into an
4
+ * `Mcp-Param-{name}` HTTP header. "Clients using the Streamable HTTP transport
5
+ * MUST reject tool definitions where any x-mcp-header value violates these
6
+ * constraints ... the client MUST exclude the invalid tool from the result of
7
+ * tools/list" (server/tools.mdx). So a bad annotation hides the tool, and the
8
+ * server never hears about it: the official SDK client only logs a warning.
9
+ *
10
+ * The checks follow the spec and the SDK client's own scan
11
+ * (scanXMcpHeaderDeclarations in @modelcontextprotocol/client), which decides
12
+ * what SDK-based clients actually drop. Where the two differ (`number`: the spec
13
+ * forbids it, the SDK accepts it), the finding says so.
14
+ */
15
+ const KEY = 'x-mcp-header';
16
+ // RFC 9110 §5.1 token: 1*tchar. No spaces, control characters or delimiters.
17
+ const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
18
+ const PRIMITIVE = new Set(['string', 'integer', 'boolean']);
19
+ // Keywords a header's chain of `properties` keys must not pass through.
20
+ const UNREACHABLE = [
21
+ 'items', 'prefixItems', 'contains', 'additionalProperties', 'unevaluatedProperties', 'unevaluatedItems',
22
+ 'propertyNames', 'patternProperties', 'dependentSchemas', 'oneOf', 'anyOf', 'allOf', 'not', 'if', 'then', 'else',
23
+ '$defs', 'definitions',
24
+ ];
25
+ const NAMED = new Set(['patternProperties', 'dependentSchemas', '$defs', 'definitions']);
26
+ /** Every broken x-mcp-header annotation in a tool's input schema; empty when all are valid or there are none. */
27
+ export function headerFaults(tool) {
28
+ const faults = [];
29
+ const seen = new Map();
30
+ const visit = (node, path, reachable) => {
31
+ if (!node || typeof node !== 'object' || Array.isArray(node))
32
+ return;
33
+ const schema = node;
34
+ const where = path.length ? path.join('.') : 'the schema root';
35
+ if (KEY in schema) {
36
+ const raw = schema[KEY];
37
+ const fault = (problem, dropped = true) => faults.push({ path: where, header: raw, problem, dropped });
38
+ if (!reachable || path.length === 0) {
39
+ fault(path.length === 0
40
+ ? 'it sits on the schema root, not on a parameter'
41
+ : `it sits under ${path.find((p) => p.startsWith('<'))?.slice(1, -1) ?? 'a keyword'}; it's only allowed on a parameter reached through "properties" alone (not items, additionalProperties, oneOf/anyOf/allOf/not, if/then/else or $defs)`);
42
+ }
43
+ else if (typeof raw !== 'string' || raw.length === 0) {
44
+ fault('the header name must be a non-empty string');
45
+ }
46
+ else if (!TOKEN.test(raw)) {
47
+ fault(`"${raw}" isn't a valid HTTP header name (RFC 9110 token: no spaces, control characters or delimiters such as ( ) / : ; = ? @ [ ] { } " ,)`);
48
+ }
49
+ else {
50
+ const type = schema.type;
51
+ if (typeof type !== 'string') {
52
+ fault(type === undefined ? 'the parameter has no "type"; it must be string, integer or boolean' : `the parameter's type is ${JSON.stringify(type)}; it must be one of string, integer or boolean, not a list`);
53
+ }
54
+ else if (type === 'number') {
55
+ fault('the parameter is a number; the spec allows only string, integer or boolean (the official SDK client accepts number for now, other clients may not)', false);
56
+ }
57
+ else if (!PRIMITIVE.has(type)) {
58
+ fault(`the parameter is ${type === 'array' || type === 'object' ? 'an' : 'a'} ${type}; it must be string, integer or boolean`);
59
+ }
60
+ else {
61
+ const prior = seen.get(raw.toLowerCase());
62
+ if (prior !== undefined)
63
+ fault(`"${raw}" is already used by ${prior}; header names must differ ignoring case`);
64
+ else
65
+ seen.set(raw.toLowerCase(), `${where} ("${raw}")`);
66
+ }
67
+ }
68
+ }
69
+ const props = schema.properties;
70
+ if (props && typeof props === 'object' && !Array.isArray(props)) {
71
+ for (const [key, child] of Object.entries(props))
72
+ visit(child, [...path, key], reachable);
73
+ }
74
+ for (const k of UNREACHABLE) {
75
+ const sub = schema[k];
76
+ if (sub === undefined)
77
+ continue;
78
+ const branches = Array.isArray(sub) ? sub : sub && typeof sub === 'object' && NAMED.has(k) ? Object.values(sub) : [sub];
79
+ for (const b of branches)
80
+ visit(b, [...path, `<${k}>`], false);
81
+ }
82
+ };
83
+ visit(tool.inputSchema, [], true);
84
+ return faults;
85
+ }
86
+ export const xMcpHeader = {
87
+ id: 'spec/x-mcp-header',
88
+ severity: 'error',
89
+ since: '2026-07-28',
90
+ summary: 'x-mcp-header annotations are valid, so HTTP clients keep the tool',
91
+ run(ctx) {
92
+ const findings = [];
93
+ const http = ctx.transport === 'http';
94
+ for (const tool of ctx.menu.tools) {
95
+ const faults = headerFaults(tool);
96
+ if (!faults.length)
97
+ continue;
98
+ const dropped = faults.some((f) => f.dropped);
99
+ const where = faults.map((f) => f.path);
100
+ findings.push({
101
+ tool: tool.name,
102
+ // Over HTTP the tool is gone for every compliant client. On stdio clients may
103
+ // ignore the annotation, but the same server is often deployed over HTTP too.
104
+ severity: dropped ? (http ? 'error' : 'warn') : 'warn',
105
+ message: dropped
106
+ ? `${tool.name} has ${faults.length === 1 ? 'an x-mcp-header annotation' : `${count(faults.length, 'x-mcp-header annotation')}`} the spec doesn't allow (on ${names(where, 4)}), and Streamable HTTP clients must then leave the whole tool out of their menu. The official SDK client does, with only a console warning, so the agent never sees ${tool.name} and nothing tells the server.${http ? ' toolmenu reads the list off the wire, which is why it is in this menu.' : ' Over stdio clients may ignore the annotation, so it shows here; served over HTTP, it would be gone.'}`
107
+ : `${tool.name} mirrors a number parameter into a header (${names(where, 4)}). The spec allows only string, integer or boolean there, so a strict Streamable HTTP client must leave the tool out of its menu; the official SDK client keeps it for now (its conformance tests expect number to work, a gap tracked upstream).`,
108
+ detail: faults.map((f) => `${f.path}${typeof f.header === 'string' && f.header ? ` (x-mcp-header: "${f.header}")` : ''}: ${f.problem}`),
109
+ fix: dropped
110
+ ? `Fix each annotation listed: on a string, integer or boolean parameter reached through "properties" alone, with a header name of letters, digits and - _ . only, different from the tool's other headers ignoring case. Then list the tools over HTTP with an SDK client and check ${tool.name} is there.`
111
+ : 'Make the parameter a string or an integer (a header carries text anyway), or stop mirroring it into a header.',
112
+ });
113
+ }
114
+ return findings;
115
+ },
116
+ };
@@ -6,6 +6,8 @@ import { route, sharedWord, vagueId } from './naming.js';
6
6
  import { cacheHints, deprecated, discover, duplicateName, schema, serverInfo, toolsCapability } from './spec.js';
7
7
  import { noDryRun, unannotated } from './write.js';
8
8
  import { gated } from './gated.js';
9
+ import { xMcpHeader } from './headers.js';
10
+ import { schemaRef } from './refs.js';
9
11
  import { findable } from './search.js';
10
12
  export const MENU_RULES = [
11
13
  nondeterministic,
@@ -25,6 +27,8 @@ export const MENU_RULES = [
25
27
  noDryRun,
26
28
  unannotated,
27
29
  schema,
30
+ xMcpHeader,
31
+ schemaRef,
28
32
  toolsCapability,
29
33
  discover,
30
34
  deprecated,
@@ -0,0 +1,15 @@
1
+ import type { MenuTool } from '../types.js';
2
+ import { type Rule } from './rule.js';
3
+ export type Where = 'inputSchema' | 'outputSchema';
4
+ export interface RefFault {
5
+ where: Where;
6
+ /** Where the $ref sits: `filter.region`, `<items>`, `<$defs>.A`. */
7
+ path: string;
8
+ ref: string;
9
+ /** network: an absolute http(s) URI, which clients must not fetch. missing: nothing in the schema it points to. */
10
+ kind: 'network' | 'missing';
11
+ }
12
+ /** Every $ref in one schema that a client can't resolve from the schema itself. */
13
+ export declare function unresolvedRefs(schema: unknown, where: Where): RefFault[];
14
+ export declare function refFaults(tool: MenuTool): RefFault[];
15
+ export declare const schemaRef: Rule;
@@ -0,0 +1,125 @@
1
+ import { count, names } from './rule.js';
2
+ /** JSON Pointer within the schema: `#/$defs/A`, `#/properties/a/items`. */
3
+ function pointer(root, ref) {
4
+ if (ref === '#' || ref === '#/')
5
+ return true;
6
+ let node = root;
7
+ for (const raw of ref.slice(2).split('/')) {
8
+ const part = decodeURIComponent(raw).replace(/~1/g, '/').replace(/~0/g, '~');
9
+ if (Array.isArray(node) && /^\d+$/.test(part) && Number(part) < node.length)
10
+ node = node[Number(part)];
11
+ else if (node && typeof node === 'object' && part in node)
12
+ node = node[part];
13
+ else
14
+ return false;
15
+ }
16
+ return true;
17
+ }
18
+ /** Every $id and $anchor in a schema, for refs that name them. */
19
+ function targets(node, ids, anchors, depth = 0) {
20
+ if (!node || typeof node !== 'object' || depth > 64)
21
+ return;
22
+ if (Array.isArray(node)) {
23
+ for (const v of node)
24
+ targets(v, ids, anchors, depth + 1);
25
+ return;
26
+ }
27
+ const s = node;
28
+ if (typeof s.$id === 'string')
29
+ ids.add(s.$id.replace(/#$/, ''));
30
+ if (typeof s.$anchor === 'string')
31
+ anchors.add(s.$anchor);
32
+ if (typeof s.$dynamicAnchor === 'string')
33
+ anchors.add(s.$dynamicAnchor);
34
+ for (const [k, v] of Object.entries(s))
35
+ if (k !== 'enum' && k !== 'const' && k !== 'default' && k !== 'examples')
36
+ targets(v, ids, anchors, depth + 1);
37
+ }
38
+ /** Every $ref in one schema that a client can't resolve from the schema itself. */
39
+ export function unresolvedRefs(schema, where) {
40
+ if (!schema || typeof schema !== 'object')
41
+ return [];
42
+ const ids = new Set();
43
+ const anchors = new Set();
44
+ targets(schema, ids, anchors);
45
+ const out = [];
46
+ const visit = (node, path, depth) => {
47
+ if (!node || typeof node !== 'object' || depth > 64)
48
+ return;
49
+ if (Array.isArray(node)) {
50
+ node.forEach((v, i) => visit(v, [...path, `${i}`], depth + 1));
51
+ return;
52
+ }
53
+ const s = node;
54
+ for (const key of ['$ref', '$dynamicRef']) {
55
+ const ref = s[key];
56
+ if (typeof ref !== 'string')
57
+ continue;
58
+ const at = path.length ? path.join('.') : 'the schema root';
59
+ if (ref.startsWith('#/') || ref === '#') {
60
+ if (!pointer(schema, ref))
61
+ out.push({ where, path: at, ref, kind: 'missing' });
62
+ }
63
+ else if (ref.startsWith('#')) {
64
+ if (!anchors.has(ref.slice(1)))
65
+ out.push({ where, path: at, ref, kind: 'missing' });
66
+ }
67
+ else {
68
+ // A ref to a schema's own $id (or a fragment of it) resolves locally.
69
+ const [base, fragment] = ref.split('#');
70
+ const local = [...ids].some((id) => id === base || id.endsWith(`/${base}`));
71
+ if (local && (!fragment || fragment.startsWith('/') || anchors.has(fragment)))
72
+ continue;
73
+ out.push({ where, path: at, ref, kind: /^https?:\/\//i.test(ref) ? 'network' : 'missing' });
74
+ }
75
+ }
76
+ for (const [k, v] of Object.entries(s)) {
77
+ if (k === 'enum' || k === 'const' || k === 'default' || k === 'examples')
78
+ continue;
79
+ visit(v, k === 'properties' ? path : [...path, k === 'items' || k.startsWith('$') || /^(any|one|all)Of$|^not$|^if$|^then$|^else$|Properties$/.test(k) ? `<${k}>` : k], depth + 1);
80
+ }
81
+ };
82
+ visit(schema, [], 0);
83
+ return out;
84
+ }
85
+ export function refFaults(tool) {
86
+ return [...unresolvedRefs(tool.inputSchema, 'inputSchema'), ...unresolvedRefs(tool.outputSchema, 'outputSchema')];
87
+ }
88
+ export const schemaRef = {
89
+ id: 'spec/ref',
90
+ severity: 'error',
91
+ since: '2026-07-28',
92
+ summary: "Every $ref in a tool's schemas resolves inside the schema",
93
+ run(ctx) {
94
+ const findings = [];
95
+ for (const tool of ctx.menu.tools) {
96
+ const faults = refFaults(tool);
97
+ if (!faults.length)
98
+ continue;
99
+ const output = faults.filter((f) => f.where === 'outputSchema');
100
+ const missingInput = faults.filter((f) => f.where === 'inputSchema' && f.kind === 'missing');
101
+ const detail = faults.map((f) => `${f.where} ${f.path}: $ref "${f.ref}" ${f.kind === 'network' ? 'is a network URI, which clients must not fetch' : 'points to nothing in the schema'}`);
102
+ const refs = names([...new Set(faults.map((f) => `"${f.ref}"`))], 3);
103
+ if (output.length) {
104
+ findings.push({
105
+ tool: tool.name,
106
+ message: `${tool.name}'s outputSchema has ${count(output.length, '$ref')} a client can't resolve (${names([...new Set(output.map((f) => `"${f.ref}"`))], 3)}), so the official SDK client fails every call to it ("has an invalid outputSchema: can't resolve reference"), however well the server answers. Clients must not fetch a network URI, so a $ref has to point inside the schema.`,
107
+ detail,
108
+ fix: `Put what the $ref points to in the outputSchema's own $defs and point the $ref there (#/$defs/…), then call ${tool.name} with an SDK client to confirm.`,
109
+ });
110
+ }
111
+ else {
112
+ findings.push({
113
+ tool: tool.name,
114
+ severity: missingInput.length ? 'error' : 'warn',
115
+ message: missingInput.length
116
+ ? `${tool.name}'s inputSchema has a $ref that points to nothing in the schema (${refs}), so the schema isn't valid: the spec requires schemas to be, the official SDK's server won't register it, and the model reads a parameter with no definition.`
117
+ : `${tool.name}'s inputSchema points to a network URI (${refs}). Clients must not fetch it and should reject the schema rather than treat the parameter as unconstrained, so a strict client can refuse ${tool.name}, and any other sends the model a parameter with no definition.`,
118
+ detail,
119
+ fix: `Put what the $ref points to in the inputSchema's own $defs and point the $ref there (#/$defs/…).`,
120
+ });
121
+ }
122
+ }
123
+ return findings;
124
+ },
125
+ };
package/dist/session.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { type ToolChange } from './compare.js';
2
2
  import { type Target } from './connect.js';
3
+ import { type InputTrace } from './mrtr.js';
3
4
  import { type FailureClass } from './failures.js';
4
5
  import type { Era, Finding, Menu, MenuTool, Severity } from './types.js';
5
6
  import { type AutoSummary } from './auto.js';
@@ -47,7 +48,9 @@ export interface StepRecord {
47
48
  * What a call step's call did: the tool answered, answered with an error
48
49
  * (isError), the request failed, or it wasn't sent (refused, not in the menu).
49
50
  */
50
- outcome?: 'answered' | 'tool-error' | 'failed' | 'not-sent';
51
+ outcome?: 'answered' | 'tool-error' | 'failed' | 'not-sent' | 'needs-input';
52
+ /** 2026-07-28: what the tool asked for and what came of the decline (mrtr.ts). */
53
+ input?: InputTrace;
51
54
  changed: boolean;
52
55
  listChanged: number;
53
56
  scope?: Scope;
package/dist/session.js CHANGED
@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
2
2
  import { parse } from 'yaml';
3
3
  import { cacheBreak, canonical, compareMenus } from './compare.js';
4
4
  import { listTools } from './connect.js';
5
+ import { callWithInput, MAX_ROUNDS } from './mrtr.js';
5
6
  import { buildMenu, toolDefinition } from './menu.js';
6
7
  import { connectPatiently, isContainerWrapper, MAIN_SEED, probeMenu, probeVariance, seeded } from './probe.js';
7
8
  import { varianceFinding } from './rules/determinism.js';
@@ -75,6 +76,8 @@ export async function session(target, scenario, options = {}) {
75
76
  const timeoutMs = options.timeoutMs ?? 30_000;
76
77
  const grace = options.noticeGraceMs ?? 500;
77
78
  const raw = [];
79
+ // 2026-07-28: every call that asked for input, for the input findings at the end.
80
+ const inputs = [];
78
81
  // The main process runs with a pinned hash seed, and so does every scope probe:
79
82
  // a probe with a different seed would count ordering variance as a change.
80
83
  const mainTarget = seeded(target, MAIN_SEED);
@@ -272,13 +275,28 @@ export async function session(target, scenario, options = {}) {
272
275
  // read-only one is asked again. On the server's word, not the user's.
273
276
  const readOnly = tool?.annotations?.readOnlyHint === true;
274
277
  callWaited.ms = 0;
275
- const result = await patiently(() => conn.client.callTool({ name: step.tool, arguments: step.args }, { timeout: timeoutMs }), {
278
+ // 2026-07-28: a tool that asks for input gets every elicitation declined
279
+ // and is called again (mrtr.ts); on 2025 it's a plain call.
280
+ const call = await patiently(() => callWithInput(conn, { name: step.tool, arguments: step.args }, { timeoutMs, elicitation: target.elicitation }), {
276
281
  waits,
277
282
  waited: callWaited,
278
283
  error: (e) => httpStatus(e) === 429 || (readOnly && tooMany(e)),
279
- result: (r) => readOnly && r.isError === true && RATE_LIMITED.test(errorText(r)),
284
+ result: (c) => readOnly && c.result?.isError === true && RATE_LIMITED.test(errorText(c.result)),
280
285
  });
286
+ if (call.input.outcome !== 'none' || call.input.missingResultType) {
287
+ record.input = call.input;
288
+ inputs.push({ step: index, tool: step.tool, input: call.input });
289
+ }
290
+ if (!call.result) {
291
+ // It never answered: still asking, asking for what wasn't declared, or failing on the decline.
292
+ record.outcome = 'needs-input';
293
+ record.note = inputNote(call.input, target.elicitation ?? 'decline');
294
+ throw new InputStopped();
295
+ }
296
+ const result = call.result;
281
297
  record.outcome = result.isError ? 'tool-error' : 'answered';
298
+ if (call.input.rounds && !result.isError)
299
+ record.note = inputNote(call.input, target.elicitation ?? 'decline');
282
300
  if (result.isError) {
283
301
  const text = errorText(result);
284
302
  if (RATE_LIMITED.test(text)) {
@@ -289,33 +307,49 @@ export async function session(target, scenario, options = {}) {
289
307
  break;
290
308
  }
291
309
  const short = clip(text, 120);
292
- record.note = text ? `the tool returned an error: ${short}` : 'the tool returned an error';
310
+ record.note = call.input.rounds
311
+ ? `${inputNote(call.input, target.elicitation ?? 'decline')}, with a tool error: ${clip(text, 100)}`
312
+ : text ? `the tool returned an error: ${short}` : 'the tool returned an error';
293
313
  record.failure = classifyFailure(text, { hadArguments: Object.keys(step.args).length > 0 });
294
- // A setup failure is reported once, for the whole run (session/untested).
295
- if (!SETUP_FAILURES.has(record.failure))
314
+ // A setup failure is reported once, for the whole run (session/untested). A
315
+ // tool error that answers a decline is how a tool should say no (input-required).
316
+ if (!SETUP_FAILURES.has(record.failure) && !call.input.rounds)
296
317
  fail('session/tool-error', 'warn', index, step, text, record.failure);
297
318
  }
298
319
  }
299
320
  catch (error) {
300
- record.status = 'failed';
301
- record.outcome = 'failed';
302
- record.note = serverWords(error, 200);
303
- if (lost(record.note, index)) {
304
- done();
305
- break;
321
+ // A tool that never answered its input requests is said by the input findings,
322
+ // not as a failed call. The menu is still listed after it, as after any step.
323
+ if (error instanceof InputStopped) {
324
+ // fall through to the listing below
306
325
  }
307
- if (tooMany(error)) {
308
- limited(index, record.note, callWaited.ms, httpStatus(error) === 429 || tool?.annotations?.readOnlyHint === true ? undefined : step.tool);
309
- record.note = 'rate-limited';
310
- done();
311
- break;
326
+ else {
327
+ record.status = 'failed';
328
+ record.outcome = 'failed';
329
+ record.note = serverWords(error, 200);
330
+ if (lost(record.note, index)) {
331
+ done();
332
+ break;
333
+ }
334
+ if (tooMany(error)) {
335
+ limited(index, record.note, callWaited.ms, httpStatus(error) === 429 || tool?.annotations?.readOnlyHint === true ? undefined : step.tool);
336
+ record.note = 'rate-limited';
337
+ done();
338
+ break;
339
+ }
340
+ const code = error.code;
341
+ // 2026-07-28's MissingRequiredClientCapabilityError says what it needed.
342
+ if (code === -32021) {
343
+ const needed = Object.keys((error.data?.requiredCapabilities ?? {}));
344
+ if (needed.length)
345
+ record.note = `${record.note} (needs the client to support ${needed.join(', ')})`;
346
+ }
347
+ record.failure = classifyFailure(record.note, { code: typeof code === 'number' ? code : undefined, hadArguments: Object.keys(step.args).length > 0 });
348
+ // The SDK's own request timeout: toolmenu stopped waiting, the server didn't refuse anything.
349
+ const timedOutMs = code === 'REQUEST_TIMEOUT' ? timeoutMs : undefined;
350
+ if (!SETUP_FAILURES.has(record.failure))
351
+ fail('session/step-failed', 'error', index, step, record.note, record.failure, timedOutMs);
312
352
  }
313
- const code = error.code;
314
- record.failure = classifyFailure(record.note, { code: typeof code === 'number' ? code : undefined, hadArguments: Object.keys(step.args).length > 0 });
315
- // The SDK's own request timeout: toolmenu stopped waiting, the server didn't refuse anything.
316
- const timedOutMs = code === 'REQUEST_TIMEOUT' ? timeoutMs : undefined;
317
- if (!SETUP_FAILURES.has(record.failure))
318
- fail('session/step-failed', 'error', index, step, record.note, record.failure, timedOutMs);
319
353
  }
320
354
  }
321
355
  else if (step.kind === 'wait_for') {
@@ -426,6 +460,7 @@ export async function session(target, scenario, options = {}) {
426
460
  done();
427
461
  }
428
462
  raw.push(...failureFindings(sameError([...failures.values()]), options.auto));
463
+ raw.push(...inputFindings(inputs, target.elicitation ?? 'decline'));
429
464
  if (explained.length)
430
465
  raw.push(knownVariance(explained));
431
466
  if (onWord.length)
@@ -1322,3 +1357,105 @@ export function starterScenario(menu, options = {}) {
1322
1357
  }
1323
1358
  return lines.join('\n') + '\n';
1324
1359
  }
1360
+ /** Thrown inside a call step when the tool never completed its input rounds: not a failed request. */
1361
+ class InputStopped extends Error {
1362
+ }
1363
+ const PAST = { decline: 'declined', cancel: 'cancelled' };
1364
+ const KIND_WORDS = { form: 'a form', url: 'a URL to open', roots: 'roots', sampling: 'sampling', other: 'something else' };
1365
+ function kindList(kinds) {
1366
+ const words = kinds.map((k) => KIND_WORDS[k]);
1367
+ return words.length <= 1 ? words.join('') : `${words.slice(0, -1).join(', ')} and ${words[words.length - 1]}`;
1368
+ }
1369
+ /** once, twice, 3 times. */
1370
+ function times(n) {
1371
+ return n === 1 ? 'once' : n === 2 ? 'twice' : `${n} times`;
1372
+ }
1373
+ /** The step's note for a call that asked for input. */
1374
+ function inputNote(input, answer) {
1375
+ const asked = `asked for ${kindList(input.kinds)}`;
1376
+ const rounds = `${input.rounds} round${input.rounds === 1 ? '' : 's'}`;
1377
+ switch (input.outcome) {
1378
+ case 'completed':
1379
+ return `${asked}; ${PAST[answer]} ${times(input.rounds)}, then answered`;
1380
+ case 'loop':
1381
+ return `${asked}; asked the same again after each ${answer}, stopped after ${rounds}`;
1382
+ case 'gave-up':
1383
+ return `${asked}; still asking after ${rounds}`;
1384
+ case 'undeclared':
1385
+ return `asked for ${kindList(input.undeclared ?? [])}, which the request didn't declare`;
1386
+ case 'decline-failed':
1387
+ return `${asked}; the retry with the ${answer} failed: ${serverWords(input.error, 160)}`;
1388
+ default:
1389
+ return asked;
1390
+ }
1391
+ }
1392
+ /**
1393
+ * What tools that asked for input did with the answer (2026-07-28 multi
1394
+ * round-trip requests). One info finding for all of them, and a warning or error
1395
+ * for each that an agent can't get past.
1396
+ */
1397
+ function inputFindings(inputs, answer) {
1398
+ const out = [];
1399
+ const asked = inputs.filter((i) => i.input.outcome !== 'none');
1400
+ if (asked.length) {
1401
+ const finished = asked.filter((i) => i.input.outcome === 'completed').length;
1402
+ out.push({
1403
+ rule: 'session/input-required',
1404
+ severity: 'info',
1405
+ step: asked[0].step,
1406
+ message: `${asked.length === 1 ? `${asked[0].tool} asked` : `${asked.length} tools asked`} for input mid-call (input_required, 2026-07-28). toolmenu ${PAST[answer]} every request, the same way every run, and called again: ${finished} of ${asked.length} then answered with a result the model can read.`,
1407
+ detail: asked.map((i) => `${i.tool} (step ${i.step}): ${inputNote(i.input, answer)}`),
1408
+ fix: 'Nothing to do for the ones that answered. The findings next to this one cover the rest.',
1409
+ });
1410
+ }
1411
+ for (const { step, tool, input } of asked) {
1412
+ if (input.outcome === 'loop' || input.outcome === 'gave-up') {
1413
+ out.push({
1414
+ rule: 'session/input-loop',
1415
+ severity: 'warn',
1416
+ step,
1417
+ tool,
1418
+ message: input.outcome === 'loop'
1419
+ ? `${tool} asks the same thing again after a ${answer}, every time: an agent whose user says no gets the question back instead of an answer, and can't finish the call. toolmenu stopped after ${MAX_ROUNDS} rounds.`
1420
+ : `${tool} was still asking for input after ${MAX_ROUNDS} rounds of ${answer}s, each time something else. An agent whose user says no can't finish the call.`,
1421
+ detail: [inputNote(input, answer)],
1422
+ fix: `Treat a ${answer} as an answer: return a result that says the user ${answer === 'decline' ? 'declined' : 'dismissed it'} (isError: true is fine), so the model can tell the user and move on.`,
1423
+ });
1424
+ }
1425
+ else if (input.outcome === 'decline-failed') {
1426
+ out.push({
1427
+ rule: 'session/decline-fails',
1428
+ severity: 'warn',
1429
+ step,
1430
+ tool,
1431
+ message: `${tool} fails with a protocol error when the user ${answer === 'decline' ? 'declines' : 'dismisses'} its request (“${serverWords(input.error, 120)}”). The model gets an error from the client instead of a result it can read and explain to the user.`,
1432
+ detail: [inputNote(input, answer)],
1433
+ fix: `Return a tool result on a ${answer} (isError: true with a sentence like "the user declined"), not a JSON-RPC error.`,
1434
+ });
1435
+ }
1436
+ else if (input.outcome === 'undeclared') {
1437
+ out.push({
1438
+ rule: 'session/undeclared-input',
1439
+ severity: 'warn',
1440
+ step,
1441
+ tool,
1442
+ message: `${tool} asked for ${kindList(input.undeclared ?? [])}, which the request didn't declare among its client capabilities. Servers must not ask a client for what it doesn't support: they should return MissingRequiredClientCapabilityError (-32021) naming it, so the client can say why the call can't run.${(input.undeclared ?? []).some((k) => k === 'roots' || k === 'sampling') ? ' 2026-07-28 also deprecates roots and sampling (SEP-2577).' : ''}`,
1443
+ detail: [inputNote(input, answer)],
1444
+ fix: `Check the request's io.modelcontextprotocol/clientCapabilities before asking, and return -32021 with requiredCapabilities when it lacks ${kindList(input.undeclared ?? [])}.${(input.undeclared ?? []).includes('roots') ? ' For roots, take the directory as a tool parameter instead.' : ''}`,
1445
+ });
1446
+ }
1447
+ }
1448
+ const unmarked = inputs.filter((i) => i.input.missingResultType);
1449
+ if (unmarked.length) {
1450
+ out.push({
1451
+ rule: 'session/result-type',
1452
+ severity: 'error',
1453
+ step: unmarked[0].step,
1454
+ ...(unmarked.length === 1 ? { tool: unmarked[0].tool } : {}),
1455
+ message: `${unmarked.length === 1 ? `${unmarked[0].tool}'s tools/call result has` : `${unmarked.length} tools' tools/call results have`} no resultType. 2026-07-28 servers must send it ("complete", or "input_required" when asking for input), and the official SDK client rejects a result without it ("missing required resultType"), so agents on it get an error where the tool answered.`,
1456
+ detail: unmarked.map((i) => `${i.tool} (step ${i.step})`),
1457
+ fix: 'Add resultType: "complete" to every tools/call result (the official SDKs add it; a hand-written server has to).',
1458
+ });
1459
+ }
1460
+ return out;
1461
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "toolmenu",
3
- "version": "0.15.0",
3
+ "version": "0.16.0",
4
4
  "description": "Lint your MCP server's tool menu for changes that confuse agents or break caches.",
5
5
  "author": "Nikša Perović (https://niksa.me)",
6
6
  "main": "dist/index.js",