Hi HN! Author here.

When an LLM-powered tool call blows up, the model usually sees an opaque stack trace. It can’t tell whether to retry, give up, or suggest a fix, so users get “Something went wrong” or infinite retry loops.

Cursor’s editor solved this by wrapping errors in a small, structured JSON envelope:

``` Request ID: c90e… {"error":"ERROR_USER_ABORTED_REQUEST", "details":{"title":"User aborted request.", "isRetryable":false}, "isExpected":true} ```

That single structure lets the agent reason correctly (“don’t retry; the user cancelled”).

I wanted the same behavior in standalone MCP servers and LangChain tools, so I extracted it into a tiny package:

``` npm i @bjoaquinc/mcp-error-formatter ```

```ts import { formatMCPError } from "@bjoaquinc/mcp-error-formatter";

export async function githubTool(args) { try { const data = await github.repos.get(args.repo); return { content: [{ type: "text", text: JSON.stringify(data) }] }; } catch (err) { return formatMCPError(err, { title: "GitHub API failed", isRetryable: true, // optional flags }); } } ```

* Supports both structured and unstructured content * Zero deps (aside from `uuid`), \~3 kB min+gzip * Adds `isRetryable`, `isExpected`, `errorType`, `requestId`, and free-form `additionalInfo` * Returns a standard `CallToolResult`, so it slots into marimo, LangChain, FastMCP, or plain MCP SDK * Apache-2.0 (OSS)

Repo: [https://github.com/bjoaquinc/mcp-error-formatter](https://github.com/bjoaquinc/mcp-error-formatter)

I’d love feedback on the format, naming, or edge-cases I’ve missed. PRs and issues welcome—happy to iterate.