toolmenu 0.21.0 → 0.24.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 +96 -37
- package/dist/apps.d.ts +56 -0
- package/dist/apps.js +99 -0
- package/dist/auto.js +2 -2
- package/dist/card.d.ts +18 -0
- package/dist/card.js +39 -0
- package/dist/cli.d.ts +1 -1
- package/dist/cli.js +70 -11
- 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 +15 -0
- package/dist/connect.js +54 -7
- package/dist/diff.js +113 -6
- package/dist/explain.d.ts +16 -0
- package/dist/explain.js +14 -0
- package/dist/failures.d.ts +18 -5
- package/dist/failures.js +27 -12
- package/dist/help.d.ts +1 -1
- package/dist/help.js +18 -3
- package/dist/mcp-env.d.ts +5 -0
- package/dist/mcp-env.js +5 -0
- package/dist/mcp.d.ts +65 -0
- package/dist/mcp.js +293 -0
- package/dist/mrtr.d.ts +9 -1
- package/dist/mrtr.js +17 -0
- package/dist/options.d.ts +3 -0
- package/dist/options.js +1 -0
- package/dist/probe.d.ts +11 -1
- package/dist/probe.js +18 -3
- package/dist/report.js +12 -5
- package/dist/rule-docs.json +94 -4
- package/dist/rules/apps.d.ts +11 -0
- package/dist/rules/apps.js +156 -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/headers.d.ts +0 -2
- package/dist/rules/headers.js +7 -12
- package/dist/rules/ids.js +35 -1
- package/dist/rules/index.js +18 -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 +18 -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/session.js +60 -11
- package/dist/snapshot.d.ts +5 -0
- package/dist/snapshot.js +89 -5
- package/dist/types.d.ts +5 -0
- package/dist/words.d.ts +8 -0
- package/dist/words.js +30 -2
- package/package.json +8 -7
- package/schemas/server-card.json +260 -0
package/dist/colour.js
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Colour for text output in a terminal: severities, the next step, the verdict. Applied
|
|
3
|
+
* to the finished text, line by line, so every command's report gets it the same way
|
|
4
|
+
* and the text itself never depends on it. Only when the stream is a terminal, unless
|
|
5
|
+
* NO_COLOR (https://no-color.org) or FORCE_COLOR says otherwise; never for json,
|
|
6
|
+
* markdown or github output.
|
|
7
|
+
*/
|
|
8
|
+
const ESC = '\x1b[';
|
|
9
|
+
const paint = (codes, text) => (text ? `${ESC}${codes}m${text}${ESC}0m` : text);
|
|
10
|
+
const SEVERITY = { ERROR: '1;31', WARN: '1;33', INFO: '1;36' };
|
|
11
|
+
/** Whether text written to this stream gets colour. */
|
|
12
|
+
export function colourFor(stream, env = process.env) {
|
|
13
|
+
if (env.NO_COLOR !== undefined && env.NO_COLOR !== '')
|
|
14
|
+
return false;
|
|
15
|
+
if (env.FORCE_COLOR !== undefined)
|
|
16
|
+
return env.FORCE_COLOR !== '0' && env.FORCE_COLOR !== 'false';
|
|
17
|
+
return !!stream.isTTY && env.TERM !== 'dumb';
|
|
18
|
+
}
|
|
19
|
+
/** The report with ANSI colour: the same characters otherwise. */
|
|
20
|
+
export function colourise(text) {
|
|
21
|
+
// Lines deeper than the current finding's message are its evidence: dimmed.
|
|
22
|
+
let evidenceFrom;
|
|
23
|
+
return text
|
|
24
|
+
.split('\n')
|
|
25
|
+
.map((line) => {
|
|
26
|
+
const indent = line.length - line.trimStart().length;
|
|
27
|
+
const finding = /^(\s*)(ERROR|WARN|INFO)(\s+)(\S+)(.*)$/.exec(line);
|
|
28
|
+
if (finding) {
|
|
29
|
+
const [, lead, severity, gap, rule, rest] = finding;
|
|
30
|
+
evidenceFrom = lead.length + severity.length + gap.length + 1;
|
|
31
|
+
return `${lead}${paint(SEVERITY[severity], severity)}${gap}${paint('1', rule)}${rest.replace(/ · unsure\b/, paint('2;3', ' · unsure'))}`;
|
|
32
|
+
}
|
|
33
|
+
const next = /^(\s*)(→ Next:)(.*)$/.exec(line);
|
|
34
|
+
if (next)
|
|
35
|
+
return `${next[1]}${paint('1;32', next[2])}${paint('32', next[3])}`;
|
|
36
|
+
if (!line.trim() || indent === 0)
|
|
37
|
+
evidenceFrom = undefined;
|
|
38
|
+
if (evidenceFrom !== undefined && indent >= evidenceFrom)
|
|
39
|
+
return paint('2', line);
|
|
40
|
+
if (/^✗ /.test(line))
|
|
41
|
+
return paint('1;31', line);
|
|
42
|
+
if (/^✓ /.test(line))
|
|
43
|
+
return paint('1;32', line);
|
|
44
|
+
const title = /^(toolmenu \w+)(.*)$/.exec(line);
|
|
45
|
+
if (title)
|
|
46
|
+
return `${paint('1;35', title[1])}${paint('1', title[2])}`;
|
|
47
|
+
const step = /^((?:step \d+|final):)(.*)$/.exec(line);
|
|
48
|
+
if (step)
|
|
49
|
+
return `${paint('1', step[1])}${step[2].replace(/menu changed/g, paint('33', 'menu changed'))}`;
|
|
50
|
+
return line;
|
|
51
|
+
})
|
|
52
|
+
.join('\n');
|
|
53
|
+
}
|
|
54
|
+
/** An error that stopped a command, with colour: what failed, the labelled evidence, the next step. */
|
|
55
|
+
export function colouriseError(text) {
|
|
56
|
+
return text
|
|
57
|
+
.split('\n')
|
|
58
|
+
.map((line) => {
|
|
59
|
+
if (line.startsWith('toolmenu: '))
|
|
60
|
+
return `${paint('1;31', 'toolmenu:')}${paint('1', line.slice('toolmenu:'.length))}`;
|
|
61
|
+
const next = /^(\s*)(→ Next:)(.*)$/.exec(line);
|
|
62
|
+
if (next)
|
|
63
|
+
return `${next[1]}${paint('1;32', next[2])}${paint('32', next[3])}`;
|
|
64
|
+
const field = /^(\s{2})([a-z][a-z -]*?)(\s{2,})(.*)$/.exec(line);
|
|
65
|
+
if (field)
|
|
66
|
+
return `${field[1]}${paint('2', field[2])}${field[3]}${field[4]}`;
|
|
67
|
+
return line;
|
|
68
|
+
})
|
|
69
|
+
.join('\n');
|
|
70
|
+
}
|
package/dist/config.d.ts
CHANGED
|
@@ -30,6 +30,8 @@ export interface Config {
|
|
|
30
30
|
lists?: string[];
|
|
31
31
|
/** snapshot: the client to check the menu for (claude-code, claude-api-search, openai). --client wins. */
|
|
32
32
|
client?: string;
|
|
33
|
+
/** snapshot (stdio): also list the menu with the network cut off. --offline-check turns it on too. */
|
|
34
|
+
offlineCheck?: boolean;
|
|
33
35
|
/** Server processes (stdio) or connections (HTTP) to compare, the main one included (default 2). */
|
|
34
36
|
processes?: number;
|
|
35
37
|
/**
|
package/dist/config.js
CHANGED
|
@@ -34,6 +34,8 @@ export async function loadConfig(path) {
|
|
|
34
34
|
if (config.lists !== undefined && !(Array.isArray(config.lists) && config.lists.every((l) => LIST_WORDS.includes(l)))) {
|
|
35
35
|
throw new Error(`${file}: lists must be a list of ${LIST_WORDS.join(', ')}`);
|
|
36
36
|
}
|
|
37
|
+
if (config.offlineCheck !== undefined && typeof config.offlineCheck !== 'boolean')
|
|
38
|
+
throw new Error(`${file}: offlineCheck must be true or false`);
|
|
37
39
|
if (config.client !== undefined && !(typeof config.client === 'string' && Object.hasOwn(CLIENTS, config.client))) {
|
|
38
40
|
throw new Error(`${file}: client must be one of ${Object.keys(CLIENTS).join(', ')}`);
|
|
39
41
|
}
|
package/dist/connect.d.ts
CHANGED
|
@@ -16,6 +16,7 @@ export type Target = {
|
|
|
16
16
|
cwd?: string;
|
|
17
17
|
protocol?: Protocol;
|
|
18
18
|
elicitation?: Elicitation;
|
|
19
|
+
apps?: boolean;
|
|
19
20
|
} | {
|
|
20
21
|
kind: 'http';
|
|
21
22
|
url: string;
|
|
@@ -23,7 +24,12 @@ export type Target = {
|
|
|
23
24
|
noAuth?: boolean;
|
|
24
25
|
protocol?: Protocol;
|
|
25
26
|
elicitation?: Elicitation;
|
|
27
|
+
apps?: boolean;
|
|
26
28
|
};
|
|
29
|
+
/** The MCP Apps extension (ext-apps): interactive UI a tool names in _meta.ui.resourceUri. */
|
|
30
|
+
export declare const APPS_EXTENSION = "io.modelcontextprotocol/ui";
|
|
31
|
+
/** The one content type an MCP App's resource may have. */
|
|
32
|
+
export declare const APPS_MIME_TYPE = "text/html;profile=mcp-app";
|
|
27
33
|
export interface WireResponse {
|
|
28
34
|
method: string;
|
|
29
35
|
result?: Record<string, unknown>;
|
|
@@ -67,6 +73,15 @@ export interface ConnectOptions {
|
|
|
67
73
|
timeoutMs?: number;
|
|
68
74
|
}
|
|
69
75
|
export declare function connect(target: Target, options?: ConnectOptions): Promise<Connection>;
|
|
76
|
+
/**
|
|
77
|
+
* Where a redirect response points, when it leaves the request's origin as the MCP
|
|
78
|
+
* SDK (2.3 and later) judges it: same scheme and host:port, or http to https on the
|
|
79
|
+
* same host with default ports, is within. Anything else the SDK leaves to it.
|
|
80
|
+
*/
|
|
81
|
+
export declare function crossOriginRedirect(input: string | URL | Request, response: Response): {
|
|
82
|
+
from: string;
|
|
83
|
+
to: string;
|
|
84
|
+
} | undefined;
|
|
70
85
|
export interface ToolList {
|
|
71
86
|
tools: Record<string, unknown>[];
|
|
72
87
|
/** Every page's raw result, for schema validation. */
|
package/dist/connect.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
|
|
2
2
|
import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/client/stdio';
|
|
3
3
|
import { hasLogin, StoredOAuthProvider } from './auth.js';
|
|
4
|
-
import { explain, isCredentialHeader, Trace } from './explain.js';
|
|
4
|
+
import { explain, isCredentialHeader, redirectError, Trace } from './explain.js';
|
|
5
5
|
import { endSession } from './close.js';
|
|
6
6
|
import { eraOf } from './menu.js';
|
|
7
7
|
import { VERSION } from './version.js';
|
|
@@ -48,6 +48,10 @@ export async function quietExclusions(work) {
|
|
|
48
48
|
export const PROTOCOLS = ['auto', 'legacy', 'modern'];
|
|
49
49
|
export const MODERN_VERSION = '2026-07-28';
|
|
50
50
|
export const ELICITATIONS = ['decline', 'cancel'];
|
|
51
|
+
/** The MCP Apps extension (ext-apps): interactive UI a tool names in _meta.ui.resourceUri. */
|
|
52
|
+
export const APPS_EXTENSION = 'io.modelcontextprotocol/ui';
|
|
53
|
+
/** The one content type an MCP App's resource may have. */
|
|
54
|
+
export const APPS_MIME_TYPE = 'text/html;profile=mcp-app';
|
|
51
55
|
/** Every response the server sent, matched to the request method, as it came off the wire. */
|
|
52
56
|
export class WireLog {
|
|
53
57
|
responses = [];
|
|
@@ -93,13 +97,25 @@ export class WireLog {
|
|
|
93
97
|
export async function connect(target, options = {}) {
|
|
94
98
|
const client = new Client({ name: 'toolmenu', version: VERSION }, {
|
|
95
99
|
versionNegotiation: { mode: target.protocol === 'legacy' ? 'legacy' : target.protocol === 'modern' ? { pin: MODERN_VERSION } : 'auto' },
|
|
96
|
-
//
|
|
97
|
-
//
|
|
98
|
-
//
|
|
99
|
-
//
|
|
100
|
-
//
|
|
100
|
+
// With target.elicitation set, the connection declares elicitation, form and URL
|
|
101
|
+
// mode: session, so a tool that asks the user something runs its "the user said
|
|
102
|
+
// no" path instead of failing (2026-07-28 multi round-trip requests); and, from
|
|
103
|
+
// 0.22, snapshot's listing, since a server may list more tools to a client that
|
|
104
|
+
// can be asked things (github-mcp-server's delete_repository). snapshot lists
|
|
105
|
+
// once more without it (menu/capability-dependent).
|
|
101
106
|
// Never roots or sampling: 2026-07-28 deprecates them (SEP-2577).
|
|
102
|
-
|
|
107
|
+
// With target.apps, the MCP Apps extension too: a server MAY register different tools,
|
|
108
|
+
// or other variants of them, for a host that renders apps (ext-apps, "Servers SHOULD
|
|
109
|
+
// check client capabilities before registering UI-enabled tools"), so the baseline
|
|
110
|
+
// is listed as such a host, as for elicitation.
|
|
111
|
+
...(target.elicitation || target.apps
|
|
112
|
+
? {
|
|
113
|
+
capabilities: {
|
|
114
|
+
...(target.elicitation ? { elicitation: { form: {}, url: {} } } : {}),
|
|
115
|
+
...(target.apps ? { extensions: { [APPS_EXTENSION]: { mimeTypes: [APPS_MIME_TYPE] } } } : {}),
|
|
116
|
+
},
|
|
117
|
+
}
|
|
118
|
+
: {}),
|
|
103
119
|
});
|
|
104
120
|
// A 2025 server asks with an elicitation/create request; 2026-07-28 ones embed it
|
|
105
121
|
// in an input_required result, which session answers itself (mrtr.ts). Same answer.
|
|
@@ -266,6 +282,29 @@ function watchProcess(stdio, trace) {
|
|
|
266
282
|
}
|
|
267
283
|
};
|
|
268
284
|
}
|
|
285
|
+
/**
|
|
286
|
+
* Where a redirect response points, when it leaves the request's origin as the MCP
|
|
287
|
+
* SDK (2.3 and later) judges it: same scheme and host:port, or http to https on the
|
|
288
|
+
* same host with default ports, is within. Anything else the SDK leaves to it.
|
|
289
|
+
*/
|
|
290
|
+
export function crossOriginRedirect(input, response) {
|
|
291
|
+
if (![301, 302, 303, 307, 308].includes(response.status))
|
|
292
|
+
return undefined;
|
|
293
|
+
const location = response.headers.get('location');
|
|
294
|
+
if (!location)
|
|
295
|
+
return undefined;
|
|
296
|
+
let from;
|
|
297
|
+
let to;
|
|
298
|
+
try {
|
|
299
|
+
from = new URL(typeof input === 'string' || input instanceof URL ? input : input.url);
|
|
300
|
+
to = new URL(location, from);
|
|
301
|
+
}
|
|
302
|
+
catch {
|
|
303
|
+
return undefined;
|
|
304
|
+
}
|
|
305
|
+
const within = (from.protocol === to.protocol && from.host === to.host) || (from.protocol === 'http:' && to.protocol === 'https:' && from.hostname === to.hostname && !from.port && !to.port);
|
|
306
|
+
return within ? undefined : { from: from.href, to: to.href };
|
|
307
|
+
}
|
|
269
308
|
/** fetch, noting each JSON-RPC request's method and the answer's status, content type and final URL. */
|
|
270
309
|
function tracedFetch(trace) {
|
|
271
310
|
return async (input, init) => {
|
|
@@ -283,6 +322,14 @@ function tracedFetch(trace) {
|
|
|
283
322
|
if (method)
|
|
284
323
|
trace.send(method);
|
|
285
324
|
const response = await fetch(input, init);
|
|
325
|
+
// A redirect the SDK won't follow because it leaves the origin (2.3 and later). Its
|
|
326
|
+
// own error names the target; this one also says which clients fail the same way,
|
|
327
|
+
// and what to run next. explain() returns it as it is.
|
|
328
|
+
const to = crossOriginRedirect(input, response);
|
|
329
|
+
if (to) {
|
|
330
|
+
trace.redirect ??= { ...to, status: response.status };
|
|
331
|
+
throw redirectError(trace.redirect);
|
|
332
|
+
}
|
|
286
333
|
if (method) {
|
|
287
334
|
trace.http.set(method, { status: response.status, statusText: response.statusText, contentType: response.headers.get('content-type') ?? '', url: response.url });
|
|
288
335
|
}
|
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';
|
|
@@ -40,6 +41,18 @@ export const DIFF_RULES = {
|
|
|
40
41
|
'diff/properties-opened': { severity: 'info', class: 'minor' },
|
|
41
42
|
'diff/properties-closed': { severity: 'error', class: 'breaking' },
|
|
42
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' },
|
|
43
56
|
'diff/other': { severity: 'info', class: 'notice' },
|
|
44
57
|
'diff/order': { severity: 'info', class: 'notice' },
|
|
45
58
|
// A tool lost a parameter and gained a required one with a close name: likely a
|
|
@@ -148,8 +161,10 @@ export function diffMenus(before, after, options = {}) {
|
|
|
148
161
|
}
|
|
149
162
|
raw.push(...compareCatalogs(before.catalog, after.catalog, ignored));
|
|
150
163
|
raw.push(...compareLists(before, after));
|
|
164
|
+
raw.push(...compareExtensions(before, after));
|
|
151
165
|
// Ignored tools leave the token counts and the budget too.
|
|
152
|
-
|
|
166
|
+
// What the agent pays: app-only tools (MCP Apps) aren't in its list.
|
|
167
|
+
const tokens = tokenChange(agentTools(oldTools), agentTools(newTools));
|
|
153
168
|
if (options.tokenBudget !== undefined && tokens.after > options.tokenBudget) {
|
|
154
169
|
const grew = tokens.tools.filter((t) => t.delta > 0).slice(0, 3);
|
|
155
170
|
raw.push({
|
|
@@ -387,9 +402,8 @@ const MAX_DEPTH = 64;
|
|
|
387
402
|
function headerLoss(t, headers, old) {
|
|
388
403
|
if (!headers)
|
|
389
404
|
return undefined;
|
|
390
|
-
const
|
|
391
|
-
|
|
392
|
-
if (!broken.length || (old && dropped(old).length))
|
|
405
|
+
const broken = headerFaults(t);
|
|
406
|
+
if (!broken.length || (old && headerFaults(old).length))
|
|
393
407
|
return undefined;
|
|
394
408
|
return {
|
|
395
409
|
rule: 'diff/x-mcp-header-invalid',
|
|
@@ -1410,10 +1424,13 @@ function compareRest(old, t) {
|
|
|
1410
1424
|
across: same(`annotations\u0000${what}`, (count, list) => `Annotations changed the same way (${what}) in ${count}: ${list}.`),
|
|
1411
1425
|
});
|
|
1412
1426
|
}
|
|
1413
|
-
|
|
1427
|
+
out.push(...compareApps(old, t));
|
|
1428
|
+
// _meta.ui's URI and visibility are compareApps'; the rest of _meta is compared as any other field.
|
|
1429
|
+
const field = (tool, k) => (k === '_meta' ? withoutUi(tool._meta) : tool[k]);
|
|
1430
|
+
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();
|
|
1414
1431
|
if (others.length) {
|
|
1415
1432
|
const what = others.map((k) => {
|
|
1416
|
-
const pair = `${show(old
|
|
1433
|
+
const pair = `${show(field(old, k))} → ${show(field(t, k))}`;
|
|
1417
1434
|
return pair.length <= 60 ? `${k} ${pair}` : k;
|
|
1418
1435
|
}).join(', ');
|
|
1419
1436
|
out.push({
|
|
@@ -1425,6 +1442,96 @@ function compareRest(old, t) {
|
|
|
1425
1442
|
}
|
|
1426
1443
|
return out;
|
|
1427
1444
|
}
|
|
1445
|
+
/** _meta without MCP Apps' resourceUri, visibility and the deprecated ui/resourceUri; undefined when nothing else is left. */
|
|
1446
|
+
function withoutUi(meta) {
|
|
1447
|
+
if (typeof meta !== 'object' || meta === null || Array.isArray(meta))
|
|
1448
|
+
return meta;
|
|
1449
|
+
const { ui, [LEGACY_URI_KEY]: _legacy, ...rest } = meta;
|
|
1450
|
+
// Only what compareApps says: the URI and visibility. The rest of _meta.ui (csp,
|
|
1451
|
+
// permissions, domain, prefersBorder) is still compared here, as any _meta field.
|
|
1452
|
+
if (typeof ui === 'object' && ui !== null && !Array.isArray(ui)) {
|
|
1453
|
+
const { resourceUri: _uri, visibility: _visibility, ...uiRest } = ui;
|
|
1454
|
+
if (Object.keys(uiRest).length)
|
|
1455
|
+
rest.ui = uiRest;
|
|
1456
|
+
}
|
|
1457
|
+
else if (ui !== undefined) {
|
|
1458
|
+
rest.ui = ui;
|
|
1459
|
+
}
|
|
1460
|
+
return Object.keys(rest).length ? rest : undefined;
|
|
1461
|
+
}
|
|
1462
|
+
/** Who sees the tool on an Apps host, as visibility says (default: both). */
|
|
1463
|
+
function seenBy(tool) {
|
|
1464
|
+
const v = uiMeta(tool)?.visibility;
|
|
1465
|
+
return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : ['model', 'app'];
|
|
1466
|
+
}
|
|
1467
|
+
/** MCP Apps: visibility and the UI a tool names. */
|
|
1468
|
+
function compareApps(old, t) {
|
|
1469
|
+
const out = [];
|
|
1470
|
+
const name = t.name;
|
|
1471
|
+
const a = seenBy(old);
|
|
1472
|
+
const b = seenBy(t);
|
|
1473
|
+
const pair = `${show(a)} → ${show(b)}`;
|
|
1474
|
+
if (a.includes('model') && !b.includes('model')) {
|
|
1475
|
+
out.push({
|
|
1476
|
+
rule: 'diff/apps-visibility',
|
|
1477
|
+
tool: name,
|
|
1478
|
+
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.`,
|
|
1479
|
+
fix: `Keep "model" in ${code(name)}'s visibility for one release, or ${BREAKING_RELEASE}.`,
|
|
1480
|
+
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.` },
|
|
1481
|
+
});
|
|
1482
|
+
}
|
|
1483
|
+
else if (!a.includes('model') && b.includes('model')) {
|
|
1484
|
+
out.push({
|
|
1485
|
+
rule: 'diff/apps-visible',
|
|
1486
|
+
tool: name,
|
|
1487
|
+
message: `${code(name)} is now shown to the agent (MCP Apps visibility ${pair}, ~${fmt(t.tokens)} tokens, estimate).`,
|
|
1488
|
+
});
|
|
1489
|
+
}
|
|
1490
|
+
else if (canonical(a) !== canonical(b)) {
|
|
1491
|
+
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'}.` });
|
|
1492
|
+
}
|
|
1493
|
+
const ua = resourceUriOf(old);
|
|
1494
|
+
const ub = resourceUriOf(t);
|
|
1495
|
+
if (ua !== ub) {
|
|
1496
|
+
const what = ua === undefined ? `now names a UI (${ub})` : ub === undefined ? `no longer names a UI (was ${ua})` : `names another UI (${ua} → ${ub})`;
|
|
1497
|
+
out.push({
|
|
1498
|
+
rule: 'diff/apps-ui',
|
|
1499
|
+
tool: name,
|
|
1500
|
+
message: `${code(name)} ${what}. What an MCP Apps host renders for it changes; calls don't.`,
|
|
1501
|
+
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.` },
|
|
1502
|
+
});
|
|
1503
|
+
}
|
|
1504
|
+
return out;
|
|
1505
|
+
}
|
|
1506
|
+
/** capabilities.extensions, compared. Menu files from before 0.23 didn't record them: not compared. */
|
|
1507
|
+
function compareExtensions(before, after) {
|
|
1508
|
+
const a = before.server.extensions;
|
|
1509
|
+
const b = after.server.extensions;
|
|
1510
|
+
if (!a || !b)
|
|
1511
|
+
return [];
|
|
1512
|
+
const out = [];
|
|
1513
|
+
for (const id of Object.keys(a)) {
|
|
1514
|
+
if (!(id in b)) {
|
|
1515
|
+
out.push({
|
|
1516
|
+
rule: 'diff/extension-removed',
|
|
1517
|
+
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.`,
|
|
1518
|
+
fix: `If it was dropped by mistake, declare ${code(id)} again; if on purpose, say so in the release notes, or ${BREAKING_RELEASE}.`,
|
|
1519
|
+
});
|
|
1520
|
+
}
|
|
1521
|
+
else if (canonical(a[id]) !== canonical(b[id])) {
|
|
1522
|
+
out.push({ rule: 'diff/extension-settings', message: `The ${code(id)} extension's settings changed (${show(a[id])} → ${show(b[id])}).` });
|
|
1523
|
+
}
|
|
1524
|
+
}
|
|
1525
|
+
for (const id of Object.keys(b))
|
|
1526
|
+
if (!(id in a))
|
|
1527
|
+
out.push({ rule: 'diff/extension-added', message: `The server now declares the ${code(id)} extension.` });
|
|
1528
|
+
return out;
|
|
1529
|
+
}
|
|
1530
|
+
/** What clients lose with an official extension, for the message. */
|
|
1531
|
+
const EXTENSION_USE = {
|
|
1532
|
+
'io.modelcontextprotocol/ui': 'MCP Apps: the UI of tools that name one',
|
|
1533
|
+
'io.modelcontextprotocol/tasks': 'Tasks: long-running calls answered with a task to poll',
|
|
1534
|
+
};
|
|
1428
1535
|
function readOnly(a) {
|
|
1429
1536
|
return a.readOnlyHint === true;
|
|
1430
1537
|
}
|
package/dist/explain.d.ts
CHANGED
|
@@ -18,6 +18,12 @@ export declare class Trace {
|
|
|
18
18
|
contentType: string;
|
|
19
19
|
url: string;
|
|
20
20
|
}>;
|
|
21
|
+
/** HTTP: a redirect to another origin, which the MCP SDK (2.3 and later) doesn't follow. */
|
|
22
|
+
redirect?: {
|
|
23
|
+
from: string;
|
|
24
|
+
to: string;
|
|
25
|
+
status: number;
|
|
26
|
+
};
|
|
21
27
|
process?: ChildProcess;
|
|
22
28
|
/** How the process ended. `afterStop`: it ended after toolmenu sent it SIGTERM, so the exit may be toolmenu's doing. */
|
|
23
29
|
exit?: {
|
|
@@ -133,3 +139,13 @@ export declare function explain(error: unknown, trace: Trace, context: ExplainCo
|
|
|
133
139
|
export declare function ignoredProxy(env?: NodeJS.ProcessEnv, host?: string): string | undefined;
|
|
134
140
|
/** What to do about an ignored proxy, for this Node. */
|
|
135
141
|
export declare function proxyAdvice(proxy: string, version?: string): string;
|
|
142
|
+
/**
|
|
143
|
+
* The server redirected to another origin. The MCP TypeScript SDK follows a redirect
|
|
144
|
+
* only within the request's origin since 2.3 (before, it re-sent custom headers,
|
|
145
|
+
* credentials included, wherever a redirect pointed). Other clients may still follow it.
|
|
146
|
+
*/
|
|
147
|
+
export declare function redirectError(r: {
|
|
148
|
+
from: string;
|
|
149
|
+
to: string;
|
|
150
|
+
status: number;
|
|
151
|
+
}, cause?: unknown): ConnectError;
|
package/dist/explain.js
CHANGED
|
@@ -11,6 +11,8 @@ export class Trace {
|
|
|
11
11
|
answered = new Set();
|
|
12
12
|
/** HTTP: the last response to each method (status, content type, final URL). */
|
|
13
13
|
http = new Map();
|
|
14
|
+
/** HTTP: a redirect to another origin, which the MCP SDK (2.3 and later) doesn't follow. */
|
|
15
|
+
redirect;
|
|
14
16
|
process;
|
|
15
17
|
/** How the process ended. `afterStop`: it ended after toolmenu sent it SIGTERM, so the exit may be toolmenu's doing. */
|
|
16
18
|
exit;
|
|
@@ -319,6 +321,10 @@ export function bodyExcerpt(body, max = 100) {
|
|
|
319
321
|
export function explain(error, trace, context) {
|
|
320
322
|
if (error instanceof ConnectError || !(error instanceof Error))
|
|
321
323
|
return error;
|
|
324
|
+
// Whatever the SDK made of it (a transport error, or a probe that waited for a reply):
|
|
325
|
+
// the server sent the request to another origin, and nothing past that was tried.
|
|
326
|
+
if (trace.redirect)
|
|
327
|
+
return redirectError(trace.redirect, error);
|
|
322
328
|
// A stored OAuth login that can't be used already says why, and what to run.
|
|
323
329
|
const login = causes(error).find((e) => e instanceof LoginNeededError);
|
|
324
330
|
if (login)
|
|
@@ -618,3 +624,11 @@ function explainHttp(error, trace, context, target) {
|
|
|
618
624
|
}
|
|
619
625
|
return error;
|
|
620
626
|
}
|
|
627
|
+
/**
|
|
628
|
+
* The server redirected to another origin. The MCP TypeScript SDK follows a redirect
|
|
629
|
+
* only within the request's origin since 2.3 (before, it re-sent custom headers,
|
|
630
|
+
* credentials included, wherever a redirect pointed). Other clients may still follow it.
|
|
631
|
+
*/
|
|
632
|
+
export function redirectError(r, cause) {
|
|
633
|
+
return new ConnectError(`The server redirects to another origin (HTTP ${r.status}). toolmenu doesn't follow it, and neither do clients built on the MCP TypeScript SDK 2.3 or later (they won't re-send headers or credentials to another host).`, [['url', r.from], ['redirects to', r.to]], `Check with the URL it redirects to: toolmenu snapshot ${r.to}. If it's your server, give clients that URL: those on the TypeScript SDK can't reach the old one.`, 'server/discover', { cause, status: r.status });
|
|
634
|
+
}
|
package/dist/failures.d.ts
CHANGED
|
@@ -73,14 +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
|
+
}
|
|
76
86
|
/**
|
|
77
|
-
* A result not marked isError whose content is an HTTP
|
|
78
|
-
*
|
|
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
|
|
79
89
|
* answer. Notion's server returns `{"status":401,"object":"error","code":"unauthorized"}`
|
|
80
90
|
* as a plain result. Only a JSON object whose own status or code says so counts, not
|
|
81
|
-
* "401" anywhere in the data
|
|
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.)
|
|
82
95
|
*/
|
|
83
|
-
export declare function
|
|
96
|
+
export declare function structuredError(result: {
|
|
84
97
|
content?: unknown;
|
|
85
98
|
structuredContent?: unknown;
|
|
86
|
-
}):
|
|
99
|
+
}): StructuredError | undefined;
|
package/dist/failures.js
CHANGED
|
@@ -207,21 +207,23 @@ 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
215
|
const DENIED_CODES = /^(?:unauthori[sz]ed|unauthenticated|forbidden|invalid_auth|invalid_token|not_authed|authentication_(?:required|failed)|permission_denied)$/i;
|
|
216
216
|
/**
|
|
217
|
-
* A result not marked isError whose content is an HTTP
|
|
218
|
-
*
|
|
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
219
|
* answer. Notion's server returns `{"status":401,"object":"error","code":"unauthorized"}`
|
|
220
220
|
* as a plain result. Only a JSON object whose own status or code says so counts, not
|
|
221
|
-
* "401" anywhere in the data
|
|
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.)
|
|
222
225
|
*/
|
|
223
|
-
export function
|
|
224
|
-
// (A tool that fetches a URL is skipped by the caller: its answer is the page's.)
|
|
226
|
+
export function structuredError(result) {
|
|
225
227
|
const objects = [result.structuredContent];
|
|
226
228
|
for (const c of Array.isArray(result.content) ? result.content : []) {
|
|
227
229
|
const text = c && typeof c === 'object' && 'text' in c && typeof c.text === 'string' ? c.text.trim() : '';
|
|
@@ -234,6 +236,11 @@ export function deniedAnswer(result) {
|
|
|
234
236
|
// not JSON
|
|
235
237
|
}
|
|
236
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;
|
|
237
244
|
for (const o of objects) {
|
|
238
245
|
if (!o || typeof o !== 'object' || Array.isArray(o))
|
|
239
246
|
continue;
|
|
@@ -241,16 +248,24 @@ export function deniedAnswer(result) {
|
|
|
241
248
|
if (!v || typeof v !== 'object' || Array.isArray(v))
|
|
242
249
|
continue;
|
|
243
250
|
const r = v;
|
|
244
|
-
const status = [r.status, r.statusCode, r.status_code, r.code].find((x) => x
|
|
251
|
+
const status = [r.status, r.statusCode, r.status_code, r.code].map(errorStatus).find((x) => x !== undefined);
|
|
245
252
|
const code = [r.code, r.error, r.type].find((x) => typeof x === 'string' && DENIED_CODES.test(x));
|
|
246
|
-
// A status alone may be what the tool was asked to fetch ({"status":403,"body":…});
|
|
247
|
-
// with it, the object has to say it's an error.
|
|
248
253
|
const isError = v !== o || r.object === 'error' || ![undefined, null, false, '', 0].includes(r.error) || typeof r.message === 'string';
|
|
249
254
|
if (code === undefined && (status === undefined || !isError))
|
|
250
255
|
continue;
|
|
251
|
-
const message = typeof r.message === 'string' ?
|
|
252
|
-
|
|
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;
|
|
253
268
|
}
|
|
254
269
|
}
|
|
255
|
-
return
|
|
270
|
+
return first;
|
|
256
271
|
}
|
package/dist/help.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export declare const COMMANDS: readonly ['init', 'snapshot', 'diff', 'session', 'history', 'auth', 'scan', 'explain'];
|
|
1
|
+
export declare const COMMANDS: readonly ['init', 'snapshot', 'diff', 'session', 'history', 'auth', 'scan', 'explain', 'mcp'];
|
|
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', 'scan', 'explain'];
|
|
7
|
+
export const COMMANDS = ['init', 'snapshot', 'diff', 'session', 'history', 'auth', 'scan', 'explain', 'mcp'];
|
|
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)']],
|
|
@@ -53,6 +53,7 @@ const OPTIONS = {
|
|
|
53
53
|
'init-out': ['--out <path>', ['where to write the baseline menu (default: menu.json)']],
|
|
54
54
|
'with-session': ['--with-session', ['the workflow also runs session --auto (calls read-only tools)']],
|
|
55
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']],
|
|
56
57
|
concurrency: ['--concurrency <n>', ['servers checked at a time (default: 4)']],
|
|
57
58
|
'out-dir': ['--out-dir <dir>', ["write each server's menu file there, as <name>.json (default: none)"]],
|
|
58
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)']],
|
|
@@ -84,7 +85,7 @@ const HELP = {
|
|
|
84
85
|
'reports what in the menu confuses agents or breaks prompt caches.',
|
|
85
86
|
SERVER_NOTE,
|
|
86
87
|
],
|
|
87
|
-
own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists'],
|
|
88
|
+
own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists', 'offline-check'],
|
|
88
89
|
shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
|
|
89
90
|
examples: [
|
|
90
91
|
'toolmenu snapshot -- npx -y @modelcontextprotocol/server-memory',
|
|
@@ -168,7 +169,7 @@ const HELP = {
|
|
|
168
169
|
'started or read is a row that says why, and makes the exit code 2: it was not checked.',
|
|
169
170
|
],
|
|
170
171
|
own: ['concurrency', 'out-dir'],
|
|
171
|
-
shared: ['config', 'format', 'json', 'fail-on', 'protocol', 'timeout', 'processes'],
|
|
172
|
+
shared: ['config', 'format', 'json', 'fail-on', 'no-auth', 'protocol', 'timeout', 'processes'],
|
|
172
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'],
|
|
173
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"],
|
|
174
175
|
},
|
|
@@ -184,6 +185,20 @@ const HELP = {
|
|
|
184
185
|
examples: ['toolmenu explain naming/vague-id', 'toolmenu explain handle-lifetime', 'toolmenu explain --json diff/param-required'],
|
|
185
186
|
exits: ['0 explained', "2 no such rule (the closest ones are named), or bad usage"],
|
|
186
187
|
},
|
|
188
|
+
mcp: {
|
|
189
|
+
summary: 'serve toolmenu to an agent as an MCP server (stdio)',
|
|
190
|
+
usage: ['toolmenu mcp'],
|
|
191
|
+
about: [
|
|
192
|
+
'An MCP server over stdio, for the agent building your server: snapshot_menu, diff_menus,',
|
|
193
|
+
'check_session and explain_rule, each running the matching command. Relative paths and',
|
|
194
|
+
'toolmenu.config.json resolve from the folder it runs in, or a tool call\'s cwd.',
|
|
195
|
+
'Claude Code: claude mcp add toolmenu -- npx -y toolmenu mcp',
|
|
196
|
+
],
|
|
197
|
+
own: [],
|
|
198
|
+
shared: [],
|
|
199
|
+
examples: ['claude mcp add toolmenu -- npx -y toolmenu mcp', '{"mcpServers": {"toolmenu": {"command": "npx", "args": ["-y", "toolmenu", "mcp"]}}}'],
|
|
200
|
+
exits: ['0 the client closed the connection', '2 bad usage'],
|
|
201
|
+
},
|
|
187
202
|
};
|
|
188
203
|
function optionLines(keys) {
|
|
189
204
|
const width = Math.max(...keys.map((k) => OPTIONS[k][0].length)) + 2;
|