toolmenu 0.27.1 → 0.28.1

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
@@ -131,7 +131,7 @@ jobs:
131
131
  - uses: actions/setup-node@v7
132
132
  with: { node-version: 22 }
133
133
  - run: npm ci && npm run build
134
- - uses: niksa90/toolmenu@v0.27.1
134
+ - uses: niksa90/toolmenu@v0.28.1
135
135
  with:
136
136
  command: node dist/server.js
137
137
  baseline: menu.json # your committed snapshot
package/dist/apps.d.ts CHANGED
@@ -40,6 +40,10 @@ export interface AppResource {
40
40
  tools: string[];
41
41
  /** resources/read failed: the error's first line. */
42
42
  error?: string;
43
+ /** The JSON-RPC error code it failed with, when there was one. */
44
+ code?: number;
45
+ /** It wasn't read: the reads together ran out of time. */
46
+ notRead?: boolean;
43
47
  /** Each content item's mimeType, in order ("" when absent). */
44
48
  mimeTypes?: string[];
45
49
  /** Some content item for this URI carries text or a blob. */
package/dist/apps.js CHANGED
@@ -70,7 +70,7 @@ export async function readAppResources(connection, tools, timeoutMs = 30_000, li
70
70
  const left = deadline - Date.now();
71
71
  // A read given a few milliseconds can only time out: past the deadline in all but name.
72
72
  if (left < MIN_READ_MS) {
73
- out[i] = { uri, tools: names, error: `not read: the reads took longer than ${Math.round((2 * timeoutMs) / 1000)} s in all` };
73
+ out[i] = { uri, tools: names, notRead: true, error: `not read: the reads took longer than ${Math.round((2 * timeoutMs) / 1000)} s in all` };
74
74
  return;
75
75
  }
76
76
  try {
@@ -85,7 +85,8 @@ export async function readAppResources(connection, tools, timeoutMs = 30_000, li
85
85
  };
86
86
  }
87
87
  catch (error) {
88
- out[i] = { uri, tools: names, error: (error instanceof Error ? error.message : String(error)).split('\n')[0].trim() };
88
+ const code = error?.code;
89
+ out[i] = { uri, tools: names, error: (error instanceof Error ? error.message : String(error)).split('\n')[0].trim(), ...(typeof code === 'number' ? { code } : {}) };
89
90
  }
90
91
  };
91
92
  let next = 0;
package/dist/auth.d.ts CHANGED
@@ -90,6 +90,7 @@ export declare function pastedRedirect(text: string): URLSearchParams | undefine
90
90
  export declare function login(serverUrl: string, options?: LoginOptions): Promise<{
91
91
  name?: string;
92
92
  tools: number;
93
+ authenticated: boolean;
93
94
  }>;
94
95
  export declare function logout(serverUrl: string): Promise<boolean>;
95
96
  /** Stored logins: the server, its issuer, and when the tokens were saved. No secrets. */
package/dist/auth.js CHANGED
@@ -281,6 +281,8 @@ function printForPaste(port) {
281
281
  */
282
282
  export async function login(serverUrl, options = {}) {
283
283
  const port = options.port ?? DEFAULT_PORT;
284
+ // What was stored before this login (a registered client, a rejected token) is kept.
285
+ const stored = hasLogin(serverUrl);
284
286
  const callback = await listenForCallback(port, options.timeoutMs ?? 300_000);
285
287
  try {
286
288
  const provider = new StoredOAuthProvider(serverUrl, {
@@ -338,7 +340,13 @@ export async function login(serverUrl, options = {}) {
338
340
  await transport.finishAuth(params);
339
341
  await endSession(client, transport);
340
342
  }
341
- return await check(serverUrl);
343
+ // A server that never asked for credentials leaves nothing to log in with: the
344
+ // file the discovery step wrote holds no token, so drop it rather than list a login.
345
+ // A file from before this login stays: it may hold a registered client.
346
+ const authenticated = Boolean(await provider.tokens());
347
+ if (!authenticated && !stored)
348
+ await logout(serverUrl);
349
+ return { ...(await check(serverUrl)), authenticated };
342
350
  }
343
351
  catch (error) {
344
352
  // GitHub's hosted server, for one: no dynamic registration, so toolmenu can't
package/dist/cli.js CHANGED
@@ -203,6 +203,17 @@ export async function main(given) {
203
203
  const badList = (lists ?? []).find((w) => !LIST_WORDS.includes(w));
204
204
  if (badList)
205
205
  throw new UsageError(`--lists takes ${LIST_WORDS.join(', ')}, comma-separated; not "${badList}"`);
206
+ if ((values['read-resources'] || values['max-reads'] !== undefined) && sub !== 'snapshot')
207
+ throw new UsageError('--read-resources and --max-reads go with snapshot.');
208
+ const readResources = sub === 'snapshot' && (values['read-resources'] ?? config.readResources ?? false);
209
+ if (readResources && !(lists ?? []).includes('resources')) {
210
+ throw new UsageError(`${values['read-resources'] ? '--read-resources' : 'readResources (in the config)'} reads what resources/list names, so it needs that list.\n → Next: add --lists resources (or "lists": ["resources"] in the config).`);
211
+ }
212
+ if (values['max-reads'] !== undefined && !readResources)
213
+ throw new UsageError('--max-reads goes with --read-resources.');
214
+ const maxReads = values['max-reads'] !== undefined ? Number(values['max-reads']) : config.maxReads;
215
+ if (maxReads !== undefined && !(Number.isInteger(maxReads) && maxReads >= 1))
216
+ throw new UsageError('--max-reads must be a whole number, 1 or more');
206
217
  if (values.client !== undefined && sub !== 'snapshot')
207
218
  throw new UsageError('--client goes with snapshot.');
208
219
  if (values.client !== undefined && !Object.hasOwn(CLIENTS, values.client))
@@ -509,11 +520,11 @@ export async function main(given) {
509
520
  const offlineCheck = values['offline-check'] ?? config.offlineCheck;
510
521
  if (values['offline-check'] && target.kind !== 'stdio')
511
522
  throw new UsageError("--offline-check goes with a stdio server: an HTTP server's network isn't this machine's to cut.");
512
- const { menu, findings, cost, notOffered } = await snapshot(target, { offlineCheck: offlineCheck && target.kind === 'stdio', routes, timeoutMs, processes, identities, client, lists, catalog: values.catalog ? (config.catalog ?? true) : undefined, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
523
+ const { menu, findings, cost, notOffered, resourcesRead } = await snapshot(target, { readResources, maxReads, offlineCheck: offlineCheck && target.kind === 'stdio', routes, timeoutMs, processes, identities, client, lists, catalog: values.catalog ? (config.catalog ?? true) : undefined, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
513
524
  const outPath = values['no-write'] ? undefined : values.out ?? 'menu.json';
514
525
  if (outPath)
515
526
  await writeFile(outPath, JSON.stringify(menu, null, 2) + '\n');
516
- await emit(formatSnapshot(menu, findings, format, outPath, cost, notOffered), findings, 'snapshot', outPath, () => snapshotHtml(menu, findings, { transport: target.kind, cost, notOffered, outPath }));
527
+ await emit(formatSnapshot(menu, findings, format, outPath, cost, notOffered, resourcesRead), findings, 'snapshot', outPath, () => snapshotHtml(menu, findings, { transport: target.kind, cost, notOffered, outPath }));
517
528
  if (values.badge !== undefined) {
518
529
  await writeFile(values.badge, JSON.stringify(badge(menu, findings), null, 2) + '\n');
519
530
  // stderr: stdout stays the report (or the JSON/SARIF a script parses).
@@ -564,7 +575,11 @@ async function authCommand(args, values) {
564
575
  if (values['client-secret'] && !values['client-id'])
565
576
  throw new UsageError('--client-secret goes with --client-id');
566
577
  const result = await login(url, { port, scope: values.scope, clientId: values['client-id'], clientSecret: values['client-secret'], noBrowser: values['no-browser'] });
567
- process.stdout.write(`Logged in to ${plain(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`);
578
+ const count = `${result.tools} tool${result.tools === 1 ? '' : 's'}`;
579
+ process.stdout.write(result.authenticated
580
+ ? `Logged in to ${plain(result.name ?? url)} (${url}): it lists ${count} with this login.\nsnapshot and session use it from now on (--no-auth to skip it); stored in ${authDir()}.\n`
581
+ : `No login made for ${plain(result.name ?? url)} (${url}): it listed ${count} without asking for credentials, so nothing was stored.\n` +
582
+ `→ Next: A server like this usually asks for a login only when a tool is called. If session reports session/untested, pass a token with --header "Authorization: Bearer <token>".\n`);
568
583
  return 0;
569
584
  }
570
585
  /**
package/dist/config.d.ts CHANGED
@@ -28,6 +28,10 @@ export interface Config {
28
28
  }>;
29
29
  /** snapshot: which lists to read besides tools: ["prompts", "resources"]. --lists wins. */
30
30
  lists?: string[];
31
+ /** snapshot: also read each listed resource (needs "resources" in lists). --read-resources turns it on too. */
32
+ readResources?: boolean;
33
+ /** snapshot: with readResources, read at most this many. --max-reads wins. */
34
+ maxReads?: number;
31
35
  /** snapshot: the client to check the menu for (claude-code, claude-api-search, openai). --client wins. */
32
36
  client?: string;
33
37
  /** snapshot (stdio): also list the menu with the network cut off. --offline-check turns it on too. */
package/dist/config.js CHANGED
@@ -40,6 +40,10 @@ export async function loadConfig(path) {
40
40
  if (config.lists !== undefined && !(Array.isArray(config.lists) && config.lists.every((l) => LIST_WORDS.includes(l)))) {
41
41
  throw new Error(`${file}: lists must be a list of ${LIST_WORDS.join(', ')}`);
42
42
  }
43
+ if (config.readResources !== undefined && typeof config.readResources !== 'boolean')
44
+ throw new Error(`${file}: readResources must be true or false`);
45
+ if (config.maxReads !== undefined && !(Number.isInteger(config.maxReads) && config.maxReads >= 1))
46
+ throw new Error(`${file}: maxReads must be a whole number, 1 or more`);
43
47
  if (config.offlineCheck !== undefined && typeof config.offlineCheck !== 'boolean')
44
48
  throw new Error(`${file}: offlineCheck must be true or false`);
45
49
  if (config.client !== undefined && !(typeof config.client === 'string' && Object.hasOwn(CLIENTS, config.client))) {
package/dist/connect.d.ts CHANGED
@@ -37,6 +37,8 @@ export interface WireResponse {
37
37
  code: number;
38
38
  message: string;
39
39
  };
40
+ /** The `uri` the request named (resources/read): which read an answer is to, when one comes late. */
41
+ uri?: string;
40
42
  }
41
43
  /** Every response the server sent, matched to the request method, as it came off the wire. */
42
44
  export declare class WireLog {
package/dist/connect.js CHANGED
@@ -62,7 +62,8 @@ export class WireLog {
62
62
  const send = transport.send.bind(transport);
63
63
  transport.send = (message, options) => {
64
64
  if ('method' in message && 'id' in message && message.id !== undefined) {
65
- this.pending.set(message.id, message.method);
65
+ const uri = message.params?.uri;
66
+ this.pending.set(message.id, { method: message.method, ...(typeof uri === 'string' ? { uri } : {}) });
66
67
  }
67
68
  return send(message, options);
68
69
  };
@@ -72,11 +73,12 @@ export class WireLog {
72
73
  this.notifications.push(message.method);
73
74
  }
74
75
  if (!('method' in message) && 'id' in message && message.id !== undefined) {
75
- const method = this.pending.get(message.id);
76
- if (method) {
76
+ const sent = this.pending.get(message.id);
77
+ if (sent) {
77
78
  this.pending.delete(message.id);
78
79
  this.responses.push({
79
- method,
80
+ method: sent.method,
81
+ ...(sent.uri !== undefined ? { uri: sent.uri } : {}),
80
82
  ...('result' in message ? { result: message.result } : {}),
81
83
  ...('error' in message ? { error: message.error } : {}),
82
84
  });
@@ -180,6 +182,27 @@ export async function connect(target, options = {}) {
180
182
  await stderrEnded(stdioStderr, trace.exit ? STDERR_AFTER_EXIT_MS : 1000);
181
183
  }
182
184
  await endSession(client, transport);
185
+ // A 401 or 403 to server/discover alone isn't the server's last word: Dreamwork
186
+ // 1.10.0 answers it with a 401 while its 2025 handshake serves a guest menu. With
187
+ // the handshake left to toolmenu, and no stored login (a refused one is reported as
188
+ // such), try the 2025 one before calling it a login wall. A server that wants
189
+ // credentials refuses that too; one that fails it any other way (a 2026-only
190
+ // server) is reported with the first refusal, which is the one that explains it.
191
+ const discover = trace.http.get('server/discover')?.status;
192
+ if (target.kind === 'http' &&
193
+ !oauth &&
194
+ (!target.protocol || target.protocol === 'auto') &&
195
+ (discover === 401 || discover === 403) &&
196
+ !trace.sent.some((s) => s.method === 'initialize')) {
197
+ const refused = explain(error, trace, context);
198
+ try {
199
+ return await connect({ ...target, protocol: 'legacy' }, options);
200
+ }
201
+ catch (retry) {
202
+ const status = retry.status;
203
+ throw status === 401 || status === 403 ? retry : refused;
204
+ }
205
+ }
183
206
  throw explain(error, trace, context);
184
207
  }
185
208
  const wire = new WireLog();
package/dist/help.js CHANGED
@@ -25,6 +25,8 @@ const OPTIONS = {
25
25
  protocol: ['--protocol <auto|legacy|modern>', ['which handshake to make (default: auto)', 'legacy: the 2025 handshake only; modern: 2026-07-28 only, an error if the server lacks it']],
26
26
  as: ['--as <name>[:<credential>]', ['list the menu as this identity too, repeatable: a header ("reader:Authorization:', 'Bearer ...") or env var ("admin:ROLE=admin") on top of --header/--env. The first', 'is the main one (its menu is saved); the others are compared with it']],
27
27
  lists: ['--lists <kinds>', ['which lists to read and check, comma-separated: tools (always),', 'prompts, resources (resources/list and resources/templates/list).', 'Saved in the menu file beside the tools']],
28
+ 'read-resources': ['--read-resources', ['with --lists resources: read each listed resource (resources/read) and report', 'the ones a client gets nothing usable from. Templates are not read; no', 'content is kept. On a hosted server this fetches every resource it lists']],
29
+ 'max-reads': ['--max-reads <n>', ['with --read-resources, read at most n resources, spread over the list', '(default: all of them, within 120 s)']],
28
30
  client: ['--client <name>', ['check the menu for one client, from its own docs: claude-code (tools deferred,', 'its description cut and search), claude-api-search (Claude API tool search),', 'openai (Responses API tool_search), codex, antigravity (lazy tools), gemini-cli', '(renames), gemini-api, vscode (128 tools a request), copilot-cloud-agent and', 'copilot-code-review (tools only; review: read-only tools only)']],
29
31
  'no-auth': ['--no-auth', ["don't use a stored OAuth login (toolmenu auth login) for this server"]],
30
32
  timeout: ['--timeout <ms>', ['per-request timeout (default: 30000)']],
@@ -92,7 +94,7 @@ const HELP = {
92
94
  'reports what in the menu confuses agents or breaks prompt caches.',
93
95
  SERVER_NOTE,
94
96
  ],
95
- own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists', 'offline-check', 'sarif', 'sarif-menu', 'junit', 'html', 'badge'],
97
+ own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists', 'read-resources', 'max-reads', 'offline-check', 'sarif', 'sarif-menu', 'junit', 'html', 'badge'],
96
98
  shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
97
99
  examples: [
98
100
  'toolmenu snapshot -- npx -y @modelcontextprotocol/server-memory',
package/dist/options.d.ts CHANGED
@@ -66,6 +66,12 @@ export declare const CLI_OPTIONS: {
66
66
  readonly lists: {
67
67
  readonly type: 'string';
68
68
  };
69
+ readonly 'read-resources': {
70
+ readonly type: 'boolean';
71
+ };
72
+ readonly 'max-reads': {
73
+ readonly type: 'string';
74
+ };
69
75
  readonly timeout: {
70
76
  readonly type: 'string';
71
77
  };
package/dist/options.js CHANGED
@@ -24,6 +24,8 @@ export const CLI_OPTIONS = {
24
24
  as: { type: 'string', multiple: true },
25
25
  client: { type: 'string' },
26
26
  lists: { type: 'string' },
27
+ 'read-resources': { type: 'boolean' },
28
+ 'max-reads': { type: 'string' },
27
29
  timeout: { type: 'string' },
28
30
  protocol: { type: 'string' },
29
31
  elicitation: { type: 'string' },
package/dist/report.d.ts CHANGED
@@ -7,7 +7,11 @@ export type Format = 'text' | 'json' | 'github' | 'markdown';
7
7
  export declare function counts(findings: Finding[]): Record<Severity, number>;
8
8
  /** --client: "as Claude Code: up front ~N tokens (…) · on demand ~M per tool loaded (largest: x, ~K)". */
9
9
  export declare function costLine(cost: ClientCost, name?: (tool: string) => string): string;
10
- export declare function formatSnapshot(menu: Menu, findings: Finding[], format: Format, outPath?: string, cost?: ClientCost, notOffered?: string[]): string;
10
+ export declare function formatSnapshot(menu: Menu, findings: Finding[], format: Format, outPath?: string, cost?: ClientCost, notOffered?: string[], resourcesRead?: {
11
+ read: number;
12
+ listed: number;
13
+ byApps?: number;
14
+ }): string;
11
15
  export declare function findingLines(findings: Finding[]): string[];
12
16
  export declare function githubLines(findings: Finding[]): string[];
13
17
  export declare function signed(n: number): string;
package/dist/report.js CHANGED
@@ -34,7 +34,7 @@ export function costLine(cost, name = plain) {
34
34
  function appOnlyNote(a) {
35
35
  return a ? ` · ${a.tools} not shown to the agent (MCP Apps visibility without "model", ~${a.tokens.toLocaleString('en-US')} tokens)` : '';
36
36
  }
37
- export function formatSnapshot(menu, findings, format, outPath, cost, notOffered = []) {
37
+ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered = [], resourcesRead) {
38
38
  const view = agentMenu(menu);
39
39
  if (format === 'json') {
40
40
  return JSON.stringify({
@@ -50,6 +50,7 @@ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered
50
50
  ...(menu.resources ? { resources: menu.resources.length } : {}),
51
51
  ...(menu.resourceTemplates ? { resourceTemplates: menu.resourceTemplates.length } : {}),
52
52
  ...(notOffered.length ? { notOffered } : {}),
53
+ ...(resourcesRead ? { resourcesRead } : {}),
53
54
  written: outPath ?? null,
54
55
  counts: counts(findings),
55
56
  findings,
@@ -82,6 +83,8 @@ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered
82
83
  const caps = [...new Set(notOffered.map((k) => (k === 'prompts' ? 'prompts' : 'resources')))];
83
84
  if (others || caps.length)
84
85
  lines.push(` ${[others ? `also listed: ${others}` : '', caps.length ? `no ${caps.join(' or ')} offered (not declared)` : ''].filter(Boolean).join(' · ')}`);
86
+ if (resourcesRead)
87
+ lines.push(` resources/read: ${resourcesRead.read.toLocaleString('en-US')} of ${plural(resourcesRead.listed, 'listed resource')} read${resourcesRead.byApps ? ` (${resourcesRead.byApps.toLocaleString('en-US')} more by the MCP Apps check)` : ''}`);
85
88
  if (outPath)
86
89
  lines.push(` wrote ${outPath}`);
87
90
  lines.push('');
@@ -0,0 +1,74 @@
1
+ import { type Connection } from './connect.js';
2
+ /** The reads together take at most this long (TOOLMENU_READ_BUDGET_MS sets another, for the tests). */
3
+ export declare const READ_BUDGET_MS: number;
4
+ /** Once this many characters of content have arrived, no further read starts. One response can pass it. */
5
+ export declare const READ_BYTES: number;
6
+ /** A resource whose listing declares a size over this isn't read. */
7
+ export declare const MAX_DECLARED_SIZE: number;
8
+ /** Why a resource wasn't checked: the run's doing, or by design. */
9
+ export type UnreadReason = 'auth' | 'payment' | 'network' | 'client' | 'environment' | 'rate-limit' | 'timeout' | 'input-required' | 'budget' | 'bytes' | 'max-reads' | 'declared-size' | 'web' | 'gone';
10
+ export interface ResourceRead {
11
+ uri: string;
12
+ /** The server answered with a result (`ok`), asked for input, answered with an error, or didn't answer. */
13
+ outcome: 'ok' | 'input-required' | 'error' | 'no-answer';
14
+ /** The JSON-RPC error, or the transport's, first line. */
15
+ error?: string;
16
+ code?: number;
17
+ /** Set when the failure is the run's (credentials, the network, a rate limit, a timeout), not the server's. */
18
+ unread?: UnreadReason;
19
+ /** `ok`: how many content items came back. */
20
+ items?: number;
21
+ /** `ok`: every item is text holding a JSON object of these keys only, `error` among them. */
22
+ errorBody?: string[];
23
+ /** `ok`: schema errors against the negotiated version's ReadResourceResult, as lines. */
24
+ schemaErrors?: string[];
25
+ /** Required result properties the schema found missing. */
26
+ missing?: string[];
27
+ /** The SDK client refused a result the server did send. */
28
+ clientError?: string;
29
+ /** Every read failed, all in these words: the server's handler, or one thing this run lacks. */
30
+ shared?: boolean;
31
+ /** A failure's words without the URI, hashed: reads that failed for one cause share it. */
32
+ cause?: string;
33
+ /** The failure says the resource isn't there (its code, "not found", ENOENT). */
34
+ saysMissing?: boolean;
35
+ /** Characters of text and blob received. */
36
+ size?: number;
37
+ ms: number;
38
+ }
39
+ export interface ResourceReads {
40
+ /** Distinct URIs resources/list named that are this pass's to read. */
41
+ listed: number;
42
+ /** Listed ui:// resources the MCP Apps check read instead (apps/resource). */
43
+ byApps: number;
44
+ reads: ResourceRead[];
45
+ /** Resources no read was sent for, by reason. */
46
+ skipped: {
47
+ reason: UnreadReason;
48
+ uris: string[];
49
+ }[];
50
+ /** resources/list was cut at the page cap: the reads cover what was listed. */
51
+ truncated?: boolean;
52
+ /** The negotiated version has a schema these results were checked against. */
53
+ schemaChecked: boolean;
54
+ }
55
+ export interface ReadOptions {
56
+ timeoutMs?: number;
57
+ /** --max-reads: at most this many, spread over the sorted list. */
58
+ maxReads?: number;
59
+ /** URIs the Apps pass has a record for: apps/resource owns those. */
60
+ appUris?: Iterable<string>;
61
+ /** The second resources/list: a URI gone from it isn't read (lists/variance says the list changes). */
62
+ second?: Record<string, unknown>[];
63
+ protocolVersion?: string;
64
+ truncated?: boolean;
65
+ }
66
+ /**
67
+ * n of the sorted items, spread evenly: indices floor(j·(N−1)/(n−1)), so both ends are
68
+ * in; the middle one for n = 1; all of them when n ≥ N.
69
+ */
70
+ export declare function spread<T>(items: T[], n: number): T[];
71
+ /** Read the listed resources, one at a time, in URI order. */
72
+ export declare function readResources(connection: Connection, listed: Record<string, unknown>[], options?: ReadOptions): Promise<ResourceReads>;
73
+ /** The reason a failure is the run's and not the server's, from its words and code; undefined when it's the server's. */
74
+ export declare function runs(text: string, code: number | undefined): UnreadReason | undefined;
@@ -0,0 +1,311 @@
1
+ /*
2
+ * snapshot --read-resources: resources/read on the concrete resources resources/list
3
+ * names, as a client does when a user or an agent picks one. A read, not a tool call.
4
+ *
5
+ * What a body holds is looked at here, in memory, and never kept: the records carry
6
+ * counts, types and error text only, and each response's body is dropped from the wire
7
+ * log once it's been looked at. The rules are in rules/lists.ts.
8
+ */
9
+ import { createHash } from 'node:crypto';
10
+ import { quietExclusions } from './connect.js';
11
+ import { classifyFailure, httpStatus, RATE_LIMITED, tooMany } from './failures.js';
12
+ import { resultValidator } from './rules/spec.js';
13
+ /** The reads together take at most this long (TOOLMENU_READ_BUDGET_MS sets another, for the tests). */
14
+ export const READ_BUDGET_MS = budgetFrom(process.env.TOOLMENU_READ_BUDGET_MS) ?? 120_000;
15
+ /** Once this many characters of content have arrived, no further read starts. One response can pass it. */
16
+ export const READ_BYTES = 64 * 1024 * 1024;
17
+ /** A resource whose listing declares a size over this isn't read. */
18
+ export const MAX_DECLARED_SIZE = 16 * 1024 * 1024;
19
+ /** Below this much time left, a read isn't started: it could only time out. */
20
+ const MIN_READ_MS = 10;
21
+ /** Keys of a body that says an error and nothing else: {"error": "… not found"}. */
22
+ const ERROR_KEYS = new Set(['error', 'message', 'code', 'status', 'detail', 'details', 'uri']);
23
+ /**
24
+ * n of the sorted items, spread evenly: indices floor(j·(N−1)/(n−1)), so both ends are
25
+ * in; the middle one for n = 1; all of them when n ≥ N.
26
+ */
27
+ export function spread(items, n) {
28
+ if (n >= items.length)
29
+ return items;
30
+ if (n === 1)
31
+ return [items[Math.floor((items.length - 1) / 2)]];
32
+ return Array.from({ length: n }, (_, j) => items[Math.floor((j * (items.length - 1)) / (n - 1))]);
33
+ }
34
+ /** Read the listed resources, one at a time, in URI order. */
35
+ export async function readResources(connection, listed, options = {}) {
36
+ const timeoutMs = options.timeoutMs ?? 30_000;
37
+ const declared = new Map();
38
+ for (const r of listed) {
39
+ if (typeof r.uri !== 'string' || !r.uri)
40
+ continue;
41
+ if (!declared.has(r.uri))
42
+ declared.set(r.uri, typeof r.size === 'number' ? r.size : 0);
43
+ }
44
+ // By code unit, not by locale: the same order on every machine.
45
+ const all = [...declared.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
46
+ const skipped = new Map();
47
+ const skip = (reason, uri) => skipped.set(reason, [...(skipped.get(reason) ?? []), uri]);
48
+ const owned = new Set(options.appUris ?? []);
49
+ const still = options.second ? new Set(options.second.map((r) => r.uri)) : undefined;
50
+ const candidates = [];
51
+ let byApps = 0;
52
+ for (const uri of all) {
53
+ if (owned.has(uri)) {
54
+ byApps++;
55
+ continue;
56
+ }
57
+ // A web URL is one the client fetches itself; a server needn't serve it over resources/read.
58
+ if (/^https?:\/\//i.test(uri))
59
+ skip('web', uri);
60
+ else if (still && !still.has(uri))
61
+ skip('gone', uri);
62
+ else if ((declared.get(uri) ?? 0) > MAX_DECLARED_SIZE)
63
+ skip('declared-size', uri);
64
+ else
65
+ candidates.push(uri);
66
+ }
67
+ const queue = options.maxReads !== undefined ? spread(candidates, options.maxReads) : candidates;
68
+ if (queue.length < candidates.length) {
69
+ const chosen = new Set(queue);
70
+ for (const uri of candidates)
71
+ if (!chosen.has(uri))
72
+ skip('max-reads', uri);
73
+ }
74
+ const validate = options.protocolVersion ? resultValidator(options.protocolVersion, 'ReadResourceResult') : null;
75
+ const validateInput = options.protocolVersion ? resultValidator(options.protocolVersion, 'InputRequiredResult') : null;
76
+ const reads = [];
77
+ const mark = connection.wire.responses.length;
78
+ const deadline = Date.now() + READ_BUDGET_MS;
79
+ let received = 0;
80
+ let stopped;
81
+ for (const uri of queue) {
82
+ if (!stopped && deadline - Date.now() < MIN_READ_MS)
83
+ stopped = 'budget';
84
+ if (!stopped && received > READ_BYTES)
85
+ stopped = 'bytes';
86
+ if (stopped) {
87
+ skip(stopped, uri);
88
+ continue;
89
+ }
90
+ const read = await readOne(connection, uri, Math.min(timeoutMs, deadline - Date.now()), validate, validateInput);
91
+ received += read.size ?? 0;
92
+ reads.push(read);
93
+ // A server that says "too many" isn't asked again: the rest go unread.
94
+ if (read.unread === 'rate-limit')
95
+ stopped = 'rate-limit';
96
+ }
97
+ // Every read failed, all for one cause, and none of them for a missing resource: a read
98
+ // handler that fails for everything, or one thing this run lacks that the words don't
99
+ // name. toolmenu can't tell which, so the finding says both (unsure), and stays a warning.
100
+ const failures = reads.filter((r) => !r.unread && (r.outcome === 'error' || r.errorBody));
101
+ const readable = reads.some((r) => r.outcome === 'ok' && !r.errorBody);
102
+ if (!readable && failures.length >= 2 && failures.every((r) => !r.saysMissing && r.cause === failures[0].cause)) {
103
+ for (const r of failures)
104
+ r.shared = true;
105
+ }
106
+ // An answer that came after its read gave up was never looked at: its body goes too.
107
+ for (const late of connection.wire.since(mark, 'resources/read'))
108
+ if (late.result)
109
+ late.result = {};
110
+ return {
111
+ listed: all.length - byApps,
112
+ byApps,
113
+ reads,
114
+ skipped: [...skipped].map(([reason, uris]) => ({ reason, uris })),
115
+ ...(options.truncated ? { truncated: true } : {}),
116
+ schemaChecked: validate !== null,
117
+ };
118
+ }
119
+ async function readOne(connection, uri, timeout, validate, validateInput) {
120
+ const mark = connection.wire.responses.length;
121
+ const started = Date.now();
122
+ let caught;
123
+ await withoutFulfilment(connection, () => quietExclusions(() => connection.client.readResource({ uri }, { timeout }))).catch((e) => (caught = e));
124
+ const ms = Date.now() - started;
125
+ // What the server sent, not the SDK's reading of it: the SDK may refuse a result toolmenu still checks.
126
+ // By URI: after a timeout, the answer to an earlier read can arrive during this one.
127
+ const answers = connection.wire.since(mark, 'resources/read').filter((r) => r.uri === uri);
128
+ const answer = answers.at(-1);
129
+ try {
130
+ if (answer?.result) {
131
+ const result = answer.result;
132
+ const clientError = caught === undefined ? undefined : firstLine(caught);
133
+ if (result.resultType === 'input_required') {
134
+ return { uri, outcome: 'input-required', unread: 'input-required', ...schemaOf(validateInput, result), ms };
135
+ }
136
+ const contents = Array.isArray(result.contents) ? result.contents : [];
137
+ let size = 0;
138
+ for (const c of contents) {
139
+ const item = c;
140
+ if (typeof item?.text === 'string')
141
+ size += item.text.length;
142
+ if (typeof item?.blob === 'string')
143
+ size += item.blob.length;
144
+ }
145
+ const body = errorBody(contents);
146
+ // An error-only body for want of credentials or the network is the run's, as an error would be.
147
+ const bodyUnread = body ? runs(body.text, undefined) : undefined;
148
+ return {
149
+ uri,
150
+ outcome: 'ok',
151
+ items: contents.length,
152
+ ...(body ? { errorBody: body.keys, cause: causeOf(body.text, uri), ...(MISSING.test(body.text) ? { saysMissing: true } : {}) } : {}),
153
+ ...(bodyUnread ? { unread: bodyUnread } : {}),
154
+ ...schemaOf(validate, result),
155
+ ...(clientError ? { clientError } : {}),
156
+ size,
157
+ ms,
158
+ };
159
+ }
160
+ if (answer?.error) {
161
+ const message = String(answer.error.message ?? '').split('\n')[0].trim();
162
+ const code = typeof answer.error.code === 'number' ? answer.error.code : undefined;
163
+ const unread = runs(message, code);
164
+ const saysMissing = code === -32002 || code === -32602 || MISSING.test(message);
165
+ return { uri, outcome: 'error', error: message, ...(code !== undefined ? { code } : {}), ...(unread ? { unread } : {}), cause: causeOf(message, uri), ...(saysMissing ? { saysMissing } : {}), ms };
166
+ }
167
+ // No answer: the transport refused the request (HTTP 401, 429…), or it timed out.
168
+ const said = firstLine(caught ?? 'no resources/read response');
169
+ const status = httpStatus(caught);
170
+ const unread = status === 429 || tooMany(caught) ? 'rate-limit' : status === 401 || status === 403 ? 'auth' : status === 402 ? 'payment' : /timed out|timeout/i.test(said) ? 'timeout' : (runs(said, undefined) ?? 'network');
171
+ return { uri, outcome: 'no-answer', error: said, unread, ms };
172
+ }
173
+ finally {
174
+ // The body has been looked at: the wire log keeps every response until the
175
+ // connection closes, and 200 resources shouldn't add up there.
176
+ for (const a of answers)
177
+ if (a.result)
178
+ a.result = {};
179
+ }
180
+ }
181
+ /**
182
+ * One request per resource: the SDK client answers an InputRequiredResult itself and
183
+ * sends the read again, up to eight times, and toolmenu has no answer worth sending.
184
+ * With that off, the first InputRequiredResult ends the read. A client-wide setting the
185
+ * SDK doesn't expose per request; a test counts the requests, should its name change.
186
+ */
187
+ async function withoutFulfilment(connection, read) {
188
+ const config = connection.client._inputRequiredDriverConfig;
189
+ if (!config)
190
+ return read();
191
+ const before = config.autoFulfill;
192
+ config.autoFulfill = false;
193
+ try {
194
+ return await read();
195
+ }
196
+ finally {
197
+ config.autoFulfill = before;
198
+ }
199
+ }
200
+ /** The reason a failure is the run's and not the server's, from its words and code; undefined when it's the server's. */
201
+ export function runs(text, code) {
202
+ // The codes for "no such resource" (-32002 to 2025-11-25, -32602 from 2026-07-28): the
203
+ // server's answer about a resource it listed, whatever else the words mention.
204
+ if (code === -32002 || code === -32602)
205
+ return undefined;
206
+ if (RATE_LIMITED.test(text))
207
+ return 'rate-limit';
208
+ if (NETWORK_WORDS.test(text))
209
+ return 'network';
210
+ if (CREDENTIAL_WORDS.test(text))
211
+ return 'auth';
212
+ if (SETUP_WORDS.test(text))
213
+ return 'environment';
214
+ const failure = classifyFailure(text, { code });
215
+ if (failure === 'auth' || failure === 'payment' || failure === 'network' || failure === 'client')
216
+ return failure;
217
+ // Something this run lacks (a browser, an app, a cluster). A missing file is not that: for a
218
+ // listed resource, ENOENT is the server naming a file it doesn't have.
219
+ if (failure === 'environment' && !/\bENOENT\b/.test(text))
220
+ return 'environment';
221
+ return undefined;
222
+ }
223
+ /**
224
+ * A read that couldn't get out, in the words servers use (the bench, 2026-11): "self-signed
225
+ * certificate in certificate chain" (Lara, Shodan behind a proxy), "[SSL:
226
+ * CERTIFICATE_VERIFY_FAILED]" and "[Errno -3] Temporary failure in name resolution"
227
+ * (StackHawk), "API error: fetch failed" (Glif), "Transport error (GET https://…)"
228
+ * (effect-mcp), `Get "https://…": dial tcp` (Terraform).
229
+ */
230
+ const NETWORK_WORDS = /self-signed certificate|certificate verify failed|CERTIFICATE_VERIFY_FAILED|unable to (?:get|verify) [^.]{0,30}certificate|failure in name resolution|no such host|\bfetch failed\b|\btransport error\b|\bdial tcp\b|\bGet "https?:\/\/|connection (?:refused|reset|timed out)|network is unreachable/i;
231
+ /**
232
+ * A credential in the wrong shape, which a dummy one is: "Access token is not in valid JWT
233
+ * format" (Mapbox); or none sent: "missing authorization header" (a hosted server that lists
234
+ * its tools without one, then wants one to read a resource).
235
+ */
236
+ const CREDENTIAL_WORDS = /\bmissing (?:an? |the )?(?:authorization|auth|bearer) (?:header|token)\b|\b(?:access |api |auth )?(?:token|key)\b[^.]{0,30}\b(?:not in (?:a )?valid|malformed|invalid format)\b/i;
237
+ /**
238
+ * Nothing to read from: "No currently active project." (Firebase), "Invalid kube-config file. No
239
+ * configuration found." (kubectl-mcp-server), "HTTP protocol is not allowed when skipTLSVerify is
240
+ * not set" (mcp-server-kubernetes with no cluster), "You must provide an endpoint" (Amazon Neptune).
241
+ */
242
+ const SETUP_WORDS = /\bno (?:currently )?(?:active|selected|default|current) (?:project|account|workspace|organi[sz]ation|cluster|context|profile)\b|\binvalid kube-?config\b|\bskipTLSVerify\b|\bmust provide an? (?:endpoint|host|url|connection string)\b/i;
243
+ /** The failure says the resource isn't there. */
244
+ const MISSING = /\bnot found\b|\bENOENT\b|no such file|does(?:n't| not) exist/i;
245
+ /** A failure's words with the URI taken out, hashed: the same for every resource one cause stops. */
246
+ function causeOf(text, uri) {
247
+ let words = text;
248
+ for (const form of new Set([uri, encodeURI(uri), uri.toLowerCase()]))
249
+ words = words.split(form).join('<uri>');
250
+ return createHash('sha1').update(words.replace(/\s+/g, ' ').trim().toLowerCase()).digest('hex').slice(0, 12);
251
+ }
252
+ /** A body that is only an error: each item text, a JSON object of ERROR_KEYS with `error` among them. */
253
+ function errorBody(contents) {
254
+ if (!contents.length)
255
+ return undefined;
256
+ const keys = new Set();
257
+ let text = '';
258
+ for (const c of contents) {
259
+ const item = c;
260
+ if (typeof item?.text !== 'string' || item.text.length > 4096 || !/^\s*\{/.test(item.text))
261
+ return undefined;
262
+ let parsed;
263
+ try {
264
+ parsed = JSON.parse(item.text);
265
+ }
266
+ catch {
267
+ return undefined;
268
+ }
269
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
270
+ return undefined;
271
+ const object = parsed;
272
+ const own = Object.keys(object);
273
+ if (!own.includes('error') || !object.error || own.some((k) => !ERROR_KEYS.has(k)))
274
+ return undefined;
275
+ for (const k of own)
276
+ keys.add(k);
277
+ const inner = typeof object.error === 'object' ? object.error.message : object.error;
278
+ text += ` ${typeof inner === 'string' ? inner : ''} ${typeof object.message === 'string' ? object.message : ''}`;
279
+ }
280
+ return { keys: [...keys].sort(), text: text.trim() };
281
+ }
282
+ /** The result against the schema: the errors as lines (paths and rules, never values). */
283
+ function schemaOf(validate, result) {
284
+ // Before the validator: it narrows a result it refuses to nothing.
285
+ const contents = result.contents;
286
+ if (!validate || validate(result))
287
+ return {};
288
+ const errors = validate.errors ?? [];
289
+ // Each item is tried as text and as blob: the union's own line says nothing the others don't.
290
+ const has = (path, key) => {
291
+ const index = /^\/contents\/(\d+)$/.exec(path)?.[1];
292
+ const item = index !== undefined && Array.isArray(contents) ? contents[Number(index)] : undefined;
293
+ return typeof item?.[key] === 'string';
294
+ };
295
+ const needs = (path, property) => errors.some((e) => e.instancePath === path && e.params && 'missingProperty' in e.params && e.params.missingProperty === property);
296
+ const lines = [
297
+ ...new Set(errors
298
+ .filter((e) => e.keyword !== 'anyOf')
299
+ // An item with text was tried as a blob too: "needs blob" there is the union's noise.
300
+ .filter((e) => !(e.keyword === 'required' && e.instancePath && (has(e.instancePath, 'text') !== has(e.instancePath, 'blob'))))
301
+ // An item is text or a blob: one line for an item with neither, not one per kind.
302
+ .map((e) => (e.instancePath && needs(e.instancePath, 'text') && needs(e.instancePath, 'blob') && e.keyword === 'required' ? `${e.instancePath} must have text or blob` : `${e.instancePath || '(result)'} ${e.message}`))),
303
+ ];
304
+ const missing = [...new Set(errors.filter((e) => !e.instancePath && e.params && 'missingProperty' in e.params).map((e) => String(e.params.missingProperty)))];
305
+ return { schemaErrors: lines.length ? lines : ['(result) does not match'], ...(missing.length ? { missing } : {}) };
306
+ }
307
+ const firstLine = (error) => (error instanceof Error ? error.message : String(error)).split('\n')[0].trim();
308
+ function budgetFrom(text) {
309
+ const n = Number(text);
310
+ return text && Number.isFinite(n) && n > 0 ? n : undefined;
311
+ }
package/dist/review.js CHANGED
@@ -13,7 +13,7 @@ import { bumpVerdict, classLine, counts, findingLines, mdFindings, releasePair,
13
13
  import { mdCode, mdText, plain } from './sanitize.js';
14
14
  // Rules that read the wire (the raw tools/list pages, the handshake), which a menu
15
15
  // file doesn't hold: run on a file they'd say the same about both menus, or nothing true.
16
- const WIRE_ONLY = new Set(['spec/schema', 'spec/discover']);
16
+ const WIRE_ONLY = new Set(['spec/schema', 'spec/discover', 'lists/resource-unreadable', 'lists/resource-read-schema', 'lists/resource-unread']);
17
17
  // diff findings that say what it couldn't compare, not what changed.
18
18
  const NOT_COMPARED = new Set(['diff/lists-unread', 'diff/catalog-queries']);
19
19
  /** The menu rules on a menu file, as far as a file can tell: no second list, no probes. */
@@ -12,7 +12,7 @@
12
12
  "apps/resource": {
13
13
  "command": "snapshot",
14
14
  "severity": "warn",
15
- "text": "MCP Apps. Each `ui://` resource a tool names in `_meta.ui.resourceUri` is read with `resources/read` (a read, not a tool call), as a host does before rendering it: the URI must start with `ui://`, the resource must exist, its content's `mimeType` must be `text/html;profile=mcp-app`, with the HTML as text or blob, and `_meta.ui.resourceUri` and the old key, when both are set, must agree. Otherwise an Apps host shows no UI and the agent gets only the text result"
15
+ "text": "MCP Apps. Each `ui://` resource a tool names in `_meta.ui.resourceUri` is read with `resources/read` (a read, not a tool call), as a host does before rendering it: the URI must start with `ui://`, the resource must exist, its content's `mimeType` must be `text/html;profile=mcp-app`, with the HTML as text or blob, and `_meta.ui.resourceUri` and the old key, when both are set, must agree. Otherwise an Apps host shows no UI and the agent gets only the text result A read that failed for the run's reasons is info, not this warning: credentials (\"not authenticated\", \"missing authorization header\"), the network, a rate limit, no answer in time, or the reads running out of time. The words are `--read-resources`'s classifier's"
16
16
  },
17
17
  "apps/visibility": {
18
18
  "command": "snapshot",
@@ -64,6 +64,21 @@
64
64
  "severity": "info",
65
65
  "text": "2026-07-28. A tool that creates a handle (`create`/`start`/`open`/`new`/`begin`/`acquire` + session, basket, cart, checkout, handle, lease or lock) that another tool takes back (`session_id`, `sessionToken`, `session`), whose description and output schema don't say how long it lasts. The spec asks for retention in the creation tool's description. Unsure"
66
66
  },
67
+ "lists/resource-read-schema": {
68
+ "command": "snapshot",
69
+ "severity": "error",
70
+ "text": "`snapshot --read-resources`. Each `resources/read` result, as it came off the wire, against `ReadResourceResult` in the official schema of the negotiated protocol version: an item needs `uri` and `text` or `blob`; 2026-07-28 also requires `resultType`, `ttlMs` and `cacheScope`, earlier versions don't. One finding for the server, with the distinct schema errors, however many resources share them. A second kind: a result that matches the schema and the official SDK client still refused (seen with a `resultType` the schema takes as any string), in the SDK's words. An `InputRequiredResult` is checked against its own schema where the version has one. A version with no pinned schema isn't checked"
71
+ },
72
+ "lists/resource-unread": {
73
+ "command": "snapshot",
74
+ "severity": "info",
75
+ "text": "`snapshot --read-resources`. The listed resources no finding covers, by reason and with counts, so a clean result isn't read as complete: the run's failures (401/403 and other credential errors, payment, the network, a client capability, something the run lacks (a cluster, a project, an app), a read that didn't answer within `--timeout`), a rate limit (the reads stop at the first one), an `InputRequiredResult` (2026-07-28: the server MAY ask for input first), the 120 s for all reads running out, 64 MB of content having arrived, `--max-reads`, a listing that declares a `size` over 16 MB, `http(s)://` URIs (the spec has the client fetch those itself), a resource gone from the second `resources/list`, and a list cut at the page limit. An error-only body whose words are a credential or network failure counts here too. A missing backend counts when the server names it: \"Invalid kube-config file\", \"You must provide an endpoint\", \"No currently active project\""
76
+ },
77
+ "lists/resource-unreadable": {
78
+ "command": "snapshot",
79
+ "severity": "warn",
80
+ "text": "`snapshot --lists resources --read-resources` (or `readResources` in the config) sends `resources/read` for each concrete resource `resources/list` names: once per URI, in URI order, one at a time. Resource templates aren't read, and a `ui://` resource a tool names is `apps/resource`'s. warn: the read answers with a JSON-RPC error that isn't the run's, one finding with each URI and the server's words (`-32002`, `-32602`, `ENOENT` and \"not found\" are the server's here: it listed the resource). No spec version says a listed resource MUST be readable, so this rests on what toolmenu saw and is never an error. warn, marked unsure: the read succeeds and every content item is text holding a JSON object with an `error` key and no key beyond `error`, `message`, `code`, `status`, `detail`, `details`, `uri` (`@dpantani/tdmcp` 0.13.2 answered `{\"error\": \"Python class … not found.\"}` for five listed resources); a guess from the shape, and the body is never quoted. warn, marked unsure: two or more reads fail, all in the same words (the URI aside), none says the resource is missing, the words name no cause toolmenu knows, and nothing reads. That is a read handler that fails for everything, or one thing the run lacks that the server didn't name; the finding says both. info: an empty `contents` array, which 2026-07-28 calls ambiguous. Each resource gets one `resources/read` request: the SDK client's own retries after an `InputRequiredResult` are off for these reads. Quiet: empty text, several contents, contents with other URIs (the spec allows sub-resources), a returned `uri` or `mimeType` that differs from the listing"
81
+ },
67
82
  "lists/schema": {
68
83
  "command": "snapshot",
69
84
  "severity": "error",
@@ -1,5 +1,7 @@
1
1
  import { APPS_MIME_TYPE } from '../connect.js';
2
2
  import { isAppOnly, isAppsMimeType, LEGACY_URI_KEY, uiMeta } from '../apps.js';
3
+ import { runs } from '../resource-read.js';
4
+ import { tooMany } from '../failures.js';
3
5
  import { clip, count, kept, names } from './rule.js';
4
6
  /*
5
7
  * MCP Apps (ext-apps): checks on the UI a tool names, as an Apps host reads it.
@@ -16,6 +18,8 @@ export const appsResource = {
16
18
  summary: "The UI a tool names (MCP Apps _meta.ui.resourceUri) is a ui:// resource the server serves as an app",
17
19
  run(ctx) {
18
20
  const problems = [];
21
+ // Reads that failed for the run's reasons: said, but not as the server's.
22
+ const unread = [];
19
23
  const read = new Map((ctx.appResources ?? []).map((r) => [r.uri, r]));
20
24
  for (const tool of kept(ctx.menu.tools, ctx)) {
21
25
  const ui = uiMeta(tool);
@@ -36,15 +40,34 @@ export const appsResource = {
36
40
  const r = read.get(uri);
37
41
  if (!r)
38
42
  continue; // not read (over the limit, or the run read none)
43
+ const reason = r.error ? runsReason(r) : undefined;
44
+ if (reason) {
45
+ unread.push({ tool: tool.name, uri, reason, error: r.error });
46
+ continue;
47
+ }
39
48
  const why = resourceProblem(r);
40
49
  if (why)
41
50
  problems.push({ tool: tool.name, why });
42
51
  }
52
+ const findings = [];
53
+ if (unread.length) {
54
+ const tools = [...new Set(unread.map((u) => u.tool))];
55
+ const one = tools.length === 1;
56
+ const credentials = unread.some((u) => u.reason === 'auth' || u.reason === 'payment');
57
+ findings.push({
58
+ severity: 'info',
59
+ ...(one ? { tool: tools[0] } : {}),
60
+ message: `${one ? `${tools[0]} names an MCP Apps UI` : `${count(tools.length, 'tool')} name MCP Apps UIs`} that toolmenu couldn't read here (${UNREAD[unread[0].reason]}: ${clip(unread[0].error, 120)}), so ${one ? "it wasn't" : "they weren't"} checked: a setup problem, not the server's.`,
61
+ ...(unread.length > 1 ? { detail: unread.map((u) => `${u.tool}: ${u.uri}: ${UNREAD[u.reason]} (${clip(u.error, 120)})`) } : {}),
62
+ fix: credentials ? 'Rerun with the credentials the server needs (--header, --env) to check the UI.' : 'Rerun where the server can answer (the network, the backend it reads from, more --timeout) to check the UI.',
63
+ });
64
+ }
43
65
  if (!problems.length)
44
- return [];
66
+ return findings;
45
67
  const tools = [...new Set(problems.map((p) => p.tool))];
46
68
  const one = tools.length === 1;
47
69
  return [
70
+ ...findings,
48
71
  {
49
72
  ...(one ? { tool: tools[0] } : {}),
50
73
  message: `${one ? `${tools[0]} names` : `${count(tools.length, 'tool')} name`} an MCP Apps UI that a host can't render: ${one ? problems[0].why : names(tools, 6)}. ${FALLBACK}`,
@@ -54,6 +77,32 @@ export const appsResource = {
54
77
  ];
55
78
  },
56
79
  };
80
+ const UNREAD = {
81
+ auth: 'credentials',
82
+ payment: 'payment',
83
+ network: 'the network',
84
+ client: "a client capability toolmenu doesn't declare",
85
+ environment: 'something this run lacks',
86
+ 'rate-limit': 'a rate limit',
87
+ timeout: 'no answer in time',
88
+ 'input-required': 'the server asked for input',
89
+ budget: 'the reads ran out of time',
90
+ bytes: 'enough content already',
91
+ 'max-reads': '--max-reads',
92
+ 'declared-size': 'its declared size',
93
+ web: 'an http(s) URL',
94
+ gone: 'gone from the list',
95
+ };
96
+ /** Why a failed read is the run's (credentials, the network, time), or undefined when it's the server's. */
97
+ function runsReason(r) {
98
+ if (r.notRead)
99
+ return 'budget';
100
+ if (tooMany(r.error))
101
+ return 'rate-limit';
102
+ if (r.code === undefined && /timed out|timeout/i.test(r.error ?? ''))
103
+ return 'timeout';
104
+ return runs(r.error ?? '', r.code);
105
+ }
57
106
  function resourceProblem(r) {
58
107
  if (r.error)
59
108
  return `resources/read of ${r.uri} failed (${clip(r.error, 120)}): the spec says the resource MUST exist on the server`;
@@ -6,7 +6,7 @@ import { clientFeatures, clientLimit, clientName } from './clients.js';
6
6
  import { invalidCredential } from './auth.js';
7
7
  import { networkDependent } from './network.js';
8
8
  import { capabilityDependent } from './capabilities.js';
9
- import { listSchema, listVariance } from './lists.js';
9
+ import { listSchema, listVariance, resourceReadSchema, resourceUnread, resourceUnreadable } from './lists.js';
10
10
  import { handleLifetime } from './handles.js';
11
11
  import { authVariance, cacheScopePublic } from './identities.js';
12
12
  import { route, sharedWord, vagueId } from './naming.js';
@@ -55,6 +55,9 @@ export const MENU_RULES = [
55
55
  capabilityDependent,
56
56
  listVariance,
57
57
  listSchema,
58
+ resourceUnreadable,
59
+ resourceReadSchema,
60
+ resourceUnread,
58
61
  cacheScopePublic,
59
62
  serverInfo,
60
63
  extensionId,
@@ -14,3 +14,6 @@ export interface ListsContext {
14
14
  }
15
15
  export declare const listVariance: Rule;
16
16
  export declare const listSchema: Rule;
17
+ export declare const resourceUnreadable: Rule;
18
+ export declare const resourceReadSchema: Rule;
19
+ export declare const resourceUnread: Rule;
@@ -1,7 +1,7 @@
1
1
  import { LIST_INFO, listChanges } from '../lists.js';
2
2
  import { classifyFailure, SETUP_FAILURES } from '../failures.js';
3
- import { count } from './rule.js';
4
- import { resultValidator } from './spec.js';
3
+ import { clip, count, names, num } from './rule.js';
4
+ import { resultValidator, sdkIssues } from './spec.js';
5
5
  const RESULT = { prompts: 'ListPromptsResult', resources: 'ListResourcesResult', resourceTemplates: 'ListResourceTemplatesResult' };
6
6
  export const listVariance = {
7
7
  id: 'lists/variance',
@@ -100,3 +100,165 @@ export const listSchema = {
100
100
  return findings;
101
101
  },
102
102
  };
103
+ /*
104
+ * snapshot --read-resources: resources/read on each listed resource (resource-read.ts).
105
+ * A failure that is the server's is lists/resource-unreadable; a result a client would
106
+ * refuse is lists/resource-read-schema; everything the run didn't or couldn't check is
107
+ * lists/resource-unread, so a clean result is never read as covering more than it did.
108
+ */
109
+ /** URIs as detail lines, the first `max` and a count of the rest. */
110
+ function listed(lines, max = 8) {
111
+ return lines.slice(0, max).concat(lines.length > max ? [`…and ${num(lines.length - max)} more`] : []);
112
+ }
113
+ /** A URI in a message: a server's text, on one line and not endless. */
114
+ const shown = (uri) => clip(uri, 160);
115
+ export const resourceUnreadable = {
116
+ id: 'lists/resource-unreadable',
117
+ severity: 'warn',
118
+ summary: 'Every resource resources/list names can be read with resources/read (snapshot --read-resources)',
119
+ run(ctx) {
120
+ const reads = ctx.resourceReads?.reads ?? [];
121
+ const findings = [];
122
+ const missingCode = ctx.protocolVersion && ctx.protocolVersion >= '2026-07-28' ? '-32602' : '-32002';
123
+ // Those a finding can be about: a read the run couldn't make its own says nothing.
124
+ const total = `${num(reads.filter((r) => !r.unread).length)} checked`;
125
+ // Every read failed in the same words: the handler, or one thing the run lacks.
126
+ const shared = reads.filter((r) => r.outcome === 'error' && !r.unread && r.shared);
127
+ if (shared.length) {
128
+ findings.push({
129
+ confidence: 'unsure',
130
+ message: `All ${count(shared.length, 'resource')} toolmenu checked fail resources/read the same way: ${clip(shared[0].error || 'no message', 160)}${shared[0].code !== undefined ? ` (${shared[0].code})` : ''}. Either the server can't read any resource it lists, or each needs something this run lacks (a backend, an account) and the words don't say so; toolmenu can't tell which.`,
131
+ detail: listed(shared.map((r) => shown(r.uri))),
132
+ fix: `If this run lacks what the resources read from, rerun where it's there. Otherwise make resources/read answer the URIs resources/list returns.`,
133
+ });
134
+ }
135
+ const failed = reads.filter((r) => r.outcome === 'error' && !r.unread && !r.shared);
136
+ if (failed.length) {
137
+ const said = (r) => `${clip(r.error || 'no message', 120)}${r.code !== undefined ? ` (${r.code})` : ''}`;
138
+ const one = failed.length === 1;
139
+ findings.push({
140
+ message: one
141
+ ? `resources/list names ${shown(failed[0].uri)}, but resources/read of it failed: ${said(failed[0])}. A client that offers the list gets an error when this one is picked.`
142
+ : `resources/list names ${count(failed.length, 'resource')} that resources/read fails on (of ${total}). A client that offers the list gets an error when one of them is picked.`,
143
+ ...(one ? {} : { detail: listed(failed.map((r) => `${shown(r.uri)}: ${said(r)}`)) }),
144
+ fix: `Make resources/read answer every URI resources/list returns, or leave the ones it can't serve out of the list.`,
145
+ });
146
+ }
147
+ const bodies = reads.filter((r) => r.outcome === 'ok' && r.errorBody && !r.unread);
148
+ if (bodies.length) {
149
+ const one = bodies.length === 1;
150
+ const keys = [...new Set(bodies.flatMap((r) => r.errorBody))].sort().join(', ');
151
+ findings.push({
152
+ confidence: 'unsure',
153
+ message: `${one ? `resources/read of ${shown(bodies[0].uri)} succeeds, but its content is` : `resources/read succeeds for ${count(bodies.length, 'listed resource')} (of ${total}) whose content is`} only a JSON object saying an error (keys: ${keys}). A client takes that for the resource and hands it to the user or the agent as content.${bodies.every((r) => r.shared) && bodies.length > 1 ? ' All of them say the same thing, so it may be one thing this run lacks.' : ''} A guess from the shape: toolmenu doesn't read meaning into content.`,
154
+ ...(one ? {} : { detail: listed(bodies.map((r) => shown(r.uri))) }),
155
+ fix: `If the read failed, answer with a JSON-RPC error (${missingCode} for a resource that doesn't exist) so a client can tell; if that object is the resource, turn this rule off for the server.`,
156
+ });
157
+ }
158
+ const empty = reads.filter((r) => r.outcome === 'ok' && r.items === 0);
159
+ if (empty.length) {
160
+ const one = empty.length === 1;
161
+ findings.push({
162
+ severity: 'info',
163
+ message: `${one ? `resources/read of ${shown(empty[0].uri)} returns` : `resources/read returns, for ${count(empty.length, 'listed resource')} (of ${total}),`} an empty contents array. A client can't tell a resource with nothing in it from one that isn't there.`,
164
+ ...(one ? {} : { detail: listed(empty.map((r) => shown(r.uri))) }),
165
+ fix: `Return one item with empty text for an empty resource, and a JSON-RPC error (${missingCode}) for one that doesn't exist.`,
166
+ });
167
+ }
168
+ return findings;
169
+ },
170
+ };
171
+ export const resourceReadSchema = {
172
+ id: 'lists/resource-read-schema',
173
+ severity: 'error',
174
+ summary: 'resources/read results match the official schema for the negotiated protocol version (snapshot --read-resources)',
175
+ run(ctx) {
176
+ if (!ctx.protocolVersion || !ctx.resourceReads?.schemaChecked)
177
+ return [];
178
+ const reads = ctx.resourceReads.reads;
179
+ const findings = [];
180
+ const invalid = reads.filter((r) => r.schemaErrors?.length);
181
+ if (invalid.length) {
182
+ // Positions in a contents array differ per resource; the rule broken doesn't.
183
+ const one = invalid.length === 1;
184
+ const lines = [...new Set(invalid.flatMap((r) => r.schemaErrors.map((l) => (one ? l : l.replace(/\/contents\/\d+/g, '/contents/N')))))];
185
+ const missing = [...new Set(invalid.flatMap((r) => r.missing ?? []))];
186
+ const hints = missing.some((m) => m === 'ttlMs' || m === 'cacheScope');
187
+ findings.push({
188
+ message: `The resources/read result ${one ? `for ${shown(invalid[0].uri)} doesn't` : `doesn't match for ${count(invalid.length, 'resource')} of ${num(reads.filter((x) => !x.unread).length)} checked: they don't`} match the official ${ctx.protocolVersion} schema, so a strict client may refuse ${one ? 'it' : 'them'}.`,
189
+ detail: listed(lines, 5).concat(one ? [] : [`e.g. ${shown(invalid[0].uri)}`]),
190
+ fix: missing.length
191
+ ? `Add ${missing.join(', ')} to the resources/read result${hints ? ` (${ctx.protocolVersion} requires cache hints on it, SEP-2549)` : ''}.`
192
+ : `Fix ${lines[0]?.split(' ')[0] || 'the result'} first (${lines[0]?.split(' ').slice(1).join(' ') || 'see above'}), then rerun.`,
193
+ });
194
+ }
195
+ // The server's result is what the schema asks for, and the official client still refused it.
196
+ const refused = reads.filter((r) => r.outcome === 'ok' && r.clientError && !r.schemaErrors?.length);
197
+ if (refused.length) {
198
+ const said = sdkIssues(refused[0].clientError);
199
+ const one = refused.length === 1;
200
+ findings.push({
201
+ message: `The official MCP SDK client rejected the resources/read result ${one ? `for ${shown(refused[0].uri)}` : `for ${count(refused.length, 'resource')} of ${num(reads.filter((x) => !x.unread).length)} checked`}, so clients built on it can't read ${one ? 'it' : 'them'}. The result does match the ${ctx.protocolVersion} schema; the SDK said: ${said.summary}`,
202
+ ...(said.detail.length || !one ? { detail: said.detail.concat(one ? [] : listed(refused.map((r) => shown(r.uri)))) } : {}),
203
+ fix: 'Fix what the SDK names above, then read the resource with the official client to confirm.',
204
+ });
205
+ }
206
+ return findings;
207
+ },
208
+ };
209
+ const UNREAD_WORDS = {
210
+ auth: 'need credentials this run lacks',
211
+ payment: 'need payment',
212
+ network: "need a network this run couldn't reach",
213
+ client: "need a client capability toolmenu doesn't declare",
214
+ environment: 'need something this run lacks (a cluster, a project, an app)',
215
+ 'rate-limit': 'the server refused for too many requests, so toolmenu stopped reading',
216
+ timeout: "didn't answer in time",
217
+ 'input-required': 'the server asked for input first (InputRequiredResult)',
218
+ budget: 'the time for the reads ran out',
219
+ bytes: 'enough content had arrived already',
220
+ 'max-reads': 'over --max-reads',
221
+ 'declared-size': 'the listing declares a size too large to read',
222
+ web: 'http(s) URLs, which a client fetches itself',
223
+ gone: 'gone from the list by its second reading',
224
+ };
225
+ export const resourceUnread = {
226
+ id: 'lists/resource-unread',
227
+ severity: 'info',
228
+ summary: 'Says which listed resources snapshot --read-resources did not check, and why',
229
+ run(ctx) {
230
+ const pass = ctx.resourceReads;
231
+ if (!pass)
232
+ return [];
233
+ const by = new Map();
234
+ const add = (reason, uris) => by.set(reason, [...(by.get(reason) ?? []), ...uris]);
235
+ for (const r of pass.reads)
236
+ if (r.unread)
237
+ add(r.unread, [r.uri]);
238
+ for (const s of pass.skipped)
239
+ add(s.reason, s.uris);
240
+ const unread = [...by.values()].reduce((n, u) => n + u.length, 0);
241
+ if (!unread && !pass.truncated)
242
+ return [];
243
+ const checked = pass.reads.filter((r) => !r.unread).length;
244
+ const detail = [...by].map(([reason, uris]) => `${num(uris.length)}: ${UNREAD_WORDS[reason]} (${names(uris.map(shown), 3)})`);
245
+ if (pass.truncated)
246
+ detail.push('resources/list was cut at the page limit: resources past it were never listed, so never read');
247
+ const credentials = by.has('auth');
248
+ return [
249
+ {
250
+ message: unread
251
+ ? `resources/read wasn't checked for ${num(unread)} of ${count(pass.listed, 'listed resource')} (${num(checked)} checked), so no finding about them doesn't mean they can be read.`
252
+ : `resources/read was checked for the ${count(pass.listed, 'resource')} toolmenu listed; resources/list has more pages than it read.`,
253
+ detail,
254
+ fix: credentials
255
+ ? 'Rerun with the credentials the resources need (--header, --env) to check them.'
256
+ : by.has('environment') || by.has('network')
257
+ ? 'Rerun where the resources can answer (the backend, account or network they read from) to check them.'
258
+ : by.has('budget') || by.has('max-reads') || by.has('timeout') || by.has('rate-limit')
259
+ ? 'Rerun against a server instance of your own, without --max-reads, to check the rest.'
260
+ : 'Nothing to change on the server for this.',
261
+ },
262
+ ];
263
+ },
264
+ };
@@ -50,6 +50,8 @@ export interface RuleContext {
50
50
  serverUrl?: string;
51
51
  /** snapshot: what resources/read gave for each ui:// resource the tools name (MCP Apps). */
52
52
  appResources?: import('../apps.js').AppResource[];
53
+ /** snapshot --read-resources: what resources/read gave for the listed resources (lists/resource-* rules). */
54
+ resourceReads?: import('../resource-read.js').ResourceReads;
53
55
  /**
54
56
  * Set by runRules from the `ignore` setting. Rules that sum many tools up in
55
57
  * one finding use it to leave ignored tools out of the summary; findings about
@@ -26,6 +26,10 @@ export interface SnapshotOptions extends RuleSettings {
26
26
  identities?: Identity[];
27
27
  /** --lists: which lists besides tools to read and check (prompts, resources). */
28
28
  lists?: string[];
29
+ /** --read-resources: resources/read on each resource resources/list names (needs resources in lists). */
30
+ readResources?: boolean;
31
+ /** --max-reads: at most this many reads, spread over the list. */
32
+ maxReads?: number;
29
33
  /** --client: check the menu for this client (src/clients.ts): its description cut, its search, its name format. */
30
34
  client?: string;
31
35
  /** --offline-check (stdio): list the menu once more with the network cut off (menu/network-dependent). */
@@ -40,6 +44,12 @@ export interface SnapshotResult {
40
44
  cost?: ClientCost;
41
45
  /** --lists: lists asked for that the server declares no capability for, so weren't read. */
42
46
  notOffered?: ListKind[];
47
+ /** --read-resources: how many listed resources were read, of how many listed. */
48
+ resourcesRead?: {
49
+ read: number;
50
+ listed: number;
51
+ byApps?: number;
52
+ };
43
53
  }
44
54
  /** Establish the menu: connect, list the tools twice, run the menu rules. */
45
55
  export declare function snapshot(given: Target, options?: SnapshotOptions): Promise<SnapshotResult>;
package/dist/snapshot.js CHANGED
@@ -5,6 +5,7 @@ import { buildMenu } from './menu.js';
5
5
  import { asIdentity, connectPatiently, isContainerWrapper, MAIN_SEED, PROBE_SEED, probeMenu, probeSameEra, probeVariance, seeded } from './probe.js';
6
6
  import { kindsToRead, readList } from './lists.js';
7
7
  import { agentMenu, readAppResources, resourceUriOf } from './apps.js';
8
+ import { readResources } from './resource-read.js';
8
9
  import { readServerCard } from './card.js';
9
10
  import { listingsDiffer } from './rules/capabilities.js';
10
11
  import { isCredentialHeader } from './explain.js';
@@ -14,6 +15,8 @@ import { MENU_RULES, runRules } from './rules/index.js';
14
15
  import { catalogFindings, readCatalog } from './catalog.js';
15
16
  import { SEVERITY_RANK } from './types.js';
16
17
  import { shellWord } from './init.js';
18
+ /** The rules about --read-resources: with all of them off, nothing is read. */
19
+ const READ_RULES = ['lists/resource-unreadable', 'lists/resource-read-schema', 'lists/resource-unread'];
17
20
  /** Establish the menu: connect, list the tools twice, run the menu rules. */
18
21
  export async function snapshot(given, options = {}) {
19
22
  const [mainIdentity, ...otherIdentities] = options.identities ?? [];
@@ -31,6 +34,7 @@ export async function snapshot(given, options = {}) {
31
34
  const reads = [];
32
35
  let undeclared = [];
33
36
  let appResources;
37
+ let resourceReads;
34
38
  try {
35
39
  first = await patiently(() => listTools(connection, options), { error: tooMany });
36
40
  const second = await patiently(() => listTools(connection, options), { error: tooMany });
@@ -58,6 +62,20 @@ export async function snapshot(given, options = {}) {
58
62
  if (options.rules?.['apps/resource'] !== 'off' && menu.tools.some((t) => resourceUriOf(t)?.startsWith('ui://'))) {
59
63
  appResources = await readAppResources(connection, menu.tools, options.timeoutMs);
60
64
  }
65
+ // --read-resources: each listed resource, read as a client does when one is picked.
66
+ // Only when the list was read, and some rule would say something about the reads.
67
+ const resources = reads.find((r) => r.kind === 'resources');
68
+ if (options.readResources && resources && !resources.first.error && READ_RULES.some((id) => options.rules?.[id] !== 'off')) {
69
+ resourceReads = await readResources(connection, resources.first.items, {
70
+ timeoutMs: options.timeoutMs,
71
+ maxReads: options.maxReads,
72
+ // A ui:// resource the Apps pass has a record for is apps/resource's, whatever it got.
73
+ appUris: (appResources ?? []).map((r) => r.uri),
74
+ second: resources.second && !resources.second.error ? resources.second.items : undefined,
75
+ protocolVersion: connection.protocolVersion,
76
+ truncated: resources.first.truncated,
77
+ });
78
+ }
61
79
  if (options.catalog) {
62
80
  menu.catalog = await readCatalog(connection, menu.tools, { ...(typeof options.catalog === 'object' ? options.catalog : {}), timeoutMs: options.timeoutMs });
63
81
  }
@@ -162,6 +180,7 @@ export async function snapshot(given, options = {}) {
162
180
  ...(offline ? { offline } : {}),
163
181
  ...(plain ? { plain } : {}),
164
182
  ...(appResources ? { appResources } : {}),
183
+ ...(resourceReads ? { resourceReads } : {}),
165
184
  ...(card ? { serverCard: card } : {}),
166
185
  ...(target.kind === 'http' ? { serverUrl: new URL(target.url).origin + new URL(target.url).pathname } : {}),
167
186
  ...(connection.era === 'legacy' && eras.has('modern') ? { laterModern: true } : {}),
@@ -181,7 +200,7 @@ export async function snapshot(given, options = {}) {
181
200
  }
182
201
  // What the agent pays: app-only tools aren't in its list.
183
202
  const cost = options.client ? clientCost(options.client, agentMenu(menu).shown) : undefined;
184
- return { menu, findings, ...(identities ? { identities } : {}), ...(cost ? { cost } : {}), ...(undeclared.length ? { notOffered: undeclared } : {}) };
203
+ return { menu, findings, ...(identities ? { identities } : {}), ...(cost ? { cost } : {}), ...(undeclared.length ? { notOffered: undeclared } : {}), ...(resourceReads ? { resourcesRead: { read: resourceReads.reads.length, listed: resourceReads.listed, ...(resourceReads.byApps ? { byApps: resourceReads.byApps } : {}) } } : {}) };
185
204
  }
186
205
  /**
187
206
  * The target with every credential it carries swapped for one that can't be valid,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "toolmenu",
3
- "version": "0.27.1",
3
+ "version": "0.28.1",
4
4
  "mcpName": "io.github.niksa90/toolmenu",
5
5
  "description": "Test your MCP server the way agents and clients meet it: the menu, the calls, the results, the sign-in, and every release after. No LLM involved.",
6
6
  "author": "Nikša Perović (https://niksa.me)",