toolmenu 0.23.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 CHANGED
@@ -36,7 +36,7 @@ It runs on the 22-server [bench](bench/README.md) and on hosted servers (GitHub,
36
36
  Notion, Supabase, Vercel…). What it has found on real servers is in
37
37
  [docs/FINDINGS.md](https://github.com/niksa90/toolmenu/blob/main/docs/FINDINGS.md).
38
38
 
39
- > **Status: 0.23.** Spec in [docs/SPEC.md](https://github.com/niksa90/toolmenu/blob/main/docs/SPEC.md),
39
+ > **Status: 0.24.** Spec in [docs/SPEC.md](https://github.com/niksa90/toolmenu/blob/main/docs/SPEC.md),
40
40
  > every rule in [docs/RULES.md](docs/RULES.md), changes in [CHANGELOG.md](CHANGELOG.md).
41
41
 
42
42
  <details>
@@ -160,6 +160,34 @@ makes the exit code 2, because it wasn't checked; one marked `disabled` is liste
160
160
  left alone. URLs are printed without their query, which can hold a key. Nothing is
161
161
  written unless `--out-dir` names a folder for each server's menu file.
162
162
 
163
+ ## For the agent building your server: `mcp`
164
+
165
+ `toolmenu mcp` is toolmenu as an MCP server (stdio), so Claude Code, Cursor or any
166
+ other client can check the server it's working on while it works. In Claude Code, as a
167
+ plugin (the server, and a skill that says when to run it and how to read the report):
168
+
169
+ ```
170
+ /plugin marketplace add niksa90/toolmenu
171
+ /plugin install toolmenu@toolmenu
172
+ ```
173
+
174
+ Or just the server, in any client: `claude mcp add toolmenu -- npx -y toolmenu mcp`, or
175
+ `{"command": "npx", "args": ["-y", "toolmenu", "mcp"]}` in an `mcpServers` config.
176
+
177
+ | Tool | Runs |
178
+ |---|---|
179
+ | `snapshot_menu` | `snapshot`: findings and token cost; writes the menu file only with `save_as` |
180
+ | `diff_menus` | `diff`: breaking changes, the token change and the version bump between two menu files |
181
+ | `check_session` | `session --auto`: calls the read-only tools and reports each menu change |
182
+ | `explain_rule` | `explain`: what a rule checks and how to change its level |
183
+
184
+ Each tool runs the CLI in a child process and returns its text report, so options,
185
+ `toolmenu.config.json` and stored OAuth logins work as they do on the command line.
186
+ Relative paths resolve from the folder `toolmenu mcp` runs in, or a call's `cwd`.
187
+ `snapshot_menu` and `check_session` start the command you give them, as the CLI does;
188
+ clients ask before each tool call unless you allow it. toolmenu's own menu passes its
189
+ checks with no findings, on both protocols and in a session (the test suite checks).
190
+
163
191
  ## In CI: one PR comment
164
192
 
165
193
  ```yaml
package/dist/cli.d.ts CHANGED
@@ -1,2 +1,2 @@
1
1
  #!/usr/bin/env node
2
- export declare function main(argv: string[]): Promise<number>;
2
+ export declare function main(given: string[]): Promise<number>;
package/dist/cli.js CHANGED
@@ -24,6 +24,7 @@ import { authDir, listLogins, login, logout } from './auth.js';
24
24
  import { existingMessage, initReport, planInit, shellWord, writeInit } from './init.js';
25
25
  import { SEVERITY_RANK } from './types.js';
26
26
  import { VERSION } from './version.js';
27
+ import { SECRET_ARGS_ENV } from './mcp-env.js';
27
28
  import { CLI_OPTIONS } from './options.js';
28
29
  import { editDistance } from './words.js';
29
30
  import { formatScan, ListError, loadList, scan, scanExit } from './scan.js';
@@ -31,7 +32,8 @@ import { explain, findRule, formatExplained, listRules, ruleDocs } from './rule-
31
32
  import { commandHelp, commandOptions, isCommand, overview, unknownCommand } from './help.js';
32
33
  class UsageError extends Error {
33
34
  }
34
- export async function main(argv) {
35
+ export async function main(given) {
36
+ const argv = withSecretArgs(given);
35
37
  const dash = argv.indexOf('--');
36
38
  const before = dash === -1 ? argv : argv.slice(0, dash);
37
39
  const command = dash === -1 ? undefined : argv.slice(dash + 1);
@@ -91,6 +93,14 @@ export async function main(argv) {
91
93
  return authCommand(rest, values);
92
94
  if (sub === 'explain')
93
95
  return explainCommand(rest, command, format);
96
+ if (sub === 'mcp') {
97
+ if (command || rest.length)
98
+ throw new UsageError('mcp takes no server: it is one. Add it to a client as: npx -y toolmenu mcp');
99
+ // Loaded only here: the CLI's other commands don't need the server SDK.
100
+ const { serveMcp } = await import('./mcp.js');
101
+ await serveMcp();
102
+ return 0;
103
+ }
94
104
  // The invocation up to the server, for examples in messages: a session example
95
105
  // without --auto or --scenario wouldn't run.
96
106
  const scenarioFlag = values.scenario ? ` --scenario ${shellWord(values.scenario)}` : '';
@@ -568,6 +578,28 @@ function commandIn(args) {
568
578
  }
569
579
  return undefined;
570
580
  }
581
+ /**
582
+ * toolmenu mcp passes header and env values (credentials) in TOOLMENU_MCP_ARGS, a JSON
583
+ * array of arguments, not on the command line: argv is readable by any local user.
584
+ * They go before the server command's "--". Removed from the environment once read.
585
+ */
586
+ function withSecretArgs(argv) {
587
+ const raw = process.env[SECRET_ARGS_ENV];
588
+ if (raw === undefined)
589
+ return argv;
590
+ delete process.env[SECRET_ARGS_ENV];
591
+ let extra;
592
+ try {
593
+ extra = JSON.parse(raw);
594
+ }
595
+ catch {
596
+ extra = undefined;
597
+ }
598
+ if (!Array.isArray(extra) || !extra.every((a) => typeof a === 'string'))
599
+ throw new UsageError(`${SECRET_ARGS_ENV} must be a JSON array of strings.`);
600
+ const dash = argv.indexOf('--');
601
+ return dash === -1 ? [...argv, ...extra] : [...argv.slice(0, dash), ...extra, ...argv.slice(dash)];
602
+ }
571
603
  function parseRelease(value) {
572
604
  const m = /^(.+?)\.\.(.+)$/.exec(value);
573
605
  if (!m)
package/dist/connect.d.ts CHANGED
@@ -73,6 +73,15 @@ export interface ConnectOptions {
73
73
  timeoutMs?: number;
74
74
  }
75
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;
76
85
  export interface ToolList {
77
86
  tools: Record<string, unknown>[];
78
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';
@@ -282,6 +282,29 @@ function watchProcess(stdio, trace) {
282
282
  }
283
283
  };
284
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
+ }
285
308
  /** fetch, noting each JSON-RPC request's method and the answer's status, content type and final URL. */
286
309
  function tracedFetch(trace) {
287
310
  return async (input, init) => {
@@ -299,6 +322,14 @@ function tracedFetch(trace) {
299
322
  if (method)
300
323
  trace.send(method);
301
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
+ }
302
333
  if (method) {
303
334
  trace.http.set(method, { status: response.status, statusText: response.statusText, contentType: response.headers.get('content-type') ?? '', url: response.url });
304
335
  }
package/dist/diff.js CHANGED
@@ -402,9 +402,8 @@ const MAX_DEPTH = 64;
402
402
  function headerLoss(t, headers, old) {
403
403
  if (!headers)
404
404
  return undefined;
405
- const dropped = (tool) => headerFaults(tool).filter((f) => f.dropped);
406
- const broken = dropped(t);
407
- if (!broken.length || (old && dropped(old).length))
405
+ const broken = headerFaults(t);
406
+ if (!broken.length || (old && headerFaults(old).length))
408
407
  return undefined;
409
408
  return {
410
409
  rule: 'diff/x-mcp-header-invalid',
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/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)']],
@@ -185,6 +185,20 @@ const HELP = {
185
185
  examples: ['toolmenu explain naming/vague-id', 'toolmenu explain handle-lifetime', 'toolmenu explain --json diff/param-required'],
186
186
  exits: ['0 explained', "2 no such rule (the closest ones are named), or bad usage"],
187
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
+ },
188
202
  };
189
203
  function optionLines(keys) {
190
204
  const width = Math.max(...keys.map((k) => OPTIONS[k][0].length)) + 2;
@@ -0,0 +1,5 @@
1
+ /**
2
+ * The environment variable toolmenu mcp passes credential arguments in (header and env
3
+ * values), shared with the CLI. Its own module so the CLI doesn't load the server SDK.
4
+ */
5
+ export declare const SECRET_ARGS_ENV = "TOOLMENU_MCP_ARGS";
@@ -0,0 +1,5 @@
1
+ /**
2
+ * The environment variable toolmenu mcp passes credential arguments in (header and env
3
+ * values), shared with the CLI. Its own module so the CLI doesn't load the server SDK.
4
+ */
5
+ export const SECRET_ARGS_ENV = 'TOOLMENU_MCP_ARGS';
package/dist/mcp.d.ts ADDED
@@ -0,0 +1,65 @@
1
+ import { McpServer } from '@modelcontextprotocol/server';
2
+ import { SECRET_ARGS_ENV } from './mcp-env.js';
3
+ export { SECRET_ARGS_ENV };
4
+ /** A whole run's ceiling. Each request inside it already has the CLI's own --timeout. */
5
+ export declare const RUN_LIMIT_MS: number;
6
+ export interface CliRun {
7
+ code: number;
8
+ stdout: string;
9
+ stderr: string;
10
+ /** Why the run was stopped, when toolmenu mcp stopped it. */
11
+ stopped?: string;
12
+ }
13
+ /** Kill every run still going, at once: toolmenu mcp itself is exiting. */
14
+ export declare function killAllNow(): void;
15
+ /** Stop every run still going, and wait for it: the client closed the connection. */
16
+ export declare function stopAll(): Promise<void>;
17
+ export interface RunOptions {
18
+ /** Arguments that carry credentials, passed through the environment (SECRET_ARGS_ENV). */
19
+ secretArgs?: string[];
20
+ signal?: AbortSignal;
21
+ limitMs?: number;
22
+ }
23
+ /** Run the toolmenu CLI with these arguments, from this folder. */
24
+ export declare function runCli(args: string[], cwd: string, options?: RunOptions): Promise<CliRun>;
25
+ type Text = {
26
+ content: {
27
+ type: 'text';
28
+ text: string;
29
+ }[];
30
+ isError?: boolean;
31
+ };
32
+ /** A CLI run as a tool result. Findings are a report, not a failure: only exit 2 (couldn't run) is an error. */
33
+ export declare function toResult(run: CliRun): Text;
34
+ type ServerArgs = {
35
+ command?: string[];
36
+ url?: string;
37
+ headers?: Record<string, string>;
38
+ env?: Record<string, string>;
39
+ cwd?: string;
40
+ };
41
+ export interface ServerSpec {
42
+ /** Before "--": the URL, if any. */
43
+ before: string[];
44
+ /** Header and env values, passed through the environment. */
45
+ secret: string[];
46
+ /** "--" and the command, if any. */
47
+ after: string[];
48
+ }
49
+ /** The CLI arguments that name the server, or why they can't. */
50
+ export declare function serverArgs(a: ServerArgs): ServerSpec | {
51
+ error: string;
52
+ };
53
+ /** The folder a call runs in, or why it can't. */
54
+ export declare function folder(baseCwd: string, cwd?: string): {
55
+ dir: string;
56
+ } | {
57
+ error: string;
58
+ };
59
+ export declare function build(baseCwd?: string): McpServer;
60
+ /**
61
+ * Serve over stdio until the client closes stdin, then stop every run still going.
62
+ * A client that closes stdin may send SIGTERM before the runs are stopped: on that, or
63
+ * on any exit, what's left is killed at once rather than left running.
64
+ */
65
+ export declare function serveMcp(): Promise<void>;
package/dist/mcp.js ADDED
@@ -0,0 +1,293 @@
1
+ /*
2
+ * `toolmenu mcp`: toolmenu as an MCP server (stdio), so an agent building an MCP
3
+ * server can check its menu while it works. Each tool runs the CLI in a child process
4
+ * (no shell) and returns its report: the same checks, options, config and exit codes
5
+ * as on the command line, and a crash or hang in one check can't take the server down.
6
+ *
7
+ * Each child runs in its own process group, so cancelling a call, its time running
8
+ * out, or the client closing the connection stops the child and the server it started.
9
+ */
10
+ import { spawn, spawnSync } from 'node:child_process';
11
+ import { statSync } from 'node:fs';
12
+ import { isAbsolute, resolve } from 'node:path';
13
+ import { fileURLToPath } from 'node:url';
14
+ import { McpServer } from '@modelcontextprotocol/server';
15
+ import { serveStdio } from '@modelcontextprotocol/server/stdio';
16
+ import * as z from 'zod';
17
+ import { CLIENT_NAMES } from './clients.js';
18
+ import { VERSION } from './version.js';
19
+ import { SECRET_ARGS_ENV } from './mcp-env.js';
20
+ export { SECRET_ARGS_ENV };
21
+ const CLI = fileURLToPath(new URL('./cli.js', import.meta.url));
22
+ /** A whole run's ceiling. Each request inside it already has the CLI's own --timeout. */
23
+ export const RUN_LIMIT_MS = 10 * 60_000;
24
+ const OUTPUT_LIMIT = 64 * 1024 * 1024;
25
+ const WINDOWS = process.platform === 'win32';
26
+ /**
27
+ * Runs still going, by the CLI's pid. On Linux and macOS each run is a process group
28
+ * (the CLI and the server it started), kept until nothing in it is alive, not until
29
+ * the CLI exits: a server that ignores SIGTERM outlives the CLI that started it.
30
+ * Windows has no process groups to signal: there a run is the CLI's process tree,
31
+ * which taskkill /T ends while the CLI is still its root.
32
+ */
33
+ const runs = new Map();
34
+ /** Whether anything in the run is still alive. */
35
+ function runAlive(pid) {
36
+ if (WINDOWS) {
37
+ const child = runs.get(pid);
38
+ return !!child && child.exitCode === null && child.signalCode === null;
39
+ }
40
+ try {
41
+ process.kill(-pid, 0);
42
+ return true;
43
+ }
44
+ catch {
45
+ return false;
46
+ }
47
+ }
48
+ /** Signal the whole run. On Windows, any stop is taskkill /T /F: there's no polite one for a console process. */
49
+ function signalRun(pid, signal) {
50
+ if (WINDOWS) {
51
+ spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
52
+ return;
53
+ }
54
+ try {
55
+ process.kill(-pid, signal);
56
+ }
57
+ catch {
58
+ // Already gone.
59
+ }
60
+ }
61
+ /** Stop a run: SIGTERM, then SIGKILL to whatever in it is still there 2 s later. */
62
+ async function stopRun(pid) {
63
+ if (runAlive(pid)) {
64
+ signalRun(pid, 'SIGTERM');
65
+ const end = Date.now() + 2_000;
66
+ while (runAlive(pid) && Date.now() < end)
67
+ await new Promise((r) => setTimeout(r, 50));
68
+ if (runAlive(pid))
69
+ signalRun(pid, 'SIGKILL');
70
+ }
71
+ runs.delete(pid);
72
+ }
73
+ /** Kill every run still going, at once: toolmenu mcp itself is exiting. */
74
+ export function killAllNow() {
75
+ for (const pid of runs.keys())
76
+ signalRun(pid, 'SIGKILL');
77
+ }
78
+ /** Stop every run still going, and wait for it: the client closed the connection. */
79
+ export async function stopAll() {
80
+ await Promise.all([...runs.keys()].map(stopRun));
81
+ }
82
+ /** Run the toolmenu CLI with these arguments, from this folder. */
83
+ export function runCli(args, cwd, options = {}) {
84
+ const { secretArgs = [], signal, limitMs = RUN_LIMIT_MS } = options;
85
+ return new Promise((done) => {
86
+ if (signal?.aborted)
87
+ return done({ code: 2, stdout: '', stderr: '', stopped: 'The call was cancelled before it started.' });
88
+ // NO_COLOR: the report goes to an agent, not a terminal. NODE_NO_WARNINGS: Node's
89
+ // own notices (experimental features) aren't findings, and would read as if they
90
+ // were. Neither reaches the server under test: it gets a minimal environment.
91
+ const env = { ...process.env, NO_COLOR: '1', NODE_NO_WARNINGS: '1' };
92
+ delete env[SECRET_ARGS_ENV];
93
+ if (secretArgs.length)
94
+ env[SECRET_ARGS_ENV] = JSON.stringify(secretArgs);
95
+ // detached: its own process group (Linux, macOS). On Windows it would open a console
96
+ // window for every run instead, so there the run stays attached and hidden.
97
+ const child = spawn(process.execPath, [CLI, ...args], { cwd, env, detached: !WINDOWS, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
98
+ if (child.pid)
99
+ runs.set(child.pid, child);
100
+ let stdout = '';
101
+ let stderr = '';
102
+ let stopped;
103
+ const halt = (why) => {
104
+ stopped ??= why;
105
+ if (child.pid)
106
+ void stopRun(child.pid);
107
+ };
108
+ child.stdout.on('data', (d) => {
109
+ stdout += d;
110
+ if (stdout.length > OUTPUT_LIMIT)
111
+ halt(`The report passed ${OUTPUT_LIMIT / 1024 / 1024} MB, so the run was stopped.`);
112
+ });
113
+ child.stderr.on('data', (d) => {
114
+ stderr += d;
115
+ if (stderr.length > OUTPUT_LIMIT)
116
+ stderr = stderr.slice(-OUTPUT_LIMIT);
117
+ });
118
+ const timer = setTimeout(() => halt(`The run took longer than ${limitMs / 60_000} minutes, so it was stopped. A server that is slow to answer each request can be given a longer --timeout in toolmenu.config.json, or fewer calls (max_calls).`), limitMs);
119
+ const onAbort = () => halt('The call was cancelled, so the run was stopped.');
120
+ signal?.addEventListener('abort', onAbort, { once: true });
121
+ let finished = false;
122
+ // A child that fails to start can emit both error and close: answer once.
123
+ const finish = (code) => {
124
+ if (finished)
125
+ return;
126
+ finished = true;
127
+ clearTimeout(timer);
128
+ signal?.removeEventListener('abort', onAbort);
129
+ // Whatever the CLI left behind (a server it couldn't stop) goes with it.
130
+ if (child.pid)
131
+ void stopRun(child.pid);
132
+ done({ code, stdout, stderr, ...(stopped ? { stopped } : {}) });
133
+ };
134
+ // Never Node's own error message: it repeats the command line.
135
+ child.on('error', (error) => {
136
+ stderr += `toolmenu mcp couldn't start the toolmenu CLI (${error.code ?? 'error'}).`;
137
+ finish(2);
138
+ });
139
+ child.on('close', (code) => finish(stopped ? 2 : code ?? 2));
140
+ });
141
+ }
142
+ /** A CLI run as a tool result. Findings are a report, not a failure: only exit 2 (couldn't run) is an error. */
143
+ export function toResult(run) {
144
+ const out = run.stdout.trim();
145
+ if (run.code === 2) {
146
+ const why = [run.stopped, run.stderr.trim()].filter(Boolean).join('\n\n') || out || 'toolmenu exited with code 2.';
147
+ return { content: [{ type: 'text', text: why }], isError: true };
148
+ }
149
+ const notes = run.stderr.trim();
150
+ const tail = run.code === 1 ? '\n\nExit 1: there are error-level findings.' : '';
151
+ return { content: [{ type: 'text', text: `${out || 'No output.'}${tail}${notes ? `\n\nNotes:\n${notes}` : ''}` }] };
152
+ }
153
+ const serverShape = {
154
+ command: z
155
+ .array(z.string())
156
+ .min(1)
157
+ .optional()
158
+ .describe('The command that starts a stdio server, one word per item: ["node", "dist/server.js"]. Give this or url.'),
159
+ url: z.string().optional().describe('A Streamable HTTP endpoint: https://example.com/mcp. Give this or command.'),
160
+ headers: z.record(z.string(), z.string()).optional().describe('HTTP headers for a url server: {"Authorization": "Bearer ..."}.'),
161
+ env: z.record(z.string(), z.string()).optional().describe('Environment variables for a command server. It gets a minimal environment plus these.'),
162
+ cwd: z.string().optional().describe('Folder to run from: where the server starts, toolmenu.config.json is read and relative paths resolve. Default: where toolmenu mcp runs.'),
163
+ };
164
+ /** The CLI arguments that name the server, or why they can't. */
165
+ export function serverArgs(a) {
166
+ if (!a.command === !a.url)
167
+ return { error: 'Give the server as command (a stdio server, e.g. ["node", "dist/server.js"]) or url (an HTTP server), one of the two.' };
168
+ if (a.url) {
169
+ if (a.env && Object.keys(a.env).length)
170
+ return { error: 'env goes with command: an HTTP server is already running. Use headers for credentials.' };
171
+ if (!/^https?:\/\//.test(a.url))
172
+ return { error: `url must be an http(s) URL; got "${a.url}". For a stdio server, give command.` };
173
+ return { before: [a.url], secret: Object.entries(a.headers ?? {}).flatMap(([k, v]) => ['--header', `${k}: ${v}`]), after: [] };
174
+ }
175
+ if (a.headers && Object.keys(a.headers).length)
176
+ return { error: 'headers go with url. Pass a stdio server its credentials with env.' };
177
+ return { before: [], secret: Object.entries(a.env ?? {}).flatMap(([k, v]) => ['--env', `${k}=${v}`]), after: ['--', ...a.command] };
178
+ }
179
+ /** The folder a call runs in, or why it can't. */
180
+ export function folder(baseCwd, cwd) {
181
+ const dir = cwd ? resolve(baseCwd, cwd) : baseCwd;
182
+ try {
183
+ if (statSync(dir).isDirectory())
184
+ return { dir };
185
+ return { error: `cwd "${cwd ?? dir}" is a file, not a folder.` };
186
+ }
187
+ catch {
188
+ return { error: `cwd "${cwd ?? dir}" doesn't exist (resolved to ${dir}). Give the server's project folder.` };
189
+ }
190
+ }
191
+ /** A path as an absolute one, so a value starting with "-" can't be read as an option. */
192
+ const absolute = (dir, path) => (isAbsolute(path) ? path : resolve(dir, path));
193
+ const failed = (text) => ({ content: [{ type: 'text', text }], isError: true });
194
+ export function build(baseCwd = process.cwd()) {
195
+ const server = new McpServer({ name: 'toolmenu', version: VERSION }, {
196
+ capabilities: { tools: {} },
197
+ // The same four tools for everyone, always: an hour, and shared caches may keep it.
198
+ cacheHints: { 'tools/list': { ttlMs: 3_600_000, cacheScope: 'public' }, 'server/discover': { ttlMs: 3_600_000, cacheScope: 'public' } },
199
+ instructions: "toolmenu checks an MCP server's tool list (its menu) the way clients and agents meet it. " +
200
+ 'After changing a server\'s tools: snapshot_menu for findings and token cost, diff_menus against the committed menu.json for breaking changes, check_session to see whether the menu changes mid-session. ' +
201
+ 'Each finding ends with a → Next: step; explain_rule says what a rule checks.',
202
+ });
203
+ /** Run a command for a server: the folder checked, credentials kept out of argv. */
204
+ const forServer = async (a, ctx, args) => {
205
+ const s = serverArgs(a);
206
+ if ('error' in s)
207
+ return failed(s.error);
208
+ const f = folder(baseCwd, a.cwd);
209
+ if ('error' in f)
210
+ return failed(f.error);
211
+ return toResult(await runCli([...args(f.dir, s), ...s.after], f.dir, { secretArgs: s.secret, signal: ctx.mcpReq.signal }));
212
+ };
213
+ server.registerTool('snapshot_menu', {
214
+ description: "Check an MCP server's tool list: start or connect to it, list its tools, and report findings (what agents misread, what breaks clients or prompt caches) and the token cost. " +
215
+ 'Writes the menu file only when save_as is given (the baseline for diff_menus).',
216
+ inputSchema: {
217
+ ...serverShape,
218
+ save_as: z.string().optional().describe('Write the menu here (menu.json for a baseline), relative to cwd. Default: not written.'),
219
+ client: z.enum(CLIENT_NAMES).optional().describe('Also check the menu as this client loads it: what it cuts, finds and refuses.'),
220
+ catalog: z.boolean().optional().describe('Also read the operations behind a search tool or command routers.'),
221
+ },
222
+ annotations: { title: 'Snapshot a server menu', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
223
+ }, (a, ctx) => forServer(a, ctx, (dir, s) => [
224
+ 'snapshot',
225
+ ...s.before,
226
+ a.save_as ? `--out=${absolute(dir, a.save_as)}` : '--no-write',
227
+ ...(a.client ? [`--client=${a.client}`] : []),
228
+ ...(a.catalog ? ['--catalog'] : []),
229
+ ]));
230
+ server.registerTool('diff_menus', {
231
+ description: 'Compare two menu files (from snapshot_menu save_as, or toolmenu snapshot): breaking changes for clients, the token change per conversation, and the version bump it needs. Reads files only.',
232
+ inputSchema: {
233
+ before: z.string().describe('The older menu file, e.g. the committed menu.json.'),
234
+ after: z.string().describe('The newer menu file.'),
235
+ release: z.string().optional().describe('The release versions to check the bump against: "1.4.0..1.5.0".'),
236
+ cwd: serverShape.cwd,
237
+ },
238
+ annotations: { title: 'Diff two menus', readOnlyHint: true, openWorldHint: false },
239
+ }, async (a, ctx) => {
240
+ const f = folder(baseCwd, a.cwd);
241
+ if ('error' in f)
242
+ return failed(f.error);
243
+ const args = ['diff', absolute(f.dir, a.before), absolute(f.dir, a.after), ...(a.release ? [`--release=${a.release}`] : [])];
244
+ return toResult(await runCli(args, f.dir, { signal: ctx.mcpReq.signal }));
245
+ });
246
+ server.registerTool('check_session', {
247
+ description: "Check whether an MCP server's menu changes while an agent works: call its tools marked readOnlyHint whose arguments the schema can fill, list the menu after each call, and report each change with the call that caused it. " +
248
+ 'Calls only read-only tools; never one marked openWorldHint unless open_world is set.',
249
+ inputSchema: {
250
+ ...serverShape,
251
+ max_calls: z.number().int().min(1).optional().describe('At most this many calls (default 20).'),
252
+ open_world: z.boolean().optional().describe('Also call read-only tools marked openWorldHint (web search, fetch): they may cost API credits.'),
253
+ },
254
+ annotations: { title: 'Run a session against a server', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
255
+ }, (a, ctx) => forServer(a, ctx, (_dir, s) => [
256
+ 'session',
257
+ '--auto',
258
+ ...s.before,
259
+ ...(a.max_calls ? [`--max-calls=${a.max_calls}`] : []),
260
+ ...(a.open_world ? ['--open-world'] : []),
261
+ ]));
262
+ server.registerTool('explain_rule', {
263
+ description: "Explain a toolmenu rule by the name a finding gives (naming/vague-id): what it checks, its default level and how to change it. Without rule, lists every rule.",
264
+ inputSchema: { rule: z.string().optional().describe('The rule, as a finding names it: naming/vague-id, or just vague-id.') },
265
+ annotations: { title: 'Explain a rule', readOnlyHint: true, openWorldHint: false },
266
+ }, async (a, ctx) => {
267
+ if (a.rule !== undefined && !/^[a-z0-9][a-z0-9/_-]*$/i.test(a.rule))
268
+ return failed(`"${a.rule}" isn't a rule name. Rules look like naming/vague-id; call explain_rule without rule to list them.`);
269
+ return toResult(await runCli(['explain', ...(a.rule ? [a.rule] : [])], baseCwd, { signal: ctx.mcpReq.signal }));
270
+ });
271
+ return server;
272
+ }
273
+ /**
274
+ * Serve over stdio until the client closes stdin, then stop every run still going.
275
+ * A client that closes stdin may send SIGTERM before the runs are stopped: on that, or
276
+ * on any exit, what's left is killed at once rather than left running.
277
+ */
278
+ export async function serveMcp() {
279
+ process.once('exit', killAllNow);
280
+ for (const [signal, code] of [['SIGTERM', 143], ['SIGINT', 130], ['SIGHUP', 129]]) {
281
+ process.once(signal, () => {
282
+ killAllNow();
283
+ process.exit(code);
284
+ });
285
+ }
286
+ const handle = serveStdio(() => build());
287
+ await new Promise((done) => {
288
+ process.stdin.once('end', done);
289
+ process.stdin.once('close', done);
290
+ });
291
+ await stopAll();
292
+ await handle.close().catch(() => { });
293
+ }
@@ -202,7 +202,7 @@
202
202
  "spec/x-mcp-header": {
203
203
  "command": "snapshot",
204
204
  "severity": "error",
205
- "text": "`since: 2026-07-28`. An `x-mcp-header` annotation the spec doesn't allow (SEP-2243): empty; not an RFC 9110 token; the same header twice ignoring case; on a parameter that isn't `string`, `integer` or `boolean`, or has no single `type`; anywhere but a parameter reached through `properties` alone. Streamable HTTP clients **MUST** leave such a tool out of `tools/list`, and the official SDK client does, with only a console warning. Error on an HTTP server, warn on stdio (clients there MAY ignore the annotation). `number` is warn on both: the spec forbids it, the SDK client accepts it for now. Every broken annotation in a tool is listed (the SDK stops at the first). Checked against the SDK client's behaviour in the tests"
205
+ "text": "`since: 2026-07-28`. An `x-mcp-header` annotation the spec doesn't allow (SEP-2243): empty; not an RFC 9110 token; the same header twice ignoring case; on a parameter that isn't `string`, `integer` or `boolean`, or has no single `type`; anywhere but a parameter reached through `properties` alone. Streamable HTTP clients **MUST** leave such a tool out of `tools/list`, and the official SDK client does, with only a console warning. Error on an HTTP server, warn on stdio (clients there MAY ignore the annotation). A `number` parameter counts too: the SDK client drops those tools since 2.4. Every broken annotation in a tool is listed (the SDK stops at the first). Checked against the SDK client's behaviour in the tests"
206
206
  },
207
207
  "write/no-dry-run": {
208
208
  "command": "snapshot",
@@ -6,8 +6,6 @@ export interface HeaderFault {
6
6
  /** The annotation's value, as written. */
7
7
  header: unknown;
8
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
9
  }
12
10
  /** Every broken x-mcp-header annotation in a tool's input schema; empty when all are valid or there are none. */
13
11
  export declare function headerFaults(tool: MenuTool): HeaderFault[];
@@ -9,8 +9,8 @@ import { count, names } from './rule.js';
9
9
  *
10
10
  * The checks follow the spec and the SDK client's own scan
11
11
  * (scanXMcpHeaderDeclarations in @modelcontextprotocol/client), which decides
12
- * what SDK-based clients actually drop. Where the two differ (`number`: the spec
13
- * forbids it, the SDK accepts it), the finding says so.
12
+ * what SDK-based clients actually drop. The two agree: since SDK 2.4 the client
13
+ * drops a tool whose header is on a number parameter too, as the spec says.
14
14
  */
15
15
  const KEY = 'x-mcp-header';
16
16
  // RFC 9110 §5.1 token: 1*tchar. No spaces, control characters or delimiters.
@@ -34,7 +34,7 @@ export function headerFaults(tool) {
34
34
  const where = path.length ? path.join('.') : 'the schema root';
35
35
  if (KEY in schema) {
36
36
  const raw = schema[KEY];
37
- const fault = (problem, dropped = true) => faults.push({ path: where, header: raw, problem, dropped });
37
+ const fault = (problem) => faults.push({ path: where, header: raw, problem });
38
38
  if (!reachable || path.length === 0) {
39
39
  fault(path.length === 0
40
40
  ? 'it sits on the schema root, not on a parameter'
@@ -57,7 +57,7 @@ export function headerFaults(tool) {
57
57
  else {
58
58
  // number takes part in the uniqueness check too: the SDK client registers it.
59
59
  if (type === 'number')
60
- fault('the parameter is a number; the spec allows only string, integer or boolean (the official SDK client accepts number for now, other clients may not)', false);
60
+ fault('the parameter is a number; it must be string, integer or boolean (make it an integer or a string: a header carries text anyway)');
61
61
  const prior = seen.get(raw.toLowerCase());
62
62
  if (prior !== undefined)
63
63
  fault(`"${raw}" is already used by ${prior}; header names must differ ignoring case`);
@@ -95,20 +95,15 @@ export const xMcpHeader = {
95
95
  const faults = headerFaults(tool);
96
96
  if (!faults.length)
97
97
  continue;
98
- const dropped = faults.some((f) => f.dropped);
99
98
  const where = faults.map((f) => f.path);
100
99
  findings.push({
101
100
  tool: tool.name,
102
101
  // Over HTTP the tool is gone for every compliant client. On stdio clients may
103
102
  // ignore the annotation, but the same server is often deployed over HTTP too.
104
- severity: dropped ? (http ? 'error' : 'warn') : 'warn',
105
- message: dropped
106
- ? `${tool.name} has ${faults.length === 1 ? 'an x-mcp-header annotation' : `${count(faults.length, 'x-mcp-header annotation')}`} the spec doesn't allow (on ${names(where, 4)}), and Streamable HTTP clients must then leave the whole tool out of their menu. The official SDK client does, with only a console warning, so the agent never sees ${tool.name} and nothing tells the server.${http ? ' toolmenu reads the list off the wire, which is why it is in this menu.' : ' Over stdio clients may ignore the annotation, so it shows here; served over HTTP, it would be gone.'}`
107
- : `${tool.name} mirrors a number parameter into a header (${names(where, 4)}). The spec allows only string, integer or boolean there, so a strict Streamable HTTP client must leave the tool out of its menu; the official SDK client keeps it for now (its conformance tests expect number to work, a gap tracked upstream).`,
103
+ severity: http ? 'error' : 'warn',
104
+ message: `${tool.name} has ${faults.length === 1 ? 'an x-mcp-header annotation' : `${count(faults.length, 'x-mcp-header annotation')}`} the spec doesn't allow (on ${names(where, 4)}), and Streamable HTTP clients must then leave the whole tool out of their menu. The official SDK client does, with only a console warning, so the agent never sees ${tool.name} and nothing tells the server.${http ? ' toolmenu reads the list off the wire, which is why it is in this menu.' : ' Over stdio clients may ignore the annotation, so it shows here; served over HTTP, it would be gone.'}`,
108
105
  detail: faults.map((f) => `${f.path}${typeof f.header === 'string' && f.header ? ` (x-mcp-header: "${f.header}")` : ''}: ${f.problem}`),
109
- fix: dropped
110
- ? `Fix each annotation listed: on a string, integer or boolean parameter reached through "properties" alone, with a header name of letters, digits and - _ . only, different from the tool's other headers ignoring case. Then list the tools over HTTP with an SDK client and check ${tool.name} is there.`
111
- : 'Make the parameter a string or an integer (a header carries text anyway), or stop mirroring it into a header.',
106
+ fix: `Fix each annotation listed: on a string, integer or boolean parameter reached through "properties" alone, with a header name of letters, digits and - _ . only, different from the tool's other headers ignoring case. Then list the tools over HTTP with an SDK client and check ${tool.name} is there.`,
112
107
  });
113
108
  }
114
109
  return findings;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "toolmenu",
3
- "version": "0.23.0",
3
+ "version": "0.24.0",
4
4
  "description": "Lint your MCP server's tool menu for changes that confuse agents or break caches.",
5
5
  "author": "Nikša Perović (https://niksa.me)",
6
6
  "main": "dist/index.js",
@@ -20,7 +20,8 @@
20
20
  "linter",
21
21
  "agents",
22
22
  "prompt-caching",
23
- "cli"
23
+ "cli",
24
+ "mcp-server"
24
25
  ],
25
26
  "license": "MIT",
26
27
  "bugs": {
@@ -28,17 +29,17 @@
28
29
  },
29
30
  "homepage": "https://github.com/niksa90/toolmenu#readme",
30
31
  "dependencies": {
31
- "@modelcontextprotocol/client": "^2.1.0",
32
+ "@modelcontextprotocol/client": "^2.4.0",
33
+ "@modelcontextprotocol/server": "^2.4.0",
32
34
  "ajv": "^8.20.0",
33
35
  "ajv-formats": "^3.0.1",
34
36
  "js-tiktoken": "^1.0.21",
35
- "yaml": "^2.9.1"
37
+ "yaml": "^2.9.1",
38
+ "zod": "^4.6.7"
36
39
  },
37
40
  "devDependencies": {
38
- "@modelcontextprotocol/server": "^2.1.0",
39
41
  "@types/node": "^22.20.4",
40
- "typescript": "^7.0.2",
41
- "zod": "^4.6.5"
42
+ "typescript": "^7.0.2"
42
43
  },
43
44
  "type": "module",
44
45
  "bin": {