toolmenu 0.12.0 → 0.14.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 +84 -23
- package/dist/args.d.ts +31 -5
- package/dist/args.js +91 -14
- package/dist/auth.d.ts +4 -2
- package/dist/auth.js +59 -21
- package/dist/auto.d.ts +80 -6
- package/dist/auto.js +255 -19
- package/dist/breakdown.d.ts +2 -0
- package/dist/breakdown.js +64 -19
- package/dist/catalog.d.ts +87 -10
- package/dist/catalog.js +415 -58
- package/dist/cli.js +170 -185
- package/dist/close.d.ts +8 -0
- package/dist/close.js +18 -0
- package/dist/config.d.ts +7 -1
- package/dist/config.js +17 -0
- package/dist/connect.d.ts +14 -0
- package/dist/connect.js +150 -16
- package/dist/diff.d.ts +23 -1
- package/dist/diff.js +574 -120
- package/dist/difference.d.ts +2 -0
- package/dist/difference.js +13 -12
- package/dist/explain.d.ts +113 -0
- package/dist/explain.js +461 -0
- package/dist/failures.d.ts +15 -0
- package/dist/failures.js +59 -2
- package/dist/help.d.ts +11 -0
- package/dist/help.js +205 -0
- package/dist/history.d.ts +13 -0
- package/dist/history.js +86 -6
- package/dist/init.d.ts +93 -2
- package/dist/init.js +508 -21
- package/dist/menu.js +10 -2
- package/dist/options.d.ts +141 -0
- package/dist/options.js +50 -0
- package/dist/report.d.ts +2 -2
- package/dist/report.js +305 -101
- package/dist/rules/description.d.ts +7 -2
- package/dist/rules/description.js +86 -42
- package/dist/rules/determinism.d.ts +4 -1
- package/dist/rules/determinism.js +175 -11
- package/dist/rules/gated.d.ts +7 -0
- package/dist/rules/gated.js +77 -0
- package/dist/rules/ids.d.ts +1 -1
- package/dist/rules/ids.js +9 -4
- package/dist/rules/index.d.ts +6 -0
- package/dist/rules/index.js +18 -6
- package/dist/rules/naming.d.ts +1 -1
- package/dist/rules/naming.js +91 -21
- package/dist/rules/rule.d.ts +25 -0
- package/dist/rules/rule.js +25 -1
- package/dist/rules/spec.d.ts +6 -0
- package/dist/rules/spec.js +56 -9
- package/dist/rules/write.d.ts +1 -1
- package/dist/rules/write.js +64 -14
- package/dist/session.d.ts +34 -9
- package/dist/session.js +525 -94
- package/dist/snapshot.d.ts +8 -2
- package/dist/snapshot.js +33 -2
- package/dist/types.d.ts +21 -0
- package/dist/words.d.ts +5 -0
- package/dist/words.js +14 -0
- package/package.json +2 -2
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.14, 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
|
|
@@ -50,6 +50,14 @@ Every value you pass with `--env` or `--header` goes into the workflow as
|
|
|
50
50
|
`${{ secrets.… }}`, never as text (a name like `DATABASE_URL` doesn't say it holds a
|
|
51
51
|
password); `init` says which secrets to add. It never overwrites a file.
|
|
52
52
|
|
|
53
|
+
Run it anywhere in the repository. `.github/workflows/toolmenu.yml` goes to the git
|
|
54
|
+
root, and the server starts in CI from the folder you ran `init` in, which is also
|
|
55
|
+
where `menu.json` is saved. That's how a monorepo package works: run `init` in
|
|
56
|
+
`packages/server`. Paths to files in the repository are made relative, so they work on
|
|
57
|
+
the runner. `init` lists anything that won't work there (a file outside the
|
|
58
|
+
repository, a `localhost` URL, a virtualenv the runner doesn't have), each with what
|
|
59
|
+
to do.
|
|
60
|
+
|
|
53
61
|
By hand:
|
|
54
62
|
|
|
55
63
|
```sh
|
|
@@ -75,6 +83,11 @@ dynamic registration needs a pre-registered app: `--client-id` (and
|
|
|
75
83
|
Both protocol generations are supported: 2026-07-28 (`server/discover`, stateless)
|
|
76
84
|
and the 2025 `initialize` handshake, through the official TypeScript SDK.
|
|
77
85
|
|
|
86
|
+
Every finding and error says what's wrong, where, what toolmenu saw, and ends in a
|
|
87
|
+
`→ Next:` step. Findings marked `· unsure` are heuristics (names and words): they say
|
|
88
|
+
what was seen, not what it means. Every command has its own help:
|
|
89
|
+
`toolmenu history --help`.
|
|
90
|
+
|
|
78
91
|
## In CI: one PR comment
|
|
79
92
|
|
|
80
93
|
```yaml
|
|
@@ -91,7 +104,7 @@ jobs:
|
|
|
91
104
|
- uses: actions/setup-node@v7
|
|
92
105
|
with: { node-version: 22 }
|
|
93
106
|
- run: npm ci && npm run build
|
|
94
|
-
- uses: niksa90/toolmenu@v0.
|
|
107
|
+
- uses: niksa90/toolmenu@v0.14.0
|
|
95
108
|
with:
|
|
96
109
|
command: node dist/server.js
|
|
97
110
|
baseline: menu.json # your committed snapshot
|
|
@@ -166,7 +179,9 @@ serves, and 23 issue and pull-request tools that only the dynamic mode has.
|
|
|
166
179
|
| `session/unannounced` | warn | The menu changed without `notifications/tools/list_changed`, although the server declared `listChanged` |
|
|
167
180
|
| `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 |
|
|
168
181
|
| `session/refused`, `session/step-failed` | error | A write the scenario didn't allow, or a call that failed for another reason |
|
|
169
|
-
| `session/tool-error` | warn | A tool that answered with an error for another reason (`isError`): the run tested less than it looks |
|
|
182
|
+
| `session/tool-error` | warn | A tool that answered with an error for another reason (`isError`): the run tested less than it looks. The same error at several steps is one finding that names them |
|
|
183
|
+
| `session/known-variance` | info | A mid-session change only in values that already vary from one tools/list to the next: same cause as the finding it names, not counted again |
|
|
184
|
+
| `session/assumed-read-only` | info | Tools called on your word (`--assume-read-only`, `assume_read_only`) although the server doesn't mark them readOnlyHint |
|
|
170
185
|
| `session/unlock-coverage` | warn | An unlock whose enum lists its values, called with only some of them: the tools behind the rest were never seen, so a baseline from the session misses them. With `--union-out` or `--auto`, an unlock never called at all too, with why `--auto` skipped it |
|
|
171
186
|
| `session/nothing-called` | warn | `--auto` called no tools (all open-world, missing values, or not read-only): the run only listed the menu |
|
|
172
187
|
| `session/session-lost` | error | The server ended the session after toolmenu opened a second connection with the same credentials (servers with one session per client). The run stops there; rerun with `--processes 1` |
|
|
@@ -177,10 +192,17 @@ serves, and 23 issue and pull-request tools that only the dynamic mode has.
|
|
|
177
192
|
whose required arguments the schema itself gives (a `default`, `examples`, an `enum`,
|
|
178
193
|
a type or format), cheapest first, then every value of each read-only unlock (outside
|
|
179
194
|
`--max-calls`, and the first value twice: a second identical unlock should change
|
|
180
|
-
nothing), then the first call again. It never guesses an ID:
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
195
|
+
nothing), then the first call again. It never guesses an ID: a tool that needs
|
|
196
|
+
`owner`, `repo` or an issue key is skipped, and the report names the flag that fills
|
|
197
|
+
it: `--value repo_path=/src/app` fills that parameter on every tool that requires it,
|
|
198
|
+
`--value get_issue.issue_key=ABC-1` on one tool, `--values-file values.yml` takes a map
|
|
199
|
+
of either. Servers that don't mark their tools `readOnlyHint` (DeepWiki, every
|
|
200
|
+
2024-11-05 server) get nothing called unless you vouch for them by name:
|
|
201
|
+
`--assume-read-only read_wiki_structure,ask_wiki_question`. Only exact names are
|
|
202
|
+
accepted: a pattern would also cover tools a later release adds. A tool marked or
|
|
203
|
+
named as a write is never called, and the report says which tools ran on your word.
|
|
204
|
+
`--save-scenario auto.yml` writes the steps, with the skipped tools commented out, for
|
|
205
|
+
you to fill in. Tools marked `openWorldHint: true` (web
|
|
184
206
|
search, fetch, scraping, which can cost API credits) are called only with
|
|
185
207
|
`--open-world`, except unlocks: changing the menu is what a session watches, and an
|
|
186
208
|
unlock spends no search credits, so it runs even on a server that marks every tool
|
|
@@ -200,11 +222,16 @@ npx toolmenu diff menu.json new-menu.json
|
|
|
200
222
|
```
|
|
201
223
|
$ npx toolmenu diff --release 2026.1.14..2026.8.31 fs-2026.1.14.json fs-2026.8.31.json
|
|
202
224
|
toolmenu diff secure-filesystem-server 2026.1.14 → 2026.8.31
|
|
203
|
-
|
|
204
|
-
|
|
225
|
+
changes 1 breaking (1 tool) · 0 minor · 3 notice (13 tools)
|
|
226
|
+
version suggested bump: major · not checked (calendar version)
|
|
227
|
+
tokens ~1,640 → ~1,664 (+24, estimate): this release adds ~24 tokens to every conversation that loads the menu
|
|
228
|
+
tools 14 → 14
|
|
205
229
|
|
|
206
230
|
ERROR diff/safety-hint
|
|
207
|
-
move_file was additive-only and is now destructive.
|
|
231
|
+
`move_file` was marked additive-only and is now destructive (destructiveHint false → true; unset means destructive). Clients that auto-approve additive tools may now ask first.
|
|
232
|
+
→ Next: If the tool still never deletes or overwrites, set destructiveHint: false; if it does now, say so in the release notes.
|
|
233
|
+
INFO diff/annotations
|
|
234
|
+
Annotations changed the same way (openWorldHint (unset) → false) in 13 of 14 tools: read_file, read_text_file, read_media_file, read_multiple_files, write_file, edit_file, … (+7).
|
|
208
235
|
…
|
|
209
236
|
```
|
|
210
237
|
|
|
@@ -215,9 +242,9 @@ the way OpenAPI breaking-change checkers do it:
|
|
|
215
242
|
|
|
216
243
|
| Class | Changes | Rules |
|
|
217
244
|
|---|---|---|
|
|
218
|
-
| **breaking** (error) | tool removed or renamed, parameter removed, new required parameter, narrower or different type, enum narrowed, a tool becoming less safe (no longer read-only, or additive → destructive) | `diff/tool-removed`, `diff/tool-renamed`, `diff/param-removed`, `diff/param-required`, `diff/param-type`, `diff/enum-narrowed`, `diff/safety-hint` |
|
|
219
|
-
| **minor** (info) | tool added, new optional parameter, parameter now optional, type or enum widened | `diff/tool-added`, `diff/param-added`, `diff/param-relaxed`, `diff/type-widened`, `diff/enum-widened` |
|
|
220
|
-
| **notice** (info) | optional parameter dropped (extra properties still allowed), description changed (with the text diff: it changes what the agent does), output schema, annotations, other fields, order, a schema restructured but accepting the same input | `diff/param-dropped`, `diff/description`, `diff/schema-other`, `diff/annotations`, `diff/other`, `diff/order`, `diff/schema-equivalent` |
|
|
245
|
+
| **breaking** (error) | tool removed or renamed, parameter removed, new required parameter, narrower or different type, enum narrowed, unlisted properties now rejected (`additionalProperties: false` added), a tool becoming less safe (no longer read-only, or additive → destructive) | `diff/tool-removed`, `diff/tool-renamed`, `diff/param-removed`, `diff/param-required`, `diff/param-type`, `diff/enum-narrowed`, `diff/properties-closed`, `diff/safety-hint` |
|
|
246
|
+
| **minor** (info) | tool added, new optional parameter, parameter now optional, type or enum widened, unlisted properties now accepted (`additionalProperties: false` removed) | `diff/tool-added`, `diff/param-added`, `diff/param-relaxed`, `diff/type-widened`, `diff/enum-widened`, `diff/properties-opened` |
|
|
247
|
+
| **notice** (info) | optional parameter dropped (extra properties still allowed), description changed (with the text diff: it changes what the agent does), output schema, annotations, other fields, order, a schema restructured but accepting the same input, only the declared `$schema` dialect changed | `diff/param-dropped`, `diff/description`, `diff/schema-other`, `diff/annotations`, `diff/other`, `diff/order`, `diff/schema-equivalent`, `diff/schema-dialect` |
|
|
221
248
|
|
|
222
249
|
The same rules apply inside parameters: fields of an object parameter, array items,
|
|
223
250
|
and the options of an `anyOf`/`oneOf` union (zod's unions, discriminated unions and
|
|
@@ -238,11 +265,26 @@ On mongodb-mcp-server 2.1.2 → 3.0.0 this finds `aggregate.pipeline[]…$vector
|
|
|
238
265
|
and `.limit` narrowed from `number` to `integer` inside a union, where the whole
|
|
239
266
|
`pipeline` used to be one "review it".
|
|
240
267
|
|
|
268
|
+
Different spellings of the same schema are one schema (`additionalProperties` absent,
|
|
269
|
+
`true` or `{}`; zod 4's safe-integer bounds), and a change every tool shares is said
|
|
270
|
+
once for the menu: a server moving from zod 3 to zod 4 reads as its real changes (a
|
|
271
|
+
field that became required, the patterns zod 4 adds to `email` and `uuid`) plus one
|
|
272
|
+
`diff/properties-opened` line ("27 tools now accept properties they don't list … most
|
|
273
|
+
likely a schema generator upgrade"), not a "review it" per object.
|
|
274
|
+
|
|
275
|
+
The same change in many tools is reported once, with the tools it touches (`pageId`
|
|
276
|
+
is new and required in 25 of 29 tools, on chrome-devtools-mcp 1.8.0); counts are per
|
|
277
|
+
change. When a tool loses a parameter and gains a required one with a close name,
|
|
278
|
+
`diff/param-renamed` (warn, unsure) points out the likely rename; both changes stay
|
|
279
|
+
breaking. Every breaking finding's next step names the version to release when the
|
|
280
|
+
bump is too small.
|
|
281
|
+
|
|
241
282
|
It also reports the token change per tool and suggests a semver bump. To check the
|
|
242
283
|
bump, pass the **release** versions: `--release 1.4.0..1.5.0` (npm, a git tag).
|
|
243
|
-
`diff/version-bump` then warns when the release's bump is smaller
|
|
244
|
-
|
|
245
|
-
|
|
284
|
+
`diff/version-bump` then warns when the release's bump is smaller. Under 1.0.0 it
|
|
285
|
+
reads versions as npm's caret does (`^0.2.3` accepts any 0.2.x): breaking changes need
|
|
286
|
+
a minor bump, new features a patch, and under 0.1.0 anything goes.
|
|
287
|
+
`diff/version-backwards` warns when the version goes down. Calendar versions and prereleases aren't judged. The version in the snapshot is what the
|
|
246
288
|
server reports (`serverInfo.version`), which is often not the release: the filesystem
|
|
247
289
|
server has said `0.2.0` for 19 releases (FINDINGS F5). It's shown, and only checked
|
|
248
290
|
with `--server-version-is-release`. `diff` also enforces an optional `tokenBudget`
|
|
@@ -268,7 +310,9 @@ names, then searches for every operation it finds or sees mentioned, until 20 qu
|
|
|
268
310
|
in a row turn up nothing new (at most 200). On Atlassian's hosted server that finds all
|
|
269
311
|
154 operations behind its 21 tools; on Sentry's, 65 behind 9, the same on every run.
|
|
270
312
|
Queries are paced and a rate limit is waited out. An operation not found this time is a
|
|
271
|
-
notice ("not returned by the same queries"), never "removed"
|
|
313
|
+
notice (`diff/catalog-missing`: "not returned by the same queries"), never "removed";
|
|
314
|
+
one found only now is `diff/catalog-added`, and catalogs read with different queries,
|
|
315
|
+
or partly (a query failed), are `diff/catalog-queries`. To steer it, set
|
|
272
316
|
`"catalog": { "queries": [...], "maxQueries": 200, "crawl": true }` in
|
|
273
317
|
`toolmenu.config.json` (FINDINGS F15).
|
|
274
318
|
|
|
@@ -277,6 +321,17 @@ catalog names, and whose words no query uses, stays unfound. On `@sentry/mcp-ser
|
|
|
277
321
|
0.42 (stdio) it finds 63 of the 64 operations in the package's catalog; `whoami` comes
|
|
278
322
|
back only when asked for by name. Add queries like that to `catalog.queries`.
|
|
279
323
|
|
|
324
|
+
**Command routers.** Some servers put their operations behind router tools instead:
|
|
325
|
+
one tool per area that takes a `command` and its `parameters`, and lists its commands
|
|
326
|
+
when called with `learn: true` (Azure's MCP server serves 71 such tools in front of
|
|
327
|
+
~410 operations). `--catalog` detects them (a `command` parameter, an arguments
|
|
328
|
+
object, a boolean listing flag, and a description that says "router" or "sub
|
|
329
|
+
commands") and calls each once in its listing mode, never with a command, so nothing
|
|
330
|
+
runs. Routers whose command is required aren't called. Detection missed one? Name
|
|
331
|
+
them: `"catalog": { "routers": ["keyvault", "storage"] }`. A router lists everything
|
|
332
|
+
it has, so unlike a search the catalog is complete except for routers that failed
|
|
333
|
+
(`catalog/failed` says which, and why).
|
|
334
|
+
|
|
280
335
|
## `history`: a package's releases, researched
|
|
281
336
|
|
|
282
337
|
```sh
|
|
@@ -306,6 +361,9 @@ into description and schema), large enums, and waste you can remove:
|
|
|
306
361
|
- **Unused `$defs`**: definitions nothing in the tool refers to. Notion's server 2.5.2
|
|
307
362
|
ships the same 9 in all 24 tools, 72% of its menu.
|
|
308
363
|
|
|
364
|
+
Every tool's estimate is in the menu file, for the ones the summary leaves out:
|
|
365
|
+
`jq -r '.tools[] | "\(.tokens)\t\(.name)"' menu.json | sort -rn`.
|
|
366
|
+
|
|
309
367
|
## `snapshot` rules
|
|
310
368
|
|
|
311
369
|
Every rule comes from a failure I actually hit building 115 tools for one MCP
|
|
@@ -321,10 +379,11 @@ server, or from the spec itself. If a rule can't point to one, it doesn't ship.
|
|
|
321
379
|
| `menu/duplicate-name` | error | Two tools with the same name: only one can be called, and some clients reject the list |
|
|
322
380
|
| `naming/route` | error | A `routes.yml` expectation broke: a keyword now matches the wrong tool at least as well as the right one |
|
|
323
381
|
| `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 |
|
|
324
|
-
| `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 |
|
|
325
|
-
| `
|
|
382
|
+
| `description/cut` | info | Descriptions longer than the client sends, with nothing that reads as an instruction past the cut, as one summary that shows where each one is cut. The model gets a prefix that can read as complete |
|
|
383
|
+
| `description/late-instruction` | info | With the default cut: instructions after character 280, which a client that cuts descriptions short would hide, as one summary. Set `descriptionLimit` and `description/buried` checks your real cut instead. (Before 0.13 this was part of `description/cut`; that id's setting still applies.) |
|
|
384
|
+
| `naming/vague-id` | warn | Parameters called just `id` that don't say *which* thing, as one summary with a suggested name |
|
|
326
385
|
| `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) |
|
|
327
|
-
| `write/unannotated` | warn |
|
|
386
|
+
| `write/unannotated` | warn | Tools named like writes (`delete_`, `send_`…) with no annotations, as one summary grouped by the annotation each name suggests |
|
|
328
387
|
| `naming/shared-word` | info | Nouns that name different things across tools (`list_team_audits` vs `get_audit_trail`), as one summary |
|
|
329
388
|
| `write/no-dry-run` | info | Destructive tools with no dry-run parameter or preview tool, as one summary |
|
|
330
389
|
| `spec/discover` | info | The server only speaks the 2025 protocol, so 2026-07-28 rules are skipped |
|
|
@@ -402,12 +461,14 @@ toolmenu sees what the server sends. Plenty of agent failures happen elsewhere:
|
|
|
402
461
|
--env <K=V> env var for a stdio server, repeatable (it only gets a
|
|
403
462
|
minimal environment otherwise)
|
|
404
463
|
--timeout <ms> per-request timeout (default: 30000)
|
|
464
|
+
--protocol <p> auto (default), legacy (2025 handshake only) or modern
|
|
465
|
+
(2026-07-28 only; an error if the server lacks it)
|
|
405
466
|
--processes <n> server processes or connections to compare (default: 2);
|
|
406
467
|
1 opens no second one, session's scope check included
|
|
407
468
|
```
|
|
408
469
|
|
|
409
470
|
Exit codes: `0` clean · `1` findings at or above `--fail-on` · `2` couldn't connect
|
|
410
|
-
or bad usage. `toolmenu --help` lists
|
|
471
|
+
or bad usage. `toolmenu <command> --help` lists that command's own options.
|
|
411
472
|
|
|
412
473
|
## Limitations
|
|
413
474
|
|
|
@@ -426,9 +487,9 @@ or bad usage. `toolmenu --help` lists the `session` and `history` options.
|
|
|
426
487
|
|
|
427
488
|
## About
|
|
428
489
|
|
|
429
|
-
Built by [
|
|
490
|
+
Built by [Nikša Perović](https://niksa.me) while running a 115-tool MCP server and watching
|
|
430
491
|
agents trip over its menu. Every rule started as one of those failures, and the
|
|
431
|
-
research behind them is in [docs/FINDINGS.md](https://github.com/niksa90/toolmenu/blob/main/docs/FINDINGS.md).
|
|
492
|
+
research behind them is in [docs/FINDINGS.md](https://github.com/niksa90/toolmenu/blob/main/docs/FINDINGS.md). The story of building it, and where it was wrong, is [on niksa.me](https://niksa.me/toolmenu).
|
|
432
493
|
|
|
433
494
|
Found a false positive, or a failure toolmenu should catch?
|
|
434
495
|
[Open an issue](https://github.com/niksa90/toolmenu/issues) with the menu (a
|
package/dist/args.d.ts
CHANGED
|
@@ -7,15 +7,41 @@ export type Synthesized = {
|
|
|
7
7
|
ok: false;
|
|
8
8
|
};
|
|
9
9
|
/**
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
10
|
+
* Does a value fit the schema's type, enum and const? Only the checks that catch a
|
|
11
|
+
* default the server itself wouldn't accept (Microsoft Learn: `default: null` on a
|
|
12
|
+
* `type: "string"`); patterns and formats are the server's business.
|
|
13
|
+
*/
|
|
14
|
+
export declare function fits(value: unknown, schema: JsonSchema | undefined): boolean;
|
|
15
|
+
/**
|
|
16
|
+
* A value the schema itself vouches for: `const`, a `default` or `examples` value
|
|
17
|
+
* that fits the type, `enum`, then by type and format. Never a guess at an ID or
|
|
18
|
+
* anything with a `pattern`, and never an empty list for a list it has to fill: a
|
|
19
|
+
* tool that needs one is skipped, not called with junk.
|
|
13
20
|
*/
|
|
14
21
|
export declare function synthesize(schema: JsonSchema | undefined, name?: string): Synthesized;
|
|
15
|
-
/**
|
|
16
|
-
|
|
22
|
+
/**
|
|
23
|
+
* A value the user gave (--value), made to fit the parameter: `5` is the number 5
|
|
24
|
+
* for an integer and the string "5" for a string; JSON that doesn't fit the type
|
|
25
|
+
* falls back to the text as typed.
|
|
26
|
+
*/
|
|
27
|
+
export declare function fitValue(given: {
|
|
28
|
+
raw?: string;
|
|
29
|
+
value: unknown;
|
|
30
|
+
}, schema: JsonSchema | undefined): unknown;
|
|
31
|
+
/** Where a tool's argument came from: the user (--value) or the schema. */
|
|
32
|
+
export type ArgSource = 'value' | 'schema';
|
|
33
|
+
/**
|
|
34
|
+
* Arguments for a tool's required parameters, or the ones it can't fill. `given`:
|
|
35
|
+
* values the user supplied for this tool, by parameter name; they come first, and
|
|
36
|
+
* one for an optional parameter is passed too.
|
|
37
|
+
*/
|
|
38
|
+
export declare function synthesizeArgs(schema: JsonSchema | undefined, given?: Record<string, {
|
|
39
|
+
raw?: string;
|
|
40
|
+
value: unknown;
|
|
41
|
+
}>): {
|
|
17
42
|
ok: true;
|
|
18
43
|
args: Record<string, unknown>;
|
|
44
|
+
sources: Record<string, ArgSource>;
|
|
19
45
|
} | {
|
|
20
46
|
ok: false;
|
|
21
47
|
missing: string[];
|
package/dist/args.js
CHANGED
|
@@ -3,19 +3,60 @@ const DATE_TIME = '2026-01-01T00:00:00Z';
|
|
|
3
3
|
const DATE = '2026-01-01';
|
|
4
4
|
const SEARCH_WORDS = /^(q|query|search|search_?query|text|keywords?|terms?|prompt|question)$/i;
|
|
5
5
|
/**
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
6
|
+
* Does a value fit the schema's type, enum and const? Only the checks that catch a
|
|
7
|
+
* default the server itself wouldn't accept (Microsoft Learn: `default: null` on a
|
|
8
|
+
* `type: "string"`); patterns and formats are the server's business.
|
|
9
|
+
*/
|
|
10
|
+
export function fits(value, schema) {
|
|
11
|
+
if (!schema || typeof schema !== 'object')
|
|
12
|
+
return true;
|
|
13
|
+
if ('const' in schema && JSON.stringify(schema.const) !== JSON.stringify(value))
|
|
14
|
+
return false;
|
|
15
|
+
if (schema.enum?.length && !schema.enum.some((e) => JSON.stringify(e) === JSON.stringify(value)))
|
|
16
|
+
return false;
|
|
17
|
+
const branches = (schema.anyOf ?? schema.oneOf);
|
|
18
|
+
if (Array.isArray(branches) && branches.length && !branches.some((b) => fits(value, b)))
|
|
19
|
+
return false;
|
|
20
|
+
if (schema.type === undefined)
|
|
21
|
+
return true;
|
|
22
|
+
const types = Array.isArray(schema.type) ? schema.type : [schema.type];
|
|
23
|
+
return types.some((t) => {
|
|
24
|
+
switch (t) {
|
|
25
|
+
case 'null':
|
|
26
|
+
return value === null;
|
|
27
|
+
case 'string':
|
|
28
|
+
return typeof value === 'string';
|
|
29
|
+
case 'boolean':
|
|
30
|
+
return typeof value === 'boolean';
|
|
31
|
+
case 'integer':
|
|
32
|
+
return Number.isInteger(value);
|
|
33
|
+
case 'number':
|
|
34
|
+
return typeof value === 'number' && Number.isFinite(value);
|
|
35
|
+
case 'array':
|
|
36
|
+
return Array.isArray(value) && (!schema.items || value.every((v) => fits(v, schema.items)));
|
|
37
|
+
case 'object':
|
|
38
|
+
return !!value && typeof value === 'object' && !Array.isArray(value);
|
|
39
|
+
default:
|
|
40
|
+
return true;
|
|
41
|
+
}
|
|
42
|
+
});
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* A value the schema itself vouches for: `const`, a `default` or `examples` value
|
|
46
|
+
* that fits the type, `enum`, then by type and format. Never a guess at an ID or
|
|
47
|
+
* anything with a `pattern`, and never an empty list for a list it has to fill: a
|
|
48
|
+
* tool that needs one is skipped, not called with junk.
|
|
9
49
|
*/
|
|
10
50
|
export function synthesize(schema, name = '') {
|
|
11
51
|
if (!schema || typeof schema !== 'object')
|
|
12
52
|
return { ok: false };
|
|
13
53
|
if ('const' in schema)
|
|
14
54
|
return { ok: true, value: schema.const };
|
|
15
|
-
if ('default' in schema)
|
|
55
|
+
if ('default' in schema && fits(schema.default, schema))
|
|
16
56
|
return { ok: true, value: schema.default };
|
|
17
|
-
|
|
18
|
-
|
|
57
|
+
const example = Array.isArray(schema.examples) ? schema.examples.find((e) => fits(e, schema)) : undefined;
|
|
58
|
+
if (example !== undefined)
|
|
59
|
+
return { ok: true, value: example };
|
|
19
60
|
if (schema.enum?.length)
|
|
20
61
|
return { ok: true, value: schema.enum[0] };
|
|
21
62
|
const branches = (schema.anyOf ?? schema.oneOf);
|
|
@@ -53,10 +94,10 @@ export function synthesize(schema, name = '') {
|
|
|
53
94
|
return { ok: false };
|
|
54
95
|
}
|
|
55
96
|
case 'array': {
|
|
97
|
+
// A required list is there to be filled: `{"urls": []}` is refused by the
|
|
98
|
+
// server (Exa's web_fetch_exa), or does nothing. No item, no call.
|
|
56
99
|
const item = synthesize(schema.items, name);
|
|
57
|
-
|
|
58
|
-
return { ok: true, value: [item.value] };
|
|
59
|
-
return typeof schema.minItems === 'number' && schema.minItems > 0 ? { ok: false } : { ok: true, value: [] };
|
|
100
|
+
return item.ok ? { ok: true, value: [item.value] } : { ok: false };
|
|
60
101
|
}
|
|
61
102
|
case 'object': {
|
|
62
103
|
const args = synthesizeArgs(schema);
|
|
@@ -66,16 +107,52 @@ export function synthesize(schema, name = '') {
|
|
|
66
107
|
return { ok: false };
|
|
67
108
|
}
|
|
68
109
|
}
|
|
69
|
-
/**
|
|
70
|
-
|
|
110
|
+
/**
|
|
111
|
+
* A value the user gave (--value), made to fit the parameter: `5` is the number 5
|
|
112
|
+
* for an integer and the string "5" for a string; JSON that doesn't fit the type
|
|
113
|
+
* falls back to the text as typed.
|
|
114
|
+
*/
|
|
115
|
+
export function fitValue(given, schema) {
|
|
116
|
+
if (fits(given.value, schema))
|
|
117
|
+
return given.value;
|
|
118
|
+
if (given.raw !== undefined && fits(given.raw, schema))
|
|
119
|
+
return given.raw;
|
|
120
|
+
// A single value for a list: --value urls=https://… means ["https://…"].
|
|
121
|
+
if (schema?.type === 'array' && fits([given.value], schema))
|
|
122
|
+
return [given.value];
|
|
123
|
+
return given.value;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Arguments for a tool's required parameters, or the ones it can't fill. `given`:
|
|
127
|
+
* values the user supplied for this tool, by parameter name; they come first, and
|
|
128
|
+
* one for an optional parameter is passed too.
|
|
129
|
+
*/
|
|
130
|
+
export function synthesizeArgs(schema, given = {}) {
|
|
71
131
|
const args = {};
|
|
132
|
+
const sources = {};
|
|
72
133
|
const missing = [];
|
|
73
|
-
|
|
134
|
+
const required = schema?.required ?? [];
|
|
135
|
+
for (const param of required) {
|
|
136
|
+
if (param in given) {
|
|
137
|
+
args[param] = fitValue(given[param], schema?.properties?.[param]);
|
|
138
|
+
sources[param] = 'value';
|
|
139
|
+
continue;
|
|
140
|
+
}
|
|
74
141
|
const v = synthesize(schema?.properties?.[param], param);
|
|
75
|
-
if (v.ok)
|
|
142
|
+
if (v.ok) {
|
|
76
143
|
args[param] = v.value;
|
|
144
|
+
sources[param] = 'schema';
|
|
145
|
+
}
|
|
77
146
|
else
|
|
78
147
|
missing.push(param);
|
|
79
148
|
}
|
|
80
|
-
|
|
149
|
+
if (missing.length)
|
|
150
|
+
return { ok: false, missing };
|
|
151
|
+
for (const [param, g] of Object.entries(given)) {
|
|
152
|
+
if (param in args || !schema?.properties || !(param in schema.properties))
|
|
153
|
+
continue;
|
|
154
|
+
args[param] = fitValue(g, schema.properties[param]);
|
|
155
|
+
sources[param] = 'value';
|
|
156
|
+
}
|
|
157
|
+
return { ok: true, args, sources };
|
|
81
158
|
}
|
package/dist/auth.d.ts
CHANGED
|
@@ -6,7 +6,7 @@ import type { OAuthClientInformationContext, OAuthClientMetadata, OAuthClientPro
|
|
|
6
6
|
export declare const DEFAULT_PORT = 33418;
|
|
7
7
|
/** Where logins live: $TOOLMENU_AUTH_DIR, else $XDG_CONFIG_HOME/toolmenu/auth, else ~/.config/toolmenu/auth. */
|
|
8
8
|
export declare function authDir(): string;
|
|
9
|
-
/** Is there a stored
|
|
9
|
+
/** Is there a stored file for this server (a login, or what's left of one)? Why a login is needed reads its contents. */
|
|
10
10
|
export declare function hasLogin(serverUrl: string): boolean;
|
|
11
11
|
export interface ProviderOptions {
|
|
12
12
|
/** A browser login may start (auth login). Otherwise a needed login is an error. */
|
|
@@ -28,6 +28,8 @@ export declare class StoredOAuthProvider implements OAuthClientProvider {
|
|
|
28
28
|
private readonly options;
|
|
29
29
|
private data;
|
|
30
30
|
private expectedState;
|
|
31
|
+
/** invalidateCredentials('all') deleted a file that held tokens, in this run. */
|
|
32
|
+
private removedLogin;
|
|
31
33
|
constructor(serverUrl: string, options?: ProviderOptions);
|
|
32
34
|
private stored;
|
|
33
35
|
private update;
|
|
@@ -50,7 +52,7 @@ export declare class StoredOAuthProvider implements OAuthClientProvider {
|
|
|
50
52
|
invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): Promise<void>;
|
|
51
53
|
}
|
|
52
54
|
export declare class LoginNeededError extends Error {
|
|
53
|
-
constructor(serverUrl: string);
|
|
55
|
+
constructor(serverUrl: string, why?: string);
|
|
54
56
|
}
|
|
55
57
|
export interface LoginOptions extends Omit<ProviderOptions, 'interactive' | 'onRedirect'> {
|
|
56
58
|
/** How to show the authorization URL. Default: print it and try to open a browser. */
|
package/dist/auth.js
CHANGED
|
@@ -7,6 +7,7 @@ import { homedir } from 'node:os';
|
|
|
7
7
|
import { join } from 'node:path';
|
|
8
8
|
import { Client, StreamableHTTPClientTransport, UnauthorizedError } from '@modelcontextprotocol/client';
|
|
9
9
|
import { VERSION } from './version.js';
|
|
10
|
+
import { endSession } from './close.js';
|
|
10
11
|
/**
|
|
11
12
|
* The redirect port. Fixed, not random: dynamic registration records the exact
|
|
12
13
|
* redirect URI, so a new port would invalidate the stored client on every login.
|
|
@@ -37,7 +38,7 @@ async function save(data) {
|
|
|
37
38
|
await writeFile(path, JSON.stringify({ ...data, savedAt: new Date().toISOString() }, null, 2) + '\n', { mode: 0o600 });
|
|
38
39
|
await chmod(path, 0o600);
|
|
39
40
|
}
|
|
40
|
-
/** Is there a stored
|
|
41
|
+
/** Is there a stored file for this server (a login, or what's left of one)? Why a login is needed reads its contents. */
|
|
41
42
|
export function hasLogin(serverUrl) {
|
|
42
43
|
return existsSync(storePath(serverUrl));
|
|
43
44
|
}
|
|
@@ -51,6 +52,8 @@ export class StoredOAuthProvider {
|
|
|
51
52
|
options;
|
|
52
53
|
data;
|
|
53
54
|
expectedState;
|
|
55
|
+
/** invalidateCredentials('all') deleted a file that held tokens, in this run. */
|
|
56
|
+
removedLogin = false;
|
|
54
57
|
constructor(serverUrl, options = {}) {
|
|
55
58
|
this.serverUrl = serverUrl;
|
|
56
59
|
this.options = options;
|
|
@@ -124,11 +127,11 @@ export class StoredOAuthProvider {
|
|
|
124
127
|
return (await this.stored()).tokens;
|
|
125
128
|
}
|
|
126
129
|
async saveTokens(tokens, ctx) {
|
|
127
|
-
await this.update({ tokens, ...(ctx?.issuer ? { issuer: ctx.issuer } : {}) });
|
|
130
|
+
await this.update({ tokens, rejected: undefined, ...(ctx?.issuer ? { issuer: ctx.issuer } : {}) });
|
|
128
131
|
}
|
|
129
132
|
async redirectToAuthorization(authorizationUrl) {
|
|
130
133
|
if (!this.options.interactive) {
|
|
131
|
-
throw new LoginNeededError(this.serverUrl);
|
|
134
|
+
throw new LoginNeededError(this.serverUrl, whyLoginNeeded(await this.stored(), this.removedLogin));
|
|
132
135
|
}
|
|
133
136
|
await this.options.onRedirect?.(authorizationUrl);
|
|
134
137
|
}
|
|
@@ -138,7 +141,7 @@ export class StoredOAuthProvider {
|
|
|
138
141
|
async codeVerifier() {
|
|
139
142
|
const v = (await this.stored()).codeVerifier;
|
|
140
143
|
if (!v)
|
|
141
|
-
throw new Error(
|
|
144
|
+
throw new Error(`No PKCE code verifier is saved for ${this.serverUrl}: the stored login changed while this one ran (another login at the same time?).\n→ Next: Run toolmenu auth login ${this.serverUrl} again.`);
|
|
142
145
|
return v;
|
|
143
146
|
}
|
|
144
147
|
async saveDiscoveryState(discoveryState) {
|
|
@@ -150,15 +153,22 @@ export class StoredOAuthProvider {
|
|
|
150
153
|
async invalidateCredentials(scope) {
|
|
151
154
|
const s = await this.stored();
|
|
152
155
|
if (scope === 'all') {
|
|
156
|
+
this.removedLogin ||= Boolean(s.tokens) || Boolean(s.rejected);
|
|
153
157
|
this.data = { serverUrl: s.serverUrl };
|
|
154
158
|
await rm(storePath(this.serverUrl), { force: true });
|
|
155
159
|
return;
|
|
156
160
|
}
|
|
157
161
|
const patch = {};
|
|
158
|
-
if (scope === 'client')
|
|
162
|
+
if (scope === 'client') {
|
|
159
163
|
patch.clientInformation = undefined;
|
|
160
|
-
|
|
164
|
+
if (s.tokens)
|
|
165
|
+
patch.rejected = 'client';
|
|
166
|
+
}
|
|
167
|
+
if (scope === 'tokens') {
|
|
161
168
|
patch.tokens = undefined;
|
|
169
|
+
if (s.tokens)
|
|
170
|
+
patch.rejected ??= s.rejected ?? 'refresh';
|
|
171
|
+
}
|
|
162
172
|
if (scope === 'verifier')
|
|
163
173
|
patch.codeVerifier = undefined;
|
|
164
174
|
if (scope === 'discovery')
|
|
@@ -166,9 +176,28 @@ export class StoredOAuthProvider {
|
|
|
166
176
|
await this.update(patch);
|
|
167
177
|
}
|
|
168
178
|
}
|
|
179
|
+
/**
|
|
180
|
+
* Why snapshot or session needs a login, from what's stored: nothing, a registration
|
|
181
|
+
* from a login that never finished, tokens the server refused, or a login the server
|
|
182
|
+
* rejected and toolmenu removed (removedLogin: in this run).
|
|
183
|
+
*/
|
|
184
|
+
function whyLoginNeeded(s, removedLogin) {
|
|
185
|
+
if (removedLogin)
|
|
186
|
+
return 'the server rejected the stored login for it, so toolmenu removed it';
|
|
187
|
+
if (s.rejected === 'client')
|
|
188
|
+
return "the stored login no longer works: the server doesn't accept the client toolmenu registered (it may have been deleted), so its tokens were dropped";
|
|
189
|
+
if (s.rejected === 'refresh')
|
|
190
|
+
return 'the stored login no longer works: its token expired or was revoked and the server refused to refresh it';
|
|
191
|
+
if (s.tokens)
|
|
192
|
+
return 'the stored login no longer works: the server refused its token';
|
|
193
|
+
if (s.clientInformation)
|
|
194
|
+
return "there's no stored login for it: an earlier toolmenu auth login registered a client but didn't finish";
|
|
195
|
+
return `there's no stored login for it (stored in ${authDir()})`;
|
|
196
|
+
}
|
|
169
197
|
export class LoginNeededError extends Error {
|
|
170
|
-
constructor(serverUrl) {
|
|
171
|
-
super(`${serverUrl}
|
|
198
|
+
constructor(serverUrl, why = `there's no stored login for it (stored in ${authDir()})`) {
|
|
199
|
+
super(`${serverUrl} asks for an OAuth login, and ${why}. snapshot and session don't open a browser.\n` +
|
|
200
|
+
`→ Next: Log in once in a terminal with a browser: toolmenu auth login ${serverUrl}. Or pass a token: --header "Authorization: Bearer <token>".`);
|
|
172
201
|
}
|
|
173
202
|
}
|
|
174
203
|
/**
|
|
@@ -190,18 +219,22 @@ export async function login(serverUrl, options = {}) {
|
|
|
190
219
|
try {
|
|
191
220
|
await client.connect(transport);
|
|
192
221
|
// Already logged in with a valid (or refreshed) token.
|
|
193
|
-
await client
|
|
222
|
+
await endSession(client, transport);
|
|
194
223
|
}
|
|
195
224
|
catch (error) {
|
|
196
225
|
if (!(error instanceof UnauthorizedError))
|
|
197
226
|
throw error;
|
|
198
227
|
const params = await callback.params;
|
|
199
|
-
if (params.get('error'))
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
228
|
+
if (params.get('error')) {
|
|
229
|
+
const described = params.get('error_description');
|
|
230
|
+
throw new Error(`The authorization server refused the login for ${serverUrl}: ${params.get('error')}${described ? ` (“${described}”)` : ''}.\n` +
|
|
231
|
+
`→ Next: Try again. If it repeats, ask for fewer scopes with --scope, or check the account may use this server.`);
|
|
232
|
+
}
|
|
233
|
+
if (!provider.lastState || params.get('state') !== provider.lastState) {
|
|
234
|
+
throw new Error(`The login callback for ${serverUrl} carried the wrong state (not the one this login sent), so it was ignored (an old browser tab, or a second login at once).\n→ Next: Run toolmenu auth login ${serverUrl} again and use the tab it opens.`);
|
|
235
|
+
}
|
|
203
236
|
await transport.finishAuth(params);
|
|
204
|
-
await client
|
|
237
|
+
await endSession(client, transport);
|
|
205
238
|
}
|
|
206
239
|
return await check(serverUrl);
|
|
207
240
|
}
|
|
@@ -210,10 +243,10 @@ export async function login(serverUrl, options = {}) {
|
|
|
210
243
|
// register itself. Say what works instead.
|
|
211
244
|
if (error instanceof Error && /does not support dynamic client registration/i.test(error.message) && !options.clientId) {
|
|
212
245
|
error.message =
|
|
213
|
-
`${serverUrl} doesn't let clients register themselves (no dynamic client registration)
|
|
214
|
-
|
|
246
|
+
`${serverUrl} doesn't let clients register themselves (its authorization server has no dynamic client registration), so toolmenu can't log in without a client of its own.\n` +
|
|
247
|
+
`→ Next: Register an OAuth app with the provider, with the callback URL http://127.0.0.1:${port}/callback, then:\n` +
|
|
215
248
|
` toolmenu auth login ${serverUrl} --client-id <id> --client-secret <secret>\n` +
|
|
216
|
-
`
|
|
249
|
+
` Or skip OAuth and pass a token the server accepts: toolmenu snapshot ${serverUrl} --header "Authorization: Bearer <token>"`;
|
|
217
250
|
}
|
|
218
251
|
throw error;
|
|
219
252
|
}
|
|
@@ -224,13 +257,14 @@ export async function login(serverUrl, options = {}) {
|
|
|
224
257
|
/** Connect with the stored login and list tools: the login works. */
|
|
225
258
|
async function check(serverUrl) {
|
|
226
259
|
const client = new Client({ name: 'toolmenu', version: VERSION });
|
|
227
|
-
|
|
260
|
+
const transport = new StreamableHTTPClientTransport(new URL(serverUrl), { authProvider: new StoredOAuthProvider(serverUrl) });
|
|
261
|
+
await client.connect(transport);
|
|
228
262
|
try {
|
|
229
263
|
const { tools } = await client.listTools();
|
|
230
264
|
return { name: client.getServerVersion()?.name, tools: tools.length };
|
|
231
265
|
}
|
|
232
266
|
finally {
|
|
233
|
-
await client
|
|
267
|
+
await endSession(client, transport);
|
|
234
268
|
}
|
|
235
269
|
}
|
|
236
270
|
export async function logout(serverUrl) {
|
|
@@ -274,8 +308,12 @@ function listenForCallback(port, timeoutMs) {
|
|
|
274
308
|
res.end('<!doctype html><title>toolmenu</title><p>Logged in. You can close this tab and go back to the terminal.</p>');
|
|
275
309
|
resolveParams(url.searchParams);
|
|
276
310
|
});
|
|
277
|
-
const timer = setTimeout(() => rejectParams(new Error(`
|
|
278
|
-
|
|
311
|
+
const timer = setTimeout(() => rejectParams(new Error(`The browser login didn't come back within ${Math.round(timeoutMs / 1000)} s: nothing reached http://127.0.0.1:${port}/callback.\n` +
|
|
312
|
+
`→ Next: Run toolmenu auth login again and finish it in the browser. The browser has to run on this machine (127.0.0.1); over SSH, log in on your own machine and copy ${authDir()}, or pass a token with --header.`)), timeoutMs);
|
|
313
|
+
server.on('error', (error) => fail(error.code === 'EADDRINUSE'
|
|
314
|
+
? new Error(`Couldn't wait for the login's redirect: port ${port} on 127.0.0.1 is in use (another toolmenu login, or another program).\n` +
|
|
315
|
+
`→ Next: Close it, or pick another port with --port <n>. The login registers http://127.0.0.1:<n>/callback, so use the same port the next time too.`)
|
|
316
|
+
: error));
|
|
279
317
|
server.listen(port, '127.0.0.1', () => ready({
|
|
280
318
|
params,
|
|
281
319
|
close: () => {
|