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 +29 -1
- package/dist/cli.d.ts +1 -1
- package/dist/cli.js +33 -1
- package/dist/connect.d.ts +9 -0
- package/dist/connect.js +32 -1
- package/dist/diff.js +2 -3
- package/dist/explain.d.ts +16 -0
- package/dist/explain.js +14 -0
- package/dist/help.d.ts +1 -1
- package/dist/help.js +15 -1
- 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/rule-docs.json +1 -1
- package/dist/rules/headers.d.ts +0 -2
- package/dist/rules/headers.js +7 -12
- package/package.json +8 -7
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.
|
|
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(
|
|
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(
|
|
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
|
|
406
|
-
|
|
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;
|
package/dist/mcp-env.js
ADDED
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
|
+
}
|
package/dist/rule-docs.json
CHANGED
|
@@ -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`
|
|
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",
|
package/dist/rules/headers.d.ts
CHANGED
|
@@ -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[];
|
package/dist/rules/headers.js
CHANGED
|
@@ -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.
|
|
13
|
-
*
|
|
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
|
|
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;
|
|
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:
|
|
105
|
-
message:
|
|
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:
|
|
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.
|
|
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.
|
|
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": {
|