68 lines
1.8 KiB
Markdown
68 lines
1.8 KiB
Markdown
# 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/`
|