toolmenu 0.25.1 → 0.27.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 +312 -35
- package/dist/args.d.ts +14 -2
- package/dist/args.js +44 -1
- package/dist/auth-check.d.ts +27 -0
- package/dist/auth-check.js +177 -0
- package/dist/auth.d.ts +7 -0
- package/dist/auth.js +29 -1
- package/dist/auto.d.ts +8 -0
- package/dist/auto.js +9 -2
- package/dist/breakdown.js +14 -10
- package/dist/cli.js +171 -56
- package/dist/clients.d.ts +13 -2
- package/dist/clients.js +65 -11
- package/dist/config.js +6 -0
- package/dist/diff.d.ts +35 -1
- package/dist/diff.js +57 -12
- package/dist/failures.js +4 -3
- package/dist/help.d.ts +1 -1
- package/dist/help.js +45 -17
- package/dist/history.js +5 -0
- package/dist/html.d.ts +29 -0
- package/dist/html.js +360 -0
- package/dist/index.d.ts +3 -2
- package/dist/index.js +3 -2
- package/dist/init.d.ts +14 -0
- package/dist/init.js +20 -6
- package/dist/junit.d.ts +17 -0
- package/dist/junit.js +87 -0
- package/dist/mcp-env.d.ts +6 -0
- package/dist/mcp-env.js +6 -0
- package/dist/mcp.d.ts +10 -0
- package/dist/mcp.js +86 -15
- package/dist/menu.d.ts +6 -0
- package/dist/menu.js +12 -1
- package/dist/options.d.ts +13 -0
- package/dist/options.js +4 -0
- package/dist/report.d.ts +14 -0
- package/dist/report.js +57 -51
- package/dist/review.d.ts +48 -0
- package/dist/review.js +212 -0
- package/dist/rule-docs.json +49 -4
- package/dist/rules/clients.d.ts +11 -0
- package/dist/rules/clients.js +65 -2
- package/dist/rules/determinism.d.ts +3 -0
- package/dist/rules/determinism.js +44 -7
- package/dist/rules/ids.js +5 -1
- package/dist/rules/index.js +5 -2
- package/dist/rules/output.d.ts +21 -0
- package/dist/rules/output.js +49 -0
- package/dist/rules/search.js +1 -1
- package/dist/rules/spec.d.ts +19 -0
- package/dist/rules/spec.js +86 -1
- package/dist/sanitize.d.ts +42 -0
- package/dist/sanitize.js +142 -0
- package/dist/sarif.d.ts +2 -0
- package/dist/sarif.js +2 -2
- package/dist/scan.d.ts +9 -2
- package/dist/scan.js +46 -24
- package/dist/session.d.ts +17 -0
- package/dist/session.js +119 -13
- package/dist/snapshot.js +2 -1
- package/package.json +5 -3
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* session/output-schema: a tool that declares an outputSchema promises its results.
|
|
3
|
+
* 2025-06-18 and later: "If an output schema is provided, servers MUST provide
|
|
4
|
+
* structured results that conform to this schema", and clients SHOULD validate
|
|
5
|
+
* them; the official TypeScript SDK client does, and throws on a result that has no
|
|
6
|
+
* structuredContent or one that doesn't match. Checked on every call that answered
|
|
7
|
+
* (not isError), so it needs a session that calls the tool.
|
|
8
|
+
*/
|
|
9
|
+
import { Ajv } from 'ajv';
|
|
10
|
+
import { Ajv2020 } from 'ajv/dist/2020.js';
|
|
11
|
+
import addFormatsImport from 'ajv-formats';
|
|
12
|
+
const addFormats = (addFormatsImport.default ?? addFormatsImport);
|
|
13
|
+
/** The protocol version output schemas came in. */
|
|
14
|
+
export const OUTPUT_SCHEMA_SINCE = '2025-06-18';
|
|
15
|
+
const validators = new WeakMap();
|
|
16
|
+
/**
|
|
17
|
+
* What's wrong with a successful result against the tool's outputSchema, or
|
|
18
|
+
* undefined when it conforms (or the schema can't be compiled: then it's the
|
|
19
|
+
* schema that's broken, which spec/schema reports, not the result).
|
|
20
|
+
*/
|
|
21
|
+
export function outputProblem(schema, result) {
|
|
22
|
+
return outputCheck(schema, result)?.problem;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* The same, and whether only `format` checks failed (a URI, a date): many validators
|
|
26
|
+
* skip format unless told to, so such a result may well pass a client.
|
|
27
|
+
*/
|
|
28
|
+
export function outputCheck(schema, result) {
|
|
29
|
+
if (result.structuredContent === undefined)
|
|
30
|
+
return { problem: 'returned no structuredContent, although the tool declares an outputSchema', formatOnly: false };
|
|
31
|
+
let validate = validators.get(schema);
|
|
32
|
+
if (!validate) {
|
|
33
|
+
const draft2020 = typeof schema.$schema !== 'string' || schema.$schema.includes('2020-12');
|
|
34
|
+
const ajv = draft2020 ? new Ajv2020({ strict: false, allErrors: true }) : new Ajv({ strict: false, allErrors: true });
|
|
35
|
+
addFormats(ajv);
|
|
36
|
+
try {
|
|
37
|
+
validate = ajv.compile(schema);
|
|
38
|
+
}
|
|
39
|
+
catch {
|
|
40
|
+
return undefined;
|
|
41
|
+
}
|
|
42
|
+
validators.set(schema, validate);
|
|
43
|
+
}
|
|
44
|
+
if (validate(result.structuredContent))
|
|
45
|
+
return undefined;
|
|
46
|
+
const all = validate.errors ?? [];
|
|
47
|
+
const errors = all.slice(0, 3).map((e) => `${e.instancePath || '(the result)'} ${e.message ?? 'is invalid'}`);
|
|
48
|
+
return { problem: `returned structuredContent that doesn't match its outputSchema: ${errors.join('; ')}`, formatOnly: all.length > 0 && all.every((e) => e.keyword === 'format') };
|
|
49
|
+
}
|
package/dist/rules/search.js
CHANGED
|
@@ -25,7 +25,7 @@ export const findable = {
|
|
|
25
25
|
if (profile) {
|
|
26
26
|
// A client that defers tools does it at any size; one whose search results
|
|
27
27
|
// aren't documented (OpenAI's spec doesn't say how many) isn't ranked against a guess.
|
|
28
|
-
if (profile.defers.value === 'none' || tools.length < 2)
|
|
28
|
+
if (!profile.defers || profile.defers.value === 'none' || tools.length < 2)
|
|
29
29
|
return [];
|
|
30
30
|
if (!profile.searchLimit && ctx.client !== 'claude-code')
|
|
31
31
|
return [];
|
package/dist/rules/spec.d.ts
CHANGED
|
@@ -4,6 +4,16 @@ export declare function resultValidator(version: string, result?: string): impor
|
|
|
4
4
|
export declare const schema: Rule;
|
|
5
5
|
export declare const toolsCapability: Rule;
|
|
6
6
|
export declare const duplicateName: Rule;
|
|
7
|
+
/**
|
|
8
|
+
* What's wrong with a tool name, or undefined when it fits the spec's format. `hidden`:
|
|
9
|
+
* it has characters that act on a terminal or can't be seen, so it can pass for
|
|
10
|
+
* another name or for none.
|
|
11
|
+
*/
|
|
12
|
+
export declare function toolNameProblem(name: string): {
|
|
13
|
+
why: string;
|
|
14
|
+
hidden: boolean;
|
|
15
|
+
} | undefined;
|
|
16
|
+
export declare const toolName: Rule;
|
|
7
17
|
export declare const discover: Rule;
|
|
8
18
|
export declare const deprecated: Rule;
|
|
9
19
|
/**
|
|
@@ -21,3 +31,12 @@ export declare const cacheHints: Rule;
|
|
|
21
31
|
*/
|
|
22
32
|
export declare const extensionId: Rule;
|
|
23
33
|
export declare const taskRequired: Rule;
|
|
34
|
+
/**
|
|
35
|
+
* The SDK's rejection, readable: "Invalid result for tools/list: [ {...zod issues...} ]"
|
|
36
|
+
* spans many lines, and its first line alone said only "…tools/list: [" (the
|
|
37
|
+
* @pipeworx servers, bench 2026-11-09). Each issue becomes a detail line, "path: message".
|
|
38
|
+
*/
|
|
39
|
+
export declare function sdkIssues(error: string): {
|
|
40
|
+
summary: string;
|
|
41
|
+
detail: string[];
|
|
42
|
+
};
|
package/dist/rules/spec.js
CHANGED
|
@@ -4,6 +4,7 @@ import { Ajv } from 'ajv';
|
|
|
4
4
|
import { Ajv2020 } from 'ajv/dist/2020.js';
|
|
5
5
|
import addFormatsImport from 'ajv-formats';
|
|
6
6
|
import { kept, names } from './rule.js';
|
|
7
|
+
import { HIDDEN_SOURCE } from '../sanitize.js';
|
|
7
8
|
// ajv-formats ships CommonJS; under NodeNext its default import is the module object.
|
|
8
9
|
const addFormats = (addFormatsImport.default ?? addFormatsImport);
|
|
9
10
|
const SCHEMA_DIR = fileURLToPath(new URL('../../schemas/', import.meta.url));
|
|
@@ -54,8 +55,10 @@ export const schema = {
|
|
|
54
55
|
}
|
|
55
56
|
const findings = [];
|
|
56
57
|
if (ctx.clientError && ctx.pages.every((page) => validate(page))) {
|
|
58
|
+
const said = sdkIssues(ctx.clientError);
|
|
57
59
|
findings.push({
|
|
58
|
-
message: `The official MCP SDK client rejected the tools/list result, so clients built on it list no tools. The result does match the ${ctx.protocolVersion} schema; the SDK said: ${
|
|
60
|
+
message: `The official MCP SDK client rejected the tools/list result, so clients built on it list no tools. The result does match the ${ctx.protocolVersion} schema; the SDK said: ${said.summary}`,
|
|
61
|
+
...(said.detail.length ? { detail: said.detail } : {}),
|
|
59
62
|
fix: 'Fix what the SDK names above, then list the tools with the official client to confirm.',
|
|
60
63
|
});
|
|
61
64
|
}
|
|
@@ -108,6 +111,64 @@ export const duplicateName = {
|
|
|
108
111
|
}));
|
|
109
112
|
},
|
|
110
113
|
};
|
|
114
|
+
/** The tool-name format the spec recommends from 2025-11-25 (SEP-986): 1 to 128 of A-Z a-z 0-9 _ - . */
|
|
115
|
+
const TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
|
|
116
|
+
/** The characters reports show as escapes (sanitize.ts): one class, so what's flagged is what's escaped. */
|
|
117
|
+
const HIDDEN = new RegExp(HIDDEN_SOURCE, 'u');
|
|
118
|
+
const codePoint = (c) => `U+${c.codePointAt(0).toString(16).toUpperCase().padStart(4, '0')}`;
|
|
119
|
+
/**
|
|
120
|
+
* What's wrong with a tool name, or undefined when it fits the spec's format. `hidden`:
|
|
121
|
+
* it has characters that act on a terminal or can't be seen, so it can pass for
|
|
122
|
+
* another name or for none.
|
|
123
|
+
*/
|
|
124
|
+
export function toolNameProblem(name) {
|
|
125
|
+
if (TOOL_NAME.test(name))
|
|
126
|
+
return undefined;
|
|
127
|
+
const chars = [...name];
|
|
128
|
+
if (chars.length === 0)
|
|
129
|
+
return { why: 'it is empty', hidden: false };
|
|
130
|
+
const hidden = [...new Set(chars.filter((c) => HIDDEN.test(c)))];
|
|
131
|
+
const other = [...new Set(chars.filter((c) => !HIDDEN.test(c) && !/[A-Za-z0-9_.-]/.test(c)))];
|
|
132
|
+
// Printable ASCII as itself; anything else by code point too, so a lookalike can't hide.
|
|
133
|
+
const shown = other.map((c) => (c === ' ' ? 'a space' : /^[!-~]$/.test(c) ? `"${c}"` : `${codePoint(c)} "${c}"`));
|
|
134
|
+
const parts = [
|
|
135
|
+
...(hidden.length ? [`characters a terminal acts on or a reader can't see (${hidden.map(codePoint).join(', ')}: controls, invisible or text-direction characters)`] : []),
|
|
136
|
+
...(shown.length ? [shown.join(', ')] : []),
|
|
137
|
+
];
|
|
138
|
+
const long = chars.length > 128 ? `${chars.length} characters long, over 128` : '';
|
|
139
|
+
return { why: parts.length ? `it has ${parts.join('; and ')}${long ? `, and is ${long}` : ''}` : `it is ${long}`, hidden: hidden.length > 0 };
|
|
140
|
+
}
|
|
141
|
+
export const toolName = {
|
|
142
|
+
id: 'spec/tool-name',
|
|
143
|
+
severity: 'warn',
|
|
144
|
+
summary: "Tool names fit the format the spec recommends: 1 to 128 of A-Z, a-z, 0-9, _, - and .",
|
|
145
|
+
run(ctx) {
|
|
146
|
+
const bad = kept(ctx.menu.tools, ctx).flatMap((t) => {
|
|
147
|
+
const p = toolNameProblem(t.name);
|
|
148
|
+
return p ? [{ tool: t.name, ...p }] : [];
|
|
149
|
+
});
|
|
150
|
+
if (!bad.length)
|
|
151
|
+
return [];
|
|
152
|
+
// Hidden characters are an error on any protocol: the name can pass for another tool's.
|
|
153
|
+
// Otherwise a recommendation from 2025-11-25 on; before that the spec gave no format.
|
|
154
|
+
const hidden = bad.filter((b) => b.hidden);
|
|
155
|
+
const older = !!ctx.protocolVersion && ctx.protocolVersion < '2025-11-25';
|
|
156
|
+
return [
|
|
157
|
+
{
|
|
158
|
+
...(bad.length === 1 ? { tool: bad[0].tool } : {}),
|
|
159
|
+
...(hidden.length ? { severity: 'error' } : older ? { severity: 'info' } : {}),
|
|
160
|
+
message: `${bad.length === 1 ? `The tool name ${bad[0].tool} doesn't` : `${bad.length} tool names don't`} fit the tool name format the MCP spec recommends from 2025-11-25 (1 to 128 characters, A-Z, a-z, 0-9, _, - and .)` +
|
|
161
|
+
`${older ? `; this server speaks ${ctx.protocolVersion}, which gave no format, so it's for the move to 2025-11-25` : ''}. ` +
|
|
162
|
+
(hidden.length
|
|
163
|
+
? `${hidden.length === 1 ? (bad.length === 1 ? 'It has' : 'One has') : `${hidden.length} have`} characters that are hidden or act on the screen, so what an agent or a person reads isn't the name the server takes. `
|
|
164
|
+
: '') +
|
|
165
|
+
'Clients may refuse such a tool, rename it, or pass it to a model API that refuses it.',
|
|
166
|
+
detail: bad.slice(0, 12).map((b) => `${b.tool}: ${b.why}`).concat(bad.length > 12 ? [`and ${bad.length - 12} more`] : []),
|
|
167
|
+
fix: 'Name tools with letters, digits, _, - and . only (files_read or files.read, not "files read"), at most 128 characters.',
|
|
168
|
+
},
|
|
169
|
+
];
|
|
170
|
+
},
|
|
171
|
+
};
|
|
111
172
|
export const discover = {
|
|
112
173
|
id: 'spec/discover',
|
|
113
174
|
severity: 'info',
|
|
@@ -300,3 +361,27 @@ export const taskRequired = {
|
|
|
300
361
|
];
|
|
301
362
|
},
|
|
302
363
|
};
|
|
364
|
+
/**
|
|
365
|
+
* The SDK's rejection, readable: "Invalid result for tools/list: [ {...zod issues...} ]"
|
|
366
|
+
* spans many lines, and its first line alone said only "…tools/list: [" (the
|
|
367
|
+
* @pipeworx servers, bench 2026-11-09). Each issue becomes a detail line, "path: message".
|
|
368
|
+
*/
|
|
369
|
+
export function sdkIssues(error) {
|
|
370
|
+
const at = error.indexOf('[');
|
|
371
|
+
if (at !== -1) {
|
|
372
|
+
try {
|
|
373
|
+
const issues = JSON.parse(error.slice(at));
|
|
374
|
+
if (Array.isArray(issues) && issues.length) {
|
|
375
|
+
const detail = issues.slice(0, 10).map((i) => `${(i.path ?? []).join('.') || '(the result)'}: ${i.message ?? 'invalid'}`);
|
|
376
|
+
if (issues.length > 10)
|
|
377
|
+
detail.push(`…and ${issues.length - 10} more`);
|
|
378
|
+
return { summary: `${error.slice(0, at).trim().replace(/:$/, '')}, ${issues.length === 1 ? 'one problem' : `${issues.length} problems`}.`, detail };
|
|
379
|
+
}
|
|
380
|
+
}
|
|
381
|
+
catch {
|
|
382
|
+
// Not JSON after all: said as text below.
|
|
383
|
+
}
|
|
384
|
+
}
|
|
385
|
+
const flat = error.replace(/\s+/g, ' ').trim();
|
|
386
|
+
return { summary: flat.length > 300 ? `${flat.slice(0, 297)}…` : flat, detail: [] };
|
|
387
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Characters a terminal (or GitHub's log parser) acts on, or a reader can't see:
|
|
3
|
+
* controls (C0, C1, DEL), format characters (the bidi overrides and isolates that
|
|
4
|
+
* reorder what's shown, "Trojan Source"; zero-width spaces and joiners; the soft
|
|
5
|
+
* hyphen; tag characters), line and paragraph separators, everything Unicode says
|
|
6
|
+
* renders as nothing (variation selectors, Hangul fillers), and the blank braille
|
|
7
|
+
* cell. Newline and tab are in it: a server's newline would start a line of its own
|
|
8
|
+
* (a fake finding, a `::error::` workflow command). spec/tool-name uses the same class.
|
|
9
|
+
*/
|
|
10
|
+
export declare const HIDDEN_SOURCE = "[\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}\\p{Default_Ignorable_Code_Point}\\u2800]";
|
|
11
|
+
/** One field of server text, for the terminal: every control character shown as an escape. */
|
|
12
|
+
export declare function plain(text: string): string;
|
|
13
|
+
/**
|
|
14
|
+
* A whole report, last thing before it's printed: whatever control characters a field
|
|
15
|
+
* still carries are shown as escapes. Its own newlines and tabs stay; the fields that
|
|
16
|
+
* came from the server have already had theirs escaped by plain().
|
|
17
|
+
*/
|
|
18
|
+
export declare function terminalSafe(report: string): string;
|
|
19
|
+
export interface MdOptions {
|
|
20
|
+
/** In a table cell: pipes are escaped, even inside code spans (GFM requires it). */
|
|
21
|
+
cell?: boolean;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Text as a markdown code span that it can't close: a fence of backticks longer than
|
|
25
|
+
* any run inside it, padded when it starts or ends with one. Control characters are
|
|
26
|
+
* shown as escapes, so it's always one line.
|
|
27
|
+
*/
|
|
28
|
+
export declare function mdCode(text: string, options?: MdOptions): string;
|
|
29
|
+
/**
|
|
30
|
+
* A finding's text, or any line that carries server text, as markdown: toolmenu's own
|
|
31
|
+
* `code` spans stay code, everything else is escaped. A backtick in a server's text
|
|
32
|
+
* can only move where code starts and ends: every piece is rendered inert either way.
|
|
33
|
+
*/
|
|
34
|
+
export declare function mdText(text: string, options?: MdOptions): string;
|
|
35
|
+
/**
|
|
36
|
+
* The net under every field: from here on, text written to `stream` goes through
|
|
37
|
+
* terminalSafe(). For the CLI's stdout and stderr, whatever the command; JSON stays
|
|
38
|
+
* the same JSON (its escapes read back as the same characters). Twice is once.
|
|
39
|
+
*/
|
|
40
|
+
export declare function guardStream(stream: NodeJS.WritableStream): void;
|
|
41
|
+
/** Write past the net: only text already made safe, with toolmenu's own colour codes added. */
|
|
42
|
+
export declare function writeUnguarded(stream: NodeJS.WritableStream, text: string): void;
|
package/dist/sanitize.js
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Text a server chose (tool names, descriptions, versions, error output), made safe
|
|
3
|
+
* for where toolmenu prints it. The menu file keeps the exact bytes; only what's
|
|
4
|
+
* shown changes.
|
|
5
|
+
*
|
|
6
|
+
* Shown as escapes, not dropped: a name with an escape sequence in it reads
|
|
7
|
+
* `a\u001b[2Jb`, so the report says what the server really sent and two different
|
|
8
|
+
* names never look the same. spec/tool-name says what's wrong with such a name.
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Characters a terminal (or GitHub's log parser) acts on, or a reader can't see:
|
|
12
|
+
* controls (C0, C1, DEL), format characters (the bidi overrides and isolates that
|
|
13
|
+
* reorder what's shown, "Trojan Source"; zero-width spaces and joiners; the soft
|
|
14
|
+
* hyphen; tag characters), line and paragraph separators, everything Unicode says
|
|
15
|
+
* renders as nothing (variation selectors, Hangul fillers), and the blank braille
|
|
16
|
+
* cell. Newline and tab are in it: a server's newline would start a line of its own
|
|
17
|
+
* (a fake finding, a `::error::` workflow command). spec/tool-name uses the same class.
|
|
18
|
+
*/
|
|
19
|
+
export const HIDDEN_SOURCE = '[\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}\\p{Default_Ignorable_Code_Point}\\u2800]';
|
|
20
|
+
const UNSAFE = new RegExp(HIDDEN_SOURCE, 'gu');
|
|
21
|
+
// The same but newline and tab, for a report whose own lines are already made.
|
|
22
|
+
const UNSAFE_IN_REPORT = new RegExp(`(?![\\n\\t])${HIDDEN_SOURCE}`, 'gu');
|
|
23
|
+
const NAMED = { '\n': '\\n', '\r': '\\r', '\t': '\\t' };
|
|
24
|
+
/**
|
|
25
|
+
* A character as an escape: \u001b; past the first plane as its UTF-16 pair
|
|
26
|
+
* (\udb40\udc41), which JSON and JavaScript read back as the same character, so a
|
|
27
|
+
* JSON report run through terminalSafe() is still the same JSON.
|
|
28
|
+
*/
|
|
29
|
+
const visible = (c) => NAMED[c] ??
|
|
30
|
+
[...Array(c.length).keys()].map((i) => `\\u${c.charCodeAt(i).toString(16).padStart(4, '0')}`).join('');
|
|
31
|
+
/** One field of server text, for the terminal: every control character shown as an escape. */
|
|
32
|
+
export function plain(text) {
|
|
33
|
+
return text.replace(UNSAFE, visible);
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* A whole report, last thing before it's printed: whatever control characters a field
|
|
37
|
+
* still carries are shown as escapes. Its own newlines and tabs stay; the fields that
|
|
38
|
+
* came from the server have already had theirs escaped by plain().
|
|
39
|
+
*/
|
|
40
|
+
export function terminalSafe(report) {
|
|
41
|
+
return report.replace(UNSAFE_IN_REPORT, visible);
|
|
42
|
+
}
|
|
43
|
+
/** Links toolmenu's own messages make, kept clickable in markdown. */
|
|
44
|
+
const OWN_LINKS = ['https://github.com/niksa90/toolmenu', 'https://code.claude.com/docs/', 'https://modelcontextprotocol.io/'];
|
|
45
|
+
/**
|
|
46
|
+
* Markdown that GitHub would act on in plain text: links and images ([ ] !), HTML
|
|
47
|
+
* and autolinks (< >), entities (&), escapes, table cells (|) and bold (*). Not _ or
|
|
48
|
+
* ~: they're in most tool names, and at worst they italicize or strike text through.
|
|
49
|
+
*/
|
|
50
|
+
const MD_SPECIAL = /[\\`*[\]<>!|&]/;
|
|
51
|
+
/** MD_SPECIAL, and what GitHub links on its own: @mentions, #refs and GH-refs, bare URLs. */
|
|
52
|
+
const MD_INERT = new RegExp(`${MD_SPECIAL.source}|@|#(?=\\d)|\\bGH-(?=\\d)|:\\/\\/|\\bwww\\.`, 'gi');
|
|
53
|
+
const MD_ESCAPE = { '&': '&', '<': '<', '>': '>' };
|
|
54
|
+
/** A zero-width space, as an entity: breaks a mention, reference or autolink without showing. */
|
|
55
|
+
const ZWSP = '​';
|
|
56
|
+
/**
|
|
57
|
+
* A link toolmenu's own messages make: one of OWN_LINKS, then the end, "/", "#" or "?",
|
|
58
|
+
* with no dot segments (/../ would leave the path the prefix names) and nothing that
|
|
59
|
+
* markdown or a URL parser reads specially.
|
|
60
|
+
*/
|
|
61
|
+
function ownLink(url) {
|
|
62
|
+
return OWN_LINKS.some((p) => url.startsWith(p) && (p.endsWith('/') || url.length === p.length || '/#?'.includes(url[p.length]))) && !/(^|[\\/])\.\.?([\\/?#]|$)|%2e|[\\\\*[\]!&@]/i.test(url);
|
|
63
|
+
}
|
|
64
|
+
/** Plain text (no backticks in it) as inert markdown. */
|
|
65
|
+
function mdPlain(text) {
|
|
66
|
+
let out = '';
|
|
67
|
+
// A link toolmenu itself makes stays a link; anything else that would autolink doesn't.
|
|
68
|
+
const parts = text.split(/(https?:\/\/[^\s<>()|`]+)/);
|
|
69
|
+
parts.forEach((part, i) => {
|
|
70
|
+
if (i % 2 === 1 && ownLink(part)) {
|
|
71
|
+
out += part;
|
|
72
|
+
return;
|
|
73
|
+
}
|
|
74
|
+
// One pass, so no replacement sees another's output (the # of an entity).
|
|
75
|
+
out += part.replace(MD_INERT, (m) => {
|
|
76
|
+
if (m === '@' || m === '#')
|
|
77
|
+
return `${m}${ZWSP}`; // no mention or mailto link; no cross-reference on an issue
|
|
78
|
+
if (/^GH-$/i.test(m))
|
|
79
|
+
return `${m.slice(0, 2)}${ZWSP}-`;
|
|
80
|
+
if (m === '://')
|
|
81
|
+
return `:${ZWSP}//`; // https://…: shown, not linked
|
|
82
|
+
if (/^www\./i.test(m))
|
|
83
|
+
return `${m.slice(0, 3)}${ZWSP}.`;
|
|
84
|
+
return MD_ESCAPE[m] ?? `\\${m}`;
|
|
85
|
+
});
|
|
86
|
+
});
|
|
87
|
+
return out;
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* Text as a markdown code span that it can't close: a fence of backticks longer than
|
|
91
|
+
* any run inside it, padded when it starts or ends with one. Control characters are
|
|
92
|
+
* shown as escapes, so it's always one line.
|
|
93
|
+
*/
|
|
94
|
+
export function mdCode(text, options = {}) {
|
|
95
|
+
const shown = plain(text);
|
|
96
|
+
if (!shown)
|
|
97
|
+
return '';
|
|
98
|
+
// A loop, not Math.max(...runs): a name with 100k backtick runs would overflow the stack.
|
|
99
|
+
let longest = 0;
|
|
100
|
+
for (const run of shown.matchAll(/`+/g))
|
|
101
|
+
longest = Math.max(longest, run[0].length);
|
|
102
|
+
const fence = '`'.repeat(longest + 1);
|
|
103
|
+
const pad = /^[`\s]|[`\s]$/.test(shown) ? ' ' : '';
|
|
104
|
+
const body = options.cell ? shown.replace(/\|/g, '\\|') : shown;
|
|
105
|
+
return `${fence}${pad}${body}${pad}${fence}`;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* A finding's text, or any line that carries server text, as markdown: toolmenu's own
|
|
109
|
+
* `code` spans stay code, everything else is escaped. A backtick in a server's text
|
|
110
|
+
* can only move where code starts and ends: every piece is rendered inert either way.
|
|
111
|
+
*/
|
|
112
|
+
export function mdText(text, options = {}) {
|
|
113
|
+
const pieces = plain(text).split('`');
|
|
114
|
+
// An unpaired backtick: the last piece is text, the backtick shown.
|
|
115
|
+
const unpaired = pieces.length % 2 === 0;
|
|
116
|
+
return pieces
|
|
117
|
+
.map((piece, i) => {
|
|
118
|
+
const last = i === pieces.length - 1;
|
|
119
|
+
if (i % 2 === 1 && !(unpaired && last))
|
|
120
|
+
return mdCode(piece, options);
|
|
121
|
+
const escaped = mdPlain(piece);
|
|
122
|
+
return unpaired && last ? `\\\`${escaped}` : escaped;
|
|
123
|
+
})
|
|
124
|
+
.join('');
|
|
125
|
+
}
|
|
126
|
+
const unguarded = new WeakMap();
|
|
127
|
+
/**
|
|
128
|
+
* The net under every field: from here on, text written to `stream` goes through
|
|
129
|
+
* terminalSafe(). For the CLI's stdout and stderr, whatever the command; JSON stays
|
|
130
|
+
* the same JSON (its escapes read back as the same characters). Twice is once.
|
|
131
|
+
*/
|
|
132
|
+
export function guardStream(stream) {
|
|
133
|
+
if (unguarded.has(stream))
|
|
134
|
+
return;
|
|
135
|
+
const write = stream.write.bind(stream);
|
|
136
|
+
unguarded.set(stream, write);
|
|
137
|
+
stream.write = (chunk, ...rest) => write(typeof chunk === 'string' ? terminalSafe(chunk) : chunk, ...rest);
|
|
138
|
+
}
|
|
139
|
+
/** Write past the net: only text already made safe, with toolmenu's own colour codes added. */
|
|
140
|
+
export function writeUnguarded(stream, text) {
|
|
141
|
+
(unguarded.get(stream) ?? stream.write.bind(stream))(text);
|
|
142
|
+
}
|
package/dist/sarif.d.ts
CHANGED
|
@@ -11,4 +11,6 @@ export interface SarifOptions {
|
|
|
11
11
|
export declare function repoRoot(from?: string): string;
|
|
12
12
|
/** The line of each tool's "name" in a menu file written by toolmenu (1-based). */
|
|
13
13
|
export declare function toolLines(text: string): Map<string, number>;
|
|
14
|
+
/** The tools a finding is about: its tool, or each tool of a change found in several. JUnit uses it too. */
|
|
15
|
+
export declare function toolsOf(f: Finding): string[];
|
|
14
16
|
export declare function toSarif(findings: Finding[], options: SarifOptions): string;
|
package/dist/sarif.js
CHANGED
|
@@ -46,8 +46,8 @@ export function toolLines(text) {
|
|
|
46
46
|
}
|
|
47
47
|
return lines;
|
|
48
48
|
}
|
|
49
|
-
/** The tools a finding is about: its tool, or each tool of a change found in several. */
|
|
50
|
-
function toolsOf(f) {
|
|
49
|
+
/** The tools a finding is about: its tool, or each tool of a change found in several. JUnit uses it too. */
|
|
50
|
+
export function toolsOf(f) {
|
|
51
51
|
const several = f.tools;
|
|
52
52
|
if (Array.isArray(several))
|
|
53
53
|
return several.filter((t) => typeof t === 'string');
|
package/dist/scan.d.ts
CHANGED
|
@@ -15,11 +15,18 @@ export interface ScanEntry {
|
|
|
15
15
|
}
|
|
16
16
|
export declare class ListError extends Error {
|
|
17
17
|
}
|
|
18
|
+
/**
|
|
19
|
+
* Which environment variables a config's ${VAR} may be filled from: the names given
|
|
20
|
+
* with --allow-env, or all of them ('*'). None by default: the config file picks
|
|
21
|
+
* where each value goes (a URL, a header, a server's arguments), so a config from
|
|
22
|
+
* someone else could send any of your environment to a server of theirs.
|
|
23
|
+
*/
|
|
24
|
+
export type AllowEnv = ReadonlySet<string> | '*';
|
|
18
25
|
/** Words of a command line: whitespace-separated, with '…' and "…" kept together. */
|
|
19
26
|
export declare function splitCommand(line: string): string[];
|
|
20
27
|
/** The servers in a list file, unique names (a repeat gets #2, #3). */
|
|
21
|
-
export declare function parseList(text: string, file: string, env?: NodeJS.ProcessEnv): ScanEntry[];
|
|
22
|
-
export declare function loadList(file: string): Promise<ScanEntry[]>;
|
|
28
|
+
export declare function parseList(text: string, file: string, env?: NodeJS.ProcessEnv, allow?: AllowEnv): ScanEntry[];
|
|
29
|
+
export declare function loadList(file: string, allow?: AllowEnv): Promise<ScanEntry[]>;
|
|
23
30
|
export interface ScanRow {
|
|
24
31
|
name: string;
|
|
25
32
|
/** Where the server is, printable: a URL without its query, or the command line. Never headers or env values. */
|
package/dist/scan.js
CHANGED
|
@@ -8,16 +8,27 @@
|
|
|
8
8
|
import { readFile } from 'node:fs/promises';
|
|
9
9
|
import { ConnectError, clean, commandLine } from './explain.js';
|
|
10
10
|
import { counts, findingLines, githubLines, mdFindings } from './report.js';
|
|
11
|
+
import { mdCode, mdText, plain } from './sanitize.js';
|
|
11
12
|
import { snapshot } from './snapshot.js';
|
|
13
|
+
import { jsonErrorAt } from './menu.js';
|
|
12
14
|
import { SEVERITY_RANK } from './types.js';
|
|
13
15
|
export class ListError extends Error {
|
|
14
16
|
}
|
|
15
|
-
/** `${VAR}`, `${VAR:-default}` (Claude Code) and `${env:VAR}` (VS Code), from the environment. */
|
|
16
|
-
function expand(value, env, missing) {
|
|
17
|
+
/** `${VAR}`, `${VAR:-default}` (Claude Code) and `${env:VAR}` (VS Code), from the environment, where allowed. */
|
|
18
|
+
function expand(value, env, missing, allow, blocked) {
|
|
17
19
|
return value.replace(/\$\{(?:env:)?([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_, name, fallback) => {
|
|
20
|
+
const allowed = allow === '*' || allow.has(name);
|
|
21
|
+
// Not allowed: the environment isn't read at all. With a default, the default, set
|
|
22
|
+
// or not, so a server can't learn which variables exist from which URL it gets.
|
|
23
|
+
if (!allowed && fallback !== undefined)
|
|
24
|
+
return fallback;
|
|
18
25
|
const v = env[name];
|
|
19
|
-
if (v !== undefined && v !== '')
|
|
20
|
-
|
|
26
|
+
if (v !== undefined && v !== '') {
|
|
27
|
+
if (allowed)
|
|
28
|
+
return v;
|
|
29
|
+
blocked.add(name);
|
|
30
|
+
return '';
|
|
31
|
+
}
|
|
21
32
|
if (fallback !== undefined)
|
|
22
33
|
return fallback;
|
|
23
34
|
missing.add(name);
|
|
@@ -33,21 +44,23 @@ function record(v) {
|
|
|
33
44
|
return Object.fromEntries(Object.entries(v).filter(([, x]) => typeof x === 'string'));
|
|
34
45
|
}
|
|
35
46
|
/** One server from a client config: `{ command, args, env, cwd }` or `{ url, headers }`. */
|
|
36
|
-
function fromConfig(name, raw, env) {
|
|
47
|
+
function fromConfig(name, raw, env, allow) {
|
|
37
48
|
if (!raw || typeof raw !== 'object')
|
|
38
49
|
return { name, problem: 'not an object' };
|
|
39
50
|
const s = raw;
|
|
40
51
|
if (s.disabled === true || s.enabled === false)
|
|
41
52
|
return { name, disabled: true };
|
|
42
53
|
const missing = new Set();
|
|
43
|
-
const
|
|
54
|
+
const blocked = new Set();
|
|
55
|
+
const x = (v) => expand(v, env, missing, allow, blocked);
|
|
44
56
|
const map = (r) => (r ? Object.fromEntries(Object.entries(r).map(([k, v]) => [k, x(v)])) : undefined);
|
|
45
57
|
const type = typeof s.type === 'string' ? s.type : typeof s.transport === 'string' ? s.transport : undefined;
|
|
46
58
|
let target;
|
|
47
59
|
if (typeof s.url === 'string' || typeof s.serverUrl === 'string' || typeof s.httpUrl === 'string') {
|
|
48
60
|
if (type === 'sse')
|
|
49
61
|
return { name, problem: 'HTTP+SSE transport, which toolmenu doesn\'t speak (Streamable HTTP only)' };
|
|
50
|
-
const
|
|
62
|
+
const raw = [s.url, s.serverUrl, s.httpUrl].find((u) => typeof u === 'string');
|
|
63
|
+
const url = x(raw);
|
|
51
64
|
const headers = map(record(s.headers));
|
|
52
65
|
target = { kind: 'http', url, ...(headers && Object.keys(headers).length ? { headers } : {}) };
|
|
53
66
|
}
|
|
@@ -65,13 +78,19 @@ function fromConfig(name, raw, env) {
|
|
|
65
78
|
}
|
|
66
79
|
else
|
|
67
80
|
return { name, problem: 'neither a command nor a url' };
|
|
81
|
+
// Set but not allowed: not checked, rather than checked with the value left out.
|
|
82
|
+
if (blocked.size) {
|
|
83
|
+
const list = [...blocked].sort();
|
|
84
|
+
return { name, problem: `${list.join(', ')} ${list.length === 1 ? 'is' : 'are'} set, but not passed in: scan fills \${VAR} only from the variables named with --allow-env (--allow-env ${list.join(',')}), so a config can't send the rest of your environment anywhere` };
|
|
85
|
+
}
|
|
68
86
|
// A missing variable would send an empty credential: say so instead of checking a server set up wrong.
|
|
69
87
|
if (missing.size)
|
|
70
88
|
return { name, problem: `${[...missing].join(', ')} ${missing.size === 1 ? 'is' : 'are'} not set (the config refers to ${missing.size === 1 ? 'it' : 'them'})` };
|
|
89
|
+
// The URL as the config writes it: a filled-in ${VAR} may be a secret.
|
|
71
90
|
if (target.kind === 'http' && !/^https?:\/\//.test(target.url))
|
|
72
|
-
return { name, problem: `"${clean(
|
|
91
|
+
return { name, problem: `"${clean([s.url, s.serverUrl, s.httpUrl].find((u) => typeof u === 'string'), 60)}" isn't an http(s) URL` };
|
|
73
92
|
const shown = target.kind === 'http'
|
|
74
|
-
? { kind: 'http', url:
|
|
93
|
+
? { kind: 'http', url: [s.url, s.serverUrl, s.httpUrl].find((u) => typeof u === 'string') }
|
|
75
94
|
: { kind: 'stdio', command: s.command, args: s.args ?? [] };
|
|
76
95
|
return { name, target, shown };
|
|
77
96
|
}
|
|
@@ -161,7 +180,7 @@ function fromLines(text) {
|
|
|
161
180
|
return entries;
|
|
162
181
|
}
|
|
163
182
|
/** The servers in a list file, unique names (a repeat gets #2, #3). */
|
|
164
|
-
export function parseList(text, file, env = process.env) {
|
|
183
|
+
export function parseList(text, file, env = process.env, allow = new Set()) {
|
|
165
184
|
let entries;
|
|
166
185
|
if (/\.jsonc?$/i.test(file) || /^\s*\{/.test(text)) {
|
|
167
186
|
let json;
|
|
@@ -170,13 +189,14 @@ export function parseList(text, file, env = process.env) {
|
|
|
170
189
|
json = JSON.parse(text.replace(/^\s*\/\/.*$/gm, ''));
|
|
171
190
|
}
|
|
172
191
|
catch (error) {
|
|
173
|
-
|
|
192
|
+
const at = jsonErrorAt(error);
|
|
193
|
+
throw new ListError(`${file} isn't valid JSON${at ? ` (${at})` : ''}`);
|
|
174
194
|
}
|
|
175
195
|
const j = json;
|
|
176
196
|
const servers = j.mcpServers ?? j.servers ?? j.mcp?.servers ?? j['mcp.servers'];
|
|
177
197
|
if (!servers || typeof servers !== 'object' || Array.isArray(servers))
|
|
178
198
|
throw new ListError(`${file} has no mcpServers or servers object, the key MCP clients keep their servers under`);
|
|
179
|
-
entries = Object.entries(servers).map(([name, raw]) => fromConfig(name, raw, env));
|
|
199
|
+
entries = Object.entries(servers).map(([name, raw]) => fromConfig(name, raw, env, allow));
|
|
180
200
|
}
|
|
181
201
|
else
|
|
182
202
|
entries = fromLines(text);
|
|
@@ -189,7 +209,7 @@ export function parseList(text, file, env = process.env) {
|
|
|
189
209
|
return n === 1 ? e : { ...e, name: `${e.name}#${n}` };
|
|
190
210
|
});
|
|
191
211
|
}
|
|
192
|
-
export async function loadList(file) {
|
|
212
|
+
export async function loadList(file, allow = new Set()) {
|
|
193
213
|
let text;
|
|
194
214
|
try {
|
|
195
215
|
text = await readFile(file, 'utf8');
|
|
@@ -197,7 +217,7 @@ export async function loadList(file) {
|
|
|
197
217
|
catch (error) {
|
|
198
218
|
throw new ListError(`couldn't read ${file}: ${error.code ?? error.message}`);
|
|
199
219
|
}
|
|
200
|
-
return parseList(text, file);
|
|
220
|
+
return parseList(text, file, process.env, allow);
|
|
201
221
|
}
|
|
202
222
|
/** Printable location. A URL's query and credentials can hold keys, so they're left out. */
|
|
203
223
|
export function where(target) {
|
|
@@ -297,33 +317,35 @@ export function formatScan(rows, format, file) {
|
|
|
297
317
|
if (format === 'github') {
|
|
298
318
|
const lines = [];
|
|
299
319
|
for (const r of rows) {
|
|
320
|
+
// The title ends at the first comma or "::": the name goes in the message.
|
|
300
321
|
if (r.failed)
|
|
301
|
-
lines.push(`::error title=toolmenu scan
|
|
322
|
+
lines.push(`::error title=toolmenu scan::${plain(`${r.name}: ${status(r)}`).replace(/%/g, '%25')}`);
|
|
302
323
|
lines.push(...githubLines(r.findings.map((f) => ({ ...f, message: `${r.name}: ${f.message}` }))));
|
|
303
324
|
}
|
|
304
325
|
return lines.join('\n');
|
|
305
326
|
}
|
|
306
327
|
if (format === 'markdown') {
|
|
307
|
-
const cell = (t) => t
|
|
308
|
-
const lines = [`### toolmenu scan: ${
|
|
328
|
+
const cell = (t) => mdText(t, { cell: true });
|
|
329
|
+
const lines = [`### toolmenu scan: ${mdText(file)}`, '', '| Server | Tools | Tokens | Findings |', '|---|--:|--:|---|'];
|
|
309
330
|
for (const r of rows)
|
|
310
|
-
lines.push(`|
|
|
331
|
+
lines.push(`| ${mdCode(r.name, { cell: true })} | ${r.menu ? r.menu.tools.length : '–'} | ${r.menu ? `~${tokens(r.menu.totalTokens)}` : '–'} | ${cell(status(r))} |`);
|
|
311
332
|
lines.push('', totals(rows));
|
|
312
333
|
for (const r of rows.filter((x) => x.findings.length))
|
|
313
|
-
lines.push('', `####
|
|
334
|
+
lines.push('', `#### ${mdCode(r.name)}`, '', ...mdFindings(r.findings));
|
|
314
335
|
return lines.join('\n');
|
|
315
336
|
}
|
|
316
|
-
const nameWidth = Math.min(32, Math.max(6, ...rows.map((r) => r.name.length)));
|
|
317
|
-
const lines = [`toolmenu scan ${file}`, ''];
|
|
337
|
+
const nameWidth = Math.min(32, Math.max(6, ...rows.map((r) => plain(r.name).length)));
|
|
338
|
+
const lines = [`toolmenu scan ${plain(file)}`, ''];
|
|
318
339
|
lines.push(` ${'server'.padEnd(nameWidth)} ${'tools'.padStart(5)} ${'tokens'.padStart(6)} findings`);
|
|
319
340
|
for (const r of rows) {
|
|
320
|
-
const
|
|
321
|
-
|
|
341
|
+
const shown = plain(r.name);
|
|
342
|
+
const name = shown.length > nameWidth ? `${shown.slice(0, nameWidth - 1)}…` : shown;
|
|
343
|
+
lines.push(` ${name.padEnd(nameWidth)} ${(r.menu ? String(r.menu.tools.length) : '–').padStart(5)} ${(r.menu ? `~${tokens(r.menu.totalTokens)}` : '–').padStart(6)} ${plain(status(r))}`);
|
|
322
344
|
}
|
|
323
345
|
lines.push('', totals(rows));
|
|
324
346
|
for (const r of rows.filter((x) => x.findings.length)) {
|
|
325
347
|
const s = r.menu.server;
|
|
326
|
-
lines.push('', `── ${r.name} ${s.name ?? ''} ${s.version ?? ''} · protocol ${s.protocolVersion ?? 'unknown'}`.trimEnd(), '');
|
|
348
|
+
lines.push('', `── ${plain(r.name)} ${plain(s.name ?? '')} ${plain(s.version ?? '')} · protocol ${plain(s.protocolVersion ?? 'unknown')}`.trimEnd(), '');
|
|
327
349
|
lines.push(...findingLines(r.findings).filter((l, i, all) => !(i === all.length - 1 && l === '')));
|
|
328
350
|
}
|
|
329
351
|
if (rows.some((r) => r.wantsCredentials))
|
package/dist/session.d.ts
CHANGED
|
@@ -65,6 +65,21 @@ export interface StepRecord {
|
|
|
65
65
|
tools: number;
|
|
66
66
|
tokens: number;
|
|
67
67
|
}
|
|
68
|
+
/**
|
|
69
|
+
* A tool in the menu after a step: its tokens, and whether this step inserted, appended,
|
|
70
|
+
* moved or edited it. Tools the step removed come last, marked removed.
|
|
71
|
+
*/
|
|
72
|
+
export interface StepTool {
|
|
73
|
+
name: string;
|
|
74
|
+
tokens: number;
|
|
75
|
+
change?: 'inserted' | 'appended' | 'moved' | 'edited' | 'removed';
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* What a step's changes did to each tool of the menu after it, by position (two tools
|
|
79
|
+
* can share a name). An added tool is appended when only added tools follow it. The
|
|
80
|
+
* tools it removed (from `before`, the menu before the step) follow, marked removed.
|
|
81
|
+
*/
|
|
82
|
+
export declare function stepMenu(tools: MenuTool[], changes?: ToolChange[], before?: MenuTool[]): StepTool[];
|
|
68
83
|
export interface SessionResult {
|
|
69
84
|
scenario: string;
|
|
70
85
|
server: Menu['server'];
|
|
@@ -108,6 +123,8 @@ export interface SessionOptions {
|
|
|
108
123
|
unionOut?: boolean;
|
|
109
124
|
/** session --auto: what the plan called and skipped, so a run that called nothing isn't a clean one. */
|
|
110
125
|
auto?: AutoSummary;
|
|
126
|
+
/** Called with the menu after each step that listed it (stepMenu), for the HTML report. Not part of the result, so no report carries it. */
|
|
127
|
+
onStepMenu?: (step: number, menu: StepTool[]) => void;
|
|
111
128
|
/** Waits before retrying a request refused for being too many (default 2, 4, 8, 16, 32 s: a per-minute limit clears within them). */
|
|
112
129
|
rateLimitWaitsMs?: number[];
|
|
113
130
|
}
|