toolmenu 0.21.0 → 0.24.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 (62) hide show
  1. package/README.md +96 -37
  2. package/dist/apps.d.ts +56 -0
  3. package/dist/apps.js +99 -0
  4. package/dist/auto.js +2 -2
  5. package/dist/card.d.ts +18 -0
  6. package/dist/card.js +39 -0
  7. package/dist/cli.d.ts +1 -1
  8. package/dist/cli.js +70 -11
  9. package/dist/colour.d.ts +8 -0
  10. package/dist/colour.js +70 -0
  11. package/dist/config.d.ts +2 -0
  12. package/dist/config.js +2 -0
  13. package/dist/connect.d.ts +15 -0
  14. package/dist/connect.js +54 -7
  15. package/dist/diff.js +113 -6
  16. package/dist/explain.d.ts +16 -0
  17. package/dist/explain.js +14 -0
  18. package/dist/failures.d.ts +18 -5
  19. package/dist/failures.js +27 -12
  20. package/dist/help.d.ts +1 -1
  21. package/dist/help.js +18 -3
  22. package/dist/mcp-env.d.ts +5 -0
  23. package/dist/mcp-env.js +5 -0
  24. package/dist/mcp.d.ts +65 -0
  25. package/dist/mcp.js +293 -0
  26. package/dist/mrtr.d.ts +9 -1
  27. package/dist/mrtr.js +17 -0
  28. package/dist/options.d.ts +3 -0
  29. package/dist/options.js +1 -0
  30. package/dist/probe.d.ts +11 -1
  31. package/dist/probe.js +18 -3
  32. package/dist/report.js +12 -5
  33. package/dist/rule-docs.json +94 -4
  34. package/dist/rules/apps.d.ts +11 -0
  35. package/dist/rules/apps.js +156 -0
  36. package/dist/rules/capabilities.d.ts +21 -0
  37. package/dist/rules/capabilities.js +103 -0
  38. package/dist/rules/card.d.ts +7 -0
  39. package/dist/rules/card.js +65 -0
  40. package/dist/rules/clients.js +1 -0
  41. package/dist/rules/description.js +3 -0
  42. package/dist/rules/headers.d.ts +0 -2
  43. package/dist/rules/headers.js +7 -12
  44. package/dist/rules/ids.js +35 -1
  45. package/dist/rules/index.js +18 -2
  46. package/dist/rules/naming.js +3 -0
  47. package/dist/rules/network.d.ts +21 -0
  48. package/dist/rules/network.js +63 -0
  49. package/dist/rules/rule.d.ts +18 -0
  50. package/dist/rules/search.js +1 -0
  51. package/dist/rules/spec.d.ts +9 -1
  52. package/dist/rules/spec.js +117 -3
  53. package/dist/rules/write.d.ts +0 -6
  54. package/dist/rules/write.js +11 -5
  55. package/dist/session.js +60 -11
  56. package/dist/snapshot.d.ts +5 -0
  57. package/dist/snapshot.js +89 -5
  58. package/dist/types.d.ts +5 -0
  59. package/dist/words.d.ts +8 -0
  60. package/dist/words.js +30 -2
  61. package/package.json +8 -7
  62. package/schemas/server-card.json +260 -0
@@ -9,8 +9,8 @@ import { count, names } from './rule.js';
9
9
  *
10
10
  * The checks follow the spec and the SDK client's own scan
11
11
  * (scanXMcpHeaderDeclarations in @modelcontextprotocol/client), which decides
12
- * what SDK-based clients actually drop. Where the two differ (`number`: the spec
13
- * forbids it, the SDK accepts it), the finding says so.
12
+ * what SDK-based clients actually drop. The two agree: since SDK 2.4 the client
13
+ * drops a tool whose header is on a number parameter too, as the spec says.
14
14
  */
15
15
  const KEY = 'x-mcp-header';
16
16
  // RFC 9110 §5.1 token: 1*tchar. No spaces, control characters or delimiters.
@@ -34,7 +34,7 @@ export function headerFaults(tool) {
34
34
  const where = path.length ? path.join('.') : 'the schema root';
35
35
  if (KEY in schema) {
36
36
  const raw = schema[KEY];
37
- const fault = (problem, dropped = true) => faults.push({ path: where, header: raw, problem, dropped });
37
+ const fault = (problem) => faults.push({ path: where, header: raw, problem });
38
38
  if (!reachable || path.length === 0) {
39
39
  fault(path.length === 0
40
40
  ? 'it sits on the schema root, not on a parameter'
@@ -57,7 +57,7 @@ export function headerFaults(tool) {
57
57
  else {
58
58
  // number takes part in the uniqueness check too: the SDK client registers it.
59
59
  if (type === 'number')
60
- fault('the parameter is a number; the spec allows only string, integer or boolean (the official SDK client accepts number for now, other clients may not)', false);
60
+ fault('the parameter is a number; it must be string, integer or boolean (make it an integer or a string: a header carries text anyway)');
61
61
  const prior = seen.get(raw.toLowerCase());
62
62
  if (prior !== undefined)
63
63
  fault(`"${raw}" is already used by ${prior}; header names must differ ignoring case`);
@@ -95,20 +95,15 @@ export const xMcpHeader = {
95
95
  const faults = headerFaults(tool);
96
96
  if (!faults.length)
97
97
  continue;
98
- const dropped = faults.some((f) => f.dropped);
99
98
  const where = faults.map((f) => f.path);
100
99
  findings.push({
101
100
  tool: tool.name,
102
101
  // Over HTTP the tool is gone for every compliant client. On stdio clients may
103
102
  // ignore the annotation, but the same server is often deployed over HTTP too.
104
- severity: dropped ? (http ? 'error' : 'warn') : 'warn',
105
- message: dropped
106
- ? `${tool.name} has ${faults.length === 1 ? 'an x-mcp-header annotation' : `${count(faults.length, 'x-mcp-header annotation')}`} the spec doesn't allow (on ${names(where, 4)}), and Streamable HTTP clients must then leave the whole tool out of their menu. The official SDK client does, with only a console warning, so the agent never sees ${tool.name} and nothing tells the server.${http ? ' toolmenu reads the list off the wire, which is why it is in this menu.' : ' Over stdio clients may ignore the annotation, so it shows here; served over HTTP, it would be gone.'}`
107
- : `${tool.name} mirrors a number parameter into a header (${names(where, 4)}). The spec allows only string, integer or boolean there, so a strict Streamable HTTP client must leave the tool out of its menu; the official SDK client keeps it for now (its conformance tests expect number to work, a gap tracked upstream).`,
103
+ severity: http ? 'error' : 'warn',
104
+ message: `${tool.name} has ${faults.length === 1 ? 'an x-mcp-header annotation' : `${count(faults.length, 'x-mcp-header annotation')}`} the spec doesn't allow (on ${names(where, 4)}), and Streamable HTTP clients must then leave the whole tool out of their menu. The official SDK client does, with only a console warning, so the agent never sees ${tool.name} and nothing tells the server.${http ? ' toolmenu reads the list off the wire, which is why it is in this menu.' : ' Over stdio clients may ignore the annotation, so it shows here; served over HTTP, it would be gone.'}`,
108
105
  detail: faults.map((f) => `${f.path}${typeof f.header === 'string' && f.header ? ` (x-mcp-header: "${f.header}")` : ''}: ${f.problem}`),
109
- fix: dropped
110
- ? `Fix each annotation listed: on a string, integer or boolean parameter reached through "properties" alone, with a header name of letters, digits and - _ . only, different from the tool's other headers ignoring case. Then list the tools over HTTP with an SDK client and check ${tool.name} is there.`
111
- : 'Make the parameter a string or an integer (a header carries text anyway), or stop mirroring it into a header.',
106
+ fix: `Fix each annotation listed: on a string, integer or boolean parameter reached through "properties" alone, with a header name of letters, digits and - _ . only, different from the tool's other headers ignoring case. Then list the tools over HTTP with an SDK client and check ${tool.name} is there.`,
112
107
  });
113
108
  }
114
109
  return findings;
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, ctx.menu.tools, common))
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))
@@ -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 });
@@ -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
+ };
@@ -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". */
@@ -16,6 +16,7 @@ const MIN_TOOLS = 10;
16
16
  const MIN_TOKENS = 10_000;
17
17
  export const findable = {
18
18
  id: 'search/findable',
19
+ scope: 'agent',
19
20
  severity: 'info',
20
21
  summary: 'Each tool comes up when searched for by its own name, for clients that defer tools',
21
22
  run(ctx) {
@@ -1,4 +1,4 @@
1
- import type { Rule } from './rule.js';
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;
@@ -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 missing = [!ctx.serverInfo.name ? 'name' : '', !ctx.serverInfo.version ? 'version' : ''].filter(Boolean);
155
- if (!missing.length)
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
- 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})` : ''}.`,
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
+ };
@@ -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;
@@ -1,4 +1,4 @@
1
- import { WRITE_VERBS, commonWords, leadingVerb, nouns, words } from '../words.js';
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 = commonWords(ctx.menu.tools.map((t) => t.name));
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 = commonWords(ctx.menu.tools.map((t) => t.name));
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',