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.
- package/README.md +119 -41
- package/dist/apps.d.ts +56 -0
- package/dist/apps.js +99 -0
- package/dist/auth.d.ts +14 -0
- package/dist/auth.js +75 -2
- package/dist/auto.d.ts +6 -0
- package/dist/auto.js +70 -7
- package/dist/card.d.ts +18 -0
- package/dist/card.js +39 -0
- package/dist/cli.js +108 -24
- package/dist/colour.d.ts +8 -0
- package/dist/colour.js +70 -0
- package/dist/config.d.ts +2 -0
- package/dist/config.js +2 -0
- package/dist/connect.d.ts +14 -0
- package/dist/connect.js +45 -7
- package/dist/diff.js +112 -13
- package/dist/explain.d.ts +1 -0
- package/dist/explain.js +11 -0
- package/dist/failures.d.ts +24 -0
- package/dist/failures.js +58 -1
- package/dist/help.d.ts +1 -1
- package/dist/help.js +36 -4
- package/dist/mrtr.d.ts +9 -1
- package/dist/mrtr.js +17 -0
- package/dist/options.d.ts +15 -0
- package/dist/options.js +5 -0
- package/dist/probe.d.ts +11 -1
- package/dist/probe.js +18 -3
- package/dist/report.d.ts +3 -0
- package/dist/report.js +15 -8
- package/dist/rule-docs.d.ts +26 -0
- package/dist/rule-docs.js +88 -0
- package/dist/rule-docs.json +597 -0
- package/dist/rules/apps.d.ts +11 -0
- package/dist/rules/apps.js +156 -0
- package/dist/rules/auth.d.ts +18 -0
- package/dist/rules/auth.js +29 -0
- package/dist/rules/capabilities.d.ts +21 -0
- package/dist/rules/capabilities.js +103 -0
- package/dist/rules/card.d.ts +7 -0
- package/dist/rules/card.js +65 -0
- package/dist/rules/clients.js +1 -0
- package/dist/rules/description.js +3 -0
- package/dist/rules/handles.d.ts +13 -0
- package/dist/rules/handles.js +78 -0
- package/dist/rules/ids.js +35 -1
- package/dist/rules/index.js +20 -2
- package/dist/rules/naming.js +3 -0
- package/dist/rules/network.d.ts +21 -0
- package/dist/rules/network.js +63 -0
- package/dist/rules/rule.d.ts +20 -0
- package/dist/rules/search.js +1 -0
- package/dist/rules/spec.d.ts +9 -1
- package/dist/rules/spec.js +117 -3
- package/dist/rules/write.d.ts +0 -6
- package/dist/rules/write.js +11 -5
- package/dist/scan.d.ts +47 -0
- package/dist/scan.js +334 -0
- package/dist/session.d.ts +2 -0
- package/dist/session.js +149 -9
- package/dist/snapshot.d.ts +15 -0
- package/dist/snapshot.js +130 -5
- package/dist/types.d.ts +5 -0
- package/dist/words.d.ts +10 -0
- package/dist/words.js +44 -2
- package/package.json +2 -2
- 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 {
|
|
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
|
|
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
|
-
|
|
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)
|
package/dist/colour.d.ts
ADDED
|
@@ -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
|
-
//
|
|
97
|
-
//
|
|
98
|
-
//
|
|
99
|
-
//
|
|
100
|
-
//
|
|
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
|
-
|
|
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;
|