toolmenu 0.11.0 → 0.13.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 +150 -30
- package/dist/args.d.ts +31 -5
- package/dist/args.js +91 -14
- package/dist/auth.d.ts +4 -2
- package/dist/auth.js +61 -18
- package/dist/auto.d.ts +71 -7
- package/dist/auto.js +267 -13
- package/dist/breakdown.d.ts +35 -6
- package/dist/breakdown.js +179 -23
- package/dist/catalog.d.ts +87 -10
- package/dist/catalog.js +415 -58
- package/dist/cli.js +116 -178
- package/dist/compare.js +20 -5
- package/dist/config.d.ts +5 -1
- package/dist/config.js +14 -0
- package/dist/connect.d.ts +4 -0
- package/dist/connect.js +132 -11
- package/dist/diff.d.ts +35 -1
- package/dist/diff.js +1132 -121
- package/dist/difference.d.ts +2 -0
- package/dist/difference.js +13 -12
- package/dist/explain.d.ts +103 -0
- package/dist/explain.js +434 -0
- package/dist/failures.d.ts +55 -0
- package/dist/failures.js +103 -0
- package/dist/help.d.ts +9 -0
- package/dist/help.js +198 -0
- package/dist/history.d.ts +13 -0
- package/dist/history.js +86 -6
- package/dist/init.d.ts +100 -5
- package/dist/init.js +520 -26
- package/dist/menu.js +10 -2
- package/dist/options.d.ts +135 -0
- package/dist/options.js +48 -0
- package/dist/probe.d.ts +15 -3
- package/dist/probe.js +35 -11
- package/dist/report.d.ts +1 -1
- package/dist/report.js +229 -99
- package/dist/rules/description.d.ts +7 -2
- package/dist/rules/description.js +89 -43
- package/dist/rules/determinism.d.ts +3 -1
- package/dist/rules/determinism.js +146 -11
- 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 +15 -5
- package/dist/rules/naming.d.ts +1 -1
- package/dist/rules/naming.js +66 -19
- package/dist/rules/rule.d.ts +18 -0
- package/dist/rules/rule.js +25 -1
- package/dist/rules/spec.d.ts +2 -0
- package/dist/rules/spec.js +61 -8
- package/dist/rules/write.d.ts +1 -1
- package/dist/rules/write.js +42 -10
- package/dist/semver.js +1 -1
- package/dist/session.d.ts +56 -7
- package/dist/session.js +800 -94
- package/dist/snapshot.d.ts +2 -2
- package/dist/snapshot.js +25 -7
- package/dist/types.d.ts +14 -0
- package/dist/words.d.ts +5 -0
- package/dist/words.js +14 -0
- package/package.json +1 -1
package/dist/cli.js
CHANGED
|
@@ -1,111 +1,27 @@
|
|
|
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
6
|
import { diffMenus } from './diff.js';
|
|
7
7
|
import { loadMenu } from './menu.js';
|
|
8
8
|
import { history, historyCsv } from './history.js';
|
|
9
9
|
import { counts, formatDiff, formatHistory, formatPlan, formatSession, formatSnapshot } from './report.js';
|
|
10
|
-
import { loadScenario, session, starterScenario } from './session.js';
|
|
11
|
-
import {
|
|
10
|
+
import { loadScenario, session, starterScenario, unlockListers, valuesFromListing } from './session.js';
|
|
11
|
+
import { listTools } from './connect.js';
|
|
12
|
+
import { patiently, tooMany } from './failures.js';
|
|
12
13
|
import { buildMenu } from './menu.js';
|
|
13
14
|
import { existsSync } from 'node:fs';
|
|
14
15
|
import { loadRoutes } from './routes.js';
|
|
15
16
|
import { snapshot } from './snapshot.js';
|
|
16
|
-
import { MAIN_SEED, probeMenu, seeded } from './probe.js';
|
|
17
|
-
import { autoScenario, scenarioYaml } from './auto.js';
|
|
17
|
+
import { connectPatiently, MAIN_SEED, probeMenu, refusedForTooMany, seeded } from './probe.js';
|
|
18
|
+
import { autoScenario, loadValuesFile, parseAssumeReadOnly, parseValueFlag, scenarioYaml } from './auto.js';
|
|
18
19
|
import { authDir, listLogins, login, logout } from './auth.js';
|
|
19
|
-
import {
|
|
20
|
+
import { existingMessage, initReport, planInit, writeInit } from './init.js';
|
|
20
21
|
import { SEVERITY_RANK } from './types.js';
|
|
21
22
|
import { VERSION } from './version.js';
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
Usage:
|
|
26
|
-
toolmenu init [options] -- <command> | <url> set up CI: a baseline and a workflow
|
|
27
|
-
toolmenu snapshot [options] -- <command> [args...] stdio server
|
|
28
|
-
toolmenu snapshot [options] <url> Streamable HTTP server
|
|
29
|
-
toolmenu diff [options] <old.json> <new.json> compare two snapshots
|
|
30
|
-
toolmenu history [options] <npm-package> snapshot and diff published versions
|
|
31
|
-
toolmenu auth login <url> | logout <url> | list OAuth logins for HTTP servers
|
|
32
|
-
toolmenu session --scenario <file> [options] -- <command> | <url>
|
|
33
|
-
run a scripted session, watch the menu
|
|
34
|
-
toolmenu session --auto [options] -- <command> | <url>
|
|
35
|
-
the same, with steps built from the menu
|
|
36
|
-
|
|
37
|
-
Commands:
|
|
38
|
-
init snapshot the server into menu.json and write .github/workflows/toolmenu.yml
|
|
39
|
-
snapshot establish the menu: list tools twice, write menu.json, run the menu rules
|
|
40
|
-
diff compare releases: breaking changes, token change, semver bump
|
|
41
|
-
session observe the menu changing while a scripted session runs
|
|
42
|
-
history research release history: install, snapshot and diff published npm versions
|
|
43
|
-
auth log in to an OAuth-protected server once; snapshot and session then use it
|
|
44
|
-
|
|
45
|
-
Options:
|
|
46
|
-
--out <path> where to write the menu (default: menu.json)
|
|
47
|
-
--no-write don't write the menu file
|
|
48
|
-
--routes <path> routes.yml: pin which words route to which tools
|
|
49
|
-
--config <path> config file (default: toolmenu.config.json, if present)
|
|
50
|
-
--format <fmt> text (default), json, github (annotations) or markdown (PR comments)
|
|
51
|
-
--json same as --format json
|
|
52
|
-
--fail-on <level> error (default), warn or info
|
|
53
|
-
--header <k: v> HTTP header, repeatable (e.g. "Authorization: Bearer ...")
|
|
54
|
-
--env <K=V> environment variable for a stdio server, repeatable. The server
|
|
55
|
-
only gets a minimal environment (PATH, HOME, ...) plus these
|
|
56
|
-
--no-auth don't use a stored OAuth login for this server
|
|
57
|
-
--timeout <ms> per-request timeout (default: 30000)
|
|
58
|
-
--catalog also read the operations behind a search tool (search and execute:
|
|
59
|
-
discover, search_*_tools) and keep them in the menu file for diff
|
|
60
|
-
--processes <n> server processes (stdio) or connections (HTTP) to compare,
|
|
61
|
-
the main one included (default: 2; 1 turns the check off)
|
|
62
|
-
-h, --help show this help
|
|
63
|
-
-v, --version show the version
|
|
64
|
-
|
|
65
|
-
diff options:
|
|
66
|
-
--release <old>..<new> the release versions (npm, git tag) to check the bump
|
|
67
|
-
against, e.g. 1.4.0..1.5.0. Without it, the bump isn't
|
|
68
|
-
checked: serverInfo.version is often not the release
|
|
69
|
-
--server-version-is-release check the bump against serverInfo.version instead
|
|
70
|
-
|
|
71
|
-
session options:
|
|
72
|
-
--scenario <path> scenario.yml: the steps to run (list, call, wait_for)
|
|
73
|
-
--plan print the steps without connecting or running anything
|
|
74
|
-
--init write a starter scenario from the server's menu (to --scenario,
|
|
75
|
-
default scenario.yml; never overwrites)
|
|
76
|
-
--auto build the steps from the menu: every read-only tool whose
|
|
77
|
-
required arguments the schema can fill (const, default,
|
|
78
|
-
examples, enum, type), then the first call again
|
|
79
|
-
--open-world with --auto, also call read-only tools marked openWorldHint:
|
|
80
|
-
true (web search, fetch, scraping): they may cost API credits
|
|
81
|
-
--max-calls <n> with --auto, at most n calls (default: 20)
|
|
82
|
-
--save-scenario <p> with --auto, write the steps it ran as a scenario file
|
|
83
|
-
--union-out <path> write every tool the session saw as a menu file, to commit as
|
|
84
|
-
the baseline for diff (tools behind unlocks included)
|
|
85
|
-
|
|
86
|
-
history options (best effort; installs and runs third-party code, so use a container):
|
|
87
|
-
--versions <n|all> number of published versions to inspect (default: 10)
|
|
88
|
-
--include-prereleases include versions like 1.2.0-beta.1
|
|
89
|
-
--arg <value> argument for the server's bin, repeatable (use --arg=--flag for flags)
|
|
90
|
-
--bin <name> which bin to run when the package has several
|
|
91
|
-
--cmd <template> command instead of the bin; {bin} and {dir} are filled in
|
|
92
|
-
--allow-scripts run install scripts (off by default)
|
|
93
|
-
--install-timeout <ms> per-version install timeout (default: 180000)
|
|
94
|
-
--csv <path> also write the dataset as CSV
|
|
95
|
-
--keep-installs keep each version's install directory
|
|
96
|
-
--out <dir> where menus and history.json go (default: toolmenu-history/<package>)
|
|
97
|
-
|
|
98
|
-
init options:
|
|
99
|
-
--with-session the workflow also runs session --auto (calls read-only tools)
|
|
100
|
-
|
|
101
|
-
auth options:
|
|
102
|
-
--port <n> loopback port for the login redirect (default: 33418)
|
|
103
|
-
--scope <scopes> scopes to ask for (default: the server's)
|
|
104
|
-
--client-id <id> a pre-registered client, for servers without dynamic registration
|
|
105
|
-
--client-secret <s> its secret, if it has one
|
|
106
|
-
|
|
107
|
-
Exit codes: 0 clean · 1 findings at or above --fail-on · 2 couldn't connect or bad usage
|
|
108
|
-
`;
|
|
23
|
+
import { CLI_OPTIONS } from './options.js';
|
|
24
|
+
import { commandHelp, isCommand, overview, unknownCommand } from './help.js';
|
|
109
25
|
class UsageError extends Error {
|
|
110
26
|
}
|
|
111
27
|
export async function main(argv) {
|
|
@@ -115,59 +31,26 @@ export async function main(argv) {
|
|
|
115
31
|
const { values, positionals } = parseArgs({
|
|
116
32
|
args: before,
|
|
117
33
|
allowPositionals: true,
|
|
118
|
-
options:
|
|
119
|
-
out: { type: 'string' },
|
|
120
|
-
'no-write': { type: 'boolean' },
|
|
121
|
-
routes: { type: 'string' },
|
|
122
|
-
config: { type: 'string' },
|
|
123
|
-
format: { type: 'string' },
|
|
124
|
-
json: { type: 'boolean' },
|
|
125
|
-
'fail-on': { type: 'string' },
|
|
126
|
-
header: { type: 'string', multiple: true },
|
|
127
|
-
env: { type: 'string', multiple: true },
|
|
128
|
-
timeout: { type: 'string' },
|
|
129
|
-
'no-auth': { type: 'boolean' },
|
|
130
|
-
port: { type: 'string' },
|
|
131
|
-
scope: { type: 'string' },
|
|
132
|
-
'client-id': { type: 'string' },
|
|
133
|
-
'client-secret': { type: 'string' },
|
|
134
|
-
processes: { type: 'string' },
|
|
135
|
-
versions: { type: 'string' },
|
|
136
|
-
release: { type: 'string' },
|
|
137
|
-
'server-version-is-release': { type: 'boolean' },
|
|
138
|
-
'include-prereleases': { type: 'boolean' },
|
|
139
|
-
arg: { type: 'string', multiple: true },
|
|
140
|
-
bin: { type: 'string' },
|
|
141
|
-
cmd: { type: 'string' },
|
|
142
|
-
'allow-scripts': { type: 'boolean' },
|
|
143
|
-
'install-timeout': { type: 'string' },
|
|
144
|
-
csv: { type: 'string' },
|
|
145
|
-
'keep-installs': { type: 'boolean' },
|
|
146
|
-
scenario: { type: 'string' },
|
|
147
|
-
plan: { type: 'boolean' },
|
|
148
|
-
init: { type: 'boolean' },
|
|
149
|
-
'union-out': { type: 'string' },
|
|
150
|
-
auto: { type: 'boolean' },
|
|
151
|
-
'with-session': { type: 'boolean' },
|
|
152
|
-
catalog: { type: 'boolean' },
|
|
153
|
-
'open-world': { type: 'boolean' },
|
|
154
|
-
'max-calls': { type: 'string' },
|
|
155
|
-
'save-scenario': { type: 'string' },
|
|
156
|
-
help: { type: 'boolean', short: 'h' },
|
|
157
|
-
version: { type: 'boolean', short: 'v' },
|
|
158
|
-
},
|
|
34
|
+
options: CLI_OPTIONS,
|
|
159
35
|
});
|
|
160
36
|
if (values.version) {
|
|
161
37
|
process.stdout.write(`${VERSION}\n`);
|
|
162
38
|
return 0;
|
|
163
39
|
}
|
|
164
40
|
const [sub, ...rest] = positionals;
|
|
41
|
+
// toolmenu help [command] reads like toolmenu [command] --help.
|
|
42
|
+
if (sub === 'help' && rest.length <= 1) {
|
|
43
|
+
if (rest[0] && !isCommand(rest[0]))
|
|
44
|
+
throw new UsageError(unknownCommand(rest[0]));
|
|
45
|
+
process.stdout.write(rest[0] && isCommand(rest[0]) ? commandHelp(rest[0]) : overview());
|
|
46
|
+
return 0;
|
|
47
|
+
}
|
|
48
|
+
if (sub && !isCommand(sub))
|
|
49
|
+
throw new UsageError(unknownCommand(sub));
|
|
165
50
|
if (values.help || !sub) {
|
|
166
|
-
process.stdout.write(
|
|
51
|
+
process.stdout.write(sub && isCommand(sub) ? commandHelp(sub) : overview());
|
|
167
52
|
return sub || values.help ? 0 : 2;
|
|
168
53
|
}
|
|
169
|
-
if (!['init', 'snapshot', 'diff', 'history', 'session', 'auth'].includes(sub))
|
|
170
|
-
throw new UsageError(`Unknown command "${sub}". Try --help.`);
|
|
171
54
|
const format = (values.json ? 'json' : values.format ?? 'text');
|
|
172
55
|
if (!['text', 'json', 'github', 'markdown'].includes(format))
|
|
173
56
|
throw new UsageError(`--format must be text, json, github or markdown`);
|
|
@@ -230,7 +113,7 @@ export async function main(argv) {
|
|
|
230
113
|
});
|
|
231
114
|
if (values.csv)
|
|
232
115
|
await writeFile(values.csv, historyCsv(result));
|
|
233
|
-
process.stdout.write(formatHistory(result, format, outDir) + '\n');
|
|
116
|
+
process.stdout.write(formatHistory(result, format, outDir, values.csv) + '\n');
|
|
234
117
|
return result.rows.length > 0 && result.rows.every((r) => r.status === 'failed') ? 1 : 0;
|
|
235
118
|
}
|
|
236
119
|
if (sub === 'session' && values.init) {
|
|
@@ -238,12 +121,29 @@ export async function main(argv) {
|
|
|
238
121
|
if (existsSync(path))
|
|
239
122
|
throw new UsageError(`${path} already exists. Pick another path with --scenario.`);
|
|
240
123
|
const initTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
|
|
241
|
-
const conn = await
|
|
124
|
+
const conn = await connectPatiently(seeded(initTarget, MAIN_SEED), { timeoutMs });
|
|
242
125
|
try {
|
|
243
|
-
const list = await listTools(conn, { timeoutMs });
|
|
126
|
+
const list = await patiently(() => listTools(conn, { timeoutMs }), { error: tooMany });
|
|
244
127
|
const menu = buildMenu(list.tools, { name: conn.server.name, version: conn.server.version, protocolVersion: conn.protocolVersion });
|
|
245
|
-
|
|
246
|
-
|
|
128
|
+
// An unlock without an enum: its values come from the server's own read-only
|
|
129
|
+
// listing (list_toolsets), so the scenario can unlock every one.
|
|
130
|
+
const unlockValues = {};
|
|
131
|
+
const read = [];
|
|
132
|
+
for (const { unlock, lister } of unlockListers(menu.tools)) {
|
|
133
|
+
try {
|
|
134
|
+
const result = await conn.client.callTool({ name: lister, arguments: {} }, { timeout: timeoutMs });
|
|
135
|
+
const found = result.isError ? [] : valuesFromListing(result);
|
|
136
|
+
if (found.length) {
|
|
137
|
+
unlockValues[unlock] = found;
|
|
138
|
+
read.push(`${found.length} values for ${unlock} from ${lister}`);
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
catch {
|
|
142
|
+
// Left as TODO in the scenario.
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
await writeFile(path, starterScenario(menu, { values: unlockValues }));
|
|
146
|
+
process.stdout.write(`wrote ${path}: a starter scenario for ${menu.tools.length} tools${read.length ? ` (read ${read.join('; ')})` : ''}. Fill in the TODOs, then run toolmenu session --scenario ${path}\n`);
|
|
247
147
|
}
|
|
248
148
|
finally {
|
|
249
149
|
await conn.close().catch(() => { });
|
|
@@ -251,32 +151,13 @@ export async function main(argv) {
|
|
|
251
151
|
return 0;
|
|
252
152
|
}
|
|
253
153
|
if (sub === 'init') {
|
|
254
|
-
const workflow = join('.github', 'workflows', 'toolmenu.yml');
|
|
255
|
-
const baseline = values.out ?? 'menu.json';
|
|
256
|
-
for (const f of [workflow, baseline])
|
|
257
|
-
if (existsSync(f))
|
|
258
|
-
throw new UsageError(`${f} already exists; init never overwrites. Remove it, or set things up by hand (README: "In CI").`);
|
|
259
154
|
const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
|
|
155
|
+
const plan = planInit({ cwd: process.cwd(), target, out: values.out, session: values['with-session'] });
|
|
156
|
+
if (plan.existing.length)
|
|
157
|
+
throw new UsageError(existingMessage(plan));
|
|
260
158
|
const { menu, findings } = await snapshot(target, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
|
|
261
|
-
await
|
|
262
|
-
|
|
263
|
-
const project = detectProject('.');
|
|
264
|
-
await writeFile(workflow, workflowYaml({ target, project, session: values['with-session'], baseline }));
|
|
265
|
-
const c = counts(findings);
|
|
266
|
-
const secrets = secretsNeeded(target);
|
|
267
|
-
const lines = [
|
|
268
|
-
`toolmenu init ${menu.server.name ?? 'server'} · ${menu.tools.length} tools · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)`,
|
|
269
|
-
` wrote ${baseline}: the baseline every pull request is compared with`,
|
|
270
|
-
` wrote ${workflow}${project.kind === 'unknown' ? ' (fill in the TODO: how CI builds your server)' : ` (${project.kind} project)`}`,
|
|
271
|
-
` today's menu: ${c.error} errors, ${c.warn} warnings, ${c.info} info (run toolmenu snapshot to see them)`,
|
|
272
|
-
...(secrets.length ? ['', `Add these repository secrets (Settings → Secrets and variables → Actions): ${secrets.join(', ')}`] : []),
|
|
273
|
-
'',
|
|
274
|
-
'Next:',
|
|
275
|
-
` git add ${baseline} ${workflow} && git commit -m "Check the MCP tool menu on every PR"`,
|
|
276
|
-
' Then open a pull request: toolmenu comments on it. Refresh the baseline when a change is intended:',
|
|
277
|
-
` toolmenu snapshot --out ${baseline} ${target.kind === 'stdio' ? '-- ' + [target.command, ...target.args].join(' ') : target.url}`,
|
|
278
|
-
];
|
|
279
|
-
process.stdout.write(lines.join('\n') + '\n');
|
|
159
|
+
await writeInit(plan, JSON.stringify(menu, null, 2) + '\n');
|
|
160
|
+
process.stdout.write(initReport(plan, { server: menu.server.name, version: menu.server.version, tools: menu.tools.length, tokens: menu.totalTokens, counts: counts(findings) }, target));
|
|
280
161
|
return 0;
|
|
281
162
|
}
|
|
282
163
|
if (sub === 'session' && values.auto) {
|
|
@@ -288,17 +169,36 @@ export async function main(argv) {
|
|
|
288
169
|
const savePath = values['save-scenario'];
|
|
289
170
|
if (savePath && existsSync(savePath))
|
|
290
171
|
throw new UsageError(`${savePath} already exists. Pick another path for --save-scenario.`);
|
|
172
|
+
// Values and vouched-for tools are checked before anything starts.
|
|
173
|
+
let given = {};
|
|
174
|
+
let assumeReadOnly = [];
|
|
175
|
+
try {
|
|
176
|
+
if (values['values-file'])
|
|
177
|
+
given = await loadValuesFile(values['values-file']);
|
|
178
|
+
for (const v of values.value ?? []) {
|
|
179
|
+
const [key, value] = parseValueFlag(v);
|
|
180
|
+
given[key] = value;
|
|
181
|
+
}
|
|
182
|
+
assumeReadOnly = parseAssumeReadOnly(values['assume-read-only'] ?? []);
|
|
183
|
+
}
|
|
184
|
+
catch (error) {
|
|
185
|
+
throw new UsageError(error instanceof Error ? error.message : String(error));
|
|
186
|
+
}
|
|
291
187
|
const autoTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
|
|
292
|
-
const
|
|
293
|
-
const
|
|
188
|
+
const waited = { ms: 0 };
|
|
189
|
+
const menu = await probeMenu(seeded(autoTarget, MAIN_SEED), timeoutMs, undefined, waited).catch((error) => {
|
|
190
|
+
throw refusedForTooMany(error, waited.ms);
|
|
191
|
+
});
|
|
192
|
+
const plan = autoScenario(menu, { openWorld: values['open-world'], maxCalls, values: given, assumeReadOnly });
|
|
294
193
|
if (savePath)
|
|
295
194
|
await writeFile(savePath, scenarioYaml(plan, menu.server.name));
|
|
296
195
|
if (values.plan) {
|
|
297
196
|
process.stdout.write(formatPlan(plan.scenario, 'auto') + '\n');
|
|
298
197
|
return 0;
|
|
299
198
|
}
|
|
300
|
-
const
|
|
301
|
-
result
|
|
199
|
+
const auto = { called: plan.called, skipped: plan.skipped, assumed: plan.assumed, withValues: plan.withValues, ignored: plan.ignored, maxCalls };
|
|
200
|
+
const result = await session(autoTarget, plan.scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: 'auto', unionOut: !!values['union-out'], auto });
|
|
201
|
+
result.auto ??= auto;
|
|
302
202
|
if (values['union-out'])
|
|
303
203
|
await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
|
|
304
204
|
const output = formatSession(result, format);
|
|
@@ -307,6 +207,8 @@ export async function main(argv) {
|
|
|
307
207
|
return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
|
|
308
208
|
}
|
|
309
209
|
if (sub === 'session') {
|
|
210
|
+
if (values.value || values['values-file'] || values['assume-read-only'])
|
|
211
|
+
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.');
|
|
310
212
|
if (!values.scenario)
|
|
311
213
|
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.');
|
|
312
214
|
let scenario;
|
|
@@ -321,7 +223,7 @@ export async function main(argv) {
|
|
|
321
223
|
return 0;
|
|
322
224
|
}
|
|
323
225
|
const sessionTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth']);
|
|
324
|
-
const result = await session(sessionTarget, scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: values.scenario });
|
|
226
|
+
const result = await session(sessionTarget, scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: values.scenario, unionOut: !!values['union-out'] });
|
|
325
227
|
if (values['union-out'])
|
|
326
228
|
await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
|
|
327
229
|
const output = formatSession(result, format);
|
|
@@ -362,17 +264,20 @@ async function authCommand(args, values) {
|
|
|
362
264
|
const [action, url, ...extra] = args;
|
|
363
265
|
if (action === 'list') {
|
|
364
266
|
const logins = await listLogins();
|
|
365
|
-
|
|
267
|
+
const width = Math.max(0, ...logins.map((l) => l.serverUrl.length));
|
|
268
|
+
process.stdout.write(logins.length
|
|
269
|
+
? [`${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'
|
|
270
|
+
: `No logins stored in ${authDir()}.\n→ Next: toolmenu auth login <url> for a server that asks for OAuth.\n`);
|
|
366
271
|
return 0;
|
|
367
272
|
}
|
|
368
273
|
if (action !== 'login' && action !== 'logout')
|
|
369
|
-
throw new UsageError('auth
|
|
274
|
+
throw new UsageError(`${action ? `auth has no action "${action}"` : 'auth needs an action'}: login <url>, logout <url> or list. See toolmenu auth --help.`);
|
|
370
275
|
if (!url || extra.length)
|
|
371
276
|
throw new UsageError(`auth ${action} needs one server URL: toolmenu auth ${action} https://example.com/mcp`);
|
|
372
277
|
if (!/^https?:\/\//.test(url))
|
|
373
278
|
throw new UsageError(`"${url}" isn't an http(s) URL.`);
|
|
374
279
|
if (action === 'logout') {
|
|
375
|
-
process.stdout.write((await logout(url)) ? `Logged out of ${url}.\n` : `No login stored for ${url}.\n`);
|
|
280
|
+
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`);
|
|
376
281
|
return 0;
|
|
377
282
|
}
|
|
378
283
|
const port = values.port ? Number(values.port) : undefined;
|
|
@@ -381,7 +286,7 @@ async function authCommand(args, values) {
|
|
|
381
286
|
if (values['client-secret'] && !values['client-id'])
|
|
382
287
|
throw new UsageError('--client-secret goes with --client-id');
|
|
383
288
|
const result = await login(url, { port, scope: values.scope, clientId: values['client-id'], clientSecret: values['client-secret'] });
|
|
384
|
-
process.stdout.write(`Logged in to ${result.name ?? url}: ${result.tools} tools
|
|
289
|
+
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`);
|
|
385
290
|
return 0;
|
|
386
291
|
}
|
|
387
292
|
function parsePairs(items, separator, flag) {
|
|
@@ -405,11 +310,44 @@ function exitWhenFlushed(code) {
|
|
|
405
310
|
}
|
|
406
311
|
process.stdout.write('', () => process.stderr.write('', () => process.exit(code)));
|
|
407
312
|
}
|
|
313
|
+
// stdout carries the report alone (--format json is parsed by CI). Libraries log
|
|
314
|
+
// with console: the MCP SDK prints a console.debug line to stdout when a server
|
|
315
|
+
// has no tools capability. Their lines go to stderr.
|
|
316
|
+
for (const method of ['log', 'info', 'debug']) {
|
|
317
|
+
console[method] = (...args) => console.error(...args);
|
|
318
|
+
}
|
|
408
319
|
main(process.argv.slice(2)).then(exitWhenFlushed, (error) => {
|
|
409
|
-
|
|
410
|
-
process.stderr.write(`toolmenu: ${message}\n`);
|
|
320
|
+
process.stderr.write(`toolmenu: ${failureMessage(error)}\n`);
|
|
411
321
|
exitWhenFlushed(2);
|
|
412
322
|
});
|
|
323
|
+
/** What stopped the command. A mistyped option gets the nearest real one. */
|
|
324
|
+
function failureMessage(error) {
|
|
325
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
326
|
+
const code = error?.code;
|
|
327
|
+
if (code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
|
|
328
|
+
const option = /Unknown option '([^']+)'/.exec(message)?.[1] ?? '';
|
|
329
|
+
const known = Object.keys(CLI_OPTIONS).map((name) => `--${name}`);
|
|
330
|
+
const guess = known.map((k) => [k, editDistance(option, k)]).sort((a, b) => a[1] - b[1])[0];
|
|
331
|
+
const hint = guess && guess[1] <= 2 ? ` Did you mean ${guess[0]}?` : '';
|
|
332
|
+
return `Unknown option ${option}.${hint}\n → Next: toolmenu --help lists every option. (A server's own flags go after "--".)`;
|
|
333
|
+
}
|
|
334
|
+
if (typeof code === 'string' && code.startsWith('ERR_PARSE_ARGS_'))
|
|
335
|
+
return `${message}\n → Next: toolmenu --help lists every option.`;
|
|
336
|
+
return message;
|
|
337
|
+
}
|
|
338
|
+
function editDistance(a, b) {
|
|
339
|
+
const row = Array.from({ length: b.length + 1 }, (_, i) => i);
|
|
340
|
+
for (let i = 1; i <= a.length; i++) {
|
|
341
|
+
let diagonal = row[0];
|
|
342
|
+
row[0] = i;
|
|
343
|
+
for (let j = 1; j <= b.length; j++) {
|
|
344
|
+
const above = row[j];
|
|
345
|
+
row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
|
|
346
|
+
diagonal = above;
|
|
347
|
+
}
|
|
348
|
+
}
|
|
349
|
+
return row[b.length];
|
|
350
|
+
}
|
|
413
351
|
function parseRelease(value) {
|
|
414
352
|
const m = /^(.+?)\.\.(.+)$/.exec(value);
|
|
415
353
|
if (!m)
|
package/dist/compare.js
CHANGED
|
@@ -35,18 +35,33 @@ export function toolDiff(before, after) {
|
|
|
35
35
|
kinds.push('serialization');
|
|
36
36
|
return kinds;
|
|
37
37
|
}
|
|
38
|
+
/**
|
|
39
|
+
* Each tool's identity in a list: its name, and for a name that repeats, which
|
|
40
|
+
* occurrence it is. The second `search` pairs with the second `search`, so a
|
|
41
|
+
* duplicate (menu/duplicate-name) isn't also read as a reorder.
|
|
42
|
+
*/
|
|
43
|
+
function identities(tools) {
|
|
44
|
+
const seen = new Map();
|
|
45
|
+
return tools.map((t) => {
|
|
46
|
+
const n = seen.get(t.name) ?? 0;
|
|
47
|
+
seen.set(t.name, n + 1);
|
|
48
|
+
return n === 0 ? t.name : `${t.name}\u0000${n}`;
|
|
49
|
+
});
|
|
50
|
+
}
|
|
38
51
|
export function compareMenus(before, after) {
|
|
39
52
|
const changes = [];
|
|
40
|
-
const
|
|
41
|
-
const
|
|
53
|
+
const beforeIds = identities(before);
|
|
54
|
+
const afterIds = identities(after);
|
|
55
|
+
const beforeById = new Map(before.map((t, i) => [beforeIds[i], { tool: t, index: i }]));
|
|
56
|
+
const afterIdSet = new Set(afterIds);
|
|
42
57
|
before.forEach((t, i) => {
|
|
43
|
-
if (!
|
|
58
|
+
if (!afterIdSet.has(beforeIds[i]))
|
|
44
59
|
changes.push({ kind: 'removed', tool: t.name, position: i });
|
|
45
60
|
});
|
|
46
61
|
// Tools present in both: the ones outside the longest run that kept its
|
|
47
62
|
// relative order are the ones that moved.
|
|
48
63
|
const common = after
|
|
49
|
-
.map((t, i) => ({ name: t.name, afterIndex: i, beforeIndex:
|
|
64
|
+
.map((t, i) => ({ name: t.name, afterIndex: i, beforeIndex: beforeById.get(afterIds[i])?.index }))
|
|
50
65
|
.filter((c) => c.beforeIndex !== undefined);
|
|
51
66
|
const kept = longestIncreasingRun(common.map((c) => c.beforeIndex));
|
|
52
67
|
common.forEach((c, i) => {
|
|
@@ -54,7 +69,7 @@ export function compareMenus(before, after) {
|
|
|
54
69
|
changes.push({ kind: 'moved', tool: c.name, position: c.afterIndex });
|
|
55
70
|
});
|
|
56
71
|
after.forEach((t, i) => {
|
|
57
|
-
const old =
|
|
72
|
+
const old = beforeById.get(afterIds[i]);
|
|
58
73
|
if (!old) {
|
|
59
74
|
changes.push({ kind: 'added', tool: t.name, position: i });
|
|
60
75
|
return;
|
package/dist/config.d.ts
CHANGED
|
@@ -16,9 +16,13 @@ export interface Config {
|
|
|
16
16
|
fullDescriptions?: string[];
|
|
17
17
|
/** Server processes (stdio) or connections (HTTP) to compare, the main one included (default 2). */
|
|
18
18
|
processes?: number;
|
|
19
|
-
/**
|
|
19
|
+
/**
|
|
20
|
+
* snapshot --catalog: which search tool and which queries (default: detected,
|
|
21
|
+
* derived from the menu), or which command routers to list (default: detected).
|
|
22
|
+
*/
|
|
20
23
|
catalog?: {
|
|
21
24
|
tool?: string;
|
|
25
|
+
routers?: string[];
|
|
22
26
|
queries?: string[];
|
|
23
27
|
pauseMs?: number;
|
|
24
28
|
crawl?: boolean;
|
package/dist/config.js
CHANGED
|
@@ -26,5 +26,19 @@ export async function loadConfig(path) {
|
|
|
26
26
|
if (config.processes !== undefined && !(Number.isInteger(config.processes) && config.processes >= 1)) {
|
|
27
27
|
throw new Error(`${file}: processes must be a whole number, 1 or more`);
|
|
28
28
|
}
|
|
29
|
+
const catalog = config.catalog;
|
|
30
|
+
if (catalog !== undefined) {
|
|
31
|
+
const names = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === 'string' && x.length > 0);
|
|
32
|
+
if (typeof catalog !== 'object' || catalog === null || Array.isArray(catalog))
|
|
33
|
+
throw new Error(`${file}: catalog must be an object, like { "routers": ["keyvault"] } or { "tool": "search_tools" }`);
|
|
34
|
+
if (catalog.tool !== undefined && !(typeof catalog.tool === 'string' && catalog.tool))
|
|
35
|
+
throw new Error(`${file}: catalog.tool must be the name of the search tool, a string`);
|
|
36
|
+
if (catalog.routers !== undefined && !names(catalog.routers))
|
|
37
|
+
throw new Error(`${file}: catalog.routers must be a list of tool names, like ["keyvault", "storage"]`);
|
|
38
|
+
if (catalog.tool !== undefined && catalog.routers !== undefined)
|
|
39
|
+
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`);
|
|
40
|
+
if (catalog.queries !== undefined && !names(catalog.queries))
|
|
41
|
+
throw new Error(`${file}: catalog.queries must be a list of search phrases, like ["list issues"]`);
|
|
42
|
+
}
|
|
29
43
|
return config;
|
|
30
44
|
}
|
package/dist/connect.d.ts
CHANGED
|
@@ -47,6 +47,10 @@ export interface Connection {
|
|
|
47
47
|
usedAuth: boolean;
|
|
48
48
|
stderr: () => string;
|
|
49
49
|
close: () => Promise<void>;
|
|
50
|
+
/** An error from a request on this connection, said with what the connection saw (exit code, stderr, stray stdout). */
|
|
51
|
+
explain?: (error: unknown, stage: string) => unknown;
|
|
52
|
+
/** Resolves once a server that just failed a request has had its say on stderr (all of it, if it exited). */
|
|
53
|
+
stderrSettled?: () => Promise<void>;
|
|
50
54
|
}
|
|
51
55
|
export interface ConnectOptions {
|
|
52
56
|
timeoutMs?: number;
|