toolmenu 0.24.0 → 0.25.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 CHANGED
@@ -1,11 +1,23 @@
1
- # toolmenu
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/niksa90/toolmenu/main/docs/logo.svg" width="120" height="120" alt="toolmenu logo: a plug with a list of tools, one checked">
3
+ </p>
4
+
5
+ <h1 align="center">toolmenu</h1>
6
+
7
+ <p align="center">
8
+ <b>Checks for MCP servers' tool lists: changes that confuse agents, break prompt caches or break clients, caught before your users hit them.</b>
9
+ </p>
10
+
11
+ <p align="center">
2
12
 
3
13
  [![npm](https://img.shields.io/npm/v/toolmenu)](https://www.npmjs.com/package/toolmenu)
4
14
  [![ci](https://github.com/niksa90/toolmenu/actions/workflows/ci.yml/badge.svg)](https://github.com/niksa90/toolmenu/actions/workflows/ci.yml)
5
15
  [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/niksa90/toolmenu/blob/main/LICENSE)
6
16
  [![MCP: 2026-07-28 and 2025](https://img.shields.io/badge/MCP-2026--07--28%20%C2%B7%202025-6E56CF)](https://modelcontextprotocol.io)
17
+ [![toolmenu](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fniksa90%2Ftoolmenu%2Fmain%2Fdocs%2Ftoolmenu-badge.json)](https://github.com/niksa90/toolmenu)
18
+ [![toolmenu MCP server on Glama](https://glama.ai/mcp/servers/niksa90/toolmenu/badges/score.svg)](https://glama.ai/mcp/servers/niksa90/toolmenu)
7
19
 
8
- **Checks for MCP servers' tool lists: changes that confuse agents, break prompt caches or break clients, caught before your users hit them.**
20
+ </p>
9
21
 
10
22
  Your MCP server's tool list is the menu every agent reads before it does anything.
11
23
  toolmenu checks that menu the way clients and agents will meet it: across calls,
@@ -36,7 +48,7 @@ It runs on the 22-server [bench](bench/README.md) and on hosted servers (GitHub,
36
48
  Notion, Supabase, Vercel…). What it has found on real servers is in
37
49
  [docs/FINDINGS.md](https://github.com/niksa90/toolmenu/blob/main/docs/FINDINGS.md).
38
50
 
39
- > **Status: 0.24.** Spec in [docs/SPEC.md](https://github.com/niksa90/toolmenu/blob/main/docs/SPEC.md),
51
+ > **Status: 0.25.** Spec in [docs/SPEC.md](https://github.com/niksa90/toolmenu/blob/main/docs/SPEC.md),
40
52
  > every rule in [docs/RULES.md](docs/RULES.md), changes in [CHANGELOG.md](CHANGELOG.md).
41
53
 
42
54
  <details>
@@ -164,7 +176,7 @@ written unless `--out-dir` names a folder for each server's menu file.
164
176
 
165
177
  `toolmenu mcp` is toolmenu as an MCP server (stdio), so Claude Code, Cursor or any
166
178
  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):
179
+ plugin (the server, and skills for checking a change, checking a release, and setting up CI):
168
180
 
169
181
  ```
170
182
  /plugin marketplace add niksa90/toolmenu
@@ -204,7 +216,7 @@ jobs:
204
216
  - uses: actions/setup-node@v7
205
217
  with: { node-version: 22 }
206
218
  - run: npm ci && npm run build
207
- - uses: niksa90/toolmenu@v0.16.1
219
+ - uses: niksa90/toolmenu@v0.25.1
208
220
  with:
209
221
  command: node dist/server.js
210
222
  baseline: menu.json # your committed snapshot
@@ -229,8 +241,55 @@ and anything `session` caught. The same report goes to the job summary.
229
241
  | `release` | `auto` | Release versions for the bump check. `auto` reads `package.json`, `pyproject.toml` or `Cargo.toml` on the base branch and the head, or compares the tag with the previous one on a tag push. Set `"1.4.0..1.5.0"` yourself, or `off` |
230
242
  | `fail-on` | `error` | Fail the job on findings at or above this level |
231
243
  | `comment` | `true` | Post and update the PR comment |
244
+ | `sarif` | | A folder to also write the findings to as SARIF, for code scanning (below) |
232
245
  | `version` | the Action's own | toolmenu version from npm: by default the one matching the Action tag you pinned (`latest` for the newest). The Action installs toolmenu from npm, so it needs a published version |
233
246
 
247
+ ### In the Security tab: code scanning
248
+
249
+ With `sarif`, findings also go to GitHub code scanning: alerts in the Security tab,
250
+ each on the line of its tool in your `menu.json`, and a code scanning check on the pull
251
+ request. GitHub shows an alert inline in the pull request only when that line changed in
252
+ it, so most stay in the Security tab and the check. Run the workflow on pushes to your
253
+ default branch too, so GitHub has a base to compare a pull request's alerts with. Code scanning is free for public repositories; private ones need GitHub Advanced
254
+ Security.
255
+
256
+ ```yaml
257
+ on:
258
+ pull_request:
259
+ push:
260
+ branches: [main] # the base GitHub compares a pull request's alerts with
261
+ permissions:
262
+ contents: read
263
+ pull-requests: write
264
+ security-events: write # to upload SARIF
265
+ steps:
266
+ # … checkout, build, as above
267
+ - uses: niksa90/toolmenu@v0.25.1
268
+ with:
269
+ command: node dist/server.js
270
+ sarif: toolmenu-sarif
271
+ - uses: github/codeql-action/upload-sarif@v4
272
+ if: always() # findings fail the toolmenu step; upload them anyway
273
+ with:
274
+ sarif_file: toolmenu-sarif
275
+ ```
276
+
277
+ Outside the Action: `toolmenu snapshot --sarif toolmenu.sarif -- node dist/server.js`
278
+ writes the file beside the usual report (`diff` and `session` take `--sarif` too), or
279
+ `--format sarif` prints it instead.
280
+
281
+ ### A badge for your README
282
+
283
+ ```sh
284
+ npx toolmenu snapshot --badge toolmenu-badge.json -- node dist/server.js
285
+ ```
286
+
287
+ writes a [shields.io endpoint](https://shields.io/badges/endpoint-badge) file (tools,
288
+ tokens, and errors or warnings, in red, yellow or green) and prints the README line
289
+ for it. Commit it with `menu.json`: it changes when the baseline does, so nothing
290
+ has to commit from CI. The badge at the top of this README is toolmenu's own MCP
291
+ server (`toolmenu mcp`), checked by itself.
292
+
234
293
  Server behind auth, or PRs from forks and Dependabot? See [docs/github-action.md](https://github.com/niksa90/toolmenu/blob/main/docs/github-action.md).
235
294
  Server that unlocks tools on request? Snapshot the full menu for the baseline and run the session on the default one: [servers that unlock tools](https://github.com/niksa90/toolmenu/blob/main/docs/github-action.md#servers-that-unlock-tools).
236
295
  PRs without secrets are skipped, and a skipped check still passes; the `skipped` output tells you.
package/dist/apps.js CHANGED
@@ -47,6 +47,8 @@ export function agentMenu(menu) {
47
47
  const tokens = tools.reduce((n, t) => n + t.tokens, 0);
48
48
  return { shown: { ...menu, tools, totalTokens: tokens }, appOnly: { tools: menu.tools.length - tools.length, tokens: menu.totalTokens - tokens } };
49
49
  }
50
+ /** Below this much time left before the deadline, a read isn't started. */
51
+ const MIN_READ_MS = 10;
50
52
  /**
51
53
  * Read each `ui://` resource the menu's tools name (resources/read: a read, not a tool
52
54
  * call), at most `limit` of them. Each is read once, however many tools name it.
@@ -66,7 +68,8 @@ export async function readAppResources(connection, tools, timeoutMs = 30_000, li
66
68
  const readOne = async (i) => {
67
69
  const [uri, names] = queue[i];
68
70
  const left = deadline - Date.now();
69
- if (left <= 0) {
71
+ // A read given a few milliseconds can only time out: past the deadline in all but name.
72
+ if (left < MIN_READ_MS) {
70
73
  out[i] = { uri, tools: names, error: `not read: the reads took longer than ${Math.round((2 * timeoutMs) / 1000)} s in all` };
71
74
  return;
72
75
  }
@@ -0,0 +1,20 @@
1
+ import type { Finding, Menu } from './types.js';
2
+ export interface Badge {
3
+ schemaVersion: 1;
4
+ label: string;
5
+ message: string;
6
+ color: string;
7
+ cacheSeconds: number;
8
+ }
9
+ /** "~980", "~4.1K", "~12K": the size people compare, not the exact estimate. */
10
+ export declare function compactTokens(n: number): string;
11
+ /** The endpoint JSON: tools and tokens, and the findings that matter (errors, else warnings). */
12
+ export declare function badge(menu: Menu, findings: Finding[]): Badge;
13
+ /** `owner/repo` of a GitHub remote URL (https or ssh), or undefined. */
14
+ export declare function githubRepo(remote: string): string | undefined;
15
+ /**
16
+ * The README line for a badge file: a shields endpoint badge reading the file from
17
+ * GitHub on the default branch, linking to toolmenu. With no GitHub remote, a
18
+ * template to fill in.
19
+ */
20
+ export declare function badgeMarkdown(badgePath: string, cwd?: string): string;
package/dist/badge.js ADDED
@@ -0,0 +1,59 @@
1
+ /*
2
+ * The README badge: a shields.io endpoint file (https://shields.io/badges/endpoint-badge)
3
+ * that `snapshot --badge <path>` writes beside the menu file. Committed with the
4
+ * baseline, it changes when the baseline does, so no CI has to commit anything:
5
+ * shields reads it from the repository.
6
+ */
7
+ import { execFileSync } from 'node:child_process';
8
+ import { relative, resolve, sep } from 'node:path';
9
+ import { counts } from './report.js';
10
+ import { repoRoot } from './sarif.js';
11
+ /** "~980", "~4.1K", "~12K": the size people compare, not the exact estimate. */
12
+ export function compactTokens(n) {
13
+ if (n < 1000)
14
+ return `~${n}`;
15
+ const k = n / 1000;
16
+ return `~${k < 10 ? k.toFixed(1).replace(/\.0$/, '') : Math.round(k)}K`;
17
+ }
18
+ /** The endpoint JSON: tools and tokens, and the findings that matter (errors, else warnings). */
19
+ export function badge(menu, findings) {
20
+ const c = counts(findings);
21
+ const tools = `${menu.tools.length} tool${menu.tools.length === 1 ? '' : 's'}`;
22
+ const found = c.error ? ` · ${c.error} error${c.error === 1 ? '' : 's'}` : c.warn ? ` · ${c.warn} warning${c.warn === 1 ? '' : 's'}` : '';
23
+ return {
24
+ schemaVersion: 1,
25
+ label: 'toolmenu',
26
+ message: `${tools} · ${compactTokens(menu.totalTokens)} tokens${found}`,
27
+ color: c.error ? 'red' : c.warn ? 'yellow' : 'brightgreen',
28
+ // shields caches for at least 300 s; an hour is plenty for a file that changes with releases.
29
+ cacheSeconds: 3600,
30
+ };
31
+ }
32
+ /** `owner/repo` of a GitHub remote URL (https or ssh), or undefined. */
33
+ export function githubRepo(remote) {
34
+ const m = /github\.com[/:]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(remote.trim());
35
+ return m ? `${m[1]}/${m[2]}` : undefined;
36
+ }
37
+ function git(args, cwd) {
38
+ try {
39
+ return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined;
40
+ }
41
+ catch {
42
+ return undefined;
43
+ }
44
+ }
45
+ /**
46
+ * The README line for a badge file: a shields endpoint badge reading the file from
47
+ * GitHub on the default branch, linking to toolmenu. With no GitHub remote, a
48
+ * template to fill in.
49
+ */
50
+ export function badgeMarkdown(badgePath, cwd = process.cwd()) {
51
+ const root = repoRoot(cwd);
52
+ const path = relative(root, resolve(cwd, badgePath)).split(sep).join('/');
53
+ const repo = githubRepo(git(['remote', 'get-url', 'origin'], cwd) ?? '');
54
+ // origin/HEAD names the default branch when the clone recorded it; else the current one.
55
+ const branch = git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], cwd)?.replace(/^origin\//, '') ?? git(['symbolic-ref', '--short', 'HEAD'], cwd) ?? 'main';
56
+ const raw = `https://raw.githubusercontent.com/${repo ?? '<owner>/<repo>'}/${branch}/${path}`;
57
+ // The badge links to toolmenu: what it is, for whoever clicks it on the README.
58
+ return `[![toolmenu](https://img.shields.io/endpoint?url=${encodeURIComponent(raw)})](https://github.com/niksa90/toolmenu)`;
59
+ }
package/dist/cli.js CHANGED
@@ -23,6 +23,8 @@ import { autoScenario, loadValuesFile, parseAssumeReadOnly, parseValueFlag, scen
23
23
  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
+ import { toSarif } from './sarif.js';
27
+ import { badge, badgeMarkdown } from './badge.js';
26
28
  import { VERSION } from './version.js';
27
29
  import { SECRET_ARGS_ENV } from './mcp-env.js';
28
30
  import { CLI_OPTIONS } from './options.js';
@@ -78,9 +80,28 @@ export async function main(given) {
78
80
  const one = stray.length === 1;
79
81
  process.stderr.write(`toolmenu: ${sub} ignores ${stray.join(', ')}: ${one ? 'it is' : 'they are'} for other commands.\n → Next: Leave ${one ? 'it' : 'them'} out to silence this; toolmenu ${sub} --help lists the options ${sub} takes.\n`);
80
82
  }
81
- const format = (values.json ? 'json' : values.format ?? 'text');
82
- if (!['text', 'json', 'github', 'markdown'].includes(format))
83
- throw new UsageError(`--format must be text, json, github or markdown`);
83
+ const asked = values.json ? 'json' : values.format ?? 'text';
84
+ if (!['text', 'json', 'github', 'markdown', 'sarif'].includes(asked))
85
+ throw new UsageError(`--format must be text, json, github, markdown or sarif`);
86
+ // SARIF is a findings file for code scanning: --format sarif prints it instead of the
87
+ // report, --sarif <path> writes it beside the report.
88
+ const sarifCommands = ['snapshot', 'diff', 'session'];
89
+ if ((asked === 'sarif' || values.sarif !== undefined || values['sarif-menu'] !== undefined) && !sarifCommands.includes(sub))
90
+ throw new UsageError(`SARIF output (--format sarif, --sarif, --sarif-menu) goes with snapshot, diff or session; ${sub} has none.`);
91
+ if (sub === 'session' && (values.plan || values.init) && (asked === 'sarif' || values.sarif !== undefined))
92
+ throw new UsageError('SARIF needs findings: --plan and --init run nothing.');
93
+ const sarifToStdout = asked === 'sarif';
94
+ const format = (sarifToStdout ? 'text' : asked);
95
+ /** Print the report, or the SARIF log with --format sarif; write --sarif's file too. */
96
+ const emit = async (report, findings, command, menuPath) => {
97
+ const menu = values['sarif-menu'] ?? menuPath;
98
+ if (values.sarif !== undefined)
99
+ await writeFile(values.sarif, toSarif(findings, { command, menuPath: menu }) + '\n');
100
+ if (sarifToStdout)
101
+ process.stdout.write(toSarif(findings, { command, menuPath: menu }) + '\n');
102
+ else if (report)
103
+ process.stdout.write(show(report) + '\n');
104
+ };
84
105
  // Colour for a report read in a terminal (colour.ts); piped, CI and other formats stay plain.
85
106
  const show = (report) => (format === 'text' && colourFor(process.stdout) ? colourise(report) : report);
86
107
  const failOn = (values['fail-on'] ?? 'error');
@@ -200,7 +221,7 @@ export async function main(given) {
200
221
  release,
201
222
  serverVersionIsRelease: values['server-version-is-release'] ?? config.serverVersionIsRelease,
202
223
  });
203
- process.stdout.write(show(formatDiff(result, before.tools.length, after.tools.length, format)) + '\n');
224
+ await emit(formatDiff(result, before.tools.length, after.tools.length, format), result.findings, 'diff', rest[1]);
204
225
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
205
226
  }
206
227
  if (sub === 'history') {
@@ -361,9 +382,7 @@ export async function main(given) {
361
382
  result.auto = { ...result.auto, ...auto };
362
383
  if (values['union-out'])
363
384
  await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
364
- const output = formatSession(result, format);
365
- if (output)
366
- process.stdout.write(show(output) + '\n');
385
+ await emit(formatSession(result, format), result.findings, 'session', values['union-out'] ?? (existsSync('menu.json') ? 'menu.json' : undefined));
367
386
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
368
387
  }
369
388
  if (sub === 'session') {
@@ -386,9 +405,7 @@ export async function main(given) {
386
405
  const result = await session(sessionTarget, scenario, { timeoutMs, processes, rules: config.rules, ignore: config.ignore, scenarioName: values.scenario, unionOut: !!values['union-out'] });
387
406
  if (values['union-out'])
388
407
  await writeFile(values['union-out'], JSON.stringify(result.union, null, 2) + '\n');
389
- const output = formatSession(result, format);
390
- if (output)
391
- process.stdout.write(show(output) + '\n');
408
+ await emit(formatSession(result, format), result.findings, 'session', values['union-out'] ?? (existsSync('menu.json') ? 'menu.json' : undefined));
392
409
  return result.findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
393
410
  }
394
411
  const target = parseTarget(rest, command, values.header ?? [], values.env ?? [], values['no-auth'], prefix, protocol);
@@ -403,9 +420,12 @@ export async function main(given) {
403
420
  const outPath = values['no-write'] ? undefined : values.out ?? 'menu.json';
404
421
  if (outPath)
405
422
  await writeFile(outPath, JSON.stringify(menu, null, 2) + '\n');
406
- const output = formatSnapshot(menu, findings, format, outPath, cost, notOffered);
407
- if (output)
408
- process.stdout.write(show(output) + '\n');
423
+ await emit(formatSnapshot(menu, findings, format, outPath, cost, notOffered), findings, 'snapshot', outPath);
424
+ if (values.badge !== undefined) {
425
+ await writeFile(values.badge, JSON.stringify(badge(menu, findings), null, 2) + '\n');
426
+ // stderr: stdout stays the report (or the JSON/SARIF a script parses).
427
+ process.stderr.write(`toolmenu: wrote the badge to ${values.badge}. Commit it with the menu file; in the README:\n ${badgeMarkdown(values.badge)}\n`);
428
+ }
409
429
  return findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
410
430
  }
411
431
  function parseTarget(positionals, command, headers, env, noAuth, prefix, protocol) {
package/dist/help.js CHANGED
@@ -12,7 +12,10 @@ const OPTIONS = {
12
12
  routes: ['--routes <path>', ['routes.yml: pin which words route to which tools']],
13
13
  catalog: ['--catalog', ['also read the operations behind a search tool (search and execute:', 'discover, search_*_tools) or command routers (listed with learn: true,', 'never run) and keep them in the menu file for diff']],
14
14
  config: ['--config <path>', ['config file (default: toolmenu.config.json, if present)']],
15
- format: ['--format <fmt>', ['text (default), json, github (annotations) or markdown (PR comments)']],
15
+ format: ['--format <fmt>', ['text (default), json, github (annotations), markdown (PR comments)', 'or sarif (code scanning; snapshot, diff and session)']],
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
+ 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
+ '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)']],
16
19
  json: ['--json', ['same as --format json']],
17
20
  'fail-on': ['--fail-on <level>', ['exit 1 on findings at this level or above: error (default), warn, info']],
18
21
  header: ['--header "<k>: <v>"', ['HTTP header, repeatable (e.g. "Authorization: Bearer ...")']],
@@ -85,7 +88,7 @@ const HELP = {
85
88
  'reports what in the menu confuses agents or breaks prompt caches.',
86
89
  SERVER_NOTE,
87
90
  ],
88
- own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists', 'offline-check'],
91
+ own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists', 'offline-check', 'sarif', 'sarif-menu', 'badge'],
89
92
  shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
90
93
  examples: [
91
94
  'toolmenu snapshot -- npx -y @modelcontextprotocol/server-memory',
@@ -97,7 +100,7 @@ const HELP = {
97
100
  summary: 'compare two menu files: breaking changes, token change, semver bump',
98
101
  usage: ['toolmenu diff [options] <old.json> <new.json>'],
99
102
  about: ['Compares two menus written by snapshot (or session --union-out). Starts no server.'],
100
- own: ['release', 'server-version-is-release'],
103
+ own: ['release', 'server-version-is-release', 'sarif', 'sarif-menu'],
101
104
  shared: ['config', 'format', 'json', 'fail-on'],
102
105
  examples: ['toolmenu diff menu.json new-menu.json', 'toolmenu diff --release 1.4.0..1.5.0 --format markdown old.json new.json'],
103
106
  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"],
@@ -115,7 +118,7 @@ const HELP = {
115
118
  'prompt cache, a different menu in a fresh process.',
116
119
  SERVER_NOTE,
117
120
  ],
118
- 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'],
121
+ 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'],
119
122
  shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
120
123
  examples: [
121
124
  'toolmenu session --auto -- node dist/index.js',
package/dist/options.d.ts CHANGED
@@ -2,6 +2,15 @@ export declare const CLI_OPTIONS: {
2
2
  readonly out: {
3
3
  readonly type: 'string';
4
4
  };
5
+ readonly sarif: {
6
+ readonly type: 'string';
7
+ };
8
+ readonly badge: {
9
+ readonly type: 'string';
10
+ };
11
+ readonly 'sarif-menu': {
12
+ readonly type: 'string';
13
+ };
5
14
  readonly 'out-dir': {
6
15
  readonly type: 'string';
7
16
  };
package/dist/options.js CHANGED
@@ -4,6 +4,9 @@
4
4
  */
5
5
  export const CLI_OPTIONS = {
6
6
  out: { type: 'string' },
7
+ sarif: { type: 'string' },
8
+ badge: { type: 'string' },
9
+ 'sarif-menu': { type: 'string' },
7
10
  'out-dir': { type: 'string' },
8
11
  'offline-check': { type: 'boolean' },
9
12
  concurrency: { type: 'string' },
@@ -0,0 +1,14 @@
1
+ import type { Finding } from './types.js';
2
+ export interface SarifOptions {
3
+ /** snapshot, diff or session: the run's category, so code scanning keeps them apart. */
4
+ command: string;
5
+ /** The menu file results point at, as a path from the working directory. */
6
+ menuPath?: string;
7
+ /** Where paths are made relative to: the repository root (default: found from the working directory). */
8
+ root?: string;
9
+ }
10
+ /** The repository root: the nearest folder up from `from` with a .git, or `from` itself. */
11
+ export declare function repoRoot(from?: string): string;
12
+ /** The line of each tool's "name" in a menu file written by toolmenu (1-based). */
13
+ export declare function toolLines(text: string): Map<string, number>;
14
+ export declare function toSarif(findings: Finding[], options: SarifOptions): string;
package/dist/sarif.js ADDED
@@ -0,0 +1,138 @@
1
+ /*
2
+ * SARIF 2.1.0 output, for GitHub code scanning and other SARIF viewers.
3
+ *
4
+ * toolmenu's findings are about tools in a menu, not lines of source, so each result
5
+ * points at the menu file in the repository (the committed baseline, or the one this
6
+ * command wrote) and, when the finding names a tool, at the line where that tool
7
+ * starts. A tool the file doesn't have (new since the baseline) points at line 1.
8
+ */
9
+ import { createHash } from 'node:crypto';
10
+ import { existsSync, readFileSync } from 'node:fs';
11
+ import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
12
+ import { pathToFileURL } from 'node:url';
13
+ import { ruleDocs } from './rule-docs.js';
14
+ import { VERSION } from './version.js';
15
+ const LEVEL = { error: 'error', warn: 'warning', info: 'note' };
16
+ const RULES_URL = 'https://github.com/niksa90/toolmenu/blob/main/docs/RULES.md';
17
+ /** The repository root: the nearest folder up from `from` with a .git, or `from` itself. */
18
+ export function repoRoot(from = process.cwd()) {
19
+ let dir = resolve(from);
20
+ for (;;) {
21
+ if (existsSync(resolve(dir, '.git')))
22
+ return dir;
23
+ const up = dirname(dir);
24
+ if (up === dir)
25
+ return resolve(from);
26
+ dir = up;
27
+ }
28
+ }
29
+ /** The line of each tool's "name" in a menu file written by toolmenu (1-based). */
30
+ export function toolLines(text) {
31
+ const lines = new Map();
32
+ const all = text.split(/\r?\n/);
33
+ const start = all.findIndex((l) => /^\s*"tools":\s*\[/.test(l));
34
+ if (start === -1)
35
+ return lines;
36
+ // A tool's own "name" is the first key of its object, one level inside the array.
37
+ for (let i = start + 1; i < all.length; i++) {
38
+ const m = /^ {6}"name":\s*("(?:[^"\\]|\\.)*")/.exec(all[i]);
39
+ if (m) {
40
+ const name = JSON.parse(m[1]);
41
+ if (!lines.has(name))
42
+ lines.set(name, i + 1);
43
+ }
44
+ if (/^ {2}\]/.test(all[i]))
45
+ break;
46
+ }
47
+ return lines;
48
+ }
49
+ /** The tools a finding is about: its tool, or each tool of a change found in several. */
50
+ function toolsOf(f) {
51
+ const several = f.tools;
52
+ if (Array.isArray(several))
53
+ return several.filter((t) => typeof t === 'string');
54
+ return f.tool ? [f.tool] : [];
55
+ }
56
+ /**
57
+ * A stable identity for a result across runs: rule, tool, and which of that rule's
58
+ * findings on that tool it is (one rule can find two things about one tool). Not the
59
+ * message: it carries counts that change between runs.
60
+ */
61
+ function fingerprint(rule, tool, nth) {
62
+ return createHash('sha256').update(`${rule}\u0000${tool ?? ''}\u0000${nth}`).digest('hex').slice(0, 32);
63
+ }
64
+ export function toSarif(findings, options) {
65
+ const root = options.root ?? repoRoot();
66
+ let artifact;
67
+ let lines = new Map();
68
+ if (options.menuPath) {
69
+ const abs = resolve(options.menuPath);
70
+ const rel = relative(root, abs);
71
+ // Inside the repository: relative to its root. Outside (or another drive): a file URL.
72
+ artifact = rel && rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel) ? { uri: rel.split(sep).join('/'), uriBaseId: '%SRCROOT%' } : { uri: pathToFileURL(abs).href };
73
+ try {
74
+ lines = toolLines(readFileSync(abs, 'utf8'));
75
+ }
76
+ catch {
77
+ // Not written (--no-write) or unreadable: results point at the file's first line.
78
+ }
79
+ }
80
+ const docs = ruleDocs();
81
+ const ruleIds = [...new Set(findings.map((f) => f.rule))].sort();
82
+ const seen = new Map();
83
+ const results = findings.flatMap((f) => {
84
+ const tools = toolsOf(f);
85
+ // One result per tool, so each alert sits on its own tool's line.
86
+ return (tools.length ? tools : [undefined]).map((tool) => {
87
+ const key = `${f.rule}\u0000${tool ?? ''}`;
88
+ const nth = seen.get(key) ?? 0;
89
+ seen.set(key, nth + 1);
90
+ const text = [f.message, ...(f.detail ?? []), ...(f.fix ? [`→ Next: ${f.fix}`] : [])].join('\n');
91
+ return {
92
+ ruleId: f.rule,
93
+ ruleIndex: ruleIds.indexOf(f.rule),
94
+ level: LEVEL[f.severity],
95
+ message: { text: f.confidence === 'unsure' ? `${text}\n(unsure: a heuristic, from names and words)` : text },
96
+ ...(artifact ? { locations: [{ physicalLocation: { artifactLocation: artifact, region: { startLine: (tool && lines.get(tool)) || 1 } } }] } : {}),
97
+ partialFingerprints: { 'toolmenuFinding/v1': fingerprint(f.rule, tool, nth) },
98
+ properties: { ...(tool ? { tool } : {}), ...(f.step !== undefined ? { step: f.step } : {}), ...(f.confidence ? { confidence: f.confidence } : {}) },
99
+ };
100
+ });
101
+ });
102
+ const log = {
103
+ $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
104
+ version: '2.1.0',
105
+ runs: [
106
+ {
107
+ tool: {
108
+ driver: {
109
+ name: 'toolmenu',
110
+ version: VERSION,
111
+ semanticVersion: VERSION,
112
+ informationUri: 'https://github.com/niksa90/toolmenu',
113
+ rules: ruleIds.map((id) => {
114
+ const doc = docs[id];
115
+ // RULES.md gives a default, sometimes with conditions ("warn, error if no call got through"): its first word.
116
+ const documented = /^(error|warn|info)\b/.exec(doc?.severity ?? '')?.[1];
117
+ const severity = documented ?? findings.find((f) => f.rule === id)?.severity ?? 'warn';
118
+ return {
119
+ id,
120
+ name: id.replace(/[^A-Za-z0-9]+(.)?/g, (_, c) => (c ? c.toUpperCase() : '')),
121
+ shortDescription: { text: id },
122
+ ...(doc ? { fullDescription: { text: doc.text } } : {}),
123
+ helpUri: RULES_URL,
124
+ help: { text: `toolmenu explain ${id}` },
125
+ defaultConfiguration: { level: LEVEL[severity] },
126
+ properties: { tags: ['mcp', doc?.command ?? options.command] },
127
+ };
128
+ }),
129
+ },
130
+ },
131
+ automationDetails: { id: `toolmenu/${options.command}/` },
132
+ originalUriBaseIds: { '%SRCROOT%': { uri: pathToFileURL(root + sep).href } },
133
+ results,
134
+ },
135
+ ],
136
+ };
137
+ return JSON.stringify(log, null, 2);
138
+ }
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "toolmenu",
3
- "version": "0.24.0",
3
+ "version": "0.25.1",
4
+ "mcpName": "io.github.niksa90/toolmenu",
4
5
  "description": "Lint your MCP server's tool menu for changes that confuse agents or break caches.",
5
6
  "author": "Nikša Perović (https://niksa.me)",
6
7
  "main": "dist/index.js",