toolmenu 0.21.0 → 0.23.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 +68 -37
- package/dist/apps.d.ts +56 -0
- package/dist/apps.js +99 -0
- package/dist/auto.js +2 -2
- package/dist/card.d.ts +18 -0
- package/dist/card.js +39 -0
- package/dist/cli.js +37 -10
- package/dist/colour.d.ts +8 -0
- package/dist/colour.js +70 -0
- package/dist/config.d.ts +2 -0
- package/dist/config.js +2 -0
- package/dist/connect.d.ts +6 -0
- package/dist/connect.js +22 -6
- package/dist/diff.js +111 -3
- package/dist/failures.d.ts +18 -5
- package/dist/failures.js +27 -12
- package/dist/help.js +3 -2
- package/dist/mrtr.d.ts +9 -1
- package/dist/mrtr.js +17 -0
- package/dist/options.d.ts +3 -0
- package/dist/options.js +1 -0
- package/dist/probe.d.ts +11 -1
- package/dist/probe.js +18 -3
- package/dist/report.js +12 -5
- package/dist/rule-docs.json +93 -3
- package/dist/rules/apps.d.ts +11 -0
- package/dist/rules/apps.js +156 -0
- package/dist/rules/capabilities.d.ts +21 -0
- package/dist/rules/capabilities.js +103 -0
- package/dist/rules/card.d.ts +7 -0
- package/dist/rules/card.js +65 -0
- package/dist/rules/clients.js +1 -0
- package/dist/rules/description.js +3 -0
- package/dist/rules/ids.js +35 -1
- package/dist/rules/index.js +18 -2
- package/dist/rules/naming.js +3 -0
- package/dist/rules/network.d.ts +21 -0
- package/dist/rules/network.js +63 -0
- package/dist/rules/rule.d.ts +18 -0
- package/dist/rules/search.js +1 -0
- package/dist/rules/spec.d.ts +9 -1
- package/dist/rules/spec.js +117 -3
- package/dist/rules/write.d.ts +0 -6
- package/dist/rules/write.js +11 -5
- package/dist/session.js +60 -11
- package/dist/snapshot.d.ts +5 -0
- package/dist/snapshot.js +89 -5
- package/dist/types.d.ts +5 -0
- package/dist/words.d.ts +8 -0
- package/dist/words.js +30 -2
- package/package.json +1 -1
- package/schemas/server-card.json +260 -0
package/dist/rules/ids.js
CHANGED
|
@@ -61,6 +61,9 @@ export function idParams(tool) {
|
|
|
61
61
|
// A qualifier alone (`parentId`, `targetId`) says how it relates, not what it is.
|
|
62
62
|
if (kindWords.length === 1 && QUALIFIERS.has(kindWords[0]))
|
|
63
63
|
kindWords.length = 0;
|
|
64
|
+
// A GraphQL node ID is the thing's own ID: commentNodeID is a comment's (GitHub).
|
|
65
|
+
if (kindWords.length > 1 && kindWords.at(-1) === 'node')
|
|
66
|
+
kindWords.pop();
|
|
64
67
|
const prefix = kindWords.join('_');
|
|
65
68
|
// A bare `id` doesn't say what it identifies (naming/vague-id covers that), so no kind is guessed.
|
|
66
69
|
params.push({ param, kind: prefix || undefined });
|
|
@@ -73,6 +76,30 @@ function looksLikeIdValue(schema) {
|
|
|
73
76
|
const type = schema.type;
|
|
74
77
|
return type === undefined || type === 'string' || type === 'integer' || (Array.isArray(type) && type.includes('string'));
|
|
75
78
|
}
|
|
79
|
+
/**
|
|
80
|
+
* A tool's operations, when an enum lists them under their own names: a router such as
|
|
81
|
+
* github-mcp-server's actions_list { method: list_workflows | list_workflow_runs } lists
|
|
82
|
+
* workflows as surely as a list_workflows tool would. Each value that reads as a list
|
|
83
|
+
* or search (list_project_views) counts as a tool of that name, with the router's parameters.
|
|
84
|
+
*/
|
|
85
|
+
/** Marks a tool made from an enum value: it counts only when its name says the kind. */
|
|
86
|
+
const OPERATION = Symbol('operation');
|
|
87
|
+
function withOperations(tools) {
|
|
88
|
+
const out = [...tools];
|
|
89
|
+
for (const t of tools) {
|
|
90
|
+
for (const schema of Object.values(t.inputSchema?.properties ?? {})) {
|
|
91
|
+
for (const v of Array.isArray(schema.enum) ? schema.enum : []) {
|
|
92
|
+
if (typeof v !== 'string' || !/^[a-z]+(?:_[a-z]+)+$/.test(v))
|
|
93
|
+
continue;
|
|
94
|
+
// Lists and searches only: a router's get_workflow needs the ID it would hand out.
|
|
95
|
+
if (!COLLECTION_VERBS.has(singular(v.split('_')[0])))
|
|
96
|
+
continue;
|
|
97
|
+
out.push({ ...t, name: v, outputSchema: undefined, [OPERATION]: true });
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
return out;
|
|
102
|
+
}
|
|
76
103
|
/** Does some other tool look like it hands out IDs of this kind? */
|
|
77
104
|
function isReturnedBySomeTool(kind, self, tools, common) {
|
|
78
105
|
return tools.some((other) => {
|
|
@@ -86,6 +113,11 @@ function isReturnedBySomeTool(kind, self, tools, common) {
|
|
|
86
113
|
const lookup = verbs.some((v) => LOOKUP_VERBS.has(v));
|
|
87
114
|
const collection = verbs.some((v) => COLLECTION_VERBS.has(v)) || w.includes('children');
|
|
88
115
|
const needsSameId = idParams(other).some((p) => p.kind === kind);
|
|
116
|
+
// An operation from an enum counts only when it names the kind (list_workflows):
|
|
117
|
+
// sapiens' action: list_public or list_mine says nothing about which IDs it lists.
|
|
118
|
+
// And after its verb: list_public lists no "list" IDs.
|
|
119
|
+
if (other[OPERATION])
|
|
120
|
+
return lookup && `_${w.slice(1).join('_')}_`.includes(`_${kind}_`) && !needsSameId;
|
|
89
121
|
// A list or search for that kind; a get that doesn't itself need the ID.
|
|
90
122
|
if (lookup && mentionsKind && (collection || !needsSameId))
|
|
91
123
|
return true;
|
|
@@ -115,6 +147,7 @@ function outputMentions(schema, kind, depth = 0, parent = '') {
|
|
|
115
147
|
}
|
|
116
148
|
export const authoredIds = {
|
|
117
149
|
id: 'ids/authored',
|
|
150
|
+
scope: 'agent',
|
|
118
151
|
// A heuristic: IDs that only appear in another tool's text output look the same
|
|
119
152
|
// as invented ones from the schema alone (FINDINGS F12).
|
|
120
153
|
severity: 'info',
|
|
@@ -123,9 +156,10 @@ export const authoredIds = {
|
|
|
123
156
|
run(ctx) {
|
|
124
157
|
const byKind = new Map();
|
|
125
158
|
const common = commonWords(ctx.menu.tools.map((t) => t.name));
|
|
159
|
+
const operations = withOperations(ctx.menu.tools);
|
|
126
160
|
for (const tool of kept(ctx.menu.tools, ctx)) {
|
|
127
161
|
for (const { param, kind } of idParams(tool)) {
|
|
128
|
-
if (!kind || isReturnedBySomeTool(kind, tool,
|
|
162
|
+
if (!kind || isReturnedBySomeTool(kind, tool, operations, common))
|
|
129
163
|
continue;
|
|
130
164
|
const schema = tool.inputSchema?.properties?.[param];
|
|
131
165
|
if (saysWhereItComesFrom(schema, ctx.menu.tools, tool.name))
|
package/dist/rules/index.js
CHANGED
|
@@ -4,16 +4,21 @@ import { connectionVariance, hostSpecific, nondeterministic, processVariance } f
|
|
|
4
4
|
import { authoredIds } from './ids.js';
|
|
5
5
|
import { clientName } from './clients.js';
|
|
6
6
|
import { invalidCredential } from './auth.js';
|
|
7
|
+
import { networkDependent } from './network.js';
|
|
8
|
+
import { capabilityDependent } from './capabilities.js';
|
|
7
9
|
import { listSchema, listVariance } from './lists.js';
|
|
8
10
|
import { handleLifetime } from './handles.js';
|
|
9
11
|
import { authVariance, cacheScopePublic } from './identities.js';
|
|
10
12
|
import { route, sharedWord, vagueId } from './naming.js';
|
|
11
|
-
import { cacheHints, deprecated, discover, duplicateName, schema, serverInfo, toolsCapability } from './spec.js';
|
|
13
|
+
import { cacheHints, deprecated, discover, duplicateName, extensionId, schema, serverInfo, taskRequired, toolsCapability } from './spec.js';
|
|
12
14
|
import { noDryRun, readOnlyMismatch, unannotated } from './write.js';
|
|
13
15
|
import { gated } from './gated.js';
|
|
14
16
|
import { xMcpHeader } from './headers.js';
|
|
15
17
|
import { schemaRef } from './refs.js';
|
|
16
18
|
import { findable } from './search.js';
|
|
19
|
+
import { appsAppOnlyListed, appsLegacyKey, appsResource, appsVisibility } from './apps.js';
|
|
20
|
+
import { agentMenu } from '../apps.js';
|
|
21
|
+
import { serverCard } from './card.js';
|
|
17
22
|
export const MENU_RULES = [
|
|
18
23
|
nondeterministic,
|
|
19
24
|
duplicateName,
|
|
@@ -43,10 +48,19 @@ export const MENU_RULES = [
|
|
|
43
48
|
cacheHints,
|
|
44
49
|
authVariance,
|
|
45
50
|
invalidCredential,
|
|
51
|
+
networkDependent,
|
|
52
|
+
capabilityDependent,
|
|
46
53
|
listVariance,
|
|
47
54
|
listSchema,
|
|
48
55
|
cacheScopePublic,
|
|
49
56
|
serverInfo,
|
|
57
|
+
extensionId,
|
|
58
|
+
taskRequired,
|
|
59
|
+
serverCard,
|
|
60
|
+
appsResource,
|
|
61
|
+
appsLegacyKey,
|
|
62
|
+
appsVisibility,
|
|
63
|
+
appsAppOnlyListed,
|
|
50
64
|
];
|
|
51
65
|
/**
|
|
52
66
|
* Rules split out of an older one. A setting for the old id still applies to the
|
|
@@ -58,13 +72,15 @@ export function runRules(rules, ctx, settings = {}) {
|
|
|
58
72
|
const ignore = (settings.ignore ?? []).map(globToRegExp);
|
|
59
73
|
const isIgnored = (tool) => ignore.some((re) => re.test(tool));
|
|
60
74
|
const findings = [];
|
|
75
|
+
// The menu as an MCP Apps host shows it to the agent: app-only tools left out.
|
|
76
|
+
const shown = agentMenu(ctx.menu).shown;
|
|
61
77
|
for (const rule of rules) {
|
|
62
78
|
const configured = settings.rules?.[rule.id] ?? (RULE_ALIASES[rule.id] ? settings.rules?.[RULE_ALIASES[rule.id]] : undefined);
|
|
63
79
|
if (configured === 'off')
|
|
64
80
|
continue;
|
|
65
81
|
if (rule.since && (!ctx.protocolVersion || ctx.protocolVersion < rule.since))
|
|
66
82
|
continue;
|
|
67
|
-
for (const f of rule.run({ ...ctx, isIgnored })) {
|
|
83
|
+
for (const f of rule.run({ ...ctx, ...(rule.scope === 'agent' ? { menu: shown } : {}), isIgnored })) {
|
|
68
84
|
if (f.tool && isIgnored(f.tool))
|
|
69
85
|
continue;
|
|
70
86
|
findings.push({ rule: rule.id, ...f, severity: configured ?? f.severity ?? rule.severity });
|
package/dist/rules/naming.js
CHANGED
|
@@ -5,6 +5,7 @@ import { kept, names } from './rule.js';
|
|
|
5
5
|
const VAGUE_IDS = /^(id|ids|uuid|uuids|identifier|identifiers)$/i;
|
|
6
6
|
export const vagueId = {
|
|
7
7
|
id: 'naming/vague-id',
|
|
8
|
+
scope: 'agent',
|
|
8
9
|
severity: 'warn',
|
|
9
10
|
lesson: '04',
|
|
10
11
|
summary: 'ID parameters say which kind of thing they identify',
|
|
@@ -52,6 +53,7 @@ function betterName(tool, param, params, common) {
|
|
|
52
53
|
}
|
|
53
54
|
export const sharedWord = {
|
|
54
55
|
id: 'naming/shared-word',
|
|
56
|
+
scope: 'agent',
|
|
55
57
|
severity: 'info',
|
|
56
58
|
lesson: '04',
|
|
57
59
|
summary: 'The same noun used for different things across tools',
|
|
@@ -132,6 +134,7 @@ export const sharedWord = {
|
|
|
132
134
|
};
|
|
133
135
|
export const route = {
|
|
134
136
|
id: 'naming/route',
|
|
137
|
+
scope: 'agent',
|
|
135
138
|
severity: 'error',
|
|
136
139
|
lesson: '04',
|
|
137
140
|
summary: 'routes.yml expectations still hold',
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { MenuTool } from '../types.js';
|
|
2
|
+
import { type Rule } from './rule.js';
|
|
3
|
+
/**
|
|
4
|
+
* snapshot --offline-check: the menu from one more stdio process whose proxy variables
|
|
5
|
+
* point at a port nothing listens on. A server that builds its menu from what it
|
|
6
|
+
* fetches at start (inite-visibility: 3 tools offline, 10 online) serves another menu
|
|
7
|
+
* on a machine without the network (CI behind a firewall, an air-gapped install), so
|
|
8
|
+
* a baseline made on one doesn't match the other, and neither do prompt caches.
|
|
9
|
+
* One-sided: a server that ignores the proxy variables still reaches the network
|
|
10
|
+
* where the machine has direct access, and then the menus match; that's no pass.
|
|
11
|
+
*/
|
|
12
|
+
export interface OfflineMenu {
|
|
13
|
+
tools?: MenuTool[];
|
|
14
|
+
/** It didn't start, or didn't list, with the network cut off. */
|
|
15
|
+
error?: string;
|
|
16
|
+
/** Started through npx, uvx, pnpm dlx, bunx: the launcher may need the network itself. */
|
|
17
|
+
launcher?: boolean;
|
|
18
|
+
/** A container wrapper (docker run …): the proxy variables reach the docker CLI, not the server. */
|
|
19
|
+
wrapper?: boolean;
|
|
20
|
+
}
|
|
21
|
+
export declare const networkDependent: Rule;
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import { compareMenus } from '../compare.js';
|
|
2
|
+
import { names } from './rule.js';
|
|
3
|
+
export const networkDependent = {
|
|
4
|
+
id: 'menu/network-dependent',
|
|
5
|
+
severity: 'warn',
|
|
6
|
+
summary: 'The menu is the same with the network cut off',
|
|
7
|
+
run(ctx) {
|
|
8
|
+
const offline = ctx.offline;
|
|
9
|
+
if (!offline)
|
|
10
|
+
return [];
|
|
11
|
+
if (offline.wrapper) {
|
|
12
|
+
return [
|
|
13
|
+
{
|
|
14
|
+
rule: 'menu/network-dependent',
|
|
15
|
+
severity: 'info',
|
|
16
|
+
message: "Not checked offline: the server runs in a container (docker run …), and the proxy variables that cut the network reach the docker CLI, not the server.",
|
|
17
|
+
fix: 'To check it, run the container with --network none yourself and compare the menus (toolmenu diff).',
|
|
18
|
+
},
|
|
19
|
+
];
|
|
20
|
+
}
|
|
21
|
+
if (offline.error) {
|
|
22
|
+
return [
|
|
23
|
+
{
|
|
24
|
+
rule: 'menu/network-dependent',
|
|
25
|
+
severity: 'info',
|
|
26
|
+
message: `The server didn't start or list its tools with the network cut off: ${offline.error.replace(/^The /, 'the ')}. A machine without the network (CI behind a firewall, an air-gapped install) gets no menu from it.${offline.launcher ? ' It starts through a package runner, which may need the network itself to fetch the package: run the installed command to check the server alone.' : ''}`,
|
|
27
|
+
fix: 'If the server needs the network only for some tools, start without it and say so in those tools\' errors; if it needs it to start, say so in its README.',
|
|
28
|
+
confidence: 'unsure',
|
|
29
|
+
},
|
|
30
|
+
];
|
|
31
|
+
}
|
|
32
|
+
const mine = ctx.menu.tools;
|
|
33
|
+
const theirs = offline.tools ?? [];
|
|
34
|
+
const changes = compareMenus(mine, theirs);
|
|
35
|
+
if (!changes.length)
|
|
36
|
+
return [];
|
|
37
|
+
const have = new Set(mine.map((t) => t.name));
|
|
38
|
+
const got = new Set(theirs.map((t) => t.name));
|
|
39
|
+
const gone = mine.filter((t) => !got.has(t.name)).map((t) => t.name);
|
|
40
|
+
const added = theirs.filter((t) => !have.has(t.name)).map((t) => t.name);
|
|
41
|
+
// A move is order, not a definition: said as "in another order".
|
|
42
|
+
const changed = [...new Set(changes.filter((c) => c.kind !== 'moved').map((c) => c.tool).filter((n) => !!n && have.has(n) && got.has(n)))];
|
|
43
|
+
// A menu that already differs between two processes with the network (menu/process-variance):
|
|
44
|
+
// only tools missing or added offline are this rule's, not order or definitions.
|
|
45
|
+
const varies = (ctx.probes ?? []).some((p) => p.tools && compareMenus(mine, p.tools).length > 0);
|
|
46
|
+
if (varies && !gone.length && !added.length)
|
|
47
|
+
return [];
|
|
48
|
+
return [
|
|
49
|
+
{
|
|
50
|
+
rule: 'menu/network-dependent',
|
|
51
|
+
severity: 'warn',
|
|
52
|
+
message: `With the network cut off, the server serves a different menu: ${!gone.length && !added.length ? `the same ${mine.length} tools` : theirs.length === mine.length ? `${mine.length} tools, as many as with it` : `${theirs.length} ${theirs.length === 1 ? 'tool' : 'tools'}, not ${mine.length}`}${gone.length || added.length || changed.length ? ` (${[gone.length ? `${gone.length} missing` : '', added.length ? `${added.length} only offline` : '', changed.length ? `${changed.length} defined differently` : ''].filter(Boolean).join(', ')})` : ', in another order'}. On a machine without the network (CI behind a firewall, an air-gapped install) agents get that menu, a baseline made with the network doesn't match it, and neither do prompt caches.`,
|
|
53
|
+
detail: [
|
|
54
|
+
...(gone.length ? [`missing offline: ${names(gone, 10)}`] : []),
|
|
55
|
+
...(added.length ? [`only offline: ${names(added, 10)}`] : []),
|
|
56
|
+
...(changed.length ? [`defined differently: ${names(changed, 10)}`] : []),
|
|
57
|
+
...(varies ? ['The menu also differs between two processes with the network (menu/process-variance), so part of this may be that.'] : []),
|
|
58
|
+
],
|
|
59
|
+
fix: 'Serve the same tool list either way: list every tool at start, and have a tool that needs the network say so in its error when it can\'t reach it.',
|
|
60
|
+
},
|
|
61
|
+
];
|
|
62
|
+
},
|
|
63
|
+
};
|
package/dist/rules/rule.d.ts
CHANGED
|
@@ -32,12 +32,24 @@ export interface RuleContext {
|
|
|
32
32
|
lists?: import('./lists.js').ListsContext;
|
|
33
33
|
/** HTTP with credentials: what the server did with an invalid credential in their place. */
|
|
34
34
|
invalidCredential?: import('./auth.js').InvalidCredential;
|
|
35
|
+
/** snapshot --offline-check: the menu from a process with the network cut off. */
|
|
36
|
+
offline?: import('./network.js').OfflineMenu;
|
|
37
|
+
/** A later process or connection got 2026-07-28 while this one fell back to 2025 (spec/discover). */
|
|
38
|
+
laterModern?: boolean;
|
|
39
|
+
/** snapshot: the menu listed by a client that declares no elicitation support. */
|
|
40
|
+
plain?: import('./capabilities.js').PlainMenu;
|
|
35
41
|
/** --client: the client profile the menu is checked for (src/clients.ts). */
|
|
36
42
|
client?: string;
|
|
37
43
|
/** Where clients are assumed to cut tool descriptions (description/buried). */
|
|
38
44
|
descriptionLimit?: number | string;
|
|
39
45
|
/** Tools (names or globs) the client sends uncut, so description/buried skips them. */
|
|
40
46
|
fullDescriptions?: string[];
|
|
47
|
+
/** snapshot over HTTP: the Server Card at <url>/server-card, when the server answered with JSON there. */
|
|
48
|
+
serverCard?: import('../card.js').CardRead;
|
|
49
|
+
/** snapshot over HTTP: the URL connected to (no query), to find the card's remote for it. */
|
|
50
|
+
serverUrl?: string;
|
|
51
|
+
/** snapshot: what resources/read gave for each ui:// resource the tools name (MCP Apps). */
|
|
52
|
+
appResources?: import('../apps.js').AppResource[];
|
|
41
53
|
/**
|
|
42
54
|
* Set by runRules from the `ignore` setting. Rules that sum many tools up in
|
|
43
55
|
* one finding use it to leave ignored tools out of the summary; findings about
|
|
@@ -56,6 +68,12 @@ export interface Rule {
|
|
|
56
68
|
/** Spec version the rule applies from. Skipped for older servers. */
|
|
57
69
|
since?: string;
|
|
58
70
|
summary: string;
|
|
71
|
+
/**
|
|
72
|
+
* 'agent': the rule is about what the agent reads (names, descriptions, schemas), so
|
|
73
|
+
* it sees the menu without MCP Apps app-only tools (visibility without "model"),
|
|
74
|
+
* which an Apps host keeps out of the agent's list. Rules about the wire see them all.
|
|
75
|
+
*/
|
|
76
|
+
scope?: 'agent';
|
|
59
77
|
run(ctx: RuleContext): RuleFinding[];
|
|
60
78
|
}
|
|
61
79
|
/** 2048 → "2,048". */
|
package/dist/rules/search.js
CHANGED
package/dist/rules/spec.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type
|
|
1
|
+
import { type Rule } from './rule.js';
|
|
2
2
|
/** A validator for one result type ($defs name) of a protocol version, or null when this toolmenu has no schema for it. */
|
|
3
3
|
export declare function resultValidator(version: string, result?: string): import("ajv").ValidateFunction<unknown> | null;
|
|
4
4
|
export declare const schema: Rule;
|
|
@@ -13,3 +13,11 @@ export declare const deprecated: Rule;
|
|
|
13
13
|
*/
|
|
14
14
|
export declare const serverInfo: Rule;
|
|
15
15
|
export declare const cacheHints: Rule;
|
|
16
|
+
/**
|
|
17
|
+
* The extensions a server declares: each key an identifier in _meta key form with a
|
|
18
|
+
* vendor prefix (io.modelcontextprotocol/ui), each value a settings object ({} for none).
|
|
19
|
+
* A client looks an extension up by its exact identifier, so one spelled otherwise reads
|
|
20
|
+
* as not declared.
|
|
21
|
+
*/
|
|
22
|
+
export declare const extensionId: Rule;
|
|
23
|
+
export declare const taskRequired: Rule;
|
package/dist/rules/spec.js
CHANGED
|
@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url';
|
|
|
3
3
|
import { Ajv } from 'ajv';
|
|
4
4
|
import { Ajv2020 } from 'ajv/dist/2020.js';
|
|
5
5
|
import addFormatsImport from 'ajv-formats';
|
|
6
|
+
import { kept, names } from './rule.js';
|
|
6
7
|
// ajv-formats ships CommonJS; under NodeNext its default import is the module object.
|
|
7
8
|
const addFormats = (addFormatsImport.default ?? addFormatsImport);
|
|
8
9
|
const SCHEMA_DIR = fileURLToPath(new URL('../../schemas/', import.meta.url));
|
|
@@ -114,6 +115,16 @@ export const discover = {
|
|
|
114
115
|
run(ctx) {
|
|
115
116
|
if (ctx.era !== 'legacy')
|
|
116
117
|
return [];
|
|
118
|
+
// A later process got 2026-07-28: this one's server/discover probe went unanswered in
|
|
119
|
+
// time, and the SDK falls back to 2025 then (stdio). The server does speak 2026-07-28.
|
|
120
|
+
if (ctx.laterModern) {
|
|
121
|
+
return [
|
|
122
|
+
{
|
|
123
|
+
message: `This connection fell back to protocol ${ctx.protocolVersion}: its server/discover probe got no usable answer (on stdio the official SDK falls back to the 2025 handshake after a timeout too). A later process got 2026-07-28, so the server speaks it, but this run was checked as a 2025 server.`,
|
|
124
|
+
fix: 'Rerun with a longer --timeout (the server may start slowly, or this machine was busy), or --protocol modern to require 2026-07-28.',
|
|
125
|
+
},
|
|
126
|
+
];
|
|
127
|
+
}
|
|
117
128
|
return [
|
|
118
129
|
{
|
|
119
130
|
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.`,
|
|
@@ -151,12 +162,30 @@ export const serverInfo = {
|
|
|
151
162
|
run(ctx) {
|
|
152
163
|
if (!ctx.serverInfo)
|
|
153
164
|
return [];
|
|
154
|
-
const
|
|
155
|
-
|
|
165
|
+
const { name, version } = ctx.serverInfo;
|
|
166
|
+
// undefined: not sent; '': sent empty (a string, so it passes the schema).
|
|
167
|
+
const gaps = [
|
|
168
|
+
name === undefined ? 'no name' : name === '' ? 'an empty name' : '',
|
|
169
|
+
version === undefined ? 'no version' : version === '' ? 'an empty version' : '',
|
|
170
|
+
].filter(Boolean);
|
|
171
|
+
if (!gaps.length)
|
|
156
172
|
return [];
|
|
173
|
+
const who = !name && !version ? 'server or release' : !name ? 'server' : 'release';
|
|
174
|
+
// 2026-07-28 moved serverInfo to each result's _meta, where it is a SHOULD ("Servers
|
|
175
|
+
// SHOULD include this field on every response"); the 2025 handshake requires it.
|
|
176
|
+
const modern = ctx.era === 'modern';
|
|
177
|
+
const absent = name === undefined && version === undefined;
|
|
178
|
+
const named = name ? ` (${name})` : '';
|
|
179
|
+
const cant = `Clients, logs and this report can't tell which ${who} answered.`;
|
|
180
|
+
const message = modern
|
|
181
|
+
? absent
|
|
182
|
+
? `The server sends no serverInfo, which 2026-07-28 says servers SHOULD include on every response (io.modelcontextprotocol/serverInfo). ${cant}`
|
|
183
|
+
: `The server's serverInfo has ${gaps.join(' and ')}${named}. ${gaps.every((g) => g.startsWith('an empty')) ? 'Valid, since it is a string, but' : 'The schema requires both when serverInfo is sent, and'} ${cant[0].toLowerCase()}${cant.slice(1)}`
|
|
184
|
+
: `The server's handshake has ${gaps.join(' and ')}${named}, which ${absent ? "the 2025 handshake requires (initialize's serverInfo)" : 'the 2025 handshake requires to be filled'}. ${cant}`;
|
|
157
185
|
return [
|
|
158
186
|
{
|
|
159
|
-
|
|
187
|
+
...(modern ? { severity: 'info' } : {}),
|
|
188
|
+
message,
|
|
160
189
|
fix: 'Set serverInfo { name, version } where the server is created, the version from its package.',
|
|
161
190
|
},
|
|
162
191
|
];
|
|
@@ -186,3 +215,88 @@ export const cacheHints = {
|
|
|
186
215
|
return findings;
|
|
187
216
|
},
|
|
188
217
|
};
|
|
218
|
+
// _meta key rules, which extension identifiers follow "with a mandatory prefix"
|
|
219
|
+
// (2026-07-28 ServerCapabilities.extensions; MetaObject): labels that start with a
|
|
220
|
+
// letter and end with a letter or digit, dots between, then a slash and a name that
|
|
221
|
+
// starts and ends alphanumeric.
|
|
222
|
+
const LABEL = '[A-Za-z](?:[A-Za-z0-9-]*[A-Za-z0-9])?';
|
|
223
|
+
const EXTENSION_ID = new RegExp(`^${LABEL}(?:\\.${LABEL})*/[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$`);
|
|
224
|
+
/**
|
|
225
|
+
* The extensions a server declares: each key an identifier in _meta key form with a
|
|
226
|
+
* vendor prefix (io.modelcontextprotocol/ui), each value a settings object ({} for none).
|
|
227
|
+
* A client looks an extension up by its exact identifier, so one spelled otherwise reads
|
|
228
|
+
* as not declared.
|
|
229
|
+
*/
|
|
230
|
+
export const extensionId = {
|
|
231
|
+
id: 'spec/extension-id',
|
|
232
|
+
severity: 'warn',
|
|
233
|
+
summary: 'Declared extensions are identified as the spec says: vendor-prefix/name, with a settings object',
|
|
234
|
+
run(ctx) {
|
|
235
|
+
const e = ctx.capabilities.extensions;
|
|
236
|
+
if (e === undefined)
|
|
237
|
+
return [];
|
|
238
|
+
if (typeof e !== 'object' || e === null || Array.isArray(e)) {
|
|
239
|
+
return [
|
|
240
|
+
{
|
|
241
|
+
message: `capabilities.extensions is ${Array.isArray(e) ? 'a list' : JSON.stringify(e)}, not an object of extension identifiers, so clients find none of the extensions it means to declare.`,
|
|
242
|
+
fix: 'Declare extensions as an object: { "io.modelcontextprotocol/ui": {} }, one key per extension, {} when it has no settings.',
|
|
243
|
+
},
|
|
244
|
+
];
|
|
245
|
+
}
|
|
246
|
+
// One entry per extension: its identifier, its settings, or both.
|
|
247
|
+
const named = [];
|
|
248
|
+
const unset = [];
|
|
249
|
+
for (const [id, settings] of Object.entries(e)) {
|
|
250
|
+
if (!EXTENSION_ID.test(id))
|
|
251
|
+
named.push(`"${id}": ${id.includes('/') ? 'not in vendor-prefix/name form (labels start with a letter; the name starts and ends alphanumeric)' : 'no vendor prefix (the spec makes one mandatory: io.modelcontextprotocol/ui, com.example/feature)'}`);
|
|
252
|
+
else if (typeof settings !== 'object' || settings === null || Array.isArray(settings))
|
|
253
|
+
unset.push(`"${id}": its settings are ${JSON.stringify(settings)}, not an object ({} for none)`);
|
|
254
|
+
}
|
|
255
|
+
const out = [];
|
|
256
|
+
if (named.length) {
|
|
257
|
+
const one = named.length === 1;
|
|
258
|
+
out.push({
|
|
259
|
+
message: `${one ? 'An extension the server declares is' : `${named.length} extensions the server declares are`} not identified as the spec says, so a client that looks ${one ? 'it' : 'them'} up by identifier finds ${one ? 'it' : 'them'} not declared: ${named[0]}${one ? '.' : '…'}`,
|
|
260
|
+
...(one ? {} : { detail: named }),
|
|
261
|
+
fix: 'Use the identifier the extension\'s spec gives (io.modelcontextprotocol/ui for MCP Apps, io.modelcontextprotocol/tasks for Tasks), or your reverse-DNS prefix for your own, with {} or a settings object as the value.',
|
|
262
|
+
});
|
|
263
|
+
}
|
|
264
|
+
if (unset.length) {
|
|
265
|
+
const one = unset.length === 1;
|
|
266
|
+
out.push({
|
|
267
|
+
message: `${one ? 'An extension the server declares has' : `${unset.length} extensions the server declares have`} settings that aren't an object, which the 2026-07-28 schema requires (a settings object per extension, {} for none), so a client that reads ${one ? 'its' : 'their'} settings may reject or ignore ${one ? 'it' : 'them'}: ${unset[0]}${one ? '.' : '…'}`,
|
|
268
|
+
...(one ? {} : { detail: unset }),
|
|
269
|
+
fix: 'Give each extension an object as its value: {} when it has no settings.',
|
|
270
|
+
});
|
|
271
|
+
}
|
|
272
|
+
return out;
|
|
273
|
+
},
|
|
274
|
+
};
|
|
275
|
+
export const taskRequired = {
|
|
276
|
+
id: 'spec/task-required',
|
|
277
|
+
severity: 'info',
|
|
278
|
+
summary: 'Tools that only run as tasks (execution.taskSupport: "required")',
|
|
279
|
+
run(ctx) {
|
|
280
|
+
const required = kept(ctx.menu.tools, ctx).filter((t) => {
|
|
281
|
+
const e = t.execution;
|
|
282
|
+
return typeof e === 'object' && e !== null && e.taskSupport === 'required';
|
|
283
|
+
});
|
|
284
|
+
if (!required.length)
|
|
285
|
+
return [];
|
|
286
|
+
const list = required.map((t) => t.name);
|
|
287
|
+
const one = list.length === 1;
|
|
288
|
+
const modern = ctx.era === 'modern';
|
|
289
|
+
return [
|
|
290
|
+
{
|
|
291
|
+
...(one ? { tool: list[0] } : {}),
|
|
292
|
+
message: modern
|
|
293
|
+
? `${one ? `${list[0]} is` : `${names(list, 6)} are`} marked execution.taskSupport: "required", a 2025-11-25 field. 2026-07-28 moved Tasks to the io.modelcontextprotocol/tasks extension, where the server decides per request whether to answer with a task, so clients on 2026-07-28 ignore it.`
|
|
294
|
+
: `${one ? `${list[0]} runs` : `${names(list, 6)} run`} only as a task (execution.taskSupport: "required"), so a client without Tasks support can't call ${one ? 'it' : 'them'}: the call is refused, not run. Most clients don't support Tasks yet.`,
|
|
295
|
+
...(one ? {} : { detail: [list.join(', ')] }),
|
|
296
|
+
fix: modern
|
|
297
|
+
? 'Drop execution from the tool definitions; answer with a task only when the request declares the io.modelcontextprotocol/tasks extension.'
|
|
298
|
+
: `If ${one ? 'it' : 'they'} can also answer in one go, mark ${one ? 'it' : 'them'} "optional", so clients without Tasks can call ${one ? 'it' : 'them'}; otherwise say in the README which clients can.`,
|
|
299
|
+
},
|
|
300
|
+
];
|
|
301
|
+
},
|
|
302
|
+
};
|
package/dist/rules/write.d.ts
CHANGED
|
@@ -1,10 +1,4 @@
|
|
|
1
1
|
import { type Rule } from './rule.js';
|
|
2
2
|
export declare const unannotated: Rule;
|
|
3
|
-
/**
|
|
4
|
-
* readOnlyHint: true on a tool whose name says it writes (create_, delete_, send_…).
|
|
5
|
-
* The spec's readOnlyHint means "the tool does not modify its environment", and
|
|
6
|
-
* clients and agents act on it: run it without asking, retry it, call it to explore.
|
|
7
|
-
* Seen on a hosted server: create_my_ideal_account, marked read-only.
|
|
8
|
-
*/
|
|
9
3
|
export declare const readOnlyMismatch: Rule;
|
|
10
4
|
export declare const noDryRun: Rule;
|
package/dist/rules/write.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { WRITE_VERBS,
|
|
1
|
+
import { WRITE_VERBS, prefixWords, leadingVerb, nouns, words } from '../words.js';
|
|
2
2
|
import { count, kept, names } from './rule.js';
|
|
3
3
|
const DRY_RUN_PARAMS = /^(dry[_-]?run|preview|validate[_-]?only|simulate|plan|what[_-]?if)$/i;
|
|
4
4
|
const PREVIEW_WORDS = new Set(['preview', 'validate', 'plan', 'simulate', 'dry']);
|
|
@@ -16,13 +16,15 @@ function hasAnnotations(tool) {
|
|
|
16
16
|
return !!tool.annotations && Object.keys(tool.annotations).length > 0;
|
|
17
17
|
}
|
|
18
18
|
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.';
|
|
19
|
+
// Not agent-scope: an MCP Apps app-only tool is still called through the host, which
|
|
20
|
+
// decides from its annotations whether to confirm (write/read-only-mismatch likewise).
|
|
19
21
|
export const unannotated = {
|
|
20
22
|
id: 'write/unannotated',
|
|
21
23
|
severity: 'warn',
|
|
22
24
|
lesson: '02',
|
|
23
25
|
summary: 'Tools that look like writes carry annotations',
|
|
24
26
|
run(ctx) {
|
|
25
|
-
const common =
|
|
27
|
+
const common = prefixWords(ctx.menu.tools.map((t) => t.name));
|
|
26
28
|
const bare = kept(ctx.menu.tools, ctx).filter((t) => isWriteByName(t, common) && !hasAnnotations(t));
|
|
27
29
|
if (bare.length === 0)
|
|
28
30
|
return [];
|
|
@@ -60,16 +62,19 @@ export const unannotated = {
|
|
|
60
62
|
* readOnlyHint: true on a tool whose name says it writes (create_, delete_, send_…).
|
|
61
63
|
* The spec's readOnlyHint means "the tool does not modify its environment", and
|
|
62
64
|
* clients and agents act on it: run it without asking, retry it, call it to explore.
|
|
63
|
-
* Seen on a hosted server: create_my_ideal_account, marked read-only.
|
|
65
|
+
* Seen on a hosted server: create_my_ideal_account, marked read-only. Not when the
|
|
66
|
+
* description says it only reads: Vercel's create_observability_query "Run a read-only
|
|
67
|
+
* … query … without changing project configuration" names the query it makes.
|
|
64
68
|
*/
|
|
69
|
+
const SAYS_READ_ONLY = /\bread[- ]only\b|\bwithout (?:changing|modifying|altering|writing)\b|\b(?:does not|doesn't|never) (?:change|modify|alter|write)\b/i;
|
|
65
70
|
export const readOnlyMismatch = {
|
|
66
71
|
id: 'write/read-only-mismatch',
|
|
67
72
|
severity: 'warn',
|
|
68
73
|
summary: 'Tools marked read-only whose names say they write',
|
|
69
74
|
run(ctx) {
|
|
70
|
-
const common =
|
|
75
|
+
const common = prefixWords(ctx.menu.tools.map((t) => t.name));
|
|
71
76
|
const lead = (t) => leadingVerb(t.name, common);
|
|
72
|
-
const odd = kept(ctx.menu.tools, ctx).filter((t) => t.annotations?.readOnlyHint === true && WRITE_VERBS.has(lead(t) ?? ''));
|
|
77
|
+
const odd = kept(ctx.menu.tools, ctx).filter((t) => t.annotations?.readOnlyHint === true && WRITE_VERBS.has(lead(t) ?? '') && !SAYS_READ_ONLY.test(t.description ?? ''));
|
|
73
78
|
if (!odd.length)
|
|
74
79
|
return [];
|
|
75
80
|
const one = odd.length === 1;
|
|
@@ -86,6 +91,7 @@ export const readOnlyMismatch = {
|
|
|
86
91
|
};
|
|
87
92
|
export const noDryRun = {
|
|
88
93
|
id: 'write/no-dry-run',
|
|
94
|
+
scope: 'agent',
|
|
89
95
|
severity: 'info',
|
|
90
96
|
lesson: '02',
|
|
91
97
|
summary: 'Destructive tools offer a way to look before leaping',
|