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.
- package/README.md +84 -23
- package/dist/args.d.ts +31 -5
- package/dist/args.js +91 -14
- package/dist/auth.d.ts +4 -2
- package/dist/auth.js +59 -21
- package/dist/auto.d.ts +80 -6
- package/dist/auto.js +255 -19
- package/dist/breakdown.d.ts +2 -0
- package/dist/breakdown.js +64 -19
- package/dist/catalog.d.ts +87 -10
- package/dist/catalog.js +415 -58
- package/dist/cli.js +170 -185
- package/dist/close.d.ts +8 -0
- package/dist/close.js +18 -0
- package/dist/config.d.ts +7 -1
- package/dist/config.js +17 -0
- package/dist/connect.d.ts +14 -0
- package/dist/connect.js +150 -16
- package/dist/diff.d.ts +23 -1
- package/dist/diff.js +574 -120
- package/dist/difference.d.ts +2 -0
- package/dist/difference.js +13 -12
- package/dist/explain.d.ts +113 -0
- package/dist/explain.js +461 -0
- package/dist/failures.d.ts +15 -0
- package/dist/failures.js +59 -2
- package/dist/help.d.ts +11 -0
- package/dist/help.js +205 -0
- package/dist/history.d.ts +13 -0
- package/dist/history.js +86 -6
- package/dist/init.d.ts +93 -2
- package/dist/init.js +508 -21
- package/dist/menu.js +10 -2
- package/dist/options.d.ts +141 -0
- package/dist/options.js +50 -0
- package/dist/report.d.ts +2 -2
- package/dist/report.js +305 -101
- package/dist/rules/description.d.ts +7 -2
- package/dist/rules/description.js +86 -42
- package/dist/rules/determinism.d.ts +4 -1
- package/dist/rules/determinism.js +175 -11
- package/dist/rules/gated.d.ts +7 -0
- package/dist/rules/gated.js +77 -0
- package/dist/rules/ids.d.ts +1 -1
- package/dist/rules/ids.js +9 -4
- package/dist/rules/index.d.ts +6 -0
- package/dist/rules/index.js +18 -6
- package/dist/rules/naming.d.ts +1 -1
- package/dist/rules/naming.js +91 -21
- package/dist/rules/rule.d.ts +25 -0
- package/dist/rules/rule.js +25 -1
- package/dist/rules/spec.d.ts +6 -0
- package/dist/rules/spec.js +56 -9
- package/dist/rules/write.d.ts +1 -1
- package/dist/rules/write.js +64 -14
- package/dist/session.d.ts +34 -9
- package/dist/session.js +525 -94
- package/dist/snapshot.d.ts +8 -2
- package/dist/snapshot.js +33 -2
- package/dist/types.d.ts +21 -0
- package/dist/words.d.ts +5 -0
- package/dist/words.js +14 -0
- package/package.json +2 -2
package/dist/rules/index.js
CHANGED
|
@@ -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 &&
|
|
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
|
}
|
package/dist/rules/naming.d.ts
CHANGED
package/dist/rules/naming.js
CHANGED
|
@@ -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
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
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
|
-
|
|
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
|
-
|
|
33
|
-
const
|
|
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
|
-
|
|
63
|
-
|
|
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
|
-
|
|
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
|
-
? {
|
|
98
|
-
|
|
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})
|
|
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
|
}
|
package/dist/rules/rule.d.ts
CHANGED
|
@@ -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[];
|
package/dist/rules/rule.js
CHANGED
|
@@ -1 +1,25 @@
|
|
|
1
|
-
|
|
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
|
+
}
|
package/dist/rules/spec.d.ts
CHANGED
|
@@ -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;
|
package/dist/rules/spec.js
CHANGED
|
@@ -34,20 +34,34 @@ export const schema = {
|
|
|
34
34
|
return [];
|
|
35
35
|
const validate = listToolsValidator(ctx.protocolVersion);
|
|
36
36
|
if (!validate) {
|
|
37
|
-
return [
|
|
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({
|
|
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:
|
|
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'}
|
|
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 [
|
|
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
|
|
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
|
|
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;
|
package/dist/rules/write.d.ts
CHANGED
package/dist/rules/write.js
CHANGED
|
@@ -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
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
|
|
63
|
+
const byDefault = [];
|
|
64
|
+
for (const tool of kept(ctx.menu.tools, ctx)) {
|
|
32
65
|
const a = tool.annotations ?? {};
|
|
33
|
-
const
|
|
34
|
-
|
|
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
|
-
...(
|
|
50
|
-
|
|
51
|
-
|
|
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
|
},
|