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,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,18 @@
1
+ import type { MenuTool } from '../types.js';
2
+ import { type Rule } from './rule.js';
3
+ /** What an HTTP server answered to the same listing with an invalid credential. */
4
+ export interface InvalidCredential {
5
+ /** It served a menu anyway. */
6
+ tools?: MenuTool[];
7
+ /** It refused with this HTTP status (401 or 403 is the answer a client can act on). */
8
+ status?: number;
9
+ /** It failed some other way. */
10
+ error?: string;
11
+ }
12
+ /**
13
+ * A credential that can't be valid, in place of the one this run used. A server that
14
+ * answers it with a menu, not 401, gives a client whose token expired or was revoked
15
+ * no reason to log in again: the agent just has fewer tools (Atlassian Rovo served 4
16
+ * of its tools to any Authorization header, 2026-11-03).
17
+ */
18
+ export declare const invalidCredential: Rule;
@@ -0,0 +1,29 @@
1
+ import { count, names, num } from './rule.js';
2
+ /**
3
+ * A credential that can't be valid, in place of the one this run used. A server that
4
+ * answers it with a menu, not 401, gives a client whose token expired or was revoked
5
+ * no reason to log in again: the agent just has fewer tools (Atlassian Rovo served 4
6
+ * of its tools to any Authorization header, 2026-11-03).
7
+ */
8
+ export const invalidCredential = {
9
+ id: 'auth/invalid-accepted',
10
+ severity: 'warn',
11
+ summary: 'An invalid credential gets an auth error, not a menu',
12
+ run(ctx) {
13
+ const probe = ctx.invalidCredential;
14
+ if (!probe?.tools)
15
+ return [];
16
+ const mine = ctx.menu.tools.map((t) => t.name);
17
+ const theirs = probe.tools.map((t) => t.name);
18
+ const same = theirs.length === mine.length && theirs.every((n) => mine.includes(n));
19
+ return [
20
+ {
21
+ message: same
22
+ ? `With an invalid credential in place of this run's, the server served the same ${count(theirs.length, 'tool')} instead of refusing (401). Listing doesn't check credentials, so a client learns its token expired or was revoked only when a call fails.`
23
+ : `With an invalid credential in place of this run's, the server served ${count(theirs.length, 'tool')} (of ${num(mine.length)} with it) instead of refusing (401). A client whose token expired or was revoked gets a smaller menu, not an auth error, so it has no reason to ask the user to log in again; the agent just has fewer tools.`,
24
+ detail: same ? [] : [`served to the invalid credential: ${names(theirs, 10)}`],
25
+ fix: "Answer a request whose credential doesn't verify with 401 and a WWW-Authenticate header, even for tools that need no login: a client re-authenticates on 401. If some tools are meant to work without a login, serve them to requests with no credential, not to ones with a bad credential.",
26
+ },
27
+ ];
28
+ },
29
+ };
@@ -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',
@@ -4,7 +4,20 @@ import { type Rule } from './rule.js';
4
4
  export interface HandleProbe {
5
5
  param: string;
6
6
  kind: string;
7
+ /**
8
+ * --create-handles: a creating tool runs first, and this call gets the handle it
9
+ * returned instead of a made-up one (the made-up one when it returned none).
10
+ */
11
+ fromCreated?: string;
7
12
  }
13
+ /** Kinds --create-handles may create: scratch state that expires. Not a lock, lease or checkout. */
14
+ export declare const CREATABLE_KINDS: Set<string>;
15
+ /** The tool that creates handles of this kind, if the menu has one. */
16
+ export declare function creatorOf(tools: MenuTool[], kind: string): MenuTool | undefined;
17
+ export declare function handleFromResult(result: {
18
+ structuredContent?: unknown;
19
+ content?: unknown;
20
+ }, kind: string): string | undefined;
8
21
  /** The handle kinds some tool in the menu creates. */
9
22
  export declare function createdKinds(tools: MenuTool[]): Set<string>;
10
23
  /** Parameters of a tool that take a handle of this kind: session_id, cartToken, `session`. */
@@ -30,6 +30,84 @@ function createdKind(tool) {
30
30
  return undefined;
31
31
  return w.slice(1).find((x) => HANDLE_KINDS.has(x));
32
32
  }
33
+ /** Kinds --create-handles may create: scratch state that expires. Not a lock, lease or checkout. */
34
+ export const CREATABLE_KINDS = new Set(['session', 'basket', 'cart']);
35
+ /** The tool that creates handles of this kind, if the menu has one. */
36
+ export function creatorOf(tools, kind) {
37
+ return tools.find((t) => createdKind(t) === kind);
38
+ }
39
+ /**
40
+ * The handle a creating tool's result carries: a `<kind>_id` / `<kind>Id` / `id` in its
41
+ * structured content, in JSON text, or written out ("session_id: s-1").
42
+ */
43
+ const WRAPPERS = new Set(['data', 'result', 'results', 'item', 'response']);
44
+ export function handleFromResult(result, kind) {
45
+ // Compared without case, dashes or underscores: session_id, sessionId and session-id are one key.
46
+ const norm = (k) => k.toLowerCase().replace(/[-_\s]/g, '');
47
+ const own = new Set([`${kind}id`, kind, `${kind}handle`, `${kind}token`]);
48
+ const scalar = (x) => (typeof x === 'string' && x ? x : typeof x === 'number' ? String(x) : undefined);
49
+ // The kind's own key anywhere (breadth first, so the shallowest wins); a bare id or
50
+ // handle only at the top, where it names what was created, not a nested user or request.
51
+ const find = (root) => {
52
+ let level = [root];
53
+ for (let depth = 0; depth <= 3 && level.length; depth++) {
54
+ const next = [];
55
+ for (const v of level) {
56
+ if (!v || typeof v !== 'object')
57
+ continue;
58
+ for (const [k, x] of Object.entries(v)) {
59
+ const found = own.has(norm(k)) ? scalar(x) : undefined;
60
+ if (found)
61
+ return found;
62
+ if (x && typeof x === 'object')
63
+ next.push(x);
64
+ }
65
+ }
66
+ level = next;
67
+ }
68
+ // At the top, or right under a wrapper ({"data":{"id":…}}), never under another thing's key (user.id).
69
+ const bare = (v, inWrapper = false) => {
70
+ // Under a wrapper, a one-item list is the item ({"data":[{"id":…}]}); a longer one, or
71
+ // a list at the top, names no single handle.
72
+ const one = Array.isArray(v) ? (inWrapper && v.length === 1 ? v[0] : undefined) : v;
73
+ if (!one || typeof one !== 'object' || Array.isArray(one))
74
+ return undefined;
75
+ for (const [k, x] of Object.entries(one)) {
76
+ const found = norm(k) === 'id' || norm(k) === 'handle' ? scalar(x) : undefined;
77
+ if (found)
78
+ return found;
79
+ }
80
+ return undefined;
81
+ };
82
+ const top = bare(root);
83
+ if (top || !root || typeof root !== 'object' || Array.isArray(root))
84
+ return top;
85
+ for (const [k, x] of Object.entries(root)) {
86
+ const found = WRAPPERS.has(norm(k)) || norm(k) === kind ? bare(x, true) : undefined;
87
+ if (found)
88
+ return found;
89
+ }
90
+ return undefined;
91
+ };
92
+ const structured = find(result.structuredContent);
93
+ if (structured)
94
+ return structured;
95
+ const texts = Array.isArray(result.content) ? result.content.filter((c) => c.type === 'text' && c.text).map((c) => c.text) : [];
96
+ for (const t of texts) {
97
+ try {
98
+ const r = find(JSON.parse(t));
99
+ if (r)
100
+ return r;
101
+ }
102
+ catch {
103
+ // not JSON: look for "session_id: s-1" written out
104
+ }
105
+ const m = new RegExp(`\\b${kind}[_ -]?(?:id|handle|token)\\b["']?\\s*[:=]\\s*["']?([\\w.:-]+)`, 'i').exec(t);
106
+ if (m)
107
+ return m[1];
108
+ }
109
+ return undefined;
110
+ }
33
111
  /** The handle kinds some tool in the menu creates. */
34
112
  export function createdKinds(tools) {
35
113
  return new Set(tools.map(createdKind).filter((k) => !!k));
package/dist/rules/ids.js CHANGED
@@ -61,6 +61,9 @@ export function idParams(tool) {
61
61
  // A qualifier alone (`parentId`, `targetId`) says how it relates, not what it is.
62
62
  if (kindWords.length === 1 && QUALIFIERS.has(kindWords[0]))
63
63
  kindWords.length = 0;
64
+ // A GraphQL node ID is the thing's own ID: commentNodeID is a comment's (GitHub).
65
+ if (kindWords.length > 1 && kindWords.at(-1) === 'node')
66
+ kindWords.pop();
64
67
  const prefix = kindWords.join('_');
65
68
  // A bare `id` doesn't say what it identifies (naming/vague-id covers that), so no kind is guessed.
66
69
  params.push({ param, kind: prefix || undefined });
@@ -73,6 +76,30 @@ function looksLikeIdValue(schema) {
73
76
  const type = schema.type;
74
77
  return type === undefined || type === 'string' || type === 'integer' || (Array.isArray(type) && type.includes('string'));
75
78
  }
79
+ /**
80
+ * A tool's operations, when an enum lists them under their own names: a router such as
81
+ * github-mcp-server's actions_list { method: list_workflows | list_workflow_runs } lists
82
+ * workflows as surely as a list_workflows tool would. Each value that reads as a list
83
+ * or search (list_project_views) counts as a tool of that name, with the router's parameters.
84
+ */
85
+ /** Marks a tool made from an enum value: it counts only when its name says the kind. */
86
+ const OPERATION = Symbol('operation');
87
+ function withOperations(tools) {
88
+ const out = [...tools];
89
+ for (const t of tools) {
90
+ for (const schema of Object.values(t.inputSchema?.properties ?? {})) {
91
+ for (const v of Array.isArray(schema.enum) ? schema.enum : []) {
92
+ if (typeof v !== 'string' || !/^[a-z]+(?:_[a-z]+)+$/.test(v))
93
+ continue;
94
+ // Lists and searches only: a router's get_workflow needs the ID it would hand out.
95
+ if (!COLLECTION_VERBS.has(singular(v.split('_')[0])))
96
+ continue;
97
+ out.push({ ...t, name: v, outputSchema: undefined, [OPERATION]: true });
98
+ }
99
+ }
100
+ }
101
+ return out;
102
+ }
76
103
  /** Does some other tool look like it hands out IDs of this kind? */
77
104
  function isReturnedBySomeTool(kind, self, tools, common) {
78
105
  return tools.some((other) => {
@@ -86,6 +113,11 @@ function isReturnedBySomeTool(kind, self, tools, common) {
86
113
  const lookup = verbs.some((v) => LOOKUP_VERBS.has(v));
87
114
  const collection = verbs.some((v) => COLLECTION_VERBS.has(v)) || w.includes('children');
88
115
  const needsSameId = idParams(other).some((p) => p.kind === kind);
116
+ // An operation from an enum counts only when it names the kind (list_workflows):
117
+ // sapiens' action: list_public or list_mine says nothing about which IDs it lists.
118
+ // And after its verb: list_public lists no "list" IDs.
119
+ if (other[OPERATION])
120
+ return lookup && `_${w.slice(1).join('_')}_`.includes(`_${kind}_`) && !needsSameId;
89
121
  // A list or search for that kind; a get that doesn't itself need the ID.
90
122
  if (lookup && mentionsKind && (collection || !needsSameId))
91
123
  return true;
@@ -115,6 +147,7 @@ function outputMentions(schema, kind, depth = 0, parent = '') {
115
147
  }
116
148
  export const authoredIds = {
117
149
  id: 'ids/authored',
150
+ scope: 'agent',
118
151
  // A heuristic: IDs that only appear in another tool's text output look the same
119
152
  // as invented ones from the schema alone (FINDINGS F12).
120
153
  severity: 'info',
@@ -123,9 +156,10 @@ export const authoredIds = {
123
156
  run(ctx) {
124
157
  const byKind = new Map();
125
158
  const common = commonWords(ctx.menu.tools.map((t) => t.name));
159
+ const operations = withOperations(ctx.menu.tools);
126
160
  for (const tool of kept(ctx.menu.tools, ctx)) {
127
161
  for (const { param, kind } of idParams(tool)) {
128
- if (!kind || isReturnedBySomeTool(kind, tool, ctx.menu.tools, common))
162
+ if (!kind || isReturnedBySomeTool(kind, tool, operations, common))
129
163
  continue;
130
164
  const schema = tool.inputSchema?.properties?.[param];
131
165
  if (saysWhereItComesFrom(schema, ctx.menu.tools, tool.name))