refactor: narrow to StandardSchemaWithJSON, add fromJsonSchema, review fixes

Follow-up to the Standard Schema feature. Completes the schema-agnostic
surface and addresses review findings.

Scope completion:
- Narrow registration types (inputSchema/outputSchema/argsSchema) from
  StandardJSONSchemaV1 to StandardSchemaWithJSON — the SDK needs both
  ~standard.validate and ~standard.jsonSchema, so the type should say so.
  validateStandardSchema drops to 11 lines, no branches.
- Drop resultSchema from experimental.tasks.getTaskResult() — same
  pattern #1606 used for callTool. Returns GetTaskPayloadResult.
- Delete 7 dead exports from schema.ts orphaned by the feature.
- Add fromJsonSchema(schema, validator) adapter for raw JSON Schema
  input (TypeBox, hand-written schemas). Wraps as StandardSchemaWithJSON
  using the SDK's existing AJV/cfWorker validators.

Bug fixes:
- Include issue.path in validation error messages (was dropping the
  field path, e.g. "must be a number" instead of "config.retryCount:
  must be a number").
- Unwrap optional schema in handlePromptCompletion — registration
  checked isCompletable after unwrapping, request handler didn't.
  completable(z.string(), cb).optional() registered but silently
  returned empty. Pre-existing on main.
- Null-safe isOptionalSchema so unwrapOptionalSchema(undefined) doesn't
  crash when the arg name doesn't exist in the schema shape.

Docs and tests:
- Migration guides document the removed exports and use z.object()
  consistently.
- standardSchema.test.ts cleaned to v2 request() API (no schema arg;
  auto-resolved from method name).
- Changeset + tests for fromJsonSchema.

Author: felixweinberger

.changeset/support-standard-json-schema.md

@@ -0,0 +1,34 @@
+---
+'@modelcontextprotocol/core': minor
+'@modelcontextprotocol/server': minor
+'@modelcontextprotocol/client': minor
+---
+
+Support Standard Schema for tool and prompt schemas
+
+Tool and prompt registration now accepts any schema library that implements the [Standard Schema spec](https://standardschema.dev/): Zod v4, Valibot, ArkType, and others. `RegisteredTool.inputSchema`, `RegisteredTool.outputSchema`, and `RegisteredPrompt.argsSchema` now use `StandardSchemaWithJSON` (requires both `~standard.validate` and `~standard.jsonSchema`) instead of the Zod-specific `AnySchema` type.
+
+**Zod v4 schemas continue to work unchanged** — Zod v4 implements the required interfaces natively.
+
+```typescript
+import { type } from 'arktype';
+
+server.registerTool('greet', {
+  inputSchema: type({ name: 'string' })
+}, async ({ name }) => ({ content: [{ type: 'text', text: `Hello, ${name}!` }] }));
+```
+
+For raw JSON Schema (e.g. TypeBox output), use the new `fromJsonSchema` adapter:
+
+```typescript
+import { fromJsonSchema, AjvJsonSchemaValidator } from '@modelcontextprotocol/core';
+
+server.registerTool('greet', {
+  inputSchema: fromJsonSchema({ type: 'object', properties: { name: { type: 'string' } } }, new AjvJsonSchemaValidator())
+}, handler);
+```
+
+**Breaking changes:**
+- `experimental.tasks.getTaskResult()` no longer accepts a `resultSchema` parameter. Returns `GetTaskPayloadResult` (a loose `Result`); cast to the expected type at the call site.
+- Removed unused exports from `@modelcontextprotocol/core`: `SchemaInput`, `schemaToJson`, `parseSchemaAsync`, `getSchemaShape`, `getSchemaDescription`, `isOptionalSchema`, `unwrapOptionalSchema`. Use the new `standardSchemaToJsonSchema` and `validateStandardSchema` instead.
+- `completable()` remains Zod-specific (it relies on Zod's `.shape` introspection).

docs/migration-SKILL.md

@@ -209,7 +209,7 @@ if (error instanceof OAuthError && error.code === OAuthErrorCode.InvalidClient)
 
 The variadic `.tool()`, `.prompt()`, `.resource()` methods are removed. Use the `register*` methods with a config object.
 
-**IMPORTANT**: v2 requires full Zod schemas — raw shapes like `{ name: z.string() }` are no longer supported. You must wrap with `z.object()`. This applies to `inputSchema`, `outputSchema`, and `argsSchema`.
+**IMPORTANT**: v2 requires schema objects implementing [Standard Schema](https://standardschema.dev/) — raw shapes like `{ name: z.string() }` are no longer supported. Wrap with `z.object()` (Zod v4), or use ArkType's `type({...})`, or Valibot. Applies to `inputSchema`, `outputSchema`, and `argsSchema`.
 
 ### Tools
 
@@ -279,13 +279,22 @@ Note: the third argument (`metadata`) is required — pass `{}` if no metadata.
 
 ### Schema Migration Quick Reference
 
-| v1 (raw shape) | v2 (Zod schema) |
+| v1 (raw shape) | v2 (Standard Schema object) |
 |----------------|-----------------|
 | `{ name: z.string() }` | `z.object({ name: z.string() })` |
 | `{ count: z.number().optional() }` | `z.object({ count: z.number().optional() })` |
 | `{}` (empty) | `z.object({})` |
 | `undefined` (no schema) | `undefined` or omit the field |
 
+### Removed core exports
+
+| Removed from `@modelcontextprotocol/core` | Replacement |
+|---|---|
+| `schemaToJson(schema)` | `standardSchemaToJsonSchema(schema)` |
+| `parseSchemaAsync(schema, data)` | `validateStandardSchema(schema, data)` |
+| `SchemaInput<T>` | `StandardSchemaWithJSON.InferInput<T>` |
+| `getSchemaShape`, `getSchemaDescription`, `isOptionalSchema`, `unwrapOptionalSchema` | none (internal Zod introspection helpers) |
+
 ## 7. Headers API
 
 Transport constructors and `RequestInfo.headers` now use the Web Standard `Headers` object instead of plain objects.

docs/migration.md

@@ -200,17 +200,17 @@ import * as z from 'zod/v4';
 const server = new McpServer({ name: 'demo', version: '1.0.0' });
 
 // Tool with schema
-server.registerTool('greet', { inputSchema: { name: z.string() } }, async ({ name }) => {
+server.registerTool('greet', { inputSchema: z.object({ name: z.string() }) }, async ({ name }) => {
     return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
 });
 
 // Tool with description
-server.registerTool('greet', { description: 'Greet a user', inputSchema: { name: z.string() } }, async ({ name }) => {
+server.registerTool('greet', { description: 'Greet a user', inputSchema: z.object({ name: z.string() }) }, async ({ name }) => {
     return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
 });
 
 // Prompt
-server.registerPrompt('summarize', { argsSchema: { text: z.string() } }, async ({ text }) => {
+server.registerPrompt('summarize', { argsSchema: z.object({ text: z.string() }) }, async ({ text }) => {
     return { messages: [{ role: 'user', content: { type: 'text', text: `Summarize: ${text}` } }] };
 });
 
@@ -220,9 +220,9 @@ server.registerResource('config', 'config://app', {}, async uri => {
 });
 ```
 
-### Zod schemas required (raw shapes no longer supported)
+### Standard Schema objects required (raw shapes no longer supported)
 
-v2 requires full Zod schemas for `inputSchema` and `argsSchema`. Raw object shapes are no longer accepted.
+v2 requires schema objects implementing the [Standard Schema spec](https://standardschema.dev/) for `inputSchema`, `outputSchema`, and `argsSchema`. Raw object shapes are no longer accepted. Zod v4, ArkType, and Valibot all implement the spec.
 
 **Before (v1):**
 
@@ -240,9 +240,15 @@ server.registerTool('greet', {
 ```typescript
 import * as z from 'zod/v4';
 
-// Must wrap with z.object()
+// Wrap with z.object() (or use any Standard Schema library)
 server.registerTool('greet', {
-  inputSchema: z.object({ name: z.string() })  // full Zod schema
+  inputSchema: z.object({ name: z.string() })
+}, async ({ name }) => { ... });
+
+// ArkType works too
+import { type } from 'arktype';
+server.registerTool('greet', {
+  inputSchema: type({ name: 'string' })
 }, async ({ name }) => { ... });
 
 // For tools with no parameters, use z.object({})
@@ -256,6 +262,15 @@ This applies to:
 - `outputSchema` in `registerTool()`
 - `argsSchema` in `registerPrompt()`
 
+**Removed Zod-specific helpers** from `@modelcontextprotocol/core` (use Standard Schema equivalents):
+
+| Removed | Replacement |
+|---|---|
+| `schemaToJson(schema)` | `standardSchemaToJsonSchema(schema)` |
+| `parseSchemaAsync(schema, data)` | `validateStandardSchema(schema, data)` |
+| `SchemaInput<T>` | `StandardSchemaWithJSON.InferInput<T>` |
+| `getSchemaShape`, `getSchemaDescription`, `isOptionalSchema`, `unwrapOptionalSchema` | No replacement — these are now internal Zod introspection helpers |
+
 ### Host header validation moved
 
 Express-specific middleware (`hostHeaderValidation()`, `localhostHostValidation()`) moved from the server package to `@modelcontextprotocol/express`. The server package now exports framework-agnostic functions instead: `validateHostHeader()`, `localhostAllowedHostnames()`,

packages/client/src/experimental/tasks/client.ts

@@ -6,20 +6,19 @@
  */
 
 import type {
-    AnyObjectSchema,
     CallToolRequest,
     CallToolResult,
     CancelTaskResult,
     CreateTaskResult,
+    GetTaskPayloadResult,
     GetTaskResult,
     ListTasksResult,
     RequestMethod,
     RequestOptions,
     ResponseMessage,
-    ResultTypeMap,
-    SchemaOutput
+    ResultTypeMap
 } from '@modelcontextprotocol/core';
-import { ProtocolError, ProtocolErrorCode } from '@modelcontextprotocol/core';
+import { GetTaskPayloadResultSchema, ProtocolError, ProtocolErrorCode } from '@modelcontextprotocol/core';
 
 import type { Client } from '../../client/client.js';
 
@@ -185,23 +184,22 @@ export class ExperimentalClientTasks {
      * Retrieves the result of a completed task.
      *
      * @param taskId - The task identifier
-     * @param resultSchema - Zod schema for validating the result
      * @param options - Optional request options
-     * @returns The task result
+     * @returns The task result. The payload structure matches the result type of the
+     *   original request (e.g., a `tools/call` task returns a `CallToolResult`).
      *
      * @experimental
      */
-    async getTaskResult<T extends AnyObjectSchema>(taskId: string, resultSchema?: T, options?: RequestOptions): Promise<SchemaOutput<T>> {
-        // Delegate to the client's underlying Protocol method
+    async getTaskResult(taskId: string, options?: RequestOptions): Promise<GetTaskPayloadResult> {
         return (
             this._client as unknown as {
-                getTaskResult: <U extends AnyObjectSchema>(
+                getTaskResult: (
                     params: { taskId: string },
-                    resultSchema?: U,
+                    resultSchema: typeof GetTaskPayloadResultSchema,
                     options?: RequestOptions
-                ) => Promise<SchemaOutput<U>>;
+                ) => Promise<GetTaskPayloadResult>;
             }
-        ).getTaskResult({ taskId }, resultSchema, options);
+        ).getTaskResult({ taskId }, GetTaskPayloadResultSchema, options);
     }
 
     /**

packages/core/src/index.ts

@@ -18,6 +18,7 @@ export * from './util/standardSchema.js';
 export * from './experimental/index.js';
 export * from './validators/ajvProvider.js';
 export * from './validators/cfWorkerProvider.js';
+export * from './validators/fromJsonSchema.js';
 /**
  * JSON Schema validation
  *

packages/core/src/util/schema.ts

@@ -15,23 +15,11 @@ export type AnySchema = z.core.$ZodType;
  */
 export type AnyObjectSchema = z.core.$ZodObject;
 
-/**
- * Extracts the input type from a Zod schema.
- */
-export type SchemaInput<T extends AnySchema> = z.input<T>;
-
 /**
  * Extracts the output type from a Zod schema.
  */
 export type SchemaOutput<T extends AnySchema> = z.output<T>;
 
-/**
- * Converts a Zod schema to JSON Schema.
- */
-export function schemaToJson(schema: AnySchema, options?: { io?: 'input' | 'output' }): Record<string, unknown> {
-    return z.toJSONSchema(schema, options) as Record<string, unknown>;
-}
-
 /**
  * Parses data against a Zod schema (synchronous).
  * Returns a discriminated union with success/error.
@@ -42,54 +30,3 @@ export function parseSchema<T extends AnySchema>(
 ): { success: true; data: z.output<T> } | { success: false; error: z.core.$ZodError } {
     return z.safeParse(schema, data);
 }
-
-/**
- * Parses data against a Zod schema (asynchronous).
- * Returns a discriminated union with success/error.
- */
-export function parseSchemaAsync<T extends AnySchema>(
-    schema: T,
-    data: unknown
-): Promise<{ success: true; data: z.output<T> } | { success: false; error: z.core.$ZodError }> {
-    return z.safeParseAsync(schema, data);
-}
-
-/**
- * Gets the shape of an object schema.
- * Returns undefined if the schema is not an object schema.
- */
-export function getSchemaShape(schema: AnySchema): Record<string, AnySchema> | undefined {
-    const candidate = schema as { shape?: unknown };
-    if (candidate.shape && typeof candidate.shape === 'object') {
-        return candidate.shape as Record<string, AnySchema>;
-    }
-    return undefined;
-}
-
-/**
- * Gets the description from a schema if it has one.
- */
-export function getSchemaDescription(schema: AnySchema): string | undefined {
-    const candidate = schema as { description?: string };
-    return candidate.description;
-}
-
-/**
- * Checks if a schema is optional (accepts undefined).
- */
-export function isOptionalSchema(schema: AnySchema): boolean {
-    const candidate = schema as { type?: string };
-    return candidate.type === 'optional';
-}
-
-/**
- * Unwraps an optional schema to get the inner schema.
- * If the schema is not optional, returns it unchanged.
- */
-export function unwrapOptionalSchema(schema: AnySchema): AnySchema {
-    if (!isOptionalSchema(schema)) {
-        return schema;
-    }
-    const candidate = schema as { def?: { innerType?: AnySchema } };
-    return candidate.def?.innerType ?? schema;
-}

packages/core/src/util/standardSchema.ts

@@ -6,9 +6,7 @@
 
 /* eslint-disable @typescript-eslint/no-namespace */
 
-import type { JsonSchemaType, jsonSchemaValidator } from '../validators/types.js';
-
-// Standard Schema interfaces (from https://standardschema.dev)
+// Standard Schema interfaces — vendored from https://standardschema.dev (spec v1, Jan 2025)
 
 export interface StandardTypedV1<Input = unknown, Output = Input> {
     readonly '~standard': StandardTypedV1.Props<Input, Output>;
@@ -92,11 +90,28 @@ export namespace StandardJSONSchemaV1 {
     export type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
 }
 
-/** Combined interface for schemas with both validation and JSON Schema conversion (e.g., Zod v4). */
+/**
+ * Combined interface for schemas with both validation and JSON Schema conversion —
+ * the intersection of {@linkcode StandardSchemaV1} and {@linkcode StandardJSONSchemaV1}.
+ *
+ * This is the type accepted by `registerTool` / `registerPrompt`. The SDK needs
+ * `~standard.jsonSchema` to advertise the tool's argument shape in `tools/list`, and
+ * `~standard.validate` to check incoming arguments when a `tools/call` arrives.
+ *
+ * Zod v4, ArkType, and Valibot (via `@valibot/to-json-schema`'s `toStandardJsonSchema`)
+ * all implement both interfaces.
+ *
+ * @see https://standardschema.dev/ for the Standard Schema specification
+ */
 export interface StandardSchemaWithJSON<Input = unknown, Output = Input> {
     readonly '~standard': StandardSchemaV1.Props<Input, Output> & StandardJSONSchemaV1.Props<Input, Output>;
 }
 
+export namespace StandardSchemaWithJSON {
+    export type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+    export type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+
 // Type guards
 
 export function isStandardJSONSchema(schema: unknown): schema is StandardJSONSchemaV1 {
@@ -131,35 +146,21 @@ export function standardSchemaToJsonSchema(schema: StandardJSONSchemaV1, io: 'in
 
 export type StandardSchemaValidationResult<T> = { success: true; data: T } | { success: false; error: string };
 
-export async function validateStandardSchema<T extends StandardJSONSchemaV1>(
-    schema: T,
-    data: unknown,
-    jsonSchemaValidatorInstance?: jsonSchemaValidator
-): Promise<StandardSchemaValidationResult<StandardJSONSchemaV1.InferOutput<T>>> {
-    // Use native validation if available
-    if (isStandardSchema(schema)) {
-        const result = await schema['~standard'].validate(data);
-        if (result.issues && result.issues.length > 0) {
-            const errorMessage = result.issues.map((i: StandardSchemaV1.Issue) => i.message).join(', ');
-            return { success: false, error: errorMessage };
-        }
-        return { success: true, data: (result as StandardSchemaV1.SuccessResult<unknown>).value as StandardJSONSchemaV1.InferOutput<T> };
-    }
-
-    // Fall back to JSON Schema validation
-    if (jsonSchemaValidatorInstance) {
-        const jsonSchema = standardSchemaToJsonSchema(schema, 'input');
-        const validator = jsonSchemaValidatorInstance.getValidator<StandardJSONSchemaV1.InferOutput<T>>(jsonSchema as JsonSchemaType);
-        const validationResult = validator(data);
+function formatIssue(issue: StandardSchemaV1.Issue): string {
+    if (!issue.path?.length) return issue.message;
+    const path = issue.path.map(p => String(typeof p === 'object' ? p.key : p)).join('.');
+    return `${path}: ${issue.message}`;
+}
 
-        if (validationResult.valid) {
-            return { success: true, data: validationResult.data };
-        }
-        return { success: false, error: validationResult.errorMessage ?? 'Validation failed' };
+export async function validateStandardSchema<T extends StandardSchemaWithJSON>(
+    schema: T,
+    data: unknown
+): Promise<StandardSchemaValidationResult<StandardSchemaWithJSON.InferOutput<T>>> {
+    const result = await schema['~standard'].validate(data);
+    if (result.issues && result.issues.length > 0) {
+        return { success: false, error: result.issues.map(i => formatIssue(i)).join(', ') };
     }
-
-    // No validation - trust the data
-    return { success: true, data: data as StandardJSONSchemaV1.InferOutput<T> };
+    return { success: true, data: (result as StandardSchemaV1.SuccessResult<unknown>).value as StandardSchemaWithJSON.InferOutput<T> };
 }
 
 // Prompt argument extraction

packages/core/src/validators/fromJsonSchema.examples.ts

@@ -0,0 +1,24 @@
+/**
+ * Type-checked examples for `fromJsonSchema.ts`.
+ *
+ * These examples are synced into JSDoc comments via the sync-snippets script.
+ *
+ * @module
+ */
+
+import { AjvJsonSchemaValidator } from './ajvProvider.js';
+import { fromJsonSchema } from './fromJsonSchema.js';
+
+/**
+ * Example: wrap a raw JSON Schema object for use with registerTool.
+ */
+function fromJsonSchema_basicUsage() {
+    //#region fromJsonSchema_basicUsage
+    const inputSchema = fromJsonSchema<{ name: string }>(
+        { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+        new AjvJsonSchemaValidator()
+    );
+    // Use with server.registerTool('greet', { inputSchema }, handler)
+    //#endregion fromJsonSchema_basicUsage
+    return inputSchema;
+}