Improve MCP tool action params ergonomics and validation

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

src/agent/mcp/client.test.ts

@@ -0,0 +1,28 @@
+import { normalizeMCPToolParams } from "@/agent/mcp/client";
+
+describe("normalizeMCPToolParams", () => {
+  it("returns object inputs unchanged", () => {
+    const input = { query: "laptops", limit: 5 };
+    expect(normalizeMCPToolParams(input)).toEqual(input);
+  });
+
+  it("parses valid JSON object strings", () => {
+    const json = "{\"query\":\"weather\",\"units\":\"metric\"}";
+    expect(normalizeMCPToolParams(json)).toEqual({
+      query: "weather",
+      units: "metric",
+    });
+  });
+
+  it("throws for invalid JSON strings", () => {
+    expect(() => normalizeMCPToolParams("{invalid")).toThrow(
+      "Invalid MCP tool params JSON string"
+    );
+  });
+
+  it("throws when parsed JSON is not an object", () => {
+    expect(() => normalizeMCPToolParams("[1,2,3]")).toThrow(
+      "must parse to a JSON object"
+    );
+  });
+});

src/agent/mcp/client.ts

@@ -16,6 +16,38 @@ interface ServerConnection {
   actions: AgentActionDefinition[];
 }
 
+const MCPToolActionParams = z.object({
+  params: z
+    .union([z.string(), z.record(z.string(), z.unknown())])
+    .describe(
+      "Parameters for the MCP tool. Provide either a JSON object directly or a JSON string."
+    ),
+});
+
+type MCPToolActionInput = z.infer<typeof MCPToolActionParams>;
+
+export function normalizeMCPToolParams(
+  input: MCPToolActionInput["params"]
+): Record<string, unknown> {
+  if (typeof input === "string") {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(input);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Invalid MCP tool params JSON string: ${message}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(
+        "MCP tool params must parse to a JSON object, not an array or primitive"
+      );
+    }
+    return parsed as Record<string, unknown>;
+  }
+
+  return input;
+}
+
 class MCPClient {
   private servers: Map<string, ServerConnection> = new Map();
   private debug: boolean;
@@ -115,26 +147,20 @@ class MCPClient {
           // Create action definition
           return {
             type: tool.name,
-            actionParams: z
-              .object({
-                params: z
-                  .string()
-                  .describe(
-                    `The stringified parameters to the ${tool.name} MCP tool. Here is the schema: ${JSON.stringify(tool.inputSchema)}`
-                  ),
-              })
-              .describe(tool.description ?? ""),
+            actionParams: MCPToolActionParams.describe(
+              `${tool.description ?? ""} Tool input schema: ${JSON.stringify(tool.inputSchema)}`
+            ),
             run: async (
               ctx: ActionContext,
-              action: any
+              action: MCPToolActionInput
             ): Promise<ActionOutput> => {
               if (!ctx.mcpClient) {
                 throw new Error(
                   "MCP client not available. Please ensure an MCP server is connected."
                 );
               }
 
-              const params = JSON.parse(action.params);
+              const params = normalizeMCPToolParams(action.params);
               const targetServerId = serverId;
 
               const result = await ctx.mcpClient.executeTool(