`v2` refactor!: remove Zod schema parameter from public-facing APIs by KKonstantinov · Pull Request #1606 · modelcontextprotocol/typescript-sdk

@KKonstantinov @claude

Remove the Zod result schema argument from Protocol.request(),
BaseContext.mcpReq.send(), Client.callTool(), and
ExperimentalServerTasks.requestStream(). The SDK now resolves
the correct result schema internally based on the method name
via a new getResultSchema() function.

This simplifies the public API surface — callers no longer need
to import and pass result schemas like CallToolResultSchema or
ElicitResultSchema when making requests.

BREAKING CHANGE: Protocol.request(), ctx.mcpReq.send(),
Client.callTool(), and ExperimentalServerTasks.requestStream()
no longer accept a schema parameter. Internal SDK methods use
the new protected _requestWithSchema()/_requestStreamWithSchema()
escape hatches.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

@KKonstantinov @claude

Add type casts and narrowing in example files where code accesses
result.content after client.request() or client.callTool(), since
the return type is now a union that includes CreateTaskResult.
Also fix formatting with prettier.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

@KKonstantinov changed the title refactor!: remove Zod schema parameter from public-facing APIs v2 refactor!: remove Zod schema parameter from public-facing APIs

Mar 1, 2026

@KKonstantinov

@KKonstantinov

@KKonstantinov KKonstantinov added the v2

Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes

label

Mar 2, 2026

@KKonstantinov

mattzcarey

mattzcarey

felixweinberger added a commit that referenced this pull request

Mar 16, 2026
Follow-up to the StandardJSONSchemaV1 feature commit. Completes the
schema-agnostic story by removing the last Zod-locked user-facing
surfaces and cleaning up code the feature orphaned.

- Drop resultSchema from experimental.tasks.getTaskResult() (client
  and server). Returns GetTaskPayloadResult; the schema param was the
  same pattern #1606 removed from callTool. Task result payload is
  polymorphic per spec (matches the original request's result type).
- Delete 7 dead exports from schema.ts. mcp.ts inlined local copies
  of the Zod introspection helpers; parseSchemaAsync/schemaToJson were
  replaced by the StandardSchema equivalents. Down to 4 exports, all
  used by protocol internals.
- Update migration docs to reflect that any Standard Schema library
  works, not just Zod.
- Add changeset.

felixweinberger added a commit that referenced this pull request

Mar 20, 2026
The unwrapOptionalSchema call added in 7eaddba would crash when the
argument name doesn't exist in the schema shape (promptShape?.[name]
yields undefined, isOptionalSchema(undefined) → TypeError). Added
optional chaining to the type check.

Also removed the dead second argument to client.request() throughout
standardSchema.test.ts — post-#1606, request() auto-resolves the schema
from the method name. The Zod schemas were silently ignored.

felixweinberger added a commit that referenced this pull request

Mar 20, 2026
…w 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.

felixweinberger added a commit that referenced this pull request

Mar 20, 2026
…w 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.