toolmenu 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -29,7 +29,7 @@ No LLM anywhere: the same inputs give the same answer, so it can sit in CI.
29
29
  (`history` installs old versions with today's dependencies, so it records what they
30
30
  serve now, which can differ from what they shipped with: FINDINGS F4.)
31
31
 
32
- > **Status: 0.10, early.** Spec in [docs/SPEC.md](https://github.com/niksa90/toolmenu/blob/main/docs/SPEC.md). What it has found on
32
+ > **Status: 0.11, 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
@@ -90,7 +90,7 @@ jobs:
90
90
  - uses: actions/setup-node@v7
91
91
  with: { node-version: 22 }
92
92
  - run: npm ci && npm run build
93
- - uses: niksa90/toolmenu@v0.10.0
93
+ - uses: niksa90/toolmenu@v0.11.0
94
94
  with:
95
95
  command: node dist/server.js
96
96
  baseline: menu.json # your committed snapshot
@@ -222,13 +222,15 @@ operations found in both snapshots with the same rules as tools.
222
222
  npx toolmenu snapshot --catalog -- node dist/server.js
223
223
  ```
224
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).
225
+ A search returns only its top matches, so toolmenu crawls the catalog by its own
226
+ words: it starts from the search tool's own example phrases and the nouns in your tool
227
+ names, then searches for every operation it finds or sees mentioned, until 20 queries
228
+ in a row turn up nothing new (at most 200). On Atlassian's hosted server that finds all
229
+ 154 operations behind its 21 tools; on Sentry's, 65 behind 9, the same on every run.
230
+ Queries are paced and a rate limit is waited out. An operation not found this time is a
231
+ notice ("not returned by the same queries"), never "removed". To steer it, set
232
+ `"catalog": { "queries": [...], "maxQueries": 200, "crawl": true }` in
233
+ `toolmenu.config.json` (FINDINGS F15).
232
234
 
233
235
  ## `history`: a package's releases, researched
234
236
 
package/dist/catalog.d.ts CHANGED
@@ -27,6 +27,12 @@ export interface CatalogOptions {
27
27
  timeoutMs?: number;
28
28
  /** Pause between queries, ms (default 300): hosted servers rate-limit searches (Sentry did). */
29
29
  pauseMs?: number;
30
+ /** Follow the catalog's own words: search for each operation found or mentioned (default true). */
31
+ crawl?: boolean;
32
+ /** At most this many queries (default 200). */
33
+ maxQueries?: number;
34
+ /** Stop after this many queries in a row find nothing new (default 20): the catalog is exhausted. */
35
+ stopAfter?: number;
30
36
  }
31
37
  /** The menu's catalog search tool: read-only, one required query, named like one. */
32
38
  export declare function findCatalogTool(tools: MenuTool[]): MenuTool | undefined;
@@ -48,3 +54,17 @@ export declare function operationsIn(result: {
48
54
  structuredContent?: unknown;
49
55
  content?: unknown;
50
56
  }): MenuTool[];
57
+ /**
58
+ * The JSON value a text starts with, ignoring what follows: Atlassian's discover
59
+ * returns its results as JSON and then a prose list of related operations, which
60
+ * makes the whole text invalid JSON.
61
+ */
62
+ export declare function leadingJson(text: string): unknown;
63
+ /**
64
+ * Operation names a result mentions without defining them: lines like
65
+ * "createJiraBoard — Create a new company-managed…" after Atlassian's JSON. Each
66
+ * is worth a search of its own.
67
+ */
68
+ export declare function mentionedNames(result: {
69
+ content?: unknown;
70
+ }): string[];
package/dist/catalog.js CHANGED
@@ -35,13 +35,33 @@ export async function readCatalog(conn, tools, options = {}) {
35
35
  throw new Error(options.tool ? `--catalog: no tool named ${options.tool} in the menu.` : '--catalog: no catalog search tool in the menu (read-only, one required query, named like search_*_tools or discover). Name it with catalog.tool in the config.');
36
36
  const queryParam = tool.inputSchema.required[0];
37
37
  const limit = limitArg(tool.inputSchema);
38
- const queries = options.queries ?? defaultQueries(tools);
38
+ // Seeds, then the catalog's own words: every operation found or mentioned is
39
+ // searched for by name, which finds it and its neighbours. Breadth first, in the
40
+ // order found, so the same catalog gives the same queries.
41
+ const queue = [...new Set(options.queries ?? [...describedExamples(tool), ...defaultQueries(tools)])];
42
+ const crawl = options.crawl ?? true;
43
+ // Crawl until the catalog stops yielding: a small one ends early, a big one
44
+ // (Atlassian's ~300 operations) goes on, up to the cap.
45
+ const maxQueries = options.maxQueries ?? 200;
46
+ const stopAfter = options.stopAfter ?? 20;
47
+ let dry = 0;
48
+ const asked = [];
49
+ const queued = new Set(queue);
50
+ const enqueue = (name) => {
51
+ const q = phrase(name);
52
+ if (crawl && q && !queued.has(q)) {
53
+ queued.add(q);
54
+ queue.push(q);
55
+ }
56
+ };
39
57
  const found = new Map();
40
58
  const failed = [];
41
59
  const pause = options.pauseMs ?? 300;
42
- for (const [i, query] of queries.entries()) {
43
- if (i > 0)
60
+ while (queue.length && asked.length < maxQueries && dry < stopAfter) {
61
+ const query = queue.shift();
62
+ if (asked.length > 0)
44
63
  await sleep(pause);
64
+ asked.push(query);
45
65
  // A rate limit is waited out (2 s, 4 s, 8 s); anything else, or a limit that
46
66
  // persists, leaves this query out and the catalog partial, never the snapshot
47
67
  // failed: diff treats operations not found as notices.
@@ -55,10 +75,19 @@ export async function readCatalog(conn, tools, options = {}) {
55
75
  }
56
76
  if (result.isError)
57
77
  failed.push({ query, error: text.slice(0, 200) || 'the tool returned an error' });
58
- else
59
- for (const op of operationsIn(result))
60
- if (!found.has(op.name))
61
- found.set(op.name, op);
78
+ else {
79
+ const before = found.size;
80
+ for (const op of operationsIn(result)) {
81
+ if (found.has(op.name))
82
+ continue;
83
+ found.set(op.name, op);
84
+ enqueue(op.name);
85
+ }
86
+ for (const name of mentionedNames(result))
87
+ if (!found.has(name))
88
+ enqueue(name);
89
+ dry = found.size > before ? 0 : dry + 1;
90
+ }
62
91
  break;
63
92
  }
64
93
  catch (error) {
@@ -73,7 +102,24 @@ export async function readCatalog(conn, tools, options = {}) {
73
102
  }
74
103
  }
75
104
  const operations = [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
76
- return { tool: tool.name, queries, operations, ...(failed.length ? { failed } : {}) };
105
+ return { tool: tool.name, queries: asked, operations, ...(failed.length ? { failed } : {}) };
106
+ }
107
+ /** An operation name as a search phrase: listJiraIssueWorklogs → "list jira issue worklogs". */
108
+ function phrase(name) {
109
+ return name
110
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
111
+ .split(/[^A-Za-z0-9]+/)
112
+ .filter(Boolean)
113
+ .map((w) => w.toLowerCase())
114
+ .join(' ');
115
+ }
116
+ /**
117
+ * Example queries the search tool's own schema suggests: Atlassian's discover
118
+ * documents its query with "transition a jira issue", "list confluence spaces"…
119
+ */
120
+ function describedExamples(tool) {
121
+ const text = [tool.description ?? '', ...Object.values(tool.inputSchema?.properties ?? {}).map((p) => String(p.description ?? ''))].join(' ');
122
+ return [...text.matchAll(/["“]([a-z][a-z0-9 ,'-]{5,60})["”]/g)].map((m) => m[1]).filter((q) => q.includes(' '));
77
123
  }
78
124
  const RATE_LIMIT = /rate.?limit|too many requests|\b429\b/i;
79
125
  function sleep(ms) {
@@ -108,12 +154,9 @@ export function operationsIn(result) {
108
154
  const text = part.text;
109
155
  if (typeof text !== 'string')
110
156
  continue;
111
- try {
112
- roots.push(JSON.parse(text));
113
- }
114
- catch {
115
- // prose, not a catalog
116
- }
157
+ const value = leadingJson(text);
158
+ if (value !== undefined)
159
+ roots.push(value);
117
160
  }
118
161
  const out = new Map();
119
162
  const walk = (v, depth) => {
@@ -132,6 +175,46 @@ export function operationsIn(result) {
132
175
  roots.forEach((r) => walk(r, 0));
133
176
  return [...out.values()];
134
177
  }
178
+ /**
179
+ * The JSON value a text starts with, ignoring what follows: Atlassian's discover
180
+ * returns its results as JSON and then a prose list of related operations, which
181
+ * makes the whole text invalid JSON.
182
+ */
183
+ export function leadingJson(text) {
184
+ const trimmed = text.trimStart();
185
+ if (!/^[[{]/.test(trimmed))
186
+ return undefined;
187
+ try {
188
+ return JSON.parse(trimmed);
189
+ }
190
+ catch (error) {
191
+ const at = /position (\d+)/.exec(error instanceof Error ? error.message : '');
192
+ if (!at)
193
+ return undefined;
194
+ try {
195
+ return JSON.parse(trimmed.slice(0, Number(at[1])));
196
+ }
197
+ catch {
198
+ return undefined;
199
+ }
200
+ }
201
+ }
202
+ /**
203
+ * Operation names a result mentions without defining them: lines like
204
+ * "createJiraBoard — Create a new company-managed…" after Atlassian's JSON. Each
205
+ * is worth a search of its own.
206
+ */
207
+ export function mentionedNames(result) {
208
+ const names = new Set();
209
+ for (const part of Array.isArray(result.content) ? result.content : []) {
210
+ const text = part.text;
211
+ if (typeof text !== 'string')
212
+ continue;
213
+ for (const m of text.matchAll(/^[ \t]*[-*]?[ \t]*`?([A-Za-z][A-Za-z0-9_.-]{2,80})`?[ \t]+(?:—|–|-{1,2}|:)[ \t]/gm))
214
+ names.add(m[1]);
215
+ }
216
+ return [...names];
217
+ }
135
218
  function asOperation(o) {
136
219
  if (typeof o.name !== 'string' || !o.name)
137
220
  return undefined;
package/dist/config.d.ts CHANGED
@@ -21,6 +21,9 @@ export interface Config {
21
21
  tool?: string;
22
22
  queries?: string[];
23
23
  pauseMs?: number;
24
+ crawl?: boolean;
25
+ maxQueries?: number;
26
+ stopAfter?: number;
24
27
  };
25
28
  }
26
29
  /** Optional: no config file is fine. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "toolmenu",
3
- "version": "0.10.0",
3
+ "version": "0.11.0",
4
4
  "description": "Lint your MCP server's tool menu for changes that confuse agents or break caches.",
5
5
  "author": "Niksa (https://niksa.me)",
6
6
  "main": "dist/index.js",