toolmenu 0.14.1 → 0.16.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 +6 -2
- package/dist/breakdown.js +25 -7
- package/dist/catalog.js +4 -0
- package/dist/cli.js +10 -3
- package/dist/connect.d.ts +5 -5
- package/dist/connect.js +26 -1
- package/dist/diff.js +20 -0
- package/dist/explain.d.ts +8 -0
- package/dist/explain.js +51 -7
- package/dist/failures.d.ts +1 -1
- package/dist/failures.js +19 -6
- package/dist/help.js +2 -1
- package/dist/mrtr.d.ts +41 -0
- package/dist/mrtr.js +95 -0
- package/dist/options.d.ts +3 -0
- package/dist/options.js +1 -0
- package/dist/rules/gated.js +4 -1
- package/dist/rules/headers.d.ts +14 -0
- package/dist/rules/headers.js +116 -0
- package/dist/rules/ids.js +2 -1
- package/dist/rules/index.js +6 -0
- package/dist/rules/refs.d.ts +15 -0
- package/dist/rules/refs.js +125 -0
- package/dist/rules/search.d.ts +2 -0
- package/dist/rules/search.js +70 -0
- package/dist/search.d.ts +24 -0
- package/dist/search.js +86 -0
- package/dist/session.d.ts +9 -1
- package/dist/session.js +184 -24
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -20,6 +20,10 @@ connections and releases, and checks **when** it changes:
|
|
|
20
20
|
- **Ready for 2026-07-28.** That protocol version says the tool set **must not** vary
|
|
21
21
|
per connection or as a side effect of other requests (the 2025 versions allow it).
|
|
22
22
|
Per-session "unlock" designs, like the one I built, are ruled out. `session` tells you whether yours is one of them.
|
|
23
|
+
It also checks the menu clients will actually show: a broken `x-mcp-header` or a
|
|
24
|
+
`$ref` they can't resolve hides a tool or fails every call to it. And when a tool
|
|
25
|
+
stops to ask the user something, `session` answers "no" and says whether the tool
|
|
26
|
+
can take it.
|
|
23
27
|
- **Between releases.** `diff` finds breaking changes and token growth, and checks
|
|
24
28
|
the version bump.
|
|
25
29
|
|
|
@@ -29,7 +33,7 @@ No LLM anywhere: the same inputs give the same answer, so it can sit in CI.
|
|
|
29
33
|
(`history` installs old versions with today's dependencies, so it records what they
|
|
30
34
|
serve now, which can differ from what they shipped with: FINDINGS F4.)
|
|
31
35
|
|
|
32
|
-
> **Status: 0.
|
|
36
|
+
> **Status: 0.16, early.** Spec in [docs/SPEC.md](https://github.com/niksa90/toolmenu/blob/main/docs/SPEC.md). What it has found on
|
|
33
37
|
> real servers: [docs/FINDINGS.md](https://github.com/niksa90/toolmenu/blob/main/docs/FINDINGS.md).
|
|
34
38
|
|
|
35
39
|
## Start here
|
|
@@ -104,7 +108,7 @@ jobs:
|
|
|
104
108
|
- uses: actions/setup-node@v7
|
|
105
109
|
with: { node-version: 22 }
|
|
106
110
|
- run: npm ci && npm run build
|
|
107
|
-
- uses: niksa90/toolmenu@v0.
|
|
111
|
+
- uses: niksa90/toolmenu@v0.16.0
|
|
108
112
|
with:
|
|
109
113
|
command: node dist/server.js
|
|
110
114
|
baseline: menu.json # your committed snapshot
|
package/dist/breakdown.js
CHANGED
|
@@ -43,15 +43,33 @@ function unusedDefs(menu) {
|
|
|
43
43
|
const { $defs: _d, definitions: _df, ...rest } = schema;
|
|
44
44
|
const used = new Set();
|
|
45
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
|
+
};
|
|
46
65
|
while (queue.length) {
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
continue;
|
|
51
|
-
used.add(id);
|
|
52
|
-
const [pool, name] = [m[1], id.slice(m[1].length + 1)];
|
|
53
|
-
queue.push(JSON.stringify(schema[pool][name] ?? {}));
|
|
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, '~'));
|
|
54
69
|
}
|
|
70
|
+
for (const m of text.matchAll(/"\$(?:dynamic)?[rR]ef"\s*:\s*"([^"]*)"/g))
|
|
71
|
+
if (!m[1].startsWith('#/'))
|
|
72
|
+
named(m[1]);
|
|
55
73
|
}
|
|
56
74
|
let unused = 0;
|
|
57
75
|
for (const pool of pools) {
|
package/dist/catalog.js
CHANGED
|
@@ -305,6 +305,10 @@ const FAILED_AS = {
|
|
|
305
305
|
what: ['answered "not found"', 'answered "not found"'],
|
|
306
306
|
fix: 'Check the server is set up for this account or site, then rerun.',
|
|
307
307
|
},
|
|
308
|
+
client: {
|
|
309
|
+
what: ["asked the client for something toolmenu doesn't offer (roots or sampling)", "asked the client for something toolmenu doesn't offer (roots or sampling)"],
|
|
310
|
+
fix: "Nothing to fix in the server: toolmenu doesn't answer roots or sampling requests, so it can't list these routers' commands.",
|
|
311
|
+
},
|
|
308
312
|
'invalid-arguments': {
|
|
309
313
|
what: ["rejected the listing call's arguments", "rejected the listing call's arguments"],
|
|
310
314
|
fix: "Read the router's own words above; if it lists its commands another way, name the right tool in catalog.tool or catalog.routers.",
|
package/dist/cli.js
CHANGED
|
@@ -3,7 +3,7 @@ import { writeFile } from 'node:fs/promises';
|
|
|
3
3
|
import { join } from 'node:path';
|
|
4
4
|
import { parseArgs } from 'node:util';
|
|
5
5
|
import { loadConfig } from './config.js';
|
|
6
|
-
import { PROTOCOLS } from './connect.js';
|
|
6
|
+
import { ELICITATIONS, PROTOCOLS } from './connect.js';
|
|
7
7
|
import { diffMenus } from './diff.js';
|
|
8
8
|
import { loadMenu } from './menu.js';
|
|
9
9
|
import { history, historyCsv } from './history.js';
|
|
@@ -79,6 +79,13 @@ export async function main(argv) {
|
|
|
79
79
|
const protocol = (values.protocol ?? config.protocol ?? 'auto');
|
|
80
80
|
if (!PROTOCOLS.includes(protocol))
|
|
81
81
|
throw new UsageError(`--protocol must be auto, legacy or modern`);
|
|
82
|
+
const elicitation = (values.elicitation ?? 'decline');
|
|
83
|
+
if (!ELICITATIONS.includes(elicitation))
|
|
84
|
+
throw new UsageError('--elicitation must be decline or cancel');
|
|
85
|
+
if (values.elicitation !== undefined && sub !== 'session')
|
|
86
|
+
throw new UsageError('--elicitation goes with session: only session calls tools.');
|
|
87
|
+
// Only session calls tools, so only its target says how to answer their questions.
|
|
88
|
+
const answering = (t) => (elicitation === 'decline' ? t : { ...t, elicitation });
|
|
82
89
|
const processes = values.processes !== undefined ? Number(values.processes) : config.processes ?? 2;
|
|
83
90
|
if (!Number.isInteger(processes) || processes < 1)
|
|
84
91
|
throw new UsageError('--processes must be a whole number, 1 or more');
|
|
@@ -203,7 +210,7 @@ export async function main(argv) {
|
|
|
203
210
|
catch (error) {
|
|
204
211
|
throw new UsageError(error instanceof Error ? error.message : String(error));
|
|
205
212
|
}
|
|
206
|
-
const autoTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
|
|
213
|
+
const autoTarget = answering(parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol));
|
|
207
214
|
const waited = { ms: 0 };
|
|
208
215
|
const menu = await probeMenu(seeded(autoTarget, MAIN_SEED), timeoutMs, undefined, waited).catch((error) => {
|
|
209
216
|
throw refusedForTooMany(error, waited.ms);
|
|
@@ -278,7 +285,7 @@ export async function main(argv) {
|
|
|
278
285
|
process.stdout.write(formatPlan(scenario, values.scenario) + '\n');
|
|
279
286
|
return 0;
|
|
280
287
|
}
|
|
281
|
-
const sessionTarget = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
|
|
288
|
+
const sessionTarget = answering(parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol));
|
|
282
289
|
const result = await session(sessionTarget, scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: values.scenario, unionOut: !!values['union-out'] });
|
|
283
290
|
if (values['union-out'])
|
|
284
291
|
await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
|
package/dist/connect.d.ts
CHANGED
|
@@ -1,14 +1,12 @@
|
|
|
1
1
|
import { Client } from '@modelcontextprotocol/client';
|
|
2
2
|
import type { Transport } from '@modelcontextprotocol/client';
|
|
3
3
|
import type { Era } from './types.js';
|
|
4
|
-
/**
|
|
5
|
-
* Which handshake to make. auto: try the 2026-07-28 `server/discover` first and fall back
|
|
6
|
-
* to the 2025 one. legacy: the 2025 handshake only. modern: 2026-07-28 only, an error if
|
|
7
|
-
* the server can't speak it.
|
|
8
|
-
*/
|
|
9
4
|
export type Protocol = 'auto' | 'legacy' | 'modern';
|
|
10
5
|
export declare const PROTOCOLS: readonly Protocol[];
|
|
11
6
|
export declare const MODERN_VERSION = "2026-07-28";
|
|
7
|
+
/** How toolmenu answers every elicitation: the user said no, or dismissed it. Never accept: that needs values, and an LLM or a person to pick them. */
|
|
8
|
+
export type Elicitation = 'decline' | 'cancel';
|
|
9
|
+
export declare const ELICITATIONS: readonly Elicitation[];
|
|
12
10
|
export type Target = {
|
|
13
11
|
kind: 'stdio';
|
|
14
12
|
command: string;
|
|
@@ -16,12 +14,14 @@ export type Target = {
|
|
|
16
14
|
env?: Record<string, string>;
|
|
17
15
|
cwd?: string;
|
|
18
16
|
protocol?: Protocol;
|
|
17
|
+
elicitation?: Elicitation;
|
|
19
18
|
} | {
|
|
20
19
|
kind: 'http';
|
|
21
20
|
url: string;
|
|
22
21
|
headers?: Record<string, string>;
|
|
23
22
|
noAuth?: boolean;
|
|
24
23
|
protocol?: Protocol;
|
|
24
|
+
elicitation?: Elicitation;
|
|
25
25
|
};
|
|
26
26
|
export interface WireResponse {
|
|
27
27
|
method: string;
|
package/dist/connect.js
CHANGED
|
@@ -5,8 +5,23 @@ import { explain, isCredentialHeader, 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';
|
|
8
|
+
/**
|
|
9
|
+
* Which handshake to make. auto: try the 2026-07-28 `server/discover` first and fall back
|
|
10
|
+
* to the 2025 one. legacy: the 2025 handshake only. modern: 2026-07-28 only, an error if
|
|
11
|
+
* the server can't speak it.
|
|
12
|
+
*/
|
|
13
|
+
// The SDK client drops a tool with an invalid x-mcp-header from its own tools/list
|
|
14
|
+
// and console.warns about it, once per list. toolmenu reads the list off the wire
|
|
15
|
+
// and reports those tools as spec/x-mcp-header findings, so the warning is noise.
|
|
16
|
+
const sdkWarn = console.warn.bind(console);
|
|
17
|
+
console.warn = (...args) => {
|
|
18
|
+
if (typeof args[0] === 'string' && args[0].startsWith('[mcp-sdk] excluding tool '))
|
|
19
|
+
return;
|
|
20
|
+
sdkWarn(...args);
|
|
21
|
+
};
|
|
8
22
|
export const PROTOCOLS = ['auto', 'legacy', 'modern'];
|
|
9
23
|
export const MODERN_VERSION = '2026-07-28';
|
|
24
|
+
export const ELICITATIONS = ['decline', 'cancel'];
|
|
10
25
|
/** Every response the server sent, matched to the request method, as it came off the wire. */
|
|
11
26
|
export class WireLog {
|
|
12
27
|
responses = [];
|
|
@@ -50,7 +65,17 @@ export class WireLog {
|
|
|
50
65
|
}
|
|
51
66
|
}
|
|
52
67
|
export async function connect(target, options = {}) {
|
|
53
|
-
const client = new Client({ name: 'toolmenu', version: VERSION }, {
|
|
68
|
+
const client = new Client({ name: 'toolmenu', version: VERSION }, {
|
|
69
|
+
versionNegotiation: { mode: target.protocol === 'legacy' ? 'legacy' : target.protocol === 'modern' ? { pin: MODERN_VERSION } : 'auto' },
|
|
70
|
+
// Elicitation, form and URL mode, so a tool that asks the user something runs
|
|
71
|
+
// its "the user said no" path instead of failing (2026-07-28 multi round-trip
|
|
72
|
+
// requests). Every request is answered the same way, with no LLM: see ELICITATION.
|
|
73
|
+
// Not roots or sampling: 2026-07-28 deprecates them (SEP-2577).
|
|
74
|
+
capabilities: { elicitation: { form: {}, url: {} } },
|
|
75
|
+
});
|
|
76
|
+
// A 2025 server asks with an elicitation/create request; 2026-07-28 ones embed it
|
|
77
|
+
// in an input_required result, which session answers itself (mrtr.ts). Same answer.
|
|
78
|
+
client.setRequestHandler('elicitation/create', async () => ({ action: target.elicitation ?? 'decline' }));
|
|
54
79
|
let transport;
|
|
55
80
|
let stderrText = '';
|
|
56
81
|
let oauth = false;
|
package/dist/diff.js
CHANGED
|
@@ -21,6 +21,10 @@ export const DIFF_RULES = {
|
|
|
21
21
|
'diff/param-dropped': { severity: 'info', class: 'notice' },
|
|
22
22
|
'diff/schema-other': { severity: 'info', class: 'notice' },
|
|
23
23
|
'diff/param-default': { severity: 'info', class: 'notice' },
|
|
24
|
+
// x-mcp-header (2026-07-28): a parameter mirrored into an Mcp-Param-* HTTP header,
|
|
25
|
+
// added, removed or renamed. Callers don't change; proxies and WAFs routing on the
|
|
26
|
+
// header do.
|
|
27
|
+
'diff/x-mcp-header': { severity: 'info', class: 'notice' },
|
|
24
28
|
// Restructured ($ref, $defs) but accepts the same input: bytes and tokens changed.
|
|
25
29
|
'diff/schema-equivalent': { severity: 'info', class: 'notice' },
|
|
26
30
|
// Only the declared $schema dialect changed: one finding for the menu.
|
|
@@ -813,9 +817,25 @@ function compareSchema(w, at, before, after, depth) {
|
|
|
813
817
|
fix: 'If the default is built from the clock or the environment, give a fixed one or none, and say in the description what an absent value means.',
|
|
814
818
|
});
|
|
815
819
|
}
|
|
820
|
+
// A header the parameter is mirrored into: who routes on it changes, not the call.
|
|
821
|
+
const [ha, hb] = [before['x-mcp-header'], after['x-mcp-header']];
|
|
822
|
+
if (canonical(ha) !== canonical(hb)) {
|
|
823
|
+
const header = (v) => `Mcp-Param-${String(v)}`;
|
|
824
|
+
const [head, tail] = ha === undefined
|
|
825
|
+
? [`: now mirrored into the ${header(hb)} HTTP header`, 'Proxies, load balancers and WAFs can route on it from this release.']
|
|
826
|
+
: hb === undefined
|
|
827
|
+
? [`: no longer mirrored into the ${header(ha)} HTTP header`, 'Anything that routes on that header stops seeing it.']
|
|
828
|
+
: [`: its HTTP header was renamed, ${header(ha)} → ${header(hb)}`, 'Routing rules that match the old header stop matching.'];
|
|
829
|
+
say(w, 'diff/x-mcp-header', at, head, tail, [before, after], {
|
|
830
|
+
...(ha === undefined
|
|
831
|
+
? {}
|
|
832
|
+
: { fix: hb === undefined ? `If a proxy, load balancer or WAF rule matches ${header(ha)}, change it before this release ships.` : `Update proxy, load balancer and WAF rules from ${header(ha)} to ${header(hb)} when this release ships.` }),
|
|
833
|
+
});
|
|
834
|
+
}
|
|
816
835
|
const rest = (s) => {
|
|
817
836
|
const r = residual(s, { object, items: arrays, union });
|
|
818
837
|
delete r.default;
|
|
838
|
+
delete r['x-mcp-header'];
|
|
819
839
|
return r;
|
|
820
840
|
};
|
|
821
841
|
if ((union || oldType === newType || accepts(after, before)) && canonical(rest(before)) !== canonical(rest(after))) {
|
package/dist/explain.d.ts
CHANGED
|
@@ -32,6 +32,8 @@ export declare class Trace {
|
|
|
32
32
|
/** stdout lines that aren't JSON-RPC: the first few, and how many in all. */
|
|
33
33
|
readonly stray: string[];
|
|
34
34
|
strayCount: number;
|
|
35
|
+
/** The first stray stdout lines, more of them than are shown: a CLI's usage runs long. */
|
|
36
|
+
readonly strayHead: string[];
|
|
35
37
|
private stdoutPartial;
|
|
36
38
|
/** The last stderr lines, and how many there were in all. */
|
|
37
39
|
readonly stderrTail: string[];
|
|
@@ -78,6 +80,12 @@ export declare function seconds(ms: number): string;
|
|
|
78
80
|
export declare function commandLine(command: string, args: string[]): string;
|
|
79
81
|
/** The stderr fact: the last lines, and a note of how many came before. */
|
|
80
82
|
export declare function stderrFact(trace: Trace): [string, string];
|
|
83
|
+
/**
|
|
84
|
+
* 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, or a server that opened an
|
|
86
|
+
* HTTP port instead of talking on stdio. Undefined when it says neither.
|
|
87
|
+
*/
|
|
88
|
+
export declare function startupHint(trace: Trace, command: string): string | undefined;
|
|
81
89
|
/** A request header that carries credentials: Authorization, a cookie, or a name with key, token, secret or auth in it (x-mcp-api-key). */
|
|
82
90
|
export declare function isCredentialHeader(name: string): boolean;
|
|
83
91
|
/**
|
package/dist/explain.js
CHANGED
|
@@ -21,6 +21,8 @@ export class Trace {
|
|
|
21
21
|
/** stdout lines that aren't JSON-RPC: the first few, and how many in all. */
|
|
22
22
|
stray = [];
|
|
23
23
|
strayCount = 0;
|
|
24
|
+
/** The first stray stdout lines, more of them than are shown: a CLI's usage runs long. */
|
|
25
|
+
strayHead = [];
|
|
24
26
|
stdoutPartial = '';
|
|
25
27
|
/** The last stderr lines, and how many there were in all. */
|
|
26
28
|
stderrTail = [];
|
|
@@ -48,6 +50,8 @@ export class Trace {
|
|
|
48
50
|
this.strayCount++;
|
|
49
51
|
if (this.stray.length < 2)
|
|
50
52
|
this.stray.push(clean(line, 160));
|
|
53
|
+
if (this.strayHead.length < 60)
|
|
54
|
+
this.strayHead.push(clean(line, 240));
|
|
51
55
|
}
|
|
52
56
|
}
|
|
53
57
|
stderr(chunk) {
|
|
@@ -144,6 +148,39 @@ function strayFact(trace) {
|
|
|
144
148
|
return ['stdout', `${quoted}${more}`];
|
|
145
149
|
}
|
|
146
150
|
const LOG_TO_STDERR = 'Log to stderr; stdout carries the protocol (in Node, console.error rather than console.log; in Python, logging or print(..., file=sys.stderr)).';
|
|
151
|
+
// A CLI's usage: argparse, click, yargs, commander, System.CommandLine, stricli.
|
|
152
|
+
const USAGE = /(?:^|\n)\s*(?:usage|(?:sub)?commands|options|examples|flags):|\bUSAGE\b|\s<command>|\[command\]|\bCOMMAND \[ARGS\]|arguments are required|subcommands? must be present|no command (?:specified|given)|required command was not provided|\b(?:run|see):? \S+ --help\b/i;
|
|
153
|
+
// A table of commands or options, two or more rows: " t3-watch start Run the service",
|
|
154
|
+
// " --version Show version number". Help output, even without a "Usage:" line.
|
|
155
|
+
const HELP_ROWS = /(?:^|\n)\s*(?:[\w.-]+ [\w-]+|-{1,2}[\w-]+(?:, -{1,2}[\w-]+)?) {2,}\S[^\n]*\n\s*(?:[\w.-]+ [\w-]+|-{1,2}[\w-]+(?:, -{1,2}[\w-]+)?) {2,}\S/;
|
|
156
|
+
// The subcommands that usually start the MCP server, most specific first. A word
|
|
157
|
+
// on its own ({mcp}, " mcp Start…", "mcp start [--transport…]"), not part of a
|
|
158
|
+
// name like agentation-mcp.
|
|
159
|
+
const SUBCOMMANDS = ['mcp start', 'mcp serve', 'server start', 'mcp', 'stdio', 'serve', 'server', 'start'];
|
|
160
|
+
// An HTTP server's address in its log: "MCP server listening on http://localhost:3001/mcp",
|
|
161
|
+
// "StreamableHTTP endpoint available at http://127.0.0.1:3333/mcp".
|
|
162
|
+
const HTTP_URL = /\b(?:listening|available|running|serving|started)\b[^\n]{0,60}?(https?:\/\/[^\s"'<>]+)/i;
|
|
163
|
+
const HTTP_PORT = /\blistening on (?:port )?:?(\d{2,5})\b/i;
|
|
164
|
+
/**
|
|
165
|
+
* What the server's own output says about how it was started, as a next step: a
|
|
166
|
+
* CLI that printed its usage and wants a subcommand, or a server that opened an
|
|
167
|
+
* HTTP port instead of talking on stdio. Undefined when it says neither.
|
|
168
|
+
*/
|
|
169
|
+
export function startupHint(trace, command) {
|
|
170
|
+
const text = [...trace.strayHead, ...trace.stderrExcerpt().lines].join('\n');
|
|
171
|
+
const url = HTTP_URL.exec(text)?.[1]?.replace(/[.,;)]+$/, '').replace('//0.0.0.0', '//localhost');
|
|
172
|
+
const port = url ? undefined : HTTP_PORT.exec(text)?.[1];
|
|
173
|
+
if (url || port) {
|
|
174
|
+
const flag = /--stdio\b/.test(text) ? '--stdio' : /--transport[ =]?(?:\[?stdio|<)/i.test(text) ? '--transport stdio' : undefined;
|
|
175
|
+
const where = url ?? `http://localhost:${port}/mcp`;
|
|
176
|
+
return `The server started an HTTP server (${where}) instead of talking on its stdin and stdout. Start it in stdio mode (${flag ? `its output mentions ${flag}` : 'often --stdio or --transport stdio'}), or run toolmenu against the address while the server runs: toolmenu snapshot ${where}`;
|
|
177
|
+
}
|
|
178
|
+
if (USAGE.test(text) || HELP_ROWS.test(text)) {
|
|
179
|
+
const sub = SUBCOMMANDS.find((c) => new RegExp(`(?:^|[\\s{,|\\[])${c.replace(' ', '\\s+')}(?=[\\s},|\\]]|$)`, 'm').test(text));
|
|
180
|
+
return `The command printed its usage and exited: it wants a subcommand or an argument it wasn't given. ${sub ? `Its usage lists “${sub}”: try ${command} ${sub}` : 'Its usage (above) or its docs say what starts the MCP server: add that after the command.'}`;
|
|
181
|
+
}
|
|
182
|
+
return undefined;
|
|
183
|
+
}
|
|
147
184
|
/** The error codes along an error's cause chain, innermost last. */
|
|
148
185
|
function causes(error) {
|
|
149
186
|
const out = [];
|
|
@@ -286,12 +323,16 @@ function explainStdio(error, trace, context, target) {
|
|
|
286
323
|
const stderrText = trace.stderrExcerpt().lines.join('\n');
|
|
287
324
|
const rejected = rejectedCredentials(stderrText);
|
|
288
325
|
let next;
|
|
326
|
+
let hint;
|
|
289
327
|
if (/cannot find (module|package)|ERR_MODULE_NOT_FOUND|ModuleNotFoundError|No module named/i.test(stderrText)) {
|
|
290
328
|
next = "The server is missing one of its own dependencies (see stderr): reinstall it, or try another version. It's a packaging problem, not your setup.";
|
|
291
329
|
}
|
|
292
330
|
else if (rejected) {
|
|
293
331
|
next = REJECTED_NEXT;
|
|
294
332
|
}
|
|
333
|
+
else if ((hint = startupHint(trace, command))) {
|
|
334
|
+
next = hint;
|
|
335
|
+
}
|
|
295
336
|
else if (trace.strayCount) {
|
|
296
337
|
next = `${LOG_TO_STDERR} Then fix what stderr says.`;
|
|
297
338
|
}
|
|
@@ -329,13 +370,16 @@ function explainStdio(error, trace, context, target) {
|
|
|
329
370
|
: rejected
|
|
330
371
|
? `${stage} timed out after ${seconds(waitedHere)}: the server is running but never answered; its stderr looks like rejected credentials (“${rejected}”).`
|
|
331
372
|
: `${stage} timed out after ${seconds(waitedHere)}: the server is running but never answered.`;
|
|
332
|
-
const
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
373
|
+
const hint = startupHint(trace, command);
|
|
374
|
+
const next = hint
|
|
375
|
+
? hint
|
|
376
|
+
: trace.strayCount
|
|
377
|
+
? LOG_TO_STDERR
|
|
378
|
+
: rejected
|
|
379
|
+
? REJECTED_NEXT
|
|
380
|
+
: stage === 'tools/list'
|
|
381
|
+
? 'The server answered initialize, then hung on tools/list: check its logs (stderr above). If building the list is just slow, raise --timeout.'
|
|
382
|
+
: 'Check the command starts an MCP server on stdio (some need an argument such as "stdio" or "--stdio"). If it is only slow to start (npx downloading, a first build), raise --timeout.';
|
|
339
383
|
return new ConnectError(headline, facts, next, stage, { cause: error });
|
|
340
384
|
}
|
|
341
385
|
// Anything else: the transport's words, with what the server said.
|
package/dist/failures.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export type FailureClass = 'auth' | 'environment' | 'network' | 'not-found' | 'invalid-arguments' | 'other';
|
|
1
|
+
export type FailureClass = 'auth' | 'environment' | 'network' | 'not-found' | 'client' | 'invalid-arguments' | 'other';
|
|
2
2
|
/** Failures of the setup (credentials, this machine, the network), not of the server. */
|
|
3
3
|
export declare const SETUP_FAILURES: Set<FailureClass>;
|
|
4
4
|
/**
|
package/dist/failures.js
CHANGED
|
@@ -5,16 +5,23 @@
|
|
|
5
5
|
* as a finding.
|
|
6
6
|
*/
|
|
7
7
|
/** Failures of the setup (credentials, this machine, the network), not of the server. */
|
|
8
|
-
export const SETUP_FAILURES = new Set(['auth', 'environment', 'network', 'not-found']);
|
|
8
|
+
export const SETUP_FAILURES = new Set(['auth', 'environment', 'network', 'not-found', 'client']);
|
|
9
|
+
// A tool that asks the client for something toolmenu doesn't offer: "Cannot request
|
|
10
|
+
// input 'roots' (roots/list): the request's client capabilities do not declare the
|
|
11
|
+
// required capability" (server-everything's get-roots-list), sampling, elicitation.
|
|
12
|
+
const CLIENT = /client capabilit(?:y|ies)\b[^.]{0,60}\b(?:do(?:es)? not|don't|doesn't|lack|missing|without)\b|\b(?:roots|sampling|elicitation)\b[^.]{0,40}\bnot (?:supported|declared|available)\b[^.]{0,20}\bclient\b|client does not support (?:roots|sampling|elicitation)/i;
|
|
9
13
|
// Something this machine lacks: "Could not find Google Chrome executable"
|
|
10
|
-
// (Chrome DevTools), "Chromium distribution 'chrome' is not found at" (Playwright)
|
|
11
|
-
|
|
14
|
+
// (Chrome DevTools), "Chromium distribution 'chrome' is not found at" (Playwright),
|
|
15
|
+
// or the wrong operating system: "Editmamei runs on Windows and macOS; this process
|
|
16
|
+
// is on "linux"" (editmamei), "Unsupported platform: linux".
|
|
17
|
+
const ENVIRONMENT = /could not find [^.]{0,40}executable|is not found at \/|\bnot installed\b|command not found|cannot find (module|package)|\bENOENT\b|\bruns on [^.;]{0,40}; this (?:process|machine|system) is on\b|\b(?:unsupported|not supported on (?:this|the current)) (?:platform|operating system|OS)\b/i;
|
|
12
18
|
// "401 Bad credentials" (GitHub), "Authorization Expired" (Sentry), "Invalid
|
|
13
19
|
// token" (Firecrawl), "authentication token is not valid" (Apify), "Please provide
|
|
14
20
|
// a valid access token" (Supabase), "NetlifyUnauthError: You're not logged into
|
|
15
|
-
// Netlify" (Netlify), "The API key you provided was rejected" (Pinecone)
|
|
16
|
-
//
|
|
17
|
-
|
|
21
|
+
// Netlify" (Netlify), "The API key you provided was rejected" (Pinecone), "Admin
|
|
22
|
+
// auth is missing", "Runtime credentials are missing" (securenow). Not a bare
|
|
23
|
+
// "token": plenty of errors mention one.
|
|
24
|
+
const AUTH = /\b(?:auth|authentication|credentials?|api[ _-]?key|access token)\b (?:is |are )?missing\b|\b(401|403)\b|unauthori[sz]ed|unauth(enticated|error)|forbidden|bad credentials|authori[sz]ation expired|re-?authori[sz]e|not authenticated|not logged (?:in|into)\b(?! to the browser)|authentication (token|failed|required|error)|(invalid|expired|revoked) (api[ _-]?key|access token|token|credentials)|(token|api[ _-]?key|credentials) (is |are )?(not valid|invalid|expired)|(api[ _-]?key|access token|credentials)\b[^.]{0,30}\b(was|were|is|are) (rejected|refused|revoked)|valid (access )?token/i;
|
|
18
25
|
const NETWORK = /\b(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ECONNRESET|EHOSTUNREACH)\b|socket hang up|getaddrinfo|network error/i;
|
|
19
26
|
// "Either 'page_id' OR both 'title' and 'space_key' must be provided" (Atlassian),
|
|
20
27
|
// "**Input Error**" (Sentry), JSON-RPC's invalid params.
|
|
@@ -151,6 +158,9 @@ export async function patiently(request, options = {}) {
|
|
|
151
158
|
* with 404; a made-up Jira URL 404s), which is setup, not the server's fault.
|
|
152
159
|
*/
|
|
153
160
|
export function classifyFailure(text, options = {}) {
|
|
161
|
+
// 2026-07-28's MissingRequiredClientCapabilityError, by its code.
|
|
162
|
+
if (options.code === -32021 || CLIENT.test(text))
|
|
163
|
+
return 'client';
|
|
154
164
|
if (ENVIRONMENT.test(text))
|
|
155
165
|
return 'environment';
|
|
156
166
|
if (AUTH.test(text))
|
|
@@ -168,6 +178,7 @@ export const FAILURE_LABELS = {
|
|
|
168
178
|
environment: 'something missing on this machine',
|
|
169
179
|
network: 'the network',
|
|
170
180
|
'not-found': 'a 404 on a call that named nothing (usually the account or site behind the credentials)',
|
|
181
|
+
client: "a client feature toolmenu doesn't offer (roots or sampling)",
|
|
171
182
|
'invalid-arguments': 'the arguments',
|
|
172
183
|
other: 'other errors',
|
|
173
184
|
};
|
|
@@ -184,6 +195,8 @@ export function setupFailureAdvice(classes, transport) {
|
|
|
184
195
|
steps.push(`If the errors are about credentials, rerun with real ones (${credentials}); a test account is enough.`);
|
|
185
196
|
if (set.has('environment'))
|
|
186
197
|
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.');
|
|
198
|
+
if (set.has('client'))
|
|
199
|
+
steps.push("If a tool needs roots or sampling from the client, toolmenu doesn't provide them (2026-07-28 deprecates both): those calls only checked that the menu stays put, and the server isn't at fault.");
|
|
187
200
|
if (set.has('network'))
|
|
188
201
|
steps.push('If the server calls an upstream API, check this machine can reach it (DNS, proxy, firewall).');
|
|
189
202
|
return { fix: steps.join(' ') || 'Check the quoted errors: they came from before the tool ran.', confidence: 'unsure' };
|
package/dist/help.js
CHANGED
|
@@ -34,6 +34,7 @@ const OPTIONS = {
|
|
|
34
34
|
'values-file': ['--values-file <path>', ['with --auto, the same as a YAML/JSON map']],
|
|
35
35
|
'assume-read-only': ['--assume-read-only <tools>', ["with --auto, call these tools although the server doesn't", 'mark them readOnlyHint (exact names, comma-separated; tools', 'marked or named as writes are still never called)']],
|
|
36
36
|
'save-scenario': ['--save-scenario <path>', ['with --auto, write the plan made before the run as a scenario file', '(calls planned later for tools an unlock brings are not in it)']],
|
|
37
|
+
elicitation: ['--elicitation <decline|cancel>', ['how to answer a tool that asks the user something mid-call (2026-07-28):', 'decline (default) or cancel, the same every time']],
|
|
37
38
|
'union-out': ['--union-out <path>', ['write every tool the session saw as a menu file, to commit as the', 'baseline for diff (tools behind unlocks included)']],
|
|
38
39
|
versions: ['--versions <n|all>', ['how many of the most recent versions to inspect (default: 10), or all']],
|
|
39
40
|
'include-prereleases': ['--include-prereleases', ['include versions like 1.2.0-beta.1']],
|
|
@@ -106,7 +107,7 @@ const HELP = {
|
|
|
106
107
|
'prompt cache, a different menu in a fresh process.',
|
|
107
108
|
SERVER_NOTE,
|
|
108
109
|
],
|
|
109
|
-
own: ['scenario', 'auto', 'init', 'plan', 'value', 'values-file', 'assume-read-only', 'open-world', 'max-calls', 'max-calls-per-unlock', 'save-scenario', 'union-out'],
|
|
110
|
+
own: ['scenario', 'auto', 'init', 'plan', 'value', 'values-file', 'assume-read-only', 'open-world', 'max-calls', 'max-calls-per-unlock', 'save-scenario', 'union-out', 'elicitation'],
|
|
110
111
|
shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
|
|
111
112
|
examples: [
|
|
112
113
|
'toolmenu session --auto -- node dist/index.js',
|
package/dist/mrtr.d.ts
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import type { Connection, Elicitation } from './connect.js';
|
|
2
|
+
/** Rounds answered before toolmenu stops: a tool still asking after this is stuck. */
|
|
3
|
+
export declare const MAX_ROUNDS = 3;
|
|
4
|
+
export type InputKind = 'form' | 'url' | 'roots' | 'sampling' | 'other';
|
|
5
|
+
export interface InputTrace {
|
|
6
|
+
/** input_required results answered. */
|
|
7
|
+
rounds: number;
|
|
8
|
+
/** What the tool asked for, in the order first asked. */
|
|
9
|
+
kinds: InputKind[];
|
|
10
|
+
/**
|
|
11
|
+
* none: it asked for nothing. completed: it answered after the decline(s).
|
|
12
|
+
* loop: it asked the same again after a decline, until the round limit.
|
|
13
|
+
* gave-up: still asking (different things) at the round limit.
|
|
14
|
+
* undeclared: it asked for something the request didn't declare (roots, sampling).
|
|
15
|
+
* decline-failed: the retry carrying the decline failed with a protocol error.
|
|
16
|
+
*/
|
|
17
|
+
outcome: 'none' | 'completed' | 'loop' | 'gave-up' | 'undeclared' | 'decline-failed';
|
|
18
|
+
/** Kinds asked for that the request didn't declare. */
|
|
19
|
+
undeclared?: InputKind[];
|
|
20
|
+
/** The protocol error a retry failed with (decline-failed). */
|
|
21
|
+
error?: unknown;
|
|
22
|
+
/** A raw result on the wire without resultType, which 2026-07-28 servers MUST send. */
|
|
23
|
+
missingResultType?: boolean;
|
|
24
|
+
}
|
|
25
|
+
type CallResult = Awaited<ReturnType<Connection['client']['callTool']>>;
|
|
26
|
+
/**
|
|
27
|
+
* Call a tool, answering any input it asks for. On a 2025-era connection it's a
|
|
28
|
+
* plain call (the SDK client's elicitation handler answers there). `result` is
|
|
29
|
+
* undefined when the tool never completed (loop, gave-up, undeclared, decline-failed).
|
|
30
|
+
*/
|
|
31
|
+
export declare function callWithInput(conn: Connection, params: {
|
|
32
|
+
name: string;
|
|
33
|
+
arguments: Record<string, unknown>;
|
|
34
|
+
}, options: {
|
|
35
|
+
timeoutMs?: number;
|
|
36
|
+
elicitation?: Elicitation;
|
|
37
|
+
}): Promise<{
|
|
38
|
+
result?: CallResult;
|
|
39
|
+
input: InputTrace;
|
|
40
|
+
}>;
|
|
41
|
+
export {};
|
package/dist/mrtr.js
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
/** Rounds answered before toolmenu stops: a tool still asking after this is stuck. */
|
|
2
|
+
export const MAX_ROUNDS = 3;
|
|
3
|
+
const DECLARED = new Set(['form', 'url']);
|
|
4
|
+
function kindOf(request) {
|
|
5
|
+
if (request.method === 'elicitation/create')
|
|
6
|
+
return request.params?.mode === 'url' ? 'url' : 'form';
|
|
7
|
+
if (request.method === 'roots/list')
|
|
8
|
+
return 'roots';
|
|
9
|
+
if (request.method === 'sampling/createMessage')
|
|
10
|
+
return 'sampling';
|
|
11
|
+
return 'other';
|
|
12
|
+
}
|
|
13
|
+
/** Keys sorted at every level: the same request asked twice reads the same. */
|
|
14
|
+
function canonical(value) {
|
|
15
|
+
if (Array.isArray(value))
|
|
16
|
+
return `[${value.map(canonical).join(',')}]`;
|
|
17
|
+
if (value && typeof value === 'object') {
|
|
18
|
+
return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
|
|
19
|
+
}
|
|
20
|
+
return JSON.stringify(value);
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Call a tool, answering any input it asks for. On a 2025-era connection it's a
|
|
24
|
+
* plain call (the SDK client's elicitation handler answers there). `result` is
|
|
25
|
+
* undefined when the tool never completed (loop, gave-up, undeclared, decline-failed).
|
|
26
|
+
*/
|
|
27
|
+
export async function callWithInput(conn, params, options) {
|
|
28
|
+
if (conn.era !== 'modern')
|
|
29
|
+
return { result: await conn.client.callTool(params, { timeout: options.timeoutMs }), input: { rounds: 0, kinds: [], outcome: 'none' } };
|
|
30
|
+
const action = options.elicitation ?? 'decline';
|
|
31
|
+
const kinds = [];
|
|
32
|
+
let missingResultType = false;
|
|
33
|
+
let previous;
|
|
34
|
+
let repeated = false;
|
|
35
|
+
let rounds = 0;
|
|
36
|
+
let call = { ...params };
|
|
37
|
+
const trace = (outcome, more = {}) => ({
|
|
38
|
+
rounds,
|
|
39
|
+
kinds,
|
|
40
|
+
outcome,
|
|
41
|
+
...(missingResultType ? { missingResultType } : {}),
|
|
42
|
+
...more,
|
|
43
|
+
});
|
|
44
|
+
for (;;) {
|
|
45
|
+
const mark = conn.wire.responses.length;
|
|
46
|
+
let result;
|
|
47
|
+
try {
|
|
48
|
+
result = (await conn.client.callTool(call, { timeout: options.timeoutMs, allowInputRequired: true }));
|
|
49
|
+
}
|
|
50
|
+
catch (error) {
|
|
51
|
+
// A result without resultType: the SDK client rejects it ("missing required
|
|
52
|
+
// resultType"). The server did answer, so the step did too; the finding says why
|
|
53
|
+
// clients won't take it.
|
|
54
|
+
const answered = conn.wire.since(mark, 'tools/call').at(-1)?.result;
|
|
55
|
+
if (answered && !('resultType' in answered)) {
|
|
56
|
+
missingResultType = true;
|
|
57
|
+
return { result: answered, input: trace(rounds ? 'completed' : 'none') };
|
|
58
|
+
}
|
|
59
|
+
// The first call failing is an ordinary failed step; a retry that carried a
|
|
60
|
+
// decline failing is the server's answer to the decline.
|
|
61
|
+
if (rounds === 0)
|
|
62
|
+
throw error;
|
|
63
|
+
return { input: trace('decline-failed', { error }) };
|
|
64
|
+
}
|
|
65
|
+
const raw = conn.wire.since(mark, 'tools/call').at(-1)?.result;
|
|
66
|
+
if (raw && !('resultType' in raw))
|
|
67
|
+
missingResultType = true;
|
|
68
|
+
if (result.resultType !== 'input_required') {
|
|
69
|
+
return { result: result, input: trace(rounds ? 'completed' : 'none') };
|
|
70
|
+
}
|
|
71
|
+
const asked = result.inputRequests ?? {};
|
|
72
|
+
for (const request of Object.values(asked)) {
|
|
73
|
+
const k = kindOf(request);
|
|
74
|
+
if (!kinds.includes(k))
|
|
75
|
+
kinds.push(k);
|
|
76
|
+
}
|
|
77
|
+
const undeclared = [...new Set(Object.values(asked).map(kindOf).filter((k) => !DECLARED.has(k)))];
|
|
78
|
+
if (undeclared.length)
|
|
79
|
+
return { input: trace('undeclared', { undeclared }) };
|
|
80
|
+
// The same requests again after a decline: the tool didn't take the answer.
|
|
81
|
+
const signature = canonical(asked);
|
|
82
|
+
if (previous !== undefined && signature === previous && Object.keys(asked).length)
|
|
83
|
+
repeated = true;
|
|
84
|
+
if (rounds >= MAX_ROUNDS)
|
|
85
|
+
return { input: trace(repeated ? 'loop' : 'gave-up') };
|
|
86
|
+
previous = signature;
|
|
87
|
+
rounds++;
|
|
88
|
+
const state = result.requestState;
|
|
89
|
+
call = {
|
|
90
|
+
...params,
|
|
91
|
+
inputResponses: Object.fromEntries(Object.keys(asked).map((key) => [key, { action }])),
|
|
92
|
+
...(state !== undefined ? { requestState: state } : {}),
|
|
93
|
+
};
|
|
94
|
+
}
|
|
95
|
+
}
|
package/dist/options.d.ts
CHANGED
package/dist/options.js
CHANGED
|
@@ -14,6 +14,7 @@ export const CLI_OPTIONS = {
|
|
|
14
14
|
env: { type: 'string', multiple: true },
|
|
15
15
|
timeout: { type: 'string' },
|
|
16
16
|
protocol: { type: 'string' },
|
|
17
|
+
elicitation: { type: 'string' },
|
|
17
18
|
'no-auth': { type: 'boolean' },
|
|
18
19
|
port: { type: 'string' },
|
|
19
20
|
scope: { type: 'string' },
|
package/dist/rules/gated.js
CHANGED
|
@@ -17,7 +17,10 @@ export const gated = {
|
|
|
17
17
|
// Only an unlock whose parameter lists what it unlocks (an enum of toolsets or
|
|
18
18
|
// domains), the kind session --auto walks: "Enables Cross-Region Restore on a
|
|
19
19
|
// vault" turns on a feature, not tools (Azure, 418 tools).
|
|
20
|
-
|
|
20
|
+
// And only one whose name or description says it unlocks tools: an enum of
|
|
21
|
+
// domains alone is as often data (Garmin's garmin_sync { domains: [sleep, hrv] }
|
|
22
|
+
// downloads them). session --auto still tries such a tool once.
|
|
23
|
+
const found = unlockers(ctx.menu.tools).filter((u) => u.param && u.values.length && u.claims);
|
|
21
24
|
if (!found.length)
|
|
22
25
|
return [];
|
|
23
26
|
// A value whose tools are already listed adds nothing: the same server started
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type { MenuTool } from '../types.js';
|
|
2
|
+
import { type Rule } from './rule.js';
|
|
3
|
+
export interface HeaderFault {
|
|
4
|
+
/** Where the annotation sits: `region`, `filter.region`, `<items>.id`. */
|
|
5
|
+
path: string;
|
|
6
|
+
/** The annotation's value, as written. */
|
|
7
|
+
header: unknown;
|
|
8
|
+
problem: string;
|
|
9
|
+
/** The SDK client drops the tool for this (true), or only the spec forbids it (false: `number`). */
|
|
10
|
+
dropped: boolean;
|
|
11
|
+
}
|
|
12
|
+
/** Every broken x-mcp-header annotation in a tool's input schema; empty when all are valid or there are none. */
|
|
13
|
+
export declare function headerFaults(tool: MenuTool): HeaderFault[];
|
|
14
|
+
export declare const xMcpHeader: Rule;
|