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
@@ -0,0 +1,597 @@
1
+ {
2
+ "apps/app-only-listed": {
3
+ "command": "snapshot",
4
+ "severity": "warn",
5
+ "text": "MCP Apps (ext-apps). A tool marked for the app only (`_meta.ui.visibility: [\"app\"]`) is in the listing toolmenu makes as a client that declares no extensions too. Such a client doesn't read `_meta.ui`, so its agent is offered a tool meant for an app's UI; ext-apps: \"Servers SHOULD check client capabilities before registering UI-enabled tools\". Not with `--processes 1`"
6
+ },
7
+ "apps/legacy-key": {
8
+ "command": "snapshot",
9
+ "severity": "info",
10
+ "text": "MCP Apps. A tool names its UI only with the flat `_meta[\"ui/resourceUri\"]`, which ext-apps deprecates (\"will be removed before GA\"); a host that reads only `_meta.ui.resourceUri` shows it without a UI"
11
+ },
12
+ "apps/resource": {
13
+ "command": "snapshot",
14
+ "severity": "warn",
15
+ "text": "MCP Apps. Each `ui://` resource a tool names in `_meta.ui.resourceUri` is read with `resources/read` (a read, not a tool call), as a host does before rendering it: the URI must start with `ui://`, the resource must exist, its content's `mimeType` must be `text/html;profile=mcp-app`, with the HTML as text or blob, and `_meta.ui.resourceUri` and the old key, when both are set, must agree. Otherwise an Apps host shows no UI and the agent gets only the text result"
16
+ },
17
+ "apps/visibility": {
18
+ "command": "snapshot",
19
+ "severity": "warn",
20
+ "text": "MCP Apps. `_meta.ui.visibility` must be a list of `\"model\"` and `\"app\"`. One that names neither leaves the tool callable by no one. Tools whose visibility leaves out `\"model\"` are kept out of the rules about what the agent reads (names, descriptions, IDs, annotations, search) and out of the token breakdown, as an Apps host keeps them out of the agent's list"
21
+ },
22
+ "auth/invalid-accepted": {
23
+ "command": "snapshot",
24
+ "severity": "warn",
25
+ "text": "HTTP with credentials, `--processes` 2 or more. toolmenu lists the menu once more with an invalid credential in the same scheme (Bearer, Basic, the API-key header, or the stored login). A server that answers it with a menu, not 401 or 403, gives a client whose token expired or was revoked no reason to log in again: the agent just sees fewer tools (Atlassian Rovo served 4 tools to any `Authorization` header)"
26
+ },
27
+ "catalog/failed": {
28
+ "command": "snapshot",
29
+ "severity": "info",
30
+ "text": "`--catalog`: searches or router listings that failed, grouped by cause (rate limit, authentication, unreadable output). Their operations aren't in the catalog, so `diff` can't see them"
31
+ },
32
+ "catalog/read": {
33
+ "command": "snapshot",
34
+ "severity": "info",
35
+ "text": "`--catalog`: what was read behind a search tool or command router, with how many searches or which listing call. A search returns its top matches, so the catalog is what the searches reached, not a guaranteed full list"
36
+ },
37
+ "catalog/skipped": {
38
+ "command": "snapshot",
39
+ "severity": "info",
40
+ "text": "`--catalog`: tools that look like command routers but weren't called, because no listing mode needs no command. toolmenu never sends a command to list one"
41
+ },
42
+ "description/buried": {
43
+ "command": "snapshot",
44
+ "severity": "warn",
45
+ "text": "A sentence that reads as an instruction to the agent sits past the point where the client cuts descriptions, so the model never sees it. Read from the words, so marked unsure"
46
+ },
47
+ "description/cut": {
48
+ "command": "snapshot",
49
+ "severity": "info",
50
+ "text": "Descriptions longer than the client sends, with where the cut falls. Nothing past it reads as an instruction, so it's a check, not a bug"
51
+ },
52
+ "description/late-instruction": {
53
+ "command": "snapshot",
54
+ "severity": "info",
55
+ "text": "Only with the default cut: an instruction past 280 characters, where one real client cut, but inside the default cut. Split out of `description/cut` in 0.13; a setting for `description/cut` still applies to it unless it's set itself (`RULE_ALIASES`)"
56
+ },
57
+ "ids/authored": {
58
+ "command": "snapshot",
59
+ "severity": "info",
60
+ "text": "An input that looks like an opaque ID where no tool appears to return that kind of ID, so the agent would have to invent it. Heuristic, and worded as one. Stronger when `outputSchema` is present"
61
+ },
62
+ "ids/handle-lifetime": {
63
+ "command": "snapshot",
64
+ "severity": "info",
65
+ "text": "2026-07-28. A tool that creates a handle (`create`/`start`/`open`/`new`/`begin`/`acquire` + session, basket, cart, checkout, handle, lease or lock) that another tool takes back (`session_id`, `sessionToken`, `session`), whose description and output schema don't say how long it lasts. The spec asks for retention in the creation tool's description. Unsure"
66
+ },
67
+ "lists/schema": {
68
+ "command": "snapshot",
69
+ "severity": "error",
70
+ "text": "Each list's raw result pages against the official schema of the protocol version (`ListPromptsResult`, `ListResourcesResult`, `ListResourceTemplatesResult`); 2026-07-28 requires `ttlMs` and `cacheScope`. A declared list that fails to answer is a warning; Method not found (-32601) is info, and a setup failure (credentials, this machine) is info that says it wasn't checked. A list asked for whose capability the server doesn't declare isn't read, and the snapshot says so in a note, not a finding"
71
+ },
72
+ "lists/variance": {
73
+ "command": "snapshot",
74
+ "severity": "warn",
75
+ "text": "`snapshot --lists prompts,resources` (or `lists` in the config) reads `prompts/list`, `resources/list` and `resources/templates/list` (only those the server declares a capability for, up to 50 pages each, bypassing the SDK's list cache) twice on the main connection and once from a second process or connection (`--processes 1` turns that off). A difference by item (name, uri, uriTemplate), in content, key order or order is the finding"
76
+ },
77
+ "menu/auth-variance": {
78
+ "command": "snapshot",
79
+ "severity": "info",
80
+ "text": "`snapshot --as name:credential` (repeatable) or `identities` in the config lists the menu once per identity: a header set (HTTP) or env vars (stdio) over `--header`/`--env`. The first identity's menu is saved and checked; each other one, from its own process or connection, is compared with it: tools it adds, lacks, or defines differently, and its tokens. The tool set **MAY** vary by authorization, so this is info. An identity that can't be listed is reported here, and the others are still compared"
81
+ },
82
+ "menu/connection-variance": {
83
+ "command": "snapshot",
84
+ "severity": "error",
85
+ "text": "The same over HTTP: a second connection with the same credentials gets a different menu. Retried once before reporting"
86
+ },
87
+ "menu/capability-dependent": {
88
+ "command": "snapshot",
89
+ "severity": "info",
90
+ "text": "snapshot lists the menu as a client that supports elicitation and MCP Apps (the menu file holds that menu) and once more as one that declares neither: the tools only one of them sees, and tools listed with another definition (an Apps server's UI variant). When they differ, a third listing with elicitation alone says which capability each tool depends on. github-mcp-server 1.14 lists `delete_repository` only to a client that can ask the user to confirm. Allowed; a client without the capability never sees those tools. An app-only tool listed only to an Apps host is what ext-apps asks for and isn't reported. Not with `--processes 1`"
91
+ },
92
+ "menu/duplicate-name": {
93
+ "command": "snapshot",
94
+ "severity": "error",
95
+ "text": "Two tools with the same name: only one can be called, and some clients reject the list"
96
+ },
97
+ "menu/gated": {
98
+ "command": "snapshot",
99
+ "severity": "warn",
100
+ "text": "The server declares `listChanged: true` and has a tool that unlocks more (an enum of toolsets or domains), and the unlock's values aren't already listed. The snapshot may be only the starting set, so a baseline made from it misses every tool behind the unlock (a real server: 18 of 115 tools). Run `session --auto` to walk the unlocks"
101
+ },
102
+ "menu/host-specific": {
103
+ "command": "snapshot",
104
+ "severity": "info",
105
+ "text": "A description holds a value that differs per host (a container, host or instance ID in hex), so the menu differs on every install and every machine misses the prompt cache. Heuristic"
106
+ },
107
+ "menu/network-dependent": {
108
+ "command": "snapshot",
109
+ "severity": "warn, info when it doesn't start",
110
+ "text": "`--offline-check` (stdio) or `offlineCheck` in the config: the menu listed once more from a process whose proxy variables point at a closed port, so the network is cut off for every client that honours them (loopback stays reachable: a server's own local helper isn't the network). A different menu is the finding (inite-visibility: 3 tools offline, 10 online): a machine without the network gets it, and a baseline made with the network doesn't match. A server that doesn't start offline is info. One-sided: a server that ignores the proxy variables still reaches the network where the machine has direct access, and the menus then match"
111
+ },
112
+ "menu/nondeterministic": {
113
+ "command": "snapshot",
114
+ "severity": "error",
115
+ "text": "Two identical `tools/list` calls return different menus. Reports what differed: order, description, schema, annotations, tool added, tool removed. Order and content changes are both cache-relevant. Spec basis for order: servers **SHOULD** return \"the same ordering across requests when the underlying set of tools has not changed\" (§12). Content changes are toolmenu's own rule (lesson 05), not a spec violation"
116
+ },
117
+ "menu/process-variance": {
118
+ "command": "snapshot",
119
+ "severity": "error",
120
+ "text": "A second server process, started the same way, serves a different menu, so every restart misses the cache. Seen on mcp-atlassian: a default built from a Python set, in a new order every start (FINDINGS F12). toolmenu runs the main process with `PYTHONHASHSEED=0`, so a Python server's saved menu is reproducible, and the second with another seed. `--processes 1` turns it off"
121
+ },
122
+ "naming/client-name": {
123
+ "command": "snapshot",
124
+ "severity": "warn",
125
+ "text": "`--client` only. Tool names outside the client's API name format: the Claude API's `^[a-zA-Z0-9_-]{1,128}$` (platform.claude.com define-tools) for `claude-code` and `claude-api-search`, OpenAI's `FunctionToolParam.name` (`^[a-zA-Z0-9_-]+$`, maxLength 128, openai/openai-openapi) for `openai`. The detail names the source and read date"
126
+ },
127
+ "naming/route": {
128
+ "command": "snapshot",
129
+ "severity": "error",
130
+ "text": "A `routes.yml` expectation broke"
131
+ },
132
+ "naming/shared-word": {
133
+ "command": "snapshot",
134
+ "severity": "info",
135
+ "text": "The same noun is a primary term in tools from different areas (the \"audit\" collision). Lists groups for review, never fails the build"
136
+ },
137
+ "naming/vague-id": {
138
+ "command": "snapshot",
139
+ "severity": "warn",
140
+ "text": "A parameter named `id`, `ids` or `key` that doesn't say which kind of thing it identifies (the ~13-wasted-calls bug)"
141
+ },
142
+ "search/findable": {
143
+ "command": "snapshot",
144
+ "severity": "info",
145
+ "text": "For a menu a client would defer (10+ tools and 10K+ tokens, or 30+ tools): a tool that a BM25 search for its own name words doesn't put in the top 5, the number a tool search returns by default. With `routes.yml`, a `must_match` tool past the top 5 for its keyword is a warning. Ranked over the name, description, argument names and argument descriptions, as Claude's tool search reads them; the client's tokenizer and parameters aren't published, so marked unsure"
146
+ },
147
+ "spec/cache-hints": {
148
+ "command": "snapshot",
149
+ "severity": "info",
150
+ "text": "Cache metadata recommendation, not a correctness error (`since: 2026-07-28`). `ttlMs: 0` on `tools/list`: valid, but tells clients the list is \"immediately stale\" and they may re-fetch every time. `cacheScope: \"public\"` on a server that required auth: valid only if the list has no user-specific data, because shared caches \"MAY … serve it across authorization contexts\". Worth a look if the tool set depends on the caller's scopes"
151
+ },
152
+ "spec/cache-scope-public": {
153
+ "command": "snapshot",
154
+ "severity": "warn",
155
+ "text": "`since: 2026-07-28`. The tool set differs by identity and `tools/list` says `cacheScope: \"public\"` (shared caches **MAY** serve it across authorization contexts). With identities to compare, it replaces `spec/cache-hints`' public-scope hint, which has no evidence either way"
156
+ },
157
+ "spec/deprecated": {
158
+ "command": "snapshot",
159
+ "severity": "info",
160
+ "text": "Advertises Sampling, Roots or Logging, or uses HTTP+SSE (`since: 2026-07-28`)"
161
+ },
162
+ "spec/extension-id": {
163
+ "command": "snapshot",
164
+ "severity": "warn",
165
+ "text": "Each key of `capabilities.extensions` is an identifier in `_meta` key form with a mandatory vendor prefix (`io.modelcontextprotocol/ui`, `com.example/feature`), each value a settings object (`{}` for none). A client looks an extension up by its exact identifier, so one spelled otherwise reads as not declared. A value that isn't an object is a finding of its own (the 2026-07-28 schema's settings object)"
166
+ },
167
+ "spec/discover": {
168
+ "command": "snapshot",
169
+ "severity": "info",
170
+ "text": "The server only speaks the 2025 protocol: no working `server/discover`, which 2026-07-28 servers **MUST** implement. Info, not error: see §13"
171
+ },
172
+ "spec/ref": {
173
+ "command": "snapshot",
174
+ "severity": "error",
175
+ "text": "`since: 2026-07-28`. A `$ref` in a tool's input or output schema that doesn't resolve inside the schema: a network URI (clients **MUST NOT** fetch it, SEP-2106) or a pointer, `#anchor` or `$id` that names nothing. In an `outputSchema`, error: the official SDK client fails every call to the tool (\"has an invalid outputSchema\"). In an `inputSchema`, error for a ref to nothing (the schema isn't valid, and the SDK's server won't register it), warn for a network URI (clients **SHOULD** reject the schema). `#/$defs`, `#anchor`, `$dynamicAnchor`, `$id` (pointers resolve inside the resource an `$id` names), draft-07 `#name` ids, `\"\"` and `#` refs resolve. The token breakdown's unused-`$defs` count uses the same resolver. Composition-keyword bounds are left to each implementation by the spec, so not checked. Checked against the SDK client's behaviour in the tests"
176
+ },
177
+ "spec/schema": {
178
+ "command": "snapshot",
179
+ "severity": "error",
180
+ "text": "`tools/list` result fails the official `schema.json` for its version. Version-aware: a 2026-07-28 result missing `ttlMs`/`cacheScope` fails, because that version requires them on cacheable results (SEP-2549); a 2025 result is checked against its own schema, which doesn't have them"
181
+ },
182
+ "spec/server-card": {
183
+ "command": "snapshot",
184
+ "severity": "warn",
185
+ "text": "HTTP only. The Server Card at `<url>/server-card` (SEP-2127, ext-server-card), when the server serves one: it doesn't match the Server Card schema, or contradicts the live server (its `version` against serverInfo, the `supportedProtocolVersions` of the remote for this URL against the negotiated version), which the card SHOULD NOT do. A JSON answer counts as a card only when it is served as `application/mcp-server-card+json` or its `$schema` names the Server Card schema, so a server answering every path with JSON has none. Info when a card names the schema but isn't served as `application/mcp-server-card+json`. The protocol versions aren't compared when this connection fell back to 2025 and a later one got 2026-07-28 (see `spec/discover`). No card, or a 404, is fine and says nothing. Names aren't compared: cards carry registry names, serverInfo a display name. Read without credentials; `\"spec/server-card\": \"off\"` in the config skips the request"
186
+ },
187
+ "spec/server-info": {
188
+ "command": "snapshot",
189
+ "severity": "warn",
190
+ "text": "The handshake's `serverInfo` has no `name` or no `version`, so a client (and `diff --server-version-is-release`) can't tell which server or release answered"
191
+ },
192
+ "spec/task-required": {
193
+ "command": "snapshot",
194
+ "severity": "info",
195
+ "text": "A tool marked `execution.taskSupport: \"required\"` (2025-11-25 Tasks) runs only as a task, so a client without Tasks support can't call it. On 2026-07-28, where Tasks became the `io.modelcontextprotocol/tasks` extension with no per-tool flag, the field says nothing and clients ignore it"
196
+ },
197
+ "spec/tools-capability": {
198
+ "command": "snapshot",
199
+ "severity": "error",
200
+ "text": "The server doesn't declare the `tools` capability, so clients (the official SDK included) never ask for its tools"
201
+ },
202
+ "spec/x-mcp-header": {
203
+ "command": "snapshot",
204
+ "severity": "error",
205
+ "text": "`since: 2026-07-28`. An `x-mcp-header` annotation the spec doesn't allow (SEP-2243): empty; not an RFC 9110 token; the same header twice ignoring case; on a parameter that isn't `string`, `integer` or `boolean`, or has no single `type`; anywhere but a parameter reached through `properties` alone. Streamable HTTP clients **MUST** leave such a tool out of `tools/list`, and the official SDK client does, with only a console warning. Error on an HTTP server, warn on stdio (clients there MAY ignore the annotation). `number` is warn on both: the spec forbids it, the SDK client accepts it for now. Every broken annotation in a tool is listed (the SDK stops at the first). Checked against the SDK client's behaviour in the tests"
206
+ },
207
+ "write/no-dry-run": {
208
+ "command": "snapshot",
209
+ "severity": "info",
210
+ "text": "A `destructiveHint: true` or `readOnlyHint: false` tool with no `dry_run`/`preview`-style parameter and no matching preview tool"
211
+ },
212
+ "write/read-only-mismatch": {
213
+ "command": "snapshot",
214
+ "severity": "warn",
215
+ "text": "`readOnlyHint: true` on a tool whose name starts with a write verb (create, delete, send, upload, set…). Unsure: a tool can write only local state. `session --auto` skips such a tool, saying why, rather than call it on the hint alone. Not when the tool's description says it only reads (\"read-only\", \"without changing\"), as with a `create_…_query` that runs a query"
216
+ },
217
+ "write/unannotated": {
218
+ "command": "snapshot",
219
+ "severity": "warn",
220
+ "text": "A tool whose name suggests writing (`delete_`, `send_`, `update_`…) has no annotations. MCP Apps app-only tools count too: the agent never sees them, but the host decides by annotations whether to confirm the app's calls"
221
+ },
222
+ "diff/annotations": {
223
+ "command": "diff",
224
+ "severity": "info (notice)",
225
+ "text": "Other annotations changed (`title`, `idempotentHint`, `openWorldHint`, a hint removed). Grouped when the same change is in several tools"
226
+ },
227
+ "diff/apps-ui": {
228
+ "command": "diff",
229
+ "severity": "info (notice)",
230
+ "text": "MCP Apps: the UI a tool names (`_meta.ui.resourceUri`, or the deprecated `_meta[\"ui/resourceUri\"]`) was added, removed or moved, or visibility changed for the app alone. What an Apps host renders changes; calls don't. Grouped across tools. The rest of `_meta.ui` (`csp`, `permissions`, `domain`) is compared as any `_meta` field, under `diff/other`"
231
+ },
232
+ "diff/apps-visibility": {
233
+ "command": "diff",
234
+ "severity": "error (breaking)",
235
+ "text": "MCP Apps: a tool's `_meta.ui.visibility` lost `\"model\"` (unset means `[\"model\", \"app\"]`). An Apps host leaves it out of the agent's tool list, so agents, saved prompts and evals that call it fail there"
236
+ },
237
+ "diff/apps-visible": {
238
+ "command": "diff",
239
+ "severity": "info (minor)",
240
+ "text": "MCP Apps: a tool's visibility gained `\"model\"`, so the agent sees it now"
241
+ },
242
+ "diff/catalog-added": {
243
+ "command": "diff",
244
+ "severity": "info",
245
+ "text": "Operations behind a search tool that are new, or newly found by the same queries"
246
+ },
247
+ "diff/catalog-missing": {
248
+ "command": "diff",
249
+ "severity": "info",
250
+ "text": "Operations behind a search tool (`--catalog`) that the same queries didn't return this time: removed, renamed, or ranked lower. A notice, no bump"
251
+ },
252
+ "diff/catalog-queries": {
253
+ "command": "diff",
254
+ "severity": "info",
255
+ "text": "Only one snapshot has a catalog, the two were read with different queries, or one is partial: what's on one side only says less"
256
+ },
257
+ "diff/description": {
258
+ "command": "diff",
259
+ "severity": "info (notice)",
260
+ "text": "A description changed, with a text diff. It doesn't break the protocol, but it changes what the agent does"
261
+ },
262
+ "diff/enum-narrowed": {
263
+ "command": "diff",
264
+ "severity": "error (breaking)",
265
+ "text": "A parameter now accepts fewer values, or became limited to a fixed set. Calls that send any other value fail validation"
266
+ },
267
+ "diff/enum-widened": {
268
+ "command": "diff",
269
+ "severity": "info (minor)",
270
+ "text": "A parameter accepts more values, or is no longer limited to a fixed set"
271
+ },
272
+ "diff/extension-added": {
273
+ "command": "diff",
274
+ "severity": "info (minor)",
275
+ "text": "The server declares an extension (`capabilities.extensions`) the old menu didn't. Menu files from before 0.23 don't record extensions: not compared"
276
+ },
277
+ "diff/extension-removed": {
278
+ "command": "diff",
279
+ "severity": "warn (breaking)",
280
+ "text": "The server no longer declares an extension: clients stop using what it adds (MCP Apps' UI, Tasks); core requests go on working"
281
+ },
282
+ "diff/extension-settings": {
283
+ "command": "diff",
284
+ "severity": "info (notice)",
285
+ "text": "An extension's settings object changed"
286
+ },
287
+ "diff/lists-unread": {
288
+ "command": "diff",
289
+ "severity": "info",
290
+ "text": "Only one menu was snapshotted with `--lists`, so prompts or resources weren't compared"
291
+ },
292
+ "diff/order": {
293
+ "command": "diff",
294
+ "severity": "info (notice)",
295
+ "text": "The tool order changed. It matters within a session (the prompt cache), not between releases"
296
+ },
297
+ "diff/other": {
298
+ "command": "diff",
299
+ "severity": "info (notice)",
300
+ "text": "Other tool fields changed (`title`, `icons`, `_meta`). Clients may show these; the agent may read them"
301
+ },
302
+ "diff/param-added": {
303
+ "command": "diff",
304
+ "severity": "info (minor)",
305
+ "text": "A new optional parameter"
306
+ },
307
+ "diff/param-default": {
308
+ "command": "diff",
309
+ "severity": "info (notice)",
310
+ "text": "A parameter's default changed: calls that leave it out now behave differently"
311
+ },
312
+ "diff/param-dropped": {
313
+ "command": "diff",
314
+ "severity": "info (notice)",
315
+ "text": "An optional parameter removed from an object that accepts properties it doesn't list: calls that still send it stay valid, but the server may ignore it"
316
+ },
317
+ "diff/param-relaxed": {
318
+ "command": "diff",
319
+ "severity": "info (minor)",
320
+ "text": "A required parameter became optional"
321
+ },
322
+ "diff/param-removed": {
323
+ "command": "diff",
324
+ "severity": "error (breaking)",
325
+ "text": "A required parameter removed (every existing call sends it, and the server no longer reads it), or an optional one removed from an object that rejects properties it doesn't list (calls that still send it fail validation)"
326
+ },
327
+ "diff/param-renamed": {
328
+ "command": "diff",
329
+ "severity": "warn",
330
+ "text": "A tool lost a parameter and gained a required one with a close name: likely a rename. A hint next to the two breaking findings, not a change of its own"
331
+ },
332
+ "diff/param-required": {
333
+ "command": "diff",
334
+ "severity": "error (breaking)",
335
+ "text": "A parameter that's new and required, or was optional and is now required. Calls that don't send it fail"
336
+ },
337
+ "diff/param-type": {
338
+ "command": "diff",
339
+ "severity": "error (breaking)",
340
+ "text": "A parameter's type changed to one that doesn't accept every old value (`string` → `integer`), or a `oneOf`/`anyOf` option was dropped"
341
+ },
342
+ "diff/prompt-added": {
343
+ "command": "diff",
344
+ "severity": "info (minor)",
345
+ "text": "`--lists`: a new prompt"
346
+ },
347
+ "diff/prompt-argument-required": {
348
+ "command": "diff",
349
+ "severity": "error (breaking)",
350
+ "text": "`--lists`: a prompt argument that's new and required, or now required. Invocations that don't pass it fail"
351
+ },
352
+ "diff/prompt-changed": {
353
+ "command": "diff",
354
+ "severity": "info (notice)",
355
+ "text": "`--lists`: a prompt's description or arguments changed, and nothing it requires"
356
+ },
357
+ "diff/prompt-removed": {
358
+ "command": "diff",
359
+ "severity": "error (breaking)",
360
+ "text": "`--lists`: a prompt removed. Users and clients that invoke it by name (a slash command, a saved workflow) get an error"
361
+ },
362
+ "diff/properties-closed": {
363
+ "command": "diff",
364
+ "severity": "error (breaking)",
365
+ "text": "`additionalProperties: false` added: calls that send extra arguments now fail validation"
366
+ },
367
+ "diff/properties-opened": {
368
+ "command": "diff",
369
+ "severity": "info (minor)",
370
+ "text": "`additionalProperties: false` removed: the tool accepts extra arguments"
371
+ },
372
+ "diff/resource-template-added": {
373
+ "command": "diff",
374
+ "severity": "info (minor)",
375
+ "text": "`--lists`: a new resource template"
376
+ },
377
+ "diff/resource-template-removed": {
378
+ "command": "diff",
379
+ "severity": "error (breaking)",
380
+ "text": "`--lists`: a resource template removed. Clients that read resources through it get an error"
381
+ },
382
+ "diff/resources": {
383
+ "command": "diff",
384
+ "severity": "info (notice)",
385
+ "text": "`--lists`: concrete resources that came or went. Resources are data (files come and go): listed, no bump"
386
+ },
387
+ "diff/safety-hint": {
388
+ "command": "diff",
389
+ "severity": "error (breaking)",
390
+ "text": "`readOnlyHint` true → false, or `destructiveHint` added. An agent or client that ran the tool without asking now has a write it didn't approve"
391
+ },
392
+ "diff/schema-dialect": {
393
+ "command": "diff",
394
+ "severity": "info (notice)",
395
+ "text": "Only the declared `$schema` dialect changed. One finding for the menu"
396
+ },
397
+ "diff/schema-equivalent": {
398
+ "command": "diff",
399
+ "severity": "info (notice)",
400
+ "text": "The schema was restructured or respelled (`$ref`, `$defs`, key order) but accepts the same input: bytes and tokens changed, nothing else"
401
+ },
402
+ "diff/schema-other": {
403
+ "command": "diff",
404
+ "severity": "info (notice)",
405
+ "text": "The input schema changed in keywords toolmenu doesn't classify, a schema that's empty or invalid, or one too large to expand through its `$ref`s. Review it by hand"
406
+ },
407
+ "diff/token-budget": {
408
+ "command": "diff",
409
+ "severity": "error",
410
+ "text": "The new menu is over `tokenBudget` from the config. Every conversation that loads it pays that before its first message"
411
+ },
412
+ "diff/tool-added": {
413
+ "command": "diff",
414
+ "severity": "info (minor)",
415
+ "text": "A new tool. It costs tokens in every conversation that loads the menu (see the token change)"
416
+ },
417
+ "diff/tool-removed": {
418
+ "command": "diff",
419
+ "severity": "error (breaking)",
420
+ "text": "A tool in the old menu isn't in the new one. Agents and saved workflows that call it get an error"
421
+ },
422
+ "diff/tool-renamed": {
423
+ "command": "diff",
424
+ "severity": "error (breaking)",
425
+ "text": "One tool removed and one added with a near-identical schema: reported as a rename, still breaking for anything that calls the old name"
426
+ },
427
+ "diff/type-widened": {
428
+ "command": "diff",
429
+ "severity": "info (minor)",
430
+ "text": "A parameter's type now accepts more (`integer` → `number`, a type added to a union)"
431
+ },
432
+ "diff/version-backwards": {
433
+ "command": "diff",
434
+ "severity": "warn",
435
+ "text": "The release version went backwards, so the bump can't be checked"
436
+ },
437
+ "diff/version-bump": {
438
+ "command": "diff",
439
+ "severity": "warn",
440
+ "text": "`--release old..new` (or `--server-version-is-release`): the bump is smaller than the changes need, a breaking change released as a minor or patch"
441
+ },
442
+ "diff/x-mcp-header": {
443
+ "command": "diff",
444
+ "severity": "info (notice)",
445
+ "text": "2026-07-28: a parameter mirrored into an `Mcp-Param-*` HTTP header was added, removed or renamed. Callers don't change; proxies and WAFs that route on the header do"
446
+ },
447
+ "diff/x-mcp-header-invalid": {
448
+ "command": "diff",
449
+ "severity": "warn (notice)",
450
+ "text": "The new release has an `x-mcp-header` annotation that breaks the spec's rules, so Streamable HTTP clients must leave the tool out of their menu. A warning, not breaking: a menu file doesn't say whether the server is served over HTTP"
451
+ },
452
+ "session/append": {
453
+ "command": "session",
454
+ "severity": "warn",
455
+ "text": "Tools added at the end of the list. Still a cache miss for the conversation when your client sends tools at the start of the prompt (Claude's Messages API does); cache-safe only when the client adds new tools after the cached content, as tool search (deferred loading) does"
456
+ },
457
+ "session/assumed-read-only": {
458
+ "command": "session",
459
+ "severity": "info",
460
+ "text": "Tools called on your word (`--assume-read-only`, `assume_read_only`) although the server doesn't mark them readOnlyHint"
461
+ },
462
+ "session/connection-local": {
463
+ "command": "session",
464
+ "severity": "error on 2026-07-28 (HTTP)",
465
+ "text": "A change only this connection sees. 2026-07-28: the tool set MUST NOT vary \"per-connection or as a side effect of other requests on the connection\""
466
+ },
467
+ "session/decline-fails": {
468
+ "command": "session",
469
+ "severity": "warn",
470
+ "text": "The retry carrying the decline fails with a JSON-RPC error, not a result the model can read. A tool error (`isError`) after a decline is the right answer and isn't reported"
471
+ },
472
+ "session/edit": {
473
+ "command": "session",
474
+ "severity": "error",
475
+ "text": "A tool's description, schema or annotations changed mid-session, with which value changed. The prompt cache is invalidated from that tool on"
476
+ },
477
+ "session/handle-error": {
478
+ "command": "session",
479
+ "severity": "warn",
480
+ "text": "A handle that can't exist answered with a JSON-RPC error, not a tool error (`isError`) the model can read and recover from by making a new one. A tool error, or an answer, isn't reported. One finding per tool; unsure"
481
+ },
482
+ "session/error-not-flagged": {
483
+ "command": "session",
484
+ "severity": "warn",
485
+ "text": "A tool answered with an HTTP error from the API behind it (`{\"status\":401,\"object\":\"error\",…}`, `{\"error\":{\"status\":500,…}}`) as a plain result, not marked `isError`, so a client that reads `isError` takes the call for a success. One finding for the run. Tools that take a URL are left out: their answer is the page's. Unsure: read from the answer's shape"
486
+ },
487
+ "session/handle-roundtrip": {
488
+ "command": "session",
489
+ "severity": "warn, info when no handle was found",
490
+ "text": "`--create-handles`: the handle a creating tool just returned (`start_session` → `session_id`) refused by the tools that take it back (warn), or a creating tool whose result has no handle to find (info), so the made-up one was used instead"
491
+ },
492
+ "session/input-loop": {
493
+ "command": "session",
494
+ "severity": "warn",
495
+ "text": "After a decline the tool asks the same question again (the same kind and schema, whatever the request key or wording), or keeps asking something else, until the round limit; or it returns `requestState`-only rounds without end. An agent whose user says no can't finish the call"
496
+ },
497
+ "session/input-required": {
498
+ "command": "session",
499
+ "severity": "info",
500
+ "text": "Which tools asked for input, for what, how many rounds, and what the decline led to. One finding for the run"
501
+ },
502
+ "session/known-variance": {
503
+ "command": "session",
504
+ "severity": "info",
505
+ "text": "A mid-session change only in values that already vary from one tools/list to the next: same cause as the finding it names, not counted again"
506
+ },
507
+ "session/mid-insert": {
508
+ "command": "session",
509
+ "severity": "error",
510
+ "text": "Tools inserted into the menu mid-session anywhere but the end. Any change to the tool list invalidates the cached prompt: the whole tool list and the conversation after it are processed again"
511
+ },
512
+ "session/nothing-called": {
513
+ "command": "session",
514
+ "severity": "warn",
515
+ "text": "`--auto` called no tools (all open-world, missing values, or not read-only): the run only listed the menu"
516
+ },
517
+ "session/rate-limited": {
518
+ "command": "session",
519
+ "severity": "error",
520
+ "text": "The server kept refusing requests for being too many (a 429) after toolmenu waited about a minute, or a tool not marked `readOnlyHint` said it was rate-limited (it isn't called again). The run stops there, with the steps it didn't check; give the run its own server instance or raise the limit for it"
521
+ },
522
+ "session/refused": {
523
+ "command": "session",
524
+ "severity": "error",
525
+ "text": "A call the scenario didn't allow: a tool not marked `readOnlyHint` without `allow_writes`, or one marked `destructiveHint`. Nothing was sent"
526
+ },
527
+ "session/remove": {
528
+ "command": "session",
529
+ "severity": "error",
530
+ "text": "A tool gone from the menu mid-session. A model that already planned to call it gets an error, and the prompt cache is invalidated"
531
+ },
532
+ "session/reorder": {
533
+ "command": "session",
534
+ "severity": "error",
535
+ "text": "The same tools mid-session in a different order: a cache miss for everything after the first moved tool"
536
+ },
537
+ "session/result-type": {
538
+ "command": "session",
539
+ "severity": "error",
540
+ "text": "A 2026-07-28 `tools/call` result without `resultType` (**MUST**), or an `input_required` result whose `requestState` isn't a string (it can't be echoed as it came; toolmenu stops the call). The official SDK client rejects a result without `resultType`"
541
+ },
542
+ "session/scope-unchecked": {
543
+ "command": "session",
544
+ "severity": "info",
545
+ "text": "A second server process or connection couldn't start mid-session (a server that holds a file or a port), so whether a change was global wasn't checked. Said once for the run"
546
+ },
547
+ "session/session-lost": {
548
+ "command": "session",
549
+ "severity": "error",
550
+ "text": "The server ended the session after toolmenu opened a second connection with the same credentials (servers with one session per client; 2025-era servers only). The run stops there; rerun with `--processes 1`"
551
+ },
552
+ "session/side-effect": {
553
+ "command": "session",
554
+ "severity": "warn on 2026-07-28 (stdio)",
555
+ "text": "The same, where stdio can't tell per-connection from global"
556
+ },
557
+ "session/step-failed": {
558
+ "command": "session",
559
+ "severity": "error",
560
+ "text": "A step that failed for a reason that isn't setup (authentication, network, missing software): a JSON-RPC error, a timeout, or a server that exited"
561
+ },
562
+ "session/server-unresponsive": {
563
+ "command": "session",
564
+ "severity": "error",
565
+ "text": "The server stopped answering after a step: the `tools/list` after it timed out with the server still running, so every later step would wait out its timeout too. The run stops there, with this one finding (the call's own timeout folded in). Seen on a server that polls a device-code sign-in inside a tool call"
566
+ },
567
+ "session/tool-error": {
568
+ "command": "session",
569
+ "severity": "warn",
570
+ "text": "A tool that answered with an error for another reason (`isError`): the run tested less than it looks. The same error at several steps is one finding that names them"
571
+ },
572
+ "session/unannounced": {
573
+ "command": "session",
574
+ "severity": "warn",
575
+ "text": "The menu changed, the server declared `listChanged: true`, and no `notifications/tools/list_changed` arrived. The spec says servers **SHOULD** send it"
576
+ },
577
+ "session/undeclared-input": {
578
+ "command": "session",
579
+ "severity": "warn",
580
+ "text": "The server asked for something the request didn't declare (roots, sampling) instead of returning `-32021`"
581
+ },
582
+ "session/unlock-coverage": {
583
+ "command": "session",
584
+ "severity": "warn",
585
+ "text": "An unlock whose enum lists its values, called with only some of them: the tools behind the rest were never seen, so a baseline from the session misses them. With `--union-out` or `--auto`, an unlock never called at all too, with why `--auto` skipped it"
586
+ },
587
+ "session/undeclared-task": {
588
+ "command": "session",
589
+ "severity": "error",
590
+ "text": "2026-07-28 with the Tasks extension (ext-tasks). A call answered with a task to poll (`resultType: \"task\"`), though session declares no `io.modelcontextprotocol/tasks` support. ext-tasks: \"A server MUST NOT return CreateTaskResult to a client that did not include the extension capability on its request\"; it should answer in one go or return -32021 naming the extension. Such a client has no `tasks/get` to poll with, so the agent gets no result"
591
+ },
592
+ "session/untested": {
593
+ "command": "session",
594
+ "severity": "warn, error if no call got through",
595
+ "text": "Calls that failed before reaching the tool: authentication, something missing on this machine (no Chrome), the network; or an answer, not marked `isError`, that is the API's 401 or 403 passed on as JSON (`{\"status\":401,\"code\":\"unauthorized\"}`, Notion's server). One finding for the run, not one per step, so an expired CI secret doesn't pass a run that tested nothing"
596
+ }
597
+ }
@@ -0,0 +1,11 @@
1
+ import { type Rule } from './rule.js';
2
+ export declare const appsResource: Rule;
3
+ export declare const appsLegacyKey: Rule;
4
+ export declare const appsVisibility: Rule;
5
+ /**
6
+ * App-only tools listed to a client that didn't declare MCP Apps. Such a client doesn't
7
+ * read _meta.ui, so it puts them in its agent's list: tools meant to be called by an
8
+ * app's UI, offered to the agent. ext-apps: "Servers SHOULD check client capabilities
9
+ * before registering UI-enabled tools".
10
+ */
11
+ export declare const appsAppOnlyListed: Rule;