toolmenu 0.16.0 → 0.17.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 +9 -2
- package/dist/auth.js +2 -1
- package/dist/auto.js +33 -2
- package/dist/breakdown.js +3 -31
- package/dist/catalog.d.ts +1 -1
- package/dist/catalog.js +4 -3
- package/dist/cli.js +42 -6
- package/dist/config.d.ts +9 -0
- package/dist/config.js +11 -0
- package/dist/connect.d.ts +1 -0
- package/dist/connect.js +46 -16
- package/dist/diff.js +51 -13
- package/dist/explain.d.ts +9 -4
- package/dist/explain.js +90 -25
- package/dist/failures.js +5 -4
- package/dist/help.js +2 -1
- package/dist/mrtr.d.ts +27 -6
- package/dist/mrtr.js +116 -37
- package/dist/options.d.ts +4 -0
- package/dist/options.js +1 -0
- package/dist/probe.d.ts +8 -0
- package/dist/probe.js +9 -1
- package/dist/report.js +2 -1
- package/dist/rules/gated.js +5 -5
- package/dist/rules/handles.d.ts +12 -0
- package/dist/rules/handles.js +88 -0
- package/dist/rules/headers.js +4 -4
- package/dist/rules/identities.d.ts +23 -0
- package/dist/rules/identities.js +84 -0
- package/dist/rules/index.js +5 -0
- package/dist/rules/refs.js +10 -78
- package/dist/rules/rule.d.ts +2 -0
- package/dist/rules/search.js +3 -2
- package/dist/rules/spec.js +2 -1
- package/dist/schema-ref.d.ts +35 -0
- package/dist/schema-ref.js +178 -0
- package/dist/search.d.ts +8 -0
- package/dist/search.js +4 -1
- package/dist/session.d.ts +17 -0
- package/dist/session.js +156 -66
- package/dist/snapshot.d.ts +10 -1
- package/dist/snapshot.js +20 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -108,7 +108,7 @@ jobs:
|
|
|
108
108
|
- uses: actions/setup-node@v7
|
|
109
109
|
with: { node-version: 22 }
|
|
110
110
|
- run: npm ci && npm run build
|
|
111
|
-
- uses: niksa90/toolmenu@v0.16.
|
|
111
|
+
- uses: niksa90/toolmenu@v0.16.1
|
|
112
112
|
with:
|
|
113
113
|
command: node dist/server.js
|
|
114
114
|
baseline: menu.json # your committed snapshot
|
|
@@ -188,7 +188,8 @@ serves, and 23 issue and pull-request tools that only the dynamic mode has.
|
|
|
188
188
|
| `session/assumed-read-only` | info | Tools called on your word (`--assume-read-only`, `assume_read_only`) although the server doesn't mark them readOnlyHint |
|
|
189
189
|
| `session/unlock-coverage` | warn | An unlock whose enum lists its values, called with only some of them: the tools behind the rest were never seen, so a baseline from the session misses them. With `--union-out` or `--auto`, an unlock never called at all too, with why `--auto` skipped it |
|
|
190
190
|
| `session/nothing-called` | warn | `--auto` called no tools (all open-world, missing values, or not read-only): the run only listed the menu |
|
|
191
|
-
| `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). The run stops there; rerun with `--processes 1` |
|
|
191
|
+
| `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` |
|
|
192
|
+
| `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 |
|
|
192
193
|
| `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 |
|
|
193
194
|
| `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 |
|
|
194
195
|
|
|
@@ -387,11 +388,14 @@ server, or from the spec itself. If a rule can't point to one, it doesn't ship.
|
|
|
387
388
|
| `description/late-instruction` | info | With the default cut: instructions after character 280, which a client that cuts descriptions short would hide, as one summary. Set `descriptionLimit` and `description/buried` checks your real cut instead. (Before 0.13 this was part of `description/cut`; that id's setting still applies.) |
|
|
388
389
|
| `naming/vague-id` | warn | Parameters called just `id` that don't say *which* thing, as one summary with a suggested name |
|
|
389
390
|
| `ids/authored` | info | An ID the agent must supply that no tool appears to return, so the agent may invent it, one finding per kind of ID (heuristic: IDs from a URL or another tool's text output look the same) |
|
|
391
|
+
| `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) |
|
|
390
392
|
| `write/unannotated` | warn | Tools named like writes (`delete_`, `send_`…) with no annotations, as one summary grouped by the annotation each name suggests |
|
|
391
393
|
| `naming/shared-word` | info | Nouns that name different things across tools (`list_team_audits` vs `get_audit_trail`), as one summary |
|
|
392
394
|
| `write/no-dry-run` | info | Destructive tools with no dry-run parameter or preview tool, as one summary |
|
|
393
395
|
| `spec/discover` | info | The server only speaks the 2025 protocol, so 2026-07-28 rules are skipped |
|
|
394
396
|
| `spec/deprecated`, `spec/cache-hints` | info | 2026-07-28: deprecated features still advertised; `ttlMs: 0`, or `cacheScope: "public"` on a server that took credentials |
|
|
397
|
+
| `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 |
|
|
398
|
+
| `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 |
|
|
395
399
|
|
|
396
400
|
The naming and ID rules are heuristics, tuned on real servers (FINDINGS F7 and
|
|
397
401
|
F10) and a private 115-tool one. They're the extras; the change checks are the point.
|
|
@@ -469,6 +473,9 @@ toolmenu sees what the server sends. Plenty of agent failures happen elsewhere:
|
|
|
469
473
|
(2026-07-28 only; an error if the server lacks it)
|
|
470
474
|
--processes <n> server processes or connections to compare (default: 2);
|
|
471
475
|
1 opens no second one, session's scope check included
|
|
476
|
+
--as <name>:<cred> snapshot: list the menu as this identity too, repeatable:
|
|
477
|
+
"reader:Authorization: Bearer …" (HTTP) or "admin:ROLE=admin"
|
|
478
|
+
(stdio). The first is the menu saved; the others are compared
|
|
472
479
|
```
|
|
473
480
|
|
|
474
481
|
Exit codes: `0` clean · `1` findings at or above `--fail-on` · `2` couldn't connect
|
package/dist/auth.js
CHANGED
|
@@ -8,6 +8,7 @@ import { join } from 'node:path';
|
|
|
8
8
|
import { Client, StreamableHTTPClientTransport, UnauthorizedError } from '@modelcontextprotocol/client';
|
|
9
9
|
import { VERSION } from './version.js';
|
|
10
10
|
import { endSession } from './close.js';
|
|
11
|
+
import { quietExclusions } from './connect.js';
|
|
11
12
|
/**
|
|
12
13
|
* The redirect port. Fixed, not random: dynamic registration records the exact
|
|
13
14
|
* redirect URI, so a new port would invalidate the stored client on every login.
|
|
@@ -260,7 +261,7 @@ async function check(serverUrl) {
|
|
|
260
261
|
const transport = new StreamableHTTPClientTransport(new URL(serverUrl), { authProvider: new StoredOAuthProvider(serverUrl) });
|
|
261
262
|
await client.connect(transport);
|
|
262
263
|
try {
|
|
263
|
-
const { tools } = await client.listTools();
|
|
264
|
+
const { tools } = await quietExclusions(() => client.listTools());
|
|
264
265
|
return { name: client.getServerVersion()?.name, tools: tools.length };
|
|
265
266
|
}
|
|
266
267
|
finally {
|
package/dist/auto.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
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
5
|
import { MAX_UNLOCKS, unlockers } from './session.js';
|
|
5
6
|
import { COLLECTION_VERBS, LOOKUP_VERBS, verbOf, WRITE_VERBS } from './words.js';
|
|
6
7
|
/** Marked or named as a write: never called on the user's word. Says why, or undefined. */
|
|
@@ -45,6 +46,7 @@ export function autoScenario(menu, options = {}) {
|
|
|
45
46
|
const { perTool, ignored: unusedValues } = resolveValues(menu, options.values ?? {});
|
|
46
47
|
ignored.push(...unusedValues);
|
|
47
48
|
const candidates = [];
|
|
49
|
+
const modern = (menu.server.protocolVersion ?? '') >= '2026-07-28';
|
|
48
50
|
// Read-only unlocks with every value in an enum: each value, outside the call
|
|
49
51
|
// budget, so the tools behind every toolset are seen (GitHub: 19 toolsets).
|
|
50
52
|
// Called even when marked openWorldHint, without --open-world: an unlock changes
|
|
@@ -76,6 +78,13 @@ export function autoScenario(menu, options = {}) {
|
|
|
76
78
|
}
|
|
77
79
|
const filled = synthesizeArgs(tool.inputSchema, perTool.get(tool.name));
|
|
78
80
|
if (!filled.ok) {
|
|
81
|
+
// 2026-07-28: a handle the server mints (a session another tool starts) is
|
|
82
|
+
// called once with one that can't exist, to see the model gets a readable error.
|
|
83
|
+
const probe = modern ? handleProbe(tool, menu.tools, filled.missing, perTool.get(tool.name)) : undefined;
|
|
84
|
+
if (probe) {
|
|
85
|
+
candidates.push({ tool, args: probe.args, rank: 4, valued: false, probe: probe.probe });
|
|
86
|
+
continue;
|
|
87
|
+
}
|
|
79
88
|
skipped.push({ tool: tool.name, reason: 'needs values', missing: filled.missing });
|
|
80
89
|
continue;
|
|
81
90
|
}
|
|
@@ -87,7 +96,7 @@ export function autoScenario(menu, options = {}) {
|
|
|
87
96
|
skipped.push({ tool: c.tool.name, reason: 'over the call budget' });
|
|
88
97
|
const steps = options.callsOnly ? [] : [{ kind: 'list' }];
|
|
89
98
|
for (const c of chosen)
|
|
90
|
-
steps.push({ kind: 'call', tool: c.tool.name, args: c.args });
|
|
99
|
+
steps.push({ kind: 'call', tool: c.tool.name, args: c.args, ...(c.probe ? { probe: c.probe } : {}) });
|
|
91
100
|
for (const u of unlocks) {
|
|
92
101
|
const array = u.tool.inputSchema?.properties?.[u.param]?.type === 'array';
|
|
93
102
|
const values = u.values.slice(0, MAX_UNLOCKS);
|
|
@@ -100,7 +109,7 @@ export function autoScenario(menu, options = {}) {
|
|
|
100
109
|
steps.push({ kind: 'call', tool: u.tool.name, args: { [u.param]: array ? [values[0]] : values[0] }, ...tentative });
|
|
101
110
|
}
|
|
102
111
|
if (chosen.length && !options.callsOnly)
|
|
103
|
-
steps.push({ kind: 'call', tool: chosen[0].tool.name, args: chosen[0].args });
|
|
112
|
+
steps.push({ kind: 'call', tool: chosen[0].tool.name, args: chosen[0].args, ...(chosen[0].probe ? { probe: chosen[0].probe } : {}) });
|
|
104
113
|
const called = [...chosen.map((c) => c.tool.name), ...unlocks.map((u) => u.tool.name)];
|
|
105
114
|
return {
|
|
106
115
|
scenario: { allowWrites: false, steps, ...(assumed.size ? { assumeReadOnly: [...assumed] } : {}) },
|
|
@@ -234,6 +243,28 @@ function rank(tool, args) {
|
|
|
234
243
|
return 2;
|
|
235
244
|
return 3;
|
|
236
245
|
}
|
|
246
|
+
/**
|
|
247
|
+
* A required handle filled with one that can't exist: `toolmenu-unknown-session`,
|
|
248
|
+
* or the nil-version UUID for a uuid format. Only for a read-only tool (the caller
|
|
249
|
+
* checks), only when every other required value is filled, and only for a kind
|
|
250
|
+
* some tool in the menu creates, so it is a handle the server mints.
|
|
251
|
+
*/
|
|
252
|
+
function handleProbe(tool, tools, missing, given) {
|
|
253
|
+
const created = createdKinds(tools);
|
|
254
|
+
const handles = missing.flatMap((param) => {
|
|
255
|
+
const kind = [...created].find((k) => handleParams(tool, k).includes(param));
|
|
256
|
+
return kind ? [{ param, kind }] : [];
|
|
257
|
+
});
|
|
258
|
+
if (handles.length !== 1 || missing.length !== 1)
|
|
259
|
+
return undefined;
|
|
260
|
+
const [{ param, kind }] = handles;
|
|
261
|
+
const schema = tool.inputSchema?.properties?.[param];
|
|
262
|
+
if (!schema || (schema.type !== undefined && schema.type !== 'string') || typeof schema.pattern === 'string' || schema.enum)
|
|
263
|
+
return undefined;
|
|
264
|
+
const value = schema.format === 'uuid' ? '00000000-0000-4000-8000-000000000000' : `toolmenu-unknown-${kind}`;
|
|
265
|
+
const rest = synthesizeArgs(tool.inputSchema, { ...given, [param]: { value, raw: value } });
|
|
266
|
+
return rest.ok ? { args: rest.args, probe: { param, kind } } : undefined;
|
|
267
|
+
}
|
|
237
268
|
/** Parameters the skipped tools need, most needed first, with how many tools each fills. */
|
|
238
269
|
export function neededValues(skipped) {
|
|
239
270
|
const by = new Map();
|
package/dist/breakdown.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { canonical } from './compare.js';
|
|
2
|
+
import { usedEntries } from './schema-ref.js';
|
|
2
3
|
import { countTokens } from './menu.js';
|
|
3
4
|
const TOP = 5;
|
|
4
5
|
const BIG_ENUM = 20;
|
|
@@ -40,37 +41,8 @@ function unusedDefs(menu) {
|
|
|
40
41
|
const pools = ['$defs', 'definitions'].filter((k) => schema[k] && typeof schema[k] === 'object');
|
|
41
42
|
if (!pools.length)
|
|
42
43
|
continue;
|
|
43
|
-
|
|
44
|
-
const used =
|
|
45
|
-
const queue = [JSON.stringify(rest)];
|
|
46
|
-
const use = (pool, name) => {
|
|
47
|
-
const id = `${pool}/${name}`;
|
|
48
|
-
if (used.has(id))
|
|
49
|
-
return;
|
|
50
|
-
used.add(id);
|
|
51
|
-
queue.push(JSON.stringify(schema[pool][name] ?? {}));
|
|
52
|
-
};
|
|
53
|
-
// A definition can also be named by its $anchor ("#amount") or its $id.
|
|
54
|
-
const named = (ref) => {
|
|
55
|
-
const [base, fragment] = ref.split('#');
|
|
56
|
-
for (const pool of pools) {
|
|
57
|
-
for (const [name, def] of Object.entries(schema[pool])) {
|
|
58
|
-
const d = (def ?? {});
|
|
59
|
-
const id = typeof d.$id === 'string' ? d.$id.replace(/#$/, '') : undefined;
|
|
60
|
-
if ((!base && fragment && d.$anchor === fragment) || (base && id && (id === base || id.endsWith(`/${base}`))))
|
|
61
|
-
use(pool, name);
|
|
62
|
-
}
|
|
63
|
-
}
|
|
64
|
-
};
|
|
65
|
-
while (queue.length) {
|
|
66
|
-
const text = queue.pop();
|
|
67
|
-
for (const m of text.matchAll(/"\$ref"\s*:\s*"#\/(\$defs|definitions)\/([^"/]+)/g)) {
|
|
68
|
-
use(m[1], decodeURIComponent(m[2]).replace(/~1/g, '/').replace(/~0/g, '~'));
|
|
69
|
-
}
|
|
70
|
-
for (const m of text.matchAll(/"\$(?:dynamic)?[rR]ef"\s*:\s*"([^"]*)"/g))
|
|
71
|
-
if (!m[1].startsWith('#/'))
|
|
72
|
-
named(m[1]);
|
|
73
|
-
}
|
|
44
|
+
// The same resolver as spec/ref: pointers, $anchor/$dynamicAnchor, $id resources.
|
|
45
|
+
const used = usedEntries(schema);
|
|
74
46
|
let unused = 0;
|
|
75
47
|
for (const pool of pools) {
|
|
76
48
|
for (const [name, def] of Object.entries(schema[pool])) {
|
package/dist/catalog.d.ts
CHANGED
package/dist/catalog.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { quietExclusions } from './connect.js';
|
|
1
2
|
import { toolTokens } from './menu.js';
|
|
2
3
|
import { classifyFailure, RATE_LIMITED, tooMany } from './failures.js';
|
|
3
4
|
import { nouns, singular } from './words.js';
|
|
@@ -271,7 +272,7 @@ async function readRouters(conn, routers, skipped, options) {
|
|
|
271
272
|
async function callPatiently(conn, name, args, timeoutMs = 30_000) {
|
|
272
273
|
for (let attempt = 0;; attempt++) {
|
|
273
274
|
try {
|
|
274
|
-
const result = await conn.client.callTool({ name, arguments: args }, { timeout: timeoutMs });
|
|
275
|
+
const result = await quietExclusions(() => conn.client.callTool({ name, arguments: args }, { timeout: timeoutMs }));
|
|
275
276
|
const text = result.isError ? resultText(result) : '';
|
|
276
277
|
if (result.isError && RATE_LIMITED.test(text) && attempt < 3) {
|
|
277
278
|
await sleep(2000 * 2 ** attempt);
|
|
@@ -306,8 +307,8 @@ const FAILED_AS = {
|
|
|
306
307
|
fix: 'Check the server is set up for this account or site, then rerun.',
|
|
307
308
|
},
|
|
308
309
|
client: {
|
|
309
|
-
what: ["
|
|
310
|
-
fix: "Nothing to fix in the server: toolmenu doesn't
|
|
310
|
+
what: ["needed a client capability toolmenu doesn't declare", "needed a client capability toolmenu doesn't declare"],
|
|
311
|
+
fix: "Nothing to fix in the server: toolmenu doesn't declare the capability it asked for, so it can't list these routers' commands.",
|
|
311
312
|
},
|
|
312
313
|
'invalid-arguments': {
|
|
313
314
|
what: ["rejected the listing call's arguments", "rejected the listing call's arguments"],
|
package/dist/cli.js
CHANGED
|
@@ -9,7 +9,7 @@ import { loadMenu } from './menu.js';
|
|
|
9
9
|
import { history, historyCsv } from './history.js';
|
|
10
10
|
import { counts, formatDiff, formatHistory, formatPlan, formatSession, formatSnapshot } from './report.js';
|
|
11
11
|
import { loadScenario, session, starterScenario, unlockListers, valuesFromListing } from './session.js';
|
|
12
|
-
import { listTools } from './connect.js';
|
|
12
|
+
import { listTools, quietExclusions } from './connect.js';
|
|
13
13
|
import { patiently, tooMany } from './failures.js';
|
|
14
14
|
import { buildMenu } from './menu.js';
|
|
15
15
|
import { existsSync } from 'node:fs';
|
|
@@ -82,10 +82,12 @@ export async function main(argv) {
|
|
|
82
82
|
const elicitation = (values.elicitation ?? 'decline');
|
|
83
83
|
if (!ELICITATIONS.includes(elicitation))
|
|
84
84
|
throw new UsageError('--elicitation must be decline or cancel');
|
|
85
|
+
if (values.as !== undefined && sub !== 'snapshot')
|
|
86
|
+
throw new UsageError('--as goes with snapshot: it lists the menu once per identity.');
|
|
85
87
|
if (values.elicitation !== undefined && sub !== 'session')
|
|
86
88
|
throw new UsageError('--elicitation goes with session: only session calls tools.');
|
|
87
|
-
// Only session calls tools, so only its
|
|
88
|
-
const answering = (t) => (
|
|
89
|
+
// Only session calls tools, so only its targets declare elicitation and say how to answer.
|
|
90
|
+
const answering = (t) => ({ ...t, elicitation });
|
|
89
91
|
const processes = values.processes !== undefined ? Number(values.processes) : config.processes ?? 2;
|
|
90
92
|
if (!Number.isInteger(processes) || processes < 1)
|
|
91
93
|
throw new UsageError('--processes must be a whole number, 1 or more');
|
|
@@ -143,7 +145,7 @@ export async function main(argv) {
|
|
|
143
145
|
const path = values.scenario ?? 'scenario.yml';
|
|
144
146
|
if (existsSync(path))
|
|
145
147
|
throw new UsageError(`${path} already exists. Pick another path with --scenario.`);
|
|
146
|
-
const initTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
|
|
148
|
+
const initTarget = answering(parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol));
|
|
147
149
|
const conn = await connectPatiently(seeded(initTarget, MAIN_SEED), { timeoutMs });
|
|
148
150
|
try {
|
|
149
151
|
const list = await patiently(() => listTools(conn, { timeoutMs }), { error: tooMany });
|
|
@@ -154,7 +156,7 @@ export async function main(argv) {
|
|
|
154
156
|
const read = [];
|
|
155
157
|
for (const { unlock, lister } of unlockListers(menu.tools)) {
|
|
156
158
|
try {
|
|
157
|
-
const result = await conn.client.callTool({ name: lister, arguments: {} }, { timeout: timeoutMs });
|
|
159
|
+
const result = await quietExclusions(() => conn.client.callTool({ name: lister, arguments: {} }, { timeout: timeoutMs }));
|
|
158
160
|
const found = result.isError ? [] : valuesFromListing(result);
|
|
159
161
|
if (found.length) {
|
|
160
162
|
unlockValues[unlock] = found;
|
|
@@ -295,9 +297,10 @@ export async function main(argv) {
|
|
|
295
297
|
return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
|
|
296
298
|
}
|
|
297
299
|
const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
|
|
300
|
+
const identities = values.as?.length ? parseIdentities(values.as, target.kind) : configIdentities(config.identities, target.kind);
|
|
298
301
|
const routesPath = values.routes ?? config.routes;
|
|
299
302
|
const routes = routesPath ? await loadRoutes(routesPath) : undefined;
|
|
300
|
-
const { menu, findings } = await snapshot(target, { routes, timeoutMs, processes, catalog: values.catalog ? (config.catalog ?? true) : undefined, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
|
|
303
|
+
const { menu, findings } = await snapshot(target, { routes, timeoutMs, processes, identities, catalog: values.catalog ? (config.catalog ?? true) : undefined, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
|
|
301
304
|
const outPath = values['no-write'] ? undefined : values.out ?? 'menu.json';
|
|
302
305
|
if (outPath)
|
|
303
306
|
await writeFile(outPath, JSON.stringify(menu, null, 2) + '\n');
|
|
@@ -352,6 +355,39 @@ async function authCommand(args, values) {
|
|
|
352
355
|
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`);
|
|
353
356
|
return 0;
|
|
354
357
|
}
|
|
358
|
+
/**
|
|
359
|
+
* --as name:credential, repeatable, in order of first mention: `reader:Authorization:
|
|
360
|
+
* Bearer x` (HTTP header) or `admin:ROLE=admin` (stdio env var). A name alone is an
|
|
361
|
+
* identity with only the --header/--env given to every run.
|
|
362
|
+
*/
|
|
363
|
+
function parseIdentities(items, kind) {
|
|
364
|
+
const byName = new Map();
|
|
365
|
+
for (const item of items) {
|
|
366
|
+
const colon = item.indexOf(':');
|
|
367
|
+
const name = (colon < 0 ? item : item.slice(0, colon)).trim();
|
|
368
|
+
if (!/^[\w.-]+$/.test(name))
|
|
369
|
+
throw new UsageError(`--as "${item}" should start with a name (letters, digits, _ . -): --as reader:${kind === 'http' ? 'Authorization: Bearer …' : 'TOKEN=…'}`);
|
|
370
|
+
const identity = byName.get(name) ?? { name };
|
|
371
|
+
byName.set(name, identity);
|
|
372
|
+
if (colon < 0)
|
|
373
|
+
continue;
|
|
374
|
+
const credential = item.slice(colon + 1);
|
|
375
|
+
if (kind === 'http')
|
|
376
|
+
identity.headers = { ...identity.headers, ...parsePairs([credential], ':', `--as ${name}:`) };
|
|
377
|
+
else
|
|
378
|
+
identity.env = { ...identity.env, ...parsePairs([credential], '=', `--as ${name}:`) };
|
|
379
|
+
}
|
|
380
|
+
if (byName.size < 2)
|
|
381
|
+
throw new UsageError('--as needs two identities or more to compare: --as reader:… --as admin:…');
|
|
382
|
+
return [...byName.values()];
|
|
383
|
+
}
|
|
384
|
+
/** The config file's identities, for this kind of server: headers for HTTP, env for stdio. */
|
|
385
|
+
function configIdentities(ids, kind) {
|
|
386
|
+
if (!ids)
|
|
387
|
+
return undefined;
|
|
388
|
+
const list = Object.entries(ids).map(([name, id]) => ({ name, ...(kind === 'http' ? (id.headers ? { headers: id.headers } : {}) : id.env ? { env: id.env } : {}) }));
|
|
389
|
+
return list.length >= 2 ? list : undefined;
|
|
390
|
+
}
|
|
355
391
|
function parsePairs(items, separator, flag) {
|
|
356
392
|
const pairs = {};
|
|
357
393
|
for (const item of items) {
|
package/dist/config.d.ts
CHANGED
|
@@ -16,6 +16,15 @@ export interface Config {
|
|
|
16
16
|
descriptionLimit?: number | string;
|
|
17
17
|
/** Tools (names or globs) your client sends with the full description. */
|
|
18
18
|
fullDescriptions?: string[];
|
|
19
|
+
/**
|
|
20
|
+
* snapshot: list the menu once per identity, the first being the main one:
|
|
21
|
+
* { "reader": { "headers": { "Authorization": "Bearer …" } }, "admin": { "env": { "ROLE": "admin" } } }.
|
|
22
|
+
* --as replaces them.
|
|
23
|
+
*/
|
|
24
|
+
identities?: Record<string, {
|
|
25
|
+
headers?: Record<string, string>;
|
|
26
|
+
env?: Record<string, string>;
|
|
27
|
+
}>;
|
|
19
28
|
/** Server processes (stdio) or connections (HTTP) to compare, the main one included (default 2). */
|
|
20
29
|
processes?: number;
|
|
21
30
|
/**
|
package/dist/config.js
CHANGED
|
@@ -29,6 +29,17 @@ export async function loadConfig(path) {
|
|
|
29
29
|
if (config.processes !== undefined && !(Number.isInteger(config.processes) && config.processes >= 1)) {
|
|
30
30
|
throw new Error(`${file}: processes must be a whole number, 1 or more`);
|
|
31
31
|
}
|
|
32
|
+
if (config.identities !== undefined) {
|
|
33
|
+
const strings = (v) => v === undefined || (typeof v === 'object' && v !== null && !Array.isArray(v) && Object.values(v).every((x) => typeof x === 'string'));
|
|
34
|
+
const ids = config.identities;
|
|
35
|
+
if (typeof ids !== 'object' || ids === null || Array.isArray(ids))
|
|
36
|
+
throw new Error(`${file}: identities must be an object, like { "reader": { "headers": { "Authorization": "Bearer …" } } }`);
|
|
37
|
+
for (const [name, id] of Object.entries(ids)) {
|
|
38
|
+
if (typeof id !== 'object' || id === null || Array.isArray(id) || !strings(id.headers) || !strings(id.env)) {
|
|
39
|
+
throw new Error(`${file}: identities.${name} must be { "headers": { … } } or { "env": { … } }, with string values`);
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
}
|
|
32
43
|
const catalog = config.catalog;
|
|
33
44
|
if (catalog !== undefined) {
|
|
34
45
|
const names = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === 'string' && x.length > 0);
|
package/dist/connect.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { Client } from '@modelcontextprotocol/client';
|
|
2
2
|
import type { Transport } from '@modelcontextprotocol/client';
|
|
3
3
|
import type { Era } from './types.js';
|
|
4
|
+
export declare function quietExclusions<T>(work: () => Promise<T>): Promise<T>;
|
|
4
5
|
export type Protocol = 'auto' | 'legacy' | 'modern';
|
|
5
6
|
export declare const PROTOCOLS: readonly Protocol[];
|
|
6
7
|
export declare const MODERN_VERSION = "2026-07-28";
|
package/dist/connect.js
CHANGED
|
@@ -10,15 +10,41 @@ import { VERSION } from './version.js';
|
|
|
10
10
|
* to the 2025 one. legacy: the 2025 handshake only. modern: 2026-07-28 only, an error if
|
|
11
11
|
* the server can't speak it.
|
|
12
12
|
*/
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
13
|
+
/**
|
|
14
|
+
* Run `work` with the SDK's "[mcp-sdk] excluding tool" warnings held back. The SDK
|
|
15
|
+
* client drops a tool with an invalid x-mcp-header from its own tools/list (also
|
|
16
|
+
* inside callTool, when it refreshes its list) and console.warns about it; toolmenu
|
|
17
|
+
* reads the list off the wire and reports those tools as spec/x-mcp-header findings.
|
|
18
|
+
* Only while toolmenu lists or calls, so an app that imports toolmenu keeps its own
|
|
19
|
+
* warnings. Overlapping runs share one filter, put in by the first and taken out by
|
|
20
|
+
* the last.
|
|
21
|
+
*/
|
|
22
|
+
let quieting = 0;
|
|
23
|
+
let originalWarn;
|
|
24
|
+
let installedWarn;
|
|
25
|
+
export async function quietExclusions(work) {
|
|
26
|
+
if (quieting++ === 0) {
|
|
27
|
+
originalWarn = console.warn;
|
|
28
|
+
const warn = originalWarn.bind(console);
|
|
29
|
+
installedWarn = (...args) => {
|
|
30
|
+
if (typeof args[0] === 'string' && args[0].startsWith('[mcp-sdk] excluding tool '))
|
|
31
|
+
return;
|
|
32
|
+
warn(...args);
|
|
33
|
+
};
|
|
34
|
+
console.warn = installedWarn;
|
|
35
|
+
}
|
|
36
|
+
try {
|
|
37
|
+
return await work();
|
|
38
|
+
}
|
|
39
|
+
finally {
|
|
40
|
+
if (--quieting === 0 && originalWarn) {
|
|
41
|
+
// Only take out our own filter: a replacement put in meanwhile stays.
|
|
42
|
+
if (console.warn === installedWarn)
|
|
43
|
+
console.warn = originalWarn;
|
|
44
|
+
originalWarn = installedWarn = undefined;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
22
48
|
export const PROTOCOLS = ['auto', 'legacy', 'modern'];
|
|
23
49
|
export const MODERN_VERSION = '2026-07-28';
|
|
24
50
|
export const ELICITATIONS = ['decline', 'cancel'];
|
|
@@ -67,15 +93,19 @@ export class WireLog {
|
|
|
67
93
|
export async function connect(target, options = {}) {
|
|
68
94
|
const client = new Client({ name: 'toolmenu', version: VERSION }, {
|
|
69
95
|
versionNegotiation: { mode: target.protocol === 'legacy' ? 'legacy' : target.protocol === 'modern' ? { pin: MODERN_VERSION } : 'auto' },
|
|
70
|
-
//
|
|
71
|
-
//
|
|
72
|
-
//
|
|
73
|
-
//
|
|
74
|
-
|
|
96
|
+
// Only for session (target.elicitation set): a connection that calls tools
|
|
97
|
+
// declares elicitation, form and URL mode, so a tool that asks the user something
|
|
98
|
+
// runs its "the user said no" path instead of failing (2026-07-28 multi
|
|
99
|
+
// round-trip requests). snapshot and the rest declare nothing, as before 0.16:
|
|
100
|
+
// a server may list different tools to a client that can be asked things.
|
|
101
|
+
// Never roots or sampling: 2026-07-28 deprecates them (SEP-2577).
|
|
102
|
+
...(target.elicitation ? { capabilities: { elicitation: { form: {}, url: {} } } } : {}),
|
|
75
103
|
});
|
|
76
104
|
// A 2025 server asks with an elicitation/create request; 2026-07-28 ones embed it
|
|
77
105
|
// in an input_required result, which session answers itself (mrtr.ts). Same answer.
|
|
78
|
-
|
|
106
|
+
const elicitation = target.elicitation;
|
|
107
|
+
if (elicitation)
|
|
108
|
+
client.setRequestHandler('elicitation/create', async () => ({ action: elicitation }));
|
|
79
109
|
let transport;
|
|
80
110
|
let stderrText = '';
|
|
81
111
|
let oauth = false;
|
|
@@ -265,7 +295,7 @@ export async function listTools(connection, options = {}) {
|
|
|
265
295
|
let clientError;
|
|
266
296
|
let caught;
|
|
267
297
|
try {
|
|
268
|
-
await connection.client.listTools(undefined, { cacheMode: 'bypass', timeout: options.timeoutMs });
|
|
298
|
+
await quietExclusions(() => connection.client.listTools(undefined, { cacheMode: 'bypass', timeout: options.timeoutMs }));
|
|
269
299
|
}
|
|
270
300
|
catch (error) {
|
|
271
301
|
caught = error;
|
package/dist/diff.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { createHash } from 'node:crypto';
|
|
2
2
|
import { canonical, compareMenus } from './compare.js';
|
|
3
3
|
import { countTokens } from './menu.js';
|
|
4
|
+
import { headerFaults } from './rules/headers.js';
|
|
5
|
+
import { indexSchema } from './schema-ref.js';
|
|
4
6
|
import { isCalendar, parseSemver } from './semver.js';
|
|
5
7
|
import { SEVERITY_RANK } from './types.js';
|
|
6
8
|
/** Every diff rule, its default severity and what it means for semver. */
|
|
@@ -25,6 +27,10 @@ export const DIFF_RULES = {
|
|
|
25
27
|
// added, removed or renamed. Callers don't change; proxies and WAFs routing on the
|
|
26
28
|
// header do.
|
|
27
29
|
'diff/x-mcp-header': { severity: 'info', class: 'notice' },
|
|
30
|
+
// The new release's x-mcp-header makes Streamable HTTP clients drop the tool,
|
|
31
|
+
// which the old one didn't. A warning, not breaking: a menu file doesn't say whether
|
|
32
|
+
// the server is served over HTTP (stdio clients may ignore the annotation).
|
|
33
|
+
'diff/x-mcp-header-invalid': { severity: 'warn', class: 'notice' },
|
|
28
34
|
// Restructured ($ref, $defs) but accepts the same input: bytes and tokens changed.
|
|
29
35
|
'diff/schema-equivalent': { severity: 'info', class: 'notice' },
|
|
30
36
|
// Only the declared $schema dialect changed: one finding for the menu.
|
|
@@ -56,6 +62,11 @@ export const DIFF_RULES = {
|
|
|
56
62
|
const BREAKING_RELEASE = '\u0000breaking-release\u0000';
|
|
57
63
|
export function diffMenus(before, after, options = {}) {
|
|
58
64
|
const raw = [];
|
|
65
|
+
// x-mcp-header is 2026-07-28's: only a menu served on it has the annotation mean anything.
|
|
66
|
+
const isModern = (m) => m.server.era === 'modern' || (m.server.protocolVersion ?? '') >= '2026-07-28';
|
|
67
|
+
const modern = isModern(after);
|
|
68
|
+
// A tool the old release already lost to a bad annotation isn't news; on a 2025 server it lost nothing.
|
|
69
|
+
const headers = { headers: modern, oldHeaders: isModern(before) };
|
|
59
70
|
// Ignored tools leave the comparison entirely, so they can't pair into a
|
|
60
71
|
// rename or show up as a reorder.
|
|
61
72
|
const ignored = ignoreMatcher(options.ignore);
|
|
@@ -89,6 +100,10 @@ export function diffMenus(before, after, options = {}) {
|
|
|
89
100
|
});
|
|
90
101
|
}
|
|
91
102
|
for (const t of added.filter((t) => !renamedTo.has(t.name))) {
|
|
103
|
+
// A new tool HTTP clients drop on arrival.
|
|
104
|
+
const lost = headerLoss(t, modern, undefined);
|
|
105
|
+
if (lost)
|
|
106
|
+
raw.push(lost);
|
|
92
107
|
raw.push({
|
|
93
108
|
rule: 'diff/tool-added',
|
|
94
109
|
tool: t.name,
|
|
@@ -102,10 +117,10 @@ export function diffMenus(before, after, options = {}) {
|
|
|
102
117
|
for (const t of newTools) {
|
|
103
118
|
const old = oldByName.get(t.name);
|
|
104
119
|
if (old)
|
|
105
|
-
raw.push(...compareTool(old, t));
|
|
120
|
+
raw.push(...compareTool(old, t, headers));
|
|
106
121
|
}
|
|
107
122
|
for (const { from, to } of renames)
|
|
108
|
-
raw.push(...compareTool(from, to).filter((f) => f.rule !== 'diff/description' && f.rule !== 'diff/other'));
|
|
123
|
+
raw.push(...compareTool(from, to, headers).filter((f) => f.rule !== 'diff/description' && f.rule !== 'diff/other'));
|
|
109
124
|
collapseDialects(raw);
|
|
110
125
|
collapseMenuWide(raw);
|
|
111
126
|
// A session's union menu is in unlock order, which no client was served: no order to compare.
|
|
@@ -355,9 +370,35 @@ function collapseMenuWide(raw) {
|
|
|
355
370
|
* "review it" at four. Recursion is bounded by resolveRefs, not by this.
|
|
356
371
|
*/
|
|
357
372
|
const MAX_DEPTH = 64;
|
|
358
|
-
|
|
373
|
+
/** The tool's new x-mcp-header problem, if HTTP clients drop it now and didn't before (`old` undefined: nothing to compare, or a 2025 release). */
|
|
374
|
+
function headerLoss(t, headers, old) {
|
|
375
|
+
if (!headers)
|
|
376
|
+
return undefined;
|
|
377
|
+
const dropped = (tool) => headerFaults(tool).filter((f) => f.dropped);
|
|
378
|
+
const broken = dropped(t);
|
|
379
|
+
if (!broken.length || (old && dropped(old).length))
|
|
380
|
+
return undefined;
|
|
381
|
+
return {
|
|
382
|
+
rule: 'diff/x-mcp-header-invalid',
|
|
383
|
+
tool: t.name,
|
|
384
|
+
message: `${code(t.name)}: an x-mcp-header annotation in this release breaks the spec's rules, so Streamable HTTP clients must leave the tool out of their menu. If the server is served over HTTP, ${code(t.name)} is gone for agents on those clients.`,
|
|
385
|
+
detail: broken.map((f) => `${f.path}${typeof f.header === 'string' && f.header ? ` (x-mcp-header: "${f.header}")` : ''}: ${f.problem}`),
|
|
386
|
+
fix: 'Fix the annotation before release: snapshot\'s spec/x-mcp-header says which rule it breaks.',
|
|
387
|
+
};
|
|
388
|
+
}
|
|
389
|
+
/**
|
|
390
|
+
* Compare one tool across releases. `headers`: check x-mcp-header validity, for a
|
|
391
|
+
* 2026-07-28 menu's own tools (not operations behind a search tool, which no client
|
|
392
|
+
* lists, and not a 2025 server, where the annotation means nothing).
|
|
393
|
+
*/
|
|
394
|
+
function compareTool(old, t, { headers = false, oldHeaders = false } = {}) {
|
|
359
395
|
const out = [];
|
|
360
396
|
const name = t.name;
|
|
397
|
+
// An annotation that makes HTTP clients drop the tool, new in this release (or new
|
|
398
|
+
// because this release moved to 2026-07-28, where it starts to count).
|
|
399
|
+
const lost = headerLoss(t, headers, oldHeaders ? old : undefined);
|
|
400
|
+
if (lost)
|
|
401
|
+
out.push(lost);
|
|
361
402
|
if ((old.description ?? '') !== (t.description ?? '')) {
|
|
362
403
|
const detail = textDiff(old.description ?? '', t.description ?? '');
|
|
363
404
|
out.push({
|
|
@@ -1144,15 +1185,11 @@ function expandRefs(schema) {
|
|
|
1144
1185
|
if (!schema || typeof schema !== 'object')
|
|
1145
1186
|
return { schema, expanded: true };
|
|
1146
1187
|
let nodes = 0;
|
|
1147
|
-
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
1152
|
-
node = node[decodeURIComponent(raw).replace(/~1/g, '/').replace(/~0/g, '~')];
|
|
1153
|
-
}
|
|
1154
|
-
return node;
|
|
1155
|
-
};
|
|
1188
|
+
// The resolver spec/ref uses: pointers, anchors and $id resources alike, and only
|
|
1189
|
+
// refs where a schema goes (a "$ref" inside enum or default is data). Each ref
|
|
1190
|
+
// resolves against the resource it's written in.
|
|
1191
|
+
const index = indexSchema(schema);
|
|
1192
|
+
const bases = new Map(index.refs.map((r) => [r.node, r.base]));
|
|
1156
1193
|
const walk = (node, stack) => {
|
|
1157
1194
|
if (++nodes > MAX_EXPANDED_NODES)
|
|
1158
1195
|
throw new Error('too large');
|
|
@@ -1162,7 +1199,8 @@ function expandRefs(schema) {
|
|
|
1162
1199
|
return node;
|
|
1163
1200
|
const o = node;
|
|
1164
1201
|
if (typeof o.$ref === 'string') {
|
|
1165
|
-
const
|
|
1202
|
+
const base = bases.get(o) ?? (o === rest ? bases.get(schema) : undefined);
|
|
1203
|
+
const target = base !== undefined ? index.resolve(o.$ref, base)?.value : undefined;
|
|
1166
1204
|
if (target && typeof target === 'object' && !Array.isArray(target) && stack.filter((r) => r === o.$ref).length < MAX_UNROLL) {
|
|
1167
1205
|
const { $ref: _ref, ...siblings } = o;
|
|
1168
1206
|
return { ...walk(target, [...stack, o.$ref]), ...walk(siblings, stack) };
|
package/dist/explain.d.ts
CHANGED
|
@@ -77,15 +77,20 @@ export declare function clean(text: string, max: number): string;
|
|
|
77
77
|
/** "5.0 s", "0.3 s", "62 s". */
|
|
78
78
|
export declare function seconds(ms: number): string;
|
|
79
79
|
/** The command line, for a message: arguments with spaces quoted, cut at 120 characters. Never the --env values. */
|
|
80
|
-
export declare function commandLine(command: string, args: string[]
|
|
80
|
+
export declare function commandLine(command: string, args: string[], { cut }?: {
|
|
81
|
+
cut?: boolean;
|
|
82
|
+
}): string;
|
|
81
83
|
/** The stderr fact: the last lines, and a note of how many came before. */
|
|
82
84
|
export declare function stderrFact(trace: Trace): [string, string];
|
|
83
85
|
/**
|
|
84
86
|
* What the server's own output says about how it was started, as a next step: a
|
|
85
|
-
* CLI that printed its usage and wants a subcommand
|
|
86
|
-
* HTTP port instead of talking on stdio.
|
|
87
|
+
* CLI that printed its usage and wants a subcommand (only when it `exited`), or a
|
|
88
|
+
* server that opened an HTTP port instead of talking on stdio. `command` is the whole
|
|
89
|
+
* command line, uncut, so the suggestion can be run as written.
|
|
87
90
|
*/
|
|
88
|
-
export declare function startupHint(trace: Trace, command: string
|
|
91
|
+
export declare function startupHint(trace: Trace, command: string, { exited }?: {
|
|
92
|
+
exited?: boolean;
|
|
93
|
+
}): string | undefined;
|
|
89
94
|
/** A request header that carries credentials: Authorization, a cookie, or a name with key, token, secret or auth in it (x-mcp-api-key). */
|
|
90
95
|
export declare function isCredentialHeader(name: string): boolean;
|
|
91
96
|
/**
|