fix: temporary fix, revert zod schema definitions for mcp tools to zod v3 (#1323)

Author: Crunchyman-ralph

.changeset/kind-lines-melt.md

@@ -0,0 +1,21 @@
+---
+"task-master-ai": patch
+---
+
+Fix MCP server compatibility with Draft-07 clients (Augment IDE, gemini-cli, gemini code assist)
+
+- Resolves #1284
+
+**Problem:**
+
+- MCP tools were using Zod v4, which outputs JSON Schema Draft 2020-12
+- MCP clients only support Draft-07
+- Tools were not discoverable in gemini-cli and other clients
+
+**Solution:**
+
+- Updated all MCP tools to import from `zod/v3` instead of `zod`
+- Zod v3 schemas convert to Draft-07 via FastMCP's zod-to-json-schema
+- Fixed logger to use stderr instead of stdout (MCP protocol requirement)
+
+This is a temporary workaround until FastMCP adds JSON Schema version configuration.

.coderabbit.yaml

@@ -1,3 +1,7 @@
 reviews:
   profile: chill
   poem: false
+  auto_review:
+    enabled: true
+    base_branches:
+      - ".*"

apps/mcp/src/tools/README-ZOD-V3.md

@@ -0,0 +1,70 @@
+# 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)

apps/mcp/src/tools/autopilot/abort.tool.ts

@@ -3,7 +3,9 @@
  * Abort a running TDD workflow and clean up state
  */
 
-import { z } from 'zod';
+// TEMPORARY: Using zod/v3 for Draft-07 JSON Schema compatibility with FastMCP's zod-to-json-schema
+// TODO: Revert to 'zod' when MCP spec issue is resolved (see PR #1323)
+import { z } from 'zod/v3';
 import {
 	handleApiResult,
 	withNormalizedProjectRoot

apps/mcp/src/tools/autopilot/commit.tool.ts

@@ -3,7 +3,9 @@
  * Create a git commit with automatic staging and message generation
  */
 
-import { z } from 'zod';
+// TEMPORARY: Using zod/v3 for Draft-07 JSON Schema compatibility with FastMCP's zod-to-json-schema
+// TODO: Revert to 'zod' when MCP spec issue is resolved (see PR #1323)
+import { z } from 'zod/v3';
 import {
 	handleApiResult,
 	withNormalizedProjectRoot

apps/mcp/src/tools/autopilot/complete.tool.ts

@@ -3,7 +3,9 @@
  * Complete the current TDD phase with test result validation
  */
 
-import { z } from 'zod';
+// TEMPORARY: Using zod/v3 for Draft-07 JSON Schema compatibility with FastMCP's zod-to-json-schema
+// TODO: Revert to 'zod' when MCP spec issue is resolved (see PR #1323)
+import { z } from 'zod/v3';
 import {
 	handleApiResult,
 	withNormalizedProjectRoot

apps/mcp/src/tools/autopilot/finalize.tool.ts

@@ -3,7 +3,9 @@
  * Finalize and complete the workflow with working tree validation
  */
 
-import { z } from 'zod';
+// TEMPORARY: Using zod/v3 for Draft-07 JSON Schema compatibility with FastMCP's zod-to-json-schema
+// TODO: Revert to 'zod' when MCP spec issue is resolved (see PR #1323)
+import { z } from 'zod/v3';
 import {
 	handleApiResult,
 	withNormalizedProjectRoot

apps/mcp/src/tools/autopilot/next.tool.ts

@@ -3,7 +3,9 @@
  * Get the next action to perform in the TDD workflow
  */
 
-import { z } from 'zod';
+// TEMPORARY: Using zod/v3 for Draft-07 JSON Schema compatibility with FastMCP's zod-to-json-schema
+// TODO: Revert to 'zod' when MCP spec issue is resolved (see PR #1323)
+import { z } from 'zod/v3';
 import {
 	handleApiResult,
 	withNormalizedProjectRoot

apps/mcp/src/tools/autopilot/resume.tool.ts

@@ -3,7 +3,9 @@
  * Resume a previously started TDD workflow from saved state
  */
 
-import { z } from 'zod';
+// TEMPORARY: Using zod/v3 for Draft-07 JSON Schema compatibility with FastMCP's zod-to-json-schema
+// TODO: Revert to 'zod' when MCP spec issue is resolved (see PR #1323)
+import { z } from 'zod/v3';
 import {
 	handleApiResult,
 	withNormalizedProjectRoot

apps/mcp/src/tools/autopilot/start.tool.ts

@@ -3,7 +3,9 @@
  * Initialize and start a new TDD workflow for a task
  */
 
-import { z } from 'zod';
+// TEMPORARY: Using zod/v3 for Draft-07 JSON Schema compatibility with FastMCP's zod-to-json-schema
+// TODO: Revert to 'zod' when MCP spec issue is resolved (see PR #1323)
+import { z } from 'zod/v3';
 import {
 	handleApiResult,
 	withNormalizedProjectRoot