refactor(compat): move zod helpers to zodCompat.ts; throw on invalid normalizeRawShapeSchema input; preserve optional in InferRawShape

- Move isZodSchema/isZodRawShape/normalizeRawShapeSchema from standardSchema.ts to a new zodCompat.ts so standardSchema.ts is Standard-Schema-spec only.
- normalizeRawShapeSchema now throws TypeError for inputs that are neither a raw shape nor a Standard Schema, instead of silently returning them.
- InferRawShape now uses z.infer<z.ZodObject<S>> so .optional() fields produce ?: keys.
- Changeset mentions the completable() constraint widening.

Author: felixweinberger

.changeset/register-rawshape-compat.md

@@ -4,3 +4,5 @@
 ---
 
 `registerTool`/`registerPrompt` accept a raw Zod shape (`{ field: z.string() }`) for `inputSchema`/`outputSchema`/`argsSchema` in addition to a wrapped Standard Schema. Raw shapes are auto-wrapped with `z.object()`. The raw-shape overloads are `@deprecated`; prefer wrapping with `z.object()`.
+
+Also widens the `completable()` constraint from `StandardSchemaWithJSON` to `StandardSchemaV1` so v1's `completable(z.string(), fn)` continues to work.

packages/core/src/index.ts

@@ -15,6 +15,7 @@ export * from './types/index.js';
 export * from './util/inMemory.js';
 export * from './util/schema.js';
 export * from './util/standardSchema.js';
+export * from './util/zodCompat.js';
 
 // experimental exports
 export * from './experimental/index.js';

packages/core/src/util/standardSchema.ts

@@ -6,8 +6,6 @@
 
 /* eslint-disable @typescript-eslint/no-namespace */
 
-import * as z from 'zod/v4';
-
 // Standard Schema interfaces — vendored from https://standardschema.dev (spec v1, Jan 2025)
 
 export interface StandardTypedV1<Input = unknown, Output = Input> {
@@ -138,45 +136,6 @@ export function isStandardSchemaWithJSON(schema: unknown): schema is StandardSch
     return isStandardJSONSchema(schema) && isStandardSchema(schema);
 }
 
-function isZodSchema(v: unknown): v is z.ZodType {
-    if (typeof v !== 'object' || v === null) return false;
-    if ('_def' in v) return true;
-    return isStandardSchema(v) && (v as StandardSchemaV1)['~standard'].vendor === 'zod';
-}
-
-/**
- * Detects a "raw shape" — a plain object whose values are Zod field schemas,
- * e.g. `{ name: z.string() }`. Powers the auto-wrap in
- * {@linkcode normalizeRawShapeSchema}, which wraps with `z.object()`, so only
- * Zod values are supported.
- *
- * @internal
- */
-export function isZodRawShape(obj: unknown): obj is Record<string, z.ZodType> {
-    if (typeof obj !== 'object' || obj === null) return false;
-    if (isStandardSchema(obj)) return false;
-    // [].every() is true, so an empty object is a valid raw shape (matches v1).
-    return Object.values(obj).every(v => isZodSchema(v));
-}
-
-/**
- * Accepts either a {@linkcode StandardSchemaWithJSON} or a raw Zod shape
- * `{ field: z.string() }` and returns a {@linkcode StandardSchemaWithJSON}.
- * Raw shapes are wrapped with `z.object()` so the rest of the pipeline sees a
- * uniform schema type; already-wrapped schemas pass through unchanged.
- *
- * @internal
- */
-export function normalizeRawShapeSchema(
-    schema: StandardSchemaWithJSON | Record<string, z.ZodType> | undefined
-): StandardSchemaWithJSON | undefined {
-    if (schema === undefined) return undefined;
-    if (isZodRawShape(schema)) {
-        return z.object(schema) as StandardSchemaWithJSON;
-    }
-    return schema;
-}
-
 // JSON Schema conversion
 
 /**

packages/core/src/util/zodCompat.ts

@@ -0,0 +1,54 @@
+/**
+ * Zod-specific helpers for the v1-compat raw-shape shorthand on
+ * `registerTool`/`registerPrompt`. Kept separate from `standardSchema.ts` so
+ * that file stays library-agnostic per the Standard Schema spec.
+ */
+
+import * as z from 'zod/v4';
+
+import type { StandardSchemaV1, StandardSchemaWithJSON } from './standardSchema.js';
+import { isStandardSchema } from './standardSchema.js';
+
+function isZodSchema(v: unknown): v is z.ZodType {
+    if (typeof v !== 'object' || v === null) return false;
+    if ('_def' in v) return true;
+    return isStandardSchema(v) && (v as StandardSchemaV1)['~standard'].vendor === 'zod';
+}
+
+/**
+ * Detects a "raw shape" — a plain object whose values are Zod field schemas,
+ * e.g. `{ name: z.string() }`. Powers the auto-wrap in
+ * {@linkcode normalizeRawShapeSchema}, which wraps with `z.object()`, so only
+ * Zod values are supported.
+ *
+ * @internal
+ */
+export function isZodRawShape(obj: unknown): obj is Record<string, z.ZodType> {
+    if (typeof obj !== 'object' || obj === null) return false;
+    if (isStandardSchema(obj)) return false;
+    // [].every() is true, so an empty object is a valid raw shape (matches v1).
+    return Object.values(obj).every(v => isZodSchema(v));
+}
+
+/**
+ * Accepts either a {@linkcode StandardSchemaWithJSON} or a raw Zod shape
+ * `{ field: z.string() }` and returns a {@linkcode StandardSchemaWithJSON}.
+ * Raw shapes are wrapped with `z.object()` so the rest of the pipeline sees a
+ * uniform schema type; already-wrapped schemas pass through unchanged.
+ *
+ * @internal
+ */
+export function normalizeRawShapeSchema(
+    schema: StandardSchemaWithJSON | Record<string, z.ZodType> | undefined
+): StandardSchemaWithJSON | undefined {
+    if (schema === undefined) return undefined;
+    if (isZodRawShape(schema)) {
+        return z.object(schema) as StandardSchemaWithJSON;
+    }
+    if (!isStandardSchema(schema)) {
+        throw new TypeError(
+            'inputSchema/outputSchema/argsSchema must be a Standard Schema (e.g. z.object({...})) or a raw Zod shape ({ field: z.string() }).'
+        );
+    }
+    return schema;
+}

packages/core/test/util/standardSchema.test.ts

@@ -1,6 +1,7 @@
 import * as z from 'zod/v4';
 
-import { isZodRawShape, normalizeRawShapeSchema, standardSchemaToJsonSchema } from '../../src/util/standardSchema.js';
+import { standardSchemaToJsonSchema } from '../../src/util/standardSchema.js';
+import { isZodRawShape, normalizeRawShapeSchema } from '../../src/util/zodCompat.js';
 
 describe('isZodRawShape', () => {
     test('treats empty object as a raw shape (matches v1)', () => {
@@ -31,6 +32,9 @@ describe('normalizeRawShapeSchema', () => {
     test('returns undefined for undefined input', () => {
         expect(normalizeRawShapeSchema(undefined)).toBeUndefined();
     });
+    test('throws TypeError for an invalid object that is neither raw shape nor Standard Schema', () => {
+        expect(() => normalizeRawShapeSchema({ a: 'not a zod schema' } as never)).toThrow(TypeError);
+    });
 });
 
 describe('standardSchemaToJsonSchema', () => {

packages/server/src/server/mcp.ts

@@ -1118,7 +1118,7 @@ export class ResourceTemplate {
 export type ZodRawShape = Record<string, z.ZodType>;
 
 /** Infers the parsed-output type of a {@linkcode ZodRawShape}. */
-export type InferRawShape<S extends ZodRawShape> = { [K in keyof S]: z.output<S[K]> };
+export type InferRawShape<S extends ZodRawShape> = z.infer<z.ZodObject<S>>;
 
 /** {@linkcode ToolCallback} variant used when `inputSchema` is a {@linkcode ZodRawShape}. */
 export type LegacyToolCallback<Args extends ZodRawShape | undefined> = Args extends ZodRawShape

packages/server/test/server/mcp.compat.test.ts

@@ -1,8 +1,9 @@
 import type { JSONRPCMessage } from '@modelcontextprotocol/core';
 import { InMemoryTransport, isStandardSchema, LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/core';
-import { describe, expect, it, vi } from 'vitest';
+import { describe, expect, expectTypeOf, it, vi } from 'vitest';
 import * as z from 'zod/v4';
 import { McpServer } from '../../src/index.js';
+import type { InferRawShape } from '../../src/server/mcp.js';
 import { completable } from '../../src/server/completable.js';
 
 describe('registerTool/registerPrompt accept raw Zod shape (auto-wrapped)', () => {
@@ -119,3 +120,10 @@ describe('registerTool/registerPrompt accept raw Zod shape (auto-wrapped)', () =
         await server.close();
     });
 });
+
+describe('InferRawShape', () => {
+    it('preserves optionality from .optional() as ?: keys', () => {
+        type S = InferRawShape<{ a: z.ZodString; b: z.ZodOptional<z.ZodString> }>;
+        expectTypeOf<S>().toEqualTypeOf<{ a: string; b?: string | undefined }>();
+    });
+});