toolmenu 0.8.0 → 0.10.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
@@ -29,7 +29,7 @@ No LLM anywhere: the same inputs give the same answer, so it can sit in CI.
29
29
  (`history` installs old versions with today's dependencies, so it records what they
30
30
  serve now, which can differ from what they shipped with: FINDINGS F4.)
31
31
 
32
- > **Status: 0.8, early.** Spec in [docs/SPEC.md](https://github.com/niksa90/toolmenu/blob/main/docs/SPEC.md). What it has found on
32
+ > **Status: 0.10, early.** Spec in [docs/SPEC.md](https://github.com/niksa90/toolmenu/blob/main/docs/SPEC.md). What it has found on
33
33
  > real servers: [docs/FINDINGS.md](https://github.com/niksa90/toolmenu/blob/main/docs/FINDINGS.md).
34
34
 
35
35
  ## Start here
@@ -38,16 +38,39 @@ Needs Node 22 or later. The GitHub Action brings its own if the runner's Node is
38
38
  for toolmenu only: your server and the job's later steps keep the job's Node.
39
39
  Your server can be in any language: toolmenu starts it (stdio) or connects to it (HTTP).
40
40
 
41
+ One command sets up CI: it snapshots your server into `menu.json` (the baseline) and
42
+ writes `.github/workflows/toolmenu.yml` for your project (Node, Python, Go or Rust).
43
+ Commit both, open a pull request, and toolmenu comments on it.
44
+
41
45
  ```sh
42
- # write a starter scenario from your server's menu, then run it
43
- npx toolmenu session --init -- node dist/server.js
44
- npx toolmenu session --scenario scenario.yml -- node dist/server.js
46
+ npx toolmenu init -- node dist/server.js # add --with-session to also run session --auto
47
+ ```
48
+
49
+ Credentials you pass with `--env` go into the workflow as `${{ secrets.… }}`, never as
50
+ values; `init` says which secrets to add. It never overwrites a file.
51
+
52
+ By hand:
45
53
 
46
- # snapshot the menu and commit menu.json as your baseline
47
- npx toolmenu snapshot -- node dist/server.js
54
+ ```sh
55
+ npx toolmenu snapshot -- node dist/server.js # the menu, its findings, menu.json
56
+ npx toolmenu diff menu.json new-menu.json # what changed between two releases
57
+ npx toolmenu session --auto -- node dist/server.js # call read-only tools, watch the menu
48
58
  ```
49
59
 
50
60
  HTTP servers work the same way: `npx toolmenu snapshot https://example.com/mcp --header "Authorization: Bearer $TOKEN"`.
61
+ Servers behind OAuth (most hosted ones: GitHub, Atlassian, Sentry…): log in once, in a
62
+ browser, and `snapshot` and `session` use that login from then on, refreshing it as
63
+ needed:
64
+
65
+ ```sh
66
+ npx toolmenu auth login https://mcp.example.com/mcp
67
+ npx toolmenu snapshot https://mcp.example.com/mcp
68
+ ```
69
+
70
+ Logins are stored per server in `~/.config/toolmenu/auth` (readable only by you);
71
+ `auth list` and `auth logout <url>` manage them. A server that doesn't allow
72
+ dynamic registration needs a pre-registered app: `--client-id` (and
73
+ `--client-secret`). In CI, where no browser can open, pass a token as a header.
51
74
  Both protocol generations are supported: 2026-07-28 (`server/discover`, stateless)
52
75
  and the 2025 `initialize` handshake, through the official TypeScript SDK.
53
76
 
@@ -67,7 +90,7 @@ jobs:
67
90
  - uses: actions/setup-node@v7
68
91
  with: { node-version: 22 }
69
92
  - run: npm ci && npm run build
70
- - uses: niksa90/toolmenu@v0.8.0
93
+ - uses: niksa90/toolmenu@v0.10.0
71
94
  with:
72
95
  command: node dist/server.js
73
96
  baseline: menu.json # your committed snapshot
@@ -86,7 +109,9 @@ and anything `session` caught. The same report goes to the job summary.
86
109
  | `headers` | | HTTP headers for a `url` server, one `Name: value` per line. Use a secret for keys: `x-api-key: ${{ secrets.MCP_API_KEY }}` |
87
110
  | `env` | | Environment variables for a `command` server, one `KEY=value` per line |
88
111
  | `baseline` | `menu.json` | The committed snapshot to diff against |
89
- | `scenario` | | A scenario to run with `session` |
112
+ | `scenario` | | A scenario to run with `session`, or `auto` to build the steps from the menu |
113
+ | `catalog` | `false` | `true` also diffs the operations behind a search tool (`snapshot --catalog`) |
114
+ | `baseline-from` | `snapshot` | `session` diffs every tool the scenario saw (the union menu), for servers whose tools appear after an unlock |
90
115
  | `release` | `auto` | Release versions for the bump check. `auto` reads `package.json`, `pyproject.toml` or `Cargo.toml` on the base branch and the head, or compares the tag with the previous one on a tag push. Set `"1.4.0..1.5.0"` yourself, or `off` |
91
116
  | `fail-on` | `error` | Fail the job on findings at or above this level |
92
117
  | `comment` | `true` | Post and update the PR comment |
@@ -132,6 +157,16 @@ as its steps, so the starter is a floor, not a ceiling.
132
157
  | `session/refused`, `session/step-failed` | error | A write the scenario didn't allow, or a call that failed for another reason |
133
158
  | `session/tool-error` | warn | A tool that answered with an error for another reason (`isError`): the run tested less than it looks |
134
159
 
160
+ **No scenario? `session --auto`** builds the steps from the menu: every read-only tool
161
+ whose required arguments the schema itself gives (a `default`, `examples`, an `enum`,
162
+ a type or format), cheapest first, then the first call again. It never guesses an ID:
163
+ a tool that needs `owner`, `repo` or an issue key is skipped, and the report says
164
+ which values were missing (`--save-scenario auto.yml` writes the steps, with the
165
+ skipped tools commented out, to fill in). Tools marked `openWorldHint: true` (web
166
+ search, fetch, scraping, which can cost API credits) are called only with
167
+ `--open-world`. On the 22 servers in `bench/`, `--auto` reaches 60 of 262 read-only
168
+ tools, 84 with `--open-world`.
169
+
135
170
  **`session` calls tools for real.** Without `allow_writes: true` it refuses any tool
136
171
  not marked `readOnlyHint: true`. `--plan` prints the steps without connecting.
137
172
 
@@ -174,6 +209,27 @@ with `--server-version-is-release`. `diff` also enforces an optional `tokenBudge
174
209
  (`diff/token-budget`). Order changes are only a notice here: between releases, prompt caches rebuild. Order
175
210
  matters *within* a session.
176
211
 
212
+ ### Operations behind a search tool (`--catalog`)
213
+
214
+ Big servers increasingly keep most operations out of the menu: a small fixed menu, a
215
+ search tool, and an execute tool (Sentry's `search_sentry_tools` + `execute_sentry_tool`,
216
+ Atlassian's `discover` + `executeRead`). A breaking change to one of those operations
217
+ never shows in the menu. `snapshot --catalog` asks the search tool a fixed set of
218
+ queries and keeps the operations it returns in `menu.json`; `diff` then compares
219
+ operations found in both snapshots with the same rules as tools.
220
+
221
+ ```sh
222
+ npx toolmenu snapshot --catalog -- node dist/server.js
223
+ ```
224
+
225
+ A search returns its top matches, not everything, so an operation not found this time
226
+ is a notice ("not returned by the same queries"), never "removed". The default queries
227
+ come from the nouns in your tool names; on your own server, list the ones that matter
228
+ in `toolmenu.config.json` (`"catalog": { "queries": ["list releases", "delete issue"] }`).
229
+ If the server can serve the whole list as a menu (Atlassian: `?tools=all`), snapshot
230
+ that instead: it's complete. Queries are paced and a rate limit is waited out; on
231
+ Sentry's hosted server, two runs of 25 queries found the same 61 operations (FINDINGS F15).
232
+
177
233
  ## `history`: a package's releases, researched
178
234
 
179
235
  ```sh
package/dist/args.d.ts ADDED
@@ -0,0 +1,22 @@
1
+ import type { JsonSchema } from './types.js';
2
+ /** A value for a schema, or why there's none. */
3
+ export type Synthesized = {
4
+ ok: true;
5
+ value: unknown;
6
+ } | {
7
+ ok: false;
8
+ };
9
+ /**
10
+ * A value the schema itself vouches for: `const`, `default`, `examples`, `enum`,
11
+ * then by type and format. Never a guess at an ID or anything with a `pattern`:
12
+ * a tool that needs one is skipped, not called with junk.
13
+ */
14
+ export declare function synthesize(schema: JsonSchema | undefined, name?: string): Synthesized;
15
+ /** Arguments for a tool's required parameters, or the ones it can't fill. */
16
+ export declare function synthesizeArgs(schema: JsonSchema | undefined): {
17
+ ok: true;
18
+ args: Record<string, unknown>;
19
+ } | {
20
+ ok: false;
21
+ missing: string[];
22
+ };
package/dist/args.js ADDED
@@ -0,0 +1,81 @@
1
+ // Fixed dates, not "now": the same menu gives the same calls on every run.
2
+ const DATE_TIME = '2026-01-01T00:00:00Z';
3
+ const DATE = '2026-01-01';
4
+ const SEARCH_WORDS = /^(q|query|search|search_?query|text|keywords?|terms?|prompt|question)$/i;
5
+ /**
6
+ * A value the schema itself vouches for: `const`, `default`, `examples`, `enum`,
7
+ * then by type and format. Never a guess at an ID or anything with a `pattern`:
8
+ * a tool that needs one is skipped, not called with junk.
9
+ */
10
+ export function synthesize(schema, name = '') {
11
+ if (!schema || typeof schema !== 'object')
12
+ return { ok: false };
13
+ if ('const' in schema)
14
+ return { ok: true, value: schema.const };
15
+ if ('default' in schema)
16
+ return { ok: true, value: schema.default };
17
+ if (Array.isArray(schema.examples) && schema.examples.length)
18
+ return { ok: true, value: schema.examples[0] };
19
+ if (schema.enum?.length)
20
+ return { ok: true, value: schema.enum[0] };
21
+ const branches = (schema.anyOf ?? schema.oneOf);
22
+ const type = Array.isArray(schema.type) ? schema.type.find((t) => t !== 'null') : schema.type;
23
+ if (!type && Array.isArray(branches)) {
24
+ for (const b of branches) {
25
+ const v = synthesize(b, name);
26
+ if (v.ok)
27
+ return v;
28
+ }
29
+ return { ok: false };
30
+ }
31
+ switch (type) {
32
+ case 'boolean':
33
+ return { ok: true, value: false };
34
+ case 'integer':
35
+ case 'number': {
36
+ const min = typeof schema.minimum === 'number' ? schema.minimum : typeof schema.exclusiveMinimum === 'number' ? schema.exclusiveMinimum + 1 : undefined;
37
+ return { ok: true, value: min ?? 1 };
38
+ }
39
+ case 'string': {
40
+ if (typeof schema.pattern === 'string')
41
+ return { ok: false };
42
+ const format = typeof schema.format === 'string' ? schema.format : '';
43
+ if (format === 'date-time')
44
+ return { ok: true, value: DATE_TIME };
45
+ if (format === 'date')
46
+ return { ok: true, value: DATE };
47
+ if (format === 'uri' || format === 'url')
48
+ return { ok: true, value: 'https://example.com' };
49
+ if (format === 'email')
50
+ return { ok: true, value: 'user@example.com' };
51
+ if (SEARCH_WORDS.test(name))
52
+ return { ok: true, value: 'test' };
53
+ return { ok: false };
54
+ }
55
+ case 'array': {
56
+ const item = synthesize(schema.items, name);
57
+ if (item.ok)
58
+ return { ok: true, value: [item.value] };
59
+ return typeof schema.minItems === 'number' && schema.minItems > 0 ? { ok: false } : { ok: true, value: [] };
60
+ }
61
+ case 'object': {
62
+ const args = synthesizeArgs(schema);
63
+ return args.ok ? { ok: true, value: args.args } : { ok: false };
64
+ }
65
+ default:
66
+ return { ok: false };
67
+ }
68
+ }
69
+ /** Arguments for a tool's required parameters, or the ones it can't fill. */
70
+ export function synthesizeArgs(schema) {
71
+ const args = {};
72
+ const missing = [];
73
+ for (const param of schema?.required ?? []) {
74
+ const v = synthesize(schema?.properties?.[param], param);
75
+ if (v.ok)
76
+ args[param] = v.value;
77
+ else
78
+ missing.push(param);
79
+ }
80
+ return missing.length ? { ok: false, missing } : { ok: true, args };
81
+ }
package/dist/auth.d.ts ADDED
@@ -0,0 +1,77 @@
1
+ import type { OAuthClientInformationContext, OAuthClientMetadata, OAuthClientProvider, OAuthDiscoveryState, StoredOAuthClientInformation, StoredOAuthTokens } from '@modelcontextprotocol/client';
2
+ /**
3
+ * The redirect port. Fixed, not random: dynamic registration records the exact
4
+ * redirect URI, so a new port would invalidate the stored client on every login.
5
+ */
6
+ export declare const DEFAULT_PORT = 33418;
7
+ /** Where logins live: $TOOLMENU_AUTH_DIR, else $XDG_CONFIG_HOME/toolmenu/auth, else ~/.config/toolmenu/auth. */
8
+ export declare function authDir(): string;
9
+ /** Is there a stored login for this server? */
10
+ export declare function hasLogin(serverUrl: string): boolean;
11
+ export interface ProviderOptions {
12
+ /** A browser login may start (auth login). Otherwise a needed login is an error. */
13
+ interactive?: boolean;
14
+ port?: number;
15
+ scope?: string;
16
+ /** A pre-registered client, for servers that don't allow dynamic registration. */
17
+ clientId?: string;
18
+ clientSecret?: string;
19
+ onRedirect?: (url: URL) => void | Promise<void>;
20
+ }
21
+ /**
22
+ * The SDK's OAuthClientProvider, backed by toolmenu's store. Credentials are bound
23
+ * to the authorization server's issuer: stored ones for a different issuer are
24
+ * never handed out.
25
+ */
26
+ export declare class StoredOAuthProvider implements OAuthClientProvider {
27
+ private readonly serverUrl;
28
+ private readonly options;
29
+ private data;
30
+ private expectedState;
31
+ constructor(serverUrl: string, options?: ProviderOptions);
32
+ private stored;
33
+ private update;
34
+ /** The issuer check: no credentials for an authorization server they weren't issued by. */
35
+ private sameIssuer;
36
+ get redirectUrl(): string;
37
+ get clientMetadata(): OAuthClientMetadata;
38
+ state(): string;
39
+ /** The state the authorization request carried, to check the callback against (the SDK doesn't). */
40
+ get lastState(): string | undefined;
41
+ clientInformation(ctx?: OAuthClientInformationContext): Promise<StoredOAuthClientInformation | undefined>;
42
+ saveClientInformation(clientInformation: StoredOAuthClientInformation, ctx?: OAuthClientInformationContext): Promise<void>;
43
+ tokens(ctx?: OAuthClientInformationContext): Promise<StoredOAuthTokens | undefined>;
44
+ saveTokens(tokens: StoredOAuthTokens, ctx?: OAuthClientInformationContext): Promise<void>;
45
+ redirectToAuthorization(authorizationUrl: URL): Promise<void>;
46
+ saveCodeVerifier(codeVerifier: string): Promise<void>;
47
+ codeVerifier(): Promise<string>;
48
+ saveDiscoveryState(discoveryState: OAuthDiscoveryState): Promise<void>;
49
+ discoveryState(): Promise<OAuthDiscoveryState | undefined>;
50
+ invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): Promise<void>;
51
+ }
52
+ export declare class LoginNeededError extends Error {
53
+ constructor(serverUrl: string);
54
+ }
55
+ export interface LoginOptions extends Omit<ProviderOptions, 'interactive' | 'onRedirect'> {
56
+ /** How to show the authorization URL. Default: print it and try to open a browser. */
57
+ open?: (url: URL) => void | Promise<void>;
58
+ /** How long to wait for the browser to come back (default 5 min). */
59
+ timeoutMs?: number;
60
+ }
61
+ /**
62
+ * Log in to an OAuth-protected MCP server: register (or reuse a client), open the
63
+ * authorization URL, receive the code on a loopback redirect, check `state`,
64
+ * exchange the code (PKCE, issuer check: the SDK's), then connect once with the new
65
+ * token to confirm it works. Returns the server's name and tool count.
66
+ */
67
+ export declare function login(serverUrl: string, options?: LoginOptions): Promise<{
68
+ name?: string;
69
+ tools: number;
70
+ }>;
71
+ export declare function logout(serverUrl: string): Promise<boolean>;
72
+ /** Stored logins: the server, its issuer, and when the tokens were saved. No secrets. */
73
+ export declare function listLogins(): Promise<{
74
+ serverUrl: string;
75
+ issuer?: string;
76
+ savedAt?: string;
77
+ }[]>;
package/dist/auth.js ADDED
@@ -0,0 +1,304 @@
1
+ import { spawn } from 'node:child_process';
2
+ import { createHash, randomBytes } from 'node:crypto';
3
+ import { existsSync, readdirSync } from 'node:fs';
4
+ import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
5
+ import { createServer } from 'node:http';
6
+ import { homedir } from 'node:os';
7
+ import { join } from 'node:path';
8
+ import { Client, StreamableHTTPClientTransport, UnauthorizedError } from '@modelcontextprotocol/client';
9
+ import { VERSION } from './version.js';
10
+ /**
11
+ * The redirect port. Fixed, not random: dynamic registration records the exact
12
+ * redirect URI, so a new port would invalidate the stored client on every login.
13
+ */
14
+ export const DEFAULT_PORT = 33418;
15
+ /** Where logins live: $TOOLMENU_AUTH_DIR, else $XDG_CONFIG_HOME/toolmenu/auth, else ~/.config/toolmenu/auth. */
16
+ export function authDir() {
17
+ if (process.env.TOOLMENU_AUTH_DIR)
18
+ return process.env.TOOLMENU_AUTH_DIR;
19
+ return join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'toolmenu', 'auth');
20
+ }
21
+ /** One file per server endpoint (origin and path), named by its hash. */
22
+ function storePath(serverUrl) {
23
+ const u = new URL(serverUrl);
24
+ return join(authDir(), createHash('sha256').update(u.origin + u.pathname).digest('hex').slice(0, 32) + '.json');
25
+ }
26
+ async function load(serverUrl) {
27
+ try {
28
+ return JSON.parse(await readFile(storePath(serverUrl), 'utf8'));
29
+ }
30
+ catch {
31
+ return { serverUrl };
32
+ }
33
+ }
34
+ async function save(data) {
35
+ await mkdir(authDir(), { recursive: true, mode: 0o700 });
36
+ const path = storePath(data.serverUrl);
37
+ await writeFile(path, JSON.stringify({ ...data, savedAt: new Date().toISOString() }, null, 2) + '\n', { mode: 0o600 });
38
+ await chmod(path, 0o600);
39
+ }
40
+ /** Is there a stored login for this server? */
41
+ export function hasLogin(serverUrl) {
42
+ return existsSync(storePath(serverUrl));
43
+ }
44
+ /**
45
+ * The SDK's OAuthClientProvider, backed by toolmenu's store. Credentials are bound
46
+ * to the authorization server's issuer: stored ones for a different issuer are
47
+ * never handed out.
48
+ */
49
+ export class StoredOAuthProvider {
50
+ serverUrl;
51
+ options;
52
+ data;
53
+ expectedState;
54
+ constructor(serverUrl, options = {}) {
55
+ this.serverUrl = serverUrl;
56
+ this.options = options;
57
+ }
58
+ async stored() {
59
+ this.data ??= await load(this.serverUrl);
60
+ return this.data;
61
+ }
62
+ async update(patch) {
63
+ this.data = { ...(await this.stored()), ...patch };
64
+ await save(this.data);
65
+ }
66
+ /** The issuer check: no credentials for an authorization server they weren't issued by. */
67
+ async sameIssuer(ctx) {
68
+ const s = await this.stored();
69
+ return !ctx?.issuer || !s.issuer || s.issuer === ctx.issuer;
70
+ }
71
+ get redirectUrl() {
72
+ return `http://127.0.0.1:${this.options.port ?? DEFAULT_PORT}/callback`;
73
+ }
74
+ get clientMetadata() {
75
+ return {
76
+ client_name: 'toolmenu',
77
+ client_uri: 'https://github.com/niksa90/toolmenu',
78
+ software_id: 'toolmenu',
79
+ software_version: VERSION,
80
+ redirect_uris: [this.redirectUrl],
81
+ grant_types: ['authorization_code', 'refresh_token'],
82
+ response_types: ['code'],
83
+ token_endpoint_auth_method: this.options.clientSecret ? 'client_secret_post' : 'none',
84
+ ...(this.options.scope ? { scope: this.options.scope } : {}),
85
+ };
86
+ }
87
+ state() {
88
+ this.expectedState = randomBytes(16).toString('base64url');
89
+ return this.expectedState;
90
+ }
91
+ /** The state the authorization request carried, to check the callback against (the SDK doesn't). */
92
+ get lastState() {
93
+ return this.expectedState;
94
+ }
95
+ async clientInformation(ctx) {
96
+ const s = await this.stored();
97
+ if (this.options.clientId) {
98
+ // Stamped with the issuer, like everything the SDK stores (SEP-2352): the one
99
+ // this server's login was first bound to, or on a first login the one being
100
+ // discovered. The SDK then won't hand this client to another server.
101
+ if (s.issuer && ctx?.issuer && s.issuer !== ctx.issuer)
102
+ return undefined;
103
+ const issuer = s.issuer ?? ctx?.issuer;
104
+ const info = { client_id: this.options.clientId, ...(this.options.clientSecret ? { client_secret: this.options.clientSecret } : {}), ...(issuer ? { issuer } : {}) };
105
+ // Kept like a registered client, so a later snapshot can refresh the token
106
+ // without --client-id.
107
+ if (JSON.stringify(s.clientInformation) !== JSON.stringify(info))
108
+ await this.update({ clientInformation: info, redirectUrl: this.redirectUrl });
109
+ return info;
110
+ }
111
+ if (!(await this.sameIssuer(ctx)))
112
+ return undefined;
113
+ // Registered for another redirect URI (a different --port): register again.
114
+ if (this.options.interactive && s.redirectUrl && s.redirectUrl !== this.redirectUrl)
115
+ return undefined;
116
+ return s.clientInformation;
117
+ }
118
+ async saveClientInformation(clientInformation, ctx) {
119
+ await this.update({ clientInformation, redirectUrl: this.redirectUrl, ...(ctx?.issuer ? { issuer: ctx.issuer } : {}) });
120
+ }
121
+ async tokens(ctx) {
122
+ if (!(await this.sameIssuer(ctx)))
123
+ return undefined;
124
+ return (await this.stored()).tokens;
125
+ }
126
+ async saveTokens(tokens, ctx) {
127
+ await this.update({ tokens, ...(ctx?.issuer ? { issuer: ctx.issuer } : {}) });
128
+ }
129
+ async redirectToAuthorization(authorizationUrl) {
130
+ if (!this.options.interactive) {
131
+ throw new LoginNeededError(this.serverUrl);
132
+ }
133
+ await this.options.onRedirect?.(authorizationUrl);
134
+ }
135
+ async saveCodeVerifier(codeVerifier) {
136
+ await this.update({ codeVerifier });
137
+ }
138
+ async codeVerifier() {
139
+ const v = (await this.stored()).codeVerifier;
140
+ if (!v)
141
+ throw new Error('No PKCE code verifier saved for this login.');
142
+ return v;
143
+ }
144
+ async saveDiscoveryState(discoveryState) {
145
+ await this.update({ discoveryState });
146
+ }
147
+ async discoveryState() {
148
+ return (await this.stored()).discoveryState;
149
+ }
150
+ async invalidateCredentials(scope) {
151
+ const s = await this.stored();
152
+ if (scope === 'all') {
153
+ this.data = { serverUrl: s.serverUrl };
154
+ await rm(storePath(this.serverUrl), { force: true });
155
+ return;
156
+ }
157
+ const patch = {};
158
+ if (scope === 'client')
159
+ patch.clientInformation = undefined;
160
+ if (scope === 'tokens')
161
+ patch.tokens = undefined;
162
+ if (scope === 'verifier')
163
+ patch.codeVerifier = undefined;
164
+ if (scope === 'discovery')
165
+ patch.discoveryState = undefined;
166
+ await this.update(patch);
167
+ }
168
+ }
169
+ export class LoginNeededError extends Error {
170
+ constructor(serverUrl) {
171
+ super(`${serverUrl} needs an OAuth login, and toolmenu can't open a browser here. Run: toolmenu auth login ${serverUrl}`);
172
+ }
173
+ }
174
+ /**
175
+ * Log in to an OAuth-protected MCP server: register (or reuse a client), open the
176
+ * authorization URL, receive the code on a loopback redirect, check `state`,
177
+ * exchange the code (PKCE, issuer check: the SDK's), then connect once with the new
178
+ * token to confirm it works. Returns the server's name and tool count.
179
+ */
180
+ export async function login(serverUrl, options = {}) {
181
+ const port = options.port ?? DEFAULT_PORT;
182
+ const callback = await listenForCallback(port, options.timeoutMs ?? 300_000);
183
+ try {
184
+ const provider = new StoredOAuthProvider(serverUrl, { ...options, port, interactive: true, onRedirect: options.open ?? openInBrowser });
185
+ // Each login discovers the authorization server afresh (a server may have
186
+ // moved); the state is then kept for the callback leg's check.
187
+ await provider.invalidateCredentials('discovery');
188
+ const transport = new StreamableHTTPClientTransport(new URL(serverUrl), { authProvider: provider });
189
+ const client = new Client({ name: 'toolmenu', version: VERSION });
190
+ try {
191
+ await client.connect(transport);
192
+ // Already logged in with a valid (or refreshed) token.
193
+ await client.close();
194
+ }
195
+ catch (error) {
196
+ if (!(error instanceof UnauthorizedError))
197
+ throw error;
198
+ const params = await callback.params;
199
+ if (params.get('error'))
200
+ throw new Error(`The authorization server refused the login: ${params.get('error')}`);
201
+ if (!provider.lastState || params.get('state') !== provider.lastState)
202
+ throw new Error('The login callback carried the wrong state, so it was ignored. Try again.');
203
+ await transport.finishAuth(params);
204
+ await client.close().catch(() => { });
205
+ }
206
+ return await check(serverUrl);
207
+ }
208
+ catch (error) {
209
+ // GitHub's hosted server, for one: no dynamic registration, so toolmenu can't
210
+ // register itself. Say what works instead.
211
+ if (error instanceof Error && /does not support dynamic client registration/i.test(error.message) && !options.clientId) {
212
+ error.message =
213
+ `${serverUrl} doesn't let clients register themselves (no dynamic client registration). Two ways in:\n` +
214
+ ` - register an OAuth app with the provider, with the callback URL http://127.0.0.1:${port}/callback, then:\n` +
215
+ ` toolmenu auth login ${serverUrl} --client-id <id> --client-secret <secret>\n` +
216
+ ` - or skip OAuth and pass a token the server accepts: toolmenu snapshot ${serverUrl} --header "Authorization: Bearer <token>"`;
217
+ }
218
+ throw error;
219
+ }
220
+ finally {
221
+ callback.close();
222
+ }
223
+ }
224
+ /** Connect with the stored login and list tools: the login works. */
225
+ async function check(serverUrl) {
226
+ const client = new Client({ name: 'toolmenu', version: VERSION });
227
+ await client.connect(new StreamableHTTPClientTransport(new URL(serverUrl), { authProvider: new StoredOAuthProvider(serverUrl) }));
228
+ try {
229
+ const { tools } = await client.listTools();
230
+ return { name: client.getServerVersion()?.name, tools: tools.length };
231
+ }
232
+ finally {
233
+ await client.close().catch(() => { });
234
+ }
235
+ }
236
+ export async function logout(serverUrl) {
237
+ const had = hasLogin(serverUrl);
238
+ await rm(storePath(serverUrl), { force: true });
239
+ return had;
240
+ }
241
+ /** Stored logins: the server, its issuer, and when the tokens were saved. No secrets. */
242
+ export async function listLogins() {
243
+ if (!existsSync(authDir()))
244
+ return [];
245
+ const out = [];
246
+ for (const f of readdirSync(authDir()).filter((f) => f.endsWith('.json'))) {
247
+ try {
248
+ const s = JSON.parse(await readFile(join(authDir(), f), 'utf8'));
249
+ out.push({ serverUrl: s.serverUrl, issuer: s.issuer, savedAt: s.savedAt });
250
+ }
251
+ catch {
252
+ // not ours
253
+ }
254
+ }
255
+ return out;
256
+ }
257
+ /** A one-shot HTTP server on 127.0.0.1 that resolves with the callback's query. */
258
+ function listenForCallback(port, timeoutMs) {
259
+ return new Promise((ready, fail) => {
260
+ let resolveParams;
261
+ let rejectParams;
262
+ const params = new Promise((resolve, reject) => {
263
+ resolveParams = resolve;
264
+ rejectParams = reject;
265
+ });
266
+ params.catch(() => { }); // surfaced where it's awaited
267
+ const server = createServer((req, res) => {
268
+ const url = new URL(req.url ?? '/', `http://127.0.0.1:${port}`);
269
+ if (url.pathname !== '/callback') {
270
+ res.writeHead(404).end();
271
+ return;
272
+ }
273
+ res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
274
+ res.end('<!doctype html><title>toolmenu</title><p>Logged in. You can close this tab and go back to the terminal.</p>');
275
+ resolveParams(url.searchParams);
276
+ });
277
+ const timer = setTimeout(() => rejectParams(new Error(`No login came back within ${Math.round(timeoutMs / 1000)} s.`)), timeoutMs);
278
+ server.on('error', (error) => fail(error.code === 'EADDRINUSE' ? new Error(`Port ${port} is in use: pick another with --port (the login registers that redirect).`) : error));
279
+ server.listen(port, '127.0.0.1', () => ready({
280
+ params,
281
+ close: () => {
282
+ clearTimeout(timer);
283
+ server.closeAllConnections();
284
+ server.close();
285
+ },
286
+ }));
287
+ });
288
+ }
289
+ /** Print the URL (always) and try to open it (best effort). */
290
+ function openInBrowser(url) {
291
+ const scope = url.searchParams.get('scope');
292
+ // toolmenu only lists tools and calls read-only ones, but it asks for the
293
+ // server's default scopes, as other clients do: some servers show tools by scope.
294
+ if (scope)
295
+ process.stderr.write(`Asking for the server's default scopes: ${scope} (narrower: --scope; toolmenu never calls a write tool on its own)\n`);
296
+ process.stderr.write(`Opening your browser to log in. If it doesn't open, visit:\n ${url.href}\n`);
297
+ const [cmd, args] = process.platform === 'darwin' ? ['open', [url.href]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', url.href]] : ['xdg-open', [url.href]];
298
+ try {
299
+ spawn(cmd, args, { detached: true, stdio: 'ignore' }).on('error', () => { }).unref();
300
+ }
301
+ catch {
302
+ // printed above
303
+ }
304
+ }
package/dist/auto.d.ts ADDED
@@ -0,0 +1,28 @@
1
+ import type { Scenario } from './session.js';
2
+ import type { Menu } from './types.js';
3
+ export interface AutoOptions {
4
+ /** Also call read-only tools marked openWorldHint: true (web search, fetch, scraping). */
5
+ openWorld?: boolean;
6
+ /** At most this many calls (default 20). */
7
+ maxCalls?: number;
8
+ }
9
+ export type SkipReason = 'not read-only' | 'open world' | 'needs values' | 'over the call budget';
10
+ export interface AutoPlan {
11
+ scenario: Scenario;
12
+ called: string[];
13
+ skipped: {
14
+ tool: string;
15
+ reason: SkipReason;
16
+ missing?: string[];
17
+ }[];
18
+ }
19
+ /**
20
+ * A scenario built from the menu, no hand-written steps: every read-only tool
21
+ * whose required arguments the schema can fill, cheapest first (no arguments,
22
+ * then lists and searches, then single lookups, then the rest), then the first
23
+ * call again, which should change nothing. Never a tool that isn't marked
24
+ * readOnlyHint, whatever allow_writes says.
25
+ */
26
+ export declare function autoScenario(menu: Menu, options?: AutoOptions): AutoPlan;
27
+ /** The plan as a scenario file, to commit and run again with --scenario. */
28
+ export declare function scenarioYaml(plan: AutoPlan, serverName?: string): string;