toolmenu 0.12.0 → 0.14.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 +84 -23
- package/dist/args.d.ts +31 -5
- package/dist/args.js +91 -14
- package/dist/auth.d.ts +4 -2
- package/dist/auth.js +59 -21
- package/dist/auto.d.ts +80 -6
- package/dist/auto.js +255 -19
- package/dist/breakdown.d.ts +2 -0
- package/dist/breakdown.js +64 -19
- package/dist/catalog.d.ts +87 -10
- package/dist/catalog.js +415 -58
- package/dist/cli.js +170 -185
- package/dist/close.d.ts +8 -0
- package/dist/close.js +18 -0
- package/dist/config.d.ts +7 -1
- package/dist/config.js +17 -0
- package/dist/connect.d.ts +14 -0
- package/dist/connect.js +150 -16
- package/dist/diff.d.ts +23 -1
- package/dist/diff.js +574 -120
- package/dist/difference.d.ts +2 -0
- package/dist/difference.js +13 -12
- package/dist/explain.d.ts +113 -0
- package/dist/explain.js +461 -0
- package/dist/failures.d.ts +15 -0
- package/dist/failures.js +59 -2
- package/dist/help.d.ts +11 -0
- package/dist/help.js +205 -0
- package/dist/history.d.ts +13 -0
- package/dist/history.js +86 -6
- package/dist/init.d.ts +93 -2
- package/dist/init.js +508 -21
- package/dist/menu.js +10 -2
- package/dist/options.d.ts +141 -0
- package/dist/options.js +50 -0
- package/dist/report.d.ts +2 -2
- package/dist/report.js +305 -101
- package/dist/rules/description.d.ts +7 -2
- package/dist/rules/description.js +86 -42
- package/dist/rules/determinism.d.ts +4 -1
- package/dist/rules/determinism.js +175 -11
- package/dist/rules/gated.d.ts +7 -0
- package/dist/rules/gated.js +77 -0
- package/dist/rules/ids.d.ts +1 -1
- package/dist/rules/ids.js +9 -4
- package/dist/rules/index.d.ts +6 -0
- package/dist/rules/index.js +18 -6
- package/dist/rules/naming.d.ts +1 -1
- package/dist/rules/naming.js +91 -21
- package/dist/rules/rule.d.ts +25 -0
- package/dist/rules/rule.js +25 -1
- package/dist/rules/spec.d.ts +6 -0
- package/dist/rules/spec.js +56 -9
- package/dist/rules/write.d.ts +1 -1
- package/dist/rules/write.js +64 -14
- package/dist/session.d.ts +34 -9
- package/dist/session.js +525 -94
- package/dist/snapshot.d.ts +8 -2
- package/dist/snapshot.js +33 -2
- package/dist/types.d.ts +21 -0
- package/dist/words.d.ts +5 -0
- package/dist/words.js +14 -0
- package/package.json +2 -2
package/dist/cli.js
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
2
|
+
import { writeFile } from 'node:fs/promises';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
4
|
import { parseArgs } from 'node:util';
|
|
5
5
|
import { loadConfig } from './config.js';
|
|
6
|
+
import { PROTOCOLS } from './connect.js';
|
|
6
7
|
import { diffMenus } from './diff.js';
|
|
7
8
|
import { loadMenu } from './menu.js';
|
|
8
9
|
import { history, historyCsv } from './history.js';
|
|
@@ -15,161 +16,49 @@ import { existsSync } from 'node:fs';
|
|
|
15
16
|
import { loadRoutes } from './routes.js';
|
|
16
17
|
import { snapshot } from './snapshot.js';
|
|
17
18
|
import { connectPatiently, MAIN_SEED, probeMenu, refusedForTooMany, seeded } from './probe.js';
|
|
18
|
-
import { autoScenario, scenarioYaml } from './auto.js';
|
|
19
|
+
import { autoScenario, loadValuesFile, parseAssumeReadOnly, parseValueFlag, scenarioYaml } from './auto.js';
|
|
19
20
|
import { authDir, listLogins, login, logout } from './auth.js';
|
|
20
|
-
import {
|
|
21
|
+
import { existingMessage, initReport, planInit, shellWord, writeInit } from './init.js';
|
|
21
22
|
import { SEVERITY_RANK } from './types.js';
|
|
22
23
|
import { VERSION } from './version.js';
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
Usage:
|
|
27
|
-
toolmenu init [options] -- <command> | <url> set up CI: a baseline and a workflow
|
|
28
|
-
toolmenu snapshot [options] -- <command> [args...] stdio server
|
|
29
|
-
toolmenu snapshot [options] <url> Streamable HTTP server
|
|
30
|
-
toolmenu diff [options] <old.json> <new.json> compare two snapshots
|
|
31
|
-
toolmenu history [options] <npm-package> snapshot and diff published versions
|
|
32
|
-
toolmenu auth login <url> | logout <url> | list OAuth logins for HTTP servers
|
|
33
|
-
toolmenu session --scenario <file> [options] -- <command> | <url>
|
|
34
|
-
run a scripted session, watch the menu
|
|
35
|
-
toolmenu session --auto [options] -- <command> | <url>
|
|
36
|
-
the same, with steps built from the menu
|
|
37
|
-
|
|
38
|
-
Commands:
|
|
39
|
-
init snapshot the server into menu.json and write .github/workflows/toolmenu.yml
|
|
40
|
-
snapshot establish the menu: list tools twice, write menu.json, run the menu rules
|
|
41
|
-
diff compare releases: breaking changes, token change, semver bump
|
|
42
|
-
session observe the menu changing while a scripted session runs
|
|
43
|
-
history research release history: install, snapshot and diff published npm versions
|
|
44
|
-
auth log in to an OAuth-protected server once; snapshot and session then use it
|
|
45
|
-
|
|
46
|
-
Options:
|
|
47
|
-
--out <path> where to write the menu (default: menu.json)
|
|
48
|
-
--no-write don't write the menu file
|
|
49
|
-
--routes <path> routes.yml: pin which words route to which tools
|
|
50
|
-
--config <path> config file (default: toolmenu.config.json, if present)
|
|
51
|
-
--format <fmt> text (default), json, github (annotations) or markdown (PR comments)
|
|
52
|
-
--json same as --format json
|
|
53
|
-
--fail-on <level> error (default), warn or info
|
|
54
|
-
--header <k: v> HTTP header, repeatable (e.g. "Authorization: Bearer ...")
|
|
55
|
-
--env <K=V> environment variable for a stdio server, repeatable. The server
|
|
56
|
-
only gets a minimal environment (PATH, HOME, ...) plus these
|
|
57
|
-
--no-auth don't use a stored OAuth login for this server
|
|
58
|
-
--timeout <ms> per-request timeout (default: 30000)
|
|
59
|
-
--catalog also read the operations behind a search tool (search and execute:
|
|
60
|
-
discover, search_*_tools) and keep them in the menu file for diff
|
|
61
|
-
--processes <n> server processes (stdio) or connections (HTTP) to compare,
|
|
62
|
-
the main one included (default: 2; 1 opens no second one, for
|
|
63
|
-
session's scope check either: for servers with one session per client)
|
|
64
|
-
-h, --help show this help
|
|
65
|
-
-v, --version show the version
|
|
66
|
-
|
|
67
|
-
diff options:
|
|
68
|
-
--release <old>..<new> the release versions (npm, git tag) to check the bump
|
|
69
|
-
against, e.g. 1.4.0..1.5.0. Without it, the bump isn't
|
|
70
|
-
checked: serverInfo.version is often not the release
|
|
71
|
-
--server-version-is-release check the bump against serverInfo.version instead
|
|
72
|
-
|
|
73
|
-
session options:
|
|
74
|
-
--scenario <path> scenario.yml: the steps to run (list, call, wait_for)
|
|
75
|
-
--plan print the steps without connecting or running anything
|
|
76
|
-
--init write a starter scenario from the server's menu (to --scenario,
|
|
77
|
-
default scenario.yml; never overwrites)
|
|
78
|
-
--auto build the steps from the menu: every read-only tool whose
|
|
79
|
-
required arguments the schema can fill (const, default,
|
|
80
|
-
examples, enum, type), then the first call again
|
|
81
|
-
--open-world with --auto, also call read-only tools marked openWorldHint:
|
|
82
|
-
true (web search, fetch, scraping): they may cost API credits
|
|
83
|
-
--max-calls <n> with --auto, at most n calls (default: 20)
|
|
84
|
-
--save-scenario <p> with --auto, write the steps it ran as a scenario file
|
|
85
|
-
--union-out <path> write every tool the session saw as a menu file, to commit as
|
|
86
|
-
the baseline for diff (tools behind unlocks included)
|
|
87
|
-
|
|
88
|
-
history options (best effort; installs and runs third-party code, so use a container):
|
|
89
|
-
--versions <n|all> number of published versions to inspect (default: 10)
|
|
90
|
-
--include-prereleases include versions like 1.2.0-beta.1
|
|
91
|
-
--arg <value> argument for the server's bin, repeatable (use --arg=--flag for flags)
|
|
92
|
-
--bin <name> which bin to run when the package has several
|
|
93
|
-
--cmd <template> command instead of the bin; {bin} and {dir} are filled in
|
|
94
|
-
--allow-scripts run install scripts (off by default)
|
|
95
|
-
--install-timeout <ms> per-version install timeout (default: 180000)
|
|
96
|
-
--csv <path> also write the dataset as CSV
|
|
97
|
-
--keep-installs keep each version's install directory
|
|
98
|
-
--out <dir> where menus and history.json go (default: toolmenu-history/<package>)
|
|
99
|
-
|
|
100
|
-
init options:
|
|
101
|
-
--with-session the workflow also runs session --auto (calls read-only tools)
|
|
102
|
-
|
|
103
|
-
auth options:
|
|
104
|
-
--port <n> loopback port for the login redirect (default: 33418)
|
|
105
|
-
--scope <scopes> scopes to ask for (default: the server's)
|
|
106
|
-
--client-id <id> a pre-registered client, for servers without dynamic registration
|
|
107
|
-
--client-secret <s> its secret, if it has one
|
|
108
|
-
|
|
109
|
-
Exit codes: 0 clean · 1 findings at or above --fail-on · 2 couldn't connect or bad usage
|
|
110
|
-
`;
|
|
24
|
+
import { CLI_OPTIONS } from './options.js';
|
|
25
|
+
import { commandHelp, commandOptions, isCommand, overview, unknownCommand } from './help.js';
|
|
111
26
|
class UsageError extends Error {
|
|
112
27
|
}
|
|
113
28
|
export async function main(argv) {
|
|
114
29
|
const dash = argv.indexOf('--');
|
|
115
30
|
const before = dash === -1 ? argv : argv.slice(0, dash);
|
|
116
31
|
const command = dash === -1 ? undefined : argv.slice(dash + 1);
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
allowPositionals: true,
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
env: { type: 'string', multiple: true },
|
|
130
|
-
timeout: { type: 'string' },
|
|
131
|
-
'no-auth': { type: 'boolean' },
|
|
132
|
-
port: { type: 'string' },
|
|
133
|
-
scope: { type: 'string' },
|
|
134
|
-
'client-id': { type: 'string' },
|
|
135
|
-
'client-secret': { type: 'string' },
|
|
136
|
-
processes: { type: 'string' },
|
|
137
|
-
versions: { type: 'string' },
|
|
138
|
-
release: { type: 'string' },
|
|
139
|
-
'server-version-is-release': { type: 'boolean' },
|
|
140
|
-
'include-prereleases': { type: 'boolean' },
|
|
141
|
-
arg: { type: 'string', multiple: true },
|
|
142
|
-
bin: { type: 'string' },
|
|
143
|
-
cmd: { type: 'string' },
|
|
144
|
-
'allow-scripts': { type: 'boolean' },
|
|
145
|
-
'install-timeout': { type: 'string' },
|
|
146
|
-
csv: { type: 'string' },
|
|
147
|
-
'keep-installs': { type: 'boolean' },
|
|
148
|
-
scenario: { type: 'string' },
|
|
149
|
-
plan: { type: 'boolean' },
|
|
150
|
-
init: { type: 'boolean' },
|
|
151
|
-
'union-out': { type: 'string' },
|
|
152
|
-
auto: { type: 'boolean' },
|
|
153
|
-
'with-session': { type: 'boolean' },
|
|
154
|
-
catalog: { type: 'boolean' },
|
|
155
|
-
'open-world': { type: 'boolean' },
|
|
156
|
-
'max-calls': { type: 'string' },
|
|
157
|
-
'save-scenario': { type: 'string' },
|
|
158
|
-
help: { type: 'boolean', short: 'h' },
|
|
159
|
-
version: { type: 'boolean', short: 'v' },
|
|
160
|
-
},
|
|
161
|
-
});
|
|
32
|
+
let parsed;
|
|
33
|
+
try {
|
|
34
|
+
parsed = parseArgs({ args: before, allowPositionals: true, options: CLI_OPTIONS });
|
|
35
|
+
}
|
|
36
|
+
catch (error) {
|
|
37
|
+
// Which command was meant, so the hint can name its help and its options.
|
|
38
|
+
const meant = commandIn(before);
|
|
39
|
+
if (meant && error && typeof error === 'object')
|
|
40
|
+
error.command = meant;
|
|
41
|
+
throw error;
|
|
42
|
+
}
|
|
43
|
+
const { values, positionals } = parsed;
|
|
162
44
|
if (values.version) {
|
|
163
45
|
process.stdout.write(`${VERSION}\n`);
|
|
164
46
|
return 0;
|
|
165
47
|
}
|
|
166
48
|
const [sub, ...rest] = positionals;
|
|
49
|
+
// toolmenu help [command] reads like toolmenu [command] --help.
|
|
50
|
+
if (sub === 'help' && rest.length <= 1) {
|
|
51
|
+
if (rest[0] && !isCommand(rest[0]))
|
|
52
|
+
throw new UsageError(unknownCommand(rest[0]));
|
|
53
|
+
process.stdout.write(rest[0] && isCommand(rest[0]) ? commandHelp(rest[0]) : overview());
|
|
54
|
+
return 0;
|
|
55
|
+
}
|
|
56
|
+
if (sub && !isCommand(sub))
|
|
57
|
+
throw new UsageError(unknownCommand(sub));
|
|
167
58
|
if (values.help || !sub) {
|
|
168
|
-
process.stdout.write(
|
|
59
|
+
process.stdout.write(sub && isCommand(sub) ? commandHelp(sub) : overview());
|
|
169
60
|
return sub || values.help ? 0 : 2;
|
|
170
61
|
}
|
|
171
|
-
if (!['init', 'snapshot', 'diff', 'history', 'session', 'auth'].includes(sub))
|
|
172
|
-
throw new UsageError(`Unknown command "${sub}". Try --help.`);
|
|
173
62
|
const format = (values.json ? 'json' : values.format ?? 'text');
|
|
174
63
|
if (!['text', 'json', 'github', 'markdown'].includes(format))
|
|
175
64
|
throw new UsageError(`--format must be text, json, github or markdown`);
|
|
@@ -181,7 +70,15 @@ export async function main(argv) {
|
|
|
181
70
|
throw new UsageError(`--timeout must be a positive number of milliseconds`);
|
|
182
71
|
if (sub === 'auth')
|
|
183
72
|
return authCommand(rest, values);
|
|
73
|
+
// The invocation up to the server, for examples in messages: a session example
|
|
74
|
+
// without --auto or --scenario wouldn't run.
|
|
75
|
+
const scenarioFlag = values.scenario ? ` --scenario ${shellWord(values.scenario)}` : '';
|
|
76
|
+
const mode = sub !== 'session' ? '' : values.init ? ` --init${scenarioFlag}` : values.auto ? ' --auto' : scenarioFlag;
|
|
77
|
+
const prefix = `${sub}${mode}`;
|
|
184
78
|
const config = await loadConfig(values.config);
|
|
79
|
+
const protocol = (values.protocol ?? config.protocol ?? 'auto');
|
|
80
|
+
if (!PROTOCOLS.includes(protocol))
|
|
81
|
+
throw new UsageError(`--protocol must be auto, legacy or modern`);
|
|
185
82
|
const processes = values.processes !== undefined ? Number(values.processes) : config.processes ?? 2;
|
|
186
83
|
if (!Number.isInteger(processes) || processes < 1)
|
|
187
84
|
throw new UsageError('--processes must be a whole number, 1 or more');
|
|
@@ -232,14 +129,14 @@ export async function main(argv) {
|
|
|
232
129
|
});
|
|
233
130
|
if (values.csv)
|
|
234
131
|
await writeFile(values.csv, historyCsv(result));
|
|
235
|
-
process.stdout.write(formatHistory(result, format, outDir) + '\n');
|
|
132
|
+
process.stdout.write(formatHistory(result, format, outDir, values.csv) + '\n');
|
|
236
133
|
return result.rows.length > 0 && result.rows.every((r) => r.status === 'failed') ? 1 : 0;
|
|
237
134
|
}
|
|
238
135
|
if (sub === 'session' && values.init) {
|
|
239
136
|
const path = values.scenario ?? 'scenario.yml';
|
|
240
137
|
if (existsSync(path))
|
|
241
138
|
throw new UsageError(`${path} already exists. Pick another path with --scenario.`);
|
|
242
|
-
const initTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
|
|
139
|
+
const initTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
|
|
243
140
|
const conn = await connectPatiently(seeded(initTarget, MAIN_SEED), { timeoutMs });
|
|
244
141
|
try {
|
|
245
142
|
const list = await patiently(() => listTools(conn, { timeoutMs }), { error: tooMany });
|
|
@@ -270,57 +167,94 @@ export async function main(argv) {
|
|
|
270
167
|
return 0;
|
|
271
168
|
}
|
|
272
169
|
if (sub === 'init') {
|
|
273
|
-
const
|
|
274
|
-
const
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
throw new UsageError(`${f} already exists; init never overwrites. Remove it, or set things up by hand (README: "In CI").`);
|
|
278
|
-
const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
|
|
170
|
+
const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
|
|
171
|
+
const plan = planInit({ cwd: process.cwd(), target, out: values.out, session: values['with-session'] });
|
|
172
|
+
if (plan.existing.length)
|
|
173
|
+
throw new UsageError(existingMessage(plan));
|
|
279
174
|
const { menu, findings } = await snapshot(target, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
|
|
280
|
-
await
|
|
281
|
-
|
|
282
|
-
const project = detectProject('.');
|
|
283
|
-
await writeFile(workflow, workflowYaml({ target, project, session: values['with-session'], baseline }));
|
|
284
|
-
const c = counts(findings);
|
|
285
|
-
const secrets = secretsNeeded(target);
|
|
286
|
-
const lines = [
|
|
287
|
-
`toolmenu init ${menu.server.name ?? 'server'} · ${menu.tools.length} tools · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)`,
|
|
288
|
-
` wrote ${baseline}: the baseline every pull request is compared with`,
|
|
289
|
-
` wrote ${workflow}${project.kind === 'unknown' ? ' (fill in the TODO: how CI builds your server)' : ` (${project.kind} project)`}`,
|
|
290
|
-
` today's menu: ${c.error} errors, ${c.warn} warnings, ${c.info} info (run toolmenu snapshot to see them)`,
|
|
291
|
-
...(secrets.length ? ['', `Add these repository secrets (Settings → Secrets and variables → Actions): ${secrets.join(', ')}`] : []),
|
|
292
|
-
'',
|
|
293
|
-
'Next:',
|
|
294
|
-
` git add ${baseline} ${workflow} && git commit -m "Check the MCP tool menu on every PR"`,
|
|
295
|
-
' Then open a pull request: toolmenu comments on it. Refresh the baseline when a change is intended:',
|
|
296
|
-
` toolmenu snapshot --out ${baseline} ${target.kind === 'stdio' ? '-- ' + [target.command, ...target.args].join(' ') : target.url}`,
|
|
297
|
-
];
|
|
298
|
-
process.stdout.write(lines.join('\n') + '\n');
|
|
175
|
+
await writeInit(plan, JSON.stringify(menu, null, 2) + '\n');
|
|
176
|
+
process.stdout.write(initReport(plan, { server: menu.server.name, version: menu.server.version, tools: menu.tools.length, tokens: menu.totalTokens, counts: counts(findings) }, target));
|
|
299
177
|
return 0;
|
|
300
178
|
}
|
|
301
179
|
if (sub === 'session' && values.auto) {
|
|
302
180
|
if (values.scenario)
|
|
303
181
|
throw new UsageError('--auto builds the steps itself; drop --scenario (or drop --auto).');
|
|
304
|
-
const
|
|
305
|
-
if (!Number.isInteger(
|
|
182
|
+
const givenMax = values['max-calls'] ? Number(values['max-calls']) : undefined;
|
|
183
|
+
if (givenMax !== undefined && !(Number.isInteger(givenMax) && givenMax >= 1))
|
|
306
184
|
throw new UsageError('--max-calls must be a whole number, 1 or more');
|
|
185
|
+
const perUnlock = values['max-calls-per-unlock'] ? Number(values['max-calls-per-unlock']) : 5;
|
|
186
|
+
if (!Number.isInteger(perUnlock) || perUnlock < 1)
|
|
187
|
+
throw new UsageError('--max-calls-per-unlock must be a whole number, 1 or more');
|
|
307
188
|
const savePath = values['save-scenario'];
|
|
308
189
|
if (savePath && existsSync(savePath))
|
|
309
190
|
throw new UsageError(`${savePath} already exists. Pick another path for --save-scenario.`);
|
|
310
|
-
|
|
191
|
+
// Values and vouched-for tools are checked before anything starts.
|
|
192
|
+
let given = {};
|
|
193
|
+
let assumeReadOnly = [];
|
|
194
|
+
try {
|
|
195
|
+
if (values['values-file'])
|
|
196
|
+
given = await loadValuesFile(values['values-file']);
|
|
197
|
+
for (const v of values.value ?? []) {
|
|
198
|
+
const [key, value] = parseValueFlag(v);
|
|
199
|
+
given[key] = value;
|
|
200
|
+
}
|
|
201
|
+
assumeReadOnly = parseAssumeReadOnly(values['assume-read-only'] ?? []);
|
|
202
|
+
}
|
|
203
|
+
catch (error) {
|
|
204
|
+
throw new UsageError(error instanceof Error ? error.message : String(error));
|
|
205
|
+
}
|
|
206
|
+
const autoTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
|
|
311
207
|
const waited = { ms: 0 };
|
|
312
208
|
const menu = await probeMenu(seeded(autoTarget, MAIN_SEED), timeoutMs, undefined, waited).catch((error) => {
|
|
313
209
|
throw refusedForTooMany(error, waited.ms);
|
|
314
210
|
});
|
|
315
|
-
const
|
|
211
|
+
const options = { openWorld: values['open-world'], values: given, assumeReadOnly };
|
|
212
|
+
let plan = autoScenario(menu, { ...options, maxCalls: givenMax ?? 20 });
|
|
213
|
+
// Each unlock value gets its own budget for the tools it brings, so the first
|
|
214
|
+
// toolsets can't use up the calls the last ones need. --max-calls, when given,
|
|
215
|
+
// caps every call, and the starting menu leaves up to half of it for the unlocks.
|
|
216
|
+
const reserve = givenMax === undefined ? 0 : Math.min(perUnlock * plan.unlockValues, Math.floor(givenMax / 2));
|
|
217
|
+
if (reserve)
|
|
218
|
+
plan = autoScenario(menu, { ...options, maxCalls: givenMax - reserve });
|
|
219
|
+
const maxCalls = givenMax ?? 20 + perUnlock * plan.unlockValues;
|
|
316
220
|
if (savePath)
|
|
317
221
|
await writeFile(savePath, scenarioYaml(plan, menu.server.name));
|
|
318
222
|
if (values.plan) {
|
|
319
223
|
process.stdout.write(formatPlan(plan.scenario, 'auto') + '\n');
|
|
320
224
|
return 0;
|
|
321
225
|
}
|
|
322
|
-
const
|
|
323
|
-
|
|
226
|
+
const auto = { called: plan.called, skipped: plan.skipped, assumed: plan.assumed, withValues: plan.withValues, ignored: plan.ignored, maxCalls, maxCallsPerUnlock: perUnlock };
|
|
227
|
+
// Tools that appear mid-session (behind an unlock) are planned when they appear,
|
|
228
|
+
// under the same rules and what's left of --max-calls. Each tool once.
|
|
229
|
+
const planned = new Set([...plan.called, ...plan.skipped.map((s) => s.tool)]);
|
|
230
|
+
let spent = plan.spent;
|
|
231
|
+
const replan = (added) => {
|
|
232
|
+
const fresh = added.filter((t) => !planned.has(t.name));
|
|
233
|
+
for (const t of fresh)
|
|
234
|
+
planned.add(t.name);
|
|
235
|
+
if (!fresh.length)
|
|
236
|
+
return [];
|
|
237
|
+
const left = maxCalls - spent;
|
|
238
|
+
const more = autoScenario({ ...menu, tools: fresh }, { ...options, maxCalls: Math.min(perUnlock, left), callsOnly: true });
|
|
239
|
+
// Left out by this unlock's own budget, not by the total: say which, for the right flag.
|
|
240
|
+
if (perUnlock < left)
|
|
241
|
+
for (const s of more.skipped)
|
|
242
|
+
if (s.reason === 'over the call budget')
|
|
243
|
+
s.reason = 'over the per-unlock budget';
|
|
244
|
+
spent += more.spent;
|
|
245
|
+
auto.called.push(...more.called);
|
|
246
|
+
auto.skipped.push(...more.skipped);
|
|
247
|
+
auto.assumed.push(...more.assumed);
|
|
248
|
+
auto.withValues.push(...more.withValues);
|
|
249
|
+
if (more.assumed.length)
|
|
250
|
+
plan.scenario.assumeReadOnly = [...(plan.scenario.assumeReadOnly ?? []), ...more.assumed];
|
|
251
|
+
return more.scenario.steps;
|
|
252
|
+
};
|
|
253
|
+
const result = await session(autoTarget, plan.scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: 'auto', unionOut: !!values['union-out'], auto, replan });
|
|
254
|
+
// A --value or --assume-read-only for a tool behind an unlock isn't unused: check
|
|
255
|
+
// them against every tool the session saw, not just the starting menu.
|
|
256
|
+
auto.ignored = autoScenario(result.union, { values: given, assumeReadOnly }).ignored;
|
|
257
|
+
result.auto = { ...result.auto, ...auto };
|
|
324
258
|
if (values['union-out'])
|
|
325
259
|
await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
|
|
326
260
|
const output = formatSession(result, format);
|
|
@@ -329,6 +263,8 @@ export async function main(argv) {
|
|
|
329
263
|
return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
|
|
330
264
|
}
|
|
331
265
|
if (sub === 'session') {
|
|
266
|
+
if (values.value || values['values-file'] || values['assume-read-only'])
|
|
267
|
+
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.');
|
|
332
268
|
if (!values.scenario)
|
|
333
269
|
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.');
|
|
334
270
|
let scenario;
|
|
@@ -342,7 +278,7 @@ export async function main(argv) {
|
|
|
342
278
|
process.stdout.write(formatPlan(scenario, values.scenario) + '\n');
|
|
343
279
|
return 0;
|
|
344
280
|
}
|
|
345
|
-
const sessionTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
|
|
281
|
+
const sessionTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
|
|
346
282
|
const result = await session(sessionTarget, scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: values.scenario, unionOut: !!values['union-out'] });
|
|
347
283
|
if (values['union-out'])
|
|
348
284
|
await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
|
|
@@ -351,7 +287,7 @@ export async function main(argv) {
|
|
|
351
287
|
process.stdout.write(output + '\n');
|
|
352
288
|
return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
|
|
353
289
|
}
|
|
354
|
-
const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
|
|
290
|
+
const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
|
|
355
291
|
const routesPath = values.routes ?? config.routes;
|
|
356
292
|
const routes = routesPath ? await loadRoutes(routesPath) : undefined;
|
|
357
293
|
const { menu, findings } = await snapshot(target, { routes, timeoutMs, processes, catalog: values.catalog ? (config.catalog ?? true) : undefined, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
|
|
@@ -363,38 +299,41 @@ export async function main(argv) {
|
|
|
363
299
|
process.stdout.write(output + '\n');
|
|
364
300
|
return findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
|
|
365
301
|
}
|
|
366
|
-
function parseTarget(positionals, command, headers, env, noAuth
|
|
302
|
+
function parseTarget(positionals, command, headers, env, noAuth, prefix, protocol) {
|
|
367
303
|
if (command) {
|
|
368
304
|
if (command.length === 0)
|
|
369
305
|
throw new UsageError('Nothing after "--": give the command that starts the server.');
|
|
370
306
|
if (positionals.length)
|
|
371
307
|
throw new UsageError(`Unexpected "${positionals[0]}" before "--".`);
|
|
372
|
-
return { kind: 'stdio', command: command[0], args: command.slice(1), env: parsePairs(env, '=', '--env') };
|
|
308
|
+
return { kind: 'stdio', command: command[0], args: command.slice(1), env: parsePairs(env, '=', '--env'), ...(protocol !== 'auto' ? { protocol } : {}) };
|
|
373
309
|
}
|
|
374
310
|
const [url, ...extra] = positionals;
|
|
375
311
|
if (!url)
|
|
376
|
-
throw new UsageError(
|
|
312
|
+
throw new UsageError(`Give a server: a URL, or the command that starts it after "--".\n → Next: toolmenu ${prefix} -- node dist/server.js (stdio) or toolmenu ${prefix} https://example.com/mcp (HTTP)`);
|
|
377
313
|
if (extra.length)
|
|
378
314
|
throw new UsageError(`Unexpected "${extra[0]}". For a stdio server, put the command after "--".`);
|
|
379
315
|
if (!/^https?:\/\//.test(url))
|
|
380
316
|
throw new UsageError(`"${url}" isn't an http(s) URL. For a stdio server, put the command after "--".`);
|
|
381
|
-
return { kind: 'http', url, headers: parsePairs(headers, ':', '--header'), ...(noAuth ? { noAuth } : {}) };
|
|
317
|
+
return { kind: 'http', url, headers: parsePairs(headers, ':', '--header'), ...(noAuth ? { noAuth } : {}), ...(protocol !== 'auto' ? { protocol } : {}) };
|
|
382
318
|
}
|
|
383
319
|
async function authCommand(args, values) {
|
|
384
320
|
const [action, url, ...extra] = args;
|
|
385
321
|
if (action === 'list') {
|
|
386
322
|
const logins = await listLogins();
|
|
387
|
-
|
|
323
|
+
const width = Math.max(0, ...logins.map((l) => l.serverUrl.length));
|
|
324
|
+
process.stdout.write(logins.length
|
|
325
|
+
? [`${logins.length} login${logins.length === 1 ? '' : 's'}, stored in ${authDir()}:`, ...logins.map((l) => ` ${l.serverUrl.padEnd(width)} issuer ${l.issuer ?? 'not recorded'} · saved ${l.savedAt?.slice(0, 10) ?? '?'}`)].join('\n') + '\n'
|
|
326
|
+
: `No logins stored in ${authDir()}.\n→ Next: toolmenu auth login <url> for a server that asks for OAuth.\n`);
|
|
388
327
|
return 0;
|
|
389
328
|
}
|
|
390
329
|
if (action !== 'login' && action !== 'logout')
|
|
391
|
-
throw new UsageError('auth
|
|
330
|
+
throw new UsageError(`${action ? `auth has no action "${action}"` : 'auth needs an action'}: login <url>, logout <url> or list. See toolmenu auth --help.`);
|
|
392
331
|
if (!url || extra.length)
|
|
393
332
|
throw new UsageError(`auth ${action} needs one server URL: toolmenu auth ${action} https://example.com/mcp`);
|
|
394
333
|
if (!/^https?:\/\//.test(url))
|
|
395
334
|
throw new UsageError(`"${url}" isn't an http(s) URL.`);
|
|
396
335
|
if (action === 'logout') {
|
|
397
|
-
process.stdout.write((await logout(url)) ? `Logged out of ${url}.\n` : `No login stored for ${url}.\n`);
|
|
336
|
+
process.stdout.write((await logout(url)) ? `Logged out of ${url}: its tokens and client registration are removed from ${authDir()}.\n` : `No login stored for ${url} (in ${authDir()}), so nothing to remove. toolmenu auth list shows the stored ones.\n`);
|
|
398
337
|
return 0;
|
|
399
338
|
}
|
|
400
339
|
const port = values.port ? Number(values.port) : undefined;
|
|
@@ -403,7 +342,7 @@ async function authCommand(args, values) {
|
|
|
403
342
|
if (values['client-secret'] && !values['client-id'])
|
|
404
343
|
throw new UsageError('--client-secret goes with --client-id');
|
|
405
344
|
const result = await login(url, { port, scope: values.scope, clientId: values['client-id'], clientSecret: values['client-secret'] });
|
|
406
|
-
process.stdout.write(`Logged in to ${result.name ?? url}: ${result.tools} tools
|
|
345
|
+
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`);
|
|
407
346
|
return 0;
|
|
408
347
|
}
|
|
409
348
|
function parsePairs(items, separator, flag) {
|
|
@@ -434,10 +373,56 @@ for (const method of ['log', 'info', 'debug']) {
|
|
|
434
373
|
console[method] = (...args) => console.error(...args);
|
|
435
374
|
}
|
|
436
375
|
main(process.argv.slice(2)).then(exitWhenFlushed, (error) => {
|
|
437
|
-
|
|
438
|
-
process.stderr.write(`toolmenu: ${message}\n`);
|
|
376
|
+
process.stderr.write(`toolmenu: ${failureMessage(error)}\n`);
|
|
439
377
|
exitWhenFlushed(2);
|
|
440
378
|
});
|
|
379
|
+
/** What stopped the command. A mistyped option gets the nearest real one. */
|
|
380
|
+
function failureMessage(error) {
|
|
381
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
382
|
+
const code = error?.code;
|
|
383
|
+
const command = error?.command;
|
|
384
|
+
const next = command
|
|
385
|
+
? `toolmenu ${command} --help lists its options. (A server's own flags go after "--".)`
|
|
386
|
+
: 'toolmenu --help lists the commands; toolmenu <command> --help lists its options.';
|
|
387
|
+
if (code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
|
|
388
|
+
const option = /Unknown option '([^']+)'/.exec(message)?.[1] ?? '';
|
|
389
|
+
const known = (command ? [...commandOptions(command), 'help', 'version'] : Object.keys(CLI_OPTIONS)).map((name) => `--${name}`);
|
|
390
|
+
const guess = known.map((k) => [k, editDistance(option, k)]).sort((a, b) => a[1] - b[1])[0];
|
|
391
|
+
const hint = guess && guess[1] <= 2 ? ` Did you mean ${guess[0]}?` : '';
|
|
392
|
+
return `Unknown option ${option}.${hint}\n → Next: ${next}`;
|
|
393
|
+
}
|
|
394
|
+
if (typeof code === 'string' && code.startsWith('ERR_PARSE_ARGS_'))
|
|
395
|
+
return `${message}\n → Next: ${next}`;
|
|
396
|
+
return message;
|
|
397
|
+
}
|
|
398
|
+
/** The command in arguments parseArgs refused: the first command name that isn't an option's value (--out diff). */
|
|
399
|
+
function commandIn(args) {
|
|
400
|
+
for (let i = 0; i < args.length; i++) {
|
|
401
|
+
const a = args[i];
|
|
402
|
+
if (a.startsWith('--')) {
|
|
403
|
+
const option = CLI_OPTIONS[a.slice(2)];
|
|
404
|
+
if (option?.type === 'string' && !a.includes('='))
|
|
405
|
+
i++;
|
|
406
|
+
continue;
|
|
407
|
+
}
|
|
408
|
+
if (isCommand(a))
|
|
409
|
+
return a;
|
|
410
|
+
}
|
|
411
|
+
return undefined;
|
|
412
|
+
}
|
|
413
|
+
function editDistance(a, b) {
|
|
414
|
+
const row = Array.from({ length: b.length + 1 }, (_, i) => i);
|
|
415
|
+
for (let i = 1; i <= a.length; i++) {
|
|
416
|
+
let diagonal = row[0];
|
|
417
|
+
row[0] = i;
|
|
418
|
+
for (let j = 1; j <= b.length; j++) {
|
|
419
|
+
const above = row[j];
|
|
420
|
+
row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
|
|
421
|
+
diagonal = above;
|
|
422
|
+
}
|
|
423
|
+
}
|
|
424
|
+
return row[b.length];
|
|
425
|
+
}
|
|
441
426
|
function parseRelease(value) {
|
|
442
427
|
const m = /^(.+?)\.\.(.+)$/.exec(value);
|
|
443
428
|
if (!m)
|
package/dist/close.d.ts
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { Client, Transport } from '@modelcontextprotocol/client';
|
|
2
|
+
/**
|
|
3
|
+
* Close a client and end its HTTP session. Closing the client only drops the
|
|
4
|
+
* connection: the server keeps the session (Mcp-Session-Id) until a DELETE ends
|
|
5
|
+
* it, and servers that keep idle sessions for hours under a cap fill up after a
|
|
6
|
+
* few dozen runs. A server that doesn't allow the DELETE (405) is fine.
|
|
7
|
+
*/
|
|
8
|
+
export declare function endSession(client: Client, transport: Transport): Promise<void>;
|
package/dist/close.js
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
|
|
2
|
+
/** A server that never answers the DELETE must not hold the run up. */
|
|
3
|
+
const END_SESSION_MS = 3000;
|
|
4
|
+
/**
|
|
5
|
+
* Close a client and end its HTTP session. Closing the client only drops the
|
|
6
|
+
* connection: the server keeps the session (Mcp-Session-Id) until a DELETE ends
|
|
7
|
+
* it, and servers that keep idle sessions for hours under a cap fill up after a
|
|
8
|
+
* few dozen runs. A server that doesn't allow the DELETE (405) is fine.
|
|
9
|
+
*/
|
|
10
|
+
export async function endSession(client, transport) {
|
|
11
|
+
if (transport instanceof StreamableHTTPClientTransport && transport.sessionId) {
|
|
12
|
+
let timer;
|
|
13
|
+
const gaveUp = new Promise((done) => (timer = setTimeout(done, END_SESSION_MS)));
|
|
14
|
+
await Promise.race([transport.terminateSession().catch(() => { }), gaveUp]);
|
|
15
|
+
clearTimeout(timer);
|
|
16
|
+
}
|
|
17
|
+
await client.close().catch(() => { });
|
|
18
|
+
}
|
package/dist/config.d.ts
CHANGED
|
@@ -4,6 +4,8 @@ export interface Config {
|
|
|
4
4
|
ignore?: string[];
|
|
5
5
|
routes?: string;
|
|
6
6
|
baseline?: string;
|
|
7
|
+
/** Which handshake to make: auto (default), legacy (2025 only) or modern (2026-07-28 only). --protocol wins. */
|
|
8
|
+
protocol?: 'auto' | 'legacy' | 'modern';
|
|
7
9
|
tokenBudget?: number;
|
|
8
10
|
/** diff checks the semver bump against serverInfo.version (off: it's often not the release version). */
|
|
9
11
|
serverVersionIsRelease?: boolean;
|
|
@@ -16,9 +18,13 @@ export interface Config {
|
|
|
16
18
|
fullDescriptions?: string[];
|
|
17
19
|
/** Server processes (stdio) or connections (HTTP) to compare, the main one included (default 2). */
|
|
18
20
|
processes?: number;
|
|
19
|
-
/**
|
|
21
|
+
/**
|
|
22
|
+
* snapshot --catalog: which search tool and which queries (default: detected,
|
|
23
|
+
* derived from the menu), or which command routers to list (default: detected).
|
|
24
|
+
*/
|
|
20
25
|
catalog?: {
|
|
21
26
|
tool?: string;
|
|
27
|
+
routers?: string[];
|
|
22
28
|
queries?: string[];
|
|
23
29
|
pauseMs?: number;
|
|
24
30
|
crawl?: boolean;
|
package/dist/config.js
CHANGED
|
@@ -19,6 +19,9 @@ export async function loadConfig(path) {
|
|
|
19
19
|
throw new Error(`${file}: rules["${id}"] must be error, warn, info or off`);
|
|
20
20
|
}
|
|
21
21
|
}
|
|
22
|
+
if (config.protocol !== undefined && !['auto', 'legacy', 'modern'].includes(config.protocol)) {
|
|
23
|
+
throw new Error(`${file}: protocol must be auto, legacy or modern`);
|
|
24
|
+
}
|
|
22
25
|
const limit = config.descriptionLimit;
|
|
23
26
|
if (limit !== undefined && !(typeof limit === 'number' && limit > 0) && !(typeof limit === 'string' && limit in CLIENT_LIMITS)) {
|
|
24
27
|
throw new Error(`${file}: descriptionLimit must be a positive number or one of ${Object.keys(CLIENT_LIMITS).join(', ')}`);
|
|
@@ -26,5 +29,19 @@ export async function loadConfig(path) {
|
|
|
26
29
|
if (config.processes !== undefined && !(Number.isInteger(config.processes) && config.processes >= 1)) {
|
|
27
30
|
throw new Error(`${file}: processes must be a whole number, 1 or more`);
|
|
28
31
|
}
|
|
32
|
+
const catalog = config.catalog;
|
|
33
|
+
if (catalog !== undefined) {
|
|
34
|
+
const names = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === 'string' && x.length > 0);
|
|
35
|
+
if (typeof catalog !== 'object' || catalog === null || Array.isArray(catalog))
|
|
36
|
+
throw new Error(`${file}: catalog must be an object, like { "routers": ["keyvault"] } or { "tool": "search_tools" }`);
|
|
37
|
+
if (catalog.tool !== undefined && !(typeof catalog.tool === 'string' && catalog.tool))
|
|
38
|
+
throw new Error(`${file}: catalog.tool must be the name of the search tool, a string`);
|
|
39
|
+
if (catalog.routers !== undefined && !names(catalog.routers))
|
|
40
|
+
throw new Error(`${file}: catalog.routers must be a list of tool names, like ["keyvault", "storage"]`);
|
|
41
|
+
if (catalog.tool !== undefined && catalog.routers !== undefined)
|
|
42
|
+
throw new Error(`${file}: catalog names both a search tool (tool) and routers (routers); a menu file keeps one catalog, so keep the one the operations are behind`);
|
|
43
|
+
if (catalog.queries !== undefined && !names(catalog.queries))
|
|
44
|
+
throw new Error(`${file}: catalog.queries must be a list of search phrases, like ["list issues"]`);
|
|
45
|
+
}
|
|
29
46
|
return config;
|
|
30
47
|
}
|
package/dist/connect.d.ts
CHANGED
|
@@ -1,17 +1,27 @@
|
|
|
1
1
|
import { Client } from '@modelcontextprotocol/client';
|
|
2
2
|
import type { Transport } from '@modelcontextprotocol/client';
|
|
3
3
|
import type { Era } from './types.js';
|
|
4
|
+
/**
|
|
5
|
+
* Which handshake to make. auto: try the 2026-07-28 `server/discover` first and fall back
|
|
6
|
+
* to the 2025 one. legacy: the 2025 handshake only. modern: 2026-07-28 only, an error if
|
|
7
|
+
* the server can't speak it.
|
|
8
|
+
*/
|
|
9
|
+
export type Protocol = 'auto' | 'legacy' | 'modern';
|
|
10
|
+
export declare const PROTOCOLS: readonly Protocol[];
|
|
11
|
+
export declare const MODERN_VERSION = "2026-07-28";
|
|
4
12
|
export type Target = {
|
|
5
13
|
kind: 'stdio';
|
|
6
14
|
command: string;
|
|
7
15
|
args: string[];
|
|
8
16
|
env?: Record<string, string>;
|
|
9
17
|
cwd?: string;
|
|
18
|
+
protocol?: Protocol;
|
|
10
19
|
} | {
|
|
11
20
|
kind: 'http';
|
|
12
21
|
url: string;
|
|
13
22
|
headers?: Record<string, string>;
|
|
14
23
|
noAuth?: boolean;
|
|
24
|
+
protocol?: Protocol;
|
|
15
25
|
};
|
|
16
26
|
export interface WireResponse {
|
|
17
27
|
method: string;
|
|
@@ -47,6 +57,10 @@ export interface Connection {
|
|
|
47
57
|
usedAuth: boolean;
|
|
48
58
|
stderr: () => string;
|
|
49
59
|
close: () => Promise<void>;
|
|
60
|
+
/** An error from a request on this connection, said with what the connection saw (exit code, stderr, stray stdout). */
|
|
61
|
+
explain?: (error: unknown, stage: string) => unknown;
|
|
62
|
+
/** Resolves once a server that just failed a request has had its say on stderr (all of it, if it exited). */
|
|
63
|
+
stderrSettled?: () => Promise<void>;
|
|
50
64
|
}
|
|
51
65
|
export interface ConnectOptions {
|
|
52
66
|
timeoutMs?: number;
|