toolmenu 0.27.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/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/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))
@@ -482,7 +493,7 @@ export async function main(given) {
482
493
  if (values.value || values['values-file'] || values['assume-read-only'])
483
494
  throw new UsageError('--value, --values-file and --assume-read-only go with --auto. In a scenario, write the values into the steps\' args, and list tools under assume_read_only.');
484
495
  if (!values.scenario)
485
- throw new UsageError('session needs --scenario <file>. Run session --init for a starter, or see https://github.com/niksa90/toolmenu#session-the-menu-changing-while-the-agent-works for the format.');
496
+ throw new UsageError('session needs --scenario <file>. Run session --init for a starter, or see https://github.com/niksa90/toolmenu/blob/main/docs/session.md for the format.');
486
497
  let scenario;
487
498
  try {
488
499
  scenario = await loadScenario(values.scenario);
@@ -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).
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
  });
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',
@@ -220,8 +222,8 @@ const HELP = {
220
222
  summary: 'serve toolmenu to an agent as an MCP server (stdio)',
221
223
  usage: ['toolmenu mcp'],
222
224
  about: [
223
- 'An MCP server over stdio, for the agent building your server: snapshot_menu, diff_menus,',
224
- 'check_session and explain_rule, each running the matching command. Relative paths and',
225
+ 'An MCP server over stdio, for the agent building your server: snapshot_menu, check_session,',
226
+ 'diff_menus, review_baseline, check_auth and explain_rule, each running the matching command. Relative paths and',
225
227
  'toolmenu.config.json resolve from the folder it runs in, or a tool call\'s cwd.',
226
228
  'Claude Code: claude mcp add toolmenu -- npx -y toolmenu mcp',
227
229
  ],
package/dist/mcp.d.ts CHANGED
@@ -30,7 +30,7 @@ type Text = {
30
30
  isError?: boolean;
31
31
  };
32
32
  /** A CLI run as a tool result. Findings are a report, not a failure: only exit 2 (couldn't run) is an error. */
33
- export declare function toResult(run: CliRun): Text;
33
+ export declare function toResult(run: CliRun, exitOne?: string): Text;
34
34
  type ServerArgs = {
35
35
  command?: string[];
36
36
  url?: string;
package/dist/mcp.js CHANGED
@@ -141,14 +141,14 @@ export function runCli(args, cwd, options = {}) {
141
141
  });
142
142
  }
143
143
  /** A CLI run as a tool result. Findings are a report, not a failure: only exit 2 (couldn't run) is an error. */
144
- export function toResult(run) {
144
+ export function toResult(run, exitOne = '\n\nExit 1: there are error-level findings.') {
145
145
  const out = run.stdout.trim();
146
146
  if (run.code === 2) {
147
147
  const why = [run.stopped, run.stderr.trim()].filter(Boolean).join('\n\n') || out || 'toolmenu exited with code 2.';
148
148
  return { content: [{ type: 'text', text: why }], isError: true };
149
149
  }
150
150
  const notes = run.stderr.trim();
151
- const tail = run.code === 1 ? '\n\nExit 1: there are error-level findings.' : '';
151
+ const tail = run.code === 1 ? exitOne : '';
152
152
  return { content: [{ type: 'text', text: `${out || 'No output.'}${tail}${notes ? `\n\nNotes:\n${notes}` : ''}` }] };
153
153
  }
154
154
  const serverShape = {
@@ -252,10 +252,11 @@ const failed = (text) => ({ content: [{ type: 'text', text }], isError: true });
252
252
  export function build(baseCwd = process.cwd()) {
253
253
  const server = new McpServer({ name: 'toolmenu', version: VERSION }, {
254
254
  capabilities: { tools: {} },
255
- // The same four tools for everyone, always: an hour, and shared caches may keep it.
255
+ // The same six tools for everyone, always: an hour, and shared caches may keep it.
256
256
  cacheHints: { 'tools/list': { ttlMs: 3_600_000, cacheScope: 'public' }, 'server/discover': { ttlMs: 3_600_000, cacheScope: 'public' } },
257
- instructions: "toolmenu checks an MCP server's tool list (its menu) the way clients and agents meet it. " +
258
- 'After changing a server\'s tools: snapshot_menu for findings and token cost, diff_menus against the committed menu.json for breaking changes, check_session to see whether the menu changes mid-session. ' +
257
+ instructions: 'toolmenu tests an MCP server the way clients and agents meet it: the tool list (its menu), the calls, the results, the sign-in, and the next release. ' +
258
+ 'After changing a server\'s tools: snapshot_menu for findings and token cost, check_session to call its read-only tools and see whether results match their schemas and whether the menu changes mid-session, ' +
259
+ 'diff_menus against the committed menu.json for breaking changes, and review_baseline before replacing that baseline. check_auth for an HTTP server that answers 401. ' +
259
260
  'Each finding ends with a → Next: step; explain_rule says what a rule checks.',
260
261
  });
261
262
  /** Run a command for a server: the folder checked, credentials kept out of argv. */
@@ -269,7 +270,7 @@ export function build(baseCwd = process.cwd()) {
269
270
  return toResult(await runCli([...args(f.dir, s), ...s.after], f.dir, { secretArgs: s.secret, signal: ctx.mcpReq.signal }));
270
271
  };
271
272
  server.registerTool('snapshot_menu', {
272
- description: "Check an MCP server's tool list: start or connect to it, list its tools, and report findings (what agents misread, what breaks clients or prompt caches) and the token cost. " +
273
+ description: "Check an MCP server's tool list as a client reads it: start or connect to it, list its tools, and report findings (what clients reject, what breaks prompt caches, what agents misread) and the token cost. " +
273
274
  'A command server is started by running command as given, so only pass a command you would run yourself. ' +
274
275
  'Writes the menu file only when save_as is given (the baseline for diff_menus): a new file inside cwd, or an existing menu file there.',
275
276
  inputSchema: {
@@ -315,7 +316,7 @@ export function build(baseCwd = process.cwd()) {
315
316
  return toResult(await runCli(args, f.dir, { signal: ctx.mcpReq.signal }));
316
317
  });
317
318
  server.registerTool('check_session', {
318
- description: "Check whether an MCP server's menu changes while an agent works: call its tools marked readOnlyHint whose arguments the schema can fill, list the menu after each call, and report each change with the call that caused it. " +
319
+ description: "Call an MCP server's tools as an agent would and check what comes back: its tools marked readOnlyHint whose arguments the schema can fill are called, each result is checked against the tool's outputSchema, and the menu is listed after each call, with each change reported with the call that caused it. " +
319
320
  'Calls only read-only tools; never one marked openWorldHint unless open_world is set. A command server is started by running command as given, so only pass a command you would run yourself.',
320
321
  inputSchema: {
321
322
  ...serverShape,
@@ -330,6 +331,45 @@ export function build(baseCwd = process.cwd()) {
330
331
  ...(a.max_calls ? [`--max-calls=${a.max_calls}`] : []),
331
332
  ...(a.open_world ? ['--open-world'] : []),
332
333
  ]));
334
+ server.registerTool('review_baseline', {
335
+ description: 'Say whether a new menu file should replace the baseline: one verdict (unchanged, safe, breaking-released, breaking, review), what breaks callers, and which findings the new menu adds, clears or makes worse. ' +
336
+ 'Use it before overwriting a committed menu.json. Reads the two files only and starts no server.',
337
+ inputSchema: {
338
+ baseline: z.string().describe('The menu file to replace, e.g. the committed menu.json.'),
339
+ candidate: z.string().describe('The new menu file, e.g. new-menu.json from snapshot_menu save_as.'),
340
+ release: z.string().optional().describe('The release versions, so breaking changes pass when the bump allows them: "1.4.0..2.0.0".'),
341
+ cwd: serverShape.cwd,
342
+ },
343
+ annotations: { title: 'Review a new menu against the baseline', readOnlyHint: true, openWorldHint: false },
344
+ }, async (a, ctx) => {
345
+ const f = folder(baseCwd, a.cwd);
346
+ if ('error' in f)
347
+ return failed(f.error);
348
+ const args = ['review', ...(a.release ? [`--release=${a.release}`] : []), absolute(f.dir, a.baseline), absolute(f.dir, a.candidate)];
349
+ const run = await runCli(args, f.dir, { signal: ctx.mcpReq.signal });
350
+ // Exit 1 here is the verdict (don't accept as is), which the report already leads with.
351
+ return toResult(run, "\n\nExit 1: the verdict is not to accept the new menu as it is.");
352
+ });
353
+ server.registerTool('check_auth', {
354
+ description: "Check an HTTP MCP server's OAuth discovery the way a client that follows the spec walks it, without logging in: the 401 and its WWW-Authenticate, the protected resource metadata, the authorization server's metadata, PKCE and registration. " +
355
+ 'Use it when a server answers 401 or a client cannot sign in. Sends unauthenticated requests to the URL and to the metadata addresses it names; no credentials, no tokens.',
356
+ inputSchema: { url: z.string().describe('The Streamable HTTP endpoint: https://mcp.example.com/mcp.') },
357
+ annotations: { title: "Check a server's OAuth discovery", readOnlyHint: true, openWorldHint: true },
358
+ }, async (a, ctx) => {
359
+ // The check is of what a client sees before it has credentials, so the URL carries none.
360
+ let parsed;
361
+ try {
362
+ parsed = new URL(a.url);
363
+ }
364
+ catch {
365
+ // not a URL: said below
366
+ }
367
+ if (parsed?.protocol !== 'https:')
368
+ return failed('url must be an https URL, such as https://mcp.example.com/mcp: OAuth discovery is checked over https.');
369
+ if (parsed.username || parsed.password)
370
+ return failed('Drop the user:password@ part of the URL: the check is made without credentials.');
371
+ return toResult(await runCli(['auth', 'check', a.url], baseCwd, { signal: ctx.mcpReq.signal }));
372
+ });
333
373
  server.registerTool('explain_rule', {
334
374
  description: "Explain a toolmenu rule by the name a finding gives (naming/vague-id): what it checks, its default level and how to change it. Without rule, lists every rule.",
335
375
  inputSchema: { rule: z.string().optional().describe('The rule, as a finding names it: naming/vague-id, or just vague-id.') },
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;