# 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`:

```typescript
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` (apps/mcp & mcp-server/src/tools)
- ✅ **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:

```typescript
// ✅ CORRECT
import { z } from 'zod/v3';

export function registerMyTool(server: FastMCP) {
  server.addTool({
    name: 'my_tool',
    parameters: z.object({ ... }),  // Will use Draft-07
    execute: async (args, context) => { ... }
  });
}
```

```typescript
// ❌ WRONG - Will break MCP client compatibility
import { z } from 'zod';  // Don't do this in apps/mcp/src/tools/
```

---

**Last Updated:** 2025-10-18
**Affects:** All files in `apps/mcp/src/tools/`
**See Also:** `mcp-server/src/tools/README-ZOD-V3.md` (same workaround)
