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
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/13542-an-mcp-tool-error-carries-the-same-next → main 3 commits fork 3 threads · 3 unresolved
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 | ||
| 22 | 22 | if (code === "forbidden" || code === "unauthorized") |
| 23 | 23 | return "`whoami_can` says what this token and account may do; use one that may, or ask someone who can, and repeat the call."; |
| 24 | 24 | 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\`.`; | |
| 26 | 26 | if (code === "rate_limited" || code === "too_many") return `wait a few seconds and call ${name} again.`; |
| 27 | 27 | if (code === "conflict" || code.startsWith("no_")) return `read the current state with ${name} or \`find_tool\` before trying again.`; |
| 28 | 28 | 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 | ||
| 35 | 35 | return `${message}${/[.!?]$/.test(message) ? "" : "."} Next: ${stepFor(tool, code)}`; |
| 36 | 36 | } |
| 37 | 37 | |
| 38 | const capital = (t: string): string => t.replace(/^./, (c) => c.toUpperCase()); | |
| 39 | ||
| 38 | 40 | /** |
| 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. | |
| 41 | 56 | */ |
| 42 | 57 | 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); | |
| 44 | 59 | } |
| 45 | 60 | |
| 46 | 61 | /** What a read-only token is told when it tries to act. */ |
| @@ -62,6 +77,5 @@ export function hintOfText(text: string): string { | ||
| 62 | 77 | const code = /^([a-z_]+): /.exec(text)?.[1]; |
| 63 | 78 | const next = /\bNext: (.*)$/s.exec(text)?.[1]; |
| 64 | 79 | 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 ?? ""); | |
| 67 | 81 | } |
src/http/respond.ts +67 −27
| @@ -40,48 +40,88 @@ export function json( | ||
| 40 | 40 | ); |
| 41 | 41 | } |
| 42 | 42 | |
| 43 | type Hint = { core: string; rest?: string }; | |
| 44 | ||
| 43 | 45 | /** |
| 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` | |
| 50 | * then `rest`, the pointer to a route, header or verb. `codes` are the sharper | |
| 51 | * words for one error code under that status. | |
| 47 | 52 | */ |
| 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 |
||
| 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 | }, | |
| 64 | 95 | }; |
| 65 | 96 | |
| 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 | } | |
| 68 | 108 | |
| 69 | 109 | /** |
| 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. | |
| 72 | 112 | */ |
| 73 | 113 | 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; | |
| 75 | 115 | } |
| 76 | 116 | |
| 77 | 117 | /** Every 401, 403, 404, 409 and 422 error body carries `hint`; a site's own is kept. */ |
| 78 | 118 | 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; | |
| 81 | 120 | const body = data as Record<string, unknown>; |
| 82 | 121 | if (typeof body.error !== "string") return data; |
| 83 | 122 | 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}` }; | |
| 85 | 125 | } |
| 86 | 126 | |
| 87 | 127 | /** |
test/mcp-error-hints.test.ts +1 −1
| @@ -51,7 +51,7 @@ const okHint = (h: unknown) => { | ||
| 51 | 51 | |
| 52 | 52 | test("the REST hint for a code is the one an MCP refusal reuses", () => { |
| 53 | 53 | 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(); | |
| 55 | 55 | expect(hintOf({ name: "x" }, "not_found")).not.toContain("/contract/"); |
| 56 | 56 | expect(hintOfText("rate_limited: slow down")).toMatch(/wait/i); |
| 57 | 57 | 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 |
||
| 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 | }); |
new above
offline
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.