toolmenu 0.28.0 → 0.29.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.
package/README.md CHANGED
@@ -131,7 +131,7 @@ jobs:
131
131
  - uses: actions/setup-node@v7
132
132
  with: { node-version: 22 }
133
133
  - run: npm ci && npm run build
134
- - uses: niksa90/toolmenu@v0.28.0
134
+ - uses: niksa90/toolmenu@v0.29.0
135
135
  with:
136
136
  command: node dist/server.js
137
137
  baseline: menu.json # your committed snapshot
package/dist/auth.d.ts CHANGED
@@ -90,6 +90,8 @@ export declare function pastedRedirect(text: string): URLSearchParams | undefine
90
90
  export declare function login(serverUrl: string, options?: LoginOptions): Promise<{
91
91
  name?: string;
92
92
  tools: number;
93
+ authenticated: boolean;
94
+ withoutLogin?: number;
93
95
  }>;
94
96
  export declare function logout(serverUrl: string): Promise<boolean>;
95
97
  /** Stored logins: the server, its issuer, and when the tokens were saved. No secrets. */
package/dist/auth.js CHANGED
@@ -281,6 +281,8 @@ function printForPaste(port) {
281
281
  */
282
282
  export async function login(serverUrl, options = {}) {
283
283
  const port = options.port ?? DEFAULT_PORT;
284
+ // What was stored before this login (a registered client, a rejected token) is kept.
285
+ const stored = hasLogin(serverUrl);
284
286
  const callback = await listenForCallback(port, options.timeoutMs ?? 300_000);
285
287
  try {
286
288
  const provider = new StoredOAuthProvider(serverUrl, {
@@ -318,6 +320,8 @@ export async function login(serverUrl, options = {}) {
318
320
  await provider.invalidateCredentials('discovery');
319
321
  const transport = new StreamableHTTPClientTransport(new URL(serverUrl), { authProvider: provider });
320
322
  const client = new Client({ name: 'toolmenu', version: VERSION });
323
+ // Whether the server asked for credentials during this login (a 401 to answer).
324
+ let challenged = false;
321
325
  try {
322
326
  await client.connect(transport);
323
327
  // Already logged in with a valid (or refreshed) token.
@@ -326,6 +330,7 @@ export async function login(serverUrl, options = {}) {
326
330
  catch (error) {
327
331
  if (!(error instanceof UnauthorizedError))
328
332
  throw error;
333
+ challenged = true;
329
334
  const params = options.noBrowser ? await Promise.race([callback.params, pasted()]).finally(() => reading.abort()) : await callback.params;
330
335
  if (params.get('error')) {
331
336
  const described = params.get('error_description');
@@ -338,7 +343,16 @@ export async function login(serverUrl, options = {}) {
338
343
  await transport.finishAuth(params);
339
344
  await endSession(client, transport);
340
345
  }
341
- return await check(serverUrl);
346
+ // A server that never asked for credentials leaves nothing to log in with: the
347
+ // file the discovery step wrote holds no token, so drop it rather than list a login.
348
+ // A file from before this login stays: it may hold a registered client.
349
+ const authenticated = Boolean(await provider.tokens());
350
+ if (!authenticated && !stored)
351
+ await logout(serverUrl);
352
+ // A token from an earlier login, sent to a server that never asked for one this time:
353
+ // it may not need it at all. List once without it, so the message can say so.
354
+ const withoutLogin = authenticated && !challenged ? await anonymousTools(serverUrl) : undefined;
355
+ return { ...(await check(serverUrl)), authenticated, ...(withoutLogin !== undefined ? { withoutLogin } : {}) };
342
356
  }
343
357
  catch (error) {
344
358
  // GitHub's hosted server, for one: no dynamic registration, so toolmenu can't
@@ -356,6 +370,22 @@ export async function login(serverUrl, options = {}) {
356
370
  callback.close();
357
371
  }
358
372
  }
373
+ /** How many tools the server lists with no credentials at all, or undefined if it wants them. */
374
+ async function anonymousTools(serverUrl) {
375
+ const { connect, listTools } = await import('./connect.js');
376
+ try {
377
+ const connection = await connect({ kind: 'http', url: serverUrl, noAuth: true });
378
+ try {
379
+ return (await listTools(connection)).tools.length;
380
+ }
381
+ finally {
382
+ await connection.close();
383
+ }
384
+ }
385
+ catch {
386
+ return undefined;
387
+ }
388
+ }
359
389
  /** Connect with the stored login and list tools: the login works. */
360
390
  async function check(serverUrl) {
361
391
  const client = new Client({ name: 'toolmenu', version: VERSION });
package/dist/cli.js CHANGED
@@ -37,6 +37,7 @@ import { CLI_OPTIONS } from './options.js';
37
37
  import { editDistance } from './words.js';
38
38
  import { formatScan, ListError, loadList, scan, scanExit } from './scan.js';
39
39
  import { explain, findRule, formatExplained, listRules, ruleDocs } from './rule-docs.js';
40
+ import { RETIRED_RULES } from './rules/index.js';
40
41
  import { commandHelp, commandOptions, isCommand, overview, unknownCommand } from './help.js';
41
42
  class UsageError extends Error {
42
43
  }
@@ -575,7 +576,14 @@ async function authCommand(args, values) {
575
576
  if (values['client-secret'] && !values['client-id'])
576
577
  throw new UsageError('--client-secret goes with --client-id');
577
578
  const result = await login(url, { port, scope: values.scope, clientId: values['client-id'], clientSecret: values['client-secret'], noBrowser: values['no-browser'] });
578
- process.stdout.write(`Logged in to ${plain(result.name ?? url)} (${url}): it lists ${result.tools} tool${result.tools === 1 ? '' : 's'} with this login.\nsnapshot and session use it from now on (--no-auth to skip it); stored in ${authDir()}.\n`);
579
+ const count = `${result.tools} tool${result.tools === 1 ? '' : 's'}`;
580
+ process.stdout.write(result.authenticated
581
+ ? `Logged in to ${plain(result.name ?? url)} (${url}): it lists ${count} with this login.\nsnapshot and session use it from now on (--no-auth to skip it); stored in ${authDir()}.\n` +
582
+ (result.withoutLogin !== undefined
583
+ ? `The server didn't ask for this login: it used the token stored earlier, and it lists ${result.withoutLogin} tool${result.withoutLogin === 1 ? '' : 's'} without one too.\n→ Next: If the menus should differ, compare them: toolmenu snapshot ${url} --no-auth. If they shouldn't, toolmenu auth logout ${url}.\n`
584
+ : '')
585
+ : `No login made for ${plain(result.name ?? url)} (${url}): it listed ${count} without asking for credentials, so nothing was stored.\n` +
586
+ `→ Next: A server like this usually asks for a login only when a tool is called. If session reports session/untested, pass a token with --header "Authorization: Bearer <token>".\n`);
579
587
  return 0;
580
588
  }
581
589
  /**
@@ -660,6 +668,11 @@ function explainCommand(rest, command, format) {
660
668
  process.stdout.write(format === 'json' ? `${JSON.stringify(Object.keys(ruleDocs()))}\n` : listRules());
661
669
  return 0;
662
670
  }
671
+ const retired = rest[0].trim().toLowerCase();
672
+ if (Object.hasOwn(RETIRED_RULES, retired)) {
673
+ process.stdout.write(format === 'json' ? `${JSON.stringify({ id: retired, retired: RETIRED_RULES[retired] })}\n` : `${retired}: ${RETIRED_RULES[retired]}\n`);
674
+ return 0;
675
+ }
663
676
  const found = findRule(rest[0]);
664
677
  if ('near' in found) {
665
678
  const hint = found.near.length ? ` Did you mean ${found.near.join(', ')}?` : '';
package/dist/config.js CHANGED
@@ -3,6 +3,8 @@ import { readFile } from 'node:fs/promises';
3
3
  import { CLIENTS } from './clients.js';
4
4
  import { LIST_WORDS } from './lists.js';
5
5
  import { CLIENT_LIMITS } from './rules/description.js';
6
+ import { RETIRED_RULES } from './rules/index.js';
7
+ import { findRule, ruleDocs } from './rule-docs.js';
6
8
  import { jsonErrorAt } from './menu.js';
7
9
  const DEFAULT_PATH = 'toolmenu.config.json';
8
10
  /** Optional: no config file is fine. */
@@ -26,6 +28,15 @@ export async function loadConfig(path) {
26
28
  if (!['error', 'warn', 'info', 'off'].includes(value)) {
27
29
  throw new Error(`${file}: rules["${id}"] must be error, warn, info or off`);
28
30
  }
31
+ if (Object.hasOwn(RETIRED_RULES, id))
32
+ process.stderr.write(`toolmenu: ${file}: rules["${id}"] changes nothing: ${RETIRED_RULES[id]}\n`);
33
+ else if (!Object.hasOwn(ruleDocs(), id)) {
34
+ // A typo is ignored like any key nothing reads, so a rule turned up to error in CI
35
+ // isn't: say so, with the closest ids, and carry on.
36
+ const found = findRule(id);
37
+ const near = 'near' in found ? found.near : [found.id];
38
+ process.stderr.write(`toolmenu: ${file}: rules["${id}"] isn't a rule, so it changes nothing.${near.length ? ` Did you mean ${near.join(', ')}?` : ''} toolmenu explain lists every rule.\n`);
39
+ }
29
40
  }
30
41
  if (config.protocol !== undefined && !['auto', 'legacy', 'modern'].includes(config.protocol)) {
31
42
  throw new Error(`${file}: protocol must be auto, legacy or modern`);
package/dist/connect.d.ts CHANGED
@@ -62,6 +62,10 @@ export interface Connection {
62
62
  version?: string;
63
63
  };
64
64
  capabilities: Record<string, unknown>;
65
+ /** server/discover got this HTTP status (401 or 403) and the 2025 handshake served the menu (spec/discover-refused). */
66
+ discoverRefused?: number;
67
+ /** The handshake's instructions, which clients may add to the model's context. */
68
+ instructions?: string;
65
69
  /** True when the request carried credentials (an Authorization-style header). */
66
70
  usedAuth: boolean;
67
71
  stderr: () => string;
package/dist/connect.js CHANGED
@@ -182,6 +182,29 @@ export async function connect(target, options = {}) {
182
182
  await stderrEnded(stdioStderr, trace.exit ? STDERR_AFTER_EXIT_MS : 1000);
183
183
  }
184
184
  await endSession(client, transport);
185
+ // A 401 or 403 to server/discover alone isn't the server's last word: Dreamwork
186
+ // 1.10.0 answers it with a 401 while its 2025 handshake serves a guest menu. With
187
+ // the handshake left to toolmenu, and no stored login (a refused one is reported as
188
+ // such), try the 2025 one before calling it a login wall. A server that wants
189
+ // credentials refuses that too; one that fails it any other way (a 2026-only
190
+ // server) is reported with the first refusal, which is the one that explains it.
191
+ const discover = trace.http.get('server/discover')?.status;
192
+ if (target.kind === 'http' &&
193
+ !oauth &&
194
+ (!target.protocol || target.protocol === 'auto') &&
195
+ (discover === 401 || discover === 403) &&
196
+ !trace.sent.some((s) => s.method === 'initialize')) {
197
+ const refused = explain(error, trace, context);
198
+ try {
199
+ const fallback = await connect({ ...target, protocol: 'legacy' }, options);
200
+ fallback.discoverRefused = discover;
201
+ return fallback;
202
+ }
203
+ catch (retry) {
204
+ const status = retry.status;
205
+ throw status === 401 || status === 403 ? retry : refused;
206
+ }
207
+ }
185
208
  throw explain(error, trace, context);
186
209
  }
187
210
  const wire = new WireLog();
@@ -197,6 +220,7 @@ export async function connect(target, options = {}) {
197
220
  era: eraOf(protocolVersion),
198
221
  server: { name: server.name, version: server.version },
199
222
  capabilities: (client.getServerCapabilities() ?? {}),
223
+ instructions: client.getInstructions(),
200
224
  usedAuth: target.kind === 'http' &&
201
225
  (oauth || Object.keys(target.headers ?? {}).some(isCredentialHeader)),
202
226
  stderr: () => stderrText,
package/dist/diff.js CHANGED
@@ -60,6 +60,8 @@ export const DIFF_RULES = {
60
60
  'diff/param-renamed': { severity: 'warn' },
61
61
  'diff/version-bump': { severity: 'warn' },
62
62
  'diff/version-backwards': { severity: 'warn' },
63
+ // --release given: the server reported the same serverInfo.version in both releases.
64
+ 'diff/server-version-stale': { severity: 'info' },
63
65
  'diff/token-budget': { severity: 'error' },
64
66
  // Operations behind a search tool (snapshot --catalog). A search returns its top
65
67
  // matches, so one not found this time may be ranked out, not removed: a notice,
@@ -220,6 +222,18 @@ export function diffMenus(before, after, options = {}) {
220
222
  fix: release.source === 'server' ? 'Pass the release versions with --release old..new.' : 'Pass --release as old..new, the older release first.',
221
223
  });
222
224
  }
225
+ // The server reported one version across two releases (the filesystem server said
226
+ // 0.2.0 for 19, F5; serbia-prices-mcp reports FastMCP's own 4.2.1): anything that
227
+ // tracks the server by serverInfo.version sees no change. Only with release versions,
228
+ // which say a release happened.
229
+ const reported = before.server.version;
230
+ if (options.release && options.release.before !== options.release.after && reported && reported === after.server.version && reported !== options.release.after) {
231
+ versionRaw.push({
232
+ rule: 'diff/server-version-stale',
233
+ message: `The server reported version ${reported} in both releases (${options.release.before} → ${options.release.after}), so serverInfo.version isn't the release version: a client, registry or log that tracks the server by it sees no change.`,
234
+ fix: "Report the release version in serverInfo.version (the package's own version, not the SDK's or the framework's default).",
235
+ });
236
+ }
223
237
  const required = release && actualBump ? requiredBump(suggestedBump, release.before) : undefined;
224
238
  const short = release && actualBump && required && BUMP_RANK[actualBump] < BUMP_RANK[required];
225
239
  if (short)
@@ -49,11 +49,6 @@
49
49
  "severity": "info",
50
50
  "text": "Descriptions longer than the client sends, with where the cut falls. Nothing past it reads as an instruction, so it's a check, not a bug"
51
51
  },
52
- "description/late-instruction": {
53
- "command": "snapshot",
54
- "severity": "info",
55
- "text": "Only with the default cut: an instruction past 280 characters, where one real client cut, but inside the default cut. Split out of `description/cut` in 0.13; a setting for `description/cut` still applies to it unless it's set itself (`RULE_ALIASES`)"
56
- },
57
52
  "ids/authored": {
58
53
  "command": "snapshot",
59
54
  "severity": "info",
@@ -64,6 +59,11 @@
64
59
  "severity": "info",
65
60
  "text": "2026-07-28. A tool that creates a handle (`create`/`start`/`open`/`new`/`begin`/`acquire` + session, basket, cart, checkout, handle, lease or lock) that another tool takes back (`session_id`, `sessionToken`, `session`), whose description and output schema don't say how long it lasts. The spec asks for retention in the creation tool's description. Unsure"
66
61
  },
62
+ "instructions/unknown-name": {
63
+ "command": "snapshot",
64
+ "severity": "warn",
65
+ "text": "The handshake's `instructions` name a tool the menu doesn't list, or, with `--lists resources`, a resource URI in the server's own scheme that no listed resource or template matches. An agent that follows the instructions asks for something the server didn't offer. A tool name is a snake_case word that starts with a verb, isn't a parameter, a listed prompt, the end of a namespaced tool name or a field (`open_url`, `read_only`), isn't written as a value (`action=update_budget`, `stop_loss: 2`) or a subcommand of a listed tool, and sits in no sentence that says why it's missing (old names, a login, a token, an account, an unlock): marked unsure. Seen on Dreamwork 1.10.0 (`submit_feedback`, a day before its menu had it) and on 16 of 1,078 hosted servers listed without credentials (2026-11-19)"
66
+ },
67
67
  "lists/resource-read-schema": {
68
68
  "command": "snapshot",
69
69
  "severity": "error",
@@ -194,6 +194,11 @@
194
194
  "severity": "info",
195
195
  "text": "The server only speaks the 2025 protocol: no working `server/discover`, which 2026-07-28 servers **MUST** implement. Info, not error: see §13"
196
196
  },
197
+ "spec/discover-refused": {
198
+ "command": "snapshot",
199
+ "severity": "warn",
200
+ "text": "HTTP. `server/discover` got 401 or 403 while the 2025 handshake (`initialize`) served the menu with the same credentials, or none. A client that tries 2026-07-28 first stops there and treats the server as needing a login: the official TypeScript SDK client (2.4) with `versionNegotiation: auto` fails with \"Version negotiation failed\"; its default (legacy) never asks. toolmenu falls back to 2025 and checks that; `spec/discover` isn't said as well. Seen on Dreamwork 1.10.0 and 3 of 733 hosted servers that needed a login on 2026-11-09 (FINDINGS F22). Checked against the SDK client's behaviour in the tests"
201
+ },
197
202
  "spec/ref": {
198
203
  "command": "snapshot",
199
204
  "severity": "error",
@@ -434,6 +439,11 @@
434
439
  "severity": "info (notice)",
435
440
  "text": "The input schema changed in keywords toolmenu doesn't classify, a schema that's empty or invalid, or one too large to expand through its `$ref`s. Review it by hand"
436
441
  },
442
+ "diff/server-version-stale": {
443
+ "command": "diff",
444
+ "severity": "info",
445
+ "text": "With `--release`: the server reported the same `serverInfo.version` in both releases, so it isn't the release version, and anything that tracks the server by it sees no change (the filesystem server said `0.2.0` for 19 releases, FINDINGS F5)"
446
+ },
437
447
  "diff/token-budget": {
438
448
  "command": "diff",
439
449
  "severity": "error",
@@ -32,5 +32,4 @@ export declare function pastTheCut(text: string, otherTools: string[], limit: nu
32
32
  export declare function sentInFull(tool: MenuTool, patterns: string[] | undefined): boolean;
33
33
  export declare const buried: Rule;
34
34
  export declare const cut: Rule;
35
- export declare const lateInstruction: Rule;
36
35
  export {};
@@ -144,8 +144,6 @@ export const buried = {
144
144
  return findings;
145
145
  },
146
146
  };
147
- /** A short cut to check against when the client's own cut isn't set: one real client cut at 280. */
148
- const SHORT_CUT = 280;
149
147
  /** “…the last words before ✂ the first words after…”, to find the cut in the text. */
150
148
  function aroundTheCut(text, at) {
151
149
  const before = text.slice(Math.max(0, at - 30), at).replace(/\s+/g, ' ');
@@ -187,43 +185,3 @@ export const cut = {
187
185
  ];
188
186
  },
189
187
  };
190
- export const lateInstruction = {
191
- id: 'description/late-instruction',
192
- scope: 'agent',
193
- severity: 'info',
194
- lesson: 'truncated description',
195
- summary: 'Instructions to the agent that a client cutting descriptions short would hide',
196
- run(ctx) {
197
- // Only with the default cut: once descriptionLimit is set, description/buried checks the real one.
198
- if (ctx.descriptionLimit !== undefined)
199
- return [];
200
- const { limit, who } = resolveLimit(undefined);
201
- if (limit <= SHORT_CUT)
202
- return [];
203
- const all = ctx.menu.tools.map((t) => t.name);
204
- const late = [];
205
- for (const tool of kept(ctx.menu.tools, ctx)) {
206
- const text = tool.description ?? '';
207
- if (text.length <= SHORT_CUT || sentInFull(tool, ctx.fullDescriptions))
208
- continue;
209
- // Past the default cut is description/buried's.
210
- const hidden = pastTheCut(text, all.filter((n) => n !== tool.name), SHORT_CUT).filter((i) => i.at < limit);
211
- if (hidden.length)
212
- late.push({ tool, at: hidden[0].at, straddles: hidden[0].straddles, sentence: sentenceAround(text, hidden[0].at), more: hidden.length - 1 });
213
- }
214
- if (late.length === 0)
215
- return [];
216
- const one = late.length === 1;
217
- const client = who;
218
- return [
219
- {
220
- ...(one ? { tool: late[0].tool.name } : {}),
221
- confidence: 'unsure',
222
- message: `${one ? `The ${late[0].tool.name} description gives` : `${late.length} descriptions give`} the agent instructions ${late.every((l) => l.straddles) ? `that run past character ${SHORT_CUT}` : late.some((l) => l.straddles) ? `after character ${SHORT_CUT} or running past it` : `after character ${SHORT_CUT}`}, where a client that cuts descriptions short never shows them (one real client cut at ${SHORT_CUT}). ${client} sends ${num(limit)} characters, so there they arrive.`,
223
- // One that starts before the cut and runs past it is cut in the middle: say so, or "char 264" reads as before the cut.
224
- detail: late.map((l) => `${l.tool.name}: char ${num(l.at)}${l.straddles ? ` (runs past ${SHORT_CUT})` : ''}: “${clip(l.sentence, 120)}”${l.more ? ` (and ${l.more} more after it)` : ''}`),
225
- fix: `If your client cuts descriptions, set descriptionLimit to its cut and toolmenu checks against that. Otherwise, moving ${one ? 'the instruction' : 'each instruction'} into the first sentences is cheap insurance.`,
226
- },
227
- ];
228
- },
229
- };
@@ -3,11 +3,10 @@ import type { Rule, RuleContext } from './rule.js';
3
3
  export type { Rule, RuleContext } from './rule.js';
4
4
  export declare const MENU_RULES: Rule[];
5
5
  /**
6
- * Rules split out of an older one. A setting for the old id still applies to the
7
- * new one unless the new id is set itself: before 0.13, description/cut held
8
- * the late-instruction hint too, and `"description/cut": "off"` turned both off.
6
+ * Rules that no longer exist, and why. A config may still name one: it changes nothing,
7
+ * and loading the config says so. `explain` says the same.
9
8
  */
10
- export declare const RULE_ALIASES: Record<string, string>;
9
+ export declare const RETIRED_RULES: Record<string, string>;
11
10
  export interface RuleSettings {
12
11
  /** Per-rule severity override, or 'off'. */
13
12
  rules?: Record<string, Severity | 'off'>;
@@ -1,5 +1,6 @@
1
1
  import { SEVERITY_RANK } from '../types.js';
2
- import { buried, cut, lateInstruction } from './description.js';
2
+ import { buried, cut } from './description.js';
3
+ import { unknownName } from './instructions.js';
3
4
  import { connectionVariance, hostSpecific, nondeterministic, processVariance } from './determinism.js';
4
5
  import { authoredIds } from './ids.js';
5
6
  import { clientFeatures, clientLimit, clientName } from './clients.js';
@@ -10,7 +11,7 @@ import { listSchema, listVariance, resourceReadSchema, resourceUnread, resourceU
10
11
  import { handleLifetime } from './handles.js';
11
12
  import { authVariance, cacheScopePublic } from './identities.js';
12
13
  import { route, sharedWord, vagueId } from './naming.js';
13
- import { cacheHints, deprecated, discover, duplicateName, extensionId, schema, serverInfo, taskRequired, toolName, toolsCapability } from './spec.js';
14
+ import { cacheHints, deprecated, discover, discoverRefused, duplicateName, extensionId, schema, serverInfo, taskRequired, toolName, toolsCapability } from './spec.js';
14
15
  import { noDryRun, readOnlyMismatch, unannotated } from './write.js';
15
16
  import { gated } from './gated.js';
16
17
  import { xMcpHeader } from './headers.js';
@@ -38,7 +39,6 @@ export const MENU_RULES = [
38
39
  handleLifetime,
39
40
  buried,
40
41
  cut,
41
- lateInstruction,
42
42
  noDryRun,
43
43
  unannotated,
44
44
  readOnlyMismatch,
@@ -47,6 +47,7 @@ export const MENU_RULES = [
47
47
  schemaRef,
48
48
  toolsCapability,
49
49
  discover,
50
+ discoverRefused,
50
51
  deprecated,
51
52
  cacheHints,
52
53
  authVariance,
@@ -67,13 +68,15 @@ export const MENU_RULES = [
67
68
  appsLegacyKey,
68
69
  appsVisibility,
69
70
  appsAppOnlyListed,
71
+ unknownName,
70
72
  ];
71
73
  /**
72
- * Rules split out of an older one. A setting for the old id still applies to the
73
- * new one unless the new id is set itself: before 0.13, description/cut held
74
- * the late-instruction hint too, and `"description/cut": "off"` turned both off.
74
+ * Rules that no longer exist, and why. A config may still name one: it changes nothing,
75
+ * and loading the config says so. `explain` says the same.
75
76
  */
76
- export const RULE_ALIASES = { 'description/late-instruction': 'description/cut' };
77
+ export const RETIRED_RULES = {
78
+ 'description/late-instruction': "retired after 0.28.1: it checked a cut at 280 characters, which no client documents. If your client cuts descriptions, set descriptionLimit to its cut and description/buried checks against it.",
79
+ };
77
80
  export function runRules(rules, ctx, settings = {}) {
78
81
  const ignore = (settings.ignore ?? []).map(globToRegExp);
79
82
  const isIgnored = (tool) => ignore.some((re) => re.test(tool));
@@ -81,7 +84,7 @@ export function runRules(rules, ctx, settings = {}) {
81
84
  // The menu as an MCP Apps host shows it to the agent: app-only tools left out.
82
85
  const shown = agentMenu(ctx.menu).shown;
83
86
  for (const rule of rules) {
84
- const configured = settings.rules?.[rule.id] ?? (RULE_ALIASES[rule.id] ? settings.rules?.[RULE_ALIASES[rule.id]] : undefined);
87
+ const configured = settings.rules?.[rule.id];
85
88
  if (configured === 'off')
86
89
  continue;
87
90
  if (rule.since && (!ctx.protocolVersion || ctx.protocolVersion < rule.since))
@@ -0,0 +1,2 @@
1
+ import { type Rule } from './rule.js';
2
+ export declare const unknownName: Rule;
@@ -0,0 +1,181 @@
1
+ import { count } from './rule.js';
2
+ /** Verbs a tool name usually starts with: they tell a tool (call submit_feedback) from a field written the same way. */
3
+ const VERBS = new Set('get list search find fetch read browse create add update edit delete remove set mark save submit send upload download run start stop check explore suggest report publish apply cancel move import export confirm forget remember restore dismiss reply generate prepare format replace reopen answer undo parse query lookup describe show open close resolve call invoke execute'.split(' '));
4
+ /** Last words of a name that make it a field or a setting, not a tool: open_url, read_only, check_first. */
5
+ const FIELD_ENDS = new Set('url urls link links id ids at on only with here first hr ms seconds minutes hours days count total'.split(' '));
6
+ /**
7
+ * A sentence that says why a tool isn't listed: old names, or a condition on it (a login,
8
+ * a token, an account, an unlock, a private mode). The rule's own fix, already done. A
9
+ * word like "token" alone isn't one: it has to sit near what makes it a condition.
10
+ */
11
+ const CONDITION = String.raw `(?:tokens?|(?:api )?keys?|account|log ?in|sign ?in|logged in|signed in|authenticat\w*|credentials?|scope)`;
12
+ const AVAILABILITY = String.raw `(?:only|available|unlock\w*|adds?|requires?|needs?|after|once|with an?)`;
13
+ /** Up to 120 characters within one sentence: a full stop inside a URL or rs_live_... doesn't end it. */
14
+ const GAP = String.raw `(?:[^.;]|\.(?!\s|$)){0,120}?`;
15
+ const EXPLAINED = [
16
+ /\b(?:old(?:er)? (?:tool )?names|formerly|renamed|deprecated|private mode|unlock\w*)\b/i,
17
+ /\bwhen (?:the )?tools are available\b/i,
18
+ new RegExp(String.raw `\b${AVAILABILITY}\b${GAP}\b${CONDITION}\b`, 'i'),
19
+ new RegExp(String.raw `\b${CONDITION}\b${GAP}\b(?:unlock\w*|adds?|only)\b`, 'i'),
20
+ ];
21
+ /** Each place `word` stands alone in `text`: where, what comes before and after it on its line, and its sentence. */
22
+ function mentions(text, word) {
23
+ const found = [];
24
+ const re = new RegExp(String.raw `(?<![\w/.:-])${word}(?![\w-])`, 'g');
25
+ for (let m = re.exec(text); m; m = re.exec(text)) {
26
+ const line0 = text.lastIndexOf('\n', m.index) + 1;
27
+ const lineEnd = text.indexOf('\n', m.index);
28
+ found.push({
29
+ at: m.index,
30
+ before: text.slice(Math.max(line0, m.index - 40), m.index),
31
+ after: text.slice(m.index + word.length, lineEnd === -1 ? m.index + word.length + 20 : Math.min(lineEnd, m.index + word.length + 20)),
32
+ sentence: wholeSentence(text, m.index),
33
+ });
34
+ }
35
+ return found;
36
+ }
37
+ /** Every property name in a schema, at any depth. */
38
+ function propertyNames(schema, out) {
39
+ if (Array.isArray(schema))
40
+ for (const item of schema)
41
+ propertyNames(item, out);
42
+ else if (schema && typeof schema === 'object') {
43
+ const props = schema.properties;
44
+ if (props && typeof props === 'object' && !Array.isArray(props))
45
+ for (const key of Object.keys(props))
46
+ out.add(key);
47
+ for (const value of Object.values(schema))
48
+ if (value && typeof value === 'object')
49
+ propertyNames(value, out);
50
+ }
51
+ }
52
+ /**
53
+ * A URI template (RFC 6570) as a pattern for the URIs it expands to. A plain {var} is one
54
+ * path segment; {+var} and {#var} may span slashes; {/var}, {.var}, {;var}, {?var} and
55
+ * {&var} add their own prefix, or nothing when the variable is undefined.
56
+ */
57
+ function templatePattern(template) {
58
+ const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
59
+ const parts = template.split(/(\{[^}]+\})/);
60
+ const source = parts
61
+ .map((part) => {
62
+ if (!part.startsWith('{'))
63
+ return escape(part);
64
+ const op = part[1];
65
+ if (op === '+' || op === '#')
66
+ return '.*';
67
+ if (op === '/')
68
+ return '(?:/[^?#]*)?';
69
+ if (op === '.')
70
+ return String.raw `(?:\.[^/?#]*)?`;
71
+ if (op === ';')
72
+ return '(?:;[^/?#]*)?';
73
+ if (op === '?' || op === '&')
74
+ return '(?:[?&][^#]*)?';
75
+ return '[^/?#]+';
76
+ })
77
+ .join('');
78
+ return new RegExp(`^${source}$`);
79
+ }
80
+ export const unknownName = {
81
+ id: 'instructions/unknown-name',
82
+ severity: 'warn',
83
+ summary: "The server's instructions name a tool or resource the server doesn't list",
84
+ run(ctx) {
85
+ const text = ctx.instructions;
86
+ if (!text)
87
+ return [];
88
+ const tools = ctx.menu.tools.map((t) => t.name);
89
+ const listed = new Set(tools);
90
+ const fields = new Set();
91
+ for (const t of ctx.menu.tools) {
92
+ propertyNames(t.inputSchema, fields);
93
+ propertyNames(t.outputSchema, fields);
94
+ }
95
+ // Words in the instructions that read as something else, by the bench (2026-11-19, 52
96
+ // servers): fields and values (chart_url, read_only, action=update_budget, stop_loss: 2),
97
+ // subcommands of a listed tool (participate submit_position), prompts, and tools the
98
+ // sentence itself says are old or need a login, a token or an unlock first.
99
+ const prompts = new Set((ctx.menu.prompts ?? []).map((p) => p.name).filter((n) => typeof n === 'string'));
100
+ const toolPattern = tools.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
101
+ const afterTool = toolPattern ? new RegExp(String.raw `(?:^|[^\w])(?:${toolPattern})\s+$`) : undefined;
102
+ const counts = ({ before, after, sentence }) => !/[=]\s*["'`]?$/.test(before) && !/^\.\w/.test(after) && !/^\s*[:=]\s*(?:["'`\d-]|true\b|false\b|null\b)/.test(after) && !afterTool?.test(before) && !EXPLAINED.some((re) => re.test(sentence));
103
+ // snake_case words that read as a tool name, not in the menu: not a field in any
104
+ // schema, and not the end of a namespaced tool name (search_stories for worklore_search_stories).
105
+ const named = [...new Set(text.match(/(?<![\w/.:-])[a-z][a-z0-9]*(?:_[a-z0-9]+)+(?![\w-])/g) ?? [])];
106
+ const missingTools = [];
107
+ for (const w of named) {
108
+ if (listed.has(w) || fields.has(w) || prompts.has(w) || tools.some((n) => n.endsWith(`_${w}`)))
109
+ continue;
110
+ const parts = w.split('_');
111
+ if (!VERBS.has(parts[0]) || FIELD_ENDS.has(parts[parts.length - 1]))
112
+ continue;
113
+ // The first mention that's neither a value nor a subcommand, nor in a sentence that already says why.
114
+ const kept = mentions(text, w).find(counts);
115
+ if (kept)
116
+ missingTools.push({ name: w, at: kept.at });
117
+ }
118
+ // Resource URIs in a scheme the server lists resources under, that match no listed
119
+ // resource or template. Only when the lists were read in full (--lists resources).
120
+ const missingUris = [];
121
+ const resources = ctx.menu.resources;
122
+ const templates = ctx.menu.resourceTemplates;
123
+ const cut = ctx.lists?.read.some((r) => (r.kind === 'resources' || r.kind === 'resourceTemplates') && r.first.truncated);
124
+ if ((resources || templates) && !cut) {
125
+ const uris = new Set((resources ?? []).map((r) => r.uri).filter((u) => typeof u === 'string'));
126
+ const patterns = (templates ?? []).map((t) => t.uriTemplate).filter((u) => typeof u === 'string');
127
+ const schemes = new Set([...uris, ...patterns].map((u) => u.split('://')[0]));
128
+ const seen = new Set();
129
+ for (const m of text.matchAll(/\b[a-z][a-z0-9+.-]*:\/\/[^\s`'")\]<>,*]+/g)) {
130
+ const raw = m[0];
131
+ // Markdown and sentence ends: **acme://guide**, acme://guide.
132
+ const uri = raw.replace(/[.;:!?_]+$/, '');
133
+ const next = text[m.index + raw.length] ?? '';
134
+ // zavod://blog/<slug>: a placeholder in the text, not a URI to read
135
+ if (/[<{]/.test(next) || uri.endsWith('/') || seen.has(uri))
136
+ continue;
137
+ seen.add(uri);
138
+ const scheme = uri.split('://')[0];
139
+ if (!schemes.has(scheme) || scheme === 'http' || scheme === 'https')
140
+ continue;
141
+ if (uris.has(uri) || patterns.includes(uri) || patterns.some((p) => templatePattern(p).test(uri)))
142
+ continue;
143
+ missingUris.push({ name: uri, at: m.index });
144
+ }
145
+ }
146
+ // In the order the agent reads them: by the mention that counted.
147
+ missingTools.sort((a, b) => a.at - b.at);
148
+ if (!missingTools.length && !missingUris.length)
149
+ return [];
150
+ const names = (list) => list.map((x) => x.name).join(', ');
151
+ const what = [
152
+ missingTools.length ? `${count(missingTools.length, 'tool')} the menu doesn't list (${names(missingTools)})` : '',
153
+ missingUris.length ? `${count(missingUris.length, 'resource')} no listed resource or template matches (${names(missingUris)})` : '',
154
+ ].filter(Boolean);
155
+ // Listed without credentials, a menu may lack what a login adds (Dreamwork's guest mode).
156
+ const login = ctx.usedAuth ? '' : ' This menu was listed without credentials; if a login adds them, list with credentials to check.';
157
+ // A server with prompts whose list wasn't read: a prompt's name can read as a tool here.
158
+ const unreadPrompts = missingTools.length && ctx.capabilities.prompts !== undefined && !ctx.menu.prompts ? ' The server declares prompts and they weren\'t listed, so one of these may be a prompt: list them with --lists prompts.' : '';
159
+ const finding = {
160
+ // A tool name is read from the words, so unsure; a URI in the server's own scheme isn't.
161
+ ...(missingTools.length ? { confidence: 'unsure' } : {}),
162
+ message: `The server's instructions name ${what.join(', and ')}. A client may give the agent the instructions; an agent that follows them asks for something this server didn't offer, and gets an error.${login}${unreadPrompts}`,
163
+ detail: [...missingTools, ...missingUris].map(({ name, at }) => `${name}: “${sentenceAt(text, at, name.length)}”`),
164
+ fix: 'Name only what the server lists, in the words it lists them: rename the instructions or the tool, or say when one is available (after a login, behind an unlock tool).',
165
+ };
166
+ return [finding];
167
+ },
168
+ };
169
+ /** The whole sentence or line around position `at`, however long: what explains a name can be far from it. */
170
+ function wholeSentence(text, at) {
171
+ const start = Math.max(text.lastIndexOf('. ', at) + 1, text.lastIndexOf('\n', at) + 1);
172
+ const ends = [text.indexOf('. ', at), text.indexOf('\n', at)].filter((i) => i !== -1);
173
+ return text.slice(start, ends.length ? Math.min(...ends) + 1 : text.length);
174
+ }
175
+ /** The sentence around position `at`, to quote: at most 120 characters each way. */
176
+ function sentenceAt(text, at, length) {
177
+ const start = Math.max(text.lastIndexOf('. ', at) + 1, text.lastIndexOf('\n', at) + 1, at - 120);
178
+ const endDot = text.indexOf('. ', at + length);
179
+ const end = Math.min(endDot === -1 ? text.length : endDot + 1, at + length + 120);
180
+ return text.slice(start, end).replace(/\s+/g, ' ').trim();
181
+ }
@@ -19,6 +19,10 @@ export interface RuleContext {
19
19
  probes?: import('./determinism.js').Probe[];
20
20
  /** The stdio command is a container wrapper (docker run …): env vars may not reach the server. */
21
21
  wrapper?: boolean;
22
+ /** server/discover was refused with this HTTP status while the 2025 handshake worked (spec/discover-refused). */
23
+ discoverRefused?: number;
24
+ /** The handshake's instructions (instructions/unknown-name). */
25
+ instructions?: string;
22
26
  /** serverInfo as the handshake sent it, when there was one (snapshot): spec/server-info. */
23
27
  serverInfo?: {
24
28
  name?: string;
@@ -15,6 +15,7 @@ export declare function toolNameProblem(name: string): {
15
15
  } | undefined;
16
16
  export declare const toolName: Rule;
17
17
  export declare const discover: Rule;
18
+ export declare const discoverRefused: Rule;
18
19
  export declare const deprecated: Rule;
19
20
  /**
20
21
  * serverInfo { name, version } is required in the handshake (both protocol
@@ -176,6 +176,9 @@ export const discover = {
176
176
  run(ctx) {
177
177
  if (ctx.era !== 'legacy')
178
178
  return [];
179
+ // A refused server/discover is spec/discover-refused's, said once there.
180
+ if (ctx.discoverRefused)
181
+ return [];
179
182
  // A later process got 2026-07-28: this one's server/discover probe went unanswered in
180
183
  // time, and the SDK falls back to 2025 then (stdio). The server does speak 2026-07-28.
181
184
  if (ctx.laterModern) {
@@ -194,6 +197,23 @@ export const discover = {
194
197
  ];
195
198
  },
196
199
  };
200
+ export const discoverRefused = {
201
+ id: 'spec/discover-refused',
202
+ severity: 'warn',
203
+ summary: 'server/discover refused with 401 or 403 while the 2025 handshake serves the menu',
204
+ run(ctx) {
205
+ const status = ctx.discoverRefused;
206
+ if (!status)
207
+ return [];
208
+ const without = ctx.usedAuth ? 'with the same credentials' : 'without credentials';
209
+ return [
210
+ {
211
+ message: `server/discover got HTTP ${status} while the 2025 handshake (initialize) served the menu ${without}. A client that tries 2026-07-28 first stops at the ${status} and treats the server as one that ${status === 401 ? 'needs a login' : 'refuses access'}: the official TypeScript SDK client (2.4) with versionNegotiation auto fails with "Version negotiation failed: the server ${status === 401 ? 'requires authorization' : 'denied access'} (HTTP ${status})". Its default (legacy) never asks, so this bites as clients move to 2026-07-28. toolmenu fell back to 2025 and checked that.`,
212
+ fix: `Answer server/discover as initialize is answered: ${ctx.usedAuth ? 'with the same credentials' : 'without credentials, since the menu is open'}. A server that doesn't speak 2026-07-28 yet can answer it with the JSON-RPC error a 2025 server sends (method not found), which clients read as "use 2025".`,
213
+ },
214
+ ];
215
+ },
216
+ };
197
217
  export const deprecated = {
198
218
  id: 'spec/deprecated',
199
219
  severity: 'info',
package/dist/snapshot.js CHANGED
@@ -174,6 +174,8 @@ export async function snapshot(given, options = {}) {
174
174
  probes,
175
175
  wrapper: isContainerWrapper(target),
176
176
  serverInfo: connection.server,
177
+ ...(connection.instructions ? { instructions: connection.instructions } : {}),
178
+ ...(connection.discoverRefused ? { discoverRefused: connection.discoverRefused } : {}),
177
179
  server: serverArgs(target),
178
180
  identities,
179
181
  ...(invalid ? { invalidCredential: invalid } : {}),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "toolmenu",
3
- "version": "0.28.0",
3
+ "version": "0.29.0",
4
4
  "mcpName": "io.github.niksa90/toolmenu",
5
5
  "description": "Test your MCP server the way agents and clients meet it: the menu, the calls, the results, the sign-in, and every release after. No LLM involved.",
6
6
  "author": "Nikša Perović (https://niksa.me)",