How to add Zod input validation to MCP tools

1// TypeScript
2server.registerTool("create-user", {
3  description: "Create a new user account",
4  inputSchema: {
5    username: z.string().min(3).max(30).regex(/^[a-zA-Z0-9_]+$/)
6      .describe("Username (3-30 chars, alphanumeric and underscores)"),
7    email: z.string().email()
8      .describe("Valid email address"),
9    bio: z.string().max(500).optional()
10      .describe("Optional user bio, max 500 characters"),
11  },
12}, async ({ username, email, bio }) => {
13  // Parameters are already validated by Zod
14  const user = await createUser({ username, email, bio });
15  return { content: [{ type: "text", text: `Created user: ${user.id}` }] };
16});

1// TypeScript
2server.registerTool("search-records", {
3  description: "Search database records with pagination",
4  inputSchema: {
5    query: z.string().min(1).describe("Search query"),
6    page: z.number().int().min(1).default(1)
7      .describe("Page number, starting from 1"),
8    pageSize: z.number().int().min(1).max(100).default(20)
9      .describe("Results per page, 1-100"),
10    minScore: z.number().min(0).max(1).optional()
11      .describe("Minimum relevance score (0.0-1.0)"),
12  },
13}, async ({ query, page, pageSize, minScore }) => {
14  const results = await search(query, { page, pageSize, minScore });
15  return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
16});
17
18# Python equivalent
19@mcp.tool()
20async def search_records(
21    query: str,
22    page: int = 1,
23    page_size: int = 20,
24    min_score: float | None = None,
25) -> str:
26    """Search database records with pagination.
27
28    Args:
29        query: Search query
30        page: Page number, starting from 1
31        page_size: Results per page, 1-100
32        min_score: Minimum relevance score (0.0-1.0)
33    """
34    results = await search(query, page=page, page_size=page_size, min_score=min_score)
35    return json.dumps(results, indent=2)

1// TypeScript
2server.registerTool("list-tasks", {
3  description: "List project tasks with filtering and sorting",
4  inputSchema: {
5    status: z.enum(["open", "in-progress", "done", "cancelled"])
6      .describe("Filter by task status"),
7    priority: z.enum(["low", "medium", "high", "critical"]).optional()
8      .describe("Filter by priority level"),
9    sortBy: z.enum(["created", "updated", "priority", "title"]).default("updated")
10      .describe("Field to sort results by"),
11    sortOrder: z.enum(["asc", "desc"]).default("desc")
12      .describe("Sort direction"),
13  },
14}, async ({ status, priority, sortBy, sortOrder }) => {
15  const tasks = await listTasks({ status, priority, sortBy, sortOrder });
16  return { content: [{ type: "text", text: JSON.stringify(tasks, null, 2) }] };
17});

1// TypeScript
2server.registerTool("send-notifications", {
3  description: "Send notifications to multiple users",
4  inputSchema: {
5    recipients: z.array(z.string().email()).min(1).max(50)
6      .describe("List of email addresses to notify (1-50)"),
7    message: z.object({
8      subject: z.string().min(1).max(200).describe("Notification subject"),
9      body: z.string().min(1).max(5000).describe("Notification body text"),
10      priority: z.enum(["low", "normal", "urgent"]).default("normal")
11        .describe("Message priority"),
12    }).describe("Notification content"),
13    dryRun: z.boolean().default(false)
14      .describe("If true, validate inputs without sending"),
15  },
16}, async ({ recipients, message, dryRun }) => {
17  if (dryRun) {
18    return { content: [{ type: "text", text: `Dry run: would notify ${recipients.length} recipients` }] };
19  }
20  await sendNotifications(recipients, message);
21  return { content: [{ type: "text", text: `Sent to ${recipients.length} recipients` }] };
22});

1// TypeScript
2server.registerTool("transfer-funds", {
3  description: "Transfer funds between accounts",
4  inputSchema: {
5    fromAccount: z.string().describe("Source account ID"),
6    toAccount: z.string().describe("Destination account ID"),
7    amount: z.number().positive().max(10000).describe("Amount to transfer (max 10,000)"),
8    currency: z.enum(["USD", "EUR", "GBP"]).describe("Currency"),
9  },
10}, async ({ fromAccount, toAccount, amount, currency }) => {
11  // Business logic validation
12  if (fromAccount === toAccount) {
13    return {
14      content: [{ type: "text", text: "Error: Source and destination accounts must be different" }],
15      isError: true,
16    };
17  }
18  const balance = await getBalance(fromAccount, currency);
19  if (balance < amount) {
20    return {
21      content: [{ type: "text", text: `Error: Insufficient funds. Balance: ${balance} ${currency}` }],
22      isError: true,
23    };
24  }
25  const result = await executeTransfer(fromAccount, toAccount, amount, currency);
26  return { content: [{ type: "text", text: `Transfer complete. ID: ${result.id}` }] };
27});