server-sdk-py: a wrong-typed tool argument reaches the caller as raw pydantic text, outside the error contract

Open
#2,012 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
30/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
python

Research direction

Start in error_contract.py and read how ErrorContractMiddleware wraps call_next, then check FastMCP 4.0 and the newest release for which exception its argument validation raises and whether that surfaces inside the middleware. Run the existing error-contract tests on both protocol eras to see the current shape of a flagged result. The first deliverable is a decision on the three options; only under option 2 do you map the failure to bad_input with a host-safe message, add tests on both eras, and write the paragraph in server-sdk/errors.

Written by the indexing model from the issue text.

Description

needs-triage

Problem

When a tool is called with an argument of the wrong type (for example limit="abc" for an int), FastMCP rejects the call during its own signature validation, before the tool body or any middleware-wrapped handler runs. The caller receives a flagged result whose text is pydantic's validation message, including input_value=..., and no structuredContent.

So on a server that uses add_error_contract, this one failure kind:

  • carries no code, so a host cannot classify it as bad_input;
  • echoes the caller's input and pydantic's internal wording, which the contract otherwise keeps out of messages;
  • is not counted in service_errors_total.

Every server built on the SDK has this path; it is not specific to one server.

Question to settle first

Should the SDK own this? Options:

  1. Leave it to FastMCP. It is FastMCP's validation and its message; the result is flagged as an error, which is the part a host relies on most.
  2. Have ErrorContractMiddleware recognise FastMCP's argument-validation failure and return bad_input with a host-safe message that names the argument and the expected type, without the input value.
  3. Raise it upstream as a FastMCP request for a structured validation error.

Option 2 depends on how FastMCP surfaces the failure to a middleware (which exception type, and whether it is raised inside call_next), which needs checking against FastMCP 4.0 and the newest release before choosing.

Scope if option 2

error_contract.py, tests on both protocol eras, and a paragraph in the docs page server-sdk/errors.

Dominant language
TypeScript
Stars
23
Forks
15
Avg merge
4h 28m
Merged PRs (30d)
209

Getting set up

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.

More from NimbleBrainInc/nimblebrain

All issues in NimbleBrainInc/nimblebrain

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.