toolmenu 0.16.0 → 0.17.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
@@ -108,7 +108,7 @@ jobs:
108
108
  - uses: actions/setup-node@v7
109
109
  with: { node-version: 22 }
110
110
  - run: npm ci && npm run build
111
- - uses: niksa90/toolmenu@v0.16.0
111
+ - uses: niksa90/toolmenu@v0.16.1
112
112
  with:
113
113
  command: node dist/server.js
114
114
  baseline: menu.json # your committed snapshot
@@ -188,7 +188,8 @@ serves, and 23 issue and pull-request tools that only the dynamic mode has.
188
188
  | `session/assumed-read-only` | info | Tools called on your word (`--assume-read-only`, `assume_read_only`) although the server doesn't mark them readOnlyHint |
189
189
  | `session/unlock-coverage` | warn | An unlock whose enum lists its values, called with only some of them: the tools behind the rest were never seen, so a baseline from the session misses them. With `--union-out` or `--auto`, an unlock never called at all too, with why `--auto` skipped it |
190
190
  | `session/nothing-called` | warn | `--auto` called no tools (all open-world, missing values, or not read-only): the run only listed the menu |
191
- | `session/session-lost` | error | The server ended the session after toolmenu opened a second connection with the same credentials (servers with one session per client). The run stops there; rerun with `--processes 1` |
191
+ | `session/session-lost` | error | The server ended the session after toolmenu opened a second connection with the same credentials (servers with one session per client; 2025-era servers only). The run stops there; rerun with `--processes 1` |
192
+ | `session/handle-error` | warn | 2026-07-28: `--auto` called a read-only tool with a handle that can't exist (`toolmenu-unknown-session`), and it answered with a protocol error instead of a tool error the model can read |
192
193
  | `session/rate-limited` | error | The server kept refusing requests for being too many (a 429) after toolmenu waited about a minute, or a tool not marked `readOnlyHint` said it was rate-limited (it isn't called again). The run stops there, with the steps it didn't check; give the run its own server instance or raise the limit for it |
193
194
  | `session/scope-unchecked` | info | A second server process or connection couldn't start mid-session (a server that holds a file or a port), so whether a change was global wasn't checked. Said once for the run |
194
195
 
@@ -387,11 +388,14 @@ server, or from the spec itself. If a rule can't point to one, it doesn't ship.
387
388
  | `description/late-instruction` | info | With the default cut: instructions after character 280, which a client that cuts descriptions short would hide, as one summary. Set `descriptionLimit` and `description/buried` checks your real cut instead. (Before 0.13 this was part of `description/cut`; that id's setting still applies.) |
388
389
  | `naming/vague-id` | warn | Parameters called just `id` that don't say *which* thing, as one summary with a suggested name |
389
390
  | `ids/authored` | info | An ID the agent must supply that no tool appears to return, so the agent may invent it, one finding per kind of ID (heuristic: IDs from a URL or another tool's text output look the same) |
391
+ | `ids/handle-lifetime` | info | 2026-07-28: a tool that creates a handle another tool takes back (`start_session` → `session_id`) doesn't say how long it lasts (heuristic) |
390
392
  | `write/unannotated` | warn | Tools named like writes (`delete_`, `send_`…) with no annotations, as one summary grouped by the annotation each name suggests |
391
393
  | `naming/shared-word` | info | Nouns that name different things across tools (`list_team_audits` vs `get_audit_trail`), as one summary |
392
394
  | `write/no-dry-run` | info | Destructive tools with no dry-run parameter or preview tool, as one summary |
393
395
  | `spec/discover` | info | The server only speaks the 2025 protocol, so 2026-07-28 rules are skipped |
394
396
  | `spec/deprecated`, `spec/cache-hints` | info | 2026-07-28: deprecated features still advertised; `ttlMs: 0`, or `cacheScope: "public"` on a server that took credentials |
397
+ | `menu/auth-variance` | info | With `--as` (or `identities` in the config): the tool set differs by identity, what each adds, lacks or defines differently against the first, and its tokens. Allowed by the spec; a baseline of one identity's menu doesn't cover the others. An identity that can't be listed is said here too |
398
+ | `spec/cache-scope-public` | warn | 2026-07-28, with `--as`: the tool set differs by identity, and `tools/list` says `cacheScope: "public"`, which lets shared caches serve one caller's list to another |
395
399
 
396
400
  The naming and ID rules are heuristics, tuned on real servers (FINDINGS F7 and
397
401
  F10) and a private 115-tool one. They're the extras; the change checks are the point.
@@ -469,6 +473,9 @@ toolmenu sees what the server sends. Plenty of agent failures happen elsewhere:
469
473
  (2026-07-28 only; an error if the server lacks it)
470
474
  --processes <n> server processes or connections to compare (default: 2);
471
475
  1 opens no second one, session's scope check included
476
+ --as <name>:<cred> snapshot: list the menu as this identity too, repeatable:
477
+ "reader:Authorization: Bearer …" (HTTP) or "admin:ROLE=admin"
478
+ (stdio). The first is the menu saved; the others are compared
472
479
  ```
473
480
 
474
481
  Exit codes: `0` clean · `1` findings at or above `--fail-on` · `2` couldn't connect
package/dist/auth.js CHANGED
@@ -8,6 +8,7 @@ import { join } from 'node:path';
8
8
  import { Client, StreamableHTTPClientTransport, UnauthorizedError } from '@modelcontextprotocol/client';
9
9
  import { VERSION } from './version.js';
10
10
  import { endSession } from './close.js';
11
+ import { quietExclusions } from './connect.js';
11
12
  /**
12
13
  * The redirect port. Fixed, not random: dynamic registration records the exact
13
14
  * redirect URI, so a new port would invalidate the stored client on every login.
@@ -260,7 +261,7 @@ async function check(serverUrl) {
260
261
  const transport = new StreamableHTTPClientTransport(new URL(serverUrl), { authProvider: new StoredOAuthProvider(serverUrl) });
261
262
  await client.connect(transport);
262
263
  try {
263
- const { tools } = await client.listTools();
264
+ const { tools } = await quietExclusions(() => client.listTools());
264
265
  return { name: client.getServerVersion()?.name, tools: tools.length };
265
266
  }
266
267
  finally {
package/dist/auto.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { readFile } from 'node:fs/promises';
2
2
  import { isMap, isNode, isScalar, parseDocument } from 'yaml';
3
3
  import { synthesizeArgs } from './args.js';
4
+ import { createdKinds, handleParams } from './rules/handles.js';
4
5
  import { MAX_UNLOCKS, unlockers } from './session.js';
5
6
  import { COLLECTION_VERBS, LOOKUP_VERBS, verbOf, WRITE_VERBS } from './words.js';
6
7
  /** Marked or named as a write: never called on the user's word. Says why, or undefined. */
@@ -45,6 +46,7 @@ export function autoScenario(menu, options = {}) {
45
46
  const { perTool, ignored: unusedValues } = resolveValues(menu, options.values ?? {});
46
47
  ignored.push(...unusedValues);
47
48
  const candidates = [];
49
+ const modern = (menu.server.protocolVersion ?? '') >= '2026-07-28';
48
50
  // Read-only unlocks with every value in an enum: each value, outside the call
49
51
  // budget, so the tools behind every toolset are seen (GitHub: 19 toolsets).
50
52
  // Called even when marked openWorldHint, without --open-world: an unlock changes
@@ -76,6 +78,13 @@ export function autoScenario(menu, options = {}) {
76
78
  }
77
79
  const filled = synthesizeArgs(tool.inputSchema, perTool.get(tool.name));
78
80
  if (!filled.ok) {
81
+ // 2026-07-28: a handle the server mints (a session another tool starts) is
82
+ // called once with one that can't exist, to see the model gets a readable error.
83
+ const probe = modern ? handleProbe(tool, menu.tools, filled.missing, perTool.get(tool.name)) : undefined;
84
+ if (probe) {
85
+ candidates.push({ tool, args: probe.args, rank: 4, valued: false, probe: probe.probe });
86
+ continue;
87
+ }
79
88
  skipped.push({ tool: tool.name, reason: 'needs values', missing: filled.missing });
80
89
  continue;
81
90
  }
@@ -87,7 +96,7 @@ export function autoScenario(menu, options = {}) {
87
96
  skipped.push({ tool: c.tool.name, reason: 'over the call budget' });
88
97
  const steps = options.callsOnly ? [] : [{ kind: 'list' }];
89
98
  for (const c of chosen)
90
- steps.push({ kind: 'call', tool: c.tool.name, args: c.args });
99
+ steps.push({ kind: 'call', tool: c.tool.name, args: c.args, ...(c.probe ? { probe: c.probe } : {}) });
91
100
  for (const u of unlocks) {
92
101
  const array = u.tool.inputSchema?.properties?.[u.param]?.type === 'array';
93
102
  const values = u.values.slice(0, MAX_UNLOCKS);
@@ -100,7 +109,7 @@ export function autoScenario(menu, options = {}) {
100
109
  steps.push({ kind: 'call', tool: u.tool.name, args: { [u.param]: array ? [values[0]] : values[0] }, ...tentative });
101
110
  }
102
111
  if (chosen.length && !options.callsOnly)
103
- steps.push({ kind: 'call', tool: chosen[0].tool.name, args: chosen[0].args });
112
+ steps.push({ kind: 'call', tool: chosen[0].tool.name, args: chosen[0].args, ...(chosen[0].probe ? { probe: chosen[0].probe } : {}) });
104
113
  const called = [...chosen.map((c) => c.tool.name), ...unlocks.map((u) => u.tool.name)];
105
114
  return {
106
115
  scenario: { allowWrites: false, steps, ...(assumed.size ? { assumeReadOnly: [...assumed] } : {}) },
@@ -234,6 +243,28 @@ function rank(tool, args) {
234
243
  return 2;
235
244
  return 3;
236
245
  }
246
+ /**
247
+ * A required handle filled with one that can't exist: `toolmenu-unknown-session`,
248
+ * or the nil-version UUID for a uuid format. Only for a read-only tool (the caller
249
+ * checks), only when every other required value is filled, and only for a kind
250
+ * some tool in the menu creates, so it is a handle the server mints.
251
+ */
252
+ function handleProbe(tool, tools, missing, given) {
253
+ const created = createdKinds(tools);
254
+ const handles = missing.flatMap((param) => {
255
+ const kind = [...created].find((k) => handleParams(tool, k).includes(param));
256
+ return kind ? [{ param, kind }] : [];
257
+ });
258
+ if (handles.length !== 1 || missing.length !== 1)
259
+ return undefined;
260
+ const [{ param, kind }] = handles;
261
+ const schema = tool.inputSchema?.properties?.[param];
262
+ if (!schema || (schema.type !== undefined && schema.type !== 'string') || typeof schema.pattern === 'string' || schema.enum)
263
+ return undefined;
264
+ const value = schema.format === 'uuid' ? '00000000-0000-4000-8000-000000000000' : `toolmenu-unknown-${kind}`;
265
+ const rest = synthesizeArgs(tool.inputSchema, { ...given, [param]: { value, raw: value } });
266
+ return rest.ok ? { args: rest.args, probe: { param, kind } } : undefined;
267
+ }
237
268
  /** Parameters the skipped tools need, most needed first, with how many tools each fills. */
238
269
  export function neededValues(skipped) {
239
270
  const by = new Map();
package/dist/breakdown.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import { canonical } from './compare.js';
2
+ import { usedEntries } from './schema-ref.js';
2
3
  import { countTokens } from './menu.js';
3
4
  const TOP = 5;
4
5
  const BIG_ENUM = 20;
@@ -40,37 +41,8 @@ function unusedDefs(menu) {
40
41
  const pools = ['$defs', 'definitions'].filter((k) => schema[k] && typeof schema[k] === 'object');
41
42
  if (!pools.length)
42
43
  continue;
43
- const { $defs: _d, definitions: _df, ...rest } = schema;
44
- const used = new Set();
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
- };
65
- while (queue.length) {
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, '~'));
69
- }
70
- for (const m of text.matchAll(/"\$(?:dynamic)?[rR]ef"\s*:\s*"([^"]*)"/g))
71
- if (!m[1].startsWith('#/'))
72
- named(m[1]);
73
- }
44
+ // The same resolver as spec/ref: pointers, $anchor/$dynamicAnchor, $id resources.
45
+ const used = usedEntries(schema);
74
46
  let unused = 0;
75
47
  for (const pool of pools) {
76
48
  for (const [name, def] of Object.entries(schema[pool])) {
package/dist/catalog.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { Connection } from './connect.js';
1
+ import { type Connection } from './connect.js';
2
2
  import type { Finding, MenuTool } from './types.js';
3
3
  /**
4
4
  * Operations a server keeps out of its menu, where `diff` can't see them:
package/dist/catalog.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { quietExclusions } from './connect.js';
1
2
  import { toolTokens } from './menu.js';
2
3
  import { classifyFailure, RATE_LIMITED, tooMany } from './failures.js';
3
4
  import { nouns, singular } from './words.js';
@@ -271,7 +272,7 @@ async function readRouters(conn, routers, skipped, options) {
271
272
  async function callPatiently(conn, name, args, timeoutMs = 30_000) {
272
273
  for (let attempt = 0;; attempt++) {
273
274
  try {
274
- const result = await conn.client.callTool({ name, arguments: args }, { timeout: timeoutMs });
275
+ const result = await quietExclusions(() => conn.client.callTool({ name, arguments: args }, { timeout: timeoutMs }));
275
276
  const text = result.isError ? resultText(result) : '';
276
277
  if (result.isError && RATE_LIMITED.test(text) && attempt < 3) {
277
278
  await sleep(2000 * 2 ** attempt);
@@ -306,8 +307,8 @@ const FAILED_AS = {
306
307
  fix: 'Check the server is set up for this account or site, then rerun.',
307
308
  },
308
309
  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.",
310
+ what: ["needed a client capability toolmenu doesn't declare", "needed a client capability toolmenu doesn't declare"],
311
+ fix: "Nothing to fix in the server: toolmenu doesn't declare the capability it asked for, so it can't list these routers' commands.",
311
312
  },
312
313
  'invalid-arguments': {
313
314
  what: ["rejected the listing call's arguments", "rejected the listing call's arguments"],
package/dist/cli.js CHANGED
@@ -9,7 +9,7 @@ import { loadMenu } from './menu.js';
9
9
  import { history, historyCsv } from './history.js';
10
10
  import { counts, formatDiff, formatHistory, formatPlan, formatSession, formatSnapshot } from './report.js';
11
11
  import { loadScenario, session, starterScenario, unlockListers, valuesFromListing } from './session.js';
12
- import { listTools } from './connect.js';
12
+ import { listTools, quietExclusions } from './connect.js';
13
13
  import { patiently, tooMany } from './failures.js';
14
14
  import { buildMenu } from './menu.js';
15
15
  import { existsSync } from 'node:fs';
@@ -82,10 +82,12 @@ export async function main(argv) {
82
82
  const elicitation = (values.elicitation ?? 'decline');
83
83
  if (!ELICITATIONS.includes(elicitation))
84
84
  throw new UsageError('--elicitation must be decline or cancel');
85
+ if (values.as !== undefined && sub !== 'snapshot')
86
+ throw new UsageError('--as goes with snapshot: it lists the menu once per identity.');
85
87
  if (values.elicitation !== undefined && sub !== 'session')
86
88
  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 });
89
+ // Only session calls tools, so only its targets declare elicitation and say how to answer.
90
+ const answering = (t) => ({ ...t, elicitation });
89
91
  const processes = values.processes !== undefined ? Number(values.processes) : config.processes ?? 2;
90
92
  if (!Number.isInteger(processes) || processes < 1)
91
93
  throw new UsageError('--processes must be a whole number, 1 or more');
@@ -143,7 +145,7 @@ export async function main(argv) {
143
145
  const path = values.scenario ?? 'scenario.yml';
144
146
  if (existsSync(path))
145
147
  throw new UsageError(`${path} already exists. Pick another path with --scenario.`);
146
- const initTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
148
+ const initTarget = answering(parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol));
147
149
  const conn = await connectPatiently(seeded(initTarget, MAIN_SEED), { timeoutMs });
148
150
  try {
149
151
  const list = await patiently(() => listTools(conn, { timeoutMs }), { error: tooMany });
@@ -154,7 +156,7 @@ export async function main(argv) {
154
156
  const read = [];
155
157
  for (const { unlock, lister } of unlockListers(menu.tools)) {
156
158
  try {
157
- const result = await conn.client.callTool({ name: lister, arguments: {} }, { timeout: timeoutMs });
159
+ const result = await quietExclusions(() => conn.client.callTool({ name: lister, arguments: {} }, { timeout: timeoutMs }));
158
160
  const found = result.isError ? [] : valuesFromListing(result);
159
161
  if (found.length) {
160
162
  unlockValues[unlock] = found;
@@ -295,9 +297,10 @@ export async function main(argv) {
295
297
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
296
298
  }
297
299
  const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
300
+ const identities = values.as?.length ? parseIdentities(values.as, target.kind) : configIdentities(config.identities, target.kind);
298
301
  const routesPath = values.routes ?? config.routes;
299
302
  const routes = routesPath ? await loadRoutes(routesPath) : undefined;
300
- const { menu, findings } = await snapshot(target, { routes, timeoutMs, processes, catalog: values.catalog ? (config.catalog ?? true) : undefined, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
303
+ const { menu, findings } = await snapshot(target, { routes, timeoutMs, processes, identities, catalog: values.catalog ? (config.catalog ?? true) : undefined, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
301
304
  const outPath = values['no-write'] ? undefined : values.out ?? 'menu.json';
302
305
  if (outPath)
303
306
  await writeFile(outPath, JSON.stringify(menu, null, 2) + '\n');
@@ -352,6 +355,39 @@ async function authCommand(args, values) {
352
355
  process.stdout.write(`Logged in to ${result.name ?? url} (${url}): it lists ${result.tools} tool${result.tools === 1 ? '' : 's'} with this login.\nsnapshot and session use it from now on (--no-auth to skip it); stored in ${authDir()}.\n`);
353
356
  return 0;
354
357
  }
358
+ /**
359
+ * --as name:credential, repeatable, in order of first mention: `reader:Authorization:
360
+ * Bearer x` (HTTP header) or `admin:ROLE=admin` (stdio env var). A name alone is an
361
+ * identity with only the --header/--env given to every run.
362
+ */
363
+ function parseIdentities(items, kind) {
364
+ const byName = new Map();
365
+ for (const item of items) {
366
+ const colon = item.indexOf(':');
367
+ const name = (colon < 0 ? item : item.slice(0, colon)).trim();
368
+ if (!/^[\w.-]+$/.test(name))
369
+ throw new UsageError(`--as "${item}" should start with a name (letters, digits, _ . -): --as reader:${kind === 'http' ? 'Authorization: Bearer …' : 'TOKEN=…'}`);
370
+ const identity = byName.get(name) ?? { name };
371
+ byName.set(name, identity);
372
+ if (colon < 0)
373
+ continue;
374
+ const credential = item.slice(colon + 1);
375
+ if (kind === 'http')
376
+ identity.headers = { ...identity.headers, ...parsePairs([credential], ':', `--as ${name}:`) };
377
+ else
378
+ identity.env = { ...identity.env, ...parsePairs([credential], '=', `--as ${name}:`) };
379
+ }
380
+ if (byName.size < 2)
381
+ throw new UsageError('--as needs two identities or more to compare: --as reader:… --as admin:…');
382
+ return [...byName.values()];
383
+ }
384
+ /** The config file's identities, for this kind of server: headers for HTTP, env for stdio. */
385
+ function configIdentities(ids, kind) {
386
+ if (!ids)
387
+ return undefined;
388
+ const list = Object.entries(ids).map(([name, id]) => ({ name, ...(kind === 'http' ? (id.headers ? { headers: id.headers } : {}) : id.env ? { env: id.env } : {}) }));
389
+ return list.length >= 2 ? list : undefined;
390
+ }
355
391
  function parsePairs(items, separator, flag) {
356
392
  const pairs = {};
357
393
  for (const item of items) {
package/dist/config.d.ts CHANGED
@@ -16,6 +16,15 @@ export interface Config {
16
16
  descriptionLimit?: number | string;
17
17
  /** Tools (names or globs) your client sends with the full description. */
18
18
  fullDescriptions?: string[];
19
+ /**
20
+ * snapshot: list the menu once per identity, the first being the main one:
21
+ * { "reader": { "headers": { "Authorization": "Bearer …" } }, "admin": { "env": { "ROLE": "admin" } } }.
22
+ * --as replaces them.
23
+ */
24
+ identities?: Record<string, {
25
+ headers?: Record<string, string>;
26
+ env?: Record<string, string>;
27
+ }>;
19
28
  /** Server processes (stdio) or connections (HTTP) to compare, the main one included (default 2). */
20
29
  processes?: number;
21
30
  /**
package/dist/config.js CHANGED
@@ -29,6 +29,17 @@ export async function loadConfig(path) {
29
29
  if (config.processes !== undefined && !(Number.isInteger(config.processes) && config.processes >= 1)) {
30
30
  throw new Error(`${file}: processes must be a whole number, 1 or more`);
31
31
  }
32
+ if (config.identities !== undefined) {
33
+ const strings = (v) => v === undefined || (typeof v === 'object' && v !== null && !Array.isArray(v) && Object.values(v).every((x) => typeof x === 'string'));
34
+ const ids = config.identities;
35
+ if (typeof ids !== 'object' || ids === null || Array.isArray(ids))
36
+ throw new Error(`${file}: identities must be an object, like { "reader": { "headers": { "Authorization": "Bearer …" } } }`);
37
+ for (const [name, id] of Object.entries(ids)) {
38
+ if (typeof id !== 'object' || id === null || Array.isArray(id) || !strings(id.headers) || !strings(id.env)) {
39
+ throw new Error(`${file}: identities.${name} must be { "headers": { … } } or { "env": { … } }, with string values`);
40
+ }
41
+ }
42
+ }
32
43
  const catalog = config.catalog;
33
44
  if (catalog !== undefined) {
34
45
  const names = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === 'string' && x.length > 0);
package/dist/connect.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { Client } from '@modelcontextprotocol/client';
2
2
  import type { Transport } from '@modelcontextprotocol/client';
3
3
  import type { Era } from './types.js';
4
+ export declare function quietExclusions<T>(work: () => Promise<T>): Promise<T>;
4
5
  export type Protocol = 'auto' | 'legacy' | 'modern';
5
6
  export declare const PROTOCOLS: readonly Protocol[];
6
7
  export declare const MODERN_VERSION = "2026-07-28";
package/dist/connect.js CHANGED
@@ -10,15 +10,41 @@ import { VERSION } from './version.js';
10
10
  * to the 2025 one. legacy: the 2025 handshake only. modern: 2026-07-28 only, an error if
11
11
  * the server can't speak it.
12
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
- };
13
+ /**
14
+ * Run `work` with the SDK's "[mcp-sdk] excluding tool" warnings held back. The SDK
15
+ * client drops a tool with an invalid x-mcp-header from its own tools/list (also
16
+ * inside callTool, when it refreshes its list) and console.warns about it; toolmenu
17
+ * reads the list off the wire and reports those tools as spec/x-mcp-header findings.
18
+ * Only while toolmenu lists or calls, so an app that imports toolmenu keeps its own
19
+ * warnings. Overlapping runs share one filter, put in by the first and taken out by
20
+ * the last.
21
+ */
22
+ let quieting = 0;
23
+ let originalWarn;
24
+ let installedWarn;
25
+ export async function quietExclusions(work) {
26
+ if (quieting++ === 0) {
27
+ originalWarn = console.warn;
28
+ const warn = originalWarn.bind(console);
29
+ installedWarn = (...args) => {
30
+ if (typeof args[0] === 'string' && args[0].startsWith('[mcp-sdk] excluding tool '))
31
+ return;
32
+ warn(...args);
33
+ };
34
+ console.warn = installedWarn;
35
+ }
36
+ try {
37
+ return await work();
38
+ }
39
+ finally {
40
+ if (--quieting === 0 && originalWarn) {
41
+ // Only take out our own filter: a replacement put in meanwhile stays.
42
+ if (console.warn === installedWarn)
43
+ console.warn = originalWarn;
44
+ originalWarn = installedWarn = undefined;
45
+ }
46
+ }
47
+ }
22
48
  export const PROTOCOLS = ['auto', 'legacy', 'modern'];
23
49
  export const MODERN_VERSION = '2026-07-28';
24
50
  export const ELICITATIONS = ['decline', 'cancel'];
@@ -67,15 +93,19 @@ export class WireLog {
67
93
  export async function connect(target, options = {}) {
68
94
  const client = new Client({ name: 'toolmenu', version: VERSION }, {
69
95
  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: {} } },
96
+ // Only for session (target.elicitation set): a connection that calls tools
97
+ // declares elicitation, form and URL mode, so a tool that asks the user something
98
+ // runs its "the user said no" path instead of failing (2026-07-28 multi
99
+ // round-trip requests). snapshot and the rest declare nothing, as before 0.16:
100
+ // a server may list different tools to a client that can be asked things.
101
+ // Never roots or sampling: 2026-07-28 deprecates them (SEP-2577).
102
+ ...(target.elicitation ? { capabilities: { elicitation: { form: {}, url: {} } } } : {}),
75
103
  });
76
104
  // A 2025 server asks with an elicitation/create request; 2026-07-28 ones embed it
77
105
  // in an input_required result, which session answers itself (mrtr.ts). Same answer.
78
- client.setRequestHandler('elicitation/create', async () => ({ action: target.elicitation ?? 'decline' }));
106
+ const elicitation = target.elicitation;
107
+ if (elicitation)
108
+ client.setRequestHandler('elicitation/create', async () => ({ action: elicitation }));
79
109
  let transport;
80
110
  let stderrText = '';
81
111
  let oauth = false;
@@ -265,7 +295,7 @@ export async function listTools(connection, options = {}) {
265
295
  let clientError;
266
296
  let caught;
267
297
  try {
268
- await connection.client.listTools(undefined, { cacheMode: 'bypass', timeout: options.timeoutMs });
298
+ await quietExclusions(() => connection.client.listTools(undefined, { cacheMode: 'bypass', timeout: options.timeoutMs }));
269
299
  }
270
300
  catch (error) {
271
301
  caught = error;
package/dist/diff.js CHANGED
@@ -1,6 +1,8 @@
1
1
  import { createHash } from 'node:crypto';
2
2
  import { canonical, compareMenus } from './compare.js';
3
3
  import { countTokens } from './menu.js';
4
+ import { headerFaults } from './rules/headers.js';
5
+ import { indexSchema } from './schema-ref.js';
4
6
  import { isCalendar, parseSemver } from './semver.js';
5
7
  import { SEVERITY_RANK } from './types.js';
6
8
  /** Every diff rule, its default severity and what it means for semver. */
@@ -25,6 +27,10 @@ export const DIFF_RULES = {
25
27
  // added, removed or renamed. Callers don't change; proxies and WAFs routing on the
26
28
  // header do.
27
29
  'diff/x-mcp-header': { severity: 'info', class: 'notice' },
30
+ // The new release's x-mcp-header makes Streamable HTTP clients drop the tool,
31
+ // which the old one didn't. A warning, not breaking: a menu file doesn't say whether
32
+ // the server is served over HTTP (stdio clients may ignore the annotation).
33
+ 'diff/x-mcp-header-invalid': { severity: 'warn', class: 'notice' },
28
34
  // Restructured ($ref, $defs) but accepts the same input: bytes and tokens changed.
29
35
  'diff/schema-equivalent': { severity: 'info', class: 'notice' },
30
36
  // Only the declared $schema dialect changed: one finding for the menu.
@@ -56,6 +62,11 @@ export const DIFF_RULES = {
56
62
  const BREAKING_RELEASE = '\u0000breaking-release\u0000';
57
63
  export function diffMenus(before, after, options = {}) {
58
64
  const raw = [];
65
+ // x-mcp-header is 2026-07-28's: only a menu served on it has the annotation mean anything.
66
+ const isModern = (m) => m.server.era === 'modern' || (m.server.protocolVersion ?? '') >= '2026-07-28';
67
+ const modern = isModern(after);
68
+ // A tool the old release already lost to a bad annotation isn't news; on a 2025 server it lost nothing.
69
+ const headers = { headers: modern, oldHeaders: isModern(before) };
59
70
  // Ignored tools leave the comparison entirely, so they can't pair into a
60
71
  // rename or show up as a reorder.
61
72
  const ignored = ignoreMatcher(options.ignore);
@@ -89,6 +100,10 @@ export function diffMenus(before, after, options = {}) {
89
100
  });
90
101
  }
91
102
  for (const t of added.filter((t) => !renamedTo.has(t.name))) {
103
+ // A new tool HTTP clients drop on arrival.
104
+ const lost = headerLoss(t, modern, undefined);
105
+ if (lost)
106
+ raw.push(lost);
92
107
  raw.push({
93
108
  rule: 'diff/tool-added',
94
109
  tool: t.name,
@@ -102,10 +117,10 @@ export function diffMenus(before, after, options = {}) {
102
117
  for (const t of newTools) {
103
118
  const old = oldByName.get(t.name);
104
119
  if (old)
105
- raw.push(...compareTool(old, t));
120
+ raw.push(...compareTool(old, t, headers));
106
121
  }
107
122
  for (const { from, to } of renames)
108
- raw.push(...compareTool(from, to).filter((f) => f.rule !== 'diff/description' && f.rule !== 'diff/other'));
123
+ raw.push(...compareTool(from, to, headers).filter((f) => f.rule !== 'diff/description' && f.rule !== 'diff/other'));
109
124
  collapseDialects(raw);
110
125
  collapseMenuWide(raw);
111
126
  // A session's union menu is in unlock order, which no client was served: no order to compare.
@@ -355,9 +370,35 @@ function collapseMenuWide(raw) {
355
370
  * "review it" at four. Recursion is bounded by resolveRefs, not by this.
356
371
  */
357
372
  const MAX_DEPTH = 64;
358
- function compareTool(old, t) {
373
+ /** The tool's new x-mcp-header problem, if HTTP clients drop it now and didn't before (`old` undefined: nothing to compare, or a 2025 release). */
374
+ function headerLoss(t, headers, old) {
375
+ if (!headers)
376
+ return undefined;
377
+ const dropped = (tool) => headerFaults(tool).filter((f) => f.dropped);
378
+ const broken = dropped(t);
379
+ if (!broken.length || (old && dropped(old).length))
380
+ return undefined;
381
+ return {
382
+ rule: 'diff/x-mcp-header-invalid',
383
+ tool: t.name,
384
+ message: `${code(t.name)}: an x-mcp-header annotation in this release breaks the spec's rules, so Streamable HTTP clients must leave the tool out of their menu. If the server is served over HTTP, ${code(t.name)} is gone for agents on those clients.`,
385
+ detail: broken.map((f) => `${f.path}${typeof f.header === 'string' && f.header ? ` (x-mcp-header: "${f.header}")` : ''}: ${f.problem}`),
386
+ fix: 'Fix the annotation before release: snapshot\'s spec/x-mcp-header says which rule it breaks.',
387
+ };
388
+ }
389
+ /**
390
+ * Compare one tool across releases. `headers`: check x-mcp-header validity, for a
391
+ * 2026-07-28 menu's own tools (not operations behind a search tool, which no client
392
+ * lists, and not a 2025 server, where the annotation means nothing).
393
+ */
394
+ function compareTool(old, t, { headers = false, oldHeaders = false } = {}) {
359
395
  const out = [];
360
396
  const name = t.name;
397
+ // An annotation that makes HTTP clients drop the tool, new in this release (or new
398
+ // because this release moved to 2026-07-28, where it starts to count).
399
+ const lost = headerLoss(t, headers, oldHeaders ? old : undefined);
400
+ if (lost)
401
+ out.push(lost);
361
402
  if ((old.description ?? '') !== (t.description ?? '')) {
362
403
  const detail = textDiff(old.description ?? '', t.description ?? '');
363
404
  out.push({
@@ -1144,15 +1185,11 @@ function expandRefs(schema) {
1144
1185
  if (!schema || typeof schema !== 'object')
1145
1186
  return { schema, expanded: true };
1146
1187
  let nodes = 0;
1147
- const pointer = (ref) => {
1148
- let node = schema;
1149
- for (const raw of ref.slice(2).split('/')) {
1150
- if (!node || typeof node !== 'object')
1151
- return undefined;
1152
- node = node[decodeURIComponent(raw).replace(/~1/g, '/').replace(/~0/g, '~')];
1153
- }
1154
- return node;
1155
- };
1188
+ // The resolver spec/ref uses: pointers, anchors and $id resources alike, and only
1189
+ // refs where a schema goes (a "$ref" inside enum or default is data). Each ref
1190
+ // resolves against the resource it's written in.
1191
+ const index = indexSchema(schema);
1192
+ const bases = new Map(index.refs.map((r) => [r.node, r.base]));
1156
1193
  const walk = (node, stack) => {
1157
1194
  if (++nodes > MAX_EXPANDED_NODES)
1158
1195
  throw new Error('too large');
@@ -1162,7 +1199,8 @@ function expandRefs(schema) {
1162
1199
  return node;
1163
1200
  const o = node;
1164
1201
  if (typeof o.$ref === 'string') {
1165
- const target = o.$ref.startsWith('#/') ? pointer(o.$ref) : undefined;
1202
+ const base = bases.get(o) ?? (o === rest ? bases.get(schema) : undefined);
1203
+ const target = base !== undefined ? index.resolve(o.$ref, base)?.value : undefined;
1166
1204
  if (target && typeof target === 'object' && !Array.isArray(target) && stack.filter((r) => r === o.$ref).length < MAX_UNROLL) {
1167
1205
  const { $ref: _ref, ...siblings } = o;
1168
1206
  return { ...walk(target, [...stack, o.$ref]), ...walk(siblings, stack) };
package/dist/explain.d.ts CHANGED
@@ -77,15 +77,20 @@ export declare function clean(text: string, max: number): string;
77
77
  /** "5.0 s", "0.3 s", "62 s". */
78
78
  export declare function seconds(ms: number): string;
79
79
  /** The command line, for a message: arguments with spaces quoted, cut at 120 characters. Never the --env values. */
80
- export declare function commandLine(command: string, args: string[]): string;
80
+ export declare function commandLine(command: string, args: string[], { cut }?: {
81
+ cut?: boolean;
82
+ }): string;
81
83
  /** The stderr fact: the last lines, and a note of how many came before. */
82
84
  export declare function stderrFact(trace: Trace): [string, string];
83
85
  /**
84
86
  * 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
+ * CLI that printed its usage and wants a subcommand (only when it `exited`), or a
88
+ * server that opened an HTTP port instead of talking on stdio. `command` is the whole
89
+ * command line, uncut, so the suggestion can be run as written.
87
90
  */
88
- export declare function startupHint(trace: Trace, command: string): string | undefined;
91
+ export declare function startupHint(trace: Trace, command: string, { exited }?: {
92
+ exited?: boolean;
93
+ }): string | undefined;
89
94
  /** A request header that carries credentials: Authorization, a cookie, or a name with key, token, secret or auth in it (x-mcp-api-key). */
90
95
  export declare function isCredentialHeader(name: string): boolean;
91
96
  /**