toolmenu 0.7.1 → 0.9.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 +37 -9
- package/dist/args.d.ts +22 -0
- package/dist/args.js +81 -0
- package/dist/auth.d.ts +77 -0
- package/dist/auth.js +304 -0
- package/dist/auto.d.ts +28 -0
- package/dist/auto.js +81 -0
- package/dist/cli.js +105 -9
- package/dist/config.d.ts +2 -0
- package/dist/config.js +3 -0
- package/dist/connect.d.ts +1 -0
- package/dist/connect.js +11 -1
- package/dist/difference.d.ts +17 -0
- package/dist/difference.js +70 -0
- package/dist/failures.d.ts +14 -0
- package/dist/failures.js +47 -0
- package/dist/history.js +3 -1
- package/dist/probe.d.ts +27 -0
- package/dist/probe.js +58 -0
- package/dist/report.js +29 -3
- package/dist/rules/determinism.d.ts +23 -1
- package/dist/rules/determinism.js +72 -2
- package/dist/rules/ids.d.ts +2 -0
- package/dist/rules/ids.js +34 -12
- package/dist/rules/index.js +3 -1
- package/dist/rules/naming.js +2 -1
- package/dist/rules/rule.d.ts +6 -0
- package/dist/session.d.ts +16 -0
- package/dist/session.js +81 -44
- package/dist/snapshot.d.ts +5 -0
- package/dist/snapshot.js +28 -18
- package/package.json +1 -1
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.
|
|
32
|
+
> **Status: 0.9, 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
|
|
@@ -48,6 +48,19 @@ npx toolmenu snapshot -- node dist/server.js
|
|
|
48
48
|
```
|
|
49
49
|
|
|
50
50
|
HTTP servers work the same way: `npx toolmenu snapshot https://example.com/mcp --header "Authorization: Bearer $TOKEN"`.
|
|
51
|
+
Servers behind OAuth (most hosted ones: GitHub, Atlassian, Sentry…): log in once, in a
|
|
52
|
+
browser, and `snapshot` and `session` use that login from then on, refreshing it as
|
|
53
|
+
needed:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
npx toolmenu auth login https://mcp.example.com/mcp
|
|
57
|
+
npx toolmenu snapshot https://mcp.example.com/mcp
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Logins are stored per server in `~/.config/toolmenu/auth` (readable only by you);
|
|
61
|
+
`auth list` and `auth logout <url>` manage them. A server that doesn't allow
|
|
62
|
+
dynamic registration needs a pre-registered app: `--client-id` (and
|
|
63
|
+
`--client-secret`). In CI, where no browser can open, pass a token as a header.
|
|
51
64
|
Both protocol generations are supported: 2026-07-28 (`server/discover`, stateless)
|
|
52
65
|
and the 2025 `initialize` handshake, through the official TypeScript SDK.
|
|
53
66
|
|
|
@@ -67,7 +80,7 @@ jobs:
|
|
|
67
80
|
- uses: actions/setup-node@v7
|
|
68
81
|
with: { node-version: 22 }
|
|
69
82
|
- run: npm ci && npm run build
|
|
70
|
-
- uses: niksa90/toolmenu@v0.
|
|
83
|
+
- uses: niksa90/toolmenu@v0.9.0
|
|
71
84
|
with:
|
|
72
85
|
command: node dist/server.js
|
|
73
86
|
baseline: menu.json # your committed snapshot
|
|
@@ -86,7 +99,8 @@ and anything `session` caught. The same report goes to the job summary.
|
|
|
86
99
|
| `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
100
|
| `env` | | Environment variables for a `command` server, one `KEY=value` per line |
|
|
88
101
|
| `baseline` | `menu.json` | The committed snapshot to diff against |
|
|
89
|
-
| `scenario` | | A scenario to run with `session` |
|
|
102
|
+
| `scenario` | | A scenario to run with `session`, or `auto` to build the steps from the menu |
|
|
103
|
+
| `baseline-from` | `snapshot` | `session` diffs every tool the scenario saw (the union menu), for servers whose tools appear after an unlock |
|
|
90
104
|
| `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
105
|
| `fail-on` | `error` | Fail the job on findings at or above this level |
|
|
92
106
|
| `comment` | `true` | Post and update the PR comment |
|
|
@@ -122,14 +136,25 @@ as its steps, so the starter is a floor, not a ceiling.
|
|
|
122
136
|
|
|
123
137
|
| Rule | Default | Catches |
|
|
124
138
|
|---|---|---|
|
|
125
|
-
| `session/mid-insert`, `session/reorder`, `session/remove`, `session/edit` | error | The menu changing mid-session anywhere but the end, with the
|
|
139
|
+
| `session/mid-insert`, `session/reorder`, `session/remove`, `session/edit` | error | The menu changing mid-session anywhere but the end, with where the change starts and which value changed. Any change to the tool list invalidates the cached prompt: the whole tool list (its size, estimated) and the conversation after it are processed again |
|
|
126
140
|
| `session/append` | warn | Tools added at the end of the list. Still a cache miss for the conversation when your client sends tools at the start of the prompt (Claude's Messages API does); cache-safe only when the client adds new tools after the cached content, as tool search (deferred loading) does |
|
|
127
141
|
| `session/connection-local` | error on 2026-07-28 (HTTP) | A change only this connection sees. 2026-07-28: the tool set MUST NOT vary "per-connection or as a side effect of other requests on the connection" |
|
|
128
142
|
| `session/side-effect` | warn on 2026-07-28 (stdio) | The same, where stdio can't tell per-connection from global |
|
|
129
|
-
| `
|
|
143
|
+
| `menu/process-variance`, `menu/connection-variance` | error | Checked before the first step, as in `snapshot` (below) |
|
|
130
144
|
| `session/unannounced` | warn | The menu changed without `notifications/tools/list_changed`, although the server declared `listChanged` |
|
|
131
|
-
| `session/
|
|
132
|
-
| `session/
|
|
145
|
+
| `session/untested` | warn, error if no call got through | Calls that failed before reaching the tool: authentication, something missing on this machine (no Chrome), the network. One finding for the run, not one per step, so an expired CI secret doesn't pass a run that tested nothing |
|
|
146
|
+
| `session/refused`, `session/step-failed` | error | A write the scenario didn't allow, or a call that failed for another reason |
|
|
147
|
+
| `session/tool-error` | warn | A tool that answered with an error for another reason (`isError`): the run tested less than it looks |
|
|
148
|
+
|
|
149
|
+
**No scenario? `session --auto`** builds the steps from the menu: every read-only tool
|
|
150
|
+
whose required arguments the schema itself gives (a `default`, `examples`, an `enum`,
|
|
151
|
+
a type or format), cheapest first, then the first call again. It never guesses an ID:
|
|
152
|
+
a tool that needs `owner`, `repo` or an issue key is skipped, and the report says
|
|
153
|
+
which values were missing (`--save-scenario auto.yml` writes the steps, with the
|
|
154
|
+
skipped tools commented out, to fill in). Tools marked `openWorldHint: true` (web
|
|
155
|
+
search, fetch, scraping, which can cost API credits) are called only with
|
|
156
|
+
`--open-world`. On the 22 servers in `bench/`, `--auto` reaches 60 of 262 read-only
|
|
157
|
+
tools, 84 with `--open-world`.
|
|
133
158
|
|
|
134
159
|
**`session` calls tools for real.** Without `allow_writes: true` it refuses any tool
|
|
135
160
|
not marked `readOnlyHint: true`. `--plan` prints the steps without connecting.
|
|
@@ -196,13 +221,15 @@ server, or from the spec itself. If a rule can't point to one, it doesn't ship.
|
|
|
196
221
|
|
|
197
222
|
| Rule | Default | Catches |
|
|
198
223
|
|---|---|---|
|
|
199
|
-
| `menu/nondeterministic` | error | Two identical `tools/list` calls returning different menus (order, descriptions, schemas, annotations) |
|
|
224
|
+
| `menu/nondeterministic` | error | Two identical `tools/list` calls returning different menus (order, descriptions, schemas, annotations), with the value that differs |
|
|
225
|
+
| `menu/process-variance` | error | A second server process, started the same way, serves a different menu, so every restart misses the cache. Seen on mcp-atlassian: a default built from a Python set, in a new order every start (FINDINGS F12). toolmenu runs the main process with `PYTHONHASHSEED=0`, so a Python server's saved menu is reproducible, and the second with another seed. `--processes 1` turns it off |
|
|
226
|
+
| `menu/connection-variance` | error (warn on 2025 protocols) | The same over HTTP: a second connection with the same credentials gets a different menu. Retried once before reporting |
|
|
200
227
|
| `spec/schema` | error | A `tools/list` result that fails the official schema for its protocol version |
|
|
201
228
|
| `naming/route` | error | A `routes.yml` expectation broke: a keyword now matches the wrong tool at least as well as the right one |
|
|
202
229
|
| `description/buried` | warn | Instructions to the agent ("use X instead", "don't retry", "never guess one") past the point where your client cuts descriptions: 2,048 characters in Claude Code, or your `descriptionLimit`. From a real failure: a client cut at 280 characters, and the line that decided routing was at 1,222 |
|
|
203
230
|
| `description/cut` | info | Descriptions longer than the client sends, with nothing that reads as an instruction past the cut, as one summary. The model gets a prefix that can read as complete |
|
|
204
231
|
| `naming/vague-id` | warn | A parameter called just `id` that doesn't say *which* thing |
|
|
205
|
-
| `ids/authored` |
|
|
232
|
+
| `ids/authored` | info | An ID the agent must supply that no tool appears to return, so the agent may invent it, one finding per kind of ID (heuristic: IDs from a URL or another tool's text output look the same) |
|
|
206
233
|
| `write/unannotated` | warn | A tool named like a write (`delete_`, `send_`…) with no annotations |
|
|
207
234
|
| `naming/shared-word` | info | Nouns that name different things across tools (`list_team_audits` vs `get_audit_trail`), as one summary |
|
|
208
235
|
| `write/no-dry-run` | info | Destructive tools with no dry-run parameter or preview tool, as one summary |
|
|
@@ -281,6 +308,7 @@ toolmenu sees what the server sends. Plenty of agent failures happen elsewhere:
|
|
|
281
308
|
--env <K=V> env var for a stdio server, repeatable (it only gets a
|
|
282
309
|
minimal environment otherwise)
|
|
283
310
|
--timeout <ms> per-request timeout (default: 30000)
|
|
311
|
+
--processes <n> server processes or connections to compare (default: 2)
|
|
284
312
|
```
|
|
285
313
|
|
|
286
314
|
Exit codes: `0` clean · `1` findings at or above `--fail-on` · `2` couldn't connect
|
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;
|