toolmenu 0.12.0 → 0.14.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.
Files changed (63) hide show
  1. package/README.md +84 -23
  2. package/dist/args.d.ts +31 -5
  3. package/dist/args.js +91 -14
  4. package/dist/auth.d.ts +4 -2
  5. package/dist/auth.js +59 -21
  6. package/dist/auto.d.ts +80 -6
  7. package/dist/auto.js +255 -19
  8. package/dist/breakdown.d.ts +2 -0
  9. package/dist/breakdown.js +64 -19
  10. package/dist/catalog.d.ts +87 -10
  11. package/dist/catalog.js +415 -58
  12. package/dist/cli.js +170 -185
  13. package/dist/close.d.ts +8 -0
  14. package/dist/close.js +18 -0
  15. package/dist/config.d.ts +7 -1
  16. package/dist/config.js +17 -0
  17. package/dist/connect.d.ts +14 -0
  18. package/dist/connect.js +150 -16
  19. package/dist/diff.d.ts +23 -1
  20. package/dist/diff.js +574 -120
  21. package/dist/difference.d.ts +2 -0
  22. package/dist/difference.js +13 -12
  23. package/dist/explain.d.ts +113 -0
  24. package/dist/explain.js +461 -0
  25. package/dist/failures.d.ts +15 -0
  26. package/dist/failures.js +59 -2
  27. package/dist/help.d.ts +11 -0
  28. package/dist/help.js +205 -0
  29. package/dist/history.d.ts +13 -0
  30. package/dist/history.js +86 -6
  31. package/dist/init.d.ts +93 -2
  32. package/dist/init.js +508 -21
  33. package/dist/menu.js +10 -2
  34. package/dist/options.d.ts +141 -0
  35. package/dist/options.js +50 -0
  36. package/dist/report.d.ts +2 -2
  37. package/dist/report.js +305 -101
  38. package/dist/rules/description.d.ts +7 -2
  39. package/dist/rules/description.js +86 -42
  40. package/dist/rules/determinism.d.ts +4 -1
  41. package/dist/rules/determinism.js +175 -11
  42. package/dist/rules/gated.d.ts +7 -0
  43. package/dist/rules/gated.js +77 -0
  44. package/dist/rules/ids.d.ts +1 -1
  45. package/dist/rules/ids.js +9 -4
  46. package/dist/rules/index.d.ts +6 -0
  47. package/dist/rules/index.js +18 -6
  48. package/dist/rules/naming.d.ts +1 -1
  49. package/dist/rules/naming.js +91 -21
  50. package/dist/rules/rule.d.ts +25 -0
  51. package/dist/rules/rule.js +25 -1
  52. package/dist/rules/spec.d.ts +6 -0
  53. package/dist/rules/spec.js +56 -9
  54. package/dist/rules/write.d.ts +1 -1
  55. package/dist/rules/write.js +64 -14
  56. package/dist/session.d.ts +34 -9
  57. package/dist/session.js +525 -94
  58. package/dist/snapshot.d.ts +8 -2
  59. package/dist/snapshot.js +33 -2
  60. package/dist/types.d.ts +21 -0
  61. package/dist/words.d.ts +5 -0
  62. package/dist/words.js +14 -0
  63. package/package.json +2 -2
@@ -1,21 +1,25 @@
1
1
  import { SEVERITY_RANK } from '../types.js';
2
- import { buried, cut } from './description.js';
3
- import { connectionVariance, nondeterministic, processVariance } from './determinism.js';
2
+ import { buried, cut, lateInstruction } from './description.js';
3
+ import { connectionVariance, hostSpecific, nondeterministic, processVariance } from './determinism.js';
4
4
  import { authoredIds } from './ids.js';
5
5
  import { route, sharedWord, vagueId } from './naming.js';
6
- import { cacheHints, deprecated, discover, duplicateName, schema, toolsCapability } from './spec.js';
6
+ import { cacheHints, deprecated, discover, duplicateName, schema, serverInfo, toolsCapability } from './spec.js';
7
7
  import { noDryRun, unannotated } from './write.js';
8
+ import { gated } from './gated.js';
8
9
  export const MENU_RULES = [
9
10
  nondeterministic,
10
11
  duplicateName,
12
+ gated,
11
13
  processVariance,
12
14
  connectionVariance,
15
+ hostSpecific,
13
16
  vagueId,
14
17
  sharedWord,
15
18
  route,
16
19
  authoredIds,
17
20
  buried,
18
21
  cut,
22
+ lateInstruction,
19
23
  noDryRun,
20
24
  unannotated,
21
25
  schema,
@@ -23,18 +27,26 @@ export const MENU_RULES = [
23
27
  discover,
24
28
  deprecated,
25
29
  cacheHints,
30
+ serverInfo,
26
31
  ];
32
+ /**
33
+ * Rules split out of an older one. A setting for the old id still applies to the
34
+ * new one unless the new id is set itself: before 0.13, description/cut held
35
+ * the late-instruction hint too, and `"description/cut": "off"` turned both off.
36
+ */
37
+ export const RULE_ALIASES = { 'description/late-instruction': 'description/cut' };
27
38
  export function runRules(rules, ctx, settings = {}) {
28
39
  const ignore = (settings.ignore ?? []).map(globToRegExp);
40
+ const isIgnored = (tool) => ignore.some((re) => re.test(tool));
29
41
  const findings = [];
30
42
  for (const rule of rules) {
31
- const configured = settings.rules?.[rule.id];
43
+ const configured = settings.rules?.[rule.id] ?? (RULE_ALIASES[rule.id] ? settings.rules?.[RULE_ALIASES[rule.id]] : undefined);
32
44
  if (configured === 'off')
33
45
  continue;
34
46
  if (rule.since && (!ctx.protocolVersion || ctx.protocolVersion < rule.since))
35
47
  continue;
36
- for (const f of rule.run(ctx)) {
37
- if (f.tool && ignore.some((re) => re.test(f.tool)))
48
+ for (const f of rule.run({ ...ctx, isIgnored })) {
49
+ if (f.tool && isIgnored(f.tool))
38
50
  continue;
39
51
  findings.push({ rule: rule.id, ...f, severity: configured ?? f.severity ?? rule.severity });
40
52
  }
@@ -1,4 +1,4 @@
1
- import type { Rule } from './rule.js';
1
+ import { type Rule } from './rule.js';
2
2
  export declare const vagueId: Rule;
3
3
  export declare const sharedWord: Rule;
4
4
  export declare const route: Rule;
@@ -1,5 +1,6 @@
1
- import { commonWords, nouns, singular, words } from '../words.js';
1
+ import { COLLECTION_VERBS, LOOKUP_VERBS, VERBS, WRITE_VERBS, commonWords, nouns, singular, verbOf, words } from '../words.js';
2
2
  import { missingWords, negatedMention, routeScores } from '../routes.js';
3
+ import { kept, names } from './rule.js';
3
4
  // Not `ref`: in real menus it's a git ref (GitHub ×4), a name with a meaning of its own.
4
5
  const VAGUE_IDS = /^(id|ids|uuid|uuids|identifier|identifiers)$/i;
5
6
  export const vagueId = {
@@ -8,20 +9,47 @@ export const vagueId = {
8
9
  lesson: '04',
9
10
  summary: 'ID parameters say which kind of thing they identify',
10
11
  run(ctx) {
11
- const findings = [];
12
- for (const tool of ctx.menu.tools) {
13
- for (const param of Object.keys(tool.inputSchema?.properties ?? {})) {
14
- if (VAGUE_IDS.test(param)) {
15
- findings.push({
16
- tool: tool.name,
17
- message: `${tool.name}.${param}: says "${param}" but not which kind of thing it identifies. Name it after the thing (e.g. form_id) so the agent doesn't pass the wrong ID.`,
18
- });
19
- }
12
+ const common = commonWords(ctx.menu.tools.map((t) => t.name));
13
+ const found = [];
14
+ for (const tool of kept(ctx.menu.tools, ctx)) {
15
+ const params = Object.keys(tool.inputSchema?.properties ?? {});
16
+ for (const param of params.filter((p) => VAGUE_IDS.test(p))) {
17
+ found.push({ tool: tool.name, param, where: `${tool.name}.${param}`, suggestion: betterName(tool.name, param, params, common) });
20
18
  }
21
19
  }
22
- return findings;
20
+ if (found.length === 0)
21
+ return [];
22
+ const one = found.length === 1;
23
+ const example = found.find((f) => f.suggestion) ?? found[0];
24
+ const tools = [...new Set(found.map((f) => f.tool))];
25
+ const said = names([...new Set(found.map((f) => `"${f.param}"`))].slice(0, 4));
26
+ // One finding: the same naming habit in 20 tools is one thing to change.
27
+ return [
28
+ {
29
+ ...(tools.length === 1 ? { tool: tools[0] } : {}),
30
+ confidence: 'unsure',
31
+ message: `${one ? `${found[0].where} is` : `${found.length} parameters are`} called just ${said}, which doesn't say which kind of thing ${one ? 'it identifies' : 'each one identifies'}. An agent holding several kinds of ID has only the description to pick the right one.`,
32
+ ...(one ? {} : { detail: found.map((f) => f.where + (f.suggestion ? ` (${f.suggestion}?)` : '')) }),
33
+ fix: `Name ${one ? 'it' : 'each one'} after what it identifies${example.suggestion ? ` (${example.where} → ${example.suggestion})` : ' (form_id, not id)'}. If renaming would break callers, say in the parameter's description which kind of ID it takes and which tool returns it.`,
34
+ },
35
+ ];
23
36
  },
24
37
  };
38
+ /** thing_id for get_thing.id, when the tool name has exactly one subject noun. */
39
+ function betterName(tool, param, params, common) {
40
+ // Only where the verb acts on the thing itself: get_monitor.id is a monitor's,
41
+ // check_crawl_status.id is a crawl job's, not a status's. Not on collection
42
+ // verbs: list_comments.id is usually the post's, not a comment's.
43
+ const verb = verbOf(tool);
44
+ if (!verb || COLLECTION_VERBS.has(verb) || !(LOOKUP_VERBS.has(verb) || WRITE_VERBS.has(verb)))
45
+ return undefined;
46
+ const subject = [...new Set(nouns(tool).filter((n) => !common.has(n)))];
47
+ if (subject.length !== 1)
48
+ return undefined;
49
+ const lower = param.toLowerCase();
50
+ // Follow the tool's own style: formId next to other camelCase parameters.
51
+ return params.some((p) => /[a-z][A-Z]/.test(p)) ? subject[0] + lower[0].toUpperCase() + lower.slice(1) : `${subject[0]}_${lower}`;
52
+ }
25
53
  export const sharedWord = {
26
54
  id: 'naming/shared-word',
27
55
  severity: 'info',
@@ -29,10 +57,27 @@ export const sharedWord = {
29
57
  summary: 'The same noun used for different things across tools',
30
58
  run(ctx) {
31
59
  const byNoun = new Map();
32
- const common = commonWords(ctx.menu.tools.map((t) => t.name));
33
- const subject = (name) => nouns(name).filter((n) => !common.has(n));
60
+ // Compared in the singular: "maps" in every name is as common as "map".
61
+ const common = new Set([...commonWords(ctx.menu.tools.map((t) => t.name))].map(singular));
62
+ const subject = (name) => nouns(name).filter((n) => !common.has(singular(n)));
63
+ // A word that opens two or more tool names is a namespace (content_*, maps_*):
64
+ // where it opens the name it isn't the tool's subject, so it isn't compared as
65
+ // a shared word there. It still tells qualifiers apart (content_get_entry vs
66
+ // context_get_entry both say "entry").
67
+ const opens = new Map();
68
+ for (const tool of ctx.menu.tools) {
69
+ const first = singular(words(tool.name)[0] ?? '');
70
+ if (first)
71
+ opens.set(first, (opens.get(first) ?? 0) + 1);
72
+ }
73
+ const namespace = (name) => {
74
+ const first = singular(words(name)[0] ?? '');
75
+ return (opens.get(first) ?? 0) >= 2 && !VERBS.has(first) ? first : undefined;
76
+ };
34
77
  for (const tool of ctx.menu.tools) {
35
78
  for (const noun of new Set(subject(tool.name))) {
79
+ if (noun === namespace(tool.name))
80
+ continue;
36
81
  byNoun.set(noun, [...(byNoun.get(noun) ?? []), tool]);
37
82
  }
38
83
  }
@@ -43,6 +88,12 @@ export const sharedWord = {
43
88
  for (const [noun, tools] of byNoun) {
44
89
  if (tools.length > 1 && tools.every((t) => singular(firstWord(t.name) ?? '') === noun))
45
90
  continue;
91
+ // In every tool's name of a menu of three or more, it's the server's one subject
92
+ // (DeepWiki: ask_wiki_question, read_wiki_contents, read_wiki_structure), not two
93
+ // things sharing a word. Two tools are too few to tell: list_team_audits and
94
+ // get_audit_trail are the clash this rule exists for.
95
+ if (tools.length >= 3 && tools.length === ctx.menu.tools.length)
96
+ continue;
46
97
  // Tools where the noun is qualified differently and neither qualifier set
47
98
  // contains the other: list_team_audits vs get_audit_trail.
48
99
  const qualifiers = tools.map((t) => ({ tool: t.name, rest: new Set(subject(t.name).filter((n) => n !== noun)) }));
@@ -59,8 +110,9 @@ export const sharedWord = {
59
110
  }
60
111
  }
61
112
  }
62
- if (clashes.size > 0)
63
- groups.push({ noun, tools: [...clashes] });
113
+ const shown = [...clashes].filter((t) => !ctx.isIgnored?.(t));
114
+ if (shown.length > 1)
115
+ groups.push({ noun, tools: shown });
64
116
  }
65
117
  if (groups.length === 0)
66
118
  return [];
@@ -69,7 +121,9 @@ export const sharedWord = {
69
121
  const shown = groups.slice(0, 8);
70
122
  return [
71
123
  {
72
- message: `${groups.length === 1 ? `"${groups[0].noun}" names` : `${groups.length} words name`} different things across tools. Worth a look where an agent could route a question to the wrong one; pin the ones that matter with routes.yml.`,
124
+ confidence: 'unsure',
125
+ message: `${groups.length === 1 ? `"${groups[0].noun}" appears` : `${groups.length} words appear`} in tool names that qualify ${groups.length === 1 ? 'it' : 'them'} differently, the way list_team_audits and get_audit_trail both say "audit". Where the word means two things, an agent asked about it can pick the wrong tool; where it means one, all is well.`,
126
+ fix: 'For each word that means two things, rename one side or pin the right tool for the word in routes.yml, so a later rename can\'t quietly undo it.',
73
127
  detail: shown.map((g) => `"${g.noun}": ${g.tools.join(', ')}`).concat(groups.length > shown.length ? [`…and ${groups.length - shown.length} more (--json lists all)`] : []),
74
128
  words: groups,
75
129
  },
@@ -94,8 +148,17 @@ export const route = {
94
148
  if (!names.has(name)) {
95
149
  // A server that announces list changes may unlock the tool later.
96
150
  findings.push(gated
97
- ? { tool: name, severity: 'info', message: `routes.yml "${keyword}" names ${name}, which isn't in the menu yet. The server can change its menu, so it may appear after an unlock; if it was renamed or removed, update routes.yml. Check this route against the full menu.` }
98
- : { tool: name, message: `routes.yml "${keyword}" names ${name}, which isn't in the menu. Renamed or removed?` });
151
+ ? {
152
+ tool: name,
153
+ severity: 'info',
154
+ message: `routes.yml "${keyword}" names ${name}, which isn't in the menu yet. The server announces menu changes, so it may appear after an unlock.`,
155
+ fix: `If ${name} was renamed or removed, update routes.yml; if it comes with an unlock, check this route against the menu after it (toolmenu session).`,
156
+ }
157
+ : {
158
+ tool: name,
159
+ message: `routes.yml "${keyword}" names ${name}, which isn't in the menu, so this route can't be checked. Renamed or removed?`,
160
+ fix: `Update "${keyword}" in routes.yml to the tool's current name, or take ${name} out of it.`,
161
+ });
99
162
  }
100
163
  }
101
164
  const scores = routeScores(keyword, ctx.menu.tools);
@@ -113,8 +176,11 @@ export const route = {
113
176
  findings.push({
114
177
  tool: good,
115
178
  message: missing.length > 0
116
- ? `"${keyword}" doesn't match ${good} at all: ${missing.map((w) => `"${w}"`).join(', ')} ${missing.length === 1 ? "isn't" : "aren't"} in its name or description.`
117
- : `"${keyword}" doesn't match ${good} at all.`,
179
+ ? `"${keyword}" doesn't match ${good} at all, the tool routes.yml says it must reach: ${missing.map((w) => `"${w}"`).join(', ')} ${missing.length === 1 ? "isn't" : "aren't"} in its name or description.`
180
+ : `"${keyword}" doesn't match ${good} at all, the tool routes.yml says it must reach.`,
181
+ fix: missing.length > 0
182
+ ? `Use ${missing.map((w) => `"${w}"`).join(', ')} in the ${good} description, or change the route word in routes.yml to one it has.`
183
+ : `Change the route word in routes.yml to one the name or description of ${good} has.`,
118
184
  });
119
185
  continue;
120
186
  }
@@ -123,7 +189,10 @@ export const route = {
123
189
  if (badScore >= goodScore) {
124
190
  findings.push({
125
191
  tool: good,
126
- message: `"${keyword}" matches ${bad} (score ${badScore}) at least as well as ${good} (score ${goodScore}). An agent could route it to the wrong tool.${why(bad)}${badScore === goodScore && !why(bad) ? ' Neither the names nor the descriptions separate them: pick a route word only the right tool has, or give it one.' : ''}`,
192
+ message: `"${keyword}" matches ${bad} (score ${badScore}) at least as well as ${good} (score ${goodScore}), so an agent could route it to the wrong tool.${why(bad)}${badScore === goodScore && !why(bad) ? ' Neither the names nor the descriptions separate them.' : ''}`,
193
+ fix: why(bad)
194
+ ? `Say what ${bad} isn't for without the words "${keyword}" (name the other tool instead), or give ${good} more of them.`
195
+ : `Give ${good} words for "${keyword}" in its name or description that ${bad} doesn't have.`,
127
196
  });
128
197
  }
129
198
  }
@@ -136,6 +205,7 @@ export const route = {
136
205
  findings.push({
137
206
  tool: bad,
138
207
  message: `"${keyword}" matches ${bad} (score ${badScore}), which routes.yml says must not match it.${why(bad)}`,
208
+ fix: `Take "${keyword}" out of the name and description of ${bad}, or drop the route if the match is right after all.`,
139
209
  });
140
210
  }
141
211
  }
@@ -19,10 +19,23 @@ export interface RuleContext {
19
19
  probes?: import('./determinism.js').Probe[];
20
20
  /** The stdio command is a container wrapper (docker run …): env vars may not reach the server. */
21
21
  wrapper?: boolean;
22
+ /** serverInfo as the handshake sent it, when there was one (snapshot): spec/server-info. */
23
+ serverInfo?: {
24
+ name?: string;
25
+ version?: string;
26
+ };
27
+ /** How this run reached the server, as the command line ends: `-- node server.js` or the URL. For next steps. */
28
+ server?: string;
22
29
  /** Where clients are assumed to cut tool descriptions (description/buried). */
23
30
  descriptionLimit?: number | string;
24
31
  /** Tools (names or globs) the client sends uncut, so description/buried skips them. */
25
32
  fullDescriptions?: string[];
33
+ /**
34
+ * Set by runRules from the `ignore` setting. Rules that sum many tools up in
35
+ * one finding use it to leave ignored tools out of the summary; findings about
36
+ * one tool are dropped by runRules itself.
37
+ */
38
+ isIgnored?: (tool: string) => boolean;
26
39
  }
27
40
  export type RuleFinding = Omit<Finding, 'rule' | 'severity'> & {
28
41
  severity?: Severity;
@@ -37,3 +50,15 @@ export interface Rule {
37
50
  summary: string;
38
51
  run(ctx: RuleContext): RuleFinding[];
39
52
  }
53
+ /** 2048 → "2,048". */
54
+ export declare function num(n: number): string;
55
+ /** "1 tool", "3 tools". */
56
+ export declare function count(n: number, one: string, many?: string): string;
57
+ /** "a, b and c"; the first `max` and "and N more" when there are more. */
58
+ export declare function names(items: string[], max?: number): string;
59
+ /** Text on one line, cut to `max` characters with an ellipsis. */
60
+ export declare function clip(text: string, max: number): string;
61
+ /** Tools the `ignore` setting doesn't drop, for findings that sum many tools up. */
62
+ export declare function kept<T extends {
63
+ name: string;
64
+ }>(tools: T[], ctx: RuleContext): T[];
@@ -1 +1,25 @@
1
- export {};
1
+ /** 2048 → "2,048". */
2
+ export function num(n) {
3
+ return n.toLocaleString('en-US');
4
+ }
5
+ /** "1 tool", "3 tools". */
6
+ export function count(n, one, many = `${one}s`) {
7
+ return `${num(n)} ${n === 1 ? one : many}`;
8
+ }
9
+ /** "a, b and c"; the first `max` and "and N more" when there are more. */
10
+ export function names(items, max = Infinity) {
11
+ const shown = items.slice(0, max);
12
+ const rest = items.length - shown.length;
13
+ if (rest > 0)
14
+ return `${shown.join(', ')} and ${num(rest)} more`;
15
+ return shown.length <= 1 ? shown.join('') : `${shown.slice(0, -1).join(', ')} and ${shown[shown.length - 1]}`;
16
+ }
17
+ /** Text on one line, cut to `max` characters with an ellipsis. */
18
+ export function clip(text, max) {
19
+ const flat = text.replace(/\s+/g, ' ').trim();
20
+ return flat.length > max ? flat.slice(0, max - 1) + '…' : flat;
21
+ }
22
+ /** Tools the `ignore` setting doesn't drop, for findings that sum many tools up. */
23
+ export function kept(tools, ctx) {
24
+ return ctx.isIgnored ? tools.filter((t) => !ctx.isIgnored(t.name)) : tools;
25
+ }
@@ -4,4 +4,10 @@ export declare const toolsCapability: Rule;
4
4
  export declare const duplicateName: Rule;
5
5
  export declare const discover: Rule;
6
6
  export declare const deprecated: Rule;
7
+ /**
8
+ * serverInfo { name, version } is required in the handshake (both protocol
9
+ * generations). Without them reports say "unknown server", and clients and logs
10
+ * can't tell which server or release answered (Netlify sends neither).
11
+ */
12
+ export declare const serverInfo: Rule;
7
13
  export declare const cacheHints: Rule;
@@ -34,20 +34,34 @@ export const schema = {
34
34
  return [];
35
35
  const validate = listToolsValidator(ctx.protocolVersion);
36
36
  if (!validate) {
37
- return [{ severity: 'info', message: `No official schema bundled for protocol ${ctx.protocolVersion}; schema check skipped.` }];
37
+ return [
38
+ {
39
+ severity: 'info',
40
+ message: `This toolmenu has no official schema for protocol ${ctx.protocolVersion}, so the tools/list result wasn't checked against one.`,
41
+ fix: 'Nothing to change on the server; a newer toolmenu may bundle this version\'s schema.',
42
+ },
43
+ ];
38
44
  }
39
45
  const findings = [];
40
46
  if (ctx.clientError && ctx.pages.every((page) => validate(page))) {
41
- findings.push({ message: `The official MCP SDK client rejected the tools/list result: ${ctx.clientError.split('\n')[0]}` });
47
+ findings.push({
48
+ 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: ${ctx.clientError.split('\n')[0]}`,
49
+ fix: 'Fix what the SDK names above, then list the tools with the official client to confirm.',
50
+ });
42
51
  }
43
52
  ctx.pages.forEach((page, i) => {
44
53
  if (validate(page))
45
54
  return;
46
55
  const errors = validate.errors ?? [];
56
+ const missing = [...new Set(errors.filter((e) => !e.instancePath && e.params && 'missingProperty' in e.params).map((e) => String(e.params.missingProperty)))];
57
+ const first = errors[0];
47
58
  findings.push({
48
- message: `tools/list result${ctx.pages.length > 1 ? ` (page ${i + 1})` : ''} doesn't match the ${ctx.protocolVersion} schema.`,
49
- detail: (ctx.clientError ? ['The official MCP SDK client rejects this result, so real clients will fail to list tools.'] : []).concat(errors.slice(0, 5).map((e) => `${e.instancePath || '(result)'} ${e.message}${e.params && 'missingProperty' in e.params ? `: ${e.params.missingProperty}` : ''}`)
50
- .concat(errors.length > 5 ? [`…and ${errors.length - 5} more`] : [])),
59
+ message: `The tools/list result${ctx.pages.length > 1 ? ` (page ${i + 1})` : ''} doesn't match the official ${ctx.protocolVersion} schema${ctx.clientError ? ', and the official MCP SDK client rejects it, so clients built on it list no tools' : ', so a strict client may refuse it'}.`,
60
+ detail: errors.slice(0, 5).map((e) => `${e.instancePath || '(result)'} ${e.message}${e.params && 'missingProperty' in e.params ? `: ${e.params.missingProperty}` : ''}`)
61
+ .concat(errors.length > 5 ? [`…and ${errors.length - 5} more`] : []),
62
+ fix: missing.length
63
+ ? `Add ${missing.join(', ')} to the tools/list result${missing.some((m) => m === 'ttlMs' || m === 'cacheScope') ? ` (${ctx.protocolVersion} requires cache hints on it, SEP-2549)` : ''}.`
64
+ : `Fix ${first?.instancePath || 'the result'} first (${first?.message ?? 'see above'}), then rerun.`,
51
65
  });
52
66
  });
53
67
  return findings;
@@ -62,7 +76,8 @@ export const toolsCapability = {
62
76
  return [];
63
77
  return [
64
78
  {
65
- message: `The server doesn't declare the tools capability, so clients don't ask for its tools: the official MCP SDK client returns an empty list without sending tools/list${ctx.menu.tools.length ? '' : ', and that is the menu toolmenu got'}. Declare "tools": {} in the server's capabilities.`,
79
+ message: `The server doesn't declare the tools capability, so clients don't ask for its tools: the official MCP SDK client returns an empty list without sending tools/list${ctx.menu.tools.length ? '' : ', and that is the menu toolmenu got'}.`,
80
+ fix: 'Declare "tools": {} in the capabilities the server sends at initialize.',
66
81
  },
67
82
  ];
68
83
  },
@@ -79,6 +94,7 @@ export const duplicateName = {
79
94
  .map(([name, at]) => ({
80
95
  tool: name,
81
96
  message: `${at.length} tools are named ${name} (positions ${at.join(', ')}). A call names the tool, so only one of them can be reached; clients may keep either, or reject the whole list (Claude's API refuses duplicate tool names).`,
97
+ fix: `Give each ${name} its own name, or drop the copy if it's the same tool listed twice.`,
82
98
  }));
83
99
  },
84
100
  };
@@ -92,6 +108,7 @@ export const discover = {
92
108
  return [
93
109
  {
94
110
  message: `The server answered with protocol ${ctx.protocolVersion} and no working server/discover, so it isn't on 2026-07-28 yet. Rules for 2026-07-28 were skipped.`,
111
+ fix: 'Nothing to do on 2025; when the server moves to 2026-07-28, implement server/discover and rerun for the 2026 checks.',
95
112
  },
96
113
  ];
97
114
  },
@@ -103,11 +120,39 @@ export const deprecated = {
103
120
  summary: 'Deprecated features still advertised',
104
121
  run(ctx) {
105
122
  if ('logging' in ctx.capabilities) {
106
- return [{ message: 'Advertises the logging capability, which 2026-07-28 deprecates (SEP-2577). Log to stderr or use OpenTelemetry instead.' }];
123
+ return [
124
+ {
125
+ message: 'The server advertises the logging capability, which 2026-07-28 deprecates (SEP-2577), so clients may stop asking for its logs.',
126
+ fix: 'Stop advertising logging; log to stderr or through OpenTelemetry instead.',
127
+ },
128
+ ];
107
129
  }
108
130
  return [];
109
131
  },
110
132
  };
133
+ /**
134
+ * serverInfo { name, version } is required in the handshake (both protocol
135
+ * generations). Without them reports say "unknown server", and clients and logs
136
+ * can't tell which server or release answered (Netlify sends neither).
137
+ */
138
+ export const serverInfo = {
139
+ id: 'spec/server-info',
140
+ severity: 'warn',
141
+ summary: 'The handshake names the server and its version',
142
+ run(ctx) {
143
+ if (!ctx.serverInfo)
144
+ return [];
145
+ const missing = [!ctx.serverInfo.name ? 'name' : '', !ctx.serverInfo.version ? 'version' : ''].filter(Boolean);
146
+ if (!missing.length)
147
+ return [];
148
+ return [
149
+ {
150
+ message: `The server's handshake has no serverInfo ${missing.join(' or ')}, which the spec requires. Clients, logs and this report can't tell which ${missing.length === 2 ? 'server or release' : missing[0] === 'name' ? 'server' : 'release'} answered${ctx.serverInfo.name ? ` (${ctx.serverInfo.name})` : ''}.`,
151
+ fix: 'Set serverInfo { name, version } where the server is created, the version from its package.',
152
+ },
153
+ ];
154
+ },
155
+ };
111
156
  export const cacheHints = {
112
157
  id: 'spec/cache-hints',
113
158
  severity: 'info',
@@ -118,12 +163,14 @@ export const cacheHints = {
118
163
  const meta = ctx.menu.listMeta ?? {};
119
164
  if (meta.ttlMs === 0) {
120
165
  findings.push({
121
- message: 'tools/list has ttlMs: 0, so clients treat the list as immediately stale and may re-fetch it every time. Valid per spec (and the default in the official TypeScript SDK v2). If the tool set is stable, a positive ttlMs saves the polling.',
166
+ message: 'tools/list says ttlMs: 0, so clients treat the list as stale the moment it arrives and may fetch it again before every use. Valid per spec, and the default in the official TypeScript SDK v2.',
167
+ fix: 'If the tool set is stable, set a positive ttlMs on tools/list (3600000 is an hour).',
122
168
  });
123
169
  }
124
170
  if (meta.cacheScope === 'public' && ctx.usedAuth) {
125
171
  findings.push({
126
- message: 'tools/list is cacheScope "public" on a server that took credentials. Public means shared caches may serve it across authorization contexts. Fine only if the tool set never depends on the caller.',
172
+ message: 'tools/list says cacheScope: "public" on a server that took credentials. Public lets shared caches serve the list to other callers, across authorization contexts. Fine only if the tool set never depends on who is asking.',
173
+ fix: 'If tools depend on the caller\'s account or scopes, set cacheScope: "private" on tools/list.',
127
174
  });
128
175
  }
129
176
  return findings;
@@ -1,3 +1,3 @@
1
- import type { Rule } from './rule.js';
1
+ import { type Rule } from './rule.js';
2
2
  export declare const unannotated: Rule;
3
3
  export declare const noDryRun: Rule;
@@ -1,24 +1,53 @@
1
1
  import { WRITE_VERBS, nouns, verbOf, words } from '../words.js';
2
+ import { count, kept, names } from './rule.js';
2
3
  const DRY_RUN_PARAMS = /^(dry[_-]?run|preview|validate[_-]?only|simulate|plan|what[_-]?if)$/i;
3
4
  const PREVIEW_WORDS = new Set(['preview', 'validate', 'plan', 'simulate', 'dry']);
5
+ /** Write verbs that only add something; the others delete or overwrite. A guess from the name. */
6
+ const ADDITIVE_VERBS = new Set(['create', 'add', 'insert', 'send', 'post', 'publish', 'submit', 'upload', 'assign', 'invite', 'approve']);
4
7
  function isWriteByName(tool) {
5
8
  return WRITE_VERBS.has(verbOf(tool.name) ?? '');
6
9
  }
7
10
  function hasAnnotations(tool) {
8
11
  return !!tool.annotations && Object.keys(tool.annotations).length > 0;
9
12
  }
13
+ const WHY = 'Without readOnlyHint and destructiveHint, a client has to assume the worst of every write, and neither the client nor the agent can tell a harmless create from a delete when deciding what to confirm.';
10
14
  export const unannotated = {
11
15
  id: 'write/unannotated',
12
16
  severity: 'warn',
13
17
  lesson: '02',
14
18
  summary: 'Tools that look like writes carry annotations',
15
19
  run(ctx) {
16
- return ctx.menu.tools
17
- .filter((t) => isWriteByName(t) && !hasAnnotations(t))
18
- .map((t) => ({
19
- tool: t.name,
20
- message: `${t.name}: the name suggests it changes something, but it has no annotations. Say readOnlyHint/destructiveHint so clients and agents know.`,
21
- }));
20
+ const bare = kept(ctx.menu.tools, ctx).filter((t) => isWriteByName(t) && !hasAnnotations(t));
21
+ if (bare.length === 0)
22
+ return [];
23
+ const additive = (t) => ADDITIVE_VERBS.has(verbOf(t.name));
24
+ // One finding, not one per tool: the same gap in 53 tools is one thing to fix.
25
+ if (bare.length === 1) {
26
+ const [tool] = bare;
27
+ const adds = additive(tool);
28
+ return [
29
+ {
30
+ tool: tool.name,
31
+ confidence: 'unsure',
32
+ message: `${tool.name} is named like a write ("${verbOf(tool.name)}") and has no annotations. ${WHY}`,
33
+ fix: `Add annotations: { readOnlyHint: false, destructiveHint: ${!adds} } to ${tool.name} (${adds ? 'true if it can also delete or overwrite' : 'false if it only adds'}), or { readOnlyHint: true } if it changes nothing.`,
34
+ },
35
+ ];
36
+ }
37
+ const verbs = [...new Set(bare.map((t) => `${verbOf(t.name)}…`))];
38
+ const overwrites = bare.filter((t) => !additive(t)).map((t) => t.name);
39
+ const adds = bare.filter(additive).map((t) => t.name);
40
+ return [
41
+ {
42
+ confidence: 'unsure',
43
+ message: `${count(bare.length, 'tool')} are named like writes (${names(verbs, 6)}) and have no annotations. ${WHY}`,
44
+ detail: [
45
+ ...(overwrites.length ? [`Delete or overwrite, going by the name (destructiveHint: true): ${overwrites.join(', ')}`] : []),
46
+ ...(adds.length ? [`Only add, going by the name (destructiveHint: false): ${adds.join(', ')}`] : []),
47
+ ],
48
+ fix: 'Add annotations to each: { readOnlyHint: false, destructiveHint: true } where it deletes or overwrites, { readOnlyHint: false, destructiveHint: false } where it only adds. The split above is a guess from the names: check each tool.',
49
+ },
50
+ ];
22
51
  },
23
52
  };
24
53
  export const noDryRun = {
@@ -27,11 +56,16 @@ export const noDryRun = {
27
56
  lesson: '02',
28
57
  summary: 'Destructive tools offer a way to look before leaping',
29
58
  run(ctx) {
59
+ // Annotated destructive (destructiveHint: true), or destructive only because the
60
+ // spec says so when a tool says readOnlyHint: false and nothing more: told apart,
61
+ // since "hover" counted as destructive is a missing annotation, not a missing dry run.
30
62
  const missing = [];
31
- for (const tool of ctx.menu.tools) {
63
+ const byDefault = [];
64
+ for (const tool of kept(ctx.menu.tools, ctx)) {
32
65
  const a = tool.annotations ?? {};
33
- const destructive = a.destructiveHint === true || (a.readOnlyHint === false && a.destructiveHint !== false);
34
- if (!destructive)
66
+ const annotated = a.destructiveHint === true;
67
+ const defaulted = !annotated && a.readOnlyHint === false && a.destructiveHint === undefined;
68
+ if (!annotated && !defaulted)
35
69
  continue;
36
70
  const hasParam = Object.keys(tool.inputSchema?.properties ?? {}).some((p) => DRY_RUN_PARAMS.test(p));
37
71
  const subject = new Set(nouns(tool.name));
@@ -39,16 +73,32 @@ export const noDryRun = {
39
73
  words(other.name).some((w) => PREVIEW_WORDS.has(w)) &&
40
74
  nouns(other.name).some((n) => subject.has(n)));
41
75
  if (!hasParam && !hasPreviewTool)
42
- missing.push(tool.name);
76
+ (annotated ? missing : byDefault).push(tool.name);
43
77
  }
44
- if (missing.length === 0)
78
+ if (missing.length === 0 && byDefault.length === 0)
45
79
  return [];
80
+ const defaultLine = `Destructive only by default (readOnlyHint: false and no destructiveHint): ${byDefault.join(', ')}`;
81
+ if (missing.length === 0) {
82
+ const one = byDefault.length === 1;
83
+ return [
84
+ {
85
+ ...(one ? { tool: byDefault[0] } : {}),
86
+ confidence: 'unsure',
87
+ message: `${one ? `${byDefault[0]} is` : `${count(byDefault.length, 'tool')} are`} destructive only by default: ${one ? 'it says' : 'they say'} readOnlyHint: false and nothing about destructiveHint, which the spec reads as destructive, and toolmenu found no dry_run/preview-style parameter or preview tool. Clients then confirm ${one ? 'it' : 'them'} like a delete.`,
88
+ ...(one ? {} : { detail: [byDefault.join(', ')] }),
89
+ fix: `Set destructiveHint on each: false where it only reads, adds or changes something cheap to undo, true where it deletes or overwrites (and then consider a dry_run parameter).`,
90
+ },
91
+ ];
92
+ }
93
+ const one = missing.length === 1;
46
94
  // One finding, not one per tool: it's a design note, not a list of defects.
47
95
  return [
48
96
  {
49
- ...(missing.length === 1 ? { tool: missing[0] } : {}),
50
- message: `${missing.length === 1 ? `${missing[0]} is` : `${missing.length} tools are`} destructive with no dry_run/preview parameter and no matching preview tool. Where the effect is costly to undo, a dry run lets the agent catch its own mistake while it's cheap.`,
51
- ...(missing.length > 1 ? { detail: [missing.join(', ')] } : {}),
97
+ ...(one && !byDefault.length ? { tool: missing[0] } : {}),
98
+ confidence: 'unsure',
99
+ message: `${one ? `${missing[0]} is` : `${count(missing.length, 'tool')} are`} annotated as destructive, and toolmenu found no dry_run/preview-style parameter and no preview tool for the same thing. Where a mistake is costly to undo, a dry run lets the agent see what would change while it can still back out.`,
100
+ ...(one && !byDefault.length ? {} : { detail: [...(one ? [] : [missing.join(', ')]), ...(byDefault.length ? [defaultLine] : [])] }),
101
+ fix: `Where the effect is hard to undo, add a dry_run parameter${one ? ` to ${missing[0]}` : ''} that returns what would change without changing it. If it's cheap to undo, or a preview exists under another name, ignore this.${byDefault.length ? ` For the tools destructive only by default, set destructiveHint: false on the ones that don't delete or overwrite.` : ''}`,
52
102
  },
53
103
  ];
54
104
  },