toolmenu 0.21.0 → 0.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +68 -37
  2. package/dist/apps.d.ts +56 -0
  3. package/dist/apps.js +99 -0
  4. package/dist/auto.js +2 -2
  5. package/dist/card.d.ts +18 -0
  6. package/dist/card.js +39 -0
  7. package/dist/cli.js +37 -10
  8. package/dist/colour.d.ts +8 -0
  9. package/dist/colour.js +70 -0
  10. package/dist/config.d.ts +2 -0
  11. package/dist/config.js +2 -0
  12. package/dist/connect.d.ts +6 -0
  13. package/dist/connect.js +22 -6
  14. package/dist/diff.js +111 -3
  15. package/dist/failures.d.ts +18 -5
  16. package/dist/failures.js +27 -12
  17. package/dist/help.js +3 -2
  18. package/dist/mrtr.d.ts +9 -1
  19. package/dist/mrtr.js +17 -0
  20. package/dist/options.d.ts +3 -0
  21. package/dist/options.js +1 -0
  22. package/dist/probe.d.ts +11 -1
  23. package/dist/probe.js +18 -3
  24. package/dist/report.js +12 -5
  25. package/dist/rule-docs.json +93 -3
  26. package/dist/rules/apps.d.ts +11 -0
  27. package/dist/rules/apps.js +156 -0
  28. package/dist/rules/capabilities.d.ts +21 -0
  29. package/dist/rules/capabilities.js +103 -0
  30. package/dist/rules/card.d.ts +7 -0
  31. package/dist/rules/card.js +65 -0
  32. package/dist/rules/clients.js +1 -0
  33. package/dist/rules/description.js +3 -0
  34. package/dist/rules/ids.js +35 -1
  35. package/dist/rules/index.js +18 -2
  36. package/dist/rules/naming.js +3 -0
  37. package/dist/rules/network.d.ts +21 -0
  38. package/dist/rules/network.js +63 -0
  39. package/dist/rules/rule.d.ts +18 -0
  40. package/dist/rules/search.js +1 -0
  41. package/dist/rules/spec.d.ts +9 -1
  42. package/dist/rules/spec.js +117 -3
  43. package/dist/rules/write.d.ts +0 -6
  44. package/dist/rules/write.js +11 -5
  45. package/dist/session.js +60 -11
  46. package/dist/snapshot.d.ts +5 -0
  47. package/dist/snapshot.js +89 -5
  48. package/dist/types.d.ts +5 -0
  49. package/dist/words.d.ts +8 -0
  50. package/dist/words.js +30 -2
  51. package/package.json +1 -1
  52. package/schemas/server-card.json +260 -0
package/dist/connect.d.ts CHANGED
@@ -16,6 +16,7 @@ export type Target = {
16
16
  cwd?: string;
17
17
  protocol?: Protocol;
18
18
  elicitation?: Elicitation;
19
+ apps?: boolean;
19
20
  } | {
20
21
  kind: 'http';
21
22
  url: string;
@@ -23,7 +24,12 @@ export type Target = {
23
24
  noAuth?: boolean;
24
25
  protocol?: Protocol;
25
26
  elicitation?: Elicitation;
27
+ apps?: boolean;
26
28
  };
29
+ /** The MCP Apps extension (ext-apps): interactive UI a tool names in _meta.ui.resourceUri. */
30
+ export declare const APPS_EXTENSION = "io.modelcontextprotocol/ui";
31
+ /** The one content type an MCP App's resource may have. */
32
+ export declare const APPS_MIME_TYPE = "text/html;profile=mcp-app";
27
33
  export interface WireResponse {
28
34
  method: string;
29
35
  result?: Record<string, unknown>;
package/dist/connect.js CHANGED
@@ -48,6 +48,10 @@ export async function quietExclusions(work) {
48
48
  export const PROTOCOLS = ['auto', 'legacy', 'modern'];
49
49
  export const MODERN_VERSION = '2026-07-28';
50
50
  export const ELICITATIONS = ['decline', 'cancel'];
51
+ /** The MCP Apps extension (ext-apps): interactive UI a tool names in _meta.ui.resourceUri. */
52
+ export const APPS_EXTENSION = 'io.modelcontextprotocol/ui';
53
+ /** The one content type an MCP App's resource may have. */
54
+ export const APPS_MIME_TYPE = 'text/html;profile=mcp-app';
51
55
  /** Every response the server sent, matched to the request method, as it came off the wire. */
52
56
  export class WireLog {
53
57
  responses = [];
@@ -93,13 +97,25 @@ export class WireLog {
93
97
  export async function connect(target, options = {}) {
94
98
  const client = new Client({ name: 'toolmenu', version: VERSION }, {
95
99
  versionNegotiation: { mode: target.protocol === 'legacy' ? 'legacy' : target.protocol === 'modern' ? { pin: MODERN_VERSION } : 'auto' },
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.
100
+ // With target.elicitation set, the connection declares elicitation, form and URL
101
+ // mode: session, so a tool that asks the user something runs its "the user said
102
+ // no" path instead of failing (2026-07-28 multi round-trip requests); and, from
103
+ // 0.22, snapshot's listing, since a server may list more tools to a client that
104
+ // can be asked things (github-mcp-server's delete_repository). snapshot lists
105
+ // once more without it (menu/capability-dependent).
101
106
  // Never roots or sampling: 2026-07-28 deprecates them (SEP-2577).
102
- ...(target.elicitation ? { capabilities: { elicitation: { form: {}, url: {} } } } : {}),
107
+ // With target.apps, the MCP Apps extension too: a server MAY register different tools,
108
+ // or other variants of them, for a host that renders apps (ext-apps, "Servers SHOULD
109
+ // check client capabilities before registering UI-enabled tools"), so the baseline
110
+ // is listed as such a host, as for elicitation.
111
+ ...(target.elicitation || target.apps
112
+ ? {
113
+ capabilities: {
114
+ ...(target.elicitation ? { elicitation: { form: {}, url: {} } } : {}),
115
+ ...(target.apps ? { extensions: { [APPS_EXTENSION]: { mimeTypes: [APPS_MIME_TYPE] } } } : {}),
116
+ },
117
+ }
118
+ : {}),
103
119
  });
104
120
  // A 2025 server asks with an elicitation/create request; 2026-07-28 ones embed it
105
121
  // in an input_required result, which session answers itself (mrtr.ts). Same answer.
package/dist/diff.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { agentTools, LEGACY_URI_KEY, resourceUriOf, uiMeta } from './apps.js';
1
2
  import { createHash } from 'node:crypto';
2
3
  import { canonical, compareMenus } from './compare.js';
3
4
  import { countTokens } from './menu.js';
@@ -40,6 +41,18 @@ export const DIFF_RULES = {
40
41
  'diff/properties-opened': { severity: 'info', class: 'minor' },
41
42
  'diff/properties-closed': { severity: 'error', class: 'breaking' },
42
43
  'diff/annotations': { severity: 'info', class: 'notice' },
44
+ // MCP Apps (ext-apps): _meta.ui.visibility without "model" keeps a tool out of the
45
+ // agent's list on an Apps host, so losing "model" removes the tool for the agent.
46
+ 'diff/apps-visibility': { severity: 'error', class: 'breaking' },
47
+ 'diff/apps-visible': { severity: 'info', class: 'minor' },
48
+ // The UI a tool names (_meta.ui.resourceUri) added, removed or moved: what an Apps
49
+ // host renders changes; calls don't.
50
+ 'diff/apps-ui': { severity: 'info', class: 'notice' },
51
+ // capabilities.extensions: an extension no longer declared is one clients stop using
52
+ // (no UI, no tasks); a warning, since core calls go on working.
53
+ 'diff/extension-removed': { severity: 'warn', class: 'breaking' },
54
+ 'diff/extension-added': { severity: 'info', class: 'minor' },
55
+ 'diff/extension-settings': { severity: 'info', class: 'notice' },
43
56
  'diff/other': { severity: 'info', class: 'notice' },
44
57
  'diff/order': { severity: 'info', class: 'notice' },
45
58
  // A tool lost a parameter and gained a required one with a close name: likely a
@@ -148,8 +161,10 @@ export function diffMenus(before, after, options = {}) {
148
161
  }
149
162
  raw.push(...compareCatalogs(before.catalog, after.catalog, ignored));
150
163
  raw.push(...compareLists(before, after));
164
+ raw.push(...compareExtensions(before, after));
151
165
  // Ignored tools leave the token counts and the budget too.
152
- const tokens = tokenChange(oldTools, newTools);
166
+ // What the agent pays: app-only tools (MCP Apps) aren't in its list.
167
+ const tokens = tokenChange(agentTools(oldTools), agentTools(newTools));
153
168
  if (options.tokenBudget !== undefined && tokens.after > options.tokenBudget) {
154
169
  const grew = tokens.tools.filter((t) => t.delta > 0).slice(0, 3);
155
170
  raw.push({
@@ -1410,10 +1425,13 @@ function compareRest(old, t) {
1410
1425
  across: same(`annotations\u0000${what}`, (count, list) => `Annotations changed the same way (${what}) in ${count}: ${list}.`),
1411
1426
  });
1412
1427
  }
1413
- const others = [...new Set([...Object.keys(old), ...Object.keys(t)])].filter((k) => !TOOL_FIELDS.has(k) && canonical(old[k]) !== canonical(t[k])).sort();
1428
+ out.push(...compareApps(old, t));
1429
+ // _meta.ui's URI and visibility are compareApps'; the rest of _meta is compared as any other field.
1430
+ const field = (tool, k) => (k === '_meta' ? withoutUi(tool._meta) : tool[k]);
1431
+ const others = [...new Set([...Object.keys(old), ...Object.keys(t)])].filter((k) => !TOOL_FIELDS.has(k) && canonical(field(old, k)) !== canonical(field(t, k))).sort();
1414
1432
  if (others.length) {
1415
1433
  const what = others.map((k) => {
1416
- const pair = `${show(old[k])} → ${show(t[k])}`;
1434
+ const pair = `${show(field(old, k))} → ${show(field(t, k))}`;
1417
1435
  return pair.length <= 60 ? `${k} ${pair}` : k;
1418
1436
  }).join(', ');
1419
1437
  out.push({
@@ -1425,6 +1443,96 @@ function compareRest(old, t) {
1425
1443
  }
1426
1444
  return out;
1427
1445
  }
1446
+ /** _meta without MCP Apps' resourceUri, visibility and the deprecated ui/resourceUri; undefined when nothing else is left. */
1447
+ function withoutUi(meta) {
1448
+ if (typeof meta !== 'object' || meta === null || Array.isArray(meta))
1449
+ return meta;
1450
+ const { ui, [LEGACY_URI_KEY]: _legacy, ...rest } = meta;
1451
+ // Only what compareApps says: the URI and visibility. The rest of _meta.ui (csp,
1452
+ // permissions, domain, prefersBorder) is still compared here, as any _meta field.
1453
+ if (typeof ui === 'object' && ui !== null && !Array.isArray(ui)) {
1454
+ const { resourceUri: _uri, visibility: _visibility, ...uiRest } = ui;
1455
+ if (Object.keys(uiRest).length)
1456
+ rest.ui = uiRest;
1457
+ }
1458
+ else if (ui !== undefined) {
1459
+ rest.ui = ui;
1460
+ }
1461
+ return Object.keys(rest).length ? rest : undefined;
1462
+ }
1463
+ /** Who sees the tool on an Apps host, as visibility says (default: both). */
1464
+ function seenBy(tool) {
1465
+ const v = uiMeta(tool)?.visibility;
1466
+ return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : ['model', 'app'];
1467
+ }
1468
+ /** MCP Apps: visibility and the UI a tool names. */
1469
+ function compareApps(old, t) {
1470
+ const out = [];
1471
+ const name = t.name;
1472
+ const a = seenBy(old);
1473
+ const b = seenBy(t);
1474
+ const pair = `${show(a)} → ${show(b)}`;
1475
+ if (a.includes('model') && !b.includes('model')) {
1476
+ out.push({
1477
+ rule: 'diff/apps-visibility',
1478
+ tool: name,
1479
+ message: `${code(name)} is no longer shown to the agent (MCP Apps visibility ${pair}). An Apps host leaves it out of the agent's tool list, so agents, saved prompts and evals that call it now fail there.`,
1480
+ fix: `Keep "model" in ${code(name)}'s visibility for one release, or ${BREAKING_RELEASE}.`,
1481
+ across: { key: `apps-visibility\u0000${pair}`, say: (count, list) => `${count[0].toUpperCase()}${count.slice(1)} are no longer shown to the agent (MCP Apps visibility ${pair}): ${list}. An Apps host leaves them out of the agent's tool list, so calls to them from agents, saved prompts and evals now fail there.` },
1482
+ });
1483
+ }
1484
+ else if (!a.includes('model') && b.includes('model')) {
1485
+ out.push({
1486
+ rule: 'diff/apps-visible',
1487
+ tool: name,
1488
+ message: `${code(name)} is now shown to the agent (MCP Apps visibility ${pair}, ~${fmt(t.tokens)} tokens, estimate).`,
1489
+ });
1490
+ }
1491
+ else if (canonical(a) !== canonical(b)) {
1492
+ out.push({ rule: 'diff/apps-ui', tool: name, message: `${code(name)}: MCP Apps visibility ${pair}. The agent sees it as before; ${b.includes('app') ? 'the app can now call it' : 'the app can no longer call it'}.` });
1493
+ }
1494
+ const ua = resourceUriOf(old);
1495
+ const ub = resourceUriOf(t);
1496
+ if (ua !== ub) {
1497
+ const what = ua === undefined ? `now names a UI (${ub})` : ub === undefined ? `no longer names a UI (was ${ua})` : `names another UI (${ua} → ${ub})`;
1498
+ out.push({
1499
+ rule: 'diff/apps-ui',
1500
+ tool: name,
1501
+ message: `${code(name)} ${what}. What an MCP Apps host renders for it changes; calls don't.`,
1502
+ across: { key: `apps-ui\u0000${ua === undefined ? 'added' : ub === undefined ? 'removed' : 'moved'}`, say: (count, list) => `${count[0].toUpperCase()}${count.slice(1)} ${ua === undefined ? 'now name a UI' : ub === undefined ? 'no longer name a UI' : 'name another UI'}: ${list}. What an MCP Apps host renders for them changes; calls don't.` },
1503
+ });
1504
+ }
1505
+ return out;
1506
+ }
1507
+ /** capabilities.extensions, compared. Menu files from before 0.23 didn't record them: not compared. */
1508
+ function compareExtensions(before, after) {
1509
+ const a = before.server.extensions;
1510
+ const b = after.server.extensions;
1511
+ if (!a || !b)
1512
+ return [];
1513
+ const out = [];
1514
+ for (const id of Object.keys(a)) {
1515
+ if (!(id in b)) {
1516
+ out.push({
1517
+ rule: 'diff/extension-removed',
1518
+ message: `The server no longer declares the ${code(id)} extension. Clients stop using what it adds${EXTENSION_USE[id] ? ` (${EXTENSION_USE[id]})` : ''}; core requests go on working.`,
1519
+ fix: `If it was dropped by mistake, declare ${code(id)} again; if on purpose, say so in the release notes, or ${BREAKING_RELEASE}.`,
1520
+ });
1521
+ }
1522
+ else if (canonical(a[id]) !== canonical(b[id])) {
1523
+ out.push({ rule: 'diff/extension-settings', message: `The ${code(id)} extension's settings changed (${show(a[id])} → ${show(b[id])}).` });
1524
+ }
1525
+ }
1526
+ for (const id of Object.keys(b))
1527
+ if (!(id in a))
1528
+ out.push({ rule: 'diff/extension-added', message: `The server now declares the ${code(id)} extension.` });
1529
+ return out;
1530
+ }
1531
+ /** What clients lose with an official extension, for the message. */
1532
+ const EXTENSION_USE = {
1533
+ 'io.modelcontextprotocol/ui': 'MCP Apps: the UI of tools that name one',
1534
+ 'io.modelcontextprotocol/tasks': 'Tasks: long-running calls answered with a task to poll',
1535
+ };
1428
1536
  function readOnly(a) {
1429
1537
  return a.readOnlyHint === true;
1430
1538
  }
@@ -73,14 +73,27 @@ export declare function setupFailureAdvice(classes: Iterable<FailureClass>, tran
73
73
  fix: string;
74
74
  confidence: 'unsure';
75
75
  };
76
+ /** An HTTP error passed on as a tool's answer: what it said. */
77
+ export interface StructuredError {
78
+ status?: number;
79
+ code?: string;
80
+ message?: string;
81
+ /** 401 or 403, or a code that says the credentials were refused. */
82
+ auth: boolean;
83
+ /** "HTTP 401: …", for a message. */
84
+ said: string;
85
+ }
76
86
  /**
77
- * A result not marked isError whose content is an HTTP auth error in structured form:
78
- * the API the tool calls said 401 or 403 and the server passed the body on as an
87
+ * A result not marked isError whose content is an HTTP error in structured form: the
88
+ * API the tool calls answered 4xx or 5xx and the server passed the body on as an
79
89
  * answer. Notion's server returns `{"status":401,"object":"error","code":"unauthorized"}`
80
90
  * as a plain result. Only a JSON object whose own status or code says so counts, not
81
- * "401" anywhere in the data. Says what it saw, or undefined.
91
+ * "401" anywhere in the data, and a status needs a sign that the object is an error
92
+ * (`object: "error"`, an `error` field, a `message`, or sitting under `error`): a
93
+ * status alone may be what the tool was asked about. (A tool that fetches a URL is
94
+ * skipped by the caller: its answer is the page's.)
82
95
  */
83
- export declare function deniedAnswer(result: {
96
+ export declare function structuredError(result: {
84
97
  content?: unknown;
85
98
  structuredContent?: unknown;
86
- }): string | undefined;
99
+ }): StructuredError | undefined;
package/dist/failures.js CHANGED
@@ -207,21 +207,23 @@ export function setupFailureAdvice(classes, transport) {
207
207
  if (set.has('environment'))
208
208
  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.');
209
209
  if (set.has('client'))
210
- steps.push("If a tool needs a client capability toolmenu doesn't declare (roots and sampling, which 2026-07-28 deprecates, or one the error names), those calls only checked that the menu stays put, and the server isn't at fault.");
210
+ steps.push("If a tool needs a client capability toolmenu doesn't declare (roots and sampling, which 2026-07-28 deprecates, the Tasks extension, or one the error names), those calls only checked that the menu stays put, and the server isn't at fault.");
211
211
  if (set.has('network'))
212
212
  steps.push('If the server calls an upstream API, check this machine can reach it (DNS, proxy, firewall).');
213
213
  return { fix: steps.join(' ') || 'Check the quoted errors: they came from before the tool ran.', confidence: 'unsure' };
214
214
  }
215
215
  const DENIED_CODES = /^(?:unauthori[sz]ed|unauthenticated|forbidden|invalid_auth|invalid_token|not_authed|authentication_(?:required|failed)|permission_denied)$/i;
216
216
  /**
217
- * A result not marked isError whose content is an HTTP auth error in structured form:
218
- * the API the tool calls said 401 or 403 and the server passed the body on as an
217
+ * A result not marked isError whose content is an HTTP error in structured form: the
218
+ * API the tool calls answered 4xx or 5xx and the server passed the body on as an
219
219
  * answer. Notion's server returns `{"status":401,"object":"error","code":"unauthorized"}`
220
220
  * as a plain result. Only a JSON object whose own status or code says so counts, not
221
- * "401" anywhere in the data. Says what it saw, or undefined.
221
+ * "401" anywhere in the data, and a status needs a sign that the object is an error
222
+ * (`object: "error"`, an `error` field, a `message`, or sitting under `error`): a
223
+ * status alone may be what the tool was asked about. (A tool that fetches a URL is
224
+ * skipped by the caller: its answer is the page's.)
222
225
  */
223
- export function deniedAnswer(result) {
224
- // (A tool that fetches a URL is skipped by the caller: its answer is the page's.)
226
+ export function structuredError(result) {
225
227
  const objects = [result.structuredContent];
226
228
  for (const c of Array.isArray(result.content) ? result.content : []) {
227
229
  const text = c && typeof c === 'object' && 'text' in c && typeof c.text === 'string' ? c.text.trim() : '';
@@ -234,6 +236,11 @@ export function deniedAnswer(result) {
234
236
  // not JSON
235
237
  }
236
238
  }
239
+ const errorStatus = (x) => {
240
+ const n = typeof x === 'number' ? x : typeof x === 'string' && /^\d{3}$/.test(x) ? Number(x) : NaN;
241
+ return n >= 400 && n <= 599 ? n : undefined;
242
+ };
243
+ let first;
237
244
  for (const o of objects) {
238
245
  if (!o || typeof o !== 'object' || Array.isArray(o))
239
246
  continue;
@@ -241,16 +248,24 @@ export function deniedAnswer(result) {
241
248
  if (!v || typeof v !== 'object' || Array.isArray(v))
242
249
  continue;
243
250
  const r = v;
244
- const status = [r.status, r.statusCode, r.status_code, r.code].find((x) => x === 401 || x === 403 || x === '401' || x === '403');
251
+ const status = [r.status, r.statusCode, r.status_code, r.code].map(errorStatus).find((x) => x !== undefined);
245
252
  const code = [r.code, r.error, r.type].find((x) => typeof x === 'string' && DENIED_CODES.test(x));
246
- // A status alone may be what the tool was asked to fetch ({"status":403,"body":…});
247
- // with it, the object has to say it's an error.
248
253
  const isError = v !== o || r.object === 'error' || ![undefined, null, false, '', 0].includes(r.error) || typeof r.message === 'string';
249
254
  if (code === undefined && (status === undefined || !isError))
250
255
  continue;
251
- const message = typeof r.message === 'string' ? `: ${r.message}` : '';
252
- return `${status !== undefined ? `HTTP ${status}` : String(code)}${message}`;
256
+ const message = typeof r.message === 'string' ? r.message : undefined;
257
+ const found = {
258
+ ...(status !== undefined ? { status } : {}),
259
+ ...(code !== undefined ? { code } : {}),
260
+ ...(message !== undefined ? { message } : {}),
261
+ auth: code !== undefined || status === 401 || status === 403,
262
+ said: `${status !== undefined ? `HTTP ${status}` : code}${message ? `: ${message}` : ''}`,
263
+ };
264
+ // An auth error anywhere wins: a 502 around a nested 401 is still the credentials.
265
+ if (found.auth)
266
+ return found;
267
+ first ??= found;
253
268
  }
254
269
  }
255
- return undefined;
270
+ return first;
256
271
  }
package/dist/help.js CHANGED
@@ -53,6 +53,7 @@ const OPTIONS = {
53
53
  'init-out': ['--out <path>', ['where to write the baseline menu (default: menu.json)']],
54
54
  'with-session': ['--with-session', ['the workflow also runs session --auto (calls read-only tools)']],
55
55
  port: ['--port <n>', ['loopback port for the login redirect (default: 33418)']],
56
+ 'offline-check': ['--offline-check', ['stdio: list the menu once more with the network cut off (the proxy variables', 'pointed at a closed port): a server whose menu depends on what it fetches at start']],
56
57
  concurrency: ['--concurrency <n>', ['servers checked at a time (default: 4)']],
57
58
  'out-dir': ['--out-dir <dir>', ["write each server's menu file there, as <name>.json (default: none)"]],
58
59
  'no-browser': ['--no-browser', ["don't open a browser: print the login URL, open it on any device, and paste", 'back the address the browser ends on (over SSH, in a container, on a remote box)']],
@@ -84,7 +85,7 @@ const HELP = {
84
85
  'reports what in the menu confuses agents or breaks prompt caches.',
85
86
  SERVER_NOTE,
86
87
  ],
87
- own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists'],
88
+ own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists', 'offline-check'],
88
89
  shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
89
90
  examples: [
90
91
  'toolmenu snapshot -- npx -y @modelcontextprotocol/server-memory',
@@ -168,7 +169,7 @@ const HELP = {
168
169
  'started or read is a row that says why, and makes the exit code 2: it was not checked.',
169
170
  ],
170
171
  own: ['concurrency', 'out-dir'],
171
- shared: ['config', 'format', 'json', 'fail-on', 'protocol', 'timeout', 'processes'],
172
+ shared: ['config', 'format', 'json', 'fail-on', 'no-auth', 'protocol', 'timeout', 'processes'],
172
173
  examples: ['toolmenu scan ~/Library/Application\\ Support/Claude/claude_desktop_config.json', 'toolmenu scan .mcp.json --format markdown', 'toolmenu scan servers.txt --concurrency 8 --out-dir menus'],
173
174
  exits: ['0 every server checked, no findings at or above --fail-on', '1 findings at or above --fail-on', "2 a server wasn't checked (couldn't start, couldn't connect, a variable not set), or bad usage"],
174
175
  },
package/dist/mrtr.d.ts CHANGED
@@ -20,7 +20,7 @@ export interface InputTrace {
20
20
  * bad-state: its requestState isn't a string, so it can't be echoed byte for byte;
21
21
  * calling again without it would run the tool again from scratch.
22
22
  */
23
- outcome: 'none' | 'completed' | 'loop' | 'gave-up' | 'unfinished' | 'undeclared' | 'decline-failed' | 'bad-state';
23
+ outcome: 'none' | 'completed' | 'loop' | 'gave-up' | 'unfinished' | 'undeclared' | 'decline-failed' | 'bad-state' | 'task';
24
24
  /** Kinds asked for that the request didn't declare. */
25
25
  undeclared?: InputKind[];
26
26
  /** The protocol error a retry failed with (decline-failed): the server's words, and its JSON-RPC code. */
@@ -32,6 +32,14 @@ export interface InputTrace {
32
32
  continuations?: number;
33
33
  /** A raw result on the wire without resultType, which 2026-07-28 servers MUST send. */
34
34
  missingResultType?: boolean;
35
+ /**
36
+ * task: the server answered with a CreateTaskResult (resultType "task", ext-tasks),
37
+ * which it MUST NOT send to a client that didn't declare io.modelcontextprotocol/tasks.
38
+ */
39
+ task?: {
40
+ taskId?: string;
41
+ status?: string;
42
+ };
35
43
  }
36
44
  type CallResult = Awaited<ReturnType<Connection['client']['callTool']>>;
37
45
  /**
package/dist/mrtr.js CHANGED
@@ -13,6 +13,16 @@ import { httpStatus, tooMany } from './failures.js';
13
13
  export const MAX_ROUNDS = 3;
14
14
  /** Rounds that carry only requestState (the tool keeps working, asks nothing) before toolmenu stops. */
15
15
  export const MAX_CONTINUATIONS = 10;
16
+ /** A CreateTaskResult (ext-tasks): resultType "task", with the task's id and status. */
17
+ function taskOf(result) {
18
+ if (!isObject(result) || result.resultType !== 'task')
19
+ return undefined;
20
+ const task = isObject(result.task) ? result.task : result;
21
+ return {
22
+ ...(typeof task.taskId === 'string' ? { taskId: task.taskId } : {}),
23
+ ...(typeof task.status === 'string' ? { status: task.status } : {}),
24
+ };
25
+ }
16
26
  const DECLARED = new Set(['form', 'url']);
17
27
  function kindOf(request) {
18
28
  if (request.method === 'elicitation/create')
@@ -100,6 +110,10 @@ export async function callWithInput(conn, params, options) {
100
110
  // What the server sent decides what failed, not the error the SDK raised.
101
111
  const wire = conn.wire.since(mark, 'tools/call').at(-1);
102
112
  const answered = wire?.result;
113
+ // A task handle toolmenu didn't ask for (it declares no Tasks support): nothing to poll.
114
+ const task = taskOf(answered);
115
+ if (task)
116
+ return { input: trace('task', { task }) };
103
117
  if (isObject(answered) && !('resultType' in answered)) {
104
118
  // No resultType: the SDK client rejects it ("missing required resultType").
105
119
  // The server did answer; session/result-type says why clients won't take it.
@@ -126,6 +140,9 @@ export async function callWithInput(conn, params, options) {
126
140
  return { input: trace('decline-failed', { error: { message: firstLine(wire.error.message ?? error), ...(typeof code === 'number' ? { code } : {}) } }) };
127
141
  }
128
142
  }
143
+ const task = taskOf(conn.wire.since(mark, 'tools/call').at(-1)?.result ?? result);
144
+ if (task)
145
+ return { input: trace('task', { task }) };
129
146
  if (result.resultType !== 'input_required')
130
147
  return { result: result, input: trace(finished()) };
131
148
  const required = result;
package/dist/options.d.ts CHANGED
@@ -5,6 +5,9 @@ export declare const CLI_OPTIONS: {
5
5
  readonly 'out-dir': {
6
6
  readonly type: 'string';
7
7
  };
8
+ readonly 'offline-check': {
9
+ readonly type: 'boolean';
10
+ };
8
11
  readonly concurrency: {
9
12
  readonly type: 'string';
10
13
  };
package/dist/options.js CHANGED
@@ -5,6 +5,7 @@
5
5
  export const CLI_OPTIONS = {
6
6
  out: { type: 'string' },
7
7
  'out-dir': { type: 'string' },
8
+ 'offline-check': { type: 'boolean' },
8
9
  concurrency: { type: 'string' },
9
10
  'no-write': { type: 'boolean' },
10
11
  routes: { type: 'string' },
package/dist/probe.d.ts CHANGED
@@ -44,4 +44,14 @@ export declare function probeMenu(target: Target, timeoutMs: number, waits?: num
44
44
  * HTTP probe that differs is retried once: a rolling deploy can serve two
45
45
  * versions for a moment.
46
46
  */
47
- export declare function probeVariance(target: Target, main: MenuTool[], processes: number, timeoutMs: number, waits?: number[]): Promise<Probe[]>;
47
+ /**
48
+ * probeMenu, on the protocol an earlier connection got. Negotiated as usual (so errors
49
+ * read as they always have); only a probe that ends on the other protocol is asked
50
+ * again, pinned to that one. Under load a version probe can time out and fall back to
51
+ * 2025 in one process only, and a menu from another protocol differs in ways no
52
+ * client sees (mastra's $schema): a false variance (the 0.22 corpus run).
53
+ */
54
+ export declare function probeSameEra(target: Target, era: string | undefined, timeoutMs: number, waits?: number[], waited?: {
55
+ ms: number;
56
+ }, seen?: Set<string>): Promise<Menu>;
57
+ export declare function probeVariance(target: Target, main: MenuTool[], processes: number, timeoutMs: number, waits?: number[], era?: string, seen?: Set<string>): Promise<Probe[]>;
package/dist/probe.js CHANGED
@@ -75,15 +75,30 @@ export async function probeMenu(target, timeoutMs, waits, waited) {
75
75
  * HTTP probe that differs is retried once: a rolling deploy can serve two
76
76
  * versions for a moment.
77
77
  */
78
- export async function probeVariance(target, main, processes, timeoutMs, waits) {
78
+ /**
79
+ * probeMenu, on the protocol an earlier connection got. Negotiated as usual (so errors
80
+ * read as they always have); only a probe that ends on the other protocol is asked
81
+ * again, pinned to that one. Under load a version probe can time out and fall back to
82
+ * 2025 in one process only, and a menu from another protocol differs in ways no
83
+ * client sees (mastra's $schema): a false variance (the 0.22 corpus run).
84
+ */
85
+ export async function probeSameEra(target, era, timeoutMs, waits, waited, seen) {
86
+ const m = await probeMenu(target, timeoutMs, waits, waited);
87
+ if (m.server.era)
88
+ seen?.add(m.server.era);
89
+ if (!era || target.protocol || m.server.era === era)
90
+ return m;
91
+ return probeMenu({ ...target, protocol: era === 'modern' ? 'modern' : 'legacy' }, timeoutMs, waits, waited);
92
+ }
93
+ export async function probeVariance(target, main, processes, timeoutMs, waits, era, seen) {
79
94
  const probes = [];
80
95
  for (let i = 0; i < processes - 1; i++) {
81
96
  const seed = String(Number(PROBE_SEED) + i);
82
97
  const waited = { ms: 0 };
83
98
  try {
84
- let tools = (await probeMenu(seeded(target, seed), timeoutMs, waits, waited)).tools;
99
+ let tools = (await probeSameEra(seeded(target, seed), era, timeoutMs, waits, waited, seen)).tools;
85
100
  if (target.kind === 'http' && compareMenus(main, tools).length)
86
- tools = (await probeMenu(target, timeoutMs, waits, waited)).tools;
101
+ tools = (await probeSameEra(target, era, timeoutMs, waits, waited)).tools;
87
102
  probes.push({ tools });
88
103
  }
89
104
  catch (error) {
package/dist/report.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { agentMenu } from './apps.js';
1
2
  import { clip, stepLabel, stepsText } from './session.js';
2
3
  import { SEVERITY_RANK } from './types.js';
3
4
  import { breakdown, breakdownLines, breakdownMarkdown } from './breakdown.js';
@@ -28,7 +29,12 @@ function costLine(cost) {
28
29
  ].filter(Boolean);
29
30
  return `as ${cost.label}: ${parts.join(' · ')}`;
30
31
  }
32
+ /** " · 2 not shown to the agent (MCP Apps visibility without "model", ~60 tokens)", or nothing. */
33
+ function appOnlyNote(a) {
34
+ return a ? ` · ${a.tools} not shown to the agent (MCP Apps visibility without "model", ~${a.tokens.toLocaleString('en-US')} tokens)` : '';
35
+ }
31
36
  export function formatSnapshot(menu, findings, format, outPath, cost, notOffered = []) {
37
+ const view = agentMenu(menu);
32
38
  if (format === 'json') {
33
39
  return JSON.stringify({
34
40
  command: 'snapshot',
@@ -36,7 +42,8 @@ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered
36
42
  tools: menu.tools.length,
37
43
  totalTokens: menu.totalTokens,
38
44
  listMeta: menu.listMeta,
39
- breakdown: breakdown(menu),
45
+ ...(view.appOnly ? { appOnly: view.appOnly } : {}),
46
+ breakdown: breakdown(view.shown),
40
47
  ...(cost ? { client: cost } : {}),
41
48
  ...(menu.prompts ? { prompts: menu.prompts.length } : {}),
42
49
  ...(menu.resources ? { resources: menu.resources.length } : {}),
@@ -54,18 +61,18 @@ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered
54
61
  return [
55
62
  `### toolmenu snapshot: \`${s.name ?? 'server'}\` ${s.version ?? ''}`.trimEnd(),
56
63
  '',
57
- `Protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)`,
64
+ `Protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)${appOnlyNote(view.appOnly)}`,
58
65
  ...(cost ? ['', `${costLine(cost)}. _${cost.basis}._`] : []),
59
66
  ...(otherLists(menu) ? ['', `Also listed: ${otherLists(menu)}`] : []),
60
67
  '',
61
68
  ...mdFindings(findings),
62
- ...mdBreakdown(menu),
69
+ ...mdBreakdown(view.shown),
63
70
  ].join('\n');
64
71
  }
65
72
  const s = menu.server;
66
73
  const lines = [
67
74
  `toolmenu snapshot ${s.name ?? 'unknown server'} ${s.version ?? ''}`.trimEnd(),
68
- ` protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)`,
75
+ ` protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)${appOnlyNote(view.appOnly)}`,
69
76
  ];
70
77
  if (cost)
71
78
  lines.push(` ${costLine(cost)}`, ` ${cost.basis}`);
@@ -77,7 +84,7 @@ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered
77
84
  if (outPath)
78
85
  lines.push(` wrote ${outPath}`);
79
86
  lines.push('');
80
- const where = breakdownLines(breakdown(menu), menu.tools.length);
87
+ const where = breakdownLines(breakdown(view.shown), view.shown.tools.length);
81
88
  if (where.length)
82
89
  lines.push(...where, '');
83
90
  lines.push(...findingLines(findings));