toolmenu 0.20.1 → 0.23.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 +119 -41
- package/dist/apps.d.ts +56 -0
- package/dist/apps.js +99 -0
- package/dist/auth.d.ts +14 -0
- package/dist/auth.js +75 -2
- package/dist/auto.d.ts +6 -0
- package/dist/auto.js +70 -7
- package/dist/card.d.ts +18 -0
- package/dist/card.js +39 -0
- package/dist/cli.js +108 -24
- package/dist/colour.d.ts +8 -0
- package/dist/colour.js +70 -0
- package/dist/config.d.ts +2 -0
- package/dist/config.js +2 -0
- package/dist/connect.d.ts +14 -0
- package/dist/connect.js +45 -7
- package/dist/diff.js +112 -13
- package/dist/explain.d.ts +1 -0
- package/dist/explain.js +11 -0
- package/dist/failures.d.ts +24 -0
- package/dist/failures.js +58 -1
- package/dist/help.d.ts +1 -1
- package/dist/help.js +36 -4
- package/dist/mrtr.d.ts +9 -1
- package/dist/mrtr.js +17 -0
- package/dist/options.d.ts +15 -0
- package/dist/options.js +5 -0
- package/dist/probe.d.ts +11 -1
- package/dist/probe.js +18 -3
- package/dist/report.d.ts +3 -0
- package/dist/report.js +15 -8
- package/dist/rule-docs.d.ts +26 -0
- package/dist/rule-docs.js +88 -0
- package/dist/rule-docs.json +597 -0
- package/dist/rules/apps.d.ts +11 -0
- package/dist/rules/apps.js +156 -0
- package/dist/rules/auth.d.ts +18 -0
- package/dist/rules/auth.js +29 -0
- package/dist/rules/capabilities.d.ts +21 -0
- package/dist/rules/capabilities.js +103 -0
- package/dist/rules/card.d.ts +7 -0
- package/dist/rules/card.js +65 -0
- package/dist/rules/clients.js +1 -0
- package/dist/rules/description.js +3 -0
- package/dist/rules/handles.d.ts +13 -0
- package/dist/rules/handles.js +78 -0
- package/dist/rules/ids.js +35 -1
- package/dist/rules/index.js +20 -2
- package/dist/rules/naming.js +3 -0
- package/dist/rules/network.d.ts +21 -0
- package/dist/rules/network.js +63 -0
- package/dist/rules/rule.d.ts +20 -0
- package/dist/rules/search.js +1 -0
- package/dist/rules/spec.d.ts +9 -1
- package/dist/rules/spec.js +117 -3
- package/dist/rules/write.d.ts +0 -6
- package/dist/rules/write.js +11 -5
- package/dist/scan.d.ts +47 -0
- package/dist/scan.js +334 -0
- package/dist/session.d.ts +2 -0
- package/dist/session.js +149 -9
- package/dist/snapshot.d.ts +15 -0
- package/dist/snapshot.js +130 -5
- package/dist/types.d.ts +5 -0
- package/dist/words.d.ts +10 -0
- package/dist/words.js +44 -2
- package/package.json +2 -2
- package/schemas/server-card.json +260 -0
package/dist/diff.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { agentTools, LEGACY_URI_KEY, resourceUriOf, uiMeta } from './apps.js';
|
|
1
2
|
import { createHash } from 'node:crypto';
|
|
2
3
|
import { canonical, compareMenus } from './compare.js';
|
|
3
4
|
import { countTokens } from './menu.js';
|
|
@@ -5,6 +6,7 @@ import { headerFaults } from './rules/headers.js';
|
|
|
5
6
|
import { indexSchema } from './schema-ref.js';
|
|
6
7
|
import { isCalendar, parseSemver } from './semver.js';
|
|
7
8
|
import { SEVERITY_RANK } from './types.js';
|
|
9
|
+
import { editDistance } from './words.js';
|
|
8
10
|
/** Every diff rule, its default severity and what it means for semver. */
|
|
9
11
|
export const DIFF_RULES = {
|
|
10
12
|
'diff/tool-removed': { severity: 'error', class: 'breaking' },
|
|
@@ -39,6 +41,18 @@ export const DIFF_RULES = {
|
|
|
39
41
|
'diff/properties-opened': { severity: 'info', class: 'minor' },
|
|
40
42
|
'diff/properties-closed': { severity: 'error', class: 'breaking' },
|
|
41
43
|
'diff/annotations': { severity: 'info', class: 'notice' },
|
|
44
|
+
// MCP Apps (ext-apps): _meta.ui.visibility without "model" keeps a tool out of the
|
|
45
|
+
// agent's list on an Apps host, so losing "model" removes the tool for the agent.
|
|
46
|
+
'diff/apps-visibility': { severity: 'error', class: 'breaking' },
|
|
47
|
+
'diff/apps-visible': { severity: 'info', class: 'minor' },
|
|
48
|
+
// The UI a tool names (_meta.ui.resourceUri) added, removed or moved: what an Apps
|
|
49
|
+
// host renders changes; calls don't.
|
|
50
|
+
'diff/apps-ui': { severity: 'info', class: 'notice' },
|
|
51
|
+
// capabilities.extensions: an extension no longer declared is one clients stop using
|
|
52
|
+
// (no UI, no tasks); a warning, since core calls go on working.
|
|
53
|
+
'diff/extension-removed': { severity: 'warn', class: 'breaking' },
|
|
54
|
+
'diff/extension-added': { severity: 'info', class: 'minor' },
|
|
55
|
+
'diff/extension-settings': { severity: 'info', class: 'notice' },
|
|
42
56
|
'diff/other': { severity: 'info', class: 'notice' },
|
|
43
57
|
'diff/order': { severity: 'info', class: 'notice' },
|
|
44
58
|
// A tool lost a parameter and gained a required one with a close name: likely a
|
|
@@ -147,8 +161,10 @@ export function diffMenus(before, after, options = {}) {
|
|
|
147
161
|
}
|
|
148
162
|
raw.push(...compareCatalogs(before.catalog, after.catalog, ignored));
|
|
149
163
|
raw.push(...compareLists(before, after));
|
|
164
|
+
raw.push(...compareExtensions(before, after));
|
|
150
165
|
// Ignored tools leave the token counts and the budget too.
|
|
151
|
-
|
|
166
|
+
// What the agent pays: app-only tools (MCP Apps) aren't in its list.
|
|
167
|
+
const tokens = tokenChange(agentTools(oldTools), agentTools(newTools));
|
|
152
168
|
if (options.tokenBudget !== undefined && tokens.after > options.tokenBudget) {
|
|
153
169
|
const grew = tokens.tools.filter((t) => t.delta > 0).slice(0, 3);
|
|
154
170
|
raw.push({
|
|
@@ -780,16 +796,6 @@ function closeNames(a, b) {
|
|
|
780
796
|
return false;
|
|
781
797
|
return editDistance(x, y) <= (long.length >= 10 ? 2 : 1);
|
|
782
798
|
}
|
|
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
799
|
/** The same type, or one side an array of the other's type. */
|
|
794
800
|
function sameKind(a, b) {
|
|
795
801
|
const [x, y] = [typeOf(a), typeOf(b)];
|
|
@@ -1419,10 +1425,13 @@ function compareRest(old, t) {
|
|
|
1419
1425
|
across: same(`annotations\u0000${what}`, (count, list) => `Annotations changed the same way (${what}) in ${count}: ${list}.`),
|
|
1420
1426
|
});
|
|
1421
1427
|
}
|
|
1422
|
-
|
|
1428
|
+
out.push(...compareApps(old, t));
|
|
1429
|
+
// _meta.ui's URI and visibility are compareApps'; the rest of _meta is compared as any other field.
|
|
1430
|
+
const field = (tool, k) => (k === '_meta' ? withoutUi(tool._meta) : tool[k]);
|
|
1431
|
+
const others = [...new Set([...Object.keys(old), ...Object.keys(t)])].filter((k) => !TOOL_FIELDS.has(k) && canonical(field(old, k)) !== canonical(field(t, k))).sort();
|
|
1423
1432
|
if (others.length) {
|
|
1424
1433
|
const what = others.map((k) => {
|
|
1425
|
-
const pair = `${show(old
|
|
1434
|
+
const pair = `${show(field(old, k))} → ${show(field(t, k))}`;
|
|
1426
1435
|
return pair.length <= 60 ? `${k} ${pair}` : k;
|
|
1427
1436
|
}).join(', ');
|
|
1428
1437
|
out.push({
|
|
@@ -1434,6 +1443,96 @@ function compareRest(old, t) {
|
|
|
1434
1443
|
}
|
|
1435
1444
|
return out;
|
|
1436
1445
|
}
|
|
1446
|
+
/** _meta without MCP Apps' resourceUri, visibility and the deprecated ui/resourceUri; undefined when nothing else is left. */
|
|
1447
|
+
function withoutUi(meta) {
|
|
1448
|
+
if (typeof meta !== 'object' || meta === null || Array.isArray(meta))
|
|
1449
|
+
return meta;
|
|
1450
|
+
const { ui, [LEGACY_URI_KEY]: _legacy, ...rest } = meta;
|
|
1451
|
+
// Only what compareApps says: the URI and visibility. The rest of _meta.ui (csp,
|
|
1452
|
+
// permissions, domain, prefersBorder) is still compared here, as any _meta field.
|
|
1453
|
+
if (typeof ui === 'object' && ui !== null && !Array.isArray(ui)) {
|
|
1454
|
+
const { resourceUri: _uri, visibility: _visibility, ...uiRest } = ui;
|
|
1455
|
+
if (Object.keys(uiRest).length)
|
|
1456
|
+
rest.ui = uiRest;
|
|
1457
|
+
}
|
|
1458
|
+
else if (ui !== undefined) {
|
|
1459
|
+
rest.ui = ui;
|
|
1460
|
+
}
|
|
1461
|
+
return Object.keys(rest).length ? rest : undefined;
|
|
1462
|
+
}
|
|
1463
|
+
/** Who sees the tool on an Apps host, as visibility says (default: both). */
|
|
1464
|
+
function seenBy(tool) {
|
|
1465
|
+
const v = uiMeta(tool)?.visibility;
|
|
1466
|
+
return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : ['model', 'app'];
|
|
1467
|
+
}
|
|
1468
|
+
/** MCP Apps: visibility and the UI a tool names. */
|
|
1469
|
+
function compareApps(old, t) {
|
|
1470
|
+
const out = [];
|
|
1471
|
+
const name = t.name;
|
|
1472
|
+
const a = seenBy(old);
|
|
1473
|
+
const b = seenBy(t);
|
|
1474
|
+
const pair = `${show(a)} → ${show(b)}`;
|
|
1475
|
+
if (a.includes('model') && !b.includes('model')) {
|
|
1476
|
+
out.push({
|
|
1477
|
+
rule: 'diff/apps-visibility',
|
|
1478
|
+
tool: name,
|
|
1479
|
+
message: `${code(name)} is no longer shown to the agent (MCP Apps visibility ${pair}). An Apps host leaves it out of the agent's tool list, so agents, saved prompts and evals that call it now fail there.`,
|
|
1480
|
+
fix: `Keep "model" in ${code(name)}'s visibility for one release, or ${BREAKING_RELEASE}.`,
|
|
1481
|
+
across: { key: `apps-visibility\u0000${pair}`, say: (count, list) => `${count[0].toUpperCase()}${count.slice(1)} are no longer shown to the agent (MCP Apps visibility ${pair}): ${list}. An Apps host leaves them out of the agent's tool list, so calls to them from agents, saved prompts and evals now fail there.` },
|
|
1482
|
+
});
|
|
1483
|
+
}
|
|
1484
|
+
else if (!a.includes('model') && b.includes('model')) {
|
|
1485
|
+
out.push({
|
|
1486
|
+
rule: 'diff/apps-visible',
|
|
1487
|
+
tool: name,
|
|
1488
|
+
message: `${code(name)} is now shown to the agent (MCP Apps visibility ${pair}, ~${fmt(t.tokens)} tokens, estimate).`,
|
|
1489
|
+
});
|
|
1490
|
+
}
|
|
1491
|
+
else if (canonical(a) !== canonical(b)) {
|
|
1492
|
+
out.push({ rule: 'diff/apps-ui', tool: name, message: `${code(name)}: MCP Apps visibility ${pair}. The agent sees it as before; ${b.includes('app') ? 'the app can now call it' : 'the app can no longer call it'}.` });
|
|
1493
|
+
}
|
|
1494
|
+
const ua = resourceUriOf(old);
|
|
1495
|
+
const ub = resourceUriOf(t);
|
|
1496
|
+
if (ua !== ub) {
|
|
1497
|
+
const what = ua === undefined ? `now names a UI (${ub})` : ub === undefined ? `no longer names a UI (was ${ua})` : `names another UI (${ua} → ${ub})`;
|
|
1498
|
+
out.push({
|
|
1499
|
+
rule: 'diff/apps-ui',
|
|
1500
|
+
tool: name,
|
|
1501
|
+
message: `${code(name)} ${what}. What an MCP Apps host renders for it changes; calls don't.`,
|
|
1502
|
+
across: { key: `apps-ui\u0000${ua === undefined ? 'added' : ub === undefined ? 'removed' : 'moved'}`, say: (count, list) => `${count[0].toUpperCase()}${count.slice(1)} ${ua === undefined ? 'now name a UI' : ub === undefined ? 'no longer name a UI' : 'name another UI'}: ${list}. What an MCP Apps host renders for them changes; calls don't.` },
|
|
1503
|
+
});
|
|
1504
|
+
}
|
|
1505
|
+
return out;
|
|
1506
|
+
}
|
|
1507
|
+
/** capabilities.extensions, compared. Menu files from before 0.23 didn't record them: not compared. */
|
|
1508
|
+
function compareExtensions(before, after) {
|
|
1509
|
+
const a = before.server.extensions;
|
|
1510
|
+
const b = after.server.extensions;
|
|
1511
|
+
if (!a || !b)
|
|
1512
|
+
return [];
|
|
1513
|
+
const out = [];
|
|
1514
|
+
for (const id of Object.keys(a)) {
|
|
1515
|
+
if (!(id in b)) {
|
|
1516
|
+
out.push({
|
|
1517
|
+
rule: 'diff/extension-removed',
|
|
1518
|
+
message: `The server no longer declares the ${code(id)} extension. Clients stop using what it adds${EXTENSION_USE[id] ? ` (${EXTENSION_USE[id]})` : ''}; core requests go on working.`,
|
|
1519
|
+
fix: `If it was dropped by mistake, declare ${code(id)} again; if on purpose, say so in the release notes, or ${BREAKING_RELEASE}.`,
|
|
1520
|
+
});
|
|
1521
|
+
}
|
|
1522
|
+
else if (canonical(a[id]) !== canonical(b[id])) {
|
|
1523
|
+
out.push({ rule: 'diff/extension-settings', message: `The ${code(id)} extension's settings changed (${show(a[id])} → ${show(b[id])}).` });
|
|
1524
|
+
}
|
|
1525
|
+
}
|
|
1526
|
+
for (const id of Object.keys(b))
|
|
1527
|
+
if (!(id in a))
|
|
1528
|
+
out.push({ rule: 'diff/extension-added', message: `The server now declares the ${code(id)} extension.` });
|
|
1529
|
+
return out;
|
|
1530
|
+
}
|
|
1531
|
+
/** What clients lose with an official extension, for the message. */
|
|
1532
|
+
const EXTENSION_USE = {
|
|
1533
|
+
'io.modelcontextprotocol/ui': 'MCP Apps: the UI of tools that name one',
|
|
1534
|
+
'io.modelcontextprotocol/tasks': 'Tasks: long-running calls answered with a task to poll',
|
|
1535
|
+
};
|
|
1437
1536
|
function readOnly(a) {
|
|
1438
1537
|
return a.readOnlyHint === true;
|
|
1439
1538
|
}
|
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;
|
package/dist/explain.js
CHANGED
|
@@ -28,6 +28,7 @@ export class Trace {
|
|
|
28
28
|
stderrTail = [];
|
|
29
29
|
stderrLines = 0;
|
|
30
30
|
stderrPartial = '';
|
|
31
|
+
ownWarning = false;
|
|
31
32
|
send(method) {
|
|
32
33
|
this.sent.push({ method, at: Date.now() });
|
|
33
34
|
}
|
|
@@ -64,6 +65,16 @@ export class Trace {
|
|
|
64
65
|
const text = clean(line, 240);
|
|
65
66
|
if (!text)
|
|
66
67
|
return;
|
|
68
|
+
// Node 22 warns about NODE_USE_ENV_PROXY, which toolmenu sets for stdio servers
|
|
69
|
+
// behind a proxy (connect.ts): toolmenu's doing, not the server's words.
|
|
70
|
+
if (/^\(node:\d+\) \[UNDICI-EHPA\] Warning: EnvHttpProxyAgent is experimental/.test(text)) {
|
|
71
|
+
this.ownWarning = true;
|
|
72
|
+
return;
|
|
73
|
+
}
|
|
74
|
+
const hint = this.ownWarning && text.startsWith('(Use `node --trace-warnings');
|
|
75
|
+
this.ownWarning = false;
|
|
76
|
+
if (hint)
|
|
77
|
+
return;
|
|
67
78
|
this.stderrLines++;
|
|
68
79
|
this.stderrTail.push(text);
|
|
69
80
|
if (this.stderrTail.length > STDERR_LINES)
|
package/dist/failures.d.ts
CHANGED
|
@@ -73,3 +73,27 @@ export declare function setupFailureAdvice(classes: Iterable<FailureClass>, tran
|
|
|
73
73
|
fix: string;
|
|
74
74
|
confidence: 'unsure';
|
|
75
75
|
};
|
|
76
|
+
/** An HTTP error passed on as a tool's answer: what it said. */
|
|
77
|
+
export interface StructuredError {
|
|
78
|
+
status?: number;
|
|
79
|
+
code?: string;
|
|
80
|
+
message?: string;
|
|
81
|
+
/** 401 or 403, or a code that says the credentials were refused. */
|
|
82
|
+
auth: boolean;
|
|
83
|
+
/** "HTTP 401: …", for a message. */
|
|
84
|
+
said: string;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* A result not marked isError whose content is an HTTP error in structured form: the
|
|
88
|
+
* API the tool calls answered 4xx or 5xx and the server passed the body on as an
|
|
89
|
+
* answer. Notion's server returns `{"status":401,"object":"error","code":"unauthorized"}`
|
|
90
|
+
* as a plain result. Only a JSON object whose own status or code says so counts, not
|
|
91
|
+
* "401" anywhere in the data, and a status needs a sign that the object is an error
|
|
92
|
+
* (`object: "error"`, an `error` field, a `message`, or sitting under `error`): a
|
|
93
|
+
* status alone may be what the tool was asked about. (A tool that fetches a URL is
|
|
94
|
+
* skipped by the caller: its answer is the page's.)
|
|
95
|
+
*/
|
|
96
|
+
export declare function structuredError(result: {
|
|
97
|
+
content?: unknown;
|
|
98
|
+
structuredContent?: unknown;
|
|
99
|
+
}): StructuredError | undefined;
|
package/dist/failures.js
CHANGED
|
@@ -207,8 +207,65 @@ export function setupFailureAdvice(classes, transport) {
|
|
|
207
207
|
if (set.has('environment'))
|
|
208
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.');
|
|
209
209
|
if (set.has('client'))
|
|
210
|
-
steps.push("If a tool needs a client capability toolmenu doesn't declare (roots and sampling, which 2026-07-28 deprecates, or one the error names), those calls only checked that the menu stays put, and the server isn't at fault.");
|
|
210
|
+
steps.push("If a tool needs a client capability toolmenu doesn't declare (roots and sampling, which 2026-07-28 deprecates, the Tasks extension, or one the error names), those calls only checked that the menu stays put, and the server isn't at fault.");
|
|
211
211
|
if (set.has('network'))
|
|
212
212
|
steps.push('If the server calls an upstream API, check this machine can reach it (DNS, proxy, firewall).');
|
|
213
213
|
return { fix: steps.join(' ') || 'Check the quoted errors: they came from before the tool ran.', confidence: 'unsure' };
|
|
214
214
|
}
|
|
215
|
+
const DENIED_CODES = /^(?:unauthori[sz]ed|unauthenticated|forbidden|invalid_auth|invalid_token|not_authed|authentication_(?:required|failed)|permission_denied)$/i;
|
|
216
|
+
/**
|
|
217
|
+
* A result not marked isError whose content is an HTTP error in structured form: the
|
|
218
|
+
* API the tool calls answered 4xx or 5xx and the server passed the body on as an
|
|
219
|
+
* answer. Notion's server returns `{"status":401,"object":"error","code":"unauthorized"}`
|
|
220
|
+
* as a plain result. Only a JSON object whose own status or code says so counts, not
|
|
221
|
+
* "401" anywhere in the data, and a status needs a sign that the object is an error
|
|
222
|
+
* (`object: "error"`, an `error` field, a `message`, or sitting under `error`): a
|
|
223
|
+
* status alone may be what the tool was asked about. (A tool that fetches a URL is
|
|
224
|
+
* skipped by the caller: its answer is the page's.)
|
|
225
|
+
*/
|
|
226
|
+
export function structuredError(result) {
|
|
227
|
+
const objects = [result.structuredContent];
|
|
228
|
+
for (const c of Array.isArray(result.content) ? result.content : []) {
|
|
229
|
+
const text = c && typeof c === 'object' && 'text' in c && typeof c.text === 'string' ? c.text.trim() : '';
|
|
230
|
+
if (!text.startsWith('{'))
|
|
231
|
+
continue;
|
|
232
|
+
try {
|
|
233
|
+
objects.push(JSON.parse(text));
|
|
234
|
+
}
|
|
235
|
+
catch {
|
|
236
|
+
// not JSON
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
const errorStatus = (x) => {
|
|
240
|
+
const n = typeof x === 'number' ? x : typeof x === 'string' && /^\d{3}$/.test(x) ? Number(x) : NaN;
|
|
241
|
+
return n >= 400 && n <= 599 ? n : undefined;
|
|
242
|
+
};
|
|
243
|
+
let first;
|
|
244
|
+
for (const o of objects) {
|
|
245
|
+
if (!o || typeof o !== 'object' || Array.isArray(o))
|
|
246
|
+
continue;
|
|
247
|
+
for (const v of [o, o.error]) {
|
|
248
|
+
if (!v || typeof v !== 'object' || Array.isArray(v))
|
|
249
|
+
continue;
|
|
250
|
+
const r = v;
|
|
251
|
+
const status = [r.status, r.statusCode, r.status_code, r.code].map(errorStatus).find((x) => x !== undefined);
|
|
252
|
+
const code = [r.code, r.error, r.type].find((x) => typeof x === 'string' && DENIED_CODES.test(x));
|
|
253
|
+
const isError = v !== o || r.object === 'error' || ![undefined, null, false, '', 0].includes(r.error) || typeof r.message === 'string';
|
|
254
|
+
if (code === undefined && (status === undefined || !isError))
|
|
255
|
+
continue;
|
|
256
|
+
const message = typeof r.message === 'string' ? r.message : undefined;
|
|
257
|
+
const found = {
|
|
258
|
+
...(status !== undefined ? { status } : {}),
|
|
259
|
+
...(code !== undefined ? { code } : {}),
|
|
260
|
+
...(message !== undefined ? { message } : {}),
|
|
261
|
+
auth: code !== undefined || status === 401 || status === 403,
|
|
262
|
+
said: `${status !== undefined ? `HTTP ${status}` : code}${message ? `: ${message}` : ''}`,
|
|
263
|
+
};
|
|
264
|
+
// An auth error anywhere wins: a 502 around a nested 401 is still the credentials.
|
|
265
|
+
if (found.auth)
|
|
266
|
+
return found;
|
|
267
|
+
first ??= found;
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
return first;
|
|
271
|
+
}
|
package/dist/help.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export declare const COMMANDS: readonly ['init', 'snapshot', 'diff', 'session', 'history', 'auth'];
|
|
1
|
+
export declare const COMMANDS: readonly ['init', 'snapshot', 'diff', 'session', 'history', 'auth', 'scan', 'explain'];
|
|
2
2
|
export type Command = (typeof COMMANDS)[number];
|
|
3
3
|
/** `toolmenu --help`: what toolmenu is and which command to reach for. */
|
|
4
4
|
export declare function overview(): string;
|
package/dist/help.js
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
* codes. Option names and behaviour live in cli.ts; this file only describes them.
|
|
5
5
|
*/
|
|
6
6
|
import { VERSION } from './version.js';
|
|
7
|
-
export const COMMANDS = ['init', 'snapshot', 'diff', 'session', 'history', 'auth'];
|
|
7
|
+
export const COMMANDS = ['init', 'snapshot', 'diff', 'session', 'history', 'auth', 'scan', 'explain'];
|
|
8
8
|
/** Every option, once: its spelling and what it does (continuation lines are indented by the renderer). */
|
|
9
9
|
const OPTIONS = {
|
|
10
10
|
out: ['--out <path>', ['where to write the menu (default: menu.json)']],
|
|
@@ -30,6 +30,7 @@ const OPTIONS = {
|
|
|
30
30
|
plan: ['--plan', ['print the steps without connecting or running anything']],
|
|
31
31
|
init: ['--init', ["write a starter scenario from the server's menu (to --scenario,", 'default scenario.yml; never overwrites)']],
|
|
32
32
|
auto: ['--auto', ['build the steps from the menu: every read-only tool whose required', 'arguments the schema can fill (const, default, examples, enum, type),', 'then the first call again']],
|
|
33
|
+
'create-handles': ['--create-handles', ['with --auto on 2026-07-28, call the tool that creates a session, basket or cart', '(a write, so only with this flag; never one marked destructiveHint) and give', 'the tools that take it back the handle it returned']],
|
|
33
34
|
'open-world': ['--open-world', ['with --auto, also call read-only tools marked openWorldHint: true', '(web search, fetch, scraping): they may cost API credits']],
|
|
34
35
|
'max-calls': ['--max-calls <n>', ['with --auto, at most n calls in all, the tools unlocks bring', 'included (default: 20, plus --max-calls-per-unlock for each unlock value)']],
|
|
35
36
|
'max-calls-per-unlock': ['--max-calls-per-unlock <n>', ['with --auto, at most n calls for the tools each unlock value', 'brings (default: 5), so every toolset gets some']],
|
|
@@ -52,6 +53,10 @@ const OPTIONS = {
|
|
|
52
53
|
'init-out': ['--out <path>', ['where to write the baseline menu (default: menu.json)']],
|
|
53
54
|
'with-session': ['--with-session', ['the workflow also runs session --auto (calls read-only tools)']],
|
|
54
55
|
port: ['--port <n>', ['loopback port for the login redirect (default: 33418)']],
|
|
56
|
+
'offline-check': ['--offline-check', ['stdio: list the menu once more with the network cut off (the proxy variables', 'pointed at a closed port): a server whose menu depends on what it fetches at start']],
|
|
57
|
+
concurrency: ['--concurrency <n>', ['servers checked at a time (default: 4)']],
|
|
58
|
+
'out-dir': ['--out-dir <dir>', ["write each server's menu file there, as <name>.json (default: none)"]],
|
|
59
|
+
'no-browser': ['--no-browser', ["don't open a browser: print the login URL, open it on any device, and paste", 'back the address the browser ends on (over SSH, in a container, on a remote box)']],
|
|
55
60
|
scope: ['--scope <scopes>', ["scopes to ask for (default: the server's)"]],
|
|
56
61
|
'client-id': ['--client-id <id>', ['a pre-registered client, for servers without dynamic registration']],
|
|
57
62
|
'client-secret': ['--client-secret <s>', ['its secret, if it has one']],
|
|
@@ -80,7 +85,7 @@ const HELP = {
|
|
|
80
85
|
'reports what in the menu confuses agents or breaks prompt caches.',
|
|
81
86
|
SERVER_NOTE,
|
|
82
87
|
],
|
|
83
|
-
own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists'],
|
|
88
|
+
own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists', 'offline-check'],
|
|
84
89
|
shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
|
|
85
90
|
examples: [
|
|
86
91
|
'toolmenu snapshot -- npx -y @modelcontextprotocol/server-memory',
|
|
@@ -110,7 +115,7 @@ const HELP = {
|
|
|
110
115
|
'prompt cache, a different menu in a fresh process.',
|
|
111
116
|
SERVER_NOTE,
|
|
112
117
|
],
|
|
113
|
-
own: ['scenario', 'auto', 'init', 'plan', 'value', 'values-file', 'assume-read-only', 'open-world', 'max-calls', 'max-calls-per-unlock', 'save-scenario', 'union-out', 'elicitation'],
|
|
118
|
+
own: ['scenario', 'auto', 'init', 'plan', 'value', 'values-file', 'assume-read-only', 'open-world', 'create-handles', 'max-calls', 'max-calls-per-unlock', 'save-scenario', 'union-out', 'elicitation'],
|
|
114
119
|
shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
|
|
115
120
|
examples: [
|
|
116
121
|
'toolmenu session --auto -- node dist/index.js',
|
|
@@ -144,7 +149,7 @@ const HELP = {
|
|
|
144
149
|
'snapshot and session then use them for that URL (--no-auth to skip).',
|
|
145
150
|
'Stored in $TOOLMENU_AUTH_DIR, else $XDG_CONFIG_HOME/toolmenu/auth, else ~/.config/toolmenu/auth.',
|
|
146
151
|
],
|
|
147
|
-
own: ['port', 'scope', 'client-id', 'client-secret'],
|
|
152
|
+
own: ['port', 'no-browser', 'scope', 'client-id', 'client-secret'],
|
|
148
153
|
shared: [],
|
|
149
154
|
examples: [
|
|
150
155
|
'toolmenu auth login https://example.com/mcp',
|
|
@@ -153,6 +158,33 @@ const HELP = {
|
|
|
153
158
|
],
|
|
154
159
|
exits: ['0 done (logout of a URL with no login is not an error)', '2 the login failed, or bad usage'],
|
|
155
160
|
},
|
|
161
|
+
scan: {
|
|
162
|
+
summary: 'snapshot every server in an MCP client config or a list, side by side',
|
|
163
|
+
usage: ['toolmenu scan [options] <list>'],
|
|
164
|
+
about: [
|
|
165
|
+
'The list is an MCP client config (Claude Desktop, Claude Code .mcp.json, Cursor,',
|
|
166
|
+
'VS Code: the mcpServers or servers object, ${VAR} filled from the environment), or a',
|
|
167
|
+
'text file with one server per line: a URL or a command, optionally "name<TAB>" first.',
|
|
168
|
+
'Runs snapshot on each (nothing written unless --out-dir). A server that could not be',
|
|
169
|
+
'started or read is a row that says why, and makes the exit code 2: it was not checked.',
|
|
170
|
+
],
|
|
171
|
+
own: ['concurrency', 'out-dir'],
|
|
172
|
+
shared: ['config', 'format', 'json', 'fail-on', 'no-auth', 'protocol', 'timeout', 'processes'],
|
|
173
|
+
examples: ['toolmenu scan ~/Library/Application\\ Support/Claude/claude_desktop_config.json', 'toolmenu scan .mcp.json --format markdown', 'toolmenu scan servers.txt --concurrency 8 --out-dir menus'],
|
|
174
|
+
exits: ['0 every server checked, no findings at or above --fail-on', '1 findings at or above --fail-on', "2 a server wasn't checked (couldn't start, couldn't connect, a variable not set), or bad usage"],
|
|
175
|
+
},
|
|
176
|
+
explain: {
|
|
177
|
+
summary: 'say what a rule checks, its default level and how to change it',
|
|
178
|
+
usage: ['toolmenu explain <rule>', 'toolmenu explain'],
|
|
179
|
+
about: [
|
|
180
|
+
'The rule as a finding names it (naming/vague-id), or the part after the slash (vague-id).',
|
|
181
|
+
'Without a rule, lists every rule by the command that reports it. Offline.',
|
|
182
|
+
],
|
|
183
|
+
own: [],
|
|
184
|
+
shared: ['format', 'json'],
|
|
185
|
+
examples: ['toolmenu explain naming/vague-id', 'toolmenu explain handle-lifetime', 'toolmenu explain --json diff/param-required'],
|
|
186
|
+
exits: ['0 explained', "2 no such rule (the closest ones are named), or bad usage"],
|
|
187
|
+
},
|
|
156
188
|
};
|
|
157
189
|
function optionLines(keys) {
|
|
158
190
|
const width = Math.max(...keys.map((k) => OPTIONS[k][0].length)) + 2;
|
package/dist/mrtr.d.ts
CHANGED
|
@@ -20,7 +20,7 @@ export interface InputTrace {
|
|
|
20
20
|
* bad-state: its requestState isn't a string, so it can't be echoed byte for byte;
|
|
21
21
|
* calling again without it would run the tool again from scratch.
|
|
22
22
|
*/
|
|
23
|
-
outcome: 'none' | 'completed' | 'loop' | 'gave-up' | 'unfinished' | 'undeclared' | 'decline-failed' | 'bad-state';
|
|
23
|
+
outcome: 'none' | 'completed' | 'loop' | 'gave-up' | 'unfinished' | 'undeclared' | 'decline-failed' | 'bad-state' | 'task';
|
|
24
24
|
/** Kinds asked for that the request didn't declare. */
|
|
25
25
|
undeclared?: InputKind[];
|
|
26
26
|
/** The protocol error a retry failed with (decline-failed): the server's words, and its JSON-RPC code. */
|
|
@@ -32,6 +32,14 @@ export interface InputTrace {
|
|
|
32
32
|
continuations?: number;
|
|
33
33
|
/** A raw result on the wire without resultType, which 2026-07-28 servers MUST send. */
|
|
34
34
|
missingResultType?: boolean;
|
|
35
|
+
/**
|
|
36
|
+
* task: the server answered with a CreateTaskResult (resultType "task", ext-tasks),
|
|
37
|
+
* which it MUST NOT send to a client that didn't declare io.modelcontextprotocol/tasks.
|
|
38
|
+
*/
|
|
39
|
+
task?: {
|
|
40
|
+
taskId?: string;
|
|
41
|
+
status?: string;
|
|
42
|
+
};
|
|
35
43
|
}
|
|
36
44
|
type CallResult = Awaited<ReturnType<Connection['client']['callTool']>>;
|
|
37
45
|
/**
|
package/dist/mrtr.js
CHANGED
|
@@ -13,6 +13,16 @@ import { httpStatus, tooMany } from './failures.js';
|
|
|
13
13
|
export const MAX_ROUNDS = 3;
|
|
14
14
|
/** Rounds that carry only requestState (the tool keeps working, asks nothing) before toolmenu stops. */
|
|
15
15
|
export const MAX_CONTINUATIONS = 10;
|
|
16
|
+
/** A CreateTaskResult (ext-tasks): resultType "task", with the task's id and status. */
|
|
17
|
+
function taskOf(result) {
|
|
18
|
+
if (!isObject(result) || result.resultType !== 'task')
|
|
19
|
+
return undefined;
|
|
20
|
+
const task = isObject(result.task) ? result.task : result;
|
|
21
|
+
return {
|
|
22
|
+
...(typeof task.taskId === 'string' ? { taskId: task.taskId } : {}),
|
|
23
|
+
...(typeof task.status === 'string' ? { status: task.status } : {}),
|
|
24
|
+
};
|
|
25
|
+
}
|
|
16
26
|
const DECLARED = new Set(['form', 'url']);
|
|
17
27
|
function kindOf(request) {
|
|
18
28
|
if (request.method === 'elicitation/create')
|
|
@@ -100,6 +110,10 @@ export async function callWithInput(conn, params, options) {
|
|
|
100
110
|
// What the server sent decides what failed, not the error the SDK raised.
|
|
101
111
|
const wire = conn.wire.since(mark, 'tools/call').at(-1);
|
|
102
112
|
const answered = wire?.result;
|
|
113
|
+
// A task handle toolmenu didn't ask for (it declares no Tasks support): nothing to poll.
|
|
114
|
+
const task = taskOf(answered);
|
|
115
|
+
if (task)
|
|
116
|
+
return { input: trace('task', { task }) };
|
|
103
117
|
if (isObject(answered) && !('resultType' in answered)) {
|
|
104
118
|
// No resultType: the SDK client rejects it ("missing required resultType").
|
|
105
119
|
// The server did answer; session/result-type says why clients won't take it.
|
|
@@ -126,6 +140,9 @@ export async function callWithInput(conn, params, options) {
|
|
|
126
140
|
return { input: trace('decline-failed', { error: { message: firstLine(wire.error.message ?? error), ...(typeof code === 'number' ? { code } : {}) } }) };
|
|
127
141
|
}
|
|
128
142
|
}
|
|
143
|
+
const task = taskOf(conn.wire.since(mark, 'tools/call').at(-1)?.result ?? result);
|
|
144
|
+
if (task)
|
|
145
|
+
return { input: trace('task', { task }) };
|
|
129
146
|
if (result.resultType !== 'input_required')
|
|
130
147
|
return { result: result, input: trace(finished()) };
|
|
131
148
|
const required = result;
|
package/dist/options.d.ts
CHANGED
|
@@ -2,6 +2,15 @@ export declare const CLI_OPTIONS: {
|
|
|
2
2
|
readonly out: {
|
|
3
3
|
readonly type: 'string';
|
|
4
4
|
};
|
|
5
|
+
readonly 'out-dir': {
|
|
6
|
+
readonly type: 'string';
|
|
7
|
+
};
|
|
8
|
+
readonly 'offline-check': {
|
|
9
|
+
readonly type: 'boolean';
|
|
10
|
+
};
|
|
11
|
+
readonly concurrency: {
|
|
12
|
+
readonly type: 'string';
|
|
13
|
+
};
|
|
5
14
|
readonly 'no-write': {
|
|
6
15
|
readonly type: 'boolean';
|
|
7
16
|
};
|
|
@@ -53,6 +62,9 @@ export declare const CLI_OPTIONS: {
|
|
|
53
62
|
readonly port: {
|
|
54
63
|
readonly type: 'string';
|
|
55
64
|
};
|
|
65
|
+
readonly 'no-browser': {
|
|
66
|
+
readonly type: 'boolean';
|
|
67
|
+
};
|
|
56
68
|
readonly scope: {
|
|
57
69
|
readonly type: 'string';
|
|
58
70
|
};
|
|
@@ -114,6 +126,9 @@ export declare const CLI_OPTIONS: {
|
|
|
114
126
|
readonly auto: {
|
|
115
127
|
readonly type: 'boolean';
|
|
116
128
|
};
|
|
129
|
+
readonly 'create-handles': {
|
|
130
|
+
readonly type: 'boolean';
|
|
131
|
+
};
|
|
117
132
|
readonly 'with-session': {
|
|
118
133
|
readonly type: 'boolean';
|
|
119
134
|
};
|
package/dist/options.js
CHANGED
|
@@ -4,6 +4,9 @@
|
|
|
4
4
|
*/
|
|
5
5
|
export const CLI_OPTIONS = {
|
|
6
6
|
out: { type: 'string' },
|
|
7
|
+
'out-dir': { type: 'string' },
|
|
8
|
+
'offline-check': { type: 'boolean' },
|
|
9
|
+
concurrency: { type: 'string' },
|
|
7
10
|
'no-write': { type: 'boolean' },
|
|
8
11
|
routes: { type: 'string' },
|
|
9
12
|
config: { type: 'string' },
|
|
@@ -20,6 +23,7 @@ export const CLI_OPTIONS = {
|
|
|
20
23
|
elicitation: { type: 'string' },
|
|
21
24
|
'no-auth': { type: 'boolean' },
|
|
22
25
|
port: { type: 'string' },
|
|
26
|
+
'no-browser': { type: 'boolean' },
|
|
23
27
|
scope: { type: 'string' },
|
|
24
28
|
'client-id': { type: 'string' },
|
|
25
29
|
'client-secret': { type: 'string' },
|
|
@@ -40,6 +44,7 @@ export const CLI_OPTIONS = {
|
|
|
40
44
|
init: { type: 'boolean' },
|
|
41
45
|
'union-out': { type: 'string' },
|
|
42
46
|
auto: { type: 'boolean' },
|
|
47
|
+
'create-handles': { type: 'boolean' },
|
|
43
48
|
'with-session': { type: 'boolean' },
|
|
44
49
|
catalog: { type: 'boolean' },
|
|
45
50
|
'open-world': { type: 'boolean' },
|
package/dist/probe.d.ts
CHANGED
|
@@ -44,4 +44,14 @@ export declare function probeMenu(target: Target, timeoutMs: number, waits?: num
|
|
|
44
44
|
* HTTP probe that differs is retried once: a rolling deploy can serve two
|
|
45
45
|
* versions for a moment.
|
|
46
46
|
*/
|
|
47
|
-
|
|
47
|
+
/**
|
|
48
|
+
* probeMenu, on the protocol an earlier connection got. Negotiated as usual (so errors
|
|
49
|
+
* read as they always have); only a probe that ends on the other protocol is asked
|
|
50
|
+
* again, pinned to that one. Under load a version probe can time out and fall back to
|
|
51
|
+
* 2025 in one process only, and a menu from another protocol differs in ways no
|
|
52
|
+
* client sees (mastra's $schema): a false variance (the 0.22 corpus run).
|
|
53
|
+
*/
|
|
54
|
+
export declare function probeSameEra(target: Target, era: string | undefined, timeoutMs: number, waits?: number[], waited?: {
|
|
55
|
+
ms: number;
|
|
56
|
+
}, seen?: Set<string>): Promise<Menu>;
|
|
57
|
+
export declare function probeVariance(target: Target, main: MenuTool[], processes: number, timeoutMs: number, waits?: number[], era?: string, seen?: Set<string>): Promise<Probe[]>;
|
package/dist/probe.js
CHANGED
|
@@ -75,15 +75,30 @@ export async function probeMenu(target, timeoutMs, waits, waited) {
|
|
|
75
75
|
* HTTP probe that differs is retried once: a rolling deploy can serve two
|
|
76
76
|
* versions for a moment.
|
|
77
77
|
*/
|
|
78
|
-
|
|
78
|
+
/**
|
|
79
|
+
* probeMenu, on the protocol an earlier connection got. Negotiated as usual (so errors
|
|
80
|
+
* read as they always have); only a probe that ends on the other protocol is asked
|
|
81
|
+
* again, pinned to that one. Under load a version probe can time out and fall back to
|
|
82
|
+
* 2025 in one process only, and a menu from another protocol differs in ways no
|
|
83
|
+
* client sees (mastra's $schema): a false variance (the 0.22 corpus run).
|
|
84
|
+
*/
|
|
85
|
+
export async function probeSameEra(target, era, timeoutMs, waits, waited, seen) {
|
|
86
|
+
const m = await probeMenu(target, timeoutMs, waits, waited);
|
|
87
|
+
if (m.server.era)
|
|
88
|
+
seen?.add(m.server.era);
|
|
89
|
+
if (!era || target.protocol || m.server.era === era)
|
|
90
|
+
return m;
|
|
91
|
+
return probeMenu({ ...target, protocol: era === 'modern' ? 'modern' : 'legacy' }, timeoutMs, waits, waited);
|
|
92
|
+
}
|
|
93
|
+
export async function probeVariance(target, main, processes, timeoutMs, waits, era, seen) {
|
|
79
94
|
const probes = [];
|
|
80
95
|
for (let i = 0; i < processes - 1; i++) {
|
|
81
96
|
const seed = String(Number(PROBE_SEED) + i);
|
|
82
97
|
const waited = { ms: 0 };
|
|
83
98
|
try {
|
|
84
|
-
let tools = (await
|
|
99
|
+
let tools = (await probeSameEra(seeded(target, seed), era, timeoutMs, waits, waited, seen)).tools;
|
|
85
100
|
if (target.kind === 'http' && compareMenus(main, tools).length)
|
|
86
|
-
tools = (await
|
|
101
|
+
tools = (await probeSameEra(target, era, timeoutMs, waits, waited)).tools;
|
|
87
102
|
probes.push({ tools });
|
|
88
103
|
}
|
|
89
104
|
catch (error) {
|
package/dist/report.d.ts
CHANGED
|
@@ -6,7 +6,10 @@ import { type Finding, type Menu, type Severity } from './types.js';
|
|
|
6
6
|
export type Format = 'text' | 'json' | 'github' | 'markdown';
|
|
7
7
|
export declare function counts(findings: Finding[]): Record<Severity, number>;
|
|
8
8
|
export declare function formatSnapshot(menu: Menu, findings: Finding[], format: Format, outPath?: string, cost?: ClientCost, notOffered?: string[]): string;
|
|
9
|
+
export declare function findingLines(findings: Finding[]): string[];
|
|
10
|
+
export declare function githubLines(findings: Finding[]): string[];
|
|
9
11
|
export declare function formatDiff(d: DiffResult, beforeTools: number, afterTools: number, format: Format): string;
|
|
10
12
|
export declare function formatHistory(h: HistoryResult, format: Format, outDir: string, csvPath?: string): string;
|
|
11
13
|
export declare function formatSession(s: SessionResult, format: Format): string;
|
|
12
14
|
export declare function formatPlan(scenario: Scenario, name: string): string;
|
|
15
|
+
export declare function mdFindings(findings: Finding[]): string[];
|