Taskmaster

# Why MCP Tools Use Zod v3 ## Problem - **FastMCP** uses `xsschema` to convert schemas → outputs JSON Schema **Draft 2020-12** - **MCP clients** (Augment IDE, gemini-cli, etc.) only support **Draft-07** - Using Zod v4 in tools causes "vendor undefined" errors and tool discovery failures ## Temporary Solution All MCP tool files import from `zod/v3` instead of `zod`: ```javascript import { z } from 'zod/v3'; // ✅ Draft-07 compatible // NOT: import { z } from 'zod'; // ❌ Would use Draft 2020-12 ``` ### Why This Works - Zod v4 ships with v3 compatibility at `zod/v3` - FastMCP + zod-to-json-schema converts Zod v3 schemas → **Draft-07** - This ensures MCP clients can discover and use our tools ### What This Means - ✅ **MCP tools** → use `zod/v3` (this directory) - ✅ **Rest of codebase** → uses `zod` (Zod v4) - ✅ **No conflicts** → they're from the same package, just different versions ## When Can We Remove This? This workaround can be removed when **either**: 1. **FastMCP adds JSON Schema version configuration** - e.g., `new FastMCP({ jsonSchema: { target: 'draft-07' } })` - Tracking: https://github.com/punkpeye/fastmcp/issues/189 2. **MCP spec adds Draft 2020-12 support** - Unlikely in the short term 3. **xsschema adds version targeting** - Would allow FastMCP to use Draft-07 ## How to Maintain When adding new MCP tools: ```javascript // ✅ CORRECT import { z } from 'zod/v3'; server.addTool({ name: 'my_tool', parameters: z.object({ ... }), // Will use Draft-07 execute: async (args) => { ... } }); ``` ```javascript // ❌ WRONG - Will break MCP client compatibility import { z } from 'zod'; // Don't do this in mcp-server/src/tools/ ``` --- **Last Updated:** 2025-10-18 **Affects:** All files in `mcp-server/src/tools/`