toolmenu 0.20.1 → 0.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/README.md +119 -41
  2. package/dist/apps.d.ts +56 -0
  3. package/dist/apps.js +99 -0
  4. package/dist/auth.d.ts +14 -0
  5. package/dist/auth.js +75 -2
  6. package/dist/auto.d.ts +6 -0
  7. package/dist/auto.js +70 -7
  8. package/dist/card.d.ts +18 -0
  9. package/dist/card.js +39 -0
  10. package/dist/cli.js +108 -24
  11. package/dist/colour.d.ts +8 -0
  12. package/dist/colour.js +70 -0
  13. package/dist/config.d.ts +2 -0
  14. package/dist/config.js +2 -0
  15. package/dist/connect.d.ts +14 -0
  16. package/dist/connect.js +45 -7
  17. package/dist/diff.js +112 -13
  18. package/dist/explain.d.ts +1 -0
  19. package/dist/explain.js +11 -0
  20. package/dist/failures.d.ts +24 -0
  21. package/dist/failures.js +58 -1
  22. package/dist/help.d.ts +1 -1
  23. package/dist/help.js +36 -4
  24. package/dist/mrtr.d.ts +9 -1
  25. package/dist/mrtr.js +17 -0
  26. package/dist/options.d.ts +15 -0
  27. package/dist/options.js +5 -0
  28. package/dist/probe.d.ts +11 -1
  29. package/dist/probe.js +18 -3
  30. package/dist/report.d.ts +3 -0
  31. package/dist/report.js +15 -8
  32. package/dist/rule-docs.d.ts +26 -0
  33. package/dist/rule-docs.js +88 -0
  34. package/dist/rule-docs.json +597 -0
  35. package/dist/rules/apps.d.ts +11 -0
  36. package/dist/rules/apps.js +156 -0
  37. package/dist/rules/auth.d.ts +18 -0
  38. package/dist/rules/auth.js +29 -0
  39. package/dist/rules/capabilities.d.ts +21 -0
  40. package/dist/rules/capabilities.js +103 -0
  41. package/dist/rules/card.d.ts +7 -0
  42. package/dist/rules/card.js +65 -0
  43. package/dist/rules/clients.js +1 -0
  44. package/dist/rules/description.js +3 -0
  45. package/dist/rules/handles.d.ts +13 -0
  46. package/dist/rules/handles.js +78 -0
  47. package/dist/rules/ids.js +35 -1
  48. package/dist/rules/index.js +20 -2
  49. package/dist/rules/naming.js +3 -0
  50. package/dist/rules/network.d.ts +21 -0
  51. package/dist/rules/network.js +63 -0
  52. package/dist/rules/rule.d.ts +20 -0
  53. package/dist/rules/search.js +1 -0
  54. package/dist/rules/spec.d.ts +9 -1
  55. package/dist/rules/spec.js +117 -3
  56. package/dist/rules/write.d.ts +0 -6
  57. package/dist/rules/write.js +11 -5
  58. package/dist/scan.d.ts +47 -0
  59. package/dist/scan.js +334 -0
  60. package/dist/session.d.ts +2 -0
  61. package/dist/session.js +149 -9
  62. package/dist/snapshot.d.ts +15 -0
  63. package/dist/snapshot.js +130 -5
  64. package/dist/types.d.ts +5 -0
  65. package/dist/words.d.ts +10 -0
  66. package/dist/words.js +44 -2
  67. package/package.json +2 -2
  68. package/schemas/server-card.json +260 -0
package/dist/card.d.ts ADDED
@@ -0,0 +1,18 @@
1
+ export declare const CARD_MEDIA_TYPE = "application/mcp-server-card+json";
2
+ export interface CardRead {
3
+ /** Where it was asked for: the server URL's origin and path, then /server-card. */
4
+ url: string;
5
+ status?: number;
6
+ contentType?: string;
7
+ /** The document, when the answer was JSON. */
8
+ card?: unknown;
9
+ /** Why it couldn't be read (network, timeout). */
10
+ error?: string;
11
+ }
12
+ /** The reserved card location for a Streamable HTTP URL: its query left out, /server-card appended to its path. */
13
+ export declare function cardUrl(serverUrl: string): string;
14
+ /**
15
+ * GET the card from its reserved location. No credentials: cards are public by design,
16
+ * and the request goes to a path the MCP endpoint didn't ask to receive them on.
17
+ */
18
+ export declare function readServerCard(serverUrl: string, timeoutMs?: number): Promise<CardRead>;
package/dist/card.js ADDED
@@ -0,0 +1,39 @@
1
+ /*
2
+ * MCP Server Cards (SEP-2127, ext-server-card): a static document describing a remote
3
+ * server, read before connecting. Its reserved location is `<streamable-http-url>/server-card`,
4
+ * served as application/mcp-server-card+json. Its version and protocol versions SHOULD NOT
5
+ * contradict what the live connection reports (ext-server-card docs/discovery.md,
6
+ * "Consistency with Runtime Behavior"). Schema: schemas/server-card.json, from
7
+ * modelcontextprotocol/ext-server-card at 526201bb.
8
+ */
9
+ export const CARD_MEDIA_TYPE = 'application/mcp-server-card+json';
10
+ /** The reserved card location for a Streamable HTTP URL: its query left out, /server-card appended to its path. */
11
+ export function cardUrl(serverUrl) {
12
+ const u = new URL(serverUrl);
13
+ return `${u.origin}${u.pathname.replace(/\/+$/, '')}/server-card`;
14
+ }
15
+ /**
16
+ * GET the card from its reserved location. No credentials: cards are public by design,
17
+ * and the request goes to a path the MCP endpoint didn't ask to receive them on.
18
+ */
19
+ export async function readServerCard(serverUrl, timeoutMs = 10_000) {
20
+ const url = cardUrl(serverUrl);
21
+ try {
22
+ const response = await fetch(url, { headers: { Accept: `${CARD_MEDIA_TYPE}, application/json;q=0.9` }, signal: AbortSignal.timeout(timeoutMs), redirect: 'follow' });
23
+ const contentType = response.headers.get('content-type') ?? '';
24
+ const out = { url, status: response.status, contentType };
25
+ if (!response.ok || !/json/i.test(contentType))
26
+ return out;
27
+ const text = await response.text();
28
+ try {
29
+ out.card = JSON.parse(text);
30
+ }
31
+ catch {
32
+ // Says JSON, isn't: no card.
33
+ }
34
+ return out;
35
+ }
36
+ catch (error) {
37
+ return { url, error: (error instanceof Error ? error.message : String(error)).split('\n')[0] };
38
+ }
39
+ }
package/dist/cli.js CHANGED
@@ -1,5 +1,6 @@
1
1
  #!/usr/bin/env node
2
- import { writeFile } from 'node:fs/promises';
2
+ import { colourFor, colourise, colouriseError } from './colour.js';
3
+ import { mkdir, writeFile } from 'node:fs/promises';
3
4
  import { join } from 'node:path';
4
5
  import { parseArgs } from 'node:util';
5
6
  import { CLIENT_NAMES, CLIENTS } from './clients.js';
@@ -24,6 +25,9 @@ import { existingMessage, initReport, planInit, shellWord, writeInit } from './i
24
25
  import { SEVERITY_RANK } from './types.js';
25
26
  import { VERSION } from './version.js';
26
27
  import { CLI_OPTIONS } from './options.js';
28
+ import { editDistance } from './words.js';
29
+ import { formatScan, ListError, loadList, scan, scanExit } from './scan.js';
30
+ import { explain, findRule, formatExplained, listRules, ruleDocs } from './rule-docs.js';
27
31
  import { commandHelp, commandOptions, isCommand, overview, unknownCommand } from './help.js';
28
32
  class UsageError extends Error {
29
33
  }
@@ -61,9 +65,22 @@ export async function main(argv) {
61
65
  process.stdout.write(sub && isCommand(sub) ? commandHelp(sub) : overview());
62
66
  return sub || values.help ? 0 : 2;
63
67
  }
68
+ // An option another command takes is ignored here: say so, or scan --no-auth reads as
69
+ // done while the stored logins are used anyway. A warning, not an error: CI scripts pass
70
+ // the shared options (--timeout) to every command.
71
+ const takes = new Set([...commandOptions(sub), 'help', 'version']);
72
+ const at = (k) => before.findIndex((a) => a === `--${k}` || a.startsWith(`--${k}=`));
73
+ // In the order they were typed.
74
+ const stray = Object.keys(values).filter((k) => !takes.has(k)).sort((a, b) => at(a) - at(b)).map((k) => `--${k}`);
75
+ if (stray.length) {
76
+ const one = stray.length === 1;
77
+ process.stderr.write(`toolmenu: ${sub} ignores ${stray.join(', ')}: ${one ? 'it is' : 'they are'} for other commands.\n → Next: Leave ${one ? 'it' : 'them'} out to silence this; toolmenu ${sub} --help lists the options ${sub} takes.\n`);
78
+ }
64
79
  const format = (values.json ? 'json' : values.format ?? 'text');
65
80
  if (!['text', 'json', 'github', 'markdown'].includes(format))
66
81
  throw new UsageError(`--format must be text, json, github or markdown`);
82
+ // Colour for a report read in a terminal (colour.ts); piped, CI and other formats stay plain.
83
+ const show = (report) => (format === 'text' && colourFor(process.stdout) ? colourise(report) : report);
67
84
  const failOn = (values['fail-on'] ?? 'error');
68
85
  if (!(failOn in SEVERITY_RANK))
69
86
  throw new UsageError(`--fail-on must be error, warn or info`);
@@ -72,6 +89,8 @@ export async function main(argv) {
72
89
  throw new UsageError(`--timeout must be a positive number of milliseconds`);
73
90
  if (sub === 'auth')
74
91
  return authCommand(rest, values);
92
+ if (sub === 'explain')
93
+ return explainCommand(rest, command, format);
75
94
  // The invocation up to the server, for examples in messages: a session example
76
95
  // without --auto or --scenario wouldn't run.
77
96
  const scenarioFlag = values.scenario ? ` --scenario ${shellWord(values.scenario)}` : '';
@@ -94,6 +113,8 @@ export async function main(argv) {
94
113
  throw new UsageError('--client goes with snapshot.');
95
114
  if (values.client !== undefined && !Object.hasOwn(CLIENTS, values.client))
96
115
  throw new UsageError(`--client must be one of ${CLIENT_NAMES.join(', ')}`);
116
+ if (values['offline-check'] && sub !== 'snapshot')
117
+ throw new UsageError('--offline-check goes with snapshot.');
97
118
  if (values.as !== undefined && sub !== 'snapshot')
98
119
  throw new UsageError('--as goes with snapshot: it lists the menu once per identity.');
99
120
  if (values.elicitation !== undefined && sub !== 'session')
@@ -103,6 +124,58 @@ export async function main(argv) {
103
124
  const processes = values.processes !== undefined ? Number(values.processes) : config.processes ?? 2;
104
125
  if (!Number.isInteger(processes) || processes < 1)
105
126
  throw new UsageError('--processes must be a whole number, 1 or more');
127
+ if (sub === 'scan') {
128
+ if (command)
129
+ throw new UsageError('scan reads its servers from a list file; give the file, not a command.');
130
+ if (rest.length !== 1)
131
+ throw new UsageError('scan needs one list: an MCP client config (mcp.json) or a text file with a server per line.');
132
+ const concurrency = values.concurrency !== undefined ? Number(values.concurrency) : 4;
133
+ if (!Number.isInteger(concurrency) || concurrency < 1)
134
+ throw new UsageError('--concurrency must be a whole number, 1 or more');
135
+ let entries;
136
+ try {
137
+ entries = await loadList(rest[0]);
138
+ }
139
+ catch (error) {
140
+ if (error instanceof ListError)
141
+ throw new UsageError(error.message);
142
+ throw error;
143
+ }
144
+ const noAuth = values['no-auth'] === true;
145
+ const withProtocol = entries.map((e) => {
146
+ if (!e.target || e.target.kind !== 'http')
147
+ return e.target && protocol !== 'auto' ? { ...e, target: { ...e.target, protocol } } : e;
148
+ return { ...e, target: { ...e.target, ...(protocol !== 'auto' ? { protocol } : {}), ...(noAuth ? { noAuth } : {}) } };
149
+ });
150
+ const outDir = values['out-dir'];
151
+ if (outDir)
152
+ await mkdir(outDir, { recursive: true });
153
+ const tty = process.stderr.isTTY;
154
+ const rows = await scan(withProtocol, {
155
+ timeoutMs,
156
+ processes,
157
+ concurrency,
158
+ rules: config.rules,
159
+ ignore: config.ignore,
160
+ descriptionLimit: config.descriptionLimit,
161
+ fullDescriptions: config.fullDescriptions,
162
+ ...(config.client ? { client: config.client } : {}),
163
+ // stdio servers only: snapshot skips it for HTTP.
164
+ ...(config.offlineCheck ? { offlineCheck: true } : {}),
165
+ onDone: (row, done, total) => {
166
+ if (tty)
167
+ process.stderr.write(`\r\x1b[K ${done}/${total} ${row.name}`);
168
+ },
169
+ });
170
+ if (tty)
171
+ process.stderr.write('\r\x1b[K');
172
+ if (outDir)
173
+ for (const r of rows)
174
+ if (r.menu)
175
+ await writeFile(join(outDir, `${r.name.replace(/[^\w.@-]+/g, '_')}.json`), JSON.stringify(r.menu, null, 2) + '\n');
176
+ process.stdout.write(show(formatScan(rows, format, rest[0])) + '\n');
177
+ return scanExit(rows, failOn);
178
+ }
106
179
  if (sub === 'diff') {
107
180
  if (command)
108
181
  throw new UsageError('diff compares two menu files; it doesn\'t start a server. Run snapshot first.');
@@ -117,7 +190,7 @@ export async function main(argv) {
117
190
  release,
118
191
  serverVersionIsRelease: values['server-version-is-release'] ?? config.serverVersionIsRelease,
119
192
  });
120
- process.stdout.write(formatDiff(result, before.tools.length, after.tools.length, format) + '\n');
193
+ process.stdout.write(show(formatDiff(result, before.tools.length, after.tools.length, format)) + '\n');
121
194
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
122
195
  }
123
196
  if (sub === 'history') {
@@ -150,7 +223,7 @@ export async function main(argv) {
150
223
  });
151
224
  if (values.csv)
152
225
  await writeFile(values.csv, historyCsv(result));
153
- process.stdout.write(formatHistory(result, format, outDir, values.csv) + '\n');
226
+ process.stdout.write(show(formatHistory(result, format, outDir, values.csv)) + '\n');
154
227
  return result.rows.length > 0 && result.rows.every((r) => r.status === 'failed') ? 1 : 0;
155
228
  }
156
229
  if (sub === 'session' && values.init) {
@@ -192,7 +265,7 @@ export async function main(argv) {
192
265
  const plan = planInit({ cwd: process.cwd(), target, out: values.out, session: values['with-session'] });
193
266
  if (plan.existing.length)
194
267
  throw new UsageError(existingMessage(plan));
195
- const { menu, findings } = await snapshot(target, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
268
+ const { menu, findings } = await snapshot(target, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions, ...(config.offlineCheck && target.kind === 'stdio' ? { offlineCheck: true } : {}) });
196
269
  await writeInit(plan, JSON.stringify(menu, null, 2) + '\n');
197
270
  process.stdout.write(initReport(plan, { server: menu.server.name, version: menu.server.version, tools: menu.tools.length, tokens: menu.totalTokens, counts: counts(findings) }, target));
198
271
  return 0;
@@ -229,7 +302,7 @@ export async function main(argv) {
229
302
  const menu = await probeMenu(seeded(autoTarget, MAIN_SEED), timeoutMs, undefined, waited).catch((error) => {
230
303
  throw refusedForTooMany(error, waited.ms);
231
304
  });
232
- const options = { openWorld: values['open-world'], values: given, assumeReadOnly };
305
+ const options = { openWorld: values['open-world'], createHandles: values['create-handles'], values: given, assumeReadOnly };
233
306
  let plan = autoScenario(menu, { ...options, maxCalls: givenMax ?? 20 });
234
307
  // Each unlock value gets its own budget for the tools it brings, so the first
235
308
  // toolsets can't use up the calls the last ones need. --max-calls, when given,
@@ -280,7 +353,7 @@ export async function main(argv) {
280
353
  await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
281
354
  const output = formatSession(result, format);
282
355
  if (output)
283
- process.stdout.write(output + '\n');
356
+ process.stdout.write(show(output) + '\n');
284
357
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
285
358
  }
286
359
  if (sub === 'session') {
@@ -305,7 +378,7 @@ export async function main(argv) {
305
378
  await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
306
379
  const output = formatSession(result, format);
307
380
  if (output)
308
- process.stdout.write(output + '\n');
381
+ process.stdout.write(show(output) + '\n');
309
382
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
310
383
  }
311
384
  const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
@@ -313,13 +386,16 @@ export async function main(argv) {
313
386
  const routesPath = values.routes ?? config.routes;
314
387
  const routes = routesPath ? await loadRoutes(routesPath) : undefined;
315
388
  const client = values.client ?? config.client;
316
- const { menu, findings, cost, notOffered } = await snapshot(target, { 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 });
389
+ const offlineCheck = values['offline-check'] ?? config.offlineCheck;
390
+ if (values['offline-check'] && target.kind !== 'stdio')
391
+ throw new UsageError("--offline-check goes with a stdio server: an HTTP server's network isn't this machine's to cut.");
392
+ 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 });
317
393
  const outPath = values['no-write'] ? undefined : values.out ?? 'menu.json';
318
394
  if (outPath)
319
395
  await writeFile(outPath, JSON.stringify(menu, null, 2) + '\n');
320
396
  const output = formatSnapshot(menu, findings, format, outPath, cost, notOffered);
321
397
  if (output)
322
- process.stdout.write(output + '\n');
398
+ process.stdout.write(show(output) + '\n');
323
399
  return findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
324
400
  }
325
401
  function parseTarget(positionals, command, headers, env, noAuth, prefix, protocol) {
@@ -364,7 +440,7 @@ async function authCommand(args, values) {
364
440
  throw new UsageError('--port must be a port number');
365
441
  if (values['client-secret'] && !values['client-id'])
366
442
  throw new UsageError('--client-secret goes with --client-id');
367
- const result = await login(url, { port, scope: values.scope, clientId: values['client-id'], clientSecret: values['client-secret'] });
443
+ const result = await login(url, { port, scope: values.scope, clientId: values['client-id'], clientSecret: values['client-secret'], noBrowser: values['no-browser'] });
368
444
  process.stdout.write(`Logged in to ${result.name ?? url} (${url}): it lists ${result.tools} tool${result.tools === 1 ? '' : 's'} with this login.\nsnapshot and session use it from now on (--no-auth to skip it); stored in ${authDir()}.\n`);
369
445
  return 0;
370
446
  }
@@ -434,9 +510,30 @@ for (const method of ['log', 'info', 'debug']) {
434
510
  console[method] = (...args) => console.error(...args);
435
511
  }
436
512
  main(process.argv.slice(2)).then(exitWhenFlushed, (error) => {
437
- process.stderr.write(`toolmenu: ${failureMessage(error)}\n`);
513
+ const message = `toolmenu: ${failureMessage(error)}`;
514
+ process.stderr.write(`${colourFor(process.stderr) ? colouriseError(message) : message}\n`);
438
515
  exitWhenFlushed(2);
439
516
  });
517
+ function explainCommand(rest, command, format) {
518
+ if (command)
519
+ throw new UsageError("explain takes a rule's name, not a server.");
520
+ if (format !== 'text' && format !== 'json')
521
+ throw new UsageError('explain prints text, or JSON with --json.');
522
+ if (rest.length > 1)
523
+ throw new UsageError(`explain takes one rule at a time; got ${rest.length}.`);
524
+ if (!rest.length) {
525
+ process.stdout.write(format === 'json' ? `${JSON.stringify(Object.keys(ruleDocs()))}\n` : listRules());
526
+ return 0;
527
+ }
528
+ const found = findRule(rest[0]);
529
+ if ('near' in found) {
530
+ const hint = found.near.length ? ` Did you mean ${found.near.join(', ')}?` : '';
531
+ throw new UsageError(`No rule "${rest[0]}".${hint} toolmenu explain lists every rule.`);
532
+ }
533
+ const e = explain(found.id);
534
+ process.stdout.write(format === 'json' ? `${JSON.stringify(e, null, 2)}\n` : formatExplained(e));
535
+ return 0;
536
+ }
440
537
  /** What stopped the command. A mistyped option gets the nearest real one. */
441
538
  function failureMessage(error) {
442
539
  const message = error instanceof Error ? error.message : String(error);
@@ -471,19 +568,6 @@ function commandIn(args) {
471
568
  }
472
569
  return undefined;
473
570
  }
474
- function editDistance(a, b) {
475
- const row = Array.from({ length: b.length + 1 }, (_, i) => i);
476
- for (let i = 1; i <= a.length; i++) {
477
- let diagonal = row[0];
478
- row[0] = i;
479
- for (let j = 1; j <= b.length; j++) {
480
- const above = row[j];
481
- row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
482
- diagonal = above;
483
- }
484
- }
485
- return row[b.length];
486
- }
487
571
  function parseRelease(value) {
488
572
  const m = /^(.+?)\.\.(.+)$/.exec(value);
489
573
  if (!m)
@@ -0,0 +1,8 @@
1
+ /** Whether text written to this stream gets colour. */
2
+ export declare function colourFor(stream: {
3
+ isTTY?: boolean;
4
+ }, env?: NodeJS.ProcessEnv): boolean;
5
+ /** The report with ANSI colour: the same characters otherwise. */
6
+ export declare function colourise(text: string): string;
7
+ /** An error that stopped a command, with colour: what failed, the labelled evidence, the next step. */
8
+ export declare function colouriseError(text: string): string;
package/dist/colour.js ADDED
@@ -0,0 +1,70 @@
1
+ /*
2
+ * Colour for text output in a terminal: severities, the next step, the verdict. Applied
3
+ * to the finished text, line by line, so every command's report gets it the same way
4
+ * and the text itself never depends on it. Only when the stream is a terminal, unless
5
+ * NO_COLOR (https://no-color.org) or FORCE_COLOR says otherwise; never for json,
6
+ * markdown or github output.
7
+ */
8
+ const ESC = '\x1b[';
9
+ const paint = (codes, text) => (text ? `${ESC}${codes}m${text}${ESC}0m` : text);
10
+ const SEVERITY = { ERROR: '1;31', WARN: '1;33', INFO: '1;36' };
11
+ /** Whether text written to this stream gets colour. */
12
+ export function colourFor(stream, env = process.env) {
13
+ if (env.NO_COLOR !== undefined && env.NO_COLOR !== '')
14
+ return false;
15
+ if (env.FORCE_COLOR !== undefined)
16
+ return env.FORCE_COLOR !== '0' && env.FORCE_COLOR !== 'false';
17
+ return !!stream.isTTY && env.TERM !== 'dumb';
18
+ }
19
+ /** The report with ANSI colour: the same characters otherwise. */
20
+ export function colourise(text) {
21
+ // Lines deeper than the current finding's message are its evidence: dimmed.
22
+ let evidenceFrom;
23
+ return text
24
+ .split('\n')
25
+ .map((line) => {
26
+ const indent = line.length - line.trimStart().length;
27
+ const finding = /^(\s*)(ERROR|WARN|INFO)(\s+)(\S+)(.*)$/.exec(line);
28
+ if (finding) {
29
+ const [, lead, severity, gap, rule, rest] = finding;
30
+ evidenceFrom = lead.length + severity.length + gap.length + 1;
31
+ return `${lead}${paint(SEVERITY[severity], severity)}${gap}${paint('1', rule)}${rest.replace(/ · unsure\b/, paint('2;3', ' · unsure'))}`;
32
+ }
33
+ const next = /^(\s*)(→ Next:)(.*)$/.exec(line);
34
+ if (next)
35
+ return `${next[1]}${paint('1;32', next[2])}${paint('32', next[3])}`;
36
+ if (!line.trim() || indent === 0)
37
+ evidenceFrom = undefined;
38
+ if (evidenceFrom !== undefined && indent >= evidenceFrom)
39
+ return paint('2', line);
40
+ if (/^✗ /.test(line))
41
+ return paint('1;31', line);
42
+ if (/^✓ /.test(line))
43
+ return paint('1;32', line);
44
+ const title = /^(toolmenu \w+)(.*)$/.exec(line);
45
+ if (title)
46
+ return `${paint('1;35', title[1])}${paint('1', title[2])}`;
47
+ const step = /^((?:step \d+|final):)(.*)$/.exec(line);
48
+ if (step)
49
+ return `${paint('1', step[1])}${step[2].replace(/menu changed/g, paint('33', 'menu changed'))}`;
50
+ return line;
51
+ })
52
+ .join('\n');
53
+ }
54
+ /** An error that stopped a command, with colour: what failed, the labelled evidence, the next step. */
55
+ export function colouriseError(text) {
56
+ return text
57
+ .split('\n')
58
+ .map((line) => {
59
+ if (line.startsWith('toolmenu: '))
60
+ return `${paint('1;31', 'toolmenu:')}${paint('1', line.slice('toolmenu:'.length))}`;
61
+ const next = /^(\s*)(→ Next:)(.*)$/.exec(line);
62
+ if (next)
63
+ return `${next[1]}${paint('1;32', next[2])}${paint('32', next[3])}`;
64
+ const field = /^(\s{2})([a-z][a-z -]*?)(\s{2,})(.*)$/.exec(line);
65
+ if (field)
66
+ return `${field[1]}${paint('2', field[2])}${field[3]}${field[4]}`;
67
+ return line;
68
+ })
69
+ .join('\n');
70
+ }
package/dist/config.d.ts CHANGED
@@ -30,6 +30,8 @@ export interface Config {
30
30
  lists?: string[];
31
31
  /** snapshot: the client to check the menu for (claude-code, claude-api-search, openai). --client wins. */
32
32
  client?: string;
33
+ /** snapshot (stdio): also list the menu with the network cut off. --offline-check turns it on too. */
34
+ offlineCheck?: boolean;
33
35
  /** Server processes (stdio) or connections (HTTP) to compare, the main one included (default 2). */
34
36
  processes?: number;
35
37
  /**
package/dist/config.js CHANGED
@@ -34,6 +34,8 @@ export async function loadConfig(path) {
34
34
  if (config.lists !== undefined && !(Array.isArray(config.lists) && config.lists.every((l) => LIST_WORDS.includes(l)))) {
35
35
  throw new Error(`${file}: lists must be a list of ${LIST_WORDS.join(', ')}`);
36
36
  }
37
+ if (config.offlineCheck !== undefined && typeof config.offlineCheck !== 'boolean')
38
+ throw new Error(`${file}: offlineCheck must be true or false`);
37
39
  if (config.client !== undefined && !(typeof config.client === 'string' && Object.hasOwn(CLIENTS, config.client))) {
38
40
  throw new Error(`${file}: client must be one of ${Object.keys(CLIENTS).join(', ')}`);
39
41
  }
package/dist/connect.d.ts CHANGED
@@ -16,6 +16,7 @@ export type Target = {
16
16
  cwd?: string;
17
17
  protocol?: Protocol;
18
18
  elicitation?: Elicitation;
19
+ apps?: boolean;
19
20
  } | {
20
21
  kind: 'http';
21
22
  url: string;
@@ -23,7 +24,12 @@ export type Target = {
23
24
  noAuth?: boolean;
24
25
  protocol?: Protocol;
25
26
  elicitation?: Elicitation;
27
+ apps?: boolean;
26
28
  };
29
+ /** The MCP Apps extension (ext-apps): interactive UI a tool names in _meta.ui.resourceUri. */
30
+ export declare const APPS_EXTENSION = "io.modelcontextprotocol/ui";
31
+ /** The one content type an MCP App's resource may have. */
32
+ export declare const APPS_MIME_TYPE = "text/html;profile=mcp-app";
27
33
  export interface WireResponse {
28
34
  method: string;
29
35
  result?: Record<string, unknown>;
@@ -78,5 +84,13 @@ export interface ToolList {
78
84
  /** Set when the SDK client rejected the result (toolmenu still reads it off the wire). */
79
85
  clientError?: string;
80
86
  }
87
+ /**
88
+ * The proxy and CA settings of this process, for a stdio server: the SDK passes a
89
+ * minimal environment (PATH, HOME…), so a server that calls an API at startup (Stripe,
90
+ * Supabase) couldn't get out behind a proxy and failed with nothing to say why. Node's
91
+ * fetch reads HTTPS_PROXY only with NODE_USE_ENV_PROXY=1, so that's set too when a proxy
92
+ * is. --env overrides each.
93
+ */
94
+ export declare function proxyEnvironment(env?: NodeJS.ProcessEnv): Record<string, string>;
81
95
  /** One full `tools/list`, bypassing the SDK's cache, read from the wire rather than the SDK's parsed copy. */
82
96
  export declare function listTools(connection: Connection, options?: ConnectOptions): Promise<ToolList>;
package/dist/connect.js CHANGED
@@ -48,6 +48,10 @@ export async function quietExclusions(work) {
48
48
  export const PROTOCOLS = ['auto', 'legacy', 'modern'];
49
49
  export const MODERN_VERSION = '2026-07-28';
50
50
  export const ELICITATIONS = ['decline', 'cancel'];
51
+ /** The MCP Apps extension (ext-apps): interactive UI a tool names in _meta.ui.resourceUri. */
52
+ export const APPS_EXTENSION = 'io.modelcontextprotocol/ui';
53
+ /** The one content type an MCP App's resource may have. */
54
+ export const APPS_MIME_TYPE = 'text/html;profile=mcp-app';
51
55
  /** Every response the server sent, matched to the request method, as it came off the wire. */
52
56
  export class WireLog {
53
57
  responses = [];
@@ -93,13 +97,25 @@ export class WireLog {
93
97
  export async function connect(target, options = {}) {
94
98
  const client = new Client({ name: 'toolmenu', version: VERSION }, {
95
99
  versionNegotiation: { mode: target.protocol === 'legacy' ? 'legacy' : target.protocol === 'modern' ? { pin: MODERN_VERSION } : 'auto' },
96
- // Only for session (target.elicitation set): a connection that calls tools
97
- // declares elicitation, form and URL mode, so a tool that asks the user something
98
- // runs its "the user said no" path instead of failing (2026-07-28 multi
99
- // round-trip requests). snapshot and the rest declare nothing, as before 0.16:
100
- // a server may list different tools to a client that can be asked things.
100
+ // With target.elicitation set, the connection declares elicitation, form and URL
101
+ // mode: session, so a tool that asks the user something runs its "the user said
102
+ // no" path instead of failing (2026-07-28 multi round-trip requests); and, from
103
+ // 0.22, snapshot's listing, since a server may list more tools to a client that
104
+ // can be asked things (github-mcp-server's delete_repository). snapshot lists
105
+ // once more without it (menu/capability-dependent).
101
106
  // Never roots or sampling: 2026-07-28 deprecates them (SEP-2577).
102
- ...(target.elicitation ? { capabilities: { elicitation: { form: {}, url: {} } } } : {}),
107
+ // With target.apps, the MCP Apps extension too: a server MAY register different tools,
108
+ // or other variants of them, for a host that renders apps (ext-apps, "Servers SHOULD
109
+ // check client capabilities before registering UI-enabled tools"), so the baseline
110
+ // is listed as such a host, as for elicitation.
111
+ ...(target.elicitation || target.apps
112
+ ? {
113
+ capabilities: {
114
+ ...(target.elicitation ? { elicitation: { form: {}, url: {} } } : {}),
115
+ ...(target.apps ? { extensions: { [APPS_EXTENSION]: { mimeTypes: [APPS_MIME_TYPE] } } } : {}),
116
+ },
117
+ }
118
+ : {}),
103
119
  });
104
120
  // A 2025 server asks with an elicitation/create request; 2026-07-28 ones embed it
105
121
  // in an input_required result, which session answers itself (mrtr.ts). Same answer.
@@ -115,7 +131,7 @@ export async function connect(target, options = {}) {
115
131
  const stdio = new StdioClientTransport({
116
132
  command: target.command,
117
133
  args: target.args,
118
- env: { ...getDefaultEnvironment(), ...target.env },
134
+ env: { ...getDefaultEnvironment(), ...proxyEnvironment(), ...target.env },
119
135
  cwd: target.cwd,
120
136
  stderr: 'pipe',
121
137
  });
@@ -289,6 +305,28 @@ function tracedFetch(trace) {
289
305
  return response;
290
306
  };
291
307
  }
308
+ /**
309
+ * The proxy and CA settings of this process, for a stdio server: the SDK passes a
310
+ * minimal environment (PATH, HOME…), so a server that calls an API at startup (Stripe,
311
+ * Supabase) couldn't get out behind a proxy and failed with nothing to say why. Node's
312
+ * fetch reads HTTPS_PROXY only with NODE_USE_ENV_PROXY=1, so that's set too when a proxy
313
+ * is. --env overrides each.
314
+ */
315
+ export function proxyEnvironment(env = process.env) {
316
+ const proxied = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy'].some((k) => env[k]);
317
+ const names = [
318
+ ...(proxied ? ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy', 'NO_PROXY', 'no_proxy'] : []),
319
+ // Certificates a proxy that inspects TLS needs trusted, by Node, Python and curl.
320
+ 'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE', 'SSL_CERT_DIR', 'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE',
321
+ ];
322
+ const out = {};
323
+ for (const k of names)
324
+ if (env[k])
325
+ out[k] = env[k];
326
+ if (proxied)
327
+ out.NODE_USE_ENV_PROXY = env.NODE_USE_ENV_PROXY || '1';
328
+ return out;
329
+ }
292
330
  /** One full `tools/list`, bypassing the SDK's cache, read from the wire rather than the SDK's parsed copy. */
293
331
  export async function listTools(connection, options = {}) {
294
332
  const mark = connection.wire.responses.length;