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 +64 -8
- 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/breakdown.d.ts +30 -0
- package/dist/breakdown.js +63 -0
- package/dist/catalog.d.ts +50 -0
- package/dist/catalog.js +168 -0
- package/dist/cli.js +139 -11
- package/dist/config.d.ts +6 -0
- package/dist/connect.d.ts +1 -0
- package/dist/connect.js +11 -1
- package/dist/diff.js +43 -0
- package/dist/init.d.ts +22 -0
- package/dist/init.js +105 -0
- package/dist/menu.js +2 -0
- package/dist/report.js +34 -2
- package/dist/session.d.ts +10 -0
- package/dist/session.js +7 -1
- package/dist/snapshot.d.ts +3 -0
- package/dist/snapshot.js +4 -0
- package/dist/types.d.ts +2 -0
- 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.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
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
-
|
|
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.
|
|
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;
|