toolmenu 0.18.0 → 0.20.1
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 +18 -5
- package/dist/auto.js +9 -3
- package/dist/catalog.js +4 -0
- package/dist/cli.js +10 -3
- package/dist/clients.d.ts +7 -1
- package/dist/clients.js +29 -6
- package/dist/config.d.ts +2 -0
- package/dist/config.js +6 -2
- package/dist/diff.js +90 -0
- package/dist/explain.d.ts +8 -0
- package/dist/explain.js +44 -5
- package/dist/failures.d.ts +1 -1
- package/dist/failures.js +12 -2
- package/dist/help.js +2 -1
- package/dist/lists.d.ts +40 -0
- package/dist/lists.js +91 -0
- package/dist/options.d.ts +3 -0
- package/dist/options.js +1 -0
- package/dist/report.d.ts +1 -1
- package/dist/report.js +19 -1
- package/dist/rules/clients.js +2 -2
- package/dist/rules/description.js +1 -1
- package/dist/rules/index.js +5 -1
- package/dist/rules/lists.d.ts +16 -0
- package/dist/rules/lists.js +102 -0
- package/dist/rules/rule.d.ts +2 -0
- package/dist/rules/search.js +2 -2
- package/dist/rules/spec.d.ts +2 -0
- package/dist/rules/spec.js +17 -8
- package/dist/rules/write.d.ts +7 -0
- package/dist/rules/write.js +41 -7
- package/dist/snapshot.d.ts +5 -0
- package/dist/snapshot.js +33 -2
- package/dist/types.d.ts +4 -0
- package/dist/words.d.ts +6 -0
- package/dist/words.js +9 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -23,7 +23,15 @@ connections and releases, and checks **when** it changes:
|
|
|
23
23
|
It also checks the menu clients will actually show: a broken `x-mcp-header` or a
|
|
24
24
|
`$ref` they can't resolve hides a tool or fails every call to it. And when a tool
|
|
25
25
|
stops to ask the user something, `session` answers "no" and says whether the tool
|
|
26
|
-
can take it.
|
|
26
|
+
can take it. Handles a server mints (`session_id`) should say how long they last and
|
|
27
|
+
fail readably when unknown; menus that differ by who asks (`--as`) shouldn't be
|
|
28
|
+
cached as public; prompts and resources (`--lists`) are checked like tools. Run
|
|
29
|
+
against the reference server, `@modelcontextprotocol/server-everything` 2.1.0, with
|
|
30
|
+
no false findings ([bench/](bench/README.md)).
|
|
31
|
+
- **For your client.** `--client claude-code | claude-api-search | openai` checks the
|
|
32
|
+
menu the way that client loads it, from its own docs: what it costs up front and per
|
|
33
|
+
tool a search loads, where it cuts descriptions, what its search can find, and names
|
|
34
|
+
its API refuses.
|
|
27
35
|
- **Between releases.** `diff` finds breaking changes and token growth, and checks
|
|
28
36
|
the version bump.
|
|
29
37
|
|
|
@@ -247,9 +255,9 @@ the way OpenAPI breaking-change checkers do it:
|
|
|
247
255
|
|
|
248
256
|
| Class | Changes | Rules |
|
|
249
257
|
|---|---|---|
|
|
250
|
-
| **breaking** (error) | tool removed or renamed, parameter removed, new required parameter, narrower or different type, enum narrowed, unlisted properties now rejected (`additionalProperties: false` added), a tool becoming less safe (no longer read-only, or additive → destructive) | `diff/tool-removed`, `diff/tool-renamed`, `diff/param-removed`, `diff/param-required`, `diff/param-type`, `diff/enum-narrowed`, `diff/properties-closed`, `diff/safety-hint` |
|
|
251
|
-
| **minor** (info) | tool added, new optional parameter, parameter now optional, type or enum widened, unlisted properties now accepted (`additionalProperties: false` removed) | `diff/tool-added`, `diff/param-added`, `diff/param-relaxed`, `diff/type-widened`, `diff/enum-widened`, `diff/properties-opened` |
|
|
252
|
-
| **notice** (info) | optional parameter dropped (extra properties still allowed), description changed (with the text diff: it changes what the agent does), output schema, annotations, other fields, order, a schema restructured but accepting the same input, only the declared `$schema` dialect changed | `diff/param-dropped`, `diff/description`, `diff/schema-other`, `diff/annotations`, `diff/other`, `diff/order`, `diff/schema-equivalent`, `diff/schema-dialect` |
|
|
258
|
+
| **breaking** (error) | tool removed or renamed, parameter removed, new required parameter, narrower or different type, enum narrowed, unlisted properties now rejected (`additionalProperties: false` added), a tool becoming less safe (no longer read-only, or additive → destructive); with `--lists` on both sides, a prompt removed or newly requiring an argument, a resource template removed | `diff/tool-removed`, `diff/tool-renamed`, `diff/param-removed`, `diff/param-required`, `diff/param-type`, `diff/enum-narrowed`, `diff/properties-closed`, `diff/safety-hint`, `diff/prompt-removed`, `diff/prompt-argument-required`, `diff/resource-template-removed` |
|
|
259
|
+
| **minor** (info) | tool added, new optional parameter, parameter now optional, type or enum widened, unlisted properties now accepted (`additionalProperties: false` removed), a prompt or resource template added | `diff/tool-added`, `diff/param-added`, `diff/param-relaxed`, `diff/type-widened`, `diff/enum-widened`, `diff/properties-opened`, `diff/prompt-added`, `diff/resource-template-added` |
|
|
260
|
+
| **notice** (info) | optional parameter dropped (extra properties still allowed), description changed (with the text diff: it changes what the agent does), output schema, annotations, other fields, order, a schema restructured but accepting the same input, only the declared `$schema` dialect changed, a prompt's description or optional arguments, resources added or gone (data, so no bump) | `diff/param-dropped`, `diff/description`, `diff/schema-other`, `diff/annotations`, `diff/other`, `diff/order`, `diff/schema-equivalent`, `diff/schema-dialect`, `diff/prompt-changed`, `diff/resources` |
|
|
253
261
|
|
|
254
262
|
The same rules apply inside parameters: fields of an object parameter, array items,
|
|
255
263
|
and the options of an `anyOf`/`oneOf` union (zod's unions, discriminated unions and
|
|
@@ -391,9 +399,12 @@ server, or from the spec itself. If a rule can't point to one, it doesn't ship.
|
|
|
391
399
|
| `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) |
|
|
392
400
|
| `write/unannotated` | warn | Tools named like writes (`delete_`, `send_`…) with no annotations, as one summary grouped by the annotation each name suggests |
|
|
393
401
|
| `naming/shared-word` | info | Nouns that name different things across tools (`list_team_audits` vs `get_audit_trail`), as one summary |
|
|
402
|
+
| `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) |
|
|
394
403
|
| `write/no-dry-run` | info | Destructive tools with no dry-run parameter or preview tool, as one summary |
|
|
395
404
|
| `spec/discover` | info | The server only speaks the 2025 protocol, so 2026-07-28 rules are skipped |
|
|
396
405
|
| `spec/deprecated`, `spec/cache-hints` | info | 2026-07-28: deprecated features still advertised; `ttlMs: 0`, or `cacheScope: "public"` on a server that took credentials |
|
|
406
|
+
| `lists/variance` | warn | With `--lists`: `prompts/list`, `resources/list` or `resources/templates/list` differs between two calls, or from a second process or connection (2026-07-28: lists no longer vary per connection) |
|
|
407
|
+
| `lists/schema` | error | With `--lists`: a list result that doesn't match the official schema (2026-07-28 requires `ttlMs` and `cacheScope` on each), or a declared list that fails to answer (warn; info for Method not found, or a setup failure such as missing credentials) |
|
|
397
408
|
| `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 |
|
|
398
409
|
| `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 |
|
|
399
410
|
| `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 |
|
|
@@ -455,7 +466,7 @@ client doesn't document is left out, not guessed.
|
|
|
455
466
|
|---|---|---|---|---|
|
|
456
467
|
| `claude-code` | tool names; full definitions for tools marked `_meta["anthropic/alwaysLoad"]` | reads a description up to 4,096 characters | 16,384 through search, 4,096 up front | Claude API's |
|
|
457
468
|
| `claude-api-search` | nothing from tools you defer (keep the 3–5 used most loaded) | name, description, argument names and descriptions; 5 results by default | none documented | `^[a-zA-Z0-9_-]{1,128}$` |
|
|
458
|
-
| `openai` |
|
|
469
|
+
| `openai` | each deferred function's name and description (its schema loads on demand); a deferred MCP server shows only its own name and description | how many results, and which fields, isn't documented, so `search/findable` doesn't run | none documented | `^[a-zA-Z0-9_-]+$`, up to 128 |
|
|
459
470
|
|
|
460
471
|
The snapshot adds a line such as `as Claude Code: up front ~524 tokens · on demand ~344
|
|
461
472
|
per tool a search loads (largest: update_contacts, ~2,093)`, and `--json` a `client`
|
|
@@ -493,6 +504,8 @@ toolmenu sees what the server sends. Plenty of agent failures happen elsewhere:
|
|
|
493
504
|
(2026-07-28 only; an error if the server lacks it)
|
|
494
505
|
--processes <n> server processes or connections to compare (default: 2);
|
|
495
506
|
1 opens no second one, session's scope check included
|
|
507
|
+
--lists <kinds> snapshot: also read and check prompts, resources (comma-separated);
|
|
508
|
+
saved in the menu file beside the tools
|
|
496
509
|
--client <name> snapshot: check the menu for one client, from its own docs:
|
|
497
510
|
claude-code, claude-api-search or openai
|
|
498
511
|
--as <name>:<cred> snapshot: list the menu as this identity too, repeatable:
|
package/dist/auto.js
CHANGED
|
@@ -3,7 +3,7 @@ import { isMap, isNode, isScalar, parseDocument } from 'yaml';
|
|
|
3
3
|
import { synthesizeArgs } from './args.js';
|
|
4
4
|
import { createdKinds, 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
|
}
|
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
|
@@ -3,6 +3,7 @@ import { 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';
|
|
6
|
+
import { LIST_WORDS } from './lists.js';
|
|
6
7
|
import { loadConfig } from './config.js';
|
|
7
8
|
import { ELICITATIONS, PROTOCOLS } from './connect.js';
|
|
8
9
|
import { diffMenus } from './diff.js';
|
|
@@ -83,9 +84,15 @@ export async function main(argv) {
|
|
|
83
84
|
const elicitation = (values.elicitation ?? 'decline');
|
|
84
85
|
if (!ELICITATIONS.includes(elicitation))
|
|
85
86
|
throw new UsageError('--elicitation must be decline or cancel');
|
|
87
|
+
if (values.lists !== undefined && sub !== 'snapshot')
|
|
88
|
+
throw new UsageError('--lists goes with snapshot.');
|
|
89
|
+
const lists = values.lists !== undefined ? values.lists.split(',').map((w) => w.trim()).filter(Boolean) : config.lists;
|
|
90
|
+
const badList = (lists ?? []).find((w) => !LIST_WORDS.includes(w));
|
|
91
|
+
if (badList)
|
|
92
|
+
throw new UsageError(`--lists takes ${LIST_WORDS.join(', ')}, comma-separated; not "${badList}"`);
|
|
86
93
|
if (values.client !== undefined && sub !== 'snapshot')
|
|
87
94
|
throw new UsageError('--client goes with snapshot.');
|
|
88
|
-
if (values.client !== undefined && !(values.client
|
|
95
|
+
if (values.client !== undefined && !Object.hasOwn(CLIENTS, values.client))
|
|
89
96
|
throw new UsageError(`--client must be one of ${CLIENT_NAMES.join(', ')}`);
|
|
90
97
|
if (values.as !== undefined && sub !== 'snapshot')
|
|
91
98
|
throw new UsageError('--as goes with snapshot: it lists the menu once per identity.');
|
|
@@ -306,11 +313,11 @@ export async function main(argv) {
|
|
|
306
313
|
const routesPath = values.routes ?? config.routes;
|
|
307
314
|
const routes = routesPath ? await loadRoutes(routesPath) : undefined;
|
|
308
315
|
const client = values.client ?? config.client;
|
|
309
|
-
const { menu, findings, cost } = await snapshot(target, { routes, timeoutMs, processes, identities, client, catalog: values.catalog ? (config.catalog ?? true) : undefined, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
|
|
316
|
+
const { menu, findings, cost, notOffered } = await snapshot(target, { routes, timeoutMs, processes, identities, client, lists, catalog: values.catalog ? (config.catalog ?? true) : undefined, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
|
|
310
317
|
const outPath = values['no-write'] ? undefined : values.out ?? 'menu.json';
|
|
311
318
|
if (outPath)
|
|
312
319
|
await writeFile(outPath, JSON.stringify(menu, null, 2) + '\n');
|
|
313
|
-
const output = formatSnapshot(menu, findings, format, outPath, cost);
|
|
320
|
+
const output = formatSnapshot(menu, findings, format, outPath, cost, notOffered);
|
|
314
321
|
if (output)
|
|
315
322
|
process.stdout.write(output + '\n');
|
|
316
323
|
return findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
|
package/dist/clients.d.ts
CHANGED
|
@@ -14,7 +14,11 @@ export interface ClientProfile {
|
|
|
14
14
|
*/
|
|
15
15
|
defers: Sourced<'all' | 'chosen' | 'none'>;
|
|
16
16
|
/** What the model has of a deferred tool before it searches: its name, or nothing. */
|
|
17
|
-
|
|
17
|
+
/**
|
|
18
|
+
* What the model has of a deferred tool before it searches: its name, nothing, or its
|
|
19
|
+
* name and description (OpenAI defers the parameter schema).
|
|
20
|
+
*/
|
|
21
|
+
beforeSearch?: Sourced<'name' | 'nothing' | 'name-and-description'>;
|
|
18
22
|
/** Where the client cuts a description: for a tool loaded up front, and one loaded through search. */
|
|
19
23
|
descriptionCut?: Sourced<{
|
|
20
24
|
upfront: number;
|
|
@@ -37,6 +41,8 @@ export interface ClientProfile {
|
|
|
37
41
|
}
|
|
38
42
|
export declare const CLIENTS: Record<string, ClientProfile>;
|
|
39
43
|
export declare const CLIENT_NAMES: string[];
|
|
44
|
+
/** A client's profile by name: own keys only ("toString" names no client). */
|
|
45
|
+
export declare function profileOf(name: string | undefined): ClientProfile | undefined;
|
|
40
46
|
/** The profile for a client name, or undefined for none given. Throws for an unknown name. */
|
|
41
47
|
export declare function clientProfile(name: string | undefined): ClientProfile | undefined;
|
|
42
48
|
/** Whether a tool name fits the client's API, and why not. */
|
package/dist/clients.js
CHANGED
|
@@ -9,6 +9,7 @@ const CLAUDE_CODE_MCP = 'https://code.claude.com/docs/en/mcp';
|
|
|
9
9
|
const CLAUDE_TOOL_SEARCH = 'https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool';
|
|
10
10
|
const CLAUDE_DEFINE_TOOLS = 'https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools';
|
|
11
11
|
const OPENAI_SPEC = 'https://github.com/openai/openai-openapi (openapi.yaml: FunctionToolParam, NamespaceToolParam, MCPTool)';
|
|
12
|
+
const OPENAI_TOOL_SEARCH = 'https://developers.openai.com/api/docs/guides/tools-tool-search';
|
|
12
13
|
const READ = '2026-11-02';
|
|
13
14
|
const claudeName = { value: { pattern: '^[a-zA-Z0-9_-]{1,128}$', max: 128, api: 'the Claude API' }, source: CLAUDE_DEFINE_TOOLS, read: READ };
|
|
14
15
|
export const CLIENTS = {
|
|
@@ -42,16 +43,26 @@ export const CLIENTS = {
|
|
|
42
43
|
label: "OpenAI's tool_search (Responses API)",
|
|
43
44
|
// FunctionToolParam.defer_loading, MCPTool.defer_loading: per function, or per MCP server.
|
|
44
45
|
defers: { value: 'chosen', source: OPENAI_SPEC, read: READ },
|
|
46
|
+
// "For an individual deferred function, the model still sees the function name and description,
|
|
47
|
+
// so in practice tool search is mostly deferring the parameter schema." For an MCP server or
|
|
48
|
+
// namespace, "the model sees only the namespace or server name and description at the beginning".
|
|
49
|
+
beforeSearch: { value: 'name-and-description', source: OPENAI_TOOL_SEARCH, read: '2026-11-03' },
|
|
50
|
+
// Not in the guide or the spec: how many tools a search returns, and which fields it matches on.
|
|
51
|
+
// So search/findable doesn't rank for OpenAI.
|
|
45
52
|
// FunctionToolParam.name: maxLength 128, pattern ^[a-zA-Z0-9_-]+$.
|
|
46
53
|
namePattern: { value: { pattern: '^[a-zA-Z0-9_-]+$', max: 128, api: "OpenAI's Responses API" }, source: OPENAI_SPEC, read: READ },
|
|
47
54
|
},
|
|
48
55
|
};
|
|
49
56
|
export const CLIENT_NAMES = Object.keys(CLIENTS);
|
|
57
|
+
/** A client's profile by name: own keys only ("toString" names no client). */
|
|
58
|
+
export function profileOf(name) {
|
|
59
|
+
return name !== undefined && Object.hasOwn(CLIENTS, name) ? CLIENTS[name] : undefined;
|
|
60
|
+
}
|
|
50
61
|
/** The profile for a client name, or undefined for none given. Throws for an unknown name. */
|
|
51
62
|
export function clientProfile(name) {
|
|
52
63
|
if (name === undefined)
|
|
53
64
|
return undefined;
|
|
54
|
-
const profile =
|
|
65
|
+
const profile = profileOf(name);
|
|
55
66
|
if (!profile)
|
|
56
67
|
throw new Error(`unknown client "${name}": one of ${CLIENT_NAMES.join(', ')}`);
|
|
57
68
|
return profile;
|
|
@@ -75,21 +86,33 @@ export function loadsUpfront(tool) {
|
|
|
75
86
|
}
|
|
76
87
|
/** What the menu costs under a client that defers tools: up front, and per tool a search loads. */
|
|
77
88
|
export function clientCost(name, menu) {
|
|
78
|
-
const profile =
|
|
89
|
+
const profile = profileOf(name);
|
|
79
90
|
if (!profile || profile.defers.value === 'none')
|
|
80
91
|
return undefined;
|
|
81
92
|
const loaded = profile.defers.value === 'all' ? menu.tools.filter(loadsUpfront) : [];
|
|
82
93
|
const deferred = menu.tools.filter((t) => !loaded.includes(t));
|
|
83
|
-
const perTool = deferred.length ? Math.round(deferred.reduce((n, t) => n + t.tokens, 0) / deferred.length) : 0;
|
|
84
|
-
const largest = [...deferred].sort((a, b) => b.tokens - a.tokens)[0];
|
|
85
94
|
const loadedTokens = loaded.reduce((n, t) => n + t.tokens, 0);
|
|
86
95
|
const seen = profile.beforeSearch?.value;
|
|
87
|
-
|
|
96
|
+
// OpenAI keeps a deferred function's name and description up front: what a search adds is the rest.
|
|
97
|
+
const seenUpfront = (t) => countTokens(`${t.name}\n${t.description ?? ''}`);
|
|
98
|
+
const upfront = seen === 'name'
|
|
99
|
+
? countTokens(deferred.map((t) => t.name).join('\n')) + loadedTokens
|
|
100
|
+
: seen === 'nothing'
|
|
101
|
+
? loadedTokens
|
|
102
|
+
: seen === 'name-and-description'
|
|
103
|
+
? deferred.reduce((n, t) => n + seenUpfront(t), 0) + loadedTokens
|
|
104
|
+
: undefined;
|
|
105
|
+
const onDemand = (t) => (seen === 'name-and-description' ? Math.max(0, t.tokens - seenUpfront(t)) : t.tokens);
|
|
88
106
|
const basis = seen === 'name'
|
|
89
107
|
? `${profile.label} defers MCP tools and shows their names until a search loads one; the server's instructions load up front too and aren't counted here (${profile.beforeSearch.source}, read ${profile.beforeSearch.read})`
|
|
90
108
|
: seen === 'nothing'
|
|
91
109
|
? `with every tool deferred, the model sees none of them until a search loads one, and the docs advise keeping the 3–5 tools used most loaded (${profile.beforeSearch.source}, read ${profile.beforeSearch.read})`
|
|
92
|
-
:
|
|
110
|
+
: seen === 'name-and-description'
|
|
111
|
+
? `deferred as functions, each tool's name and description stay up front and its schema loads on demand; deferred as one MCP server, the model sees only the server's name and description (set where the server is added) until a search loads its tools (${profile.beforeSearch.source}, read ${profile.beforeSearch.read})`
|
|
112
|
+
: `${profile.label} defers per function or per MCP server; what the model sees before a search isn't documented, so no up-front figure`;
|
|
113
|
+
const perTool = deferred.length ? Math.round(deferred.reduce((n, t) => n + onDemand(t), 0) / deferred.length) : 0;
|
|
114
|
+
const biggest = [...deferred].sort((a, b) => onDemand(b) - onDemand(a))[0];
|
|
115
|
+
const largest = biggest ? { name: biggest.name, tokens: onDemand(biggest) } : undefined;
|
|
93
116
|
return {
|
|
94
117
|
client: name,
|
|
95
118
|
label: profile.label,
|
package/dist/config.d.ts
CHANGED
|
@@ -26,6 +26,8 @@ export interface Config {
|
|
|
26
26
|
headers?: Record<string, string>;
|
|
27
27
|
env?: Record<string, string>;
|
|
28
28
|
}>;
|
|
29
|
+
/** snapshot: which lists to read besides tools: ["prompts", "resources"]. --lists wins. */
|
|
30
|
+
lists?: string[];
|
|
29
31
|
/** snapshot: the client to check the menu for (claude-code, claude-api-search, openai). --client wins. */
|
|
30
32
|
client?: string;
|
|
31
33
|
/** Server processes (stdio) or connections (HTTP) to compare, the main one included (default 2). */
|
package/dist/config.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { existsSync } from 'node:fs';
|
|
2
2
|
import { readFile } from 'node:fs/promises';
|
|
3
3
|
import { CLIENTS } from './clients.js';
|
|
4
|
+
import { LIST_WORDS } from './lists.js';
|
|
4
5
|
import { CLIENT_LIMITS } from './rules/description.js';
|
|
5
6
|
const DEFAULT_PATH = 'toolmenu.config.json';
|
|
6
7
|
/** Optional: no config file is fine. */
|
|
@@ -24,13 +25,16 @@ export async function loadConfig(path) {
|
|
|
24
25
|
throw new Error(`${file}: protocol must be auto, legacy or modern`);
|
|
25
26
|
}
|
|
26
27
|
const limit = config.descriptionLimit;
|
|
27
|
-
if (limit !== undefined && !(typeof limit === 'number' && limit > 0) && !(typeof limit === 'string' && limit
|
|
28
|
+
if (limit !== undefined && !(typeof limit === 'number' && limit > 0) && !(typeof limit === 'string' && Object.hasOwn(CLIENT_LIMITS, limit))) {
|
|
28
29
|
throw new Error(`${file}: descriptionLimit must be a positive number or one of ${Object.keys(CLIENT_LIMITS).join(', ')}`);
|
|
29
30
|
}
|
|
30
31
|
if (config.processes !== undefined && !(Number.isInteger(config.processes) && config.processes >= 1)) {
|
|
31
32
|
throw new Error(`${file}: processes must be a whole number, 1 or more`);
|
|
32
33
|
}
|
|
33
|
-
if (config.
|
|
34
|
+
if (config.lists !== undefined && !(Array.isArray(config.lists) && config.lists.every((l) => LIST_WORDS.includes(l)))) {
|
|
35
|
+
throw new Error(`${file}: lists must be a list of ${LIST_WORDS.join(', ')}`);
|
|
36
|
+
}
|
|
37
|
+
if (config.client !== undefined && !(typeof config.client === 'string' && Object.hasOwn(CLIENTS, config.client))) {
|
|
34
38
|
throw new Error(`${file}: client must be one of ${Object.keys(CLIENTS).join(', ')}`);
|
|
35
39
|
}
|
|
36
40
|
if (config.identities !== undefined) {
|
package/dist/diff.js
CHANGED
|
@@ -53,6 +53,17 @@ export const DIFF_RULES = {
|
|
|
53
53
|
'diff/catalog-missing': { severity: 'info' },
|
|
54
54
|
'diff/catalog-added': { severity: 'info' },
|
|
55
55
|
'diff/catalog-queries': { severity: 'info' },
|
|
56
|
+
// snapshot --lists: prompts are called by name like tools, and resource templates are
|
|
57
|
+
// the URIs clients read through. Concrete resources are data (files come and go):
|
|
58
|
+
// counted, no bump. Only compared when both menus read the list.
|
|
59
|
+
'diff/prompt-removed': { severity: 'error', class: 'breaking' },
|
|
60
|
+
'diff/prompt-argument-required': { severity: 'error', class: 'breaking' },
|
|
61
|
+
'diff/prompt-added': { severity: 'info', class: 'minor' },
|
|
62
|
+
'diff/prompt-changed': { severity: 'info', class: 'notice' },
|
|
63
|
+
'diff/resource-template-removed': { severity: 'error', class: 'breaking' },
|
|
64
|
+
'diff/resource-template-added': { severity: 'info', class: 'minor' },
|
|
65
|
+
'diff/resources': { severity: 'info', class: 'notice' },
|
|
66
|
+
'diff/lists-unread': { severity: 'info' },
|
|
56
67
|
};
|
|
57
68
|
/**
|
|
58
69
|
* In fixes: the release a breaking change should ship in. Resolved once the
|
|
@@ -135,6 +146,7 @@ export function diffMenus(before, after, options = {}) {
|
|
|
135
146
|
});
|
|
136
147
|
}
|
|
137
148
|
raw.push(...compareCatalogs(before.catalog, after.catalog, ignored));
|
|
149
|
+
raw.push(...compareLists(before, after));
|
|
138
150
|
// Ignored tools leave the token counts and the budget too.
|
|
139
151
|
const tokens = tokenChange(oldTools, newTools);
|
|
140
152
|
if (options.tokenBudget !== undefined && tokens.after > options.tokenBudget) {
|
|
@@ -1220,6 +1232,84 @@ function expandRefs(schema) {
|
|
|
1220
1232
|
return { schema, expanded: false };
|
|
1221
1233
|
}
|
|
1222
1234
|
}
|
|
1235
|
+
/** The arguments a prompt requires. */
|
|
1236
|
+
function requiredArguments(p) {
|
|
1237
|
+
return (Array.isArray(p.arguments) ? p.arguments : []).filter((a) => a.required === true).map((a) => String(a.name));
|
|
1238
|
+
}
|
|
1239
|
+
/**
|
|
1240
|
+
* snapshot --lists: prompts, resource templates and resources between two menus.
|
|
1241
|
+
* A list only one menu read isn't compared (everything would read as added or removed).
|
|
1242
|
+
*/
|
|
1243
|
+
function compareLists(before, after) {
|
|
1244
|
+
const out = [];
|
|
1245
|
+
const unread = [];
|
|
1246
|
+
const pair = (key, label) => {
|
|
1247
|
+
const a = before[key];
|
|
1248
|
+
const b = after[key];
|
|
1249
|
+
if (!a && !b)
|
|
1250
|
+
return undefined;
|
|
1251
|
+
if (!a || !b) {
|
|
1252
|
+
unread.push(`${label} (${a ? 'the old' : 'the new'} menu has them, the ${a ? 'new' : 'old'} one wasn't read with --lists)`);
|
|
1253
|
+
return undefined;
|
|
1254
|
+
}
|
|
1255
|
+
return [a, b];
|
|
1256
|
+
};
|
|
1257
|
+
const prompts = pair('prompts', 'prompts');
|
|
1258
|
+
if (prompts) {
|
|
1259
|
+
const [a, b] = prompts;
|
|
1260
|
+
const oldBy = new Map(a.map((p) => [String(p.name), p]));
|
|
1261
|
+
const newBy = new Map(b.map((p) => [String(p.name), p]));
|
|
1262
|
+
for (const [name] of oldBy) {
|
|
1263
|
+
if (!newBy.has(name))
|
|
1264
|
+
out.push({ rule: 'diff/prompt-removed', message: `Prompt ${code(name)} was removed. Users and clients that invoke it by name (a slash command, a saved workflow) now get an error.`, fix: `Keep ${code(name)} for one release, or ${BREAKING_RELEASE}.` });
|
|
1265
|
+
}
|
|
1266
|
+
for (const [name, p] of newBy) {
|
|
1267
|
+
const old = oldBy.get(name);
|
|
1268
|
+
if (!old) {
|
|
1269
|
+
out.push({ rule: 'diff/prompt-added', message: `Prompt ${code(name)} is new.` });
|
|
1270
|
+
continue;
|
|
1271
|
+
}
|
|
1272
|
+
const required = requiredArguments(p).filter((r) => !requiredArguments(old).includes(r));
|
|
1273
|
+
if (required.length) {
|
|
1274
|
+
out.push({ rule: 'diff/prompt-argument-required', message: `Prompt ${code(name)} now requires ${required.map(code).join(', ')}. Invocations that don't pass ${required.length === 1 ? 'it' : 'them'} now fail.`, fix: `Make ${required.length === 1 ? 'it' : 'them'} optional, or ${BREAKING_RELEASE}.` });
|
|
1275
|
+
}
|
|
1276
|
+
else if (JSON.stringify(old) !== JSON.stringify(p)) {
|
|
1277
|
+
out.push({ rule: 'diff/prompt-changed', message: `Prompt ${code(name)} changed (its description or arguments), and nothing it requires.` });
|
|
1278
|
+
}
|
|
1279
|
+
}
|
|
1280
|
+
}
|
|
1281
|
+
const templates = pair('resourceTemplates', 'resource templates');
|
|
1282
|
+
if (templates) {
|
|
1283
|
+
const [a, b] = templates;
|
|
1284
|
+
const oldSet = new Set(a.map((t) => String(t.uriTemplate)));
|
|
1285
|
+
const newSet = new Set(b.map((t) => String(t.uriTemplate)));
|
|
1286
|
+
for (const t of oldSet)
|
|
1287
|
+
if (!newSet.has(t))
|
|
1288
|
+
out.push({ rule: 'diff/resource-template-removed', message: `Resource template ${code(t)} was removed. Clients that read resources through it now get an error.`, fix: `Keep ${code(t)} for one release, or ${BREAKING_RELEASE}.` });
|
|
1289
|
+
for (const t of newSet)
|
|
1290
|
+
if (!oldSet.has(t))
|
|
1291
|
+
out.push({ rule: 'diff/resource-template-added', message: `Resource template ${code(t)} is new.` });
|
|
1292
|
+
}
|
|
1293
|
+
const resources = pair('resources', 'resources');
|
|
1294
|
+
if (resources) {
|
|
1295
|
+
const [a, b] = resources;
|
|
1296
|
+
const oldSet = new Set(a.map((r) => String(r.uri)));
|
|
1297
|
+
const newSet = new Set(b.map((r) => String(r.uri)));
|
|
1298
|
+
const gone = [...oldSet].filter((u) => !newSet.has(u));
|
|
1299
|
+
const fresh = [...newSet].filter((u) => !oldSet.has(u));
|
|
1300
|
+
if (gone.length || fresh.length) {
|
|
1301
|
+
out.push({
|
|
1302
|
+
rule: 'diff/resources',
|
|
1303
|
+
message: `The resources list changed: ${[fresh.length ? `${fresh.length} new` : '', gone.length ? `${gone.length} gone` : ''].filter(Boolean).join(', ')}. Resources are often data that changes between runs; a resource clients rely on by URI going away is worth a look.`,
|
|
1304
|
+
detail: [...gone.slice(0, 5).map((u) => `gone: ${u}`), ...fresh.slice(0, 5).map((u) => `new: ${u}`), ...(gone.length + fresh.length > 10 ? ['…'] : [])],
|
|
1305
|
+
});
|
|
1306
|
+
}
|
|
1307
|
+
}
|
|
1308
|
+
if (unread.length) {
|
|
1309
|
+
out.push({ rule: 'diff/lists-unread', message: `Not compared: ${unread.join('; ')}.`, fix: 'Snapshot both releases with the same --lists to compare them.' });
|
|
1310
|
+
}
|
|
1311
|
+
return out;
|
|
1312
|
+
}
|
|
1223
1313
|
/** What the operations are behind: the search tool or router by name, or "the command routers" as words. */
|
|
1224
1314
|
function catalogSource(c) {
|
|
1225
1315
|
return (c.routers?.length ?? 0) > 1 ? c.tool : code(c.tool);
|
package/dist/explain.d.ts
CHANGED
|
@@ -124,3 +124,11 @@ export interface ExplainContext {
|
|
|
124
124
|
* when there's nothing to add (a refusal for too many requests keeps its own path).
|
|
125
125
|
*/
|
|
126
126
|
export declare function explain(error: unknown, trace: Trace, context: ExplainContext): unknown;
|
|
127
|
+
/**
|
|
128
|
+
* A proxy this machine sets that Node's built-in fetch ignores: it reads HTTPS_PROXY
|
|
129
|
+
* only with NODE_USE_ENV_PROXY=1 (Node 22.21 and later). Behind such a proxy, every
|
|
130
|
+
* host looks like it doesn't resolve.
|
|
131
|
+
*/
|
|
132
|
+
export declare function ignoredProxy(env?: NodeJS.ProcessEnv, host?: string): string | undefined;
|
|
133
|
+
/** What to do about an ignored proxy, for this Node. */
|
|
134
|
+
export declare function proxyAdvice(proxy: string, version?: string): string;
|
package/dist/explain.js
CHANGED
|
@@ -164,7 +164,10 @@ const HELP_ROW = /^[ \t]*(?:[a-z][\w.-]*(?: [a-z][\w-]*)?(?: [[<][^\]>]*[\]>])*|
|
|
|
164
164
|
/** Help output, even when the "Usage:" line scrolled out of the stderr kept: three table rows or more. */
|
|
165
165
|
const helpRows = (text) => text.split('\n').filter((l) => HELP_ROW.test(l)).length >= 3;
|
|
166
166
|
// The subcommands that usually start the MCP server, most specific first.
|
|
167
|
-
const SUBCOMMANDS = ['mcp start', 'mcp serve', 'server start', 'mcp', 'stdio', 'serve', 'server', 'start'];
|
|
167
|
+
const SUBCOMMANDS = ['mcp start', 'mcp serve', 'server start', 'mcp', 'stdio', 'serve', 'server', 'start', 'run'];
|
|
168
|
+
// A CLI that names its commands when it gets none: "Unknown command: undefined. Expected
|
|
169
|
+
// 'init' or 'run'." (@cloudflare/mcp-server-cloudflare 0.2.0).
|
|
170
|
+
const EXPECTED_COMMANDS = /\b(?:unknown|invalid|missing|no) (?:sub)?command\b[^\n]*?\bexpected:?\s+((?:["'`][a-z][\w-]*["'`](?:,?\s*(?:or\s+)?)?)+)/i;
|
|
168
171
|
// An HTTP server's address in its log: "MCP server listening on http://localhost:3001/mcp",
|
|
169
172
|
// "StreamableHTTP endpoint available at http://127.0.0.1:3333/mcp".
|
|
170
173
|
const HTTP_URL = /\b(?:listening|available|running|serving|started)\b[^\n]{0,60}?(https?:\/\/[^\s"'<>]+)/gi;
|
|
@@ -202,6 +205,10 @@ function offeredSubcommand(text) {
|
|
|
202
205
|
for (const m of text.matchAll(/\{([^{}\n]*)\}/g))
|
|
203
206
|
for (const w of m[1].split(','))
|
|
204
207
|
offered.add(w.trim());
|
|
208
|
+
const expected = EXPECTED_COMMANDS.exec(text);
|
|
209
|
+
if (expected)
|
|
210
|
+
for (const m of expected[1].matchAll(/["'`]([a-z][\w-]*)["'`]/g))
|
|
211
|
+
offered.add(m[1]);
|
|
205
212
|
let inUsage = false;
|
|
206
213
|
for (const line of text.split('\n')) {
|
|
207
214
|
if (!line.trim()) {
|
|
@@ -236,7 +243,7 @@ export function startupHint(trace, command, { exited = true } = {}) {
|
|
|
236
243
|
const where = url ?? `http://localhost:${port}/mcp`;
|
|
237
244
|
return `The server started an HTTP server (${where}) instead of talking on its stdin and stdout. Start it in stdio mode (${flag ? `its output mentions ${flag}` : 'often --stdio or --transport stdio'}), or run toolmenu against the address while the server runs: toolmenu snapshot ${where}`;
|
|
238
245
|
}
|
|
239
|
-
if (exited && (USAGE.some((re) => re.test(text)) || helpRows(text))) {
|
|
246
|
+
if (exited && (USAGE.some((re) => re.test(text)) || helpRows(text) || EXPECTED_COMMANDS.test(text))) {
|
|
240
247
|
const sub = offeredSubcommand(text);
|
|
241
248
|
return `The command printed its usage and exited: it wants a subcommand or an argument it wasn't given. ${sub ? `Its usage lists “${sub}”: try ${command} ${sub}` : 'Its usage (above) or its docs say what starts the MCP server: add that after the command.'}`;
|
|
242
249
|
}
|
|
@@ -460,6 +467,28 @@ function rejectedCredentials(stderrText) {
|
|
|
460
467
|
return REJECTED.exec(stderrText)?.[0];
|
|
461
468
|
}
|
|
462
469
|
const REJECTED_NEXT = "Check the API key or token the server was given (--env, or its config): it's likely wrong, expired or for another account. This is a reading of the server's log, not certain: read its stderr above.";
|
|
470
|
+
/**
|
|
471
|
+
* A proxy this machine sets that Node's built-in fetch ignores: it reads HTTPS_PROXY
|
|
472
|
+
* only with NODE_USE_ENV_PROXY=1 (Node 22.21 and later). Behind such a proxy, every
|
|
473
|
+
* host looks like it doesn't resolve.
|
|
474
|
+
*/
|
|
475
|
+
export function ignoredProxy(env = process.env, host) {
|
|
476
|
+
if (env.NODE_USE_ENV_PROXY === '1')
|
|
477
|
+
return undefined;
|
|
478
|
+
// A host NO_PROXY exempts goes direct either way: its DNS failure is its own.
|
|
479
|
+
const exempt = (env.NO_PROXY ?? env.no_proxy ?? '').split(',').map((h) => h.trim().replace(/^\*?\./, '').toLowerCase()).filter(Boolean);
|
|
480
|
+
if (host && exempt.some((h) => h === '*' || host.toLowerCase() === h || host.toLowerCase().endsWith(`.${h}`)))
|
|
481
|
+
return undefined;
|
|
482
|
+
return ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy'].find((k) => env[k]);
|
|
483
|
+
}
|
|
484
|
+
/** What to do about an ignored proxy, for this Node. */
|
|
485
|
+
export function proxyAdvice(proxy, version = process.versions.node) {
|
|
486
|
+
const [major, minor] = version.split('.').map(Number);
|
|
487
|
+
const supported = major > 22 || (major === 22 && minor >= 21);
|
|
488
|
+
return supported
|
|
489
|
+
? `This machine sets ${proxy}, but Node's fetch only goes through it with NODE_USE_ENV_PROXY=1: rerun as NODE_USE_ENV_PROXY=1 toolmenu ….`
|
|
490
|
+
: `This machine sets ${proxy}, but Node's fetch doesn't go through it, and Node ${version} can't be told to: Node 22.21 or later reads it with NODE_USE_ENV_PROXY=1.`;
|
|
491
|
+
}
|
|
463
492
|
function firstLine(text) {
|
|
464
493
|
return clean(text.split('\n')[0], 300);
|
|
465
494
|
}
|
|
@@ -477,9 +506,19 @@ function explainHttp(error, trace, context, target) {
|
|
|
477
506
|
const innermost = chain.at(-1);
|
|
478
507
|
// The network, before any HTTP answer.
|
|
479
508
|
if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') {
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
509
|
+
const proxy = ignoredProxy(process.env, host);
|
|
510
|
+
return new ConnectError(code === 'ENOTFOUND' ? `Couldn't find ${host}: the name doesn't resolve (DNS: ENOTFOUND).` : `Couldn't look up ${host}: DNS failed for now (EAI_AGAIN).`, [['url', target.url], ['stage', first], ...(proxy ? [['proxy', `${proxy} is set, but Node's fetch doesn't use it`]] : [])], proxy
|
|
511
|
+
? proxyAdvice(proxy)
|
|
512
|
+
: code === 'ENOTFOUND'
|
|
513
|
+
? "Check the host name for typos. If it's right, the server may have moved or shut down: look up its current URL in its docs or registry entry."
|
|
514
|
+
: 'Check this machine\'s network and DNS, then retry.', stage, { cause: error });
|
|
515
|
+
}
|
|
516
|
+
// A proxy that won't open the tunnel (undici: "Proxy response (502) !== 200 when HTTP Tunneling").
|
|
517
|
+
const tunnel = chain.map((e) => /Proxy response \((\d+)\) !== 200 when HTTP Tunneling/.exec(e.message)).find(Boolean);
|
|
518
|
+
if (tunnel) {
|
|
519
|
+
return new ConnectError(`The proxy couldn't open a connection to ${host}: it answered the tunnel request with HTTP ${tunnel[1]}.`, [['url', target.url], ['stage', first]], tunnel[1] === '403' || tunnel[1] === '407'
|
|
520
|
+
? `The proxy refused ${host}: check what HTTPS_PROXY's policy allows, or run from a machine that can reach it directly.`
|
|
521
|
+
: `The proxy couldn't reach ${host} (often: the host is down or doesn't answer). Check that the server is up, e.g. curl -I ${target.url}, then retry.`, stage, { cause: error });
|
|
483
522
|
}
|
|
484
523
|
if (code === 'ECONNREFUSED') {
|
|
485
524
|
return new ConnectError(`Nothing is listening at ${host}:${port}: the connection was refused (ECONNREFUSED).`, [['url', target.url], ['stage', first]], `Start the server, or check the host and port${url.port ? '' : ` (no port in the URL means ${port})`}.`, stage, { cause: error });
|
package/dist/failures.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export type FailureClass = 'auth' | 'environment' | 'network' | 'not-found' | 'client' | 'invalid-arguments' | 'other';
|
|
1
|
+
export type FailureClass = 'auth' | 'payment' | 'environment' | 'network' | 'not-found' | 'client' | 'invalid-arguments' | 'other';
|
|
2
2
|
/** Failures of the setup (credentials, this machine, the network), not of the server. */
|
|
3
3
|
export declare const SETUP_FAILURES: Set<FailureClass>;
|
|
4
4
|
/**
|
package/dist/failures.js
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* as a finding.
|
|
6
6
|
*/
|
|
7
7
|
/** Failures of the setup (credentials, this machine, the network), not of the server. */
|
|
8
|
-
export const SETUP_FAILURES = new Set(['auth', 'environment', 'network', 'not-found', 'client']);
|
|
8
|
+
export const SETUP_FAILURES = new Set(['auth', 'payment', 'environment', 'network', 'not-found', 'client']);
|
|
9
9
|
// A tool that asks the client for something toolmenu doesn't offer: "Cannot request
|
|
10
10
|
// input 'roots' (roots/list): the request's client capabilities do not declare the
|
|
11
11
|
// required capability" (server-everything's get-roots-list), sampling, elicitation.
|
|
@@ -22,6 +22,11 @@ const ENVIRONMENT = /could not find [^.]{0,40}executable|is not found at \/|\bno
|
|
|
22
22
|
// Netlify" (Netlify), "The API key you provided was rejected" (Pinecone), "Admin
|
|
23
23
|
// auth is missing", "Runtime credentials are missing" (securenow). Not a bare
|
|
24
24
|
// "token": plenty of errors mention one.
|
|
25
|
+
// Hosted servers ask the user to sign in in their own words: "Sign in to Ideal (or create
|
|
26
|
+
// your creator account) to continue", "Connect your Novamris account to read its saved chart".
|
|
27
|
+
const SIGN_IN = /\bsign in to\b|\blog ?in to (?:continue|use)\b|\bconnect your [\w .'-]{1,40}? account\b/i;
|
|
28
|
+
// A paid tool: "Payment required: $0.50 over MPP" (a hosted server), HTTP 402, no credits left.
|
|
29
|
+
const PAYMENT = /\bpayment required\b|\b(?:HTTP|status(?: code)?) 402\b|\binsufficient (?:credits?|balance|funds)\b/i;
|
|
25
30
|
const AUTH = /\b(?:auth|authentication|credentials?|api[ _-]?key|access token)\b (?:is |are )?missing\b|\bno (?:authentication|auth|credentials?|api[ _-]?keys?|access tokens?|auth tokens?) (?:was |were )?(?:found|provided|configured|set|given)\b|\b(401|403)\b|unauthori[sz]ed|unauth(enticated|error)|forbidden|bad credentials|authori[sz]ation expired|re-?authori[sz]e|not authenticated|not logged (?:in|into)\b(?! to the browser)|authentication (token|failed|required|error)|(invalid|expired|revoked) (api[ _-]?key|access token|token|credentials)|(token|api[ _-]?key|credentials) (is |are )?(not valid|invalid|expired)|(api[ _-]?key|access token|credentials)\b[^.]{0,30}\b(was|were|is|are) (rejected|refused|revoked)|valid (access )?token/i;
|
|
26
31
|
const NETWORK = /\b(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ECONNRESET|EHOSTUNREACH)\b|socket hang up|getaddrinfo|network error/i;
|
|
27
32
|
// "Either 'page_id' OR both 'title' and 'space_key' must be provided" (Atlassian),
|
|
@@ -164,7 +169,9 @@ export function classifyFailure(text, options = {}) {
|
|
|
164
169
|
return 'client';
|
|
165
170
|
if (ENVIRONMENT.test(text))
|
|
166
171
|
return 'environment';
|
|
167
|
-
if (
|
|
172
|
+
if (PAYMENT.test(text))
|
|
173
|
+
return 'payment';
|
|
174
|
+
if (AUTH.test(text) || SIGN_IN.test(text))
|
|
168
175
|
return 'auth';
|
|
169
176
|
if (NETWORK.test(text))
|
|
170
177
|
return 'network';
|
|
@@ -176,6 +183,7 @@ export function classifyFailure(text, options = {}) {
|
|
|
176
183
|
}
|
|
177
184
|
export const FAILURE_LABELS = {
|
|
178
185
|
auth: 'authentication',
|
|
186
|
+
payment: 'payment (a paid tool)',
|
|
179
187
|
environment: 'something missing on this machine',
|
|
180
188
|
network: 'the network',
|
|
181
189
|
'not-found': 'a 404 on a call that named nothing (usually the account or site behind the credentials)',
|
|
@@ -194,6 +202,8 @@ export function setupFailureAdvice(classes, transport) {
|
|
|
194
202
|
const steps = [];
|
|
195
203
|
if (set.has('auth') || set.has('not-found'))
|
|
196
204
|
steps.push(`If the errors are about credentials, rerun with real ones (${credentials}); a test account is enough.`);
|
|
205
|
+
if (set.has('payment'))
|
|
206
|
+
steps.push('If a tool asks for payment, it can\'t be checked without paying: leave it out of the scenario, or run with an account that has credit.');
|
|
197
207
|
if (set.has('environment'))
|
|
198
208
|
steps.push('If something is missing on this machine (a browser, a binary, a module), install it where the server runs, or run the server in its own container image.');
|
|
199
209
|
if (set.has('client'))
|
package/dist/help.js
CHANGED
|
@@ -19,6 +19,7 @@ const OPTIONS = {
|
|
|
19
19
|
env: ['--env <K=V>', ['environment variable for a stdio server, repeatable. The server only', 'gets a minimal environment (PATH, HOME, ...) plus these']],
|
|
20
20
|
protocol: ['--protocol <auto|legacy|modern>', ['which handshake to make (default: auto)', 'legacy: the 2025 handshake only; modern: 2026-07-28 only, an error if the server lacks it']],
|
|
21
21
|
as: ['--as <name>[:<credential>]', ['list the menu as this identity too, repeatable: a header ("reader:Authorization:', 'Bearer ...") or env var ("admin:ROLE=admin") on top of --header/--env. The first', 'is the main one (its menu is saved); the others are compared with it']],
|
|
22
|
+
lists: ['--lists <kinds>', ['which lists to read and check, comma-separated: tools (always),', 'prompts, resources (resources/list and resources/templates/list).', 'Saved in the menu file beside the tools']],
|
|
22
23
|
client: ['--client <name>', ['check the menu for one client, from its own docs: claude-code (tools deferred,', 'its description cut and search), claude-api-search (Claude API tool search)', 'or openai (Responses API tool_search): cost up front and per tool, names it refuses']],
|
|
23
24
|
'no-auth': ['--no-auth', ["don't use a stored OAuth login (toolmenu auth login) for this server"]],
|
|
24
25
|
timeout: ['--timeout <ms>', ['per-request timeout (default: 30000)']],
|
|
@@ -79,7 +80,7 @@ const HELP = {
|
|
|
79
80
|
'reports what in the menu confuses agents or breaks prompt caches.',
|
|
80
81
|
SERVER_NOTE,
|
|
81
82
|
],
|
|
82
|
-
own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client'],
|
|
83
|
+
own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists'],
|
|
83
84
|
shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
|
|
84
85
|
examples: [
|
|
85
86
|
'toolmenu snapshot -- npx -y @modelcontextprotocol/server-memory',
|
package/dist/lists.d.ts
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import { type Connection } from './connect.js';
|
|
2
|
+
export declare const LIST_KINDS: readonly ['prompts', 'resources', 'resourceTemplates'];
|
|
3
|
+
export type ListKind = (typeof LIST_KINDS)[number];
|
|
4
|
+
/** The --lists words: `resources` reads both resources/list and resources/templates/list. */
|
|
5
|
+
export declare const LIST_WORDS: readonly ['tools', 'prompts', 'resources'];
|
|
6
|
+
/** Each list's JSON-RPC method, result key, the key that names an item, and its words. */
|
|
7
|
+
export declare const LIST_INFO: Record<ListKind, {
|
|
8
|
+
method: string;
|
|
9
|
+
key: string;
|
|
10
|
+
id: string;
|
|
11
|
+
one: string;
|
|
12
|
+
capability: 'prompts' | 'resources';
|
|
13
|
+
}>;
|
|
14
|
+
/** Pages read at most: a resources list can be a whole file tree. */
|
|
15
|
+
export declare const MAX_PAGES = 50;
|
|
16
|
+
export interface ListRead {
|
|
17
|
+
kind: ListKind;
|
|
18
|
+
items: Record<string, unknown>[];
|
|
19
|
+
/** Raw result pages, as received (spec/schema checks them). */
|
|
20
|
+
pages: Record<string, unknown>[];
|
|
21
|
+
listMeta: {
|
|
22
|
+
ttlMs?: number;
|
|
23
|
+
cacheScope?: string;
|
|
24
|
+
};
|
|
25
|
+
/** Stopped at MAX_PAGES. */
|
|
26
|
+
truncated?: boolean;
|
|
27
|
+
/** Why it couldn't be read. */
|
|
28
|
+
error?: string;
|
|
29
|
+
/** The JSON-RPC error code it failed with, when there was one (-32601: method not found). */
|
|
30
|
+
code?: number;
|
|
31
|
+
}
|
|
32
|
+
/** Read one list, page by page, as the server sends it. */
|
|
33
|
+
export declare function readList(connection: Connection, kind: ListKind, timeoutMs?: number): Promise<ListRead>;
|
|
34
|
+
/** The list kinds the --lists words ask for that the server declares a capability for, and the ones it doesn't. */
|
|
35
|
+
export declare function kindsToRead(words: string[], capabilities: Record<string, unknown>): {
|
|
36
|
+
read: ListKind[];
|
|
37
|
+
undeclared: ListKind[];
|
|
38
|
+
};
|
|
39
|
+
/** Two reads of one list: what changed between them, by item id and in order. */
|
|
40
|
+
export declare function listChanges(kind: ListKind, before: Record<string, unknown>[], after: Record<string, unknown>[]): string[];
|