feat: allow custom friendlyErrors message on parameters validation error (#151)

* feat: allow custom friendlyErrors message on parameters validation error

Add general usage utils param to server constructor

* fix: add formatInvalidParamsErrorMessage callback test

---------

Co-authored-by: Frank Fiegel <[email protected]>

Author: soamati

src/FastMCP.test.ts

@@ -2914,3 +2914,60 @@ test("HTTP Stream: calls a tool", { timeout: 20000 }, async () => {
     await server.stop();
   }
 });
+
+test("uses `formatInvalidParamsErrorMessage` callback to build ErrorCode.InvalidParams error message", async () => {
+  await runWithTestServer({
+    run: async ({ client }) => {
+      try {
+        await client.callTool({
+          arguments: {
+            a: 1,
+            b: "invalid",
+          },
+          name: "add",
+        });
+      } catch (error) {
+        expect(error).toBeInstanceOf(McpError);
+
+        // @ts-expect-error - we know that error is an McpError
+        expect(error.code).toBe(ErrorCode.InvalidParams);
+
+        // @ts-expect-error - we know that error is an McpError
+        expect(error.message).toBe(
+          `MCP error -32602: MCP error -32602: Tool 'add' parameter validation failed: My custom error message: Field b failed with error 'Expected number, received string'. Please check the parameter types and values according to the tool's schema.`,
+        );
+      }
+    },
+    server: async () => {
+      const server = new FastMCP({
+        name: "Test",
+        utils: {
+          formatInvalidParamsErrorMessage: (issues) => {
+            const message = issues
+              .map((issue) => {
+                const path = issue.path?.join(".") || "root";
+                return `Field ${path} failed with error '${issue.message}'`;
+              })
+              .join(", ");
+            return `My custom error message: ${message}`;
+          },
+        },
+        version: "1.0.0",
+      });
+
+      server.addTool({
+        description: "Add two numbers",
+        execute: async (args) => {
+          return String(args.a + args.b);
+        },
+        name: "add",
+        parameters: z.object({
+          a: z.number(),
+          b: z.number(),
+        }),
+      });
+
+      return server;
+    },
+  });
+});

src/FastMCP.ts

@@ -670,6 +670,14 @@ type ServerOptions<T extends FastMCPSessionAuth> = {
      */
     enabled?: boolean;
   };
+  /**
+   * General utilities
+   */
+  utils?: {
+    formatInvalidParamsErrorMessage?: (
+      issues: readonly StandardSchemaV1.Issue[],
+    ) => string;
+  };
   version: `${number}.${number}.${number}`;
 };
 
@@ -790,6 +798,8 @@ export class FastMCPSession<
 
   #server: Server;
 
+  #utils?: ServerOptions<T>["utils"];
+
   constructor({
     auth,
     instructions,
@@ -801,6 +811,7 @@ export class FastMCPSession<
     roots,
     tools,
     transportType,
+    utils,
     version,
   }: {
     auth?: T;
@@ -813,6 +824,7 @@ export class FastMCPSession<
     roots?: ServerOptions<T>["roots"];
     tools: Tool<T>[];
     transportType?: "httpStream" | "stdio";
+    utils?: ServerOptions<T>["utils"];
     version: string;
   }) {
     super();
@@ -845,6 +857,8 @@ export class FastMCPSession<
       { capabilities: this.#capabilities, instructions: instructions },
     );
 
+    this.#utils = utils;
+
     this.setupErrorHandling();
     this.setupLoggingHandlers();
     this.setupRootsHandlers();
@@ -1487,12 +1501,14 @@ export class FastMCPSession<
         );
 
         if (parsed.issues) {
-          const friendlyErrors = parsed.issues
-            .map((issue) => {
-              const path = issue.path?.join(".") || "root";
-              return `${path}: ${issue.message}`;
-            })
-            .join(", ");
+          const friendlyErrors = this.#utils?.formatInvalidParamsErrorMessage
+            ? this.#utils.formatInvalidParamsErrorMessage(parsed.issues)
+            : parsed.issues
+                .map((issue) => {
+                  const path = issue.path?.join(".") || "root";
+                  return `${path}: ${issue.message}`;
+                })
+                .join(", ");
 
           throw new McpError(
             ErrorCode.InvalidParams,
@@ -1872,6 +1888,7 @@ export class FastMCP<
         roots: this.#options.roots,
         tools: this.#tools,
         transportType: "stdio",
+        utils: this.#options.utils,
         version: this.#options.version,
       });
 
@@ -1903,6 +1920,7 @@ export class FastMCP<
             roots: this.#options.roots,
             tools: this.#tools,
             transportType: "httpStream",
+            utils: this.#options.utils,
             version: this.#options.version,
           });
         },