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
package/dist/snapshot.js CHANGED
@@ -2,8 +2,13 @@ import { listTools } from './connect.js';
2
2
  import { patiently, tooMany } from './failures.js';
3
3
  import { ConnectError } from './explain.js';
4
4
  import { buildMenu } from './menu.js';
5
- import { asIdentity, connectPatiently, isContainerWrapper, MAIN_SEED, PROBE_SEED, probeMenu, probeVariance, seeded } from './probe.js';
5
+ import { asIdentity, connectPatiently, isContainerWrapper, MAIN_SEED, PROBE_SEED, probeMenu, probeSameEra, probeVariance, seeded } from './probe.js';
6
6
  import { kindsToRead, readList } from './lists.js';
7
+ import { agentMenu, readAppResources, resourceUriOf } from './apps.js';
8
+ import { readServerCard } from './card.js';
9
+ import { listingsDiffer } from './rules/capabilities.js';
10
+ import { isCredentialHeader } from './explain.js';
11
+ import { httpStatus } from './failures.js';
7
12
  import { clientCost } from './clients.js';
8
13
  import { MENU_RULES, runRules } from './rules/index.js';
9
14
  import { catalogFindings, readCatalog } from './catalog.js';
@@ -12,7 +17,11 @@ import { shellWord } from './init.js';
12
17
  /** Establish the menu: connect, list the tools twice, run the menu rules. */
13
18
  export async function snapshot(given, options = {}) {
14
19
  const [mainIdentity, ...otherIdentities] = options.identities ?? [];
15
- const target = asIdentity(given, mainIdentity);
20
+ // Listed as a client that can be asked things (elicitation, answered "decline"; no tool
21
+ // is called, so none is asked): a server may list some tools only to such clients, and
22
+ // the baseline should hold every tool some client sees. One more listing without it
23
+ // says what a client without elicitation gets (rules/capabilities.ts).
24
+ const target = withElicitation(asIdentity(given, mainIdentity));
16
25
  // Connecting and listing are read-only: a refusal for being too many is waited
17
26
  // out and they're sent again (CI behind a shared rate limit).
18
27
  const connection = await connectPatiently(seeded(target, MAIN_SEED), { timeoutMs: options.timeoutMs });
@@ -21,6 +30,7 @@ export async function snapshot(given, options = {}) {
21
30
  let first;
22
31
  const reads = [];
23
32
  let undeclared = [];
33
+ let appResources;
24
34
  try {
25
35
  first = await patiently(() => listTools(connection, options), { error: tooMany });
26
36
  const second = await patiently(() => listTools(connection, options), { error: tooMany });
@@ -29,6 +39,7 @@ export async function snapshot(given, options = {}) {
29
39
  version: connection.server.version,
30
40
  protocolVersion: connection.protocolVersion,
31
41
  era: connection.era,
42
+ extensions: declaredExtensions(connection.capabilities),
32
43
  };
33
44
  menu = buildMenu(first.tools, server, first.listMeta);
34
45
  secondList = buildMenu(second.tools, server, second.listMeta).tools;
@@ -42,6 +53,11 @@ export async function snapshot(given, options = {}) {
42
53
  if (!first.error)
43
54
  menu[kind] = first.items;
44
55
  }
56
+ // MCP Apps: each ui:// resource a tool names, read as a host would before rendering
57
+ // it (apps/resource). A read, not a tool call.
58
+ if (options.rules?.['apps/resource'] !== 'off' && menu.tools.some((t) => resourceUriOf(t)?.startsWith('ui://'))) {
59
+ appResources = await readAppResources(connection, menu.tools, options.timeoutMs);
60
+ }
45
61
  if (options.catalog) {
46
62
  menu.catalog = await readCatalog(connection, menu.tools, { ...(typeof options.catalog === 'object' ? options.catalog : {}), timeoutMs: options.timeoutMs });
47
63
  }
@@ -58,7 +74,9 @@ export async function snapshot(given, options = {}) {
58
74
  }
59
75
  // After the main process has exited: a server that holds a file or a port
60
76
  // shouldn't have to share it with its own probe.
61
- const probes = await probeVariance(target, menu.tools, options.processes ?? 2, options.timeoutMs ?? 30_000);
77
+ // Eras later processes negotiated, before any retry on the main one's (spec/discover).
78
+ const eras = new Set();
79
+ const probes = await probeVariance(target, menu.tools, options.processes ?? 2, options.timeoutMs ?? 30_000, undefined, connection.era, eras);
62
80
  // The other lists from a second process (stdio) or connection (HTTP), as tools get.
63
81
  if ((options.processes ?? 2) > 1 && reads.some((r) => !r.first.error)) {
64
82
  try {
@@ -76,13 +94,42 @@ export async function snapshot(given, options = {}) {
76
94
  // The tool probe above says why a second process or connection failed.
77
95
  }
78
96
  }
97
+ // A credential that can't be valid, in place of the one this run used (HTTP): the
98
+ // server should refuse it, not serve a menu (rules/auth.ts).
99
+ const invalid = target.kind === 'http' && connection.usedAuth && (options.processes ?? 2) > 1 ? await invalidCredentialProbe(target, options.timeoutMs ?? 30_000) : undefined;
100
+ // The Server Card at its reserved location, compared with the live server (rules/card.ts).
101
+ const card = target.kind === 'http' && options.rules?.['spec/server-card'] !== 'off' ? await readServerCard(target.url, Math.min(options.timeoutMs ?? 30_000, 10_000)) : undefined;
102
+ // The menu a client without elicitation gets (rules/capabilities.ts).
103
+ // Another process or connection: not with --processes 1 (one session per client), nor when the rule is off.
104
+ let plain;
105
+ if ((options.processes ?? 2) > 1 && options.rules?.['menu/capability-dependent'] !== 'off') {
106
+ try {
107
+ plain = { tools: (await probeSameEra(seeded({ ...target, elicitation: undefined, apps: undefined }, MAIN_SEED), connection.era, options.timeoutMs ?? 30_000, undefined, undefined, eras)).tools };
108
+ }
109
+ catch (error) {
110
+ plain = { error: firstLine(error) };
111
+ }
112
+ // The menus differ: once more with elicitation alone, to tell which capability a tool
113
+ // depends on (MCP Apps or elicitation). Only then: it's one more process or connection.
114
+ if (plain.tools && listingsDiffer(menu.tools, plain.tools)) {
115
+ try {
116
+ plain.elicitationOnly = (await probeSameEra(seeded({ ...target, apps: undefined }, MAIN_SEED), connection.era, options.timeoutMs ?? 30_000, undefined, undefined, eras)).tools;
117
+ }
118
+ catch {
119
+ // Not attributed: the finding names both capabilities.
120
+ }
121
+ }
122
+ }
123
+ // --offline-check: one more process with the network cut off (rules/network.ts).
124
+ // Not run when the rule is off: it's a whole server start.
125
+ const offline = options.offlineCheck && target.kind === 'stdio' && options.rules?.['menu/network-dependent'] !== 'off' ? (isContainerWrapper(target) ? { wrapper: true } : await offlineProbe(target, options.timeoutMs ?? 30_000)) : undefined;
79
126
  // Each other identity's menu, from its own process (stdio) or connection (HTTP).
80
127
  const identities = mainIdentity
81
128
  ? [{ name: mainIdentity.name, tools: menu.tools, tokens: menu.totalTokens, cacheScope: menu.listMeta?.cacheScope }]
82
129
  : undefined;
83
130
  for (const identity of otherIdentities) {
84
131
  try {
85
- const m = await probeMenu(seeded(asIdentity(given, identity), MAIN_SEED), options.timeoutMs ?? 30_000);
132
+ const m = await probeMenu(seeded(withElicitation(asIdentity(given, identity)), MAIN_SEED), options.timeoutMs ?? 30_000);
86
133
  identities.push({ name: identity.name, tools: m.tools, tokens: m.totalTokens, cacheScope: m.listMeta?.cacheScope });
87
134
  }
88
135
  catch (error) {
@@ -110,6 +157,13 @@ export async function snapshot(given, options = {}) {
110
157
  serverInfo: connection.server,
111
158
  server: serverArgs(target),
112
159
  identities,
160
+ ...(invalid ? { invalidCredential: invalid } : {}),
161
+ ...(offline ? { offline } : {}),
162
+ ...(plain ? { plain } : {}),
163
+ ...(appResources ? { appResources } : {}),
164
+ ...(card ? { serverCard: card } : {}),
165
+ ...(target.kind === 'http' ? { serverUrl: new URL(target.url).origin + new URL(target.url).pathname } : {}),
166
+ ...(connection.era === 'legacy' && eras.has('modern') ? { laterModern: true } : {}),
113
167
  ...(reads.length || undeclared.length ? { lists: { read: reads, undeclared } } : {}),
114
168
  }, options);
115
169
  // What --catalog called and what it got, under the same settings as the rules
@@ -124,9 +178,80 @@ export async function snapshot(given, options = {}) {
124
178
  }
125
179
  findings.sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]);
126
180
  }
127
- const cost = options.client ? clientCost(options.client, menu) : undefined;
181
+ // What the agent pays: app-only tools aren't in its list.
182
+ const cost = options.client ? clientCost(options.client, agentMenu(menu).shown) : undefined;
128
183
  return { menu, findings, ...(identities ? { identities } : {}), ...(cost ? { cost } : {}), ...(undeclared.length ? { notOffered: undeclared } : {}) };
129
184
  }
185
+ /**
186
+ * The target with every credential it carries swapped for one that can't be valid,
187
+ * same scheme: Bearer stays Bearer, Basic gets a made-up user and password, an API-key
188
+ * header a made-up key. A stored login (OAuth) becomes an invalid Bearer token.
189
+ */
190
+ export function withInvalidCredential(target) {
191
+ const headers = {};
192
+ let replaced = false;
193
+ for (const [k, v] of Object.entries(target.headers ?? {})) {
194
+ if (k.toLowerCase() === 'authorization') {
195
+ const scheme = /^\s*(\w+)\s/.exec(v)?.[1] ?? 'Bearer';
196
+ headers[k] = /^basic$/i.test(scheme) ? `Basic ${Buffer.from('toolmenu-invalid:toolmenu-invalid').toString('base64')}` : `${scheme} toolmenu-invalid-credential`;
197
+ replaced = true;
198
+ }
199
+ else if (isCredentialHeader(k)) {
200
+ headers[k] = 'toolmenu-invalid-credential';
201
+ replaced = true;
202
+ }
203
+ else
204
+ headers[k] = v;
205
+ }
206
+ if (!replaced)
207
+ headers.Authorization = 'Bearer toolmenu-invalid-credential';
208
+ return { ...target, headers, noAuth: true };
209
+ }
210
+ /**
211
+ * The proxy variables pointed at a port nothing listens on (the discard port): every
212
+ * client that honours them (Python requests and httpx, Go, curl, Node's fetch with
213
+ * NODE_USE_ENV_PROXY on 22.21+) fails to connect at once. Loopback stays exempt: a
214
+ * server's own local helper (TabRunner's bridge on 127.0.0.1) isn't the network.
215
+ * These win over --env: a proxy given there would undo the cut.
216
+ */
217
+ const LOOPBACK = 'localhost,127.0.0.1,::1';
218
+ export function offlineEnvironment() {
219
+ const dead = 'http://127.0.0.1:9';
220
+ return { HTTPS_PROXY: dead, https_proxy: dead, HTTP_PROXY: dead, http_proxy: dead, ALL_PROXY: dead, all_proxy: dead, NO_PROXY: LOOPBACK, no_proxy: LOOPBACK, NODE_USE_ENV_PROXY: '1' };
221
+ }
222
+ async function offlineProbe(target, timeoutMs) {
223
+ const launcher = /(?:^|[\\/])(?:npx|uvx|bunx|pnpx|pipx)(?:\.cmd|\.exe)?$/.test(target.command) || (/(?:^|[\\/])(?:pnpm|yarn|npm|bun)(?:\.cmd|\.exe)?$/.test(target.command) && /^(?:dlx|exec|x)$/.test(target.args[0] ?? ''));
224
+ try {
225
+ const m = await probeMenu(seeded({ ...target, env: { ...target.env, ...offlineEnvironment() } }, MAIN_SEED), timeoutMs);
226
+ return { tools: m.tools };
227
+ }
228
+ catch (error) {
229
+ const e = error instanceof ConnectError ? error.headline : firstLine(error);
230
+ return { error: e.replace(/\.$/, ''), ...(launcher ? { launcher } : {}) };
231
+ }
232
+ }
233
+ async function invalidCredentialProbe(target, timeoutMs) {
234
+ try {
235
+ const m = await probeMenu(withInvalidCredential(target), timeoutMs);
236
+ return { tools: m.tools };
237
+ }
238
+ catch (error) {
239
+ const status = httpStatus(error);
240
+ return status !== undefined ? { status } : { error: firstLine(error) };
241
+ }
242
+ }
243
+ /**
244
+ * The target, listed as a client that supports elicitation (answered "decline" if ever
245
+ * asked) and renders MCP Apps: the client that sees every tool some client sees.
246
+ */
247
+ function withElicitation(t) {
248
+ return { ...t, elicitation: t.elicitation ?? 'decline', apps: true };
249
+ }
250
+ /** capabilities.extensions as the server sent it: identifier → settings, {} for none. */
251
+ export function declaredExtensions(capabilities) {
252
+ const e = capabilities.extensions;
253
+ return typeof e === 'object' && e !== null && !Array.isArray(e) ? { ...e } : {};
254
+ }
130
255
  const firstLine = (error) => (error instanceof Error ? error.message : String(error)).split('\n')[0].trim();
131
256
  /**
132
257
  * How this run reached the server, as the end of a command line, for next steps:
package/dist/types.d.ts CHANGED
@@ -53,6 +53,11 @@ export interface Menu {
53
53
  version?: string;
54
54
  protocolVersion?: string;
55
55
  era?: Era;
56
+ /**
57
+ * The extensions the server declares (capabilities.extensions: identifier → settings),
58
+ * {} for none. Absent in menu files from before 0.23, so diff can't tell those apart.
59
+ */
60
+ extensions?: Record<string, unknown>;
56
61
  };
57
62
  capturedAt: string;
58
63
  /** In server order. Order is the point. */
package/dist/words.d.ts CHANGED
@@ -13,6 +13,14 @@ export declare const WRITE_VERBS: Set<string>;
13
13
  export declare function article(word: string): 'a' | 'an';
14
14
  /** Words most of a server's tool names share (`firecrawl_`, `API-`, `browser_`): no information. */
15
15
  export declare function commonWords(names: string[]): Set<string>;
16
+ /**
17
+ * Words a name's leading verb is read after: those most of the menu's names share
18
+ * (commonWords), and a namespace prefix: a word, not a verb, that opens 3 or more
19
+ * names and is followed by a verb in 3 or more of them. kubectl_create leads with
20
+ * "create" although kubectl opens 10 of 23 names, under the 60% that makes it common.
21
+ * percent_change keeps "percent": a prefix of one or two names is not a namespace.
22
+ */
23
+ export declare function prefixWords(names: string[]): Set<string>;
16
24
  /** The tool's verb: the first word that is one, skipping prefixes like `API-`. */
17
25
  export declare function verbOf(name: string): string | undefined;
18
26
  /**
@@ -23,3 +31,5 @@ export declare function verbOf(name: string): string | undefined;
23
31
  export declare function leadingVerb(name: string, common?: Set<string>): string | undefined;
24
32
  /** The nouns in a tool name, singular: `list_team_audits` → team, audit. */
25
33
  export declare function nouns(name: string): string[];
34
+ /** Levenshtein distance: edits that turn one string into the other. */
35
+ export declare function editDistance(a: string, b: string): number;
package/dist/words.js CHANGED
@@ -64,6 +64,27 @@ export function commonWords(names) {
64
64
  counts.set(w, (counts.get(w) ?? 0) + 1);
65
65
  return new Set([...counts].filter(([, n]) => names.length >= 4 && n >= names.length * 0.6).map(([w]) => w));
66
66
  }
67
+ /**
68
+ * Words a name's leading verb is read after: those most of the menu's names share
69
+ * (commonWords), and a namespace prefix: a word, not a verb, that opens 3 or more
70
+ * names and is followed by a verb in 3 or more of them. kubectl_create leads with
71
+ * "create" although kubectl opens 10 of 23 names, under the 60% that makes it common.
72
+ * percent_change keeps "percent": a prefix of one or two names is not a namespace.
73
+ */
74
+ export function prefixWords(names) {
75
+ const out = commonWords(names);
76
+ const opened = new Map();
77
+ for (const name of names) {
78
+ const [first, second] = words(name);
79
+ if (first === undefined || VERBS.has(first) || second === undefined || !VERBS.has(second))
80
+ continue;
81
+ opened.set(first, (opened.get(first) ?? 0) + 1);
82
+ }
83
+ for (const [w, n] of opened)
84
+ if (n >= 3)
85
+ out.add(w);
86
+ return out;
87
+ }
67
88
  /** The tool's verb: the first word that is one, skipping prefixes like `API-`. */
68
89
  export function verbOf(name) {
69
90
  return words(name).find((w) => VERBS.has(w));
@@ -74,9 +95,16 @@ export function verbOf(name) {
74
95
  * in its object (score_status_update scores; "update" is what it scores).
75
96
  */
76
97
  export function leadingVerb(name, common = new Set()) {
77
- const first = words(name).find((w) => !common.has(w));
78
- return first !== undefined && VERBS.has(first) ? first : undefined;
98
+ const rest = words(name).filter((w, i, all) => all.slice(0, i + 1).some((x) => !common.has(x)));
99
+ const [first, second] = rest;
100
+ if (first !== undefined && VERBS.has(first))
101
+ return first;
102
+ // Object first, then the verb (browserbase_session_create, session_close): only a word
103
+ // that can't be read as a noun, so percent_change still computes a change.
104
+ return first !== undefined && second !== undefined && ONLY_VERBS.has(second) ? second : undefined;
79
105
  }
106
+ /** Verbs that aren't also nouns in tool names: not change, update, set, post, patch, copy or plan. */
107
+ const ONLY_VERBS = new Set(['create', 'add', 'insert', 'upsert', 'modify', 'delete', 'remove', 'purge', 'destroy', 'revoke', 'cancel', 'close', 'send', 'publish', 'submit', 'upload', 'rename', 'assign', 'invite', 'approve', 'get', 'list', 'fetch', 'retrieve', 'describe']);
80
108
  /** The nouns in a tool name, singular: `list_team_audits` → team, audit. */
81
109
  export function nouns(name) {
82
110
  return words(name)
@@ -84,3 +112,17 @@ export function nouns(name) {
84
112
  .map(singular)
85
113
  .filter((w) => !GENERIC.has(w));
86
114
  }
115
+ /** Levenshtein distance: edits that turn one string into the other. */
116
+ export function editDistance(a, b) {
117
+ const row = Array.from({ length: b.length + 1 }, (_, i) => i);
118
+ for (let i = 1; i <= a.length; i++) {
119
+ let diagonal = row[0];
120
+ row[0] = i;
121
+ for (let j = 1; j <= b.length; j++) {
122
+ const above = row[j];
123
+ row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
124
+ diagonal = above;
125
+ }
126
+ }
127
+ return row[b.length];
128
+ }
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "toolmenu",
3
- "version": "0.20.1",
3
+ "version": "0.23.0",
4
4
  "description": "Lint your MCP server's tool menu for changes that confuse agents or break caches.",
5
5
  "author": "Nikša Perović (https://niksa.me)",
6
6
  "main": "dist/index.js",
7
7
  "scripts": {
8
- "build": "tsc -p tsconfig.json",
8
+ "build": "tsc -p tsconfig.json && node scripts/rule-docs.mjs",
9
9
  "test": "npm run build && node --test --test-reporter=spec test/*.test.mjs",
10
10
  "typecheck": "tsc -p tsconfig.json --noEmit",
11
11
  "prepublishOnly": "npm run build"
@@ -0,0 +1,260 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$defs": {
4
+ "Icon": {
5
+ "description": "An optionally-sized icon that can be displayed in a user interface.",
6
+ "properties": {
7
+ "mimeType": {
8
+ "description": "Optional MIME type override if the source MIME type is missing or generic.\nFor example: `\"image/png\"`, `\"image/jpeg\"`, or `\"image/svg+xml\"`.",
9
+ "type": "string"
10
+ },
11
+ "sizes": {
12
+ "description": "Optional array of strings that specify sizes at which the icon can be used.\nEach string should be in WxH format (e.g., `\"48x48\"`, `\"96x96\"`) or `\"any\"` for scalable formats like SVG.\n\nIf not provided, the client should assume that the icon can be used at any size.",
13
+ "items": {
14
+ "type": "string"
15
+ },
16
+ "type": "array"
17
+ },
18
+ "src": {
19
+ "description": "A standard URI pointing to an icon resource. May be an HTTP/HTTPS URL or a\n`data:` URI with Base64-encoded image data.\n\nConsumers SHOULD take steps to ensure URLs serving icons are from the\nsame domain as the client/server or a trusted domain.\n\nConsumers SHOULD take appropriate precautions when consuming SVGs as they can contain\nexecutable JavaScript.",
20
+ "format": "uri",
21
+ "type": "string"
22
+ },
23
+ "theme": {
24
+ "description": "Optional specifier for the theme this icon is designed for. `\"light\"` indicates\nthe icon is designed to be used with a light background, and `\"dark\"` indicates\nthe icon is designed to be used with a dark background.\n\nIf not provided, the client should assume the icon can be used with any theme.",
25
+ "enum": ["dark", "light"],
26
+ "type": "string"
27
+ }
28
+ },
29
+ "required": ["src"],
30
+ "type": "object"
31
+ },
32
+ "Input": {
33
+ "description": "A user-supplied or pre-set input value, used for {@link Remote} URL\nvariables and header values.",
34
+ "properties": {
35
+ "choices": {
36
+ "description": "Allowed values for the input. If provided, the user must select one.",
37
+ "items": {
38
+ "type": "string"
39
+ },
40
+ "type": "array"
41
+ },
42
+ "default": {
43
+ "description": "Default value for the input. SHOULD be a valid value for the input.",
44
+ "type": "string"
45
+ },
46
+ "description": {
47
+ "description": "Human-readable explanation of the input. Clients can use this to provide\ncontext to the user.",
48
+ "type": "string"
49
+ },
50
+ "format": {
51
+ "description": "Specifies the input format. `\"filepath\"` should be interpreted as a file\non the user's filesystem. When the input is converted to a string,\nbooleans should be represented by `\"true\"`/`\"false\"`, and numbers by\ndecimal values.",
52
+ "enum": ["boolean", "filepath", "number", "string"],
53
+ "type": "string"
54
+ },
55
+ "isRequired": {
56
+ "description": "Whether the input must be supplied for the connection to succeed.",
57
+ "type": "boolean"
58
+ },
59
+ "isSecret": {
60
+ "description": "Whether the input is a secret value (e.g., password, token). If true,\nclients should handle the value securely.",
61
+ "type": "boolean"
62
+ },
63
+ "placeholder": {
64
+ "description": "Placeholder displayed during configuration to provide examples or\nguidance about the expected form of the input.",
65
+ "type": "string"
66
+ },
67
+ "value": {
68
+ "description": "Pre-set value for the input. If set, the value should not be configurable\nby end users. Identifiers wrapped in `{curly_braces}` will be replaced\nwith the corresponding entries from the input's `variables` map (if any).",
69
+ "type": "string"
70
+ }
71
+ },
72
+ "type": "object"
73
+ },
74
+ "KeyValueInput": {
75
+ "description": "A named {@link Input} — used for HTTP headers — whose `value` may reference\nvariables for substitution.",
76
+ "properties": {
77
+ "choices": {
78
+ "description": "Allowed values for the input. If provided, the user must select one.",
79
+ "items": {
80
+ "type": "string"
81
+ },
82
+ "type": "array"
83
+ },
84
+ "default": {
85
+ "description": "Default value for the input. SHOULD be a valid value for the input.",
86
+ "type": "string"
87
+ },
88
+ "description": {
89
+ "description": "Human-readable explanation of the input. Clients can use this to provide\ncontext to the user.",
90
+ "type": "string"
91
+ },
92
+ "format": {
93
+ "description": "Specifies the input format. `\"filepath\"` should be interpreted as a file\non the user's filesystem. When the input is converted to a string,\nbooleans should be represented by `\"true\"`/`\"false\"`, and numbers by\ndecimal values.",
94
+ "enum": ["boolean", "filepath", "number", "string"],
95
+ "type": "string"
96
+ },
97
+ "isRequired": {
98
+ "description": "Whether the input must be supplied for the connection to succeed.",
99
+ "type": "boolean"
100
+ },
101
+ "isSecret": {
102
+ "description": "Whether the input is a secret value (e.g., password, token). If true,\nclients should handle the value securely.",
103
+ "type": "boolean"
104
+ },
105
+ "name": {
106
+ "description": "Name of the header.",
107
+ "type": "string"
108
+ },
109
+ "placeholder": {
110
+ "description": "Placeholder displayed during configuration to provide examples or\nguidance about the expected form of the input.",
111
+ "type": "string"
112
+ },
113
+ "value": {
114
+ "description": "Pre-set value for the input. If set, the value should not be configurable\nby end users. Identifiers wrapped in `{curly_braces}` will be replaced\nwith the corresponding entries from the input's `variables` map (if any).",
115
+ "type": "string"
116
+ },
117
+ "variables": {
118
+ "additionalProperties": {
119
+ "$ref": "#/$defs/Input"
120
+ },
121
+ "description": "Variables referenced by `{curly_braces}` identifiers in `value`. The map\nkey is the variable name; the value defines the variable's properties.",
122
+ "type": "object"
123
+ }
124
+ },
125
+ "required": ["name"],
126
+ "type": "object"
127
+ },
128
+ "MetaObject": {
129
+ "additionalProperties": {},
130
+ "description": "Represents the contents of a `_meta` field, which clients and servers use to attach additional metadata to their interactions.\n\nCertain key names are reserved by MCP for protocol-level metadata; implementations MUST NOT make assumptions about values at these keys. Additionally, specific schema definitions may reserve particular names for purpose-specific metadata, as declared in those definitions.\n\nValid keys have two segments:\n\n**Prefix:**\n- Optional — if specified, MUST be a series of _labels_ separated by dots (`.`), followed by a slash (`/`).\n- Labels MUST start with a letter and end with a letter or digit. Interior characters may be letters, digits, or hyphens (`-`).\n- Any prefix consisting of zero or more labels, followed by `modelcontextprotocol` or `mcp`, followed by any label, is **reserved** for MCP use. For example: `modelcontextprotocol.io/`, `mcp.dev/`, `api.modelcontextprotocol.org/`, and `tools.mcp.com/` are all reserved.\n\n**Name:**\n- Unless empty, MUST start and end with an alphanumeric character (`[a-z0-9A-Z]`).\n- Interior characters may be alphanumeric, hyphens (`-`), underscores (`_`), or dots (`.`).",
131
+ "type": "object"
132
+ },
133
+ "Remote": {
134
+ "description": "Metadata for connecting to a remote (HTTP-based) MCP server endpoint.",
135
+ "properties": {
136
+ "headers": {
137
+ "description": "HTTP headers required or accepted when connecting to this remote\nendpoint. Each header is described as a {@link KeyValueInput} so that\nclients can prompt users for required values, mark secrets, surface\ndefaults, and constrain to a list of choices.",
138
+ "items": {
139
+ "$ref": "#/$defs/KeyValueInput"
140
+ },
141
+ "type": "array"
142
+ },
143
+ "supportedProtocolVersions": {
144
+ "description": "MCP protocol versions actively supported by this remote endpoint. Allows\nclients to select a compatible protocol version before connecting.",
145
+ "items": {
146
+ "type": "string"
147
+ },
148
+ "type": "array"
149
+ },
150
+ "type": {
151
+ "description": "The transport type for this remote endpoint.",
152
+ "enum": ["sse", "streamable-http"],
153
+ "type": "string"
154
+ },
155
+ "url": {
156
+ "description": "URL template for the remote endpoint. Must start with `http://`,\n`https://`, or a `{template-variable}`. Variables in `{curly_braces}`\nare substituted from the {@link Remote.variables} map before the\nclient connects.",
157
+ "pattern": "^(https?://[^\\s]+|\\{[a-zA-Z_][a-zA-Z0-9_]*\\}[^\\s]*)$",
158
+ "type": "string"
159
+ },
160
+ "variables": {
161
+ "additionalProperties": {
162
+ "$ref": "#/$defs/Input"
163
+ },
164
+ "description": "Configuration variables that can be referenced as `{curly_braces}`\nplaceholders in `url` (and inside header values via\n{@link KeyValueInput.variables}). The map key is the variable\nname; the value defines the variable's properties (e.g., human-readable\ndescription, default, whether it is required or secret).",
165
+ "type": "object"
166
+ }
167
+ },
168
+ "required": ["type", "url"],
169
+ "type": "object"
170
+ },
171
+ "Repository": {
172
+ "description": "Repository metadata for the MCP server source code. Enables users and\nsecurity experts to inspect the code, improving transparency.",
173
+ "properties": {
174
+ "id": {
175
+ "description": "Repository identifier from the hosting service (e.g., GitHub repo ID).\nOwned and determined by the source forge. Should remain stable across\nrepository renames and may be used to detect repository resurrection\nattacks — if a repository is deleted and recreated, the ID should change.",
176
+ "type": "string"
177
+ },
178
+ "source": {
179
+ "description": "Repository hosting service identifier (e.g., `\"github\"`). Used by registries\nto determine validation and API access methods.",
180
+ "type": "string"
181
+ },
182
+ "subfolder": {
183
+ "description": "Optional relative path from repository root to the server location within a\nmonorepo or nested package structure. Must be a clean relative path.",
184
+ "type": "string"
185
+ },
186
+ "url": {
187
+ "description": "Repository URL for browsing source code. Should support both web browsing\nand `git clone` operations.",
188
+ "format": "uri",
189
+ "type": "string"
190
+ }
191
+ },
192
+ "required": ["source", "url"],
193
+ "type": "object"
194
+ },
195
+ "ServerCard": {
196
+ "description": "A static metadata document describing a remote MCP server, suitable for\npre-connection discovery. A Server Card may be hosted at any unreserved URI;\nMCP reserves `GET <streamable-http-url>/server-card` as the recommended\nlocation. Clients learn a card's URL from an [AI Catalog](https://github.com/Agent-Card/ai-catalog)\nrather than guessing it.\n\nServer Cards describe only what is needed to discover and connect to a remote server:\nidentity, transport, and protocol versions.\n\nThey do not enumerate primitives (tools, resources, prompts) — those remain\nsubject to runtime listing via the protocol's standard list operations.\n\nThe fields a Server Card does declare (identity, transport, protocol\nversions) are advisory, not authoritative: they should be consistent with\nthe server's `server/discover` response, and clients must not treat them as\nauthoritative for security decisions. See \"Consistency with Runtime\nBehavior\" in docs/discovery.md for the normative requirement.",
197
+ "properties": {
198
+ "$schema": {
199
+ "description": "The Server Card JSON Schema URI that this document conforms to. Required.\n\nMust be the `/v1/` Server Card schema URL under\n`static.modelcontextprotocol.io/schemas/` (i.e.,\n`https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json`).\nSchema URLs are versioned by the `vN` segment rather than by date; a\nbreaking revision of the Server Card shape publishes a new `vN` family.",
200
+ "format": "uri",
201
+ "pattern": "^https://static\\.modelcontextprotocol\\.io/schemas/v1/server-card\\.schema\\.json$",
202
+ "type": "string"
203
+ },
204
+ "_meta": {
205
+ "$ref": "#/$defs/MetaObject",
206
+ "description": "Extension metadata using reverse-DNS namespacing for vendor-specific data.\n\nFollows the protocol's standard `_meta` definition."
207
+ },
208
+ "description": {
209
+ "description": "Clear human-readable explanation of server functionality. Should focus on\ncapabilities, not implementation details.",
210
+ "maxLength": 100,
211
+ "minLength": 1,
212
+ "type": "string"
213
+ },
214
+ "icons": {
215
+ "description": "Optional set of sized icons that the client can display in a user interface.\n\nClients that support rendering icons MUST support at least the following\nMIME types: `image/png` and `image/jpeg` (safe, universal compatibility).\nClients SHOULD also support: `image/svg+xml` (scalable but requires security\nprecautions) and `image/webp` (modern, efficient format).",
216
+ "items": {
217
+ "$ref": "#/$defs/Icon"
218
+ },
219
+ "type": "array"
220
+ },
221
+ "name": {
222
+ "description": "Server name in reverse-DNS format. Must contain exactly one forward slash\nseparating namespace from server name.",
223
+ "maxLength": 200,
224
+ "minLength": 3,
225
+ "pattern": "^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$",
226
+ "type": "string"
227
+ },
228
+ "remotes": {
229
+ "description": "Metadata helpful for making HTTP-based connections to this MCP server.",
230
+ "items": {
231
+ "$ref": "#/$defs/Remote"
232
+ },
233
+ "type": "array"
234
+ },
235
+ "repository": {
236
+ "$ref": "#/$defs/Repository",
237
+ "description": "Optional repository metadata for the MCP server source code.\nRecommended for transparency and security inspection."
238
+ },
239
+ "title": {
240
+ "description": "Optional human-readable title or display name for the MCP server.\nMCP subregistries or clients MAY choose to use this for display purposes.",
241
+ "maxLength": 100,
242
+ "minLength": 1,
243
+ "type": "string"
244
+ },
245
+ "version": {
246
+ "description": "Version string for this server. SHOULD follow semantic versioning\n(e.g., '1.0.2', '2.1.0-alpha'). Equivalent of `Implementation.version`\nin the MCP specification. Non-semantic versions are allowed but may not\nsort predictably. Version ranges are rejected (e.g., '^1.2.3', '~1.2.3',\n'>=1.2.3', '1.x', '1.*').",
247
+ "maxLength": 255,
248
+ "type": "string"
249
+ },
250
+ "websiteUrl": {
251
+ "description": "Optional URL to the server's homepage, documentation, or project website.\nProvides a central link for users to learn more about the server.\nParticularly useful when the server has custom installation instructions\nor setup requirements.",
252
+ "format": "uri",
253
+ "type": "string"
254
+ }
255
+ },
256
+ "required": ["$schema", "description", "name", "version"],
257
+ "type": "object"
258
+ }
259
+ }
260
+ }