feat: add UserError

README.md

@@ -110,6 +110,29 @@ server.addTool({
 });
 ```
 
+#### Errors
+
+The errors that are meant to be shown to the user should be thrown as `UserError` instances:
+
+```js
+import { UserError } from "fastmcp";
+
+server.addTool({
+  name: "download",
+  description: "Download a file",
+  parameters: z.object({
+    url: z.string(),
+  }),
+  execute: async (args) => {
+    if (args.url.startsWith("https://example.com")) {
+      throw new UserError("This URL is not allowed");
+    }
+
+    return "done";
+  },
+});
+```
+
 #### Progress
 
 Tools can report progress by calling `reportProgress` in the context object:

src/FastMCP.test.ts

@@ -1,4 +1,4 @@
-import { FastMCP } from "./FastMCP.js";
+import { FastMCP, UserError } from "./FastMCP.js";
 import { z } from "zod";
 import { test, expect, vi } from "vitest";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -138,7 +138,7 @@ test("calls a tool", async () => {
   });
 });
 
-test("handles tool errors", async () => {
+test("handles UserError errors", async () => {
   await runWithTestServer({
     start: async () => {
       const server = new FastMCP({
@@ -154,7 +154,7 @@ test("handles tool errors", async () => {
           b: z.number(),
         }),
         execute: async (args) => {
-          throw new Error("Something went wrong");
+          throw new UserError("Something went wrong");
         },
       });
 
@@ -170,7 +170,7 @@ test("handles tool errors", async () => {
           },
         }),
       ).toEqual({
-        content: [{ type: "text", text: "Error: Error: Something went wrong" }],
+        content: [{ type: "text", text: "Something went wrong" }],
         isError: true,
       });
     },

src/FastMCP.ts

@@ -16,6 +16,29 @@ import { zodToJsonSchema } from "zod-to-json-schema";
 import type { z } from "zod";
 import http from "http";
 
+abstract class FastMCPError extends Error {
+  public constructor(message?: string) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+type Extra = unknown;
+
+type Extras = Record<string, Extra>;
+
+class UnexpectedStateError extends FastMCPError {
+  public extras?: Extras;
+
+  public constructor(message: string, extras?: Extras) {
+    super(message);
+    this.name = new.target.name;
+    this.extras = extras;
+  }
+}
+
+export class UserError extends UnexpectedStateError {}
+
 type ToolParameters = z.ZodTypeAny;
 
 type Progress = {
@@ -181,6 +204,13 @@ export class FastMCP {
             reportProgress,
           });
         } catch (error) {
+          if (error instanceof UserError) {
+            return {
+              content: [{ type: "text", text: error.message }],
+              isError: true,
+            };
+          }
+
           return {
             content: [{ type: "text", text: `Error: ${error}` }],
             isError: true,