toolmenu 0.20.1 → 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.
Files changed (68) hide show
  1. package/README.md +119 -41
  2. package/dist/apps.d.ts +56 -0
  3. package/dist/apps.js +99 -0
  4. package/dist/auth.d.ts +14 -0
  5. package/dist/auth.js +75 -2
  6. package/dist/auto.d.ts +6 -0
  7. package/dist/auto.js +70 -7
  8. package/dist/card.d.ts +18 -0
  9. package/dist/card.js +39 -0
  10. package/dist/cli.js +108 -24
  11. package/dist/colour.d.ts +8 -0
  12. package/dist/colour.js +70 -0
  13. package/dist/config.d.ts +2 -0
  14. package/dist/config.js +2 -0
  15. package/dist/connect.d.ts +14 -0
  16. package/dist/connect.js +45 -7
  17. package/dist/diff.js +112 -13
  18. package/dist/explain.d.ts +1 -0
  19. package/dist/explain.js +11 -0
  20. package/dist/failures.d.ts +24 -0
  21. package/dist/failures.js +58 -1
  22. package/dist/help.d.ts +1 -1
  23. package/dist/help.js +36 -4
  24. package/dist/mrtr.d.ts +9 -1
  25. package/dist/mrtr.js +17 -0
  26. package/dist/options.d.ts +15 -0
  27. package/dist/options.js +5 -0
  28. package/dist/probe.d.ts +11 -1
  29. package/dist/probe.js +18 -3
  30. package/dist/report.d.ts +3 -0
  31. package/dist/report.js +15 -8
  32. package/dist/rule-docs.d.ts +26 -0
  33. package/dist/rule-docs.js +88 -0
  34. package/dist/rule-docs.json +597 -0
  35. package/dist/rules/apps.d.ts +11 -0
  36. package/dist/rules/apps.js +156 -0
  37. package/dist/rules/auth.d.ts +18 -0
  38. package/dist/rules/auth.js +29 -0
  39. package/dist/rules/capabilities.d.ts +21 -0
  40. package/dist/rules/capabilities.js +103 -0
  41. package/dist/rules/card.d.ts +7 -0
  42. package/dist/rules/card.js +65 -0
  43. package/dist/rules/clients.js +1 -0
  44. package/dist/rules/description.js +3 -0
  45. package/dist/rules/handles.d.ts +13 -0
  46. package/dist/rules/handles.js +78 -0
  47. package/dist/rules/ids.js +35 -1
  48. package/dist/rules/index.js +20 -2
  49. package/dist/rules/naming.js +3 -0
  50. package/dist/rules/network.d.ts +21 -0
  51. package/dist/rules/network.js +63 -0
  52. package/dist/rules/rule.d.ts +20 -0
  53. package/dist/rules/search.js +1 -0
  54. package/dist/rules/spec.d.ts +9 -1
  55. package/dist/rules/spec.js +117 -3
  56. package/dist/rules/write.d.ts +0 -6
  57. package/dist/rules/write.js +11 -5
  58. package/dist/scan.d.ts +47 -0
  59. package/dist/scan.js +334 -0
  60. package/dist/session.d.ts +2 -0
  61. package/dist/session.js +149 -9
  62. package/dist/snapshot.d.ts +15 -0
  63. package/dist/snapshot.js +130 -5
  64. package/dist/types.d.ts +5 -0
  65. package/dist/words.d.ts +10 -0
  66. package/dist/words.js +44 -2
  67. package/package.json +2 -2
  68. package/schemas/server-card.json +260 -0
@@ -3,16 +3,22 @@ import { buried, cut, lateInstruction } from './description.js';
3
3
  import { connectionVariance, hostSpecific, nondeterministic, processVariance } from './determinism.js';
4
4
  import { authoredIds } from './ids.js';
5
5
  import { clientName } from './clients.js';
6
+ import { invalidCredential } from './auth.js';
7
+ import { networkDependent } from './network.js';
8
+ import { capabilityDependent } from './capabilities.js';
6
9
  import { listSchema, listVariance } from './lists.js';
7
10
  import { handleLifetime } from './handles.js';
8
11
  import { authVariance, cacheScopePublic } from './identities.js';
9
12
  import { route, sharedWord, vagueId } from './naming.js';
10
- 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';
11
14
  import { noDryRun, readOnlyMismatch, unannotated } from './write.js';
12
15
  import { gated } from './gated.js';
13
16
  import { xMcpHeader } from './headers.js';
14
17
  import { schemaRef } from './refs.js';
15
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';
16
22
  export const MENU_RULES = [
17
23
  nondeterministic,
18
24
  duplicateName,
@@ -41,10 +47,20 @@ export const MENU_RULES = [
41
47
  deprecated,
42
48
  cacheHints,
43
49
  authVariance,
50
+ invalidCredential,
51
+ networkDependent,
52
+ capabilityDependent,
44
53
  listVariance,
45
54
  listSchema,
46
55
  cacheScopePublic,
47
56
  serverInfo,
57
+ extensionId,
58
+ taskRequired,
59
+ serverCard,
60
+ appsResource,
61
+ appsLegacyKey,
62
+ appsVisibility,
63
+ appsAppOnlyListed,
48
64
  ];
49
65
  /**
50
66
  * Rules split out of an older one. A setting for the old id still applies to the
@@ -56,13 +72,15 @@ export function runRules(rules, ctx, settings = {}) {
56
72
  const ignore = (settings.ignore ?? []).map(globToRegExp);
57
73
  const isIgnored = (tool) => ignore.some((re) => re.test(tool));
58
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;
59
77
  for (const rule of rules) {
60
78
  const configured = settings.rules?.[rule.id] ?? (RULE_ALIASES[rule.id] ? settings.rules?.[RULE_ALIASES[rule.id]] : undefined);
61
79
  if (configured === 'off')
62
80
  continue;
63
81
  if (rule.since && (!ctx.protocolVersion || ctx.protocolVersion < rule.since))
64
82
  continue;
65
- for (const f of rule.run({ ...ctx, isIgnored })) {
83
+ for (const f of rule.run({ ...ctx, ...(rule.scope === 'agent' ? { menu: shown } : {}), isIgnored })) {
66
84
  if (f.tool && isIgnored(f.tool))
67
85
  continue;
68
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
+ };
@@ -30,12 +30,26 @@ export interface RuleContext {
30
30
  identities?: import('./identities.js').IdentityMenu[];
31
31
  /** snapshot --lists: the prompts and resources lists read (lists/* rules). */
32
32
  lists?: import('./lists.js').ListsContext;
33
+ /** HTTP with credentials: what the server did with an invalid credential in their place. */
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;
33
41
  /** --client: the client profile the menu is checked for (src/clients.ts). */
34
42
  client?: string;
35
43
  /** Where clients are assumed to cut tool descriptions (description/buried). */
36
44
  descriptionLimit?: number | string;
37
45
  /** Tools (names or globs) the client sends uncut, so description/buried skips them. */
38
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[];
39
53
  /**
40
54
  * Set by runRules from the `ignore` setting. Rules that sum many tools up in
41
55
  * one finding use it to leave ignored tools out of the summary; findings about
@@ -54,6 +68,12 @@ export interface Rule {
54
68
  /** Spec version the rule applies from. Skipped for older servers. */
55
69
  since?: string;
56
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';
57
77
  run(ctx: RuleContext): RuleFinding[];
58
78
  }
59
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',
package/dist/scan.d.ts ADDED
@@ -0,0 +1,47 @@
1
+ import type { Target } from './connect.js';
2
+ import { type Format } from './report.js';
3
+ import { type SnapshotOptions } from './snapshot.js';
4
+ import { type Finding, type Menu, type Severity } from './types.js';
5
+ export interface ScanEntry {
6
+ name: string;
7
+ /** Undefined when the entry can't be run: `problem` says why. */
8
+ target?: Target;
9
+ /** Why it can't be run: not checked, so the scan isn't a pass. */
10
+ problem?: string;
11
+ /** Turned off in the config: listed, not checked, and not a failure. */
12
+ disabled?: true;
13
+ /** The target as the config writes it, ${VAR} unfilled: what's printed, so a key passed in args stays out. */
14
+ shown?: Target;
15
+ }
16
+ export declare class ListError extends Error {
17
+ }
18
+ /** Words of a command line: whitespace-separated, with '…' and "…" kept together. */
19
+ export declare function splitCommand(line: string): string[];
20
+ /** The servers in a list file, unique names (a repeat gets #2, #3). */
21
+ export declare function parseList(text: string, file: string, env?: NodeJS.ProcessEnv): ScanEntry[];
22
+ export declare function loadList(file: string): Promise<ScanEntry[]>;
23
+ export interface ScanRow {
24
+ name: string;
25
+ /** Where the server is, printable: a URL without its query, or the command line. Never headers or env values. */
26
+ where: string;
27
+ menu?: Menu;
28
+ findings: Finding[];
29
+ /** Why the server wasn't checked: it couldn't be started or read, or its entry can't be run. */
30
+ failed?: string;
31
+ /** Turned off in the config. */
32
+ disabled?: true;
33
+ /** An HTTP server that answered 401 or 403. */
34
+ wantsCredentials?: true;
35
+ }
36
+ /** Printable location. A URL's query and credentials can hold keys, so they're left out. */
37
+ export declare function where(target: Target | undefined): string;
38
+ export interface ScanOptions extends SnapshotOptions {
39
+ /** Servers checked at a time (default 4). */
40
+ concurrency?: number;
41
+ /** Called as each server finishes, for progress on stderr. */
42
+ onDone?: (row: ScanRow, done: number, total: number) => void;
43
+ }
44
+ export declare function scan(entries: ScanEntry[], options?: ScanOptions): Promise<ScanRow[]>;
45
+ /** 0 every server read and nothing at --fail-on; 1 findings at --fail-on; 2 a server wasn't read. */
46
+ export declare function scanExit(rows: ScanRow[], failOn: Severity): number;
47
+ export declare function formatScan(rows: ScanRow[], format: Format, file: string): string;