toolmenu 0.25.2 → 0.27.1
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 +170 -683
- 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 +151 -49
- 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 -18
- 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 +6 -1
- package/dist/junit.js +12 -3
- package/dist/mcp-env.d.ts +6 -0
- package/dist/mcp-env.js +6 -0
- package/dist/mcp.d.ts +11 -1
- package/dist/mcp.js +123 -22
- package/dist/menu.d.ts +6 -0
- package/dist/menu.js +12 -1
- package/dist/options.d.ts +10 -0
- package/dist/options.js +3 -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/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
package/dist/diff.js
CHANGED
|
@@ -79,6 +79,31 @@ export const DIFF_RULES = {
|
|
|
79
79
|
'diff/resources': { severity: 'info', class: 'notice' },
|
|
80
80
|
'diff/lists-unread': { severity: 'info' },
|
|
81
81
|
};
|
|
82
|
+
/**
|
|
83
|
+
* The tools diffMenus compares and how they changed: ignored tools leave the
|
|
84
|
+
* comparison entirely, so they can't pair into a rename or show up as a reorder.
|
|
85
|
+
* The HTML report shows the same.
|
|
86
|
+
*/
|
|
87
|
+
export function comparedTools(before, after, ignore) {
|
|
88
|
+
const ignored = ignoreMatcher(ignore);
|
|
89
|
+
const oldTools = before.tools.filter((t) => !ignored(t.name));
|
|
90
|
+
const positions = [];
|
|
91
|
+
const newTools = after.tools.filter((t, i) => !ignored(t.name) && positions.push(i) > 0);
|
|
92
|
+
const oldNames = new Set(oldTools.map((t) => t.name));
|
|
93
|
+
const newNames = new Set(newTools.map((t) => t.name));
|
|
94
|
+
const renames = findRenames(oldTools.filter((t) => !newNames.has(t.name)), newTools.filter((t) => !oldNames.has(t.name)));
|
|
95
|
+
const from = new Set(renames.map((r) => r.from.name));
|
|
96
|
+
const to = new Set(renames.map((r) => r.to.name));
|
|
97
|
+
return {
|
|
98
|
+
before: oldTools,
|
|
99
|
+
after: newTools,
|
|
100
|
+
positions,
|
|
101
|
+
ignored: after.tools.length - newTools.length,
|
|
102
|
+
added: newTools.filter((t) => !oldNames.has(t.name) && !to.has(t.name)).map((t) => t.name),
|
|
103
|
+
removed: oldTools.filter((t) => !newNames.has(t.name) && !from.has(t.name)).map((t) => t.name),
|
|
104
|
+
renamed: renames.map((r) => ({ from: r.from.name, to: r.to.name })),
|
|
105
|
+
};
|
|
106
|
+
}
|
|
82
107
|
/**
|
|
83
108
|
* In fixes: the release a breaking change should ship in. Resolved once the
|
|
84
109
|
* versions are known (resolveFixes): "release it as 2.0.0", or "ship it in a
|
|
@@ -92,16 +117,15 @@ export function diffMenus(before, after, options = {}) {
|
|
|
92
117
|
const modern = isModern(after);
|
|
93
118
|
// A tool the old release already lost to a bad annotation isn't news; on a 2025 server it lost nothing.
|
|
94
119
|
const headers = { headers: modern, oldHeaders: isModern(before) };
|
|
95
|
-
// Ignored tools leave the comparison entirely, so they can't pair into a
|
|
96
|
-
// rename or show up as a reorder.
|
|
97
120
|
const ignored = ignoreMatcher(options.ignore);
|
|
98
|
-
const
|
|
99
|
-
const
|
|
121
|
+
const compared = comparedTools(before, after, options.ignore);
|
|
122
|
+
const oldTools = compared.before;
|
|
123
|
+
const newTools = compared.after;
|
|
100
124
|
const oldByName = new Map(oldTools.map((t) => [t.name, t]));
|
|
101
125
|
const newByName = new Map(newTools.map((t) => [t.name, t]));
|
|
102
126
|
const removed = oldTools.filter((t) => !newByName.has(t.name));
|
|
103
127
|
const added = newTools.filter((t) => !oldByName.has(t.name));
|
|
104
|
-
const renames =
|
|
128
|
+
const renames = compared.renamed.map((r) => ({ from: oldByName.get(r.from), to: newByName.get(r.to) }));
|
|
105
129
|
const renamedFrom = new Set(renames.map((r) => r.from.name));
|
|
106
130
|
const renamedTo = new Set(renames.map((r) => r.to.name));
|
|
107
131
|
for (const { from, to } of renames) {
|
|
@@ -813,7 +837,23 @@ function sameKind(a, b) {
|
|
|
813
837
|
* path, and the path nested fields hang off: `gen.rows[]` for array items,
|
|
814
838
|
* `gen.block(kind="text")` for a union option.
|
|
815
839
|
*/
|
|
816
|
-
|
|
840
|
+
/**
|
|
841
|
+
* A schema as an object. JSON Schema allows `true` (anything) and `false` (nothing)
|
|
842
|
+
* as a whole schema (`"items": true`, figma-mcp-rs); a broken server may send null or
|
|
843
|
+
* a string. Those are wrapped, not dropped, so a change to them still shows.
|
|
844
|
+
*/
|
|
845
|
+
export function asSchema(node) {
|
|
846
|
+
if (node === true)
|
|
847
|
+
return {};
|
|
848
|
+
if (node === false)
|
|
849
|
+
return { not: {} };
|
|
850
|
+
if (node && typeof node === 'object' && !Array.isArray(node))
|
|
851
|
+
return node;
|
|
852
|
+
return { 'x-toolmenu-not-a-schema': node };
|
|
853
|
+
}
|
|
854
|
+
function compareSchema(w, at, rawBefore, rawAfter, depth) {
|
|
855
|
+
const before = asSchema(rawBefore);
|
|
856
|
+
const after = asSchema(rawAfter);
|
|
817
857
|
// Past the limit, a change is said as such, not passed off as an unclassified one.
|
|
818
858
|
if (depth >= MAX_DEPTH) {
|
|
819
859
|
if (canonical(sameTypes(before)) !== canonical(sameTypes(after))) {
|
|
@@ -841,7 +881,10 @@ function compareSchema(w, at, before, after, depth) {
|
|
|
841
881
|
if (accepts(after, before))
|
|
842
882
|
say(w, 'diff/type-widened', at, ` now accepts more types: ${pair}`, '', [before, after]);
|
|
843
883
|
else {
|
|
844
|
-
|
|
884
|
+
// Only the types the new schema no longer takes: null|string → string loses null.
|
|
885
|
+
const newTypes = new Set(typesOf(after) ?? []);
|
|
886
|
+
const lost = [...new Set(typesOf(before) ?? [])].filter((t) => !newTypes.has(t) && !(t === 'integer' && newTypes.has('number'))).sort().join(' or ');
|
|
887
|
+
say(w, 'diff/param-type', at, ` changed type: ${pair}`, `Calls that send ${lost ? `${article(lost)} ${lost}` : 'any other type'} fail validation.`, [before, after], {
|
|
845
888
|
fix: oldType && newType ? `Accept both (${[...new Set([...oldType.split('|'), ...newType.split('|')])].join('|')}) for one release, or ${BREAKING_RELEASE}.` : `Restore the old type, or ${BREAKING_RELEASE}.`,
|
|
846
889
|
});
|
|
847
890
|
}
|
|
@@ -909,7 +952,7 @@ function compareSchema(w, at, before, after, depth) {
|
|
|
909
952
|
* node's), as the one option.
|
|
910
953
|
*/
|
|
911
954
|
function optionsOf(s) {
|
|
912
|
-
const options = unionOptions(s);
|
|
955
|
+
const options = unionOptions(s)?.map(asSchema);
|
|
913
956
|
return options && options.length > 0 ? options : [undescribed(s)];
|
|
914
957
|
}
|
|
915
958
|
/**
|
|
@@ -1168,9 +1211,10 @@ function discriminator(options) {
|
|
|
1168
1211
|
const names = Object.keys(own[0].properties).sort();
|
|
1169
1212
|
return names.find((n) => own.every((o) => fixedValue(o.properties[n]) !== undefined));
|
|
1170
1213
|
}
|
|
1171
|
-
function fixedValue(
|
|
1172
|
-
if (
|
|
1214
|
+
function fixedValue(raw) {
|
|
1215
|
+
if (raw === undefined)
|
|
1173
1216
|
return undefined;
|
|
1217
|
+
const s = asSchema(raw);
|
|
1174
1218
|
if ('const' in s)
|
|
1175
1219
|
return s.const;
|
|
1176
1220
|
return Array.isArray(s.enum) && s.enum.length === 1 ? s.enum[0] : undefined;
|
|
@@ -1539,7 +1583,7 @@ function destructive(a) {
|
|
|
1539
1583
|
return !readOnly(a) && a.destructiveHint !== false;
|
|
1540
1584
|
}
|
|
1541
1585
|
function hasDefault(schema) {
|
|
1542
|
-
return 'default' in schema;
|
|
1586
|
+
return 'default' in asSchema(schema);
|
|
1543
1587
|
}
|
|
1544
1588
|
function show(value) {
|
|
1545
1589
|
return value === undefined ? '(unset)' : JSON.stringify(value);
|
|
@@ -1639,7 +1683,8 @@ function typeAlternatives(schema) {
|
|
|
1639
1683
|
function allowedValues(schema) {
|
|
1640
1684
|
if (Array.isArray(schema.enum))
|
|
1641
1685
|
return schema.enum;
|
|
1642
|
-
|
|
1686
|
+
const s = asSchema(schema);
|
|
1687
|
+
return 'const' in s ? [s.const] : undefined;
|
|
1643
1688
|
}
|
|
1644
1689
|
function enumChange(before, after) {
|
|
1645
1690
|
const a = allowedValues(before);
|
package/dist/failures.js
CHANGED
|
@@ -15,19 +15,20 @@ const CLIENT = /client capabilit(?:y|ies)\b[^.]{0,60}\b(?:do(?:es)? not|don't|do
|
|
|
15
15
|
// or the wrong operating system: "Editmamei runs on Windows and macOS; this process
|
|
16
16
|
// is on "linux"" (editmamei), "Unsupported platform: linux" (an OS name, not any
|
|
17
17
|
// "platform" argument: "Unsupported platform: myspace" is the tool's own error).
|
|
18
|
-
const ENVIRONMENT = /could not find [^.]{0,40}executable|is not found at \/|\bnot installed\b|command not found|cannot find (module|package)|\bENOENT\b|\bruns on [^.;]{0,40}; this (?:process|machine|system) is on\b|\bunsupported (?:platform|operating system|OS)(?:\s*[.!]?\s*$|\s*\.\s|[^.\n]{0,40}?\b(?:linux|darwin|macos|win32|windows(?:_nt)?|freebsd|openbsd|aix|sunos|android)(?![a-z]))|\bnot supported on (?:this|the current) (?:platform|operating system|OS)\b/i;
|
|
18
|
+
const ENVIRONMENT = /could not find [^.]{0,40}executable|\bno (?:browser|chrome|chromium) (?:was )?found\b|\bnot a git repository\b|\b(?:extension|app|application|plugin|bridge) is not (?:connected|running)\b|is not found at \/|\bnot installed\b|command not found|cannot find (module|package)|\bENOENT\b|\bruns on [^.;]{0,40}; this (?:process|machine|system) is on\b|\bunsupported (?:platform|operating system|OS)(?:\s*[.!]?\s*$|\s*\.\s|[^.\n]{0,40}?\b(?:linux|darwin|macos|win32|windows(?:_nt)?|freebsd|openbsd|aix|sunos|android)(?![a-z]))|\bnot supported on (?:this|the current) (?:platform|operating system|OS)\b/i;
|
|
19
19
|
// "401 Bad credentials" (GitHub), "Authorization Expired" (Sentry), "Invalid
|
|
20
20
|
// token" (Firecrawl), "authentication token is not valid" (Apify), "Please provide
|
|
21
21
|
// a valid access token" (Supabase), "NetlifyUnauthError: You're not logged into
|
|
22
22
|
// Netlify" (Netlify), "The API key you provided was rejected" (Pinecone), "Admin
|
|
23
|
-
// auth is missing", "Runtime credentials are missing" (securenow)
|
|
23
|
+
// auth is missing", "Runtime credentials are missing" (securenow), "ADR Aggregator API key not
|
|
24
|
+
// configured" (mcp-adr-analysis-server). Not a bare
|
|
24
25
|
// "token": plenty of errors mention one.
|
|
25
26
|
// Hosted servers ask the user to sign in in their own words: "Sign in to Ideal (or create
|
|
26
27
|
// your creator account) to continue", "Connect your Novamris account to read its saved chart".
|
|
27
28
|
const SIGN_IN = /\bsign in to\b|\blog ?in to (?:continue|use)\b|\bconnect your [\w .'-]{1,40}? account\b/i;
|
|
28
29
|
// A paid tool: "Payment required: $0.50 over MPP" (a hosted server), HTTP 402, no credits left.
|
|
29
30
|
const PAYMENT = /\bpayment required\b|\b(?:HTTP|status(?: code)?) 402\b|\binsufficient (?:credits?|balance|funds)\b/i;
|
|
30
|
-
const AUTH = /\b(?:auth|authentication|credentials?|api[ _-]?key|access token)\b (?:is |are )?missing\b|\bno (?:authentication|auth|credentials?|api[ _-]?keys?|access tokens?|auth tokens?) (?:was |were )?(?:found|provided|configured|set|given)\b|\b(401|403)\b|unauthori[sz]ed|unauth(enticated|error)|forbidden|bad credentials|authori[sz]ation expired|re-?authori[sz]e|not authenticated|not logged (?:in|into)\b(?! to the browser)|authentication (token|failed|required|error)|(invalid|expired|revoked) (api[ _-]?key|access token|token|credentials)|(token|api[ _-]?key|credentials) (is |are )?(not valid|invalid|expired)|(api[ _-]?key|access token|credentials)\b[^.]{0,30}\b(was|were|is|are) (rejected|refused|revoked)|valid (access )?token/i;
|
|
31
|
+
const AUTH = /\b(?:auth|authentication|credentials?|api[ _-]?key|access token)\b (?:is |are )?missing\b|\b(?:api[ _-]?key|access token|auth token|credentials?)\b (?:is |are |was |were )?not (?:configured|set|provided)\b|\bneeds? (?:an? )?(?:[\w-]+ )?(?:credentials?|api[ _-]?key|access token)\b|\bmissing (?:required )?authentication credentials?\b|\b[a-z0-9_]*(?:api_?key|token|secret)\b (?:is |was )?not (?:set|configured|provided)\b|\bno (?:authentication|auth|credentials?|api[ _-]?keys?|access tokens?|auth tokens?) (?:was |were )?(?:found|provided|configured|set|given)\b|\b(401|403)\b|unauthori[sz]ed|unauth(enticated|error)|forbidden|bad credentials|authori[sz]ation expired|re-?authori[sz]e|not authenticated|not logged (?:in|into)\b(?! to the browser)|authentication (token|failed|required|error)|(invalid|expired|revoked) (api[ _-]?key|access token|token|credentials)|(token|api[ _-]?key|credentials) (is |are )?(not valid|invalid|expired)|(api[ _-]?key|access token|credentials)\b[^.]{0,30}\b(was|were|is|are) (rejected|refused|revoked)|valid (access )?token/i;
|
|
31
32
|
const NETWORK = /\b(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ECONNRESET|EHOSTUNREACH)\b|socket hang up|getaddrinfo|network error/i;
|
|
32
33
|
// "Either 'page_id' OR both 'title' and 'space_key' must be provided" (Atlassian),
|
|
33
34
|
// "**Input Error**" (Sentry), JSON-RPC's invalid params.
|
package/dist/help.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export declare const COMMANDS: readonly ['init', 'snapshot', 'diff', 'session', 'history', 'auth', 'scan', 'explain', 'mcp'];
|
|
1
|
+
export declare const COMMANDS: readonly ['init', 'snapshot', 'diff', 'review', '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', 'mcp'];
|
|
7
|
+
export const COMMANDS = ['init', 'snapshot', 'diff', 'review', '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)']],
|
|
@@ -16,6 +16,7 @@ const OPTIONS = {
|
|
|
16
16
|
badge: ['--badge <path>', ['also write a README badge there (a shields.io endpoint file: tools, tokens,', 'errors or warnings). Commit it with the menu file; it prints the README line']],
|
|
17
17
|
sarif: ['--sarif <path>', ['also write the findings as SARIF 2.1.0 to this file, for GitHub code', 'scanning (upload it with github/codeql-action/upload-sarif)']],
|
|
18
18
|
junit: ['--junit <path>', ['also write the findings as JUnit XML to this file, for CI test reports', '(GitLab, Jenkins, Azure DevOps, CircleCI): findings at --fail-on or above fail']],
|
|
19
|
+
html: ['--html <path>', ['also write the report as one self-contained HTML page (no script, works', 'offline): keep it as a CI artifact or send it to someone']],
|
|
19
20
|
'sarif-menu': ['--sarif-menu <path>', ['the committed menu file SARIF results point at, at each tool\'s line', '(default: the menu file this command wrote, or diff\'s newer one)']],
|
|
20
21
|
json: ['--json', ['same as --format json']],
|
|
21
22
|
'fail-on': ['--fail-on <level>', ['exit 1 on findings at this level or above: error (default), warn, info']],
|
|
@@ -24,7 +25,7 @@ const OPTIONS = {
|
|
|
24
25
|
protocol: ['--protocol <auto|legacy|modern>', ['which handshake to make (default: auto)', 'legacy: the 2025 handshake only; modern: 2026-07-28 only, an error if the server lacks it']],
|
|
25
26
|
as: ['--as <name>[:<credential>]', ['list the menu as this identity too, repeatable: a header ("reader:Authorization:', 'Bearer ...") or env var ("admin:ROLE=admin") on top of --header/--env. The first', 'is the main one (its menu is saved); the others are compared with it']],
|
|
26
27
|
lists: ['--lists <kinds>', ['which lists to read and check, comma-separated: tools (always),', 'prompts, resources (resources/list and resources/templates/list).', 'Saved in the menu file beside the tools']],
|
|
27
|
-
client: ['--client <name>', ['check the menu for one client, from its own docs: claude-code (tools deferred,', 'its description cut and search), claude-api-search (Claude API tool search)', '
|
|
28
|
+
client: ['--client <name>', ['check the menu for one client, from its own docs: claude-code (tools deferred,', 'its description cut and search), claude-api-search (Claude API tool search),', 'openai (Responses API tool_search), codex, antigravity (lazy tools), gemini-cli', '(renames), gemini-api, vscode (128 tools a request), copilot-cloud-agent and', 'copilot-code-review (tools only; review: read-only tools only)']],
|
|
28
29
|
'no-auth': ['--no-auth', ["don't use a stored OAuth login (toolmenu auth login) for this server"]],
|
|
29
30
|
timeout: ['--timeout <ms>', ['per-request timeout (default: 30000)']],
|
|
30
31
|
processes: ['--processes <n>', ['server processes (stdio) or connections (HTTP) to compare, the main', 'one included (default: 2). 1 opens no second one: for servers with one', 'session per client']],
|
|
@@ -35,6 +36,7 @@ const OPTIONS = {
|
|
|
35
36
|
init: ['--init', ["write a starter scenario from the server's menu (to --scenario,", 'default scenario.yml; never overwrites)']],
|
|
36
37
|
auto: ['--auto', ['build the steps from the menu: every read-only tool whose required', 'arguments the schema can fill (const, default, examples, enum, type),', 'then the first call again']],
|
|
37
38
|
'create-handles': ['--create-handles', ['with --auto on 2026-07-28, call the tool that creates a session, basket or cart', '(a write, so only with this flag; never one marked destructiveHint) and give', 'the tools that take it back the handle it returned']],
|
|
39
|
+
'call-everything': ['--call-everything', ['with --auto, call every tool once, writes and open-world ones included, with a', 'made-up value (toolmenu-test, 1) where the schema gives none. Stdio only: run', 'the server in a sandbox with nothing to lose (no credentials, no network)']],
|
|
38
40
|
'open-world': ['--open-world', ['with --auto, also call read-only tools marked openWorldHint: true', '(web search, fetch, scraping): they may cost API credits']],
|
|
39
41
|
'max-calls': ['--max-calls <n>', ['with --auto, at most n calls in all, the tools unlocks bring', 'included (default: 20, plus --max-calls-per-unlock for each unlock value)']],
|
|
40
42
|
'max-calls-per-unlock': ['--max-calls-per-unlock <n>', ['with --auto, at most n calls for the tools each unlock value', 'brings (default: 5), so every toolset gets some']],
|
|
@@ -60,6 +62,7 @@ const OPTIONS = {
|
|
|
60
62
|
'offline-check': ['--offline-check', ['stdio: list the menu once more with the network cut off (the proxy variables', 'pointed at a closed port): a server whose menu depends on what it fetches at start']],
|
|
61
63
|
concurrency: ['--concurrency <n>', ['servers checked at a time (default: 4)']],
|
|
62
64
|
'out-dir': ['--out-dir <dir>', ["write each server's menu file there, as <name>.json (default: none)"]],
|
|
65
|
+
'allow-env': ['--allow-env <names>', ['environment variables a config\'s ${VAR} may be filled from, comma-', "separated or repeated; '*' for all (default: none)"]],
|
|
63
66
|
'no-browser': ['--no-browser', ["don't open a browser: print the login URL, open it on any device, and paste", 'back the address the browser ends on (over SSH, in a container, on a remote box)']],
|
|
64
67
|
scope: ['--scope <scopes>', ["scopes to ask for (default: the server's)"]],
|
|
65
68
|
'client-id': ['--client-id <id>', ['a pre-registered client, for servers without dynamic registration']],
|
|
@@ -89,7 +92,7 @@ const HELP = {
|
|
|
89
92
|
'reports what in the menu confuses agents or breaks prompt caches.',
|
|
90
93
|
SERVER_NOTE,
|
|
91
94
|
],
|
|
92
|
-
own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists', 'offline-check', 'sarif', 'sarif-menu', 'junit', 'badge'],
|
|
95
|
+
own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists', 'offline-check', 'sarif', 'sarif-menu', 'junit', 'html', 'badge'],
|
|
93
96
|
shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
|
|
94
97
|
examples: [
|
|
95
98
|
'toolmenu snapshot -- npx -y @modelcontextprotocol/server-memory',
|
|
@@ -101,11 +104,28 @@ const HELP = {
|
|
|
101
104
|
summary: 'compare two menu files: breaking changes, token change, semver bump',
|
|
102
105
|
usage: ['toolmenu diff [options] <old.json> <new.json>'],
|
|
103
106
|
about: ['Compares two menus written by snapshot (or session --union-out). Starts no server.'],
|
|
104
|
-
own: ['release', 'server-version-is-release', 'sarif', 'sarif-menu', 'junit'],
|
|
107
|
+
own: ['release', 'server-version-is-release', 'sarif', 'sarif-menu', 'junit', 'html'],
|
|
105
108
|
shared: ['config', 'format', 'json', 'fail-on'],
|
|
106
109
|
examples: ['toolmenu diff menu.json new-menu.json', 'toolmenu diff --release 1.4.0..1.5.0 --format markdown old.json new.json'],
|
|
107
110
|
exits: ['0 no findings at or above --fail-on', '1 findings at or above --fail-on', "2 a menu file can't be read, or bad usage"],
|
|
108
111
|
},
|
|
112
|
+
review: {
|
|
113
|
+
summary: 'should a new menu file replace the baseline? a verdict, and the findings it adds or clears',
|
|
114
|
+
usage: ['toolmenu review [options] <baseline.json> <new.json>'],
|
|
115
|
+
about: [
|
|
116
|
+
'Compares the new menu with the committed baseline as diff does, runs the menu rules on',
|
|
117
|
+
'both files, and says whether to accept it: what breaks callers, which findings are new,',
|
|
118
|
+
'which are gone. Starts no server. Pass --release to check breaking changes against the bump.',
|
|
119
|
+
],
|
|
120
|
+
own: ['release', 'server-version-is-release'],
|
|
121
|
+
shared: ['config', 'format', 'json', 'fail-on'],
|
|
122
|
+
examples: ['toolmenu review menu.json new-menu.json', 'toolmenu review --release 1.4.0..2.0.0 --format markdown menu.json new-menu.json'],
|
|
123
|
+
exits: [
|
|
124
|
+
'0 accept: unchanged, safe, or breaking changes the release allows',
|
|
125
|
+
'1 not as it is: breaking changes without a release that allows them, or new findings at or above --fail-on',
|
|
126
|
+
"2 a menu file can't be read, or bad usage",
|
|
127
|
+
],
|
|
128
|
+
},
|
|
109
129
|
session: {
|
|
110
130
|
summary: 'run a session (scripted or --auto) and watch the menu change',
|
|
111
131
|
usage: [
|
|
@@ -119,7 +139,7 @@ const HELP = {
|
|
|
119
139
|
'prompt cache, a different menu in a fresh process.',
|
|
120
140
|
SERVER_NOTE,
|
|
121
141
|
],
|
|
122
|
-
own: ['scenario', 'auto', 'init', 'plan', 'value', 'values-file', 'assume-read-only', 'open-world', 'create-handles', 'max-calls', 'max-calls-per-unlock', 'save-scenario', 'union-out', 'elicitation', 'sarif', 'sarif-menu', 'junit'],
|
|
142
|
+
own: ['scenario', 'auto', 'init', 'plan', 'value', 'values-file', 'assume-read-only', 'open-world', 'call-everything', 'create-handles', 'max-calls', 'max-calls-per-unlock', 'save-scenario', 'union-out', 'elicitation', 'sarif', 'sarif-menu', 'junit', 'html'],
|
|
123
143
|
shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
|
|
124
144
|
examples: [
|
|
125
145
|
'toolmenu session --auto -- node dist/index.js',
|
|
@@ -146,35 +166,42 @@ const HELP = {
|
|
|
146
166
|
exits: ['0 at least one version was inspected', '1 every version failed', "2 bad usage, or the package's versions couldn't be listed"],
|
|
147
167
|
},
|
|
148
168
|
auth: {
|
|
149
|
-
summary: 'log in to an OAuth-protected HTTP server once',
|
|
150
|
-
usage: ['toolmenu auth login [options] <url>', 'toolmenu auth logout <url>', 'toolmenu auth list'],
|
|
169
|
+
summary: 'log in to an OAuth-protected HTTP server once, or check its OAuth discovery',
|
|
170
|
+
usage: ['toolmenu auth login [options] <url>', 'toolmenu auth logout <url>', 'toolmenu auth list', 'toolmenu auth check <url>'],
|
|
151
171
|
about: [
|
|
152
172
|
'login opens the browser once and stores the tokens (only you can read the file);',
|
|
153
173
|
'snapshot and session then use them for that URL (--no-auth to skip).',
|
|
154
174
|
'Stored in $TOOLMENU_AUTH_DIR, else $XDG_CONFIG_HOME/toolmenu/auth, else ~/.config/toolmenu/auth.',
|
|
175
|
+
'check walks the server\'s OAuth discovery the way a client that follows the spec does,',
|
|
176
|
+
'without logging in: the 401, the protected resource metadata, the authorization server\'s',
|
|
177
|
+
'metadata, PKCE and registration (auth/* rules in docs/RULES.md).',
|
|
155
178
|
],
|
|
156
179
|
own: ['port', 'no-browser', 'scope', 'client-id', 'client-secret'],
|
|
157
|
-
shared: [],
|
|
180
|
+
shared: ['format', 'json', 'fail-on', 'timeout'],
|
|
158
181
|
examples: [
|
|
159
182
|
'toolmenu auth login https://example.com/mcp',
|
|
183
|
+
'toolmenu auth check https://mcp.example.com/mcp',
|
|
160
184
|
'toolmenu auth login --client-id <id> --client-secret <secret> https://example.com/mcp',
|
|
161
185
|
'toolmenu auth list',
|
|
162
186
|
],
|
|
163
|
-
exits: ['0 done (logout of a URL with no login is not an error)', '2 the login failed, or bad usage'],
|
|
187
|
+
exits: ['0 done (logout of a URL with no login is not an error; check: no findings at or above --fail-on)', '1 check: findings at or above --fail-on', '2 the login failed, or bad usage'],
|
|
164
188
|
},
|
|
165
189
|
scan: {
|
|
166
190
|
summary: 'snapshot every server in an MCP client config or a list, side by side',
|
|
167
191
|
usage: ['toolmenu scan [options] <list>'],
|
|
168
192
|
about: [
|
|
169
193
|
'The list is an MCP client config (Claude Desktop, Claude Code .mcp.json, Cursor,',
|
|
170
|
-
'VS Code: the mcpServers or servers object,
|
|
171
|
-
'
|
|
172
|
-
'
|
|
173
|
-
'
|
|
194
|
+
'VS Code: the mcpServers or servers object), or a text file with one server per line:',
|
|
195
|
+
'a URL or a command, optionally "name<TAB>" first. Runs snapshot on each (nothing',
|
|
196
|
+
'written unless --out-dir). A server that could not be started or read is a row that',
|
|
197
|
+
'says why, and makes the exit code 2: it was not checked.',
|
|
198
|
+
'scan starts every command in the list: scan only lists you would run yourself.',
|
|
199
|
+
'${VAR} in a config is filled only from variables named with --allow-env; an entry',
|
|
200
|
+
'that uses another is not checked, so a config cannot send your environment anywhere.',
|
|
174
201
|
],
|
|
175
|
-
own: ['concurrency', 'out-dir'],
|
|
202
|
+
own: ['concurrency', 'out-dir', 'allow-env'],
|
|
176
203
|
shared: ['config', 'format', 'json', 'fail-on', 'no-auth', 'protocol', 'timeout', 'processes'],
|
|
177
|
-
examples: ['toolmenu scan ~/Library/Application\\ Support/Claude/claude_desktop_config.json', 'toolmenu scan .mcp.json --format markdown', 'toolmenu scan servers.txt --concurrency 8 --out-dir menus'],
|
|
204
|
+
examples: ['toolmenu scan ~/Library/Application\\ Support/Claude/claude_desktop_config.json --allow-env GITHUB_TOKEN', 'toolmenu scan .mcp.json --format markdown', 'toolmenu scan servers.txt --concurrency 8 --out-dir menus'],
|
|
178
205
|
exits: ['0 every server checked, no findings at or above --fail-on', '1 findings at or above --fail-on', "2 a server wasn't checked (couldn't start, couldn't connect, a variable not set), or bad usage"],
|
|
179
206
|
},
|
|
180
207
|
explain: {
|
|
@@ -193,8 +220,8 @@ const HELP = {
|
|
|
193
220
|
summary: 'serve toolmenu to an agent as an MCP server (stdio)',
|
|
194
221
|
usage: ['toolmenu mcp'],
|
|
195
222
|
about: [
|
|
196
|
-
'An MCP server over stdio, for the agent building your server: snapshot_menu,
|
|
197
|
-
'
|
|
223
|
+
'An MCP server over stdio, for the agent building your server: snapshot_menu, check_session,',
|
|
224
|
+
'diff_menus, review_baseline, check_auth and explain_rule, each running the matching command. Relative paths and',
|
|
198
225
|
'toolmenu.config.json resolve from the folder it runs in, or a tool call\'s cwd.',
|
|
199
226
|
'Claude Code: claude mcp add toolmenu -- npx -y toolmenu mcp',
|
|
200
227
|
],
|
|
@@ -216,7 +243,7 @@ export function overview() {
|
|
|
216
243
|
const width = Math.max(...COMMANDS.map((c) => c.length)) + 3;
|
|
217
244
|
return [
|
|
218
245
|
`toolmenu ${VERSION}`,
|
|
219
|
-
"
|
|
246
|
+
"Test your MCP server the way agents and clients meet it: the menu, the calls, the results, the sign-in, every release.",
|
|
220
247
|
'',
|
|
221
248
|
'Usage: toolmenu <command> [options]',
|
|
222
249
|
'',
|
package/dist/history.js
CHANGED
|
@@ -9,6 +9,8 @@ import { diffMenus } from './diff.js';
|
|
|
9
9
|
import { snapshot } from './snapshot.js';
|
|
10
10
|
const run = promisify(execFile);
|
|
11
11
|
const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
|
|
12
|
+
/** A registry version as npm publishes them: 1.2.3, 1.2.3-rc.1, 1.2.3+build. */
|
|
13
|
+
const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
|
|
12
14
|
/** The npm registry, through the user's own npm (their config, proxy and registry). */
|
|
13
15
|
export const npmSource = {
|
|
14
16
|
async versions(pkg) {
|
|
@@ -48,8 +50,11 @@ export async function history(pkg, options) {
|
|
|
48
50
|
const all = await source.versions(pkg);
|
|
49
51
|
// Version order, not publish order: a backport (1.0.1 after 2.0.0) is diffed
|
|
50
52
|
// against 1.0.0, not against 2.0.0.
|
|
53
|
+
// Only versions shaped like semver: each is used in a file name and an npm argument
|
|
54
|
+
// (through a shell on Windows), and a registry is another party.
|
|
51
55
|
const candidates = all
|
|
52
56
|
.map((v, index) => ({ v, index }))
|
|
57
|
+
.filter(({ v }) => SEMVER.test(v.version))
|
|
53
58
|
.filter(({ v }) => options.includePrereleases || !v.version.includes('-'))
|
|
54
59
|
.sort((a, b) => compareVersions(a.v.version, b.v.version) || a.index - b.index)
|
|
55
60
|
.map(({ v }) => v);
|
package/dist/html.d.ts
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { ClientCost } from './clients.js';
|
|
2
|
+
import type { DiffResult, DiffTools } from './diff.js';
|
|
3
|
+
import { type SessionResult, type StepTool } from './session.js';
|
|
4
|
+
import type { Finding, Menu } from './types.js';
|
|
5
|
+
export declare function esc(text: unknown): string;
|
|
6
|
+
export interface SnapshotHtmlOptions {
|
|
7
|
+
/** stdio or http, for the subtitle. */
|
|
8
|
+
transport?: string;
|
|
9
|
+
/** --client: what the menu costs under that client. */
|
|
10
|
+
cost?: ClientCost;
|
|
11
|
+
/** --lists asked for that the server doesn't offer. */
|
|
12
|
+
notOffered?: string[];
|
|
13
|
+
/** Where the menu file was written. */
|
|
14
|
+
outPath?: string;
|
|
15
|
+
}
|
|
16
|
+
/** The snapshot page. It counts as the text report does: every tool the server lists, app-only ones marked. */
|
|
17
|
+
export declare function snapshotHtml(menu: Menu, findings: Finding[], options?: SnapshotHtmlOptions): string;
|
|
18
|
+
export interface DiffHtmlOptions {
|
|
19
|
+
/** The two menu files, as given on the command line. */
|
|
20
|
+
paths?: [string, string];
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* The diff page, from what diffMenus compared and decided (`tools`, from its onTools):
|
|
24
|
+
* the tools after the ignore globs, and which were added, removed and renamed. Token
|
|
25
|
+
* totals are the result's, which leave app-only tools out, as the text report's do.
|
|
26
|
+
*/
|
|
27
|
+
export declare function diffHtml(result: DiffResult, tools: DiffTools, options?: DiffHtmlOptions): string;
|
|
28
|
+
/** The session page. `menus`: the menu after each step, from session's onStepMenu. */
|
|
29
|
+
export declare function sessionHtml(result: SessionResult, menus?: Map<number, StepTool[]>): string;
|