toolmenu 0.25.2 → 0.27.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 +248 -29
- package/dist/args.d.ts +14 -2
- package/dist/args.js +44 -1
- package/dist/auth-check.d.ts +27 -0
- package/dist/auth-check.js +177 -0
- package/dist/auth.d.ts +7 -0
- package/dist/auth.js +29 -1
- package/dist/auto.d.ts +8 -0
- package/dist/auto.js +9 -2
- package/dist/breakdown.js +14 -10
- package/dist/cli.js +150 -48
- package/dist/clients.d.ts +13 -2
- package/dist/clients.js +65 -11
- package/dist/config.js +6 -0
- package/dist/diff.d.ts +35 -1
- package/dist/diff.js +57 -12
- package/dist/failures.js +4 -3
- package/dist/help.d.ts +1 -1
- package/dist/help.js +43 -16
- package/dist/history.js +5 -0
- package/dist/html.d.ts +29 -0
- package/dist/html.js +360 -0
- package/dist/index.d.ts +3 -2
- package/dist/index.js +3 -2
- package/dist/init.d.ts +14 -0
- package/dist/init.js +20 -6
- package/dist/junit.d.ts +6 -1
- package/dist/junit.js +12 -3
- package/dist/mcp-env.d.ts +6 -0
- package/dist/mcp-env.js +6 -0
- package/dist/mcp.d.ts +10 -0
- package/dist/mcp.js +76 -15
- package/dist/menu.d.ts +6 -0
- package/dist/menu.js +12 -1
- package/dist/options.d.ts +10 -0
- package/dist/options.js +3 -0
- package/dist/report.d.ts +14 -0
- package/dist/report.js +57 -51
- package/dist/review.d.ts +48 -0
- package/dist/review.js +212 -0
- package/dist/rule-docs.json +49 -4
- package/dist/rules/clients.d.ts +11 -0
- package/dist/rules/clients.js +65 -2
- package/dist/rules/determinism.d.ts +3 -0
- package/dist/rules/determinism.js +44 -7
- package/dist/rules/ids.js +5 -1
- package/dist/rules/index.js +5 -2
- package/dist/rules/output.d.ts +21 -0
- package/dist/rules/output.js +49 -0
- package/dist/rules/search.js +1 -1
- package/dist/rules/spec.d.ts +19 -0
- package/dist/rules/spec.js +86 -1
- package/dist/sanitize.d.ts +42 -0
- package/dist/sanitize.js +142 -0
- package/dist/scan.d.ts +9 -2
- package/dist/scan.js +46 -24
- package/dist/session.d.ts +17 -0
- package/dist/session.js +119 -13
- package/dist/snapshot.js +2 -1
- package/package.json +5 -3
|
@@ -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
|
-
|
|
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:
|
|
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
|
-
|
|
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)} |
|
|
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')) {
|