toolmenu 0.27.0 → 0.27.1

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/dist/cli.js CHANGED
@@ -482,7 +482,7 @@ export async function main(given) {
482
482
  if (values.value || values['values-file'] || values['assume-read-only'])
483
483
  throw new UsageError('--value, --values-file and --assume-read-only go with --auto. In a scenario, write the values into the steps\' args, and list tools under assume_read_only.');
484
484
  if (!values.scenario)
485
- throw new UsageError('session needs --scenario <file>. Run session --init for a starter, or see https://github.com/niksa90/toolmenu#session-the-menu-changing-while-the-agent-works for the format.');
485
+ throw new UsageError('session needs --scenario <file>. Run session --init for a starter, or see https://github.com/niksa90/toolmenu/blob/main/docs/session.md for the format.');
486
486
  let scenario;
487
487
  try {
488
488
  scenario = await loadScenario(values.scenario);
package/dist/help.js CHANGED
@@ -220,8 +220,8 @@ const HELP = {
220
220
  summary: 'serve toolmenu to an agent as an MCP server (stdio)',
221
221
  usage: ['toolmenu mcp'],
222
222
  about: [
223
- 'An MCP server over stdio, for the agent building your server: snapshot_menu, diff_menus,',
224
- 'check_session and explain_rule, each running the matching command. Relative paths and',
223
+ 'An MCP server over stdio, for the agent building your server: snapshot_menu, check_session,',
224
+ 'diff_menus, review_baseline, check_auth and explain_rule, each running the matching command. Relative paths and',
225
225
  'toolmenu.config.json resolve from the folder it runs in, or a tool call\'s cwd.',
226
226
  'Claude Code: claude mcp add toolmenu -- npx -y toolmenu mcp',
227
227
  ],
package/dist/mcp.d.ts CHANGED
@@ -30,7 +30,7 @@ type Text = {
30
30
  isError?: boolean;
31
31
  };
32
32
  /** A CLI run as a tool result. Findings are a report, not a failure: only exit 2 (couldn't run) is an error. */
33
- export declare function toResult(run: CliRun): Text;
33
+ export declare function toResult(run: CliRun, exitOne?: string): Text;
34
34
  type ServerArgs = {
35
35
  command?: string[];
36
36
  url?: string;
package/dist/mcp.js CHANGED
@@ -141,14 +141,14 @@ export function runCli(args, cwd, options = {}) {
141
141
  });
142
142
  }
143
143
  /** A CLI run as a tool result. Findings are a report, not a failure: only exit 2 (couldn't run) is an error. */
144
- export function toResult(run) {
144
+ export function toResult(run, exitOne = '\n\nExit 1: there are error-level findings.') {
145
145
  const out = run.stdout.trim();
146
146
  if (run.code === 2) {
147
147
  const why = [run.stopped, run.stderr.trim()].filter(Boolean).join('\n\n') || out || 'toolmenu exited with code 2.';
148
148
  return { content: [{ type: 'text', text: why }], isError: true };
149
149
  }
150
150
  const notes = run.stderr.trim();
151
- const tail = run.code === 1 ? '\n\nExit 1: there are error-level findings.' : '';
151
+ const tail = run.code === 1 ? exitOne : '';
152
152
  return { content: [{ type: 'text', text: `${out || 'No output.'}${tail}${notes ? `\n\nNotes:\n${notes}` : ''}` }] };
153
153
  }
154
154
  const serverShape = {
@@ -252,10 +252,11 @@ const failed = (text) => ({ content: [{ type: 'text', text }], isError: true });
252
252
  export function build(baseCwd = process.cwd()) {
253
253
  const server = new McpServer({ name: 'toolmenu', version: VERSION }, {
254
254
  capabilities: { tools: {} },
255
- // The same four tools for everyone, always: an hour, and shared caches may keep it.
255
+ // The same six tools for everyone, always: an hour, and shared caches may keep it.
256
256
  cacheHints: { 'tools/list': { ttlMs: 3_600_000, cacheScope: 'public' }, 'server/discover': { ttlMs: 3_600_000, cacheScope: 'public' } },
257
- instructions: "toolmenu checks an MCP server's tool list (its menu) the way clients and agents meet it. " +
258
- 'After changing a server\'s tools: snapshot_menu for findings and token cost, diff_menus against the committed menu.json for breaking changes, check_session to see whether the menu changes mid-session. ' +
257
+ instructions: 'toolmenu tests an MCP server the way clients and agents meet it: the tool list (its menu), the calls, the results, the sign-in, and the next release. ' +
258
+ 'After changing a server\'s tools: snapshot_menu for findings and token cost, check_session to call its read-only tools and see whether results match their schemas and whether the menu changes mid-session, ' +
259
+ 'diff_menus against the committed menu.json for breaking changes, and review_baseline before replacing that baseline. check_auth for an HTTP server that answers 401. ' +
259
260
  'Each finding ends with a → Next: step; explain_rule says what a rule checks.',
260
261
  });
261
262
  /** Run a command for a server: the folder checked, credentials kept out of argv. */
@@ -269,7 +270,7 @@ export function build(baseCwd = process.cwd()) {
269
270
  return toResult(await runCli([...args(f.dir, s), ...s.after], f.dir, { secretArgs: s.secret, signal: ctx.mcpReq.signal }));
270
271
  };
271
272
  server.registerTool('snapshot_menu', {
272
- description: "Check an MCP server's tool list: start or connect to it, list its tools, and report findings (what agents misread, what breaks clients or prompt caches) and the token cost. " +
273
+ description: "Check an MCP server's tool list as a client reads it: start or connect to it, list its tools, and report findings (what clients reject, what breaks prompt caches, what agents misread) and the token cost. " +
273
274
  'A command server is started by running command as given, so only pass a command you would run yourself. ' +
274
275
  'Writes the menu file only when save_as is given (the baseline for diff_menus): a new file inside cwd, or an existing menu file there.',
275
276
  inputSchema: {
@@ -315,7 +316,7 @@ export function build(baseCwd = process.cwd()) {
315
316
  return toResult(await runCli(args, f.dir, { signal: ctx.mcpReq.signal }));
316
317
  });
317
318
  server.registerTool('check_session', {
318
- description: "Check whether an MCP server's menu changes while an agent works: call its tools marked readOnlyHint whose arguments the schema can fill, list the menu after each call, and report each change with the call that caused it. " +
319
+ description: "Call an MCP server's tools as an agent would and check what comes back: its tools marked readOnlyHint whose arguments the schema can fill are called, each result is checked against the tool's outputSchema, and the menu is listed after each call, with each change reported with the call that caused it. " +
319
320
  'Calls only read-only tools; never one marked openWorldHint unless open_world is set. A command server is started by running command as given, so only pass a command you would run yourself.',
320
321
  inputSchema: {
321
322
  ...serverShape,
@@ -330,6 +331,45 @@ export function build(baseCwd = process.cwd()) {
330
331
  ...(a.max_calls ? [`--max-calls=${a.max_calls}`] : []),
331
332
  ...(a.open_world ? ['--open-world'] : []),
332
333
  ]));
334
+ server.registerTool('review_baseline', {
335
+ description: 'Say whether a new menu file should replace the baseline: one verdict (unchanged, safe, breaking-released, breaking, review), what breaks callers, and which findings the new menu adds, clears or makes worse. ' +
336
+ 'Use it before overwriting a committed menu.json. Reads the two files only and starts no server.',
337
+ inputSchema: {
338
+ baseline: z.string().describe('The menu file to replace, e.g. the committed menu.json.'),
339
+ candidate: z.string().describe('The new menu file, e.g. new-menu.json from snapshot_menu save_as.'),
340
+ release: z.string().optional().describe('The release versions, so breaking changes pass when the bump allows them: "1.4.0..2.0.0".'),
341
+ cwd: serverShape.cwd,
342
+ },
343
+ annotations: { title: 'Review a new menu against the baseline', readOnlyHint: true, openWorldHint: false },
344
+ }, async (a, ctx) => {
345
+ const f = folder(baseCwd, a.cwd);
346
+ if ('error' in f)
347
+ return failed(f.error);
348
+ const args = ['review', ...(a.release ? [`--release=${a.release}`] : []), absolute(f.dir, a.baseline), absolute(f.dir, a.candidate)];
349
+ const run = await runCli(args, f.dir, { signal: ctx.mcpReq.signal });
350
+ // Exit 1 here is the verdict (don't accept as is), which the report already leads with.
351
+ return toResult(run, "\n\nExit 1: the verdict is not to accept the new menu as it is.");
352
+ });
353
+ server.registerTool('check_auth', {
354
+ description: "Check an HTTP MCP server's OAuth discovery the way a client that follows the spec walks it, without logging in: the 401 and its WWW-Authenticate, the protected resource metadata, the authorization server's metadata, PKCE and registration. " +
355
+ 'Use it when a server answers 401 or a client cannot sign in. Sends unauthenticated requests to the URL and to the metadata addresses it names; no credentials, no tokens.',
356
+ inputSchema: { url: z.string().describe('The Streamable HTTP endpoint: https://mcp.example.com/mcp.') },
357
+ annotations: { title: "Check a server's OAuth discovery", readOnlyHint: true, openWorldHint: true },
358
+ }, async (a, ctx) => {
359
+ // The check is of what a client sees before it has credentials, so the URL carries none.
360
+ let parsed;
361
+ try {
362
+ parsed = new URL(a.url);
363
+ }
364
+ catch {
365
+ // not a URL: said below
366
+ }
367
+ if (parsed?.protocol !== 'https:')
368
+ return failed('url must be an https URL, such as https://mcp.example.com/mcp: OAuth discovery is checked over https.');
369
+ if (parsed.username || parsed.password)
370
+ return failed('Drop the user:password@ part of the URL: the check is made without credentials.');
371
+ return toResult(await runCli(['auth', 'check', a.url], baseCwd, { signal: ctx.mcpReq.signal }));
372
+ });
333
373
  server.registerTool('explain_rule', {
334
374
  description: "Explain a toolmenu rule by the name a finding gives (naming/vague-id): what it checks, its default level and how to change it. Without rule, lists every rule.",
335
375
  inputSchema: { rule: z.string().optional().describe('The rule, as a finding names it: naming/vague-id, or just vague-id.') },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "toolmenu",
3
- "version": "0.27.0",
3
+ "version": "0.27.1",
4
4
  "mcpName": "io.github.niksa90/toolmenu",
5
5
  "description": "Test your MCP server the way agents and clients meet it: the menu, the calls, the results, the sign-in, and every release after. No LLM involved.",
6
6
  "author": "Nikša Perović (https://niksa.me)",