Merge branch 'main' into fix/rpc-error-message-prefix-v2

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. For raw JSON Schema, wrap with `fromJsonSchema(schema, validator)` from `@modelcontextprotocol/core`. 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,11 +240,23 @@ 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 }) => { ... });
+
+// Raw JSON Schema via fromJsonSchema
+import { fromJsonSchema, AjvJsonSchemaValidator } from '@modelcontextprotocol/core';
+server.registerTool('greet', {
+  inputSchema: fromJsonSchema({ type: 'object', properties: { name: { type: 'string' } } }, new AjvJsonSchemaValidator())
+}, handler);
+
 // For tools with no parameters, use z.object({})
 server.registerTool('ping', {
   inputSchema: z.object({})
@@ -256,6 +268,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()`,

examples/server/package.json

@@ -34,14 +34,17 @@
     "dependencies": {
         "@hono/node-server": "catalog:runtimeServerOnly",
         "@modelcontextprotocol/examples-shared": "workspace:^",
-        "@modelcontextprotocol/node": "workspace:^",
-        "@modelcontextprotocol/server": "workspace:^",
         "@modelcontextprotocol/express": "workspace:^",
         "@modelcontextprotocol/hono": "workspace:^",
+        "@modelcontextprotocol/node": "workspace:^",
+        "@modelcontextprotocol/server": "workspace:^",
+        "@valibot/to-json-schema": "catalog:devTools",
+        "arktype": "catalog:devTools",
         "better-auth": "^1.4.17",
         "cors": "catalog:runtimeServerOnly",
         "express": "catalog:runtimeServerOnly",
         "hono": "catalog:runtimeServerOnly",
+        "valibot": "catalog:devTools",
         "zod": "catalog:runtimeShared"
     },
     "devDependencies": {

examples/server/src/arktypeExample.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * Minimal MCP server using ArkType for schema validation.
+ * ArkType implements the Standard Schema spec with built-in JSON Schema conversion.
+ */
+
+import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import { type } from 'arktype';
+
+const server = new McpServer({
+    name: 'arktype-example',
+    version: '1.0.0'
+});
+
+// Register a tool with ArkType schema
+server.registerTool(
+    'greet',
+    {
+        description: 'Generate a greeting',
+        inputSchema: type({ name: 'string' })
+    },
+    async ({ name }) => ({
+        content: [{ type: 'text', text: `Hello, ${name}!` }]
+    })
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

examples/server/src/valibotExample.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Minimal MCP server using Valibot for schema validation.
+ * Use toStandardJsonSchema() from @valibot/to-json-schema to create
+ * StandardJSONSchemaV1-compliant schemas.
+ */
+
+import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import { toStandardJsonSchema } from '@valibot/to-json-schema';
+import * as v from 'valibot';
+
+const server = new McpServer({
+    name: 'valibot-example',
+    version: '1.0.0'
+});
+
+// Register a tool with Valibot schema
+server.registerTool(
+    'greet',
+    {
+        description: 'Generate a greeting',
+        inputSchema: toStandardJsonSchema(v.object({ name: v.string() }))
+    },
+    async ({ name }) => ({
+        content: [{ type: 'text', text: `Hello, ${name}!` }]
+    })
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

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

@@ -12,11 +12,13 @@ export * from './shared/uriTemplate.js';
 export * from './types/types.js';
 export * from './util/inMemory.js';
 export * from './util/schema.js';
+export * from './util/standardSchema.js';
 
 // experimental exports
 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

@@ -1,34 +1,25 @@
+/**
+ * Internal Zod schema utilities for protocol handling.
+ * These are used internally by the SDK for protocol message validation.
+ */
+
 import * as z from 'zod/v4';
 
 /**
  * Base type for any Zod schema.
- * This is the canonical type to use when accepting user-provided schemas.
  */
 export type AnySchema = z.core.$ZodType;
 
 /**
- * A Zod schema for objects specifically (not unions).
- * Use this when you need to constrain to ZodObject schemas.
+ * A Zod schema for objects specifically.
  */
 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.
@@ -39,56 +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).
- * Uses the public .type property which works in both zod/v4 and zod/v4/mini.
- */
-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.
- * Uses the public .def.innerType property which works in both zod/v4 and zod/v4/mini.
- */
-export function unwrapOptionalSchema(schema: AnySchema): AnySchema {
-    if (!isOptionalSchema(schema)) {
-        return schema;
-    }
-    const candidate = schema as { def?: { innerType?: AnySchema } };
-    return candidate.def?.innerType ?? schema;
-}