[Server] Answer arguments the input schema refuses with an `isError` result from revision 2025-11-25 on
Mantenedores costumam responder em até 1 dia
Avaliação
- Dificuldade
- 3/5
- Tempo estimado
- 1-2 dias
- Facilidade para iniciantes
- 25/100
Direção de pesquisa
Start in src/Server/Handler/Request/CallToolHandler.php, where schema validation runs before the tool and returns Error::forInvalidParams(); the ToolCallException branch and validateStructuredContent() show how an isError CallToolResult is built. The change is gated on the negotiated protocol revision, so check how the session version is available there and cover both 2025-06-18 and 2025-11-25 in tests. Done when a schema mismatch on 2025-11-25 returns an isError result and older revisions still return -32602. A pull request (#764) is already open against this issue, so coordinate with it first.
Escrita pelo modelo de indexação a partir do texto da issue.
Descrição
Description
CallToolHandler validates the arguments of tools/call against the tool's input schema before the tool runs, and answers a mismatch with the JSON-RPC error -32602 (Error::forInvalidParams(), with the validation errors in data).
I know this is the documented behaviour: docs/servers/schemas.md ("Argument Validation") shows that exact error, and the 0.10.0 changelog says "arguments that don't fit are answered with -32602". It also matches the 2025-06-18 revision, whose "Error Handling" lists "Invalid arguments" under Protocol Errors.
The specification moved that case in 2025-11-25, though. "Error Handling" of Tools now lists "Input validation errors (e.g., date in wrong format, value out of range)" under Tool Execution Errors, reported in the result with isError: true, and keeps only unknown tools, malformed requests and server errors as protocol errors. It gives the reason: tool execution errors "contain actionable feedback that language models can use to self-correct and retry with adjusted parameters", and clients SHOULD pass them to the model, while they only MAY pass protocol errors. The 2026-07-28 text keeps it that way.
So on a session that negotiated 2025-11-25, the same kind of mistake by a model has two outcomes:
- a value the tool refuses (
ToolCallException) comes back as a result withisError: true; - a value the schema refuses (a pattern, an enum, a range, a missing property) comes back as a protocol error, and whether the model ever reads "String does not match the required pattern" is up to the client.
#515 made the same choice for the other direction: an output that does not match outputSchema is answered as an isError result so that the model sees what went wrong.
I met it on the MCP server of a card game: a card that exists but is not legal comes back as a refusal the model can read, with the legal cards, while a card written in lower case comes back as a protocol error.
Versions
mcp/sdk v0.10.0, PHP 8.5.12. src/Server/Handler/Request/CallToolHandler.php is the same on main (7155eaee). Also seen on v0.9.0.
How to reproduce
<?php
require __DIR__.'/vendor/autoload.php';
use Mcp\Server\Capability\Attribute\Schema;
use Mcp\Server\Exception\ToolCallException;
use Mcp\Server\Server;
use Mcp\Server\Transport\StdioTransport;
final class Letters
{
public function shout(#[Schema(pattern: '^[A-Z]$')] string $letter): string
{
if ('Z' === $letter) {
throw new ToolCallException('Z is not allowed today, pick another capital letter.');
}
return $letter.'!';
}
}
Server::builder()
->setServerInfo('letters', '1.0.0')
->addTool([Letters::class, 'shout'], 'shout')
->build()
->run(new StdioTransport());
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"repro","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"shout","arguments":{"letter":"Z"}}}' \
'{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"shout","arguments":{"letter":"a"}}}' \
| php repro.php
Refused by the tool (id 2):
{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"Z is not allowed today, pick another capital letter."}],"isError":true}}
Refused by the schema (id 3):
{"jsonrpc":"2.0","id":3,"error":{"code":-32602,"message":"Invalid parameters for tool 'shout': Property '\/letter': String does not match the required pattern: `^[A-Z]$`.","data":{"validation_errors":[{"pointer":"\/letter","keyword":"pattern","message":"String does not match the required pattern: `^[A-Z]$`."}]}}}
Expected
On a session at 2025-11-25 or later, a result the model can read for id 3:
{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Invalid parameters for tool 'shout': Property '\/letter': String does not match the required pattern: `^[A-Z]$`."}],"isError":true}}
Possible solution
In CallToolHandler, when the schema validation fails and the negotiated revision is 2025-11-25 or later, return new Response($request->getId(), CallToolResult::error([new TextContent($summaryMessage)])), as the ToolCallException branch and validateStructuredContent() already do. Sessions on 2025-06-18 and before keep -32602, as their revision says; an unknown tool and a request that is not a valid CallToolRequest stay protocol errors on every revision.
Was -32602 kept on purpose for the newer revisions? I found no note on it in the changelog or around the validation block. If the change is welcome I can send a pull request, with the docs page and a [BC Break] changelog entry.
- Linguagem predominante
- PHP
- Estrelas
- 1.7k
- Forks
- 206
- Merge médio
- 1d 19h
- PRs com merge (30d)
- 100
Preparar o ambiente
- Sem Dockerfile nem arquivo Docker Compose
- Sem modelo de pull request
- Ler o guia de contribuição
Primeiros passos
- Leia a issue inteira e depois o guia de contribuição do projeto.
- Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
- Faça um fork do repositório e trabalhe em uma branch.
- Abra um pull request que referencie o número da issue.
Mais de modelcontextprotocol/php-sdk
-
[Client] `Builder::addRequestHandler()` rejects the SDK's own handlers under PHPStanTalvez já em andamento @xixi-box assumiu hoje. Aberta
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 68/100
modelcontextprotocol/php-sdk#768 ·
Mantenedores costumam responder em até 1 dia
-
[Server] Handler type uses bare Closure, hard to decorate RegistryInterface under strict PHPStanAbertaServer
Dificuldade 1/5 Menos de uma hora Facilidade para iniciantes 78/100
modelcontextprotocol/php-sdk#468 · 3 comentários ·
Mantenedores costumam responder em até 1 dia
-
[Client] `callTool()` cannot defer `input_required` or send a later retry (MRTR)Talvez já em andamento @xixi-box assumiu hoje. Aberta
Dificuldade 4/5 3-5 dias Facilidade para iniciantes 30/100
modelcontextprotocol/php-sdk#767 ·
Mantenedores costumam responder em até 1 dia
-
Dificuldade 4/5 3-5 dias Facilidade para iniciantes 47/100
modelcontextprotocol/php-sdk#757 ·
Mantenedores costumam responder em até 1 dia
-
[Server] A `float $x = INF` default makes `tools/list` fail for all toolsTalvez já em andamento @andre-schade assumiu há 2 dias. Aberta
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 25/100
modelcontextprotocol/php-sdk#756 ·
Mantenedores costumam responder em até 1 dia
Todas as issues de modelcontextprotocol/php-sdk
Issues semelhantes
-
Change: check an identifier filter the same way in every tool - the order of somcp_search_ordersAbertaconsistency enhancement Orders
Dificuldade 1/5 Menos de uma hora Facilidade para iniciantes 88/100
novalo-dev/Prestashop-MCP-Server#343 ·
Mantenedores costumam responder em até 1 dia
-
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 72/100
Mantenedores costumam responder em até 1 dia
-
claude
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 72/100
sprain/sprainocchio#45 ·
Mantenedores costumam responder em até 1 dia
-
sync-en
Dificuldade 1/5 Menos de uma hora Facilidade para iniciantes 85/100
Mantenedores costumam responder em até 1 dia
-
sync-en
Dificuldade 1/5 Menos de uma hora Facilidade para iniciantes 85/100
Mantenedores costumam responder em até 1 dia