toolmenu 0.20.0 → 0.21.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 +52 -4
- package/dist/auth.d.ts +14 -0
- package/dist/auth.js +75 -2
- package/dist/auto.d.ts +6 -0
- package/dist/auto.js +77 -8
- package/dist/catalog.js +4 -0
- package/dist/cli.js +73 -16
- package/dist/connect.d.ts +8 -0
- package/dist/connect.js +23 -1
- package/dist/diff.js +1 -10
- package/dist/explain.d.ts +9 -0
- package/dist/explain.js +55 -5
- package/dist/failures.d.ts +12 -1
- package/dist/failures.js +54 -2
- package/dist/help.d.ts +1 -1
- package/dist/help.js +34 -3
- package/dist/options.d.ts +12 -0
- package/dist/options.js +4 -0
- package/dist/report.d.ts +3 -0
- package/dist/report.js +3 -3
- package/dist/rule-docs.d.ts +26 -0
- package/dist/rule-docs.js +88 -0
- package/dist/rule-docs.json +507 -0
- package/dist/rules/auth.d.ts +18 -0
- package/dist/rules/auth.js +29 -0
- package/dist/rules/handles.d.ts +13 -0
- package/dist/rules/handles.js +78 -0
- package/dist/rules/index.js +4 -1
- package/dist/rules/lists.js +1 -1
- package/dist/rules/rule.d.ts +2 -0
- package/dist/rules/write.d.ts +7 -0
- package/dist/rules/write.js +41 -7
- package/dist/scan.d.ts +47 -0
- package/dist/scan.js +334 -0
- package/dist/session.d.ts +2 -0
- package/dist/session.js +96 -5
- package/dist/snapshot.d.ts +10 -0
- package/dist/snapshot.js +41 -0
- package/dist/words.d.ts +8 -0
- package/dist/words.js +23 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -91,14 +91,51 @@ npx toolmenu snapshot https://mcp.example.com/mcp
|
|
|
91
91
|
Logins are stored per server in `~/.config/toolmenu/auth` (readable only by you);
|
|
92
92
|
`auth list` and `auth logout <url>` manage them. A server that doesn't allow
|
|
93
93
|
dynamic registration needs a pre-registered app: `--client-id` (and
|
|
94
|
-
`--client-secret`).
|
|
94
|
+
`--client-secret`). Over SSH or in a container, `auth login --no-browser` prints the
|
|
95
|
+
login URL instead of opening it: open it on any device, sign in, and paste back the
|
|
96
|
+
address the browser ends on (a `localhost` page that doesn't load is expected). In
|
|
97
|
+
CI, where nobody can sign in, pass a token as a header.
|
|
95
98
|
Both protocol generations are supported: 2026-07-28 (`server/discover`, stateless)
|
|
96
99
|
and the 2025 `initialize` handshake, through the official TypeScript SDK.
|
|
97
100
|
|
|
98
101
|
Every finding and error says what's wrong, where, what toolmenu saw, and ends in a
|
|
99
102
|
`→ Next:` step. Findings marked `· unsure` are heuristics (names and words): they say
|
|
100
|
-
what was seen, not what it means.
|
|
101
|
-
|
|
103
|
+
what was seen, not what it means. `toolmenu explain <rule>` says what a rule checks,
|
|
104
|
+
its default level and how to change it (every rule is in [docs/RULES.md](docs/RULES.md)).
|
|
105
|
+
Every command has its own help: `toolmenu history --help`.
|
|
106
|
+
|
|
107
|
+
Behind a proxy (`HTTPS_PROXY`), stdio servers get the proxy and CA settings
|
|
108
|
+
(`HTTPS_PROXY`, `NO_PROXY`, `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`…)
|
|
109
|
+
along with the minimal environment, and `NODE_USE_ENV_PROXY=1` so a Node server's
|
|
110
|
+
`fetch` uses the proxy. Without them a server that calls an API can't reach it, and
|
|
111
|
+
fails as if it were broken.
|
|
112
|
+
|
|
113
|
+
### Every server you use: `scan`
|
|
114
|
+
|
|
115
|
+
```sh
|
|
116
|
+
npx toolmenu scan ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
|
117
|
+
npx toolmenu scan .mcp.json --format markdown
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
`scan` runs `snapshot` on every server in an MCP client config (Claude Desktop, Claude
|
|
121
|
+
Code's `.mcp.json`, Cursor, VS Code: the `mcpServers` or `servers` object) or in a
|
|
122
|
+
text file with one server per line (a URL or a command, optionally `name<TAB>` first),
|
|
123
|
+
four at a time (`--concurrency`), and prints them side by side, then each server's
|
|
124
|
+
findings, like this:
|
|
125
|
+
|
|
126
|
+
```
|
|
127
|
+
server tools tokens findings
|
|
128
|
+
github 42 ~18K 1 error · 2 warn
|
|
129
|
+
filesystem 11 ~2.1K no findings
|
|
130
|
+
linear – – not checked: LINEAR_API_KEY is not set (the config refers to it)
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`${VAR}`, `${VAR:-default}` and `${env:VAR}` in the config are filled from the
|
|
134
|
+
environment. A server whose variable isn't set isn't started with an empty
|
|
135
|
+
credential: it's a row that says so. A server that couldn't be started or read
|
|
136
|
+
makes the exit code 2, because it wasn't checked; one marked `disabled` is listed and
|
|
137
|
+
left alone. URLs are printed without their query, which can hold a key. Nothing is
|
|
138
|
+
written unless `--out-dir` names a folder for each server's menu file.
|
|
102
139
|
|
|
103
140
|
## In CI: one PR comment
|
|
104
141
|
|
|
@@ -198,6 +235,7 @@ serves, and 23 issue and pull-request tools that only the dynamic mode has.
|
|
|
198
235
|
| `session/nothing-called` | warn | `--auto` called no tools (all open-world, missing values, or not read-only): the run only listed the menu |
|
|
199
236
|
| `session/session-lost` | error | The server ended the session after toolmenu opened a second connection with the same credentials (servers with one session per client; 2025-era servers only). The run stops there; rerun with `--processes 1` |
|
|
200
237
|
| `session/handle-error` | warn | 2026-07-28: `--auto` called a read-only tool with a handle that can't exist (`toolmenu-unknown-session`), and it answered with a protocol error instead of a tool error the model can read |
|
|
238
|
+
| `session/handle-roundtrip` | warn | With `--create-handles`: the tool that creates a session, basket or cart was called, and the tools that take it back refused the handle it had just returned (info when its result had no handle to find) |
|
|
201
239
|
| `session/rate-limited` | error | The server kept refusing requests for being too many (a 429) after toolmenu waited about a minute, or a tool not marked `readOnlyHint` said it was rate-limited (it isn't called again). The run stops there, with the steps it didn't check; give the run its own server instance or raise the limit for it |
|
|
202
240
|
| `session/scope-unchecked` | info | A second server process or connection couldn't start mid-session (a server that holds a file or a port), so whether a change was global wasn't checked. Said once for the run |
|
|
203
241
|
|
|
@@ -214,6 +252,10 @@ of either. Servers that don't mark their tools `readOnlyHint` (DeepWiki, every
|
|
|
214
252
|
`--assume-read-only read_wiki_structure,ask_wiki_question`. Only exact names are
|
|
215
253
|
accepted: a pattern would also cover tools a later release adds. A tool marked or
|
|
216
254
|
named as a write is never called, and the report says which tools ran on your word.
|
|
255
|
+
With `--create-handles` on 2026-07-28, `--auto` also calls the tool that creates a
|
|
256
|
+
session, basket or cart (`start_session`; a write, so only with the flag, and never
|
|
257
|
+
one marked `destructiveHint`; not locks, leases or checkouts) and gives the tools that
|
|
258
|
+
take it back the handle it returned, beside the made-up one.
|
|
217
259
|
`--save-scenario auto.yml` writes the steps, with the skipped tools commented out, for
|
|
218
260
|
you to fill in. Tools marked `openWorldHint: true` (web
|
|
219
261
|
search, fetch, scraping, which can cost API credits) are called only with
|
|
@@ -399,6 +441,7 @@ server, or from the spec itself. If a rule can't point to one, it doesn't ship.
|
|
|
399
441
|
| `ids/handle-lifetime` | info | 2026-07-28: a tool that creates a handle another tool takes back (`start_session` → `session_id`) doesn't say how long it lasts (heuristic) |
|
|
400
442
|
| `write/unannotated` | warn | Tools named like writes (`delete_`, `send_`…) with no annotations, as one summary grouped by the annotation each name suggests |
|
|
401
443
|
| `naming/shared-word` | info | Nouns that name different things across tools (`list_team_audits` vs `get_audit_trail`), as one summary |
|
|
444
|
+
| `write/read-only-mismatch` | warn | A tool marked `readOnlyHint: true` whose name says it writes (`create_my_account`): clients act on the hint, and `--auto` doesn't call it on the hint alone (heuristic) |
|
|
402
445
|
| `write/no-dry-run` | info | Destructive tools with no dry-run parameter or preview tool, as one summary |
|
|
403
446
|
| `spec/discover` | info | The server only speaks the 2025 protocol, so 2026-07-28 rules are skipped |
|
|
404
447
|
| `spec/deprecated`, `spec/cache-hints` | info | 2026-07-28: deprecated features still advertised; `ttlMs: 0`, or `cacheScope: "public"` on a server that took credentials |
|
|
@@ -407,6 +450,9 @@ server, or from the spec itself. If a rule can't point to one, it doesn't ship.
|
|
|
407
450
|
| `naming/client-name` | warn | With `--client`: tool names the client's API refuses: `^[a-zA-Z0-9_-]{1,128}$` for the Claude API, `^[a-zA-Z0-9_-]+$` up to 128 for OpenAI's functions. MCP allows names such as `files.read` that neither takes as they are |
|
|
408
451
|
| `menu/auth-variance` | info | With `--as` (or `identities` in the config): the tool set differs by identity, what each adds, lacks or defines differently against the first, and its tokens. Allowed by the spec; a baseline of one identity's menu doesn't cover the others. An identity that can't be listed is said here too |
|
|
409
452
|
| `spec/cache-scope-public` | warn | 2026-07-28, with `--as`: the tool set differs by identity, and `tools/list` says `cacheScope: "public"`, which lets shared caches serve one caller's list to another |
|
|
453
|
+
| `auth/invalid-accepted` | warn | HTTP with credentials: the menu listed once more with an invalid credential in the same scheme. A server that serves a menu to it, not 401, gives a client whose token expired no reason to log in again; the agent just has fewer tools (Atlassian Rovo served 4 tools to any `Authorization` header). `--processes 1` turns it off |
|
|
454
|
+
|
|
455
|
+
The full list, `diff` and `session` rules included, is [docs/RULES.md](docs/RULES.md).
|
|
410
456
|
|
|
411
457
|
The naming and ID rules are heuristics, tuned on real servers (FINDINGS F7 and
|
|
412
458
|
F10) and a private 115-tool one. They're the extras; the change checks are the point.
|
|
@@ -510,10 +556,12 @@ toolmenu sees what the server sends. Plenty of agent failures happen elsewhere:
|
|
|
510
556
|
--as <name>:<cred> snapshot: list the menu as this identity too, repeatable:
|
|
511
557
|
"reader:Authorization: Bearer …" (HTTP) or "admin:ROLE=admin"
|
|
512
558
|
(stdio). The first is the menu saved; the others are compared
|
|
559
|
+
--concurrency <n> scan: servers checked at a time (default: 4)
|
|
560
|
+
--out-dir <dir> scan: write each server's menu file there, as <name>.json
|
|
513
561
|
```
|
|
514
562
|
|
|
515
563
|
Exit codes: `0` clean · `1` findings at or above `--fail-on` · `2` couldn't connect
|
|
516
|
-
or bad usage. `toolmenu <command> --help` lists that command's own options.
|
|
564
|
+
(for `scan`: a server wasn't checked) or bad usage. `toolmenu <command> --help` lists that command's own options.
|
|
517
565
|
|
|
518
566
|
## Limitations
|
|
519
567
|
|
package/dist/auth.d.ts
CHANGED
|
@@ -59,7 +59,21 @@ export interface LoginOptions extends Omit<ProviderOptions, 'interactive' | 'onR
|
|
|
59
59
|
open?: (url: URL) => void | Promise<void>;
|
|
60
60
|
/** How long to wait for the browser to come back (default 5 min). */
|
|
61
61
|
timeoutMs?: number;
|
|
62
|
+
/**
|
|
63
|
+
* --no-browser: don't open a browser; print the URL, and also take the address the
|
|
64
|
+
* browser ends on, pasted back (a machine whose browser can't reach this one's
|
|
65
|
+
* 127.0.0.1: SSH, a container, a remote dev box). `paste` reads that text (default:
|
|
66
|
+
* one line from stdin).
|
|
67
|
+
*/
|
|
68
|
+
noBrowser?: boolean;
|
|
69
|
+
paste?: () => Promise<string>;
|
|
62
70
|
}
|
|
71
|
+
/**
|
|
72
|
+
* The redirect's query from what someone pasted: the whole address the browser ended
|
|
73
|
+
* on (http://127.0.0.1:33418/callback?code=…&state=…), or just its query. Undefined when
|
|
74
|
+
* it carries neither a code nor an error.
|
|
75
|
+
*/
|
|
76
|
+
export declare function pastedRedirect(text: string): URLSearchParams | undefined;
|
|
63
77
|
/**
|
|
64
78
|
* Log in to an OAuth-protected MCP server: register (or reuse a client), open the
|
|
65
79
|
* authorization URL, receive the code on a loopback redirect, check `state`,
|
package/dist/auth.js
CHANGED
|
@@ -201,6 +201,50 @@ export class LoginNeededError extends Error {
|
|
|
201
201
|
`→ Next: Log in once in a terminal with a browser: toolmenu auth login ${serverUrl}. Or pass a token: --header "Authorization: Bearer <token>".`);
|
|
202
202
|
}
|
|
203
203
|
}
|
|
204
|
+
/**
|
|
205
|
+
* The redirect's query from what someone pasted: the whole address the browser ended
|
|
206
|
+
* on (http://127.0.0.1:33418/callback?code=…&state=…), or just its query. Undefined when
|
|
207
|
+
* it carries neither a code nor an error.
|
|
208
|
+
*/
|
|
209
|
+
export function pastedRedirect(text) {
|
|
210
|
+
const t = text.trim().replace(/^["'<]|["'>]$/g, '');
|
|
211
|
+
let params;
|
|
212
|
+
try {
|
|
213
|
+
params = /^[a-z][a-z0-9+.-]*:\/\//i.test(t) ? new URL(t).searchParams : new URLSearchParams(t.replace(/^[^?]*\?/, ''));
|
|
214
|
+
}
|
|
215
|
+
catch {
|
|
216
|
+
return undefined;
|
|
217
|
+
}
|
|
218
|
+
return params.get('code') || params.get('error') ? params : undefined;
|
|
219
|
+
}
|
|
220
|
+
/**
|
|
221
|
+
* Lines from stdin, for --no-browser: one reader for the whole login, so a line
|
|
222
|
+
* already buffered after a bad paste isn't lost. Ends (undefined) when stdin does;
|
|
223
|
+
* `signal` closes it when the loopback redirect won, so stdin doesn't keep the
|
|
224
|
+
* process alive.
|
|
225
|
+
*/
|
|
226
|
+
async function* stdinLines(signal) {
|
|
227
|
+
const { createInterface } = await import('node:readline');
|
|
228
|
+
const rl = createInterface({ input: process.stdin });
|
|
229
|
+
const stop = () => rl.close();
|
|
230
|
+
signal.addEventListener('abort', stop, { once: true });
|
|
231
|
+
try {
|
|
232
|
+
for await (const line of rl)
|
|
233
|
+
yield line;
|
|
234
|
+
}
|
|
235
|
+
finally {
|
|
236
|
+
signal.removeEventListener('abort', stop);
|
|
237
|
+
rl.close();
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
/** Print the authorization URL and say what to paste back. */
|
|
241
|
+
function printForPaste(port) {
|
|
242
|
+
return (url) => {
|
|
243
|
+
process.stderr.write(`Open this address in a browser on any device and approve the login:\n\n ${url.href}\n\n` +
|
|
244
|
+
`The browser then goes to http://127.0.0.1:${port}/callback?code=… . On another device that page won't load: ` +
|
|
245
|
+
`copy its address from the address bar and paste it here, then press Enter.\n> `);
|
|
246
|
+
};
|
|
247
|
+
}
|
|
204
248
|
/**
|
|
205
249
|
* Log in to an OAuth-protected MCP server: register (or reuse a client), open the
|
|
206
250
|
* authorization URL, receive the code on a loopback redirect, check `state`,
|
|
@@ -211,7 +255,36 @@ export async function login(serverUrl, options = {}) {
|
|
|
211
255
|
const port = options.port ?? DEFAULT_PORT;
|
|
212
256
|
const callback = await listenForCallback(port, options.timeoutMs ?? 300_000);
|
|
213
257
|
try {
|
|
214
|
-
const provider = new StoredOAuthProvider(serverUrl, {
|
|
258
|
+
const provider = new StoredOAuthProvider(serverUrl, {
|
|
259
|
+
...options,
|
|
260
|
+
port,
|
|
261
|
+
interactive: true,
|
|
262
|
+
onRedirect: options.open ?? (options.noBrowser ? printForPaste(port) : openInBrowser),
|
|
263
|
+
});
|
|
264
|
+
// --no-browser: the loopback redirect, or the address pasted back, whichever comes first.
|
|
265
|
+
const reading = new AbortController();
|
|
266
|
+
const retry = () => process.stderr.write(`That has no code= or error= in it: paste the whole address the browser ended on (http://127.0.0.1:${port}/callback?code=…).\n> `);
|
|
267
|
+
const pasted = async () => {
|
|
268
|
+
if (options.paste) {
|
|
269
|
+
for (;;) {
|
|
270
|
+
const params = pastedRedirect(await options.paste());
|
|
271
|
+
if (params)
|
|
272
|
+
return params;
|
|
273
|
+
retry();
|
|
274
|
+
}
|
|
275
|
+
}
|
|
276
|
+
for await (const line of stdinLines(reading.signal)) {
|
|
277
|
+
const params = pastedRedirect(line);
|
|
278
|
+
if (params)
|
|
279
|
+
return params;
|
|
280
|
+
retry();
|
|
281
|
+
}
|
|
282
|
+
// stdin ended (</dev/null, a script): nothing can be pasted, but the browser may
|
|
283
|
+
// still reach the loopback (SSH with the port forwarded). Said, then left to it.
|
|
284
|
+
if (!reading.signal.aborted)
|
|
285
|
+
process.stderr.write(`\nNothing can be pasted here (stdin ended): waiting for the browser to reach http://127.0.0.1:${port}/callback instead.\n`);
|
|
286
|
+
return new Promise(() => { });
|
|
287
|
+
};
|
|
215
288
|
// Each login discovers the authorization server afresh (a server may have
|
|
216
289
|
// moved); the state is then kept for the callback leg's check.
|
|
217
290
|
await provider.invalidateCredentials('discovery');
|
|
@@ -225,7 +298,7 @@ export async function login(serverUrl, options = {}) {
|
|
|
225
298
|
catch (error) {
|
|
226
299
|
if (!(error instanceof UnauthorizedError))
|
|
227
300
|
throw error;
|
|
228
|
-
const params = await callback.params;
|
|
301
|
+
const params = options.noBrowser ? await Promise.race([callback.params, pasted()]).finally(() => reading.abort()) : await callback.params;
|
|
229
302
|
if (params.get('error')) {
|
|
230
303
|
const described = params.get('error_description');
|
|
231
304
|
throw new Error(`The authorization server refused the login for ${serverUrl}: ${params.get('error')}${described ? ` (“${described}”)` : ''}.\n` +
|
package/dist/auto.d.ts
CHANGED
|
@@ -11,6 +11,12 @@ export interface GivenValue {
|
|
|
11
11
|
export interface AutoOptions {
|
|
12
12
|
/** Also call read-only tools marked openWorldHint: true (web search, fetch, scraping). */
|
|
13
13
|
openWorld?: boolean;
|
|
14
|
+
/**
|
|
15
|
+
* --create-handles: call the tool that creates a session, basket or cart (a write,
|
|
16
|
+
* so only when asked, and never one marked destructiveHint), and give the tools that
|
|
17
|
+
* take it back the handle it returned instead of a made-up one.
|
|
18
|
+
*/
|
|
19
|
+
createHandles?: boolean;
|
|
14
20
|
/** At most this many calls (default 20). */
|
|
15
21
|
maxCalls?: number;
|
|
16
22
|
/**
|
package/dist/auto.js
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import { readFile } from 'node:fs/promises';
|
|
2
2
|
import { isMap, isNode, isScalar, parseDocument } from 'yaml';
|
|
3
3
|
import { synthesizeArgs } from './args.js';
|
|
4
|
-
import { createdKinds, handleParams } from './rules/handles.js';
|
|
4
|
+
import { CREATABLE_KINDS, createdKinds, creatorOf, handleParams } from './rules/handles.js';
|
|
5
5
|
import { MAX_UNLOCKS, unlockers } from './session.js';
|
|
6
|
-
import { COLLECTION_VERBS, LOOKUP_VERBS, verbOf, WRITE_VERBS } from './words.js';
|
|
6
|
+
import { COLLECTION_VERBS, commonWords, leadingVerb, LOOKUP_VERBS, verbOf, WRITE_VERBS } from './words.js';
|
|
7
7
|
/** Marked or named as a write: never called on the user's word. Says why, or undefined. */
|
|
8
8
|
export function writeSign(tool) {
|
|
9
9
|
const a = tool.annotations ?? {};
|
|
@@ -42,7 +42,11 @@ export function autoScenario(menu, options = {}) {
|
|
|
42
42
|
else
|
|
43
43
|
assumed.add(name);
|
|
44
44
|
}
|
|
45
|
-
|
|
45
|
+
// The server's readOnlyHint, but not against a name that says it writes: a hosted
|
|
46
|
+
// server marked create_my_ideal_account read-only (write/read-only-mismatch).
|
|
47
|
+
const common = commonWords(menu.tools.map((t) => t.name));
|
|
48
|
+
const namedWrite = (t) => WRITE_VERBS.has(leadingVerb(t.name, common) ?? '');
|
|
49
|
+
const readOnly = (t) => (t.annotations?.readOnlyHint === true && !namedWrite(t)) || assumed.has(t.name);
|
|
46
50
|
const { perTool, ignored: unusedValues } = resolveValues(menu, options.values ?? {});
|
|
47
51
|
ignored.push(...unusedValues);
|
|
48
52
|
const candidates = [];
|
|
@@ -63,7 +67,9 @@ export function autoScenario(menu, options = {}) {
|
|
|
63
67
|
continue;
|
|
64
68
|
const a = tool.annotations ?? {};
|
|
65
69
|
if (!readOnly(tool)) {
|
|
66
|
-
const write =
|
|
70
|
+
const write = a.readOnlyHint === true && namedWrite(tool)
|
|
71
|
+
? `the server marks it readOnlyHint, but its name starts with "${leadingVerb(tool.name, common)}", a write: not called on the hint alone`
|
|
72
|
+
: writeSign(tool);
|
|
67
73
|
skipped.push(write || a.readOnlyHint !== undefined ? { tool: tool.name, reason: 'not read-only', ...(write ? { why: write } : {}) } : { tool: tool.name, reason: 'unmarked' });
|
|
68
74
|
continue;
|
|
69
75
|
}
|
|
@@ -98,11 +104,67 @@ export function autoScenario(menu, options = {}) {
|
|
|
98
104
|
}
|
|
99
105
|
candidates.sort((x, y) => x.rank - y.rank);
|
|
100
106
|
const chosen = candidates.slice(0, maxCalls);
|
|
107
|
+
// A tool also called through its other candidate (a plain call beside an optional-handle probe) isn't skipped.
|
|
101
108
|
for (const c of candidates.slice(maxCalls))
|
|
102
|
-
|
|
109
|
+
if (!chosen.some((x) => x.tool.name === c.tool.name))
|
|
110
|
+
skipped.push({ tool: c.tool.name, reason: 'over the call budget' });
|
|
103
111
|
const steps = options.callsOnly ? [] : [{ kind: 'list' }];
|
|
104
|
-
|
|
112
|
+
// --create-handles: the creating tool of each kind a probe takes, called first.
|
|
113
|
+
const creators = [];
|
|
114
|
+
// Calls the plan makes, the final repeat aside: each creator is one, and each probe it serves is called twice.
|
|
115
|
+
const cost = () => chosen.length + creators.length + chosen.filter((c) => c.probe?.fromCreated).length;
|
|
116
|
+
if (options.createHandles && modern) {
|
|
117
|
+
for (const kind of [...new Set(chosen.filter((c) => c.probe).map((c) => c.probe.kind))]) {
|
|
118
|
+
if (!CREATABLE_KINDS.has(kind))
|
|
119
|
+
continue;
|
|
120
|
+
const creator = creatorOf(menu.tools, kind);
|
|
121
|
+
if (!creator || creator.annotations?.destructiveHint === true)
|
|
122
|
+
continue;
|
|
123
|
+
const filled = synthesizeArgs(creator.inputSchema, perTool.get(creator.name));
|
|
124
|
+
if (!filled.ok)
|
|
125
|
+
continue;
|
|
126
|
+
creators.push({ tool: creator, kind, args: filled.args });
|
|
127
|
+
for (const c of chosen)
|
|
128
|
+
if (c.probe?.kind === kind)
|
|
129
|
+
c.probe = { ...c.probe, fromCreated: creator.name };
|
|
130
|
+
}
|
|
131
|
+
// Within --max-calls. First the real-handle calls go (last first), each probe keeping
|
|
132
|
+
// its made-up call as without --create-handles, and a creator that serves none goes
|
|
133
|
+
// with them; only then whole calls.
|
|
134
|
+
const unused = () => {
|
|
135
|
+
for (let i = creators.length - 1; i >= 0; i--)
|
|
136
|
+
if (!chosen.some((c) => c.probe?.fromCreated === creators[i].tool.name))
|
|
137
|
+
creators.splice(i, 1);
|
|
138
|
+
};
|
|
139
|
+
for (let i = chosen.length - 1; i >= 0 && cost() > maxCalls; i--) {
|
|
140
|
+
const probe = chosen[i].probe;
|
|
141
|
+
if (!probe?.fromCreated)
|
|
142
|
+
continue;
|
|
143
|
+
chosen[i].probe = { param: probe.param, kind: probe.kind };
|
|
144
|
+
unused();
|
|
145
|
+
}
|
|
146
|
+
while (chosen.length && cost() > maxCalls) {
|
|
147
|
+
const c = chosen.pop();
|
|
148
|
+
// A tool called through its other candidate (its plain call beside an optional-handle probe) isn't skipped.
|
|
149
|
+
if (!chosen.some((x) => x.tool.name === c.tool.name) && !skipped.some((x) => x.tool === c.tool.name))
|
|
150
|
+
skipped.push({ tool: c.tool.name, reason: 'over the call budget' });
|
|
151
|
+
unused();
|
|
152
|
+
}
|
|
153
|
+
// Called on purpose now: not skipped.
|
|
154
|
+
for (const c of creators) {
|
|
155
|
+
const i = skipped.findIndex((x) => x.tool === c.tool.name);
|
|
156
|
+
if (i >= 0)
|
|
157
|
+
skipped.splice(i, 1);
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
for (const c of creators)
|
|
161
|
+
steps.push({ kind: 'call', tool: c.tool.name, args: c.args, creates: c.kind });
|
|
162
|
+
for (const c of chosen) {
|
|
163
|
+
// With a created handle, both: the made-up one (session/handle-error) and the real one (session/handle-roundtrip).
|
|
164
|
+
if (c.probe?.fromCreated)
|
|
165
|
+
steps.push({ kind: 'call', tool: c.tool.name, args: c.args, probe: { param: c.probe.param, kind: c.probe.kind } });
|
|
105
166
|
steps.push({ kind: 'call', tool: c.tool.name, args: c.args, ...(c.probe ? { probe: c.probe } : {}) });
|
|
167
|
+
}
|
|
106
168
|
for (const u of unlocks) {
|
|
107
169
|
const array = u.tool.inputSchema?.properties?.[u.param]?.type === 'array';
|
|
108
170
|
const values = u.values.slice(0, MAX_UNLOCKS);
|
|
@@ -116,7 +178,7 @@ export function autoScenario(menu, options = {}) {
|
|
|
116
178
|
}
|
|
117
179
|
if (chosen.length && !options.callsOnly)
|
|
118
180
|
steps.push({ kind: 'call', tool: chosen[0].tool.name, args: chosen[0].args, ...(chosen[0].probe ? { probe: chosen[0].probe } : {}) });
|
|
119
|
-
const called = [...chosen.map((c) => c.tool.name), ...unlocks.map((u) => u.tool.name)];
|
|
181
|
+
const called = [...creators.map((c) => c.tool.name), ...chosen.map((c) => c.tool.name), ...unlocks.map((u) => u.tool.name)];
|
|
120
182
|
return {
|
|
121
183
|
scenario: { allowWrites: false, steps, ...(assumed.size ? { assumeReadOnly: [...assumed] } : {}) },
|
|
122
184
|
called,
|
|
@@ -124,7 +186,7 @@ export function autoScenario(menu, options = {}) {
|
|
|
124
186
|
withValues: chosen.filter((c) => c.valued).map((c) => c.tool.name),
|
|
125
187
|
skipped,
|
|
126
188
|
ignored,
|
|
127
|
-
spent:
|
|
189
|
+
spent: cost(),
|
|
128
190
|
unlockValues: unlocks.reduce((n, u) => n + Math.min(u.values.length, MAX_UNLOCKS), 0),
|
|
129
191
|
};
|
|
130
192
|
}
|
|
@@ -390,6 +452,13 @@ export function scenarioYaml(plan, serverName) {
|
|
|
390
452
|
for (const step of plan.scenario.steps) {
|
|
391
453
|
if (step.kind === 'list')
|
|
392
454
|
lines.push(' - list');
|
|
455
|
+
else if (step.kind === 'call' && step.creates) {
|
|
456
|
+
// A write, called only with --create-handles: as written it would be refused under allow_writes: false.
|
|
457
|
+
lines.push(` # --create-handles called ${step.tool} to create a ${step.creates} (a write); to replay it, set allow_writes: true and uncomment:`, ` # - call: ${step.tool}`, ...(Object.keys(step.args).length ? [` # args: ${JSON.stringify(step.args)}`] : []));
|
|
458
|
+
}
|
|
459
|
+
else if (step.kind === 'call' && step.probe?.fromCreated) {
|
|
460
|
+
lines.push(` # --create-handles called ${step.tool} with the ${step.probe.kind} ${step.probe.fromCreated} returned (session/handle-roundtrip); to replay it, put one in:`, ` # - call: ${step.tool}`, ` # args: ${JSON.stringify({ ...step.args, [step.probe.param]: 'TODO' })}`);
|
|
461
|
+
}
|
|
393
462
|
else if (step.kind === 'call' && step.probe) {
|
|
394
463
|
// A made-up handle is --auto's check, not a step to replay: as written it would fail as a step.
|
|
395
464
|
lines.push(` # --auto called ${step.tool} with a made-up ${step.probe.kind} (session/handle-error); to replay it, put a real one in:`, ` # - call: ${step.tool}`, ` # args: ${JSON.stringify(step.args)}`);
|
package/dist/catalog.js
CHANGED
|
@@ -294,6 +294,10 @@ const FAILED_AS = {
|
|
|
294
294
|
what: ['wanted credentials before it would list its commands', 'wanted credentials before they would list their commands'],
|
|
295
295
|
fix: "Rerun with the server's credentials (--env for a stdio server, --header for HTTP); if these routers aren't yours to watch, ignore this.",
|
|
296
296
|
},
|
|
297
|
+
payment: {
|
|
298
|
+
what: ['asked for payment before it would list its commands', 'asked for payment before they would list their commands'],
|
|
299
|
+
fix: "Listing these routers' commands costs money here; rerun with an account that has credit if they're yours to watch, or ignore this.",
|
|
300
|
+
},
|
|
297
301
|
environment: {
|
|
298
302
|
what: ["needs something this machine doesn't have", "need something this machine doesn't have"],
|
|
299
303
|
fix: 'Install what the error names where toolmenu starts the server (the same container or CI image), then rerun.',
|
package/dist/cli.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import { writeFile } from 'node:fs/promises';
|
|
2
|
+
import { mkdir, writeFile } from 'node:fs/promises';
|
|
3
3
|
import { join } from 'node:path';
|
|
4
4
|
import { parseArgs } from 'node:util';
|
|
5
5
|
import { CLIENT_NAMES, CLIENTS } from './clients.js';
|
|
@@ -24,6 +24,9 @@ import { existingMessage, initReport, planInit, shellWord, writeInit } from './i
|
|
|
24
24
|
import { SEVERITY_RANK } from './types.js';
|
|
25
25
|
import { VERSION } from './version.js';
|
|
26
26
|
import { CLI_OPTIONS } from './options.js';
|
|
27
|
+
import { editDistance } from './words.js';
|
|
28
|
+
import { formatScan, ListError, loadList, scan, scanExit } from './scan.js';
|
|
29
|
+
import { explain, findRule, formatExplained, listRules, ruleDocs } from './rule-docs.js';
|
|
27
30
|
import { commandHelp, commandOptions, isCommand, overview, unknownCommand } from './help.js';
|
|
28
31
|
class UsageError extends Error {
|
|
29
32
|
}
|
|
@@ -72,6 +75,8 @@ export async function main(argv) {
|
|
|
72
75
|
throw new UsageError(`--timeout must be a positive number of milliseconds`);
|
|
73
76
|
if (sub === 'auth')
|
|
74
77
|
return authCommand(rest, values);
|
|
78
|
+
if (sub === 'explain')
|
|
79
|
+
return explainCommand(rest, command, format);
|
|
75
80
|
// The invocation up to the server, for examples in messages: a session example
|
|
76
81
|
// without --auto or --scenario wouldn't run.
|
|
77
82
|
const scenarioFlag = values.scenario ? ` --scenario ${shellWord(values.scenario)}` : '';
|
|
@@ -103,6 +108,51 @@ export async function main(argv) {
|
|
|
103
108
|
const processes = values.processes !== undefined ? Number(values.processes) : config.processes ?? 2;
|
|
104
109
|
if (!Number.isInteger(processes) || processes < 1)
|
|
105
110
|
throw new UsageError('--processes must be a whole number, 1 or more');
|
|
111
|
+
if (sub === 'scan') {
|
|
112
|
+
if (command)
|
|
113
|
+
throw new UsageError('scan reads its servers from a list file; give the file, not a command.');
|
|
114
|
+
if (rest.length !== 1)
|
|
115
|
+
throw new UsageError('scan needs one list: an MCP client config (mcp.json) or a text file with a server per line.');
|
|
116
|
+
const concurrency = values.concurrency !== undefined ? Number(values.concurrency) : 4;
|
|
117
|
+
if (!Number.isInteger(concurrency) || concurrency < 1)
|
|
118
|
+
throw new UsageError('--concurrency must be a whole number, 1 or more');
|
|
119
|
+
let entries;
|
|
120
|
+
try {
|
|
121
|
+
entries = await loadList(rest[0]);
|
|
122
|
+
}
|
|
123
|
+
catch (error) {
|
|
124
|
+
if (error instanceof ListError)
|
|
125
|
+
throw new UsageError(error.message);
|
|
126
|
+
throw error;
|
|
127
|
+
}
|
|
128
|
+
const withProtocol = entries.map((e) => (e.target && protocol !== 'auto' ? { ...e, target: { ...e.target, protocol } } : e));
|
|
129
|
+
const outDir = values['out-dir'];
|
|
130
|
+
if (outDir)
|
|
131
|
+
await mkdir(outDir, { recursive: true });
|
|
132
|
+
const tty = process.stderr.isTTY;
|
|
133
|
+
const rows = await scan(withProtocol, {
|
|
134
|
+
timeoutMs,
|
|
135
|
+
processes,
|
|
136
|
+
concurrency,
|
|
137
|
+
rules: config.rules,
|
|
138
|
+
ignore: config.ignore,
|
|
139
|
+
descriptionLimit: config.descriptionLimit,
|
|
140
|
+
fullDescriptions: config.fullDescriptions,
|
|
141
|
+
...(config.client ? { client: config.client } : {}),
|
|
142
|
+
onDone: (row, done, total) => {
|
|
143
|
+
if (tty)
|
|
144
|
+
process.stderr.write(`\r\x1b[K ${done}/${total} ${row.name}`);
|
|
145
|
+
},
|
|
146
|
+
});
|
|
147
|
+
if (tty)
|
|
148
|
+
process.stderr.write('\r\x1b[K');
|
|
149
|
+
if (outDir)
|
|
150
|
+
for (const r of rows)
|
|
151
|
+
if (r.menu)
|
|
152
|
+
await writeFile(join(outDir, `${r.name.replace(/[^\w.@-]+/g, '_')}.json`), JSON.stringify(r.menu, null, 2) + '\n');
|
|
153
|
+
process.stdout.write(formatScan(rows, format, rest[0]) + '\n');
|
|
154
|
+
return scanExit(rows, failOn);
|
|
155
|
+
}
|
|
106
156
|
if (sub === 'diff') {
|
|
107
157
|
if (command)
|
|
108
158
|
throw new UsageError('diff compares two menu files; it doesn\'t start a server. Run snapshot first.');
|
|
@@ -229,7 +279,7 @@ export async function main(argv) {
|
|
|
229
279
|
const menu = await probeMenu(seeded(autoTarget, MAIN_SEED), timeoutMs, undefined, waited).catch((error) => {
|
|
230
280
|
throw refusedForTooMany(error, waited.ms);
|
|
231
281
|
});
|
|
232
|
-
const options = { openWorld: values['open-world'], values: given, assumeReadOnly };
|
|
282
|
+
const options = { openWorld: values['open-world'], createHandles: values['create-handles'], values: given, assumeReadOnly };
|
|
233
283
|
let plan = autoScenario(menu, { ...options, maxCalls: givenMax ?? 20 });
|
|
234
284
|
// Each unlock value gets its own budget for the tools it brings, so the first
|
|
235
285
|
// toolsets can't use up the calls the last ones need. --max-calls, when given,
|
|
@@ -364,7 +414,7 @@ async function authCommand(args, values) {
|
|
|
364
414
|
throw new UsageError('--port must be a port number');
|
|
365
415
|
if (values['client-secret'] && !values['client-id'])
|
|
366
416
|
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'] });
|
|
417
|
+
const result = await login(url, { port, scope: values.scope, clientId: values['client-id'], clientSecret: values['client-secret'], noBrowser: values['no-browser'] });
|
|
368
418
|
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
419
|
return 0;
|
|
370
420
|
}
|
|
@@ -437,6 +487,26 @@ main(process.argv.slice(2)).then(exitWhenFlushed, (error) => {
|
|
|
437
487
|
process.stderr.write(`toolmenu: ${failureMessage(error)}\n`);
|
|
438
488
|
exitWhenFlushed(2);
|
|
439
489
|
});
|
|
490
|
+
function explainCommand(rest, command, format) {
|
|
491
|
+
if (command)
|
|
492
|
+
throw new UsageError("explain takes a rule's name, not a server.");
|
|
493
|
+
if (format !== 'text' && format !== 'json')
|
|
494
|
+
throw new UsageError('explain prints text, or JSON with --json.');
|
|
495
|
+
if (rest.length > 1)
|
|
496
|
+
throw new UsageError(`explain takes one rule at a time; got ${rest.length}.`);
|
|
497
|
+
if (!rest.length) {
|
|
498
|
+
process.stdout.write(format === 'json' ? `${JSON.stringify(Object.keys(ruleDocs()))}\n` : listRules());
|
|
499
|
+
return 0;
|
|
500
|
+
}
|
|
501
|
+
const found = findRule(rest[0]);
|
|
502
|
+
if ('near' in found) {
|
|
503
|
+
const hint = found.near.length ? ` Did you mean ${found.near.join(', ')}?` : '';
|
|
504
|
+
throw new UsageError(`No rule "${rest[0]}".${hint} toolmenu explain lists every rule.`);
|
|
505
|
+
}
|
|
506
|
+
const e = explain(found.id);
|
|
507
|
+
process.stdout.write(format === 'json' ? `${JSON.stringify(e, null, 2)}\n` : formatExplained(e));
|
|
508
|
+
return 0;
|
|
509
|
+
}
|
|
440
510
|
/** What stopped the command. A mistyped option gets the nearest real one. */
|
|
441
511
|
function failureMessage(error) {
|
|
442
512
|
const message = error instanceof Error ? error.message : String(error);
|
|
@@ -471,19 +541,6 @@ function commandIn(args) {
|
|
|
471
541
|
}
|
|
472
542
|
return undefined;
|
|
473
543
|
}
|
|
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
544
|
function parseRelease(value) {
|
|
488
545
|
const m = /^(.+?)\.\.(.+)$/.exec(value);
|
|
489
546
|
if (!m)
|
package/dist/connect.d.ts
CHANGED
|
@@ -78,5 +78,13 @@ export interface ToolList {
|
|
|
78
78
|
/** Set when the SDK client rejected the result (toolmenu still reads it off the wire). */
|
|
79
79
|
clientError?: string;
|
|
80
80
|
}
|
|
81
|
+
/**
|
|
82
|
+
* The proxy and CA settings of this process, for a stdio server: the SDK passes a
|
|
83
|
+
* minimal environment (PATH, HOME…), so a server that calls an API at startup (Stripe,
|
|
84
|
+
* Supabase) couldn't get out behind a proxy and failed with nothing to say why. Node's
|
|
85
|
+
* fetch reads HTTPS_PROXY only with NODE_USE_ENV_PROXY=1, so that's set too when a proxy
|
|
86
|
+
* is. --env overrides each.
|
|
87
|
+
*/
|
|
88
|
+
export declare function proxyEnvironment(env?: NodeJS.ProcessEnv): Record<string, string>;
|
|
81
89
|
/** One full `tools/list`, bypassing the SDK's cache, read from the wire rather than the SDK's parsed copy. */
|
|
82
90
|
export declare function listTools(connection: Connection, options?: ConnectOptions): Promise<ToolList>;
|
package/dist/connect.js
CHANGED
|
@@ -115,7 +115,7 @@ export async function connect(target, options = {}) {
|
|
|
115
115
|
const stdio = new StdioClientTransport({
|
|
116
116
|
command: target.command,
|
|
117
117
|
args: target.args,
|
|
118
|
-
env: { ...getDefaultEnvironment(), ...target.env },
|
|
118
|
+
env: { ...getDefaultEnvironment(), ...proxyEnvironment(), ...target.env },
|
|
119
119
|
cwd: target.cwd,
|
|
120
120
|
stderr: 'pipe',
|
|
121
121
|
});
|
|
@@ -289,6 +289,28 @@ function tracedFetch(trace) {
|
|
|
289
289
|
return response;
|
|
290
290
|
};
|
|
291
291
|
}
|
|
292
|
+
/**
|
|
293
|
+
* The proxy and CA settings of this process, for a stdio server: the SDK passes a
|
|
294
|
+
* minimal environment (PATH, HOME…), so a server that calls an API at startup (Stripe,
|
|
295
|
+
* Supabase) couldn't get out behind a proxy and failed with nothing to say why. Node's
|
|
296
|
+
* fetch reads HTTPS_PROXY only with NODE_USE_ENV_PROXY=1, so that's set too when a proxy
|
|
297
|
+
* is. --env overrides each.
|
|
298
|
+
*/
|
|
299
|
+
export function proxyEnvironment(env = process.env) {
|
|
300
|
+
const proxied = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy'].some((k) => env[k]);
|
|
301
|
+
const names = [
|
|
302
|
+
...(proxied ? ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy', 'NO_PROXY', 'no_proxy'] : []),
|
|
303
|
+
// Certificates a proxy that inspects TLS needs trusted, by Node, Python and curl.
|
|
304
|
+
'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE', 'SSL_CERT_DIR', 'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE',
|
|
305
|
+
];
|
|
306
|
+
const out = {};
|
|
307
|
+
for (const k of names)
|
|
308
|
+
if (env[k])
|
|
309
|
+
out[k] = env[k];
|
|
310
|
+
if (proxied)
|
|
311
|
+
out.NODE_USE_ENV_PROXY = env.NODE_USE_ENV_PROXY || '1';
|
|
312
|
+
return out;
|
|
313
|
+
}
|
|
292
314
|
/** One full `tools/list`, bypassing the SDK's cache, read from the wire rather than the SDK's parsed copy. */
|
|
293
315
|
export async function listTools(connection, options = {}) {
|
|
294
316
|
const mark = connection.wire.responses.length;
|
package/dist/diff.js
CHANGED
|
@@ -5,6 +5,7 @@ import { headerFaults } from './rules/headers.js';
|
|
|
5
5
|
import { indexSchema } from './schema-ref.js';
|
|
6
6
|
import { isCalendar, parseSemver } from './semver.js';
|
|
7
7
|
import { SEVERITY_RANK } from './types.js';
|
|
8
|
+
import { editDistance } from './words.js';
|
|
8
9
|
/** Every diff rule, its default severity and what it means for semver. */
|
|
9
10
|
export const DIFF_RULES = {
|
|
10
11
|
'diff/tool-removed': { severity: 'error', class: 'breaking' },
|
|
@@ -780,16 +781,6 @@ function closeNames(a, b) {
|
|
|
780
781
|
return false;
|
|
781
782
|
return editDistance(x, y) <= (long.length >= 10 ? 2 : 1);
|
|
782
783
|
}
|
|
783
|
-
function editDistance(a, b) {
|
|
784
|
-
let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
|
|
785
|
-
for (let i = 1; i <= a.length; i++) {
|
|
786
|
-
const row = [i];
|
|
787
|
-
for (let j = 1; j <= b.length; j++)
|
|
788
|
-
row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
|
|
789
|
-
prev = row;
|
|
790
|
-
}
|
|
791
|
-
return prev[b.length];
|
|
792
|
-
}
|
|
793
784
|
/** The same type, or one side an array of the other's type. */
|
|
794
785
|
function sameKind(a, b) {
|
|
795
786
|
const [x, y] = [typeOf(a), typeOf(b)];
|
package/dist/explain.d.ts
CHANGED
|
@@ -39,6 +39,7 @@ export declare class Trace {
|
|
|
39
39
|
readonly stderrTail: string[];
|
|
40
40
|
stderrLines: number;
|
|
41
41
|
private stderrPartial;
|
|
42
|
+
private ownWarning;
|
|
42
43
|
send(method: string): void;
|
|
43
44
|
/** A chunk of the server's stdout: remembers lines that aren't JSON-RPC messages. */
|
|
44
45
|
stdout(chunk: string): void;
|
|
@@ -124,3 +125,11 @@ export interface ExplainContext {
|
|
|
124
125
|
* when there's nothing to add (a refusal for too many requests keeps its own path).
|
|
125
126
|
*/
|
|
126
127
|
export declare function explain(error: unknown, trace: Trace, context: ExplainContext): unknown;
|
|
128
|
+
/**
|
|
129
|
+
* A proxy this machine sets that Node's built-in fetch ignores: it reads HTTPS_PROXY
|
|
130
|
+
* only with NODE_USE_ENV_PROXY=1 (Node 22.21 and later). Behind such a proxy, every
|
|
131
|
+
* host looks like it doesn't resolve.
|
|
132
|
+
*/
|
|
133
|
+
export declare function ignoredProxy(env?: NodeJS.ProcessEnv, host?: string): string | undefined;
|
|
134
|
+
/** What to do about an ignored proxy, for this Node. */
|
|
135
|
+
export declare function proxyAdvice(proxy: string, version?: string): string;
|