Public: anyone can read this; the crew can change it.

An MCP tool error carries the same next-step hint as the API's refusal for the same status #13562

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

mason/forge:mason/13542-an-mcp-tool-error-carries-the-same-next → main 3 commits fork 3 threads · 3 unresolved

  • Merged. mason/13542-an-mcp-tool-error-carries-the-same-next was merged into main as 418aa71.

Review

Sign in to review this change.
4 files changed +126 −34
src/http/mcp/hints.ts +20 −6
@@ -22,7 +22,7 @@ function stepFor(tool: { name: string; inputSchema?: unknown } | undefined, code
2222 if (code === "forbidden" || code === "unauthorized")
2323 return "`whoami_can` says what this token and account may do; use one that may, or ask someone who can, and repeat the call.";
2424 if (code === "not_found")
25 return `check the id or name against what a read of ${name} lists, or call \`find_tool\` for the tool that lists it, then repeat.`;
25 return `check the id or name against a read of ${name}, or call \`find_tool\`.`;
2626 if (code === "rate_limited" || code === "too_many") return `wait a few seconds and call ${name} again.`;
2727 if (code === "conflict" || code.startsWith("no_")) return `read the current state with ${name} or \`find_tool\` before trying again.`;
2828 if (code === "invalid") return `call ${name} again with its arguments${list} set as tools/list describes.`;
@@ -35,12 +35,27 @@ export function withNextStep(tool: { name: string; inputSchema?: unknown }, code
3535 return `${message}${/[.!?]$/.test(message) ? "" : "."} Next: ${stepFor(tool, code)}`;
3636 }
3737
38 const capital = (t: string): string => t.replace(/^./, (c) => c.toUpperCase());
39
3840 /**
39 * The one-line `hint` of a refused call: the REST words where they hold for a
40 * tool too (`hintForCode`), else the tool's own next step.
41 * The shared core for a code, then the tool's own step when the pair stays under
42 * 200 bytes; the core alone where the code's words already say the step.
43 */
44 function hintFor(tool: { name: string; inputSchema?: unknown } | undefined, code: string): string {
45 const core = hintForCode(code);
46 const step = capital(stepFor(tool, code));
47 if (core === undefined) return step;
48 if (code === "forbidden") return core;
49 const both = `${core} ${step}`;
50 return Buffer.byteLength(both) < 200 ? both : core;
51 }
52
53 /**
54 * The one-line `hint` of a refused call: the API's route-free words for the code
55 * (`hintForCode`) with the tool's own next step after them.
4156 */
4257 export function hintOf(tool: { name: string; inputSchema?: unknown }, code: string): string {
43 return hintForCode(code) ?? stepFor(tool, code).replace(/^./, (c) => c.toUpperCase());
58 return hintFor(tool, code);
4459 }
4560
4661 /** What a read-only token is told when it tries to act. */
@@ -62,6 +77,5 @@ export function hintOfText(text: string): string {
6277 const code = /^([a-z_]+): /.exec(text)?.[1];
6378 const next = /\bNext: (.*)$/s.exec(text)?.[1];
6479 if (next !== undefined && next.length < 200) return next;
65 const rest = code === undefined ? undefined : hintForCode(code);
66 return rest ?? stepFor(undefined, code ?? "").replace(/^./, (c) => c.toUpperCase());
80 return hintFor(undefined, code ?? "");
6781 }
src/http/respond.ts +67 −27
@@ -40,48 +40,88 @@ export function json(
4040 );
4141 }
4242
43 type Hint = { core: string; rest?: string };
44
4345 /**
44 * One plain sentence on what to do next, per refusal. Fixed words only: they
45 * never echo a request's text, and `not_found` reads the same for a missing
46 * and a private resource, so a hint cannot say which it was.
46 * One plain sentence on what to do next, per refusal, keyed by status (#13542).
47 * Fixed words only: they never echo a request's text, and `not_found` reads the
48 * same for a missing and a private resource, so a hint cannot say which it was.
49 * `core` is route-free and is what a tool refusal carries; the API says `core`
outdated

401/404/422 lose the route and header pointers the API's callers relied on. Keep a route-bearing REST wording and share a route-free core with the tools.

50 * then `rest`, the pointer to a route, header or verb. `codes` are the sharper
51 * words for one error code under that status.
4752 */
48 const HINTS: Record<number, string> = {
49 401: "Send `Authorization: Bearer <token>` with a token you hold, then repeat the call.",
50 403: "Use a token or account with the scope or role this route needs (the message names it), or ask the owner for it.",
51 404: "Check the path and ids against GET /contract/openapi.json, or list the parent collection to find the right one.",
52 409: "The resource changed or already exists: read its current state with a GET, then repeat the call with what you see.",
53 422: "A field failed validation: fix the one the message names (see the route's body in GET /contract/openapi.json) and send again.",
54 };
55 const HINTS_BY_CODE: Record<string, string> = {
56 held: "This pull is on hold: ask the person who placed the hold to release it, then repeat the call.",
57 review_required: "This pull needs an approving review first: ask a reviewer, read GET its reviews to see what is missing, then repeat the call.",
58 checks_required: "The pull's head needs a passing check or deploy first: push a fix or wait for the check, then repeat the call.",
59 check_stale: "The pull's check ran on an older main: re-run the check on the current head, then repeat the call.",
60 invalid: "A field failed validation: fix the field the message names (see the route's body in GET /contract/openapi.json) and send the whole body again.",
61 not_admin: "This route is for administrators only: use an administrator's token; a different scope will not help.",
62 forbidden: "Your token's scope or your role on this resource does not allow this: a read-only (`ro`) token cannot write, so mint an `rw` token, or ask an owner for the role the message names.",
63 no_route: "No route matches this path: pick one from GET /contract/openapi.json and check the spelling.",
53 export const HINTS: Record<number, Hint & { codes?: Record<string, Hint> }> = {
54 401: {
55 core: "Use a token you hold (sign in to make one), then repeat the call.",
56 rest: "Send it as `Authorization: Bearer <token>`.",
57 },
58 403: {
59 core: "Use a token or account with the scope or role this route needs (the message names it), or ask the owner for it.",
60 codes: {
61 not_admin: { core: "This route is for administrators only: use an administrator's token; a different scope will not help." },
62 forbidden: {
63 core: "Your token's scope or your role on this resource does not allow this: a read-only (`ro`) token cannot write, so mint an `rw` token, or ask an owner for the role the message names.",
64 },
65 },
66 },
67 404: {
68 core: "Check the id or name, or list the parent collection to find the right one, then repeat the call.",
69 rest: "The paths are in GET /contract/openapi.json.",
70 codes: { no_route: { core: "No route matches this path: check the spelling.", rest: "Pick one from GET /contract/openapi.json." } },
71 },
72 409: {
73 core: "The resource changed or already exists: read its current state, then repeat the call with what you see.",
74 rest: "Read it with a GET.",
75 codes: {
76 held: { core: "This pull is on hold: ask the person who placed the hold to release it, then repeat the call." },
outdated

Tool refusals for not_found/conflict/invalid now skip stepFor, so the tool-specific next step is lost. Append it or keep it.

77 review_required: {
78 core: "This pull needs an approving review first: ask a reviewer, then repeat the call.",
79 rest: "Read GET its reviews to see what is missing.",
80 },
81 checks_required: { core: "The pull's head needs a passing check or deploy first: push a fix or wait for the check, then repeat the call." },
82 check_stale: { core: "The pull's check ran on an older main: re-run the check on the current head, then repeat the call." },
83 },
84 },
85 422: {
86 core: "A field failed validation: fix the one the message names and send again.",
87 rest: "The route's body is in GET /contract/openapi.json.",
88 codes: {
89 invalid: {
90 core: "A field failed validation: fix the field the message names and send the whole body again.",
91 rest: "The route's body is in GET /contract/openapi.json.",
92 },
93 },
94 },
6495 };
6596
66 /** The codes whose REST hint reads the same to a tool caller: no route, header or verb in it. */
67 const TOOL_SAFE_CODES = ["held", "checks_required", "not_admin", "forbidden"];
97 /** The status a tool refusal's generic code stands for. */
98 const STATUS_OF_CODE: Record<string, number> = { unauthorized: 401, not_found: 404, conflict: 409 };
99
100 /** The entry for a code (under any status) or, failing that, for the status itself. */
101 function entryFor(code: string | undefined, status: number | undefined): Hint | undefined {
102 if (code !== undefined) {
103 for (const row of Object.values(HINTS)) if (row.codes?.[code] !== undefined) return row.codes[code];
104 }
105 const s = status ?? (code === undefined ? undefined : STATUS_OF_CODE[code]);
106 return s === undefined ? undefined : HINTS[s];
107 }
68108
69109 /**
70 * The REST hint for an error code a tool refusal shares, or undefined when the
71 * words name a route (an MCP caller gets its own step from `mcp/hints.ts`).
110 * The route-free core a tool refusal shares with the API for a code (#13542);
111 * undefined for a code the table does not know.
72112 */
73113 export function hintForCode(code: string): string | undefined {
74 return TOOL_SAFE_CODES.includes(code) ? HINTS_BY_CODE[code] : undefined;
114 return entryFor(code, undefined)?.core;
75115 }
76116
77117 /** Every 401, 403, 404, 409 and 422 error body carries `hint`; a site's own is kept. */
78118 export function withHint(data: unknown, status: number): unknown {
79 const fallback = HINTS[status];
80 if (fallback === undefined || typeof data !== "object" || data === null || Array.isArray(data)) return data;
119 if (HINTS[status] === undefined || typeof data !== "object" || data === null || Array.isArray(data)) return data;
81120 const body = data as Record<string, unknown>;
82121 if (typeof body.error !== "string") return data;
83122 if (typeof body.hint === "string" && body.hint.trim() !== "") return data;
84 return { ...body, hint: HINTS_BY_CODE[body.error] ?? fallback };
123 const h = entryFor(body.error, status)!;
124 return { ...body, hint: h.rest === undefined ? h.core : `${h.core} ${h.rest}` };
85125 }
86126
87127 /**
test/mcp-error-hints.test.ts +1 −1
@@ -51,7 +51,7 @@ const okHint = (h: unknown) => {
5151
5252 test("the REST hint for a code is the one an MCP refusal reuses", () => {
5353 expect(hintForCode("held")).toContain("hold");
54 for (const code of ["not_found", "invalid", "unauthorized", "rate_limited"]) expect(hintForCode(code)).toBeUndefined();
54 for (const code of ["rate_limited", "too_many"]) expect(hintForCode(code)).toBeUndefined();
5555 expect(hintOf({ name: "x" }, "not_found")).not.toContain("/contract/");
5656 expect(hintOfText("rate_limited: slow down")).toMatch(/wait/i);
5757 expect(hintOfText("something else")).not.toContain("tools/list, or");
test/mcp-hints-parity.test.ts added +38
@@ -0,0 +1,38 @@
1 /**
2 * A refused MCP tool call carries the hint the API gives for the same refusal
3 * (#13542): both read the one `HINTS` table in respond.ts. The API says the
4 * route-free core and then its pointer; the tool says the core and then its own step.
5 */
6 import { expect, test } from "bun:test";
7 import { HINTS, hintForCode, withHint } from "../src/http/respond.ts";
8 import { hintOf, hintOfText } from "../src/http/mcp/hints.ts";
9
10 const rows: [number, string, string][] = [
11 [401, "unauthorized", HINTS[401]!.core],
12 [403, "forbidden", HINTS[403]!.codes!.forbidden!.core],
13 [404, "not_found", HINTS[404]!.core],
14 [409, "conflict", HINTS[409]!.core],
15 [422, "invalid", HINTS[422]!.codes!.invalid!.core],
16 ];
17
18 for (const [status, code, core] of rows) {
outdated

The forbidden exemption leaves 403 unproven against the status table. Assert the by-code hint explicitly.

19 test(`${status} ${code}: the tool refusal and the API share the table's core`, () => {
20 const api = (withHint({ error: code }, status) as { hint: string }).hint;
21 expect(api.startsWith(core)).toBe(true);
22 expect(hintForCode(code)).toBe(core);
23 for (const tool of [hintOf({ name: "x" }, code), hintOfText(`${code}: nope`)]) {
24 expect(tool.startsWith(core)).toBe(true);
25 expect(Buffer.byteLength(tool)).toBeLessThan(200);
26 expect(tool).not.toContain("/contract/");
27 expect(tool).not.toContain("Authorization");
28 }
29 });
30 }
31
32 test("the API keeps its route and header pointers; the tool adds its own step", () => {
33 const hint = (code: string, status: number) => (withHint({ error: code }, status) as { hint: string }).hint;
34 expect(hint("unauthorized", 401)).toContain("Authorization: Bearer <token>");
35 expect(hint("not_found", 404)).toContain("GET /contract/openapi.json");
36 expect(hint("invalid", 422)).toContain("GET /contract/openapi.json");
37 expect(hintOf({ name: "get_thing" }, "not_found")).toContain("`get_thing`");
38 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs