modelcontextprotocol / modelcontextprotocol/typescript-sdk

Consider type coercion for tool arguments

Open
#1,361 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement needs decision P3
Dominant language
TypeScript
Stars
13.4k
Forks
2.2k
Avg merge
3d 15h
Merged PRs (30d)
4

Description

Problem

Models occasionally send tool arguments with incorrect JSON types - for example, numbers serialized as strings ({"thoughtNumber": "1"} instead of {"thoughtNumber": 1}). This causes Zod validation to reject otherwise valid requests.

This issue affects many MCP servers. For example, modelcontextprotocol/servers#2812 added a specific workaround to one part of the sequential-thinking server, but the maintainers noted this feels like the wrong layer to fix it.

The "proper" fix is probably smarter models, or as a consistent layer in the SDKs. This would avoid server authors either having to implement ad-hoc coercion logic OR suffer from these problems.

Proposal

The SDK could provide type coercion for tool arguments, either:

  1. Built-in coercion - automatically coerce string→number, string→boolean etc. when the schema expects a different primitive type (e.g. similar to https://ajv.js.org/coercion.html)
  2. Composable helper - export a coerceToolArgs(schema, args) utility that servers can use
  3. Documentation - guidance on how to handle this with Zod's .coerce or .preprocess (but doing so safely so that e.g. "thing" doesn't become true when coerced to bool)

Example

// Current: fails validation
const args1 = { thoughtNumber: "1" }  // model sent number string
const args2 = { thoughtNumber: "one" }  // model sent string
const schema = z.object({ thoughtNumber: z.number() })
schema.parse(args1)  // ZodError: Expected number, received string
schema.parse(args2)  // ZodError: Expected number, received string

// With coercion: works
const coercedSchema = z.object({ thoughtNumber: z.coerce.number() })
coercedSchema.parse(args1)  // { thoughtNumber: 1 }
coercedSchema.parse(args2)  // ZodError: Expected number, received string

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No file or test is named. Start by locating the TypeScript SDK path that validates tool arguments and review how Zod schemas are handled there. Compare built-in coercion, a composable helper, and documentation guidance; done means the selected approach is defined with safe behavior and appropriate coverage.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.