toolmenu 0.20.1 → 0.23.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.
Files changed (68) hide show
  1. package/README.md +119 -41
  2. package/dist/apps.d.ts +56 -0
  3. package/dist/apps.js +99 -0
  4. package/dist/auth.d.ts +14 -0
  5. package/dist/auth.js +75 -2
  6. package/dist/auto.d.ts +6 -0
  7. package/dist/auto.js +70 -7
  8. package/dist/card.d.ts +18 -0
  9. package/dist/card.js +39 -0
  10. package/dist/cli.js +108 -24
  11. package/dist/colour.d.ts +8 -0
  12. package/dist/colour.js +70 -0
  13. package/dist/config.d.ts +2 -0
  14. package/dist/config.js +2 -0
  15. package/dist/connect.d.ts +14 -0
  16. package/dist/connect.js +45 -7
  17. package/dist/diff.js +112 -13
  18. package/dist/explain.d.ts +1 -0
  19. package/dist/explain.js +11 -0
  20. package/dist/failures.d.ts +24 -0
  21. package/dist/failures.js +58 -1
  22. package/dist/help.d.ts +1 -1
  23. package/dist/help.js +36 -4
  24. package/dist/mrtr.d.ts +9 -1
  25. package/dist/mrtr.js +17 -0
  26. package/dist/options.d.ts +15 -0
  27. package/dist/options.js +5 -0
  28. package/dist/probe.d.ts +11 -1
  29. package/dist/probe.js +18 -3
  30. package/dist/report.d.ts +3 -0
  31. package/dist/report.js +15 -8
  32. package/dist/rule-docs.d.ts +26 -0
  33. package/dist/rule-docs.js +88 -0
  34. package/dist/rule-docs.json +597 -0
  35. package/dist/rules/apps.d.ts +11 -0
  36. package/dist/rules/apps.js +156 -0
  37. package/dist/rules/auth.d.ts +18 -0
  38. package/dist/rules/auth.js +29 -0
  39. package/dist/rules/capabilities.d.ts +21 -0
  40. package/dist/rules/capabilities.js +103 -0
  41. package/dist/rules/card.d.ts +7 -0
  42. package/dist/rules/card.js +65 -0
  43. package/dist/rules/clients.js +1 -0
  44. package/dist/rules/description.js +3 -0
  45. package/dist/rules/handles.d.ts +13 -0
  46. package/dist/rules/handles.js +78 -0
  47. package/dist/rules/ids.js +35 -1
  48. package/dist/rules/index.js +20 -2
  49. package/dist/rules/naming.js +3 -0
  50. package/dist/rules/network.d.ts +21 -0
  51. package/dist/rules/network.js +63 -0
  52. package/dist/rules/rule.d.ts +20 -0
  53. package/dist/rules/search.js +1 -0
  54. package/dist/rules/spec.d.ts +9 -1
  55. package/dist/rules/spec.js +117 -3
  56. package/dist/rules/write.d.ts +0 -6
  57. package/dist/rules/write.js +11 -5
  58. package/dist/scan.d.ts +47 -0
  59. package/dist/scan.js +334 -0
  60. package/dist/session.d.ts +2 -0
  61. package/dist/session.js +149 -9
  62. package/dist/snapshot.d.ts +15 -0
  63. package/dist/snapshot.js +130 -5
  64. package/dist/types.d.ts +5 -0
  65. package/dist/words.d.ts +10 -0
  66. package/dist/words.js +44 -2
  67. package/package.json +2 -2
  68. package/schemas/server-card.json +260 -0
package/README.md CHANGED
@@ -3,46 +3,69 @@
3
3
  [![npm](https://img.shields.io/npm/v/toolmenu)](https://www.npmjs.com/package/toolmenu)
4
4
  [![ci](https://github.com/niksa90/toolmenu/actions/workflows/ci.yml/badge.svg)](https://github.com/niksa90/toolmenu/actions/workflows/ci.yml)
5
5
  [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/niksa90/toolmenu/blob/main/LICENSE)
6
+ [![MCP: 2026-07-28 and 2025](https://img.shields.io/badge/MCP-2026--07--28%20%C2%B7%202025-6E56CF)](https://modelcontextprotocol.io)
6
7
 
7
- **Lint your MCP server's tool menu for changes that confuse agents or break caches.**
8
-
9
- The MCP linters I found grade one snapshot of the menu an agent reads: tool names,
10
- descriptions, schemas. toolmenu observes how the menu behaves across calls,
11
- connections and releases, and checks **when** it changes:
12
-
13
- - **Mid-session.** A menu that changes after the conversation has started can
14
- invalidate the cached conversation: most clients put the tool list at the start of
15
- the prompt, so any change to it, even a tool added at the end, means everything
16
- after it is processed again. In my logs, one mid-conversation unlock rewrote
17
- 40–57K tokens of cached prefix (from my own logs; more on this, with a benchmark
18
- of the setups, in [this write-up](https://niksa.me/agent-tools-design-lessons)). `session` catches it, pins it to the step that
19
- caused it, and says where in the list it happened.
20
- - **Ready for 2026-07-28.** That protocol version says the tool set **must not** vary
21
- per connection or as a side effect of other requests (the 2025 versions allow it).
22
- Per-session "unlock" designs, like the one I built, are ruled out. `session` tells you whether yours is one of them.
23
- It also checks the menu clients will actually show: a broken `x-mcp-header` or a
24
- `$ref` they can't resolve hides a tool or fails every call to it. And when a tool
25
- stops to ask the user something, `session` answers "no" and says whether the tool
26
- can take it. Handles a server mints (`session_id`) should say how long they last and
27
- fail readably when unknown; menus that differ by who asks (`--as`) shouldn't be
28
- cached as public; prompts and resources (`--lists`) are checked like tools. Run
29
- against the reference server, `@modelcontextprotocol/server-everything` 2.1.0, with
30
- no false findings ([bench/](bench/README.md)).
31
- - **For your client.** `--client claude-code | claude-api-search | openai` checks the
32
- menu the way that client loads it, from its own docs: what it costs up front and per
33
- tool a search loads, where it cuts descriptions, what its search can find, and names
34
- its API refuses.
35
- - **Between releases.** `diff` finds breaking changes and token growth, and checks
36
- the version bump.
8
+ **Checks for MCP servers' tool lists: changes that confuse agents, break prompt caches or break clients, caught before your users hit them.**
37
9
 
38
- ![toolmenu session output: tools inserted mid-list, a description edited, each pinned to the step that caused it](https://raw.githubusercontent.com/niksa90/toolmenu/main/docs/demo.svg)
10
+ Your MCP server's tool list is the menu every agent reads before it does anything.
11
+ toolmenu checks that menu the way clients and agents will meet it: across calls,
12
+ connections, clients and releases. No LLM is involved, so the same inputs always give
13
+ the same answer and it fits in CI.
39
14
 
40
- No LLM anywhere: the same inputs give the same answer, so it can sit in CI.
41
- (`history` installs old versions with today's dependencies, so it records what they
42
- serve now, which can differ from what they shipped with: FINDINGS F4.)
15
+ ```sh
16
+ npx toolmenu snapshot -- node dist/server.js # or: npx toolmenu snapshot https://example.com/mcp
17
+ npx toolmenu init -- node dist/server.js # CI: a baseline, a workflow, a comment on every PR
18
+ ```
19
+
20
+ ![toolmenu session output: tools inserted mid-list, a description edited, each pinned to the step that caused it](https://raw.githubusercontent.com/niksa90/toolmenu/main/docs/demo.svg)
43
21
 
44
- > **Status: 0.16, early.** Spec in [docs/SPEC.md](https://github.com/niksa90/toolmenu/blob/main/docs/SPEC.md). What it has found on
45
- > real servers: [docs/FINDINGS.md](https://github.com/niksa90/toolmenu/blob/main/docs/FINDINGS.md).
22
+ ## What it catches
23
+
24
+ | | |
25
+ |---|---|
26
+ | **A menu that changes mid-session** | `session` calls your tools and watches the list. A tool added mid-conversation can rewrite the whole cached prompt: one unlock cost 40–57K tokens of cache in my logs. |
27
+ | **Breaking releases** | `diff` compares two menus: removed tools, new required parameters, narrowed types, token growth. It also says whether your version bump is big enough. |
28
+ | **The 2026-07-28 protocol** | The tool set must not vary per connection, and results need `resultType`. Elicitation, multi round-trip input and `server/discover` are checked too, as are the 2025 handshakes. |
29
+ | **MCP Apps, Tasks, Server Cards** | It reads `ui://` resources as a host does and checks who may see each tool. It catches tasks sent to clients that can't poll them, and Server Cards that contradict the live server. |
30
+ | **Your client's view** | `--client claude-code \| claude-api-search \| openai` shows what each client loads, cuts, can find and refuses. |
31
+ | **What agents misread** | It flags vague `id`s, IDs no tool returns, instructions buried late in descriptions, and writes without annotations or marked read-only. |
32
+ | **Menus that drift** | It catches defaults built from the clock or a hash order, menus that differ per process, per connection or offline, and listings that depend on who asks. |
33
+
34
+ Every finding says what's wrong, where it is and what toolmenu saw, and ends with a `→ Next:` step.
35
+ It runs on the 22-server [bench](bench/README.md) and on hosted servers (GitHub, Atlassian, Sentry,
36
+ Notion, Supabase, Vercel…). What it has found on real servers is in
37
+ [docs/FINDINGS.md](https://github.com/niksa90/toolmenu/blob/main/docs/FINDINGS.md).
38
+
39
+ > **Status: 0.23.** Spec in [docs/SPEC.md](https://github.com/niksa90/toolmenu/blob/main/docs/SPEC.md),
40
+ > every rule in [docs/RULES.md](docs/RULES.md), changes in [CHANGELOG.md](CHANGELOG.md).
41
+
42
+ <details>
43
+ <summary><b>Why "when it changes" matters</b></summary>
44
+
45
+ The MCP linters I found grade one snapshot of the menu: tool names, descriptions,
46
+ schemas. toolmenu also checks **when** the menu changes:
47
+
48
+ - **Mid-session.** Most clients put the tool list at the start of the prompt, so any
49
+ change to it, even a tool added at the end, means everything after it is processed
50
+ again. More on this, with a benchmark of the setups, in
51
+ [this write-up](https://niksa.me/agent-tools-design-lessons). `session` pins each
52
+ change to the step that caused it, and says where in the list it happened.
53
+ - **Per connection.** 2026-07-28 says the tool set **must not** vary per connection or
54
+ as a side effect of other requests (the 2025 versions allow it). Per-session
55
+ "unlock" designs, like the one I built, are ruled out. `session` tells you whether
56
+ yours is one of them. It also checks the menu clients will actually show: a broken
57
+ `x-mcp-header` or a `$ref` they can't resolve hides a tool or fails every call to
58
+ it. When a tool stops to ask the user something, `session` answers "no" and says
59
+ whether the tool can take it.
60
+ - **Between releases.** `diff` finds breaking changes and token growth, and checks the
61
+ version bump. `history` does it across a package's published releases. It installs
62
+ old versions with today's dependencies, so it records what they serve now
63
+ (FINDINGS F4).
64
+
65
+ Run against the reference server, `@modelcontextprotocol/server-everything`, it
66
+ reports no false findings ([bench/](bench/README.md)).
67
+
68
+ </details>
46
69
 
47
70
  ## Start here
48
71
 
@@ -91,14 +114,51 @@ npx toolmenu snapshot https://mcp.example.com/mcp
91
114
  Logins are stored per server in `~/.config/toolmenu/auth` (readable only by you);
92
115
  `auth list` and `auth logout <url>` manage them. A server that doesn't allow
93
116
  dynamic registration needs a pre-registered app: `--client-id` (and
94
- `--client-secret`). In CI, where no browser can open, pass a token as a header.
117
+ `--client-secret`). Over SSH or in a container, `auth login --no-browser` prints the
118
+ login URL instead of opening it: open it on any device, sign in, and paste back the
119
+ address the browser ends on (a `localhost` page that doesn't load is expected). In
120
+ CI, where nobody can sign in, pass a token as a header.
95
121
  Both protocol generations are supported: 2026-07-28 (`server/discover`, stateless)
96
122
  and the 2025 `initialize` handshake, through the official TypeScript SDK.
97
123
 
98
124
  Every finding and error says what's wrong, where, what toolmenu saw, and ends in a
99
125
  `→ Next:` step. Findings marked `· unsure` are heuristics (names and words): they say
100
- what was seen, not what it means. Every command has its own help:
101
- `toolmenu history --help`.
126
+ what was seen, not what it means. `toolmenu explain <rule>` says what a rule checks,
127
+ its default level and how to change it (every rule is in [docs/RULES.md](docs/RULES.md)).
128
+ Every command has its own help: `toolmenu history --help`.
129
+
130
+ Behind a proxy (`HTTPS_PROXY`), stdio servers get the proxy and CA settings
131
+ (`HTTPS_PROXY`, `NO_PROXY`, `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`…)
132
+ along with the minimal environment, and `NODE_USE_ENV_PROXY=1` so a Node server's
133
+ `fetch` uses the proxy. Without them a server that calls an API can't reach it, and
134
+ fails as if it were broken.
135
+
136
+ ### Every server you use: `scan`
137
+
138
+ ```sh
139
+ npx toolmenu scan ~/Library/Application\ Support/Claude/claude_desktop_config.json
140
+ npx toolmenu scan .mcp.json --format markdown
141
+ ```
142
+
143
+ `scan` runs `snapshot` on every server in an MCP client config (Claude Desktop, Claude
144
+ Code's `.mcp.json`, Cursor, VS Code: the `mcpServers` or `servers` object) or in a
145
+ text file with one server per line (a URL or a command, optionally `name<TAB>` first),
146
+ four at a time (`--concurrency`), and prints them side by side, then each server's
147
+ findings, like this:
148
+
149
+ ```
150
+ server tools tokens findings
151
+ github 42 ~18K 1 error · 2 warn
152
+ filesystem 11 ~2.1K no findings
153
+ linear – – not checked: LINEAR_API_KEY is not set (the config refers to it)
154
+ ```
155
+
156
+ `${VAR}`, `${VAR:-default}` and `${env:VAR}` in the config are filled from the
157
+ environment. A server whose variable isn't set isn't started with an empty
158
+ credential: it's a row that says so. A server that couldn't be started or read
159
+ makes the exit code 2, because it wasn't checked; one marked `disabled` is listed and
160
+ left alone. URLs are printed without their query, which can hold a key. Nothing is
161
+ written unless `--out-dir` names a folder for each server's menu file.
102
162
 
103
163
  ## In CI: one PR comment
104
164
 
@@ -198,6 +258,9 @@ serves, and 23 issue and pull-request tools that only the dynamic mode has.
198
258
  | `session/nothing-called` | warn | `--auto` called no tools (all open-world, missing values, or not read-only): the run only listed the menu |
199
259
  | `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; 2025-era servers only). The run stops there; rerun with `--processes 1` |
200
260
  | `session/handle-error` | warn | 2026-07-28: `--auto` called a read-only tool with a handle that can't exist (`toolmenu-unknown-session`), and it answered with a protocol error instead of a tool error the model can read |
261
+ | `session/error-not-flagged` | warn | A tool answered with an HTTP error from the API behind it (`{"status":401,"object":"error",…}`) as a plain result, not marked `isError`, so a client that reads `isError` takes the call for a success (Notion's server). An auth one also counts toward `session/untested`. Tools that take a URL are left out: their answer is the page's (heuristic) |
262
+ | `session/server-unresponsive` | error | The server stopped answering after a step: even `tools/list` timed out. The run stops there with this one finding, instead of every later step waiting out its timeout (a server that polls a device-code sign-in inside a tool call) |
263
+ | `session/handle-roundtrip` | warn | With `--create-handles`: the tool that creates a session, basket or cart was called, and the tools that take it back refused the handle it had just returned (info when its result had no handle to find) |
201
264
  | `session/rate-limited` | error | The server kept refusing requests for being too many (a 429) after toolmenu waited about a minute, or a tool not marked `readOnlyHint` said it was rate-limited (it isn't called again). The run stops there, with the steps it didn't check; give the run its own server instance or raise the limit for it |
202
265
  | `session/scope-unchecked` | info | A second server process or connection couldn't start mid-session (a server that holds a file or a port), so whether a change was global wasn't checked. Said once for the run |
203
266
 
@@ -214,6 +277,10 @@ of either. Servers that don't mark their tools `readOnlyHint` (DeepWiki, every
214
277
  `--assume-read-only read_wiki_structure,ask_wiki_question`. Only exact names are
215
278
  accepted: a pattern would also cover tools a later release adds. A tool marked or
216
279
  named as a write is never called, and the report says which tools ran on your word.
280
+ With `--create-handles` on 2026-07-28, `--auto` also calls the tool that creates a
281
+ session, basket or cart (`start_session`; a write, so only with the flag, and never
282
+ one marked `destructiveHint`; not locks, leases or checkouts) and gives the tools that
283
+ take it back the handle it returned, beside the made-up one.
217
284
  `--save-scenario auto.yml` writes the steps, with the skipped tools commented out, for
218
285
  you to fill in. Tools marked `openWorldHint: true` (web
219
286
  search, fetch, scraping, which can cost API credits) are called only with
@@ -408,6 +475,11 @@ server, or from the spec itself. If a rule can't point to one, it doesn't ship.
408
475
  | `naming/client-name` | warn | With `--client`: tool names the client's API refuses: `^[a-zA-Z0-9_-]{1,128}$` for the Claude API, `^[a-zA-Z0-9_-]+$` up to 128 for OpenAI's functions. MCP allows names such as `files.read` that neither takes as they are |
409
476
  | `menu/auth-variance` | info | With `--as` (or `identities` in the config): the tool set differs by identity, what each adds, lacks or defines differently against the first, and its tokens. Allowed by the spec; a baseline of one identity's menu doesn't cover the others. An identity that can't be listed is said here too |
410
477
  | `spec/cache-scope-public` | warn | 2026-07-28, with `--as`: the tool set differs by identity, and `tools/list` says `cacheScope: "public"`, which lets shared caches serve one caller's list to another |
478
+ | `menu/capability-dependent` | info | Tools a server lists only to a client that supports elicitation, or only to one that doesn't. `snapshot` lists as a client with elicitation, so the menu file holds those tools (github-mcp-server 1.14 lists `delete_repository` only to a client that can ask the user to confirm; before 0.22 a baseline missed it), and once more without |
479
+ | `menu/network-dependent` | warn | With `--offline-check` (stdio): the menu listed once more with the network cut off (the proxy variables pointed at a closed port, loopback left alone) differs: inite-visibility serves 3 tools offline and 10 online, so a baseline made with the network doesn't match a machine without it. A server that doesn't start offline is info. A server that ignores the proxy variables still reaches the network where the machine has it directly; then nothing is reported, which isn't a pass |
480
+ | `auth/invalid-accepted` | warn | HTTP with credentials: the menu listed once more with an invalid credential in the same scheme. A server that serves a menu to it, not 401, gives a client whose token expired no reason to log in again; the agent just has fewer tools (Atlassian Rovo served 4 tools to any `Authorization` header). `--processes 1` turns it off |
481
+
482
+ The full list, `diff` and `session` rules included, is [docs/RULES.md](docs/RULES.md).
411
483
 
412
484
  The naming and ID rules are heuristics, tuned on real servers (FINDINGS F7 and
413
485
  F10) and a private 115-tool one. They're the extras; the change checks are the point.
@@ -438,10 +510,13 @@ meant to steer away from, and toolmenu says so.
438
510
  "routes": "routes.yml",
439
511
  "tokenBudget": 4000,
440
512
  "descriptionLimit": "claude-code",
441
- "fullDescriptions": ["search_capabilities", "lookup_*"]
513
+ "fullDescriptions": ["search_capabilities", "lookup_*"],
514
+ "offlineCheck": true
442
515
  }
443
516
  ```
444
517
 
518
+ `offlineCheck` turns on `--offline-check` for every `snapshot` of a stdio server.
519
+
445
520
  `descriptionLimit` is where your client cuts tool descriptions: a number, or a client
446
521
  whose cut has been reported: `"claude-code"` (the default: Claude Code's own docs,
447
522
  [code.claude.com/docs/en/mcp](https://code.claude.com/docs/en/mcp), read 2026-11-02:
@@ -511,10 +586,13 @@ toolmenu sees what the server sends. Plenty of agent failures happen elsewhere:
511
586
  --as <name>:<cred> snapshot: list the menu as this identity too, repeatable:
512
587
  "reader:Authorization: Bearer …" (HTTP) or "admin:ROLE=admin"
513
588
  (stdio). The first is the menu saved; the others are compared
589
+ --offline-check snapshot (stdio): also list the menu with the network cut off
590
+ --concurrency <n> scan: servers checked at a time (default: 4)
591
+ --out-dir <dir> scan: write each server's menu file there, as <name>.json
514
592
  ```
515
593
 
516
594
  Exit codes: `0` clean · `1` findings at or above `--fail-on` · `2` couldn't connect
517
- or bad usage. `toolmenu <command> --help` lists that command's own options.
595
+ (for `scan`: a server wasn't checked) or bad usage. `toolmenu <command> --help` lists that command's own options.
518
596
 
519
597
  ## Limitations
520
598
 
package/dist/apps.d.ts ADDED
@@ -0,0 +1,56 @@
1
+ import type { Connection } from './connect.js';
2
+ import type { Menu, MenuTool } from './types.js';
3
+ /** The deprecated flat key, before `_meta.ui` ("will be removed before GA"). */
4
+ export declare const LEGACY_URI_KEY = "ui/resourceUri";
5
+ export interface UiMeta {
6
+ /** `_meta.ui.resourceUri`. */
7
+ resourceUri?: unknown;
8
+ /** `_meta["ui/resourceUri"]`, the deprecated spelling. */
9
+ legacyUri?: unknown;
10
+ /** `_meta.ui.visibility`, as sent. */
11
+ visibility?: unknown;
12
+ }
13
+ /** The tool's MCP Apps metadata, or undefined when it has none. */
14
+ export declare function uiMeta(tool: object): UiMeta | undefined;
15
+ /** The UI resource the host renders for this tool: `_meta.ui.resourceUri`, else the deprecated key. */
16
+ export declare function resourceUriOf(tool: object): string | undefined;
17
+ /**
18
+ * Listed for the app only: `visibility` is a list without "model". An Apps host MUST
19
+ * NOT put such a tool in the agent's tool list, so the agent never reads its name,
20
+ * description or schema. Absent, visibility is ["model", "app"].
21
+ */
22
+ export declare function isAppOnly(tool: object): boolean;
23
+ /** The tools the agent is shown: all of them but the app-only ones. */
24
+ export declare function agentTools<T extends object>(tools: T[]): T[];
25
+ /**
26
+ * The menu the agent is shown, its token total recomputed, and what was left out: one
27
+ * view for the report, the agent-scope rules and the --client cost.
28
+ */
29
+ export declare function agentMenu(menu: Menu): {
30
+ shown: Menu;
31
+ appOnly?: {
32
+ tools: number;
33
+ tokens: number;
34
+ };
35
+ };
36
+ /** What resources/read gave for one UI resource. */
37
+ export interface AppResource {
38
+ uri: string;
39
+ /** The tools that name it. */
40
+ tools: string[];
41
+ /** resources/read failed: the error's first line. */
42
+ error?: string;
43
+ /** Each content item's mimeType, in order ("" when absent). */
44
+ mimeTypes?: string[];
45
+ /** Some content item for this URI carries text or a blob. */
46
+ hasContent?: boolean;
47
+ /** The content items' URIs that differ from the one asked for. */
48
+ otherUris?: string[];
49
+ }
50
+ /**
51
+ * Read each `ui://` resource the menu's tools name (resources/read: a read, not a tool
52
+ * call), at most `limit` of them. Each is read once, however many tools name it.
53
+ */
54
+ export declare function readAppResources(connection: Connection, tools: MenuTool[], timeoutMs?: number, limit?: number): Promise<AppResource[]>;
55
+ /** Whether a content type is the one MCP Apps allow, compared without case or spaces around `;`. */
56
+ export declare function isAppsMimeType(mime: string): boolean;
package/dist/apps.js ADDED
@@ -0,0 +1,99 @@
1
+ import { APPS_MIME_TYPE } from './connect.js';
2
+ /** The deprecated flat key, before `_meta.ui` ("will be removed before GA"). */
3
+ export const LEGACY_URI_KEY = 'ui/resourceUri';
4
+ const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
5
+ /** The tool's MCP Apps metadata, or undefined when it has none. */
6
+ export function uiMeta(tool) {
7
+ const raw = tool._meta;
8
+ const meta = isObject(raw) ? raw : undefined;
9
+ if (!meta)
10
+ return undefined;
11
+ const ui = isObject(meta.ui) ? meta.ui : undefined;
12
+ const out = {
13
+ ...(ui && 'resourceUri' in ui ? { resourceUri: ui.resourceUri } : {}),
14
+ ...(LEGACY_URI_KEY in meta ? { legacyUri: meta[LEGACY_URI_KEY] } : {}),
15
+ ...(ui && 'visibility' in ui ? { visibility: ui.visibility } : {}),
16
+ };
17
+ return Object.keys(out).length ? out : undefined;
18
+ }
19
+ /** The UI resource the host renders for this tool: `_meta.ui.resourceUri`, else the deprecated key. */
20
+ export function resourceUriOf(tool) {
21
+ const ui = uiMeta(tool);
22
+ // An empty _meta.ui.resourceUri names nothing: the deprecated key, when it has one, is what's left.
23
+ const uri = typeof ui?.resourceUri === 'string' && ui.resourceUri ? ui.resourceUri : typeof ui?.legacyUri === 'string' ? ui.legacyUri : undefined;
24
+ return uri || undefined;
25
+ }
26
+ /**
27
+ * Listed for the app only: `visibility` is a list without "model". An Apps host MUST
28
+ * NOT put such a tool in the agent's tool list, so the agent never reads its name,
29
+ * description or schema. Absent, visibility is ["model", "app"].
30
+ */
31
+ export function isAppOnly(tool) {
32
+ const v = uiMeta(tool)?.visibility;
33
+ return Array.isArray(v) && !v.includes('model');
34
+ }
35
+ /** The tools the agent is shown: all of them but the app-only ones. */
36
+ export function agentTools(tools) {
37
+ return tools.some(isAppOnly) ? tools.filter((t) => !isAppOnly(t)) : tools;
38
+ }
39
+ /**
40
+ * The menu the agent is shown, its token total recomputed, and what was left out: one
41
+ * view for the report, the agent-scope rules and the --client cost.
42
+ */
43
+ export function agentMenu(menu) {
44
+ const tools = agentTools(menu.tools);
45
+ if (tools === menu.tools)
46
+ return { shown: menu };
47
+ const tokens = tools.reduce((n, t) => n + t.tokens, 0);
48
+ return { shown: { ...menu, tools, totalTokens: tokens }, appOnly: { tools: menu.tools.length - tools.length, tokens: menu.totalTokens - tokens } };
49
+ }
50
+ /**
51
+ * Read each `ui://` resource the menu's tools name (resources/read: a read, not a tool
52
+ * call), at most `limit` of them. Each is read once, however many tools name it.
53
+ */
54
+ export async function readAppResources(connection, tools, timeoutMs = 30_000, limit = 50) {
55
+ const byUri = new Map();
56
+ for (const t of tools) {
57
+ const uri = resourceUriOf(t);
58
+ if (uri && uri.startsWith('ui://'))
59
+ byUri.set(uri, [...(byUri.get(uri) ?? []), t.name]);
60
+ }
61
+ const queue = [...byUri].slice(0, limit);
62
+ const out = new Array(queue.length);
63
+ // All of them within 2 × the request timeout, 4 at a time: a server whose reads hang
64
+ // costs one bounded wait, not one timeout per resource.
65
+ const deadline = Date.now() + 2 * timeoutMs;
66
+ const readOne = async (i) => {
67
+ const [uri, names] = queue[i];
68
+ const left = deadline - Date.now();
69
+ if (left <= 0) {
70
+ out[i] = { uri, tools: names, error: `not read: the reads took longer than ${Math.round((2 * timeoutMs) / 1000)} s in all` };
71
+ return;
72
+ }
73
+ try {
74
+ const result = await connection.client.readResource({ uri }, { timeout: Math.min(timeoutMs, left) });
75
+ const contents = Array.isArray(result?.contents) ? result.contents : [];
76
+ out[i] = {
77
+ uri,
78
+ tools: names,
79
+ mimeTypes: contents.map((c) => (typeof c.mimeType === 'string' ? c.mimeType : '')),
80
+ hasContent: contents.some((c) => (typeof c.text === 'string' && c.text.length > 0) || (typeof c.blob === 'string' && c.blob.length > 0)),
81
+ otherUris: contents.flatMap((c) => (typeof c.uri === 'string' && c.uri !== uri ? [c.uri] : [])),
82
+ };
83
+ }
84
+ catch (error) {
85
+ out[i] = { uri, tools: names, error: (error instanceof Error ? error.message : String(error)).split('\n')[0].trim() };
86
+ }
87
+ };
88
+ let next = 0;
89
+ const worker = async () => {
90
+ while (next < queue.length)
91
+ await readOne(next++);
92
+ };
93
+ await Promise.all(Array.from({ length: Math.min(4, queue.length) }, worker));
94
+ return out.filter((r) => r !== undefined);
95
+ }
96
+ /** Whether a content type is the one MCP Apps allow, compared without case or spaces around `;`. */
97
+ export function isAppsMimeType(mime) {
98
+ return mime.toLowerCase().replace(/\s*;\s*/g, ';') === APPS_MIME_TYPE;
99
+ }
package/dist/auth.d.ts CHANGED
@@ -59,7 +59,21 @@ export interface LoginOptions extends Omit<ProviderOptions, 'interactive' | 'onR
59
59
  open?: (url: URL) => void | Promise<void>;
60
60
  /** How long to wait for the browser to come back (default 5 min). */
61
61
  timeoutMs?: number;
62
+ /**
63
+ * --no-browser: don't open a browser; print the URL, and also take the address the
64
+ * browser ends on, pasted back (a machine whose browser can't reach this one's
65
+ * 127.0.0.1: SSH, a container, a remote dev box). `paste` reads that text (default:
66
+ * one line from stdin).
67
+ */
68
+ noBrowser?: boolean;
69
+ paste?: () => Promise<string>;
62
70
  }
71
+ /**
72
+ * The redirect's query from what someone pasted: the whole address the browser ended
73
+ * on (http://127.0.0.1:33418/callback?code=…&state=…), or just its query. Undefined when
74
+ * it carries neither a code nor an error.
75
+ */
76
+ export declare function pastedRedirect(text: string): URLSearchParams | undefined;
63
77
  /**
64
78
  * Log in to an OAuth-protected MCP server: register (or reuse a client), open the
65
79
  * authorization URL, receive the code on a loopback redirect, check `state`,
package/dist/auth.js CHANGED
@@ -201,6 +201,50 @@ export class LoginNeededError extends Error {
201
201
  `→ Next: Log in once in a terminal with a browser: toolmenu auth login ${serverUrl}. Or pass a token: --header "Authorization: Bearer <token>".`);
202
202
  }
203
203
  }
204
+ /**
205
+ * The redirect's query from what someone pasted: the whole address the browser ended
206
+ * on (http://127.0.0.1:33418/callback?code=…&state=…), or just its query. Undefined when
207
+ * it carries neither a code nor an error.
208
+ */
209
+ export function pastedRedirect(text) {
210
+ const t = text.trim().replace(/^["'<]|["'>]$/g, '');
211
+ let params;
212
+ try {
213
+ params = /^[a-z][a-z0-9+.-]*:\/\//i.test(t) ? new URL(t).searchParams : new URLSearchParams(t.replace(/^[^?]*\?/, ''));
214
+ }
215
+ catch {
216
+ return undefined;
217
+ }
218
+ return params.get('code') || params.get('error') ? params : undefined;
219
+ }
220
+ /**
221
+ * Lines from stdin, for --no-browser: one reader for the whole login, so a line
222
+ * already buffered after a bad paste isn't lost. Ends (undefined) when stdin does;
223
+ * `signal` closes it when the loopback redirect won, so stdin doesn't keep the
224
+ * process alive.
225
+ */
226
+ async function* stdinLines(signal) {
227
+ const { createInterface } = await import('node:readline');
228
+ const rl = createInterface({ input: process.stdin });
229
+ const stop = () => rl.close();
230
+ signal.addEventListener('abort', stop, { once: true });
231
+ try {
232
+ for await (const line of rl)
233
+ yield line;
234
+ }
235
+ finally {
236
+ signal.removeEventListener('abort', stop);
237
+ rl.close();
238
+ }
239
+ }
240
+ /** Print the authorization URL and say what to paste back. */
241
+ function printForPaste(port) {
242
+ return (url) => {
243
+ process.stderr.write(`Open this address in a browser on any device and approve the login:\n\n ${url.href}\n\n` +
244
+ `The browser then goes to http://127.0.0.1:${port}/callback?code=… . On another device that page won't load: ` +
245
+ `copy its address from the address bar and paste it here, then press Enter.\n> `);
246
+ };
247
+ }
204
248
  /**
205
249
  * Log in to an OAuth-protected MCP server: register (or reuse a client), open the
206
250
  * authorization URL, receive the code on a loopback redirect, check `state`,
@@ -211,7 +255,36 @@ export async function login(serverUrl, options = {}) {
211
255
  const port = options.port ?? DEFAULT_PORT;
212
256
  const callback = await listenForCallback(port, options.timeoutMs ?? 300_000);
213
257
  try {
214
- const provider = new StoredOAuthProvider(serverUrl, { ...options, port, interactive: true, onRedirect: options.open ?? openInBrowser });
258
+ const provider = new StoredOAuthProvider(serverUrl, {
259
+ ...options,
260
+ port,
261
+ interactive: true,
262
+ onRedirect: options.open ?? (options.noBrowser ? printForPaste(port) : openInBrowser),
263
+ });
264
+ // --no-browser: the loopback redirect, or the address pasted back, whichever comes first.
265
+ const reading = new AbortController();
266
+ const retry = () => process.stderr.write(`That has no code= or error= in it: paste the whole address the browser ended on (http://127.0.0.1:${port}/callback?code=…).\n> `);
267
+ const pasted = async () => {
268
+ if (options.paste) {
269
+ for (;;) {
270
+ const params = pastedRedirect(await options.paste());
271
+ if (params)
272
+ return params;
273
+ retry();
274
+ }
275
+ }
276
+ for await (const line of stdinLines(reading.signal)) {
277
+ const params = pastedRedirect(line);
278
+ if (params)
279
+ return params;
280
+ retry();
281
+ }
282
+ // stdin ended (</dev/null, a script): nothing can be pasted, but the browser may
283
+ // still reach the loopback (SSH with the port forwarded). Said, then left to it.
284
+ if (!reading.signal.aborted)
285
+ process.stderr.write(`\nNothing can be pasted here (stdin ended): waiting for the browser to reach http://127.0.0.1:${port}/callback instead.\n`);
286
+ return new Promise(() => { });
287
+ };
215
288
  // Each login discovers the authorization server afresh (a server may have
216
289
  // moved); the state is then kept for the callback leg's check.
217
290
  await provider.invalidateCredentials('discovery');
@@ -225,7 +298,7 @@ export async function login(serverUrl, options = {}) {
225
298
  catch (error) {
226
299
  if (!(error instanceof UnauthorizedError))
227
300
  throw error;
228
- const params = await callback.params;
301
+ const params = options.noBrowser ? await Promise.race([callback.params, pasted()]).finally(() => reading.abort()) : await callback.params;
229
302
  if (params.get('error')) {
230
303
  const described = params.get('error_description');
231
304
  throw new Error(`The authorization server refused the login for ${serverUrl}: ${params.get('error')}${described ? ` (“${described}”)` : ''}.\n` +
package/dist/auto.d.ts CHANGED
@@ -11,6 +11,12 @@ export interface GivenValue {
11
11
  export interface AutoOptions {
12
12
  /** Also call read-only tools marked openWorldHint: true (web search, fetch, scraping). */
13
13
  openWorld?: boolean;
14
+ /**
15
+ * --create-handles: call the tool that creates a session, basket or cart (a write,
16
+ * so only when asked, and never one marked destructiveHint), and give the tools that
17
+ * take it back the handle it returned instead of a made-up one.
18
+ */
19
+ createHandles?: boolean;
14
20
  /** At most this many calls (default 20). */
15
21
  maxCalls?: number;
16
22
  /**
package/dist/auto.js CHANGED
@@ -1,9 +1,9 @@
1
1
  import { readFile } from 'node:fs/promises';
2
2
  import { isMap, isNode, isScalar, parseDocument } from 'yaml';
3
3
  import { synthesizeArgs } from './args.js';
4
- import { createdKinds, handleParams } from './rules/handles.js';
4
+ import { CREATABLE_KINDS, createdKinds, creatorOf, handleParams } from './rules/handles.js';
5
5
  import { MAX_UNLOCKS, unlockers } from './session.js';
6
- import { COLLECTION_VERBS, commonWords, leadingVerb, LOOKUP_VERBS, verbOf, WRITE_VERBS } from './words.js';
6
+ import { COLLECTION_VERBS, prefixWords, leadingVerb, LOOKUP_VERBS, verbOf, WRITE_VERBS } from './words.js';
7
7
  /** Marked or named as a write: never called on the user's word. Says why, or undefined. */
8
8
  export function writeSign(tool) {
9
9
  const a = tool.annotations ?? {};
@@ -44,7 +44,7 @@ export function autoScenario(menu, options = {}) {
44
44
  }
45
45
  // The server's readOnlyHint, but not against a name that says it writes: a hosted
46
46
  // server marked create_my_ideal_account read-only (write/read-only-mismatch).
47
- const common = commonWords(menu.tools.map((t) => t.name));
47
+ const common = prefixWords(menu.tools.map((t) => t.name));
48
48
  const namedWrite = (t) => WRITE_VERBS.has(leadingVerb(t.name, common) ?? '');
49
49
  const readOnly = (t) => (t.annotations?.readOnlyHint === true && !namedWrite(t)) || assumed.has(t.name);
50
50
  const { perTool, ignored: unusedValues } = resolveValues(menu, options.values ?? {});
@@ -104,11 +104,67 @@ export function autoScenario(menu, options = {}) {
104
104
  }
105
105
  candidates.sort((x, y) => x.rank - y.rank);
106
106
  const chosen = candidates.slice(0, maxCalls);
107
+ // A tool also called through its other candidate (a plain call beside an optional-handle probe) isn't skipped.
107
108
  for (const c of candidates.slice(maxCalls))
108
- skipped.push({ tool: c.tool.name, reason: 'over the call budget' });
109
+ if (!chosen.some((x) => x.tool.name === c.tool.name))
110
+ skipped.push({ tool: c.tool.name, reason: 'over the call budget' });
109
111
  const steps = options.callsOnly ? [] : [{ kind: 'list' }];
110
- for (const c of chosen)
112
+ // --create-handles: the creating tool of each kind a probe takes, called first.
113
+ const creators = [];
114
+ // Calls the plan makes, the final repeat aside: each creator is one, and each probe it serves is called twice.
115
+ const cost = () => chosen.length + creators.length + chosen.filter((c) => c.probe?.fromCreated).length;
116
+ if (options.createHandles && modern) {
117
+ for (const kind of [...new Set(chosen.filter((c) => c.probe).map((c) => c.probe.kind))]) {
118
+ if (!CREATABLE_KINDS.has(kind))
119
+ continue;
120
+ const creator = creatorOf(menu.tools, kind);
121
+ if (!creator || creator.annotations?.destructiveHint === true)
122
+ continue;
123
+ const filled = synthesizeArgs(creator.inputSchema, perTool.get(creator.name));
124
+ if (!filled.ok)
125
+ continue;
126
+ creators.push({ tool: creator, kind, args: filled.args });
127
+ for (const c of chosen)
128
+ if (c.probe?.kind === kind)
129
+ c.probe = { ...c.probe, fromCreated: creator.name };
130
+ }
131
+ // Within --max-calls. First the real-handle calls go (last first), each probe keeping
132
+ // its made-up call as without --create-handles, and a creator that serves none goes
133
+ // with them; only then whole calls.
134
+ const unused = () => {
135
+ for (let i = creators.length - 1; i >= 0; i--)
136
+ if (!chosen.some((c) => c.probe?.fromCreated === creators[i].tool.name))
137
+ creators.splice(i, 1);
138
+ };
139
+ for (let i = chosen.length - 1; i >= 0 && cost() > maxCalls; i--) {
140
+ const probe = chosen[i].probe;
141
+ if (!probe?.fromCreated)
142
+ continue;
143
+ chosen[i].probe = { param: probe.param, kind: probe.kind };
144
+ unused();
145
+ }
146
+ while (chosen.length && cost() > maxCalls) {
147
+ const c = chosen.pop();
148
+ // A tool called through its other candidate (its plain call beside an optional-handle probe) isn't skipped.
149
+ if (!chosen.some((x) => x.tool.name === c.tool.name) && !skipped.some((x) => x.tool === c.tool.name))
150
+ skipped.push({ tool: c.tool.name, reason: 'over the call budget' });
151
+ unused();
152
+ }
153
+ // Called on purpose now: not skipped.
154
+ for (const c of creators) {
155
+ const i = skipped.findIndex((x) => x.tool === c.tool.name);
156
+ if (i >= 0)
157
+ skipped.splice(i, 1);
158
+ }
159
+ }
160
+ for (const c of creators)
161
+ steps.push({ kind: 'call', tool: c.tool.name, args: c.args, creates: c.kind });
162
+ for (const c of chosen) {
163
+ // With a created handle, both: the made-up one (session/handle-error) and the real one (session/handle-roundtrip).
164
+ if (c.probe?.fromCreated)
165
+ steps.push({ kind: 'call', tool: c.tool.name, args: c.args, probe: { param: c.probe.param, kind: c.probe.kind } });
111
166
  steps.push({ kind: 'call', tool: c.tool.name, args: c.args, ...(c.probe ? { probe: c.probe } : {}) });
167
+ }
112
168
  for (const u of unlocks) {
113
169
  const array = u.tool.inputSchema?.properties?.[u.param]?.type === 'array';
114
170
  const values = u.values.slice(0, MAX_UNLOCKS);
@@ -122,7 +178,7 @@ export function autoScenario(menu, options = {}) {
122
178
  }
123
179
  if (chosen.length && !options.callsOnly)
124
180
  steps.push({ kind: 'call', tool: chosen[0].tool.name, args: chosen[0].args, ...(chosen[0].probe ? { probe: chosen[0].probe } : {}) });
125
- const called = [...chosen.map((c) => c.tool.name), ...unlocks.map((u) => u.tool.name)];
181
+ const called = [...creators.map((c) => c.tool.name), ...chosen.map((c) => c.tool.name), ...unlocks.map((u) => u.tool.name)];
126
182
  return {
127
183
  scenario: { allowWrites: false, steps, ...(assumed.size ? { assumeReadOnly: [...assumed] } : {}) },
128
184
  called,
@@ -130,7 +186,7 @@ export function autoScenario(menu, options = {}) {
130
186
  withValues: chosen.filter((c) => c.valued).map((c) => c.tool.name),
131
187
  skipped,
132
188
  ignored,
133
- spent: chosen.length,
189
+ spent: cost(),
134
190
  unlockValues: unlocks.reduce((n, u) => n + Math.min(u.values.length, MAX_UNLOCKS), 0),
135
191
  };
136
192
  }
@@ -396,6 +452,13 @@ export function scenarioYaml(plan, serverName) {
396
452
  for (const step of plan.scenario.steps) {
397
453
  if (step.kind === 'list')
398
454
  lines.push(' - list');
455
+ else if (step.kind === 'call' && step.creates) {
456
+ // A write, called only with --create-handles: as written it would be refused under allow_writes: false.
457
+ lines.push(` # --create-handles called ${step.tool} to create a ${step.creates} (a write); to replay it, set allow_writes: true and uncomment:`, ` # - call: ${step.tool}`, ...(Object.keys(step.args).length ? [` # args: ${JSON.stringify(step.args)}`] : []));
458
+ }
459
+ else if (step.kind === 'call' && step.probe?.fromCreated) {
460
+ lines.push(` # --create-handles called ${step.tool} with the ${step.probe.kind} ${step.probe.fromCreated} returned (session/handle-roundtrip); to replay it, put one in:`, ` # - call: ${step.tool}`, ` # args: ${JSON.stringify({ ...step.args, [step.probe.param]: 'TODO' })}`);
461
+ }
399
462
  else if (step.kind === 'call' && step.probe) {
400
463
  // A made-up handle is --auto's check, not a step to replay: as written it would fail as a step.
401
464
  lines.push(` # --auto called ${step.tool} with a made-up ${step.probe.kind} (session/handle-error); to replay it, put a real one in:`, ` # - call: ${step.tool}`, ` # args: ${JSON.stringify(step.args)}`);