toolmenu 0.25.2 → 0.27.1

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 (60) hide show
  1. package/README.md +170 -683
  2. package/dist/args.d.ts +14 -2
  3. package/dist/args.js +44 -1
  4. package/dist/auth-check.d.ts +27 -0
  5. package/dist/auth-check.js +177 -0
  6. package/dist/auth.d.ts +7 -0
  7. package/dist/auth.js +29 -1
  8. package/dist/auto.d.ts +8 -0
  9. package/dist/auto.js +9 -2
  10. package/dist/breakdown.js +14 -10
  11. package/dist/cli.js +151 -49
  12. package/dist/clients.d.ts +13 -2
  13. package/dist/clients.js +65 -11
  14. package/dist/config.js +6 -0
  15. package/dist/diff.d.ts +35 -1
  16. package/dist/diff.js +57 -12
  17. package/dist/failures.js +4 -3
  18. package/dist/help.d.ts +1 -1
  19. package/dist/help.js +45 -18
  20. package/dist/history.js +5 -0
  21. package/dist/html.d.ts +29 -0
  22. package/dist/html.js +360 -0
  23. package/dist/index.d.ts +3 -2
  24. package/dist/index.js +3 -2
  25. package/dist/init.d.ts +14 -0
  26. package/dist/init.js +20 -6
  27. package/dist/junit.d.ts +6 -1
  28. package/dist/junit.js +12 -3
  29. package/dist/mcp-env.d.ts +6 -0
  30. package/dist/mcp-env.js +6 -0
  31. package/dist/mcp.d.ts +11 -1
  32. package/dist/mcp.js +123 -22
  33. package/dist/menu.d.ts +6 -0
  34. package/dist/menu.js +12 -1
  35. package/dist/options.d.ts +10 -0
  36. package/dist/options.js +3 -0
  37. package/dist/report.d.ts +14 -0
  38. package/dist/report.js +57 -51
  39. package/dist/review.d.ts +48 -0
  40. package/dist/review.js +212 -0
  41. package/dist/rule-docs.json +49 -4
  42. package/dist/rules/clients.d.ts +11 -0
  43. package/dist/rules/clients.js +65 -2
  44. package/dist/rules/determinism.d.ts +3 -0
  45. package/dist/rules/determinism.js +44 -7
  46. package/dist/rules/ids.js +5 -1
  47. package/dist/rules/index.js +5 -2
  48. package/dist/rules/output.d.ts +21 -0
  49. package/dist/rules/output.js +49 -0
  50. package/dist/rules/search.js +1 -1
  51. package/dist/rules/spec.d.ts +19 -0
  52. package/dist/rules/spec.js +86 -1
  53. package/dist/sanitize.d.ts +42 -0
  54. package/dist/sanitize.js +142 -0
  55. package/dist/scan.d.ts +9 -2
  56. package/dist/scan.js +46 -24
  57. package/dist/session.d.ts +17 -0
  58. package/dist/session.js +119 -13
  59. package/dist/snapshot.js +2 -1
  60. package/package.json +5 -3
package/dist/args.d.ts CHANGED
@@ -19,6 +19,16 @@ export declare function fits(value: unknown, schema: JsonSchema | undefined): bo
19
19
  * tool that needs one is skipped, not called with junk.
20
20
  */
21
21
  export declare function synthesize(schema: JsonSchema | undefined, name?: string): Synthesized;
22
+ /** Made-up values are marked as toolmenu's, so they're easy to find in a server's logs. */
23
+ export declare const INVENTED = "toolmenu-test";
24
+ /**
25
+ * A value of the right type where the schema itself vouches for none, for
26
+ * `session --auto --call-everything`: the schema's own value first (synthesize),
27
+ * then a made-up one ("toolmenu-test", 1, a one-item list, an object of invented
28
+ * required fields). A pattern it can't satisfy gets the made-up string anyway: the
29
+ * tool's answer to a value it refuses is part of what's checked.
30
+ */
31
+ export declare function invent(schema: JsonSchema | undefined, name?: string, depth?: number): unknown;
22
32
  /**
23
33
  * A value the user gave (--value), made to fit the parameter: `5` is the number 5
24
34
  * for an integer and the string "5" for a string; JSON that doesn't fit the type
@@ -29,7 +39,7 @@ export declare function fitValue(given: {
29
39
  value: unknown;
30
40
  }, schema: JsonSchema | undefined): unknown;
31
41
  /** Where a tool's argument came from: the user (--value) or the schema. */
32
- export type ArgSource = 'value' | 'schema';
42
+ export type ArgSource = 'value' | 'schema' | 'invented';
33
43
  /**
34
44
  * Arguments for a tool's required parameters, or the ones it can't fill. `given`:
35
45
  * values the user supplied for this tool, by parameter name; they come first, and
@@ -38,7 +48,9 @@ export type ArgSource = 'value' | 'schema';
38
48
  export declare function synthesizeArgs(schema: JsonSchema | undefined, given?: Record<string, {
39
49
  raw?: string;
40
50
  value: unknown;
41
- }>): {
51
+ }>, options?: {
52
+ invent?: boolean;
53
+ }): {
42
54
  ok: true;
43
55
  args: Record<string, unknown>;
44
56
  sources: Record<string, ArgSource>;
package/dist/args.js CHANGED
@@ -107,6 +107,45 @@ export function synthesize(schema, name = '') {
107
107
  return { ok: false };
108
108
  }
109
109
  }
110
+ /** Made-up values are marked as toolmenu's, so they're easy to find in a server's logs. */
111
+ export const INVENTED = 'toolmenu-test';
112
+ /**
113
+ * A value of the right type where the schema itself vouches for none, for
114
+ * `session --auto --call-everything`: the schema's own value first (synthesize),
115
+ * then a made-up one ("toolmenu-test", 1, a one-item list, an object of invented
116
+ * required fields). A pattern it can't satisfy gets the made-up string anyway: the
117
+ * tool's answer to a value it refuses is part of what's checked.
118
+ */
119
+ export function invent(schema, name = '', depth = 0) {
120
+ const own = synthesize(schema, name);
121
+ if (own.ok)
122
+ return own.value;
123
+ if (!schema || typeof schema !== 'object' || depth > 8)
124
+ return INVENTED;
125
+ const branches = (schema.anyOf ?? schema.oneOf);
126
+ const type = Array.isArray(schema.type) ? schema.type.find((t) => t !== 'null') : schema.type;
127
+ if (!type && Array.isArray(branches) && branches.length)
128
+ return invent(branches.find((b) => b && typeof b === 'object' && b.type !== 'null') ?? branches[0], name, depth + 1);
129
+ switch (type) {
130
+ case 'boolean':
131
+ return false;
132
+ case 'integer':
133
+ case 'number':
134
+ return 1;
135
+ case 'array':
136
+ return [invent(schema.items, name, depth + 1)];
137
+ case 'object': {
138
+ const out = {};
139
+ for (const p of schema.required ?? [])
140
+ out[p] = invent(schema.properties?.[p], p, depth + 1);
141
+ return out;
142
+ }
143
+ case 'null':
144
+ return null;
145
+ default:
146
+ return INVENTED;
147
+ }
148
+ }
110
149
  /**
111
150
  * A value the user gave (--value), made to fit the parameter: `5` is the number 5
112
151
  * for an integer and the string "5" for a string; JSON that doesn't fit the type
@@ -127,7 +166,7 @@ export function fitValue(given, schema) {
127
166
  * values the user supplied for this tool, by parameter name; they come first, and
128
167
  * one for an optional parameter is passed too.
129
168
  */
130
- export function synthesizeArgs(schema, given = {}) {
169
+ export function synthesizeArgs(schema, given = {}, options = {}) {
131
170
  const args = {};
132
171
  const sources = {};
133
172
  const missing = [];
@@ -143,6 +182,10 @@ export function synthesizeArgs(schema, given = {}) {
143
182
  args[param] = v.value;
144
183
  sources[param] = 'schema';
145
184
  }
185
+ else if (options.invent) {
186
+ args[param] = invent(schema?.properties?.[param], param);
187
+ sources[param] = 'invented';
188
+ }
146
189
  else
147
190
  missing.push(param);
148
191
  }
@@ -0,0 +1,27 @@
1
+ import type { Finding } from './types.js';
2
+ export interface AuthCheck {
3
+ url: string;
4
+ /** What the unauthenticated initialize got: the status, and the WWW-Authenticate header. */
5
+ status?: number;
6
+ wwwAuthenticate?: string;
7
+ /** Where the protected resource metadata was found, and how. */
8
+ metadataUrl?: string;
9
+ foundBy?: 'header' | 'well-known path' | 'well-known root';
10
+ resource?: string;
11
+ authorizationServers?: string[];
12
+ /** The first authorization server's metadata URL, and what it says. */
13
+ serverMetadataUrl?: string;
14
+ pkce?: string[];
15
+ registration?: 'dynamic' | 'client-id-metadata' | 'both' | 'none';
16
+ findings: Finding[];
17
+ }
18
+ /** `resource_metadata="…"` from a WWW-Authenticate header. */
19
+ export declare function resourceMetadataOf(header: string | undefined): string | undefined;
20
+ /** The well-known URIs RFC 9728 and the spec name, path-specific first. */
21
+ export declare function wellKnownResource(url: string): {
22
+ path: string;
23
+ root: string;
24
+ };
25
+ /** The spec's order for an authorization server's metadata: RFC 8414 then OpenID Connect, path-aware. */
26
+ export declare function serverMetadataUrls(issuer: string): string[];
27
+ export declare function authCheck(url: string, timeoutMs?: number): Promise<AuthCheck>;
@@ -0,0 +1,177 @@
1
+ const INIT = { jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'toolmenu-auth-check', version: '1' } } };
2
+ async function getJson(url, timeoutMs) {
3
+ try {
4
+ const r = await fetch(url, { headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(timeoutMs), redirect: 'follow' });
5
+ if (!r.ok)
6
+ return { status: r.status };
7
+ const json = (await r.json().catch(() => undefined));
8
+ return { status: r.status, json: json && typeof json === 'object' && !Array.isArray(json) ? json : undefined };
9
+ }
10
+ catch {
11
+ return { status: 0 };
12
+ }
13
+ }
14
+ /** `resource_metadata="…"` from a WWW-Authenticate header. */
15
+ export function resourceMetadataOf(header) {
16
+ return header ? /resource_metadata\s*=\s*"([^"]+)"/i.exec(header)?.[1] ?? /resource_metadata\s*=\s*([^\s,]+)/i.exec(header)?.[1] : undefined;
17
+ }
18
+ /**
19
+ * Whether failed fetches show the document isn't there (404, 410, or not JSON) or only
20
+ * that it couldn't be read: a 401/403, a 5xx, or no answer (a firewall, a proxy that
21
+ * blocks the host). The second is no finding against the server.
22
+ */
23
+ function unreadable(statuses) {
24
+ return statuses.some((s) => s === 0 || s === 401 || s === 403 || s === 429 || s >= 500);
25
+ }
26
+ /** The well-known URIs RFC 9728 and the spec name, path-specific first. */
27
+ export function wellKnownResource(url) {
28
+ const u = new URL(url);
29
+ const path = u.pathname.replace(/\/$/, '');
30
+ return { path: `${u.origin}/.well-known/oauth-protected-resource${path}`, root: `${u.origin}/.well-known/oauth-protected-resource` };
31
+ }
32
+ /** The spec's order for an authorization server's metadata: RFC 8414 then OpenID Connect, path-aware. */
33
+ export function serverMetadataUrls(issuer) {
34
+ const u = new URL(issuer);
35
+ const path = u.pathname.replace(/\/$/, '');
36
+ return path
37
+ ? [`${u.origin}/.well-known/oauth-authorization-server${path}`, `${u.origin}/.well-known/openid-configuration${path}`, `${u.origin}${path}/.well-known/openid-configuration`]
38
+ : [`${u.origin}/.well-known/oauth-authorization-server`, `${u.origin}/.well-known/openid-configuration`];
39
+ }
40
+ export async function authCheck(url, timeoutMs = 15_000) {
41
+ const out = { url, findings: [] };
42
+ const say = (rule, severity, message, fix, detail) => out.findings.push({ rule, severity, message, ...(fix ? { fix } : {}), ...(detail?.length ? { detail } : {}) });
43
+ try {
44
+ const r = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream', 'MCP-Protocol-Version': '2025-11-25' }, body: JSON.stringify(INIT), signal: AbortSignal.timeout(timeoutMs) });
45
+ out.status = r.status;
46
+ out.wwwAuthenticate = r.headers.get('www-authenticate') ?? undefined;
47
+ await r.body?.cancel().catch(() => { });
48
+ }
49
+ catch (error) {
50
+ say('auth/discovery', 'error', `Couldn't reach ${url}: ${error instanceof Error ? error.message : String(error)}.`, 'Check the URL and the network, then run it again.');
51
+ return out;
52
+ }
53
+ if (out.status !== 401) {
54
+ say('auth/discovery', 'info', out.status && out.status < 300 ? `${url} answered without credentials (HTTP ${out.status}), so it doesn't ask for OAuth: nothing to check.` : `${url} answered HTTP ${out.status} without credentials, not 401, so a client isn't told to log in.`, out.status === 403 ? 'A server that wants OAuth answers 401 with WWW-Authenticate, not 403.' : undefined);
55
+ return out;
56
+ }
57
+ // 1. Where the protected resource metadata is: the header first, then the well-known URIs.
58
+ const fromHeader = resourceMetadataOf(out.wwwAuthenticate);
59
+ const known = wellKnownResource(url);
60
+ const tries = [...(fromHeader ? [[fromHeader, 'header']] : []), [known.path, 'well-known path'], [known.root, 'well-known root']];
61
+ let prm;
62
+ const prmStatuses = [];
63
+ for (const [where, how] of tries) {
64
+ const got = await getJson(where, timeoutMs);
65
+ prmStatuses.push(got.status);
66
+ if (got.json) {
67
+ prm = got.json;
68
+ out.metadataUrl = where;
69
+ out.foundBy = how;
70
+ break;
71
+ }
72
+ }
73
+ if (!out.wwwAuthenticate && !prm) {
74
+ say('auth/discovery', 'info', `The 401 has no WWW-Authenticate header, and there's no OAuth protected resource metadata, so the server doesn't advertise OAuth. Authorization is OPTIONAL in MCP: if it takes an API key or another credential, that's fine; if it means OAuth, no client can find where to log in.`, 'If the server uses OAuth, answer 401 with WWW-Authenticate: Bearer resource_metadata="…" and serve the metadata (RFC 9728).', [`tried ${known.path}`, `tried ${known.root}`]);
75
+ return out;
76
+ }
77
+ if (!out.wwwAuthenticate) {
78
+ say('auth/discovery', prm ? 'info' : 'error', `The 401 has no WWW-Authenticate header${prm ? ', so clients find the metadata only at the well-known URI' : ''}.`, 'Answer 401 with WWW-Authenticate: Bearer resource_metadata="<your metadata URL>" (RFC 9728 §5.1).');
79
+ }
80
+ else if (!fromHeader && prm) {
81
+ say('auth/discovery', 'info', `The 401's WWW-Authenticate header has no resource_metadata, so clients find the metadata only at the well-known URI (${out.foundBy}).`, 'Add resource_metadata="<your metadata URL>" to the WWW-Authenticate header (RFC 9728 §5.1).', [`WWW-Authenticate: ${out.wwwAuthenticate.slice(0, 200)}`]);
82
+ }
83
+ if (!prm && unreadable(prmStatuses)) {
84
+ say('auth/discovery', 'info', `Couldn't read the protected resource metadata (HTTP ${prmStatuses.join(', ')}), so whether it's there wasn't checked: a 403, a 5xx or no answer says nothing about the document.`, 'Run the check again from another network.', tries.map(([u], i) => `${u}: HTTP ${prmStatuses[i] || 'no answer'}`));
85
+ return out;
86
+ }
87
+ if (!prm) {
88
+ say('auth/discovery', 'error', `No OAuth protected resource metadata where the spec says to look, so a client that follows it can't find where to log in. MCP servers MUST serve it (RFC 9728), named in the 401's WWW-Authenticate header or at a well-known URI.`, 'Serve the metadata at /.well-known/oauth-protected-resource (with the MCP path appended), and name it in the 401: WWW-Authenticate: Bearer resource_metadata="…".', [...(fromHeader ? [`named in WWW-Authenticate: ${fromHeader} (not JSON, or not there)`] : []), `tried ${known.path}`, `tried ${known.root}`]);
89
+ return out;
90
+ }
91
+ if (fromHeader && out.metadataUrl !== fromHeader) {
92
+ say('auth/discovery', 'warn', `The 401's WWW-Authenticate names ${fromHeader}, which isn't there, but the well-known URI serves the metadata. Clients use the header's URL when it's present.`, 'Point resource_metadata at the URL that serves the metadata.');
93
+ }
94
+ // 2. The metadata: its authorization servers, and its resource.
95
+ out.resource = typeof prm.resource === 'string' ? prm.resource : undefined;
96
+ const servers = Array.isArray(prm.authorization_servers) ? prm.authorization_servers.filter((s) => typeof s === 'string') : [];
97
+ out.authorizationServers = servers;
98
+ // Authorization server metadata (RFC 8414: issuer, authorization_endpoint) served where
99
+ // the protected resource metadata belongs: a mix-up worth naming (mcp-server.zomato.com).
100
+ const serverDoc = typeof prm.issuer === 'string' && typeof prm.authorization_endpoint === 'string';
101
+ if (!servers.length) {
102
+ say('auth/resource-metadata', 'error', serverDoc
103
+ ? `${out.metadataUrl} serves authorization server metadata (issuer, authorization_endpoint: RFC 8414), not protected resource metadata (RFC 9728), so it lists no authorization_servers. A client that follows the 2025-06-18 or later spec can't find where to log in; one that falls back to the server's own origin as its authorization server (the 2025-03-26 way) may still manage.`
104
+ : `The protected resource metadata (${out.metadataUrl}) lists no authorization_servers. It MUST list at least one, or a client has nowhere to log in.`, serverDoc
105
+ ? `Serve protected resource metadata there instead: {"resource": "${url}", "authorization_servers": ["${typeof prm.issuer === 'string' ? prm.issuer.replace(/\/$/, '') : 'https://your-auth-server'}"]}, and keep the authorization server metadata at /.well-known/oauth-authorization-server.`
106
+ : 'Add "authorization_servers": ["https://your-auth-server"] to the metadata.');
107
+ }
108
+ // RFC 9728 §3.3: metadata named by WWW-Authenticate must have the URL the client
109
+ // called as its resource; metadata from a well-known URI, the identifier that URI was
110
+ // built from (the origin for the root one, origin and path for the path one).
111
+ const u = new URL(url);
112
+ const expected = out.foundBy === 'well-known root' ? u.origin : out.foundBy === 'well-known path' ? `${u.origin}${u.pathname.replace(/\/$/, '')}` : url;
113
+ if (!out.resource) {
114
+ // Said once, with the mix-up, when it's the authorization server's document.
115
+ if (!serverDoc)
116
+ say('auth/resource-metadata', 'error', `The protected resource metadata (${out.metadataUrl}) has no "resource". RFC 9728 requires it, and a client checks it against the server it's connecting to.`, `Add "resource": "${url}" to the metadata.`);
117
+ }
118
+ else if (out.resource !== expected) {
119
+ const sameButSlash = out.resource.replace(/\/$/, '') === expected.replace(/\/$/, '');
120
+ // The official SDK's checkResourceAllowed takes a resource on the same origin whose
121
+ // path is a parent of the URL's (trailing slashes aside); RFC 9728 says identical.
122
+ // What the official SDK compares: the server's URL against the resource, a same-origin
123
+ // parent path accepted (checkResourceAllowed), whatever URI the metadata came from.
124
+ const parent = (() => {
125
+ try {
126
+ const r = new URL(out.resource);
127
+ const e = new URL(url);
128
+ const slash = (p) => (p.endsWith('/') ? p : p + '/');
129
+ return r.origin === e.origin && slash(e.pathname).startsWith(slash(r.pathname));
130
+ }
131
+ catch {
132
+ return false;
133
+ }
134
+ })();
135
+ say('auth/resource-metadata', sameButSlash || parent ? 'warn' : 'error', `The protected resource metadata (${out.foundBy === 'header' ? 'named by WWW-Authenticate' : `at the ${out.foundBy} URI`}) says resource "${out.resource}", not "${expected}"${out.foundBy === 'header' ? ', the URL the client called' : ', the identifier that URI is built from'}. RFC 9728 §3.3: a client MUST NOT use metadata whose resource isn't identical to it.${sameButSlash ? ' Only a trailing slash differs: the official MCP SDK client accepts it, a client that follows the RFC to the letter doesn\'t.' : parent ? (out.resource.replace(/\/$/, '') === url.replace(/\/$/, '') ? ' It\'s the server\'s own URL, which the official MCP SDK client compares against and accepts; a client that follows the RFC to the letter doesn\'t.' : ' It\'s a parent of the server\'s URL on the same origin: the official MCP SDK client accepts it, a client that follows the RFC to the letter doesn\'t.') : ''}`, `Make "resource" exactly ${expected}.`);
136
+ }
137
+ if (!servers.length)
138
+ return out;
139
+ // 3. The first authorization server's metadata: PKCE, and how a client registers.
140
+ let as;
141
+ const asStatuses = [];
142
+ for (const where of serverMetadataUrls(servers[0])) {
143
+ const got = await getJson(where, timeoutMs);
144
+ asStatuses.push(got.status);
145
+ if (got.json) {
146
+ as = got.json;
147
+ out.serverMetadataUrl = where;
148
+ break;
149
+ }
150
+ }
151
+ if (!as && unreadable(asStatuses)) {
152
+ say('auth/server-metadata', 'info', `Couldn't read ${servers[0]}'s authorization server metadata (HTTP ${asStatuses.join(', ')}), so PKCE and registration weren't checked: a 403, a 5xx or no answer says nothing about whether it's there.`, 'Run the check again from another network.', serverMetadataUrls(servers[0]).map((u, i) => `${u}: HTTP ${asStatuses[i] || 'no answer'}`));
153
+ return out;
154
+ }
155
+ if (!as) {
156
+ say('auth/server-metadata', 'error', `No authorization server metadata for ${servers[0]} at the URIs the spec has clients try (RFC 8414, then OpenID Connect Discovery), so a client can't find where to send the user.`, `Serve the metadata at ${serverMetadataUrls(servers[0])[0]}.`, serverMetadataUrls(servers[0]).map((u) => `tried ${u}`));
157
+ return out;
158
+ }
159
+ out.pkce = Array.isArray(as.code_challenge_methods_supported) ? as.code_challenge_methods_supported.map(String) : undefined;
160
+ if (!out.pkce?.includes('S256')) {
161
+ say('auth/pkce', 'error', out.pkce
162
+ ? `The authorization server's metadata (${out.serverMetadataUrl}) lists code_challenge_methods_supported ${JSON.stringify(out.pkce)}, without S256. MCP clients MUST use S256 when they can and MUST verify it's supported, so a client that follows the spec can't log in.`
163
+ : (out.serverMetadataUrl ?? '').includes('openid-configuration')
164
+ ? // OpenID Connect Discovery doesn't define the field, but MCP 2025-11-25 requires it
165
+ // of providers that use it. Its absence says PKCE isn't advertised, not that it's
166
+ // missing: Entra ID supports S256 and documents it, and omits the field.
167
+ `The authorization server's OpenID Connect metadata (${out.serverMetadataUrl}) has no code_challenge_methods_supported. That doesn't show the server lacks PKCE (some support it without saying so here), but MCP 2025-11-25 requires providers that use OpenID Connect Discovery to include it, and tells clients to verify it and refuse to go on without it. So a client that follows the MCP spec to the letter won't log in, whatever the server supports.`
168
+ : `The authorization server's metadata (${out.serverMetadataUrl}) has no code_challenge_methods_supported. Under RFC 8414 that means it doesn't support PKCE, and MCP clients MUST refuse to go on without it, so a client that follows the spec can't log in.`, 'Add "code_challenge_methods_supported": ["S256"] to the authorization server metadata (and support it).');
169
+ }
170
+ const dynamic = typeof as.registration_endpoint === 'string';
171
+ const cimd = as.client_id_metadata_document_supported === true;
172
+ out.registration = dynamic && cimd ? 'both' : dynamic ? 'dynamic' : cimd ? 'client-id-metadata' : 'none';
173
+ if (out.registration === 'none') {
174
+ say('auth/registration', 'info', `The authorization server offers no registration endpoint and no Client ID Metadata Documents, so every client needs an app registered ahead of time (toolmenu: --client-id).`, 'Support Client ID Metadata Documents (the spec\'s SHOULD) or dynamic client registration, so clients can log in without one.');
175
+ }
176
+ return out;
177
+ }
package/dist/auth.d.ts CHANGED
@@ -51,6 +51,13 @@ export declare class StoredOAuthProvider implements OAuthClientProvider {
51
51
  discoveryState(): Promise<OAuthDiscoveryState | undefined>;
52
52
  invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): Promise<void>;
53
53
  }
54
+ /**
55
+ * Why an authorization URL from a server's metadata mustn't be opened, or undefined
56
+ * when it may be. Only https (or http to a loopback address): any other scheme
57
+ * (file:, smb:, an app's own) would have the system open a file or start a program,
58
+ * and the browser opener (xdg-open, open, rundll32) does whatever the scheme says.
59
+ */
60
+ export declare function unsafeAuthorizationUrl(url: URL): string | undefined;
54
61
  export declare class LoginNeededError extends Error {
55
62
  constructor(serverUrl: string, why?: string);
56
63
  }
package/dist/auth.js CHANGED
@@ -9,6 +9,7 @@ import { Client, StreamableHTTPClientTransport, UnauthorizedError } from '@model
9
9
  import { VERSION } from './version.js';
10
10
  import { endSession } from './close.js';
11
11
  import { quietExclusions } from './connect.js';
12
+ import { plain } from './sanitize.js';
12
13
  /**
13
14
  * The redirect port. Fixed, not random: dynamic registration records the exact
14
15
  * redirect URI, so a new port would invalidate the stored client on every login.
@@ -134,6 +135,10 @@ export class StoredOAuthProvider {
134
135
  if (!this.options.interactive) {
135
136
  throw new LoginNeededError(this.serverUrl, whyLoginNeeded(await this.stored(), this.removedLogin));
136
137
  }
138
+ // The URL comes from the server's metadata: checked before anything opens or prints it.
139
+ const refused = unsafeAuthorizationUrl(authorizationUrl);
140
+ if (refused)
141
+ throw new Error(`${this.serverUrl} sent a login address toolmenu won't open: ${refused}.\n→ Next: Check the server is the one you meant. If it is, ask its authors to serve the authorization endpoint over https.`);
137
142
  await this.options.onRedirect?.(authorizationUrl);
138
143
  }
139
144
  async saveCodeVerifier(codeVerifier) {
@@ -177,6 +182,29 @@ export class StoredOAuthProvider {
177
182
  await this.update(patch);
178
183
  }
179
184
  }
185
+ /** Hosts that only reach this machine: plain http is fine there (RFC 8252, OAuth 2.1). */
186
+ function isLoopback(hostname) {
187
+ const h = hostname.toLowerCase().replace(/\.$/, '');
188
+ // [::ffff:7f00:1]: 127.0.0.1 written as IPv6 (the URL parser normalizes [::ffff:127.0.0.1] to it).
189
+ return h === 'localhost' || h.endsWith('.localhost') || /^127(\.\d{1,3}){3}$/.test(h) || h === '[::1]' || /^\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\]$/.test(h);
190
+ }
191
+ /**
192
+ * Why an authorization URL from a server's metadata mustn't be opened, or undefined
193
+ * when it may be. Only https (or http to a loopback address): any other scheme
194
+ * (file:, smb:, an app's own) would have the system open a file or start a program,
195
+ * and the browser opener (xdg-open, open, rundll32) does whatever the scheme says.
196
+ */
197
+ export function unsafeAuthorizationUrl(url) {
198
+ const shown = url.href.length > 200 ? `${url.href.slice(0, 199)}…` : url.href;
199
+ if (url.protocol === 'https:')
200
+ return url.username || url.password ? `it carries credentials (${url.protocol}//user:password@…)` : undefined;
201
+ if (url.protocol === 'http:') {
202
+ if (url.username || url.password)
203
+ return `it carries credentials (${url.protocol}//user:password@…)`;
204
+ return isLoopback(url.hostname) ? undefined : `it's plain http to another machine (${JSON.stringify(shown)}); only https, or http to this machine, is opened`;
205
+ }
206
+ return `its scheme is ${JSON.stringify(url.protocol)} (${JSON.stringify(shown)}), not https`;
207
+ }
180
208
  /**
181
209
  * Why snapshot or session needs a login, from what's stored: nothing, a registration
182
210
  * from a login that never finished, tokens the server refused, or a login the server
@@ -404,7 +432,7 @@ function openInBrowser(url) {
404
432
  // toolmenu only lists tools and calls read-only ones, but it asks for the
405
433
  // server's default scopes, as other clients do: some servers show tools by scope.
406
434
  if (scope)
407
- process.stderr.write(`Asking for the server's default scopes: ${scope} (narrower: --scope; toolmenu never calls a write tool on its own)\n`);
435
+ process.stderr.write(`Asking for the server's default scopes: ${plain(scope)} (narrower: --scope; toolmenu never calls a write tool on its own)\n`);
408
436
  process.stderr.write(`Opening your browser to log in. If it doesn't open, visit:\n ${url.href}\n`);
409
437
  // Not `cmd /c start` on Windows: cmd reads the URL's `&` as a command separator,
410
438
  // cutting the URL, and the URL comes from the server's metadata. rundll32 opens
package/dist/auto.d.ts CHANGED
@@ -36,6 +36,12 @@ export interface AutoOptions {
36
36
  * never called.
37
37
  */
38
38
  assumeReadOnly?: string[];
39
+ /**
40
+ * --call-everything: every tool, once, writes and open-world ones included, with a
41
+ * made-up value where the schema gives none. Only for a stdio server in a sandbox
42
+ * with nothing to lose (the bench's sealed container): the CLI refuses it over HTTP.
43
+ */
44
+ everything?: boolean;
39
45
  }
40
46
  export type SkipReason = 'not read-only' | 'unmarked' | 'open world' | 'needs values' | 'over the call budget' | 'over the per-unlock budget';
41
47
  export interface AutoPlan {
@@ -70,6 +76,8 @@ export type AutoSummary = Pick<AutoPlan, 'called' | 'skipped'> & Partial<Pick<Au
70
76
  tool: string;
71
77
  calls: number;
72
78
  }[];
79
+ /** --call-everything: every tool called, with made-up values where the schema gives none. */
80
+ everything?: boolean;
73
81
  };
74
82
  /** Marked or named as a write: never called on the user's word. Says why, or undefined. */
75
83
  export declare function writeSign(tool: MenuTool): string | undefined;
package/dist/auto.js CHANGED
@@ -25,7 +25,8 @@ export function writeSign(tool) {
25
25
  * in assumeReadOnly and nothing marks or names it as a write.
26
26
  */
27
27
  export function autoScenario(menu, options = {}) {
28
- const maxCalls = options.maxCalls ?? 20;
28
+ // --call-everything: every tool once, unless --max-calls says otherwise.
29
+ const maxCalls = options.maxCalls ?? (options.everything ? Infinity : 20);
29
30
  const skipped = [];
30
31
  const ignored = [];
31
32
  const byName = new Map(menu.tools.map((t) => [t.name, t]));
@@ -66,6 +67,12 @@ export function autoScenario(menu, options = {}) {
66
67
  if (unlocking.has(tool.name))
67
68
  continue;
68
69
  const a = tool.annotations ?? {};
70
+ if (options.everything) {
71
+ const filled = synthesizeArgs(tool.inputSchema, perTool.get(tool.name), { invent: true });
72
+ if (filled.ok)
73
+ candidates.push({ tool, args: filled.args, rank: rank(tool, filled.args), valued: Object.values(filled.sources).includes('value') });
74
+ continue;
75
+ }
69
76
  if (!readOnly(tool)) {
70
77
  const write = a.readOnlyHint === true && namedWrite(tool)
71
78
  ? `the server marks it readOnlyHint, but its name starts with "${leadingVerb(tool.name, common)}", a write: not called on the hint alone`
@@ -180,7 +187,7 @@ export function autoScenario(menu, options = {}) {
180
187
  steps.push({ kind: 'call', tool: chosen[0].tool.name, args: chosen[0].args, ...(chosen[0].probe ? { probe: chosen[0].probe } : {}) });
181
188
  const called = [...creators.map((c) => c.tool.name), ...chosen.map((c) => c.tool.name), ...unlocks.map((u) => u.tool.name)];
182
189
  return {
183
- scenario: { allowWrites: false, steps, ...(assumed.size ? { assumeReadOnly: [...assumed] } : {}) },
190
+ scenario: { allowWrites: options.everything === true, steps, ...(assumed.size ? { assumeReadOnly: [...assumed] } : {}) },
184
191
  called,
185
192
  assumed: called.filter((n) => assumed.has(n)),
186
193
  withValues: chosen.filter((c) => c.valued).map((c) => c.tool.name),
package/dist/breakdown.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { mdCode, mdText, plain } from './sanitize.js';
1
2
  import { canonical } from './compare.js';
2
3
  import { usedEntries } from './schema-ref.js';
3
4
  import { countTokens } from './menu.js';
@@ -129,6 +130,9 @@ function repeatedBlocks(menu) {
129
130
  .map(({ waste: _w, ...r }) => r);
130
131
  }
131
132
  function enumValues(schema) {
133
+ // A property schema can be anything a server sends (null, true): only an object has an enum.
134
+ if (!schema || typeof schema !== 'object')
135
+ return [];
132
136
  if (Array.isArray(schema.enum))
133
137
  return schema.enum;
134
138
  if (Array.isArray(schema.items?.enum))
@@ -137,7 +141,7 @@ function enumValues(schema) {
137
141
  }
138
142
  const tok = (x) => `~${x.toLocaleString('en-US')}`;
139
143
  const pct = (x) => `${Math.round(x * 100)}%`;
140
- const list = (names, total) => `${names.join(', ')}${total > names.length ? ', …' : ''}`;
144
+ const list = (names, total) => `${names.map(plain).join(', ')}${total > names.length ? ', …' : ''}`;
141
145
  /** A tool's schema can't refer to another tool's: said once, after the repeated blocks that span tools. */
142
146
  const ACROSS_TOOLS = "A tool's schema can't $ref another tool's, so a block shared across tools is paid once per tool: only a smaller block saves tokens there.";
143
147
  function items(b, tools) {
@@ -151,13 +155,13 @@ function items(b, tools) {
151
155
  }]
152
156
  : [];
153
157
  // Two different blocks under the same name ("form") are told apart by where the first one is.
154
- const label = (r) => (b.repeated.filter((x) => x.tools > 1 && x.param === r.param).length > 1 && r.where[0] ? `${r.param} at ${r.where[0]}` : r.param);
158
+ const label = (r) => plain(b.repeated.filter((x) => x.tools > 1 && x.param === r.param).length > 1 && r.where[0] ? `${r.param} at ${r.where[0]}` : r.param);
155
159
  const repeated = b.repeated.map((r) => {
156
160
  if (r.tools === 1) {
157
161
  const places = list(r.where.map((w) => w.slice(r.withinTool.length + 1)), r.count);
158
- return { kind: 'repeated', text: `repeated: one ${tok(r.tokens)}-token block ×${r.count} in ${r.withinTool} (${places})${r.saving > 0 ? `: a $defs entry could save ${tok(r.saving)}` : ''}`, ...(r.saving > 0 ? { fix: `Move the block into ${r.withinTool}'s $defs once and $ref it.` } : {}) };
162
+ return { kind: 'repeated', text: `repeated: one ${tok(r.tokens)}-token block ×${r.count} in ${plain(r.withinTool)} (${places})${r.saving > 0 ? `: a $defs entry could save ${tok(r.saving)}` : ''}`, ...(r.saving > 0 ? { fix: `Move the block into ${plain(r.withinTool)}'s $defs once and $ref it.` } : {}) };
159
163
  }
160
- const inside = r.within > 1 ? `, ×${r.within} inside ${r.withinTool}${r.saving > 0 ? `: a $defs entry there could save ${tok(r.saving)}` : ''}` : '';
164
+ const inside = r.within > 1 ? `, ×${r.within} inside ${plain(r.withinTool)}${r.saving > 0 ? `: a $defs entry there could save ${tok(r.saving)}` : ''}` : '';
161
165
  return { kind: 'repeated', text: `repeated: ${label(r)} (${tok(r.tokens)} tokens) in ${r.tools} tools, ${tok(r.total)} in all${inside}` };
162
166
  });
163
167
  // A small menu gets no breakdown, but waste inside one tool is worth a line anyway.
@@ -166,9 +170,9 @@ function items(b, tools) {
166
170
  return within.length ? { title: 'Where the tokens go (estimate):', items: within } : undefined;
167
171
  }
168
172
  const topShare = b.top.reduce((s, t) => s + t.share, 0);
169
- const width = Math.min(40, Math.max(...b.top.map((t) => t.name.length)));
170
- const top = b.top.map((t) => ({ kind: 'top', text: `${pct(t.share).padStart(4)} ${t.name.padEnd(width)} ${tok(t.tokens).padStart(7)} tokens (description ${tok(t.description)}, schema ${tok(t.schema)})` }));
171
- const enums = b.enums.map((e) => ({ kind: 'enum', text: `enum: ${e.tool}.${e.param} has ${e.values} values, ${tok(e.tokens)} tokens` }));
173
+ const width = Math.min(40, Math.max(...b.top.map((t) => plain(t.name).length)));
174
+ const top = b.top.map((t) => ({ kind: 'top', text: `${pct(t.share).padStart(4)} ${plain(t.name).padEnd(width)} ${tok(t.tokens).padStart(7)} tokens (description ${tok(t.description)}, schema ${tok(t.schema)})` }));
175
+ const enums = b.enums.map((e) => ({ kind: 'enum', text: `enum: ${plain(`${e.tool}.${e.param}`)} has ${e.values} values, ${tok(e.tokens)} tokens` }));
172
176
  const note = b.repeated.some((r) => r.tools > 1) ? [{ kind: 'note', text: ACROSS_TOOLS }] : [];
173
177
  return { title: `Where the tokens go (estimate): the top ${b.top.length} tools are ${pct(topShare)} of the menu`, items: [...top, ...unused, ...enums, ...repeated, ...note] };
174
178
  }
@@ -192,13 +196,13 @@ export function breakdownMarkdown(b, tools) {
192
196
  const found = items(b, tools);
193
197
  if (!found)
194
198
  return [];
195
- const cell = (t) => t.replace(/\|/g, '\\|');
196
- const code = (t) => t.replace(/\$defs/g, '`$defs`');
199
+ // The text has the server's names in it (escaped for the terminal already): made inert for markdown, $defs as code.
200
+ const code = (t) => mdText(t.replace(/\$defs/g, '`$defs`'));
197
201
  const lines = ['', `<details><summary>${found.title}</summary>`, ''];
198
202
  if (tools >= 5) {
199
203
  lines.push('| Share | Tool | Tokens | Description | Schema |', '|---:|---|---:|---:|---:|');
200
204
  for (const t of b.top)
201
- lines.push(`| ${pct(t.share)} | \`${cell(t.name)}\` | ${tok(t.tokens)} | ${tok(t.description)} | ${tok(t.schema)} |`);
205
+ lines.push(`| ${pct(t.share)} | ${mdCode(t.name, { cell: true })} | ${tok(t.tokens)} | ${tok(t.description)} | ${tok(t.schema)} |`);
202
206
  lines.push('');
203
207
  }
204
208
  for (const item of found.items.filter((i) => i.kind !== 'top' && i.kind !== 'note')) {