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
@@ -1,4 +1,24 @@
1
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
+ },
2
22
  "auth/invalid-accepted": {
3
23
  "command": "snapshot",
4
24
  "severity": "warn",
@@ -64,6 +84,11 @@
64
84
  "severity": "error",
65
85
  "text": "The same over HTTP: a second connection with the same credentials gets a different menu. Retried once before reporting"
66
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
+ },
67
92
  "menu/duplicate-name": {
68
93
  "command": "snapshot",
69
94
  "severity": "error",
@@ -79,6 +104,11 @@
79
104
  "severity": "info",
80
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"
81
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
+ },
82
112
  "menu/nondeterministic": {
83
113
  "command": "snapshot",
84
114
  "severity": "error",
@@ -129,6 +159,11 @@
129
159
  "severity": "info",
130
160
  "text": "Advertises Sampling, Roots or Logging, or uses HTTP+SSE (`since: 2026-07-28`)"
131
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
+ },
132
167
  "spec/discover": {
133
168
  "command": "snapshot",
134
169
  "severity": "info",
@@ -144,11 +179,21 @@
144
179
  "severity": "error",
145
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"
146
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
+ },
147
187
  "spec/server-info": {
148
188
  "command": "snapshot",
149
189
  "severity": "warn",
150
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"
151
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
+ },
152
197
  "spec/tools-capability": {
153
198
  "command": "snapshot",
154
199
  "severity": "error",
@@ -157,7 +202,7 @@
157
202
  "spec/x-mcp-header": {
158
203
  "command": "snapshot",
159
204
  "severity": "error",
160
- "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"
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). A `number` parameter counts too: the SDK client drops those tools since 2.4. Every broken annotation in a tool is listed (the SDK stops at the first). Checked against the SDK client's behaviour in the tests"
161
206
  },
162
207
  "write/no-dry-run": {
163
208
  "command": "snapshot",
@@ -167,18 +212,33 @@
167
212
  "write/read-only-mismatch": {
168
213
  "command": "snapshot",
169
214
  "severity": "warn",
170
- "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"
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"
171
216
  },
172
217
  "write/unannotated": {
173
218
  "command": "snapshot",
174
219
  "severity": "warn",
175
- "text": "A tool whose name suggests writing (`delete_`, `send_`, `update_`…) has no annotations"
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"
176
221
  },
177
222
  "diff/annotations": {
178
223
  "command": "diff",
179
224
  "severity": "info (notice)",
180
225
  "text": "Other annotations changed (`title`, `idempotentHint`, `openWorldHint`, a hint removed). Grouped when the same change is in several tools"
181
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
+ },
182
242
  "diff/catalog-added": {
183
243
  "command": "diff",
184
244
  "severity": "info",
@@ -209,6 +269,21 @@
209
269
  "severity": "info (minor)",
210
270
  "text": "A parameter accepts more values, or is no longer limited to a fixed set"
211
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
+ },
212
287
  "diff/lists-unread": {
213
288
  "command": "diff",
214
289
  "severity": "info",
@@ -404,6 +479,11 @@
404
479
  "severity": "warn",
405
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"
406
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
+ },
407
487
  "session/handle-roundtrip": {
408
488
  "command": "session",
409
489
  "severity": "warn, info when no handle was found",
@@ -477,7 +557,12 @@
477
557
  "session/step-failed": {
478
558
  "command": "session",
479
559
  "severity": "error",
480
- "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. A server that stops answering (`tools/list` times out after a step) ends the run there, with one finding"
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"
481
566
  },
482
567
  "session/tool-error": {
483
568
  "command": "session",
@@ -499,6 +584,11 @@
499
584
  "severity": "warn",
500
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"
501
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
+ },
502
592
  "session/untested": {
503
593
  "command": "session",
504
594
  "severity": "warn, error if no call got through",
@@ -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;
@@ -0,0 +1,156 @@
1
+ import { APPS_MIME_TYPE } from '../connect.js';
2
+ import { isAppOnly, isAppsMimeType, LEGACY_URI_KEY, uiMeta } from '../apps.js';
3
+ import { clip, count, kept, names } from './rule.js';
4
+ /*
5
+ * MCP Apps (ext-apps): checks on the UI a tool names, as an Apps host reads it.
6
+ * Each traced to specification/draft/apps.mdx:
7
+ * "URI MUST start with ui:// scheme"; "Resource MUST exist on the server";
8
+ * "mimeType MUST be text/html;profile=mcp-app"; "Content MUST be provided via
9
+ * either text or blob"; visibility "model" | "app", "Host MUST NOT include tools in
10
+ * the agent's tool list when their visibility does not include "model"".
11
+ */
12
+ const FALLBACK = 'An Apps host then shows no UI for the tool; the agent still gets its text result.';
13
+ export const appsResource = {
14
+ id: 'apps/resource',
15
+ severity: 'warn',
16
+ summary: "The UI a tool names (MCP Apps _meta.ui.resourceUri) is a ui:// resource the server serves as an app",
17
+ run(ctx) {
18
+ const problems = [];
19
+ const read = new Map((ctx.appResources ?? []).map((r) => [r.uri, r]));
20
+ for (const tool of kept(ctx.menu.tools, ctx)) {
21
+ const ui = uiMeta(tool);
22
+ if (!ui || (ui.resourceUri === undefined && ui.legacyUri === undefined))
23
+ continue;
24
+ const uri = ui.resourceUri ?? ui.legacyUri;
25
+ if (typeof uri !== 'string' || !uri) {
26
+ problems.push({ tool: tool.name, why: `_meta.ui.resourceUri is ${JSON.stringify(uri)}, not a ui:// URI` });
27
+ continue;
28
+ }
29
+ if (typeof ui.resourceUri === 'string' && typeof ui.legacyUri === 'string' && ui.resourceUri !== ui.legacyUri) {
30
+ problems.push({ tool: tool.name, why: `_meta.ui.resourceUri is ${ui.resourceUri} but _meta["${LEGACY_URI_KEY}"] is ${ui.legacyUri}: hosts that read the old key render another UI` });
31
+ }
32
+ if (!uri.startsWith('ui://')) {
33
+ problems.push({ tool: tool.name, why: `${clip(uri, 80)} isn't a ui:// URI, which MCP Apps require` });
34
+ continue;
35
+ }
36
+ const r = read.get(uri);
37
+ if (!r)
38
+ continue; // not read (over the limit, or the run read none)
39
+ const why = resourceProblem(r);
40
+ if (why)
41
+ problems.push({ tool: tool.name, why });
42
+ }
43
+ if (!problems.length)
44
+ return [];
45
+ const tools = [...new Set(problems.map((p) => p.tool))];
46
+ const one = tools.length === 1;
47
+ return [
48
+ {
49
+ ...(one ? { tool: tools[0] } : {}),
50
+ message: `${one ? `${tools[0]} names` : `${count(tools.length, 'tool')} name`} an MCP Apps UI that a host can't render: ${one ? problems[0].why : names(tools, 6)}. ${FALLBACK}`,
51
+ ...(one && problems.length === 1 ? {} : { detail: problems.map((p) => `${p.tool}: ${p.why}`) }),
52
+ fix: `Serve each UI as a ui:// resource that resources/read returns with mimeType "${APPS_MIME_TYPE}" and the HTML as text or blob, and point _meta.ui.resourceUri at it.`,
53
+ },
54
+ ];
55
+ },
56
+ };
57
+ function resourceProblem(r) {
58
+ if (r.error)
59
+ return `resources/read of ${r.uri} failed (${clip(r.error, 120)}): the spec says the resource MUST exist on the server`;
60
+ const types = r.mimeTypes ?? [];
61
+ if (!types.length)
62
+ return `resources/read of ${r.uri} returned no contents`;
63
+ const wrong = types.filter((m) => !isAppsMimeType(m));
64
+ if (wrong.length)
65
+ return `resources/read of ${r.uri} gave mimeType ${wrong.map((m) => (m ? `"${m}"` : 'none')).join(', ')}, not "${APPS_MIME_TYPE}"`;
66
+ if (!r.hasContent)
67
+ return `resources/read of ${r.uri} returned no text or blob`;
68
+ return undefined;
69
+ }
70
+ export const appsLegacyKey = {
71
+ id: 'apps/legacy-key',
72
+ severity: 'info',
73
+ summary: 'Tools name their UI with _meta.ui.resourceUri, not the deprecated _meta["ui/resourceUri"]',
74
+ run(ctx) {
75
+ const old = kept(ctx.menu.tools, ctx).filter((t) => {
76
+ const ui = uiMeta(t);
77
+ return ui && ui.legacyUri !== undefined && ui.resourceUri === undefined;
78
+ });
79
+ if (!old.length)
80
+ return [];
81
+ const one = old.length === 1;
82
+ return [
83
+ {
84
+ ...(one ? { tool: old[0].name } : {}),
85
+ message: `${one ? `${old[0].name} names its UI` : `${count(old.length, 'tool')} name their UI`} only with _meta["${LEGACY_URI_KEY}"], which MCP Apps deprecate ("will be removed before GA"). A host that reads only _meta.ui.resourceUri shows ${one ? 'it' : 'them'} without a UI.`,
86
+ ...(one ? {} : { detail: [names(old.map((t) => t.name), 20)] }),
87
+ fix: `Add _meta: { ui: { resourceUri: "<the same ui:// URI>" } } to ${one ? old[0].name : 'each'}; keep the old key while older hosts need it.`,
88
+ },
89
+ ];
90
+ },
91
+ };
92
+ const VISIBILITIES = new Set(['model', 'app']);
93
+ export const appsVisibility = {
94
+ id: 'apps/visibility',
95
+ severity: 'warn',
96
+ summary: 'MCP Apps _meta.ui.visibility is a list of "model" and "app"',
97
+ run(ctx) {
98
+ const problems = [];
99
+ for (const tool of kept(ctx.menu.tools, ctx)) {
100
+ const v = uiMeta(tool)?.visibility;
101
+ if (v === undefined)
102
+ continue;
103
+ if (!Array.isArray(v)) {
104
+ problems.push({ tool: tool.name, why: `visibility is ${clip(JSON.stringify(v), 60)}, not a list` });
105
+ continue;
106
+ }
107
+ const unknown = v.filter((x) => typeof x !== 'string' || !VISIBILITIES.has(x));
108
+ if (unknown.length)
109
+ problems.push({ tool: tool.name, why: `visibility has ${unknown.map((x) => JSON.stringify(x)).join(', ')}, which hosts don't know` });
110
+ if (!v.includes('model') && !v.includes('app'))
111
+ problems.push({ tool: tool.name, why: 'visibility names neither "model" nor "app", so no one can call it: not the agent, not the app' });
112
+ }
113
+ if (!problems.length)
114
+ return [];
115
+ const tools = [...new Set(problems.map((p) => p.tool))];
116
+ const one = tools.length === 1;
117
+ return [
118
+ {
119
+ ...(one ? { tool: tools[0] } : {}),
120
+ message: `${one ? `${tools[0]}'s` : `${count(tools.length, 'tool')}' `} MCP Apps visibility ${one ? 'is' : 'are'} not what hosts read: ${one ? problems[0].why : names(tools, 6)}. Hosts show a tool to the agent only when visibility includes "model", and let the app call it only when it includes "app".`,
121
+ ...(one && problems.length === 1 ? {} : { detail: problems.map((p) => `${p.tool}: ${p.why}`) }),
122
+ fix: 'Set _meta.ui.visibility to ["model", "app"] (the default when it is left out), ["model"], or ["app"] for a tool only the app calls.',
123
+ },
124
+ ];
125
+ },
126
+ };
127
+ /**
128
+ * App-only tools listed to a client that didn't declare MCP Apps. Such a client doesn't
129
+ * read _meta.ui, so it puts them in its agent's list: tools meant to be called by an
130
+ * app's UI, offered to the agent. ext-apps: "Servers SHOULD check client capabilities
131
+ * before registering UI-enabled tools".
132
+ */
133
+ export const appsAppOnlyListed = {
134
+ id: 'apps/app-only-listed',
135
+ severity: 'warn',
136
+ summary: 'App-only tools are listed only to clients that declare MCP Apps',
137
+ run(ctx) {
138
+ const plain = ctx.plain?.tools;
139
+ if (!plain)
140
+ return [];
141
+ // Marked for the app: a visibility that names neither is apps/visibility's.
142
+ const leaked = kept(plain.filter((t) => isAppOnly(t) && (uiMeta(t)?.visibility).includes('app')), ctx);
143
+ if (!leaked.length)
144
+ return [];
145
+ const one = leaked.length === 1;
146
+ const list = leaked.map((t) => t.name);
147
+ return [
148
+ {
149
+ ...(one ? { tool: list[0] } : {}),
150
+ message: `${one ? `${list[0]} is` : `${names(list, 6)} are`} marked for the app only (_meta.ui.visibility without "model"), yet listed to a client that doesn't declare MCP Apps too. That client doesn't read _meta.ui, so its agent is offered ${one ? 'a tool' : 'tools'} meant for an app's UI.`,
151
+ ...(one ? {} : { detail: [list.join(', ')] }),
152
+ fix: `List ${one ? 'it' : 'them'} only when the client declares the io.modelcontextprotocol/ui extension (ext-apps' getUiCapability), as the spec asks servers to.`,
153
+ },
154
+ ];
155
+ },
156
+ };
@@ -0,0 +1,21 @@
1
+ import { type Rule } from './rule.js';
2
+ import type { MenuTool } from '../types.js';
3
+ /**
4
+ * snapshot lists the menu as a client that supports elicitation and MCP Apps, and once
5
+ * more as one that declares neither. A server may list a tool only to clients that can
6
+ * ask the user to confirm (github-mcp-server 1.14's delete_repository), or register
7
+ * other tools, or other variants of them, for a host that renders apps (ext-apps:
8
+ * "Servers MAY register different tool variants based on host capabilities"). Allowed;
9
+ * worth knowing, because a client without the capability never sees those tools, and a
10
+ * baseline made without it misses them. When the two differ, a third listing with
11
+ * elicitation alone tells which capability each tool depends on.
12
+ */
13
+ export interface PlainMenu {
14
+ tools?: MenuTool[];
15
+ error?: string;
16
+ /** Listed with elicitation and without MCP Apps: set only when `tools` differs from the main menu. */
17
+ elicitationOnly?: MenuTool[];
18
+ }
19
+ /** Whether the rule has anything to say about these two listings: snapshot lists a third time only then. */
20
+ export declare function listingsDiffer(main: MenuTool[], bare: MenuTool[]): boolean;
21
+ export declare const capabilityDependent: Rule;
@@ -0,0 +1,103 @@
1
+ import { names } from './rule.js';
2
+ import { isAppOnly } from '../apps.js';
3
+ const CAN = {
4
+ elicitation: 'supports elicitation (can ask the user to confirm)',
5
+ apps: 'renders MCP Apps (declares io.modelcontextprotocol/ui)',
6
+ either: 'supports elicitation and MCP Apps',
7
+ };
8
+ const CANNOT = {
9
+ elicitation: "doesn't support elicitation",
10
+ apps: "doesn't render MCP Apps",
11
+ either: 'supports neither elicitation nor MCP Apps',
12
+ };
13
+ const WITHOUT = {
14
+ elicitation: 'A client without elicitation',
15
+ apps: 'A client without MCP Apps',
16
+ either: 'A client with neither',
17
+ };
18
+ /** A tool's definition without toolmenu's token estimate. */
19
+ const definition = (t) => {
20
+ const { tokens: _tokens, ...rest } = t;
21
+ return JSON.stringify(rest);
22
+ };
23
+ /**
24
+ * What the rule compares, between the main listing and a bare one: tools listed only
25
+ * in the main one (app-only tools left out: listing those only to Apps hosts is what
26
+ * ext-apps asks for), only in the bare one, and same-name tools defined otherwise.
27
+ */
28
+ function compareListings(main, bare) {
29
+ const theirs = new Map(bare.map((t) => [t.name, t]));
30
+ const mine = new Map(main.map((t) => [t.name, t]));
31
+ return {
32
+ theirs,
33
+ mine,
34
+ only: [...mine.keys()].filter((n) => !theirs.has(n) && !isAppOnly(mine.get(n))),
35
+ without: [...theirs.keys()].filter((n) => !mine.has(n)),
36
+ variants: [...mine.keys()].filter((n) => theirs.has(n) && definition(mine.get(n)) !== definition(theirs.get(n))),
37
+ };
38
+ }
39
+ /** Whether the rule has anything to say about these two listings: snapshot lists a third time only then. */
40
+ export function listingsDiffer(main, bare) {
41
+ const { only, without, variants } = compareListings(main, bare);
42
+ return only.length + without.length + variants.length > 0;
43
+ }
44
+ export const capabilityDependent = {
45
+ id: 'menu/capability-dependent',
46
+ severity: 'info',
47
+ summary: 'The tools a client sees depend on whether it supports elicitation or MCP Apps',
48
+ run(ctx) {
49
+ const plain = ctx.plain?.tools;
50
+ if (!plain)
51
+ return [];
52
+ const middle = ctx.plain?.elicitationOnly;
53
+ const { mine, only, without, variants } = compareListings(ctx.menu.tools, plain);
54
+ const halfway = middle ? new Map(middle.map((t) => [t.name, t])) : undefined;
55
+ // Which capability brings a tool, or its variant: the one elicitation alone doesn't.
56
+ const cause = (name, same) => (!halfway ? 'either' : same(halfway.get(name)) ? 'elicitation' : 'apps');
57
+ if (!only.length && !without.length && !variants.length)
58
+ return [];
59
+ const byCause = new Map();
60
+ for (const n of only) {
61
+ const c = cause(n, (m) => m !== undefined);
62
+ byCause.set(c, [...(byCause.get(c) ?? []), n]);
63
+ }
64
+ // A tool that goes away for a capable client (Supabase drops its cost-confirming tools
65
+ // when it can ask the user instead): the capability whose listing lacks it.
66
+ const withoutCause = new Map();
67
+ for (const n of without) {
68
+ const c = !halfway ? 'either' : halfway.has(n) ? 'apps' : 'elicitation';
69
+ withoutCause.set(c, [...(withoutCause.get(c) ?? []), n]);
70
+ }
71
+ const variantCause = new Map();
72
+ for (const n of variants) {
73
+ const c = cause(n, (m) => m !== undefined && definition(m) === definition(mine.get(n)));
74
+ variantCause.set(c, [...(variantCause.get(c) ?? []), n]);
75
+ }
76
+ const causes = new Set([...byCause.keys(), ...withoutCause.keys(), ...variantCause.keys()]);
77
+ const overall = causes.size === 1 ? [...causes][0] : 'either';
78
+ const parts = [];
79
+ for (const [c, ns] of byCause)
80
+ parts.push(`${names(ns, 10)} ${ns.length === 1 ? 'is' : 'are'} listed only to a client that ${CAN[c]}`);
81
+ for (const [c, ns] of withoutCause)
82
+ parts.push(`${names(ns, 10)} ${ns.length === 1 ? 'is' : 'are'} listed only to a client that ${CANNOT[c]}`);
83
+ for (const [c, ns] of variantCause)
84
+ parts.push(`${names(ns, 10)} ${ns.length === 1 ? 'is' : 'are'} listed with another definition to a client that ${CAN[c]}`);
85
+ const one = only.length + without.length + variants.length === 1;
86
+ const sentence = parts.join('; ');
87
+ const seen = only.length + variants.length;
88
+ const tail = seen > 0
89
+ ? `The menu file holds the menu of a client with both, so diff sees ${seen === 1 ? 'that tool' : 'those tools'} as such a client gets ${seen === 1 ? 'it' : 'them'}.`
90
+ : `The menu file holds the menu of a client with both, which doesn't have ${without.length === 1 ? 'it' : 'them'}, so diff doesn't see changes to ${without.length === 1 ? 'it' : 'them'}.`;
91
+ return [
92
+ {
93
+ rule: 'menu/capability-dependent',
94
+ severity: 'info',
95
+ ...(one ? { tool: only[0] ?? without[0] ?? variants[0] } : {}),
96
+ message: `${sentence}. ${WITHOUT[overall]} gets ${plain.length} ${plain.length === 1 ? 'tool' : 'tools'}${variants.length ? `, ${variants.length === 1 ? 'one' : 'some'} of them different` : ''}, not ${ctx.menu.tools.length}. ${tail}`,
97
+ fix: overall === 'apps'
98
+ ? 'Nothing to change if this is deliberate (a UI variant for Apps hosts). Keep a text-only variant that works without the UI, and say in the README which tools need an Apps host.'
99
+ : 'Nothing to change if this is deliberate (a destructive tool that asks the user first, a UI variant for Apps hosts). Say in the README which tools need which client capability, so users of other clients know why they are missing.',
100
+ },
101
+ ];
102
+ },
103
+ };
@@ -0,0 +1,7 @@
1
+ import { type Rule } from './rule.js';
2
+ /**
3
+ * The Server Card at `<url>/server-card`, against the live connection. A server without
4
+ * one is fine (cards are optional) and nothing is said. Name isn't compared: cards use
5
+ * registry names (io.github.upstash/context7), serverInfo a display name (Context7).
6
+ */
7
+ export declare const serverCard: Rule;
@@ -0,0 +1,65 @@
1
+ import { CARD_MEDIA_TYPE } from '../card.js';
2
+ import { resultValidator } from './spec.js';
3
+ import { clip } from './rule.js';
4
+ const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
5
+ const trim = (u) => u.replace(/\/+$/, '');
6
+ /**
7
+ * The Server Card at `<url>/server-card`, against the live connection. A server without
8
+ * one is fine (cards are optional) and nothing is said. Name isn't compared: cards use
9
+ * registry names (io.github.upstash/context7), serverInfo a display name (Context7).
10
+ */
11
+ export const serverCard = {
12
+ id: 'spec/server-card',
13
+ severity: 'warn',
14
+ summary: "The Server Card agrees with the live server: schema, version, protocol versions",
15
+ run(ctx) {
16
+ const read = ctx.serverCard;
17
+ if (!read || !isObject(read.card))
18
+ return [];
19
+ const card = read.card;
20
+ // Only a card says it is one: its media type, or the Server Card schema in $schema.
21
+ // A server that answers every path with JSON (an error object, a health check) has none.
22
+ const typed = !!read.contentType?.toLowerCase().startsWith(CARD_MEDIA_TYPE);
23
+ if (!typed && !(typeof card.$schema === 'string' && /server-card/i.test(card.$schema)))
24
+ return [];
25
+ const where = read.url;
26
+ const out = [];
27
+ const validate = resultValidator('server-card', 'ServerCard');
28
+ if (validate && !validate(card)) {
29
+ const errors = (validate.errors ?? []).slice(0, 5).map((e) => `${e.instancePath || '(the card)'} ${e.message ?? ''}`.trim());
30
+ out.push({
31
+ message: `The Server Card at ${where} doesn't match the Server Card schema, so clients that read cards before connecting may skip it or misread it: ${errors[0]}.`,
32
+ ...(errors.length > 1 ? { detail: errors } : {}),
33
+ fix: 'Fix the card against schema.json in modelcontextprotocol/ext-server-card.',
34
+ });
35
+ }
36
+ const contradictions = [];
37
+ const live = ctx.serverInfo?.version;
38
+ if (typeof card.version === 'string' && live && card.version !== live)
39
+ contradictions.push(`version: the card says ${clip(card.version, 60)}, the server ${clip(live, 60)}`);
40
+ // The remote for the URL this run connected to; its protocol versions against the one negotiated.
41
+ const remotes = Array.isArray(card.remotes) ? card.remotes.filter(isObject) : [];
42
+ const mine = ctx.serverUrl ? remotes.find((r) => typeof r.url === 'string' && trim(r.url) === trim(ctx.serverUrl)) : undefined;
43
+ const versions = Array.isArray(mine?.supportedProtocolVersions) ? mine.supportedProtocolVersions.filter((v) => typeof v === 'string') : undefined;
44
+ // Not when this connection fell back to 2025 and a later one got 2026-07-28: the
45
+ // negotiated version then isn't all the server speaks (spec/discover says why).
46
+ if (versions?.length && ctx.protocolVersion && !ctx.laterModern && !versions.includes(ctx.protocolVersion)) {
47
+ contradictions.push(`protocol: the card lists ${versions.join(', ')} for ${mine.url}, the server negotiated ${ctx.protocolVersion}`);
48
+ }
49
+ if (contradictions.length) {
50
+ out.push({
51
+ message: `The Server Card at ${where} contradicts the live server (${contradictions.join('; ')}). Clients read the card before connecting, so they pick or configure the server by values it doesn't have; ext-server-card says the card SHOULD NOT contradict server/discover and serverInfo.`,
52
+ ...(contradictions.length > 1 ? { detail: contradictions } : {}),
53
+ fix: 'Build the card from the same values the server reports (its package version, the protocol versions the SDK serves), or update it with each release.',
54
+ });
55
+ }
56
+ if (!typed) {
57
+ out.push({
58
+ severity: 'info',
59
+ message: `The Server Card at ${where} is served as ${read.contentType ? clip(read.contentType, 60) : 'no content type'}, not ${CARD_MEDIA_TYPE}, which ext-server-card says servers SHOULD use.`,
60
+ fix: `Serve it with Content-Type: ${CARD_MEDIA_TYPE}.`,
61
+ });
62
+ }
63
+ return out;
64
+ },
65
+ };
@@ -7,6 +7,7 @@ import { count, kept } from './rule.js';
7
7
  */
8
8
  export const clientName = {
9
9
  id: 'naming/client-name',
10
+ scope: 'agent',
10
11
  severity: 'warn',
11
12
  summary: "Tool names the client's API doesn't accept as they are",
12
13
  run(ctx) {
@@ -111,6 +111,7 @@ export function sentInFull(tool, patterns) {
111
111
  }
112
112
  export const buried = {
113
113
  id: 'description/buried',
114
+ scope: 'agent',
114
115
  severity: 'warn',
115
116
  lesson: 'truncated description',
116
117
  summary: 'Instructions to the agent sit past the point where your client cuts descriptions',
@@ -153,6 +154,7 @@ function aroundTheCut(text, at) {
153
154
  }
154
155
  export const cut = {
155
156
  id: 'description/cut',
157
+ scope: 'agent',
156
158
  severity: 'info',
157
159
  lesson: 'truncated description',
158
160
  summary: 'Descriptions longer than your client sends',
@@ -187,6 +189,7 @@ export const cut = {
187
189
  };
188
190
  export const lateInstruction = {
189
191
  id: 'description/late-instruction',
192
+ scope: 'agent',
190
193
  severity: 'info',
191
194
  lesson: 'truncated description',
192
195
  summary: 'Instructions to the agent that a client cutting descriptions short would hide',
@@ -6,8 +6,6 @@ export interface HeaderFault {
6
6
  /** The annotation's value, as written. */
7
7
  header: unknown;
8
8
  problem: string;
9
- /** The SDK client drops the tool for this (true), or only the spec forbids it (false: `number`). */
10
- dropped: boolean;
11
9
  }
12
10
  /** Every broken x-mcp-header annotation in a tool's input schema; empty when all are valid or there are none. */
13
11
  export declare function headerFaults(tool: MenuTool): HeaderFault[];