build: auto-generate Zod schemas from TypeScript types using ts-to-zod

[ochafik]

TL;DR

Edit types in one place → Zod schemas + JSON Schema auto-generated.

Before: Hand-maintain both TypeScript interfaces AND Zod schemas (error-prone, tedious).
After: Edit src/spec.types.ts only. Run npm run generate:schemas. Done.

---

How It Works

1. Single Source of Truth

src/spec.types.ts          ← YOU EDIT THIS (TypeScript interfaces)
        ↓
   npm run generate:schemas
        ↓
src/generated/
├── schema.ts              ← Zod schemas (auto-generated)
├── schema.test.ts         ← Type verification (auto-generated)  
└── schema.json            ← JSON Schema (auto-generated)

2. Generation Pipeline

We use ts-to-zod to convert TypeScript interfaces to Zod schemas, then post-process the output:

ts-to-zod Output	Post-Processing	Why
import { z } from "zod"	→ "zod/v4"	We use Zod v4 subpath
z.any() for SDK types	→ Import actual schemas	ContentBlock, Tool, etc. have real schemas in MCP SDK
z.record().and(z.object())	→ z.looseObject()	Index signatures need simpler representation

3. Adding Descriptions

Use @description JSDoc tags to generate .describe() calls:

// In spec.types.ts:
interface McpUiOpenLinkRequest {
  params: {
    /** @description URL to open in the host's browser */
    url: string;
  };
}

Generates:

// In generated/schema.ts:
export const McpUiOpenLinkRequestSchema = z.object({
  params: z.object({
    url: z.string().describe("URL to open in the host's browser")
  })
});

These descriptions flow into the JSON Schema too, enabling documentation generation and IDE support.

---

What's Exported

// Types (from spec.types.ts)
import type { McpUiOpenLinkRequest, McpUiHostContext, ... } from "@modelcontextprotocol/ext-apps";

// Zod Schemas (from generated/schema.ts)  
import { McpUiOpenLinkRequestSchema, McpUiHostContextSchema, ... } from "@modelcontextprotocol/ext-apps";

// JSON Schema
import schema from "@modelcontextprotocol/ext-apps/schema.json";

All 47 exports from main branch are preserved with identical types.

---

Testing

Check	Status
npm run build	✅ Passes
npm test	✅ 15 tests pass
Type compatibility	✅ Compile-time verified via schema.test.ts
Backwards compatibility	✅ All 47 exports from main preserved
CI freshness check	✅ git diff --exit-code src/generated/

---

For Reviewers

Key files to review:

• src/spec.types.ts - The new source of truth for all protocol types
• scripts/generate-schemas.ts - The generation + post-processing logic
• src/types.ts - Re-exports (just wiring, no logic)

The src/generated/ files are auto-generated and don't need detailed review.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/ext-apps@116

commit: 0285d51

[idosal]

Awesome @ochafik !