modelcontextprotocol/php-sdk
Watch
1
0
Fork
You've already forked php-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[Schema][Server] Close the 2025-11-25 schema gaps and add the 2026-07-28 surface (#421)

Browse source 
* [Schema][Server] Close the 2025-11-25 schema gaps and add the 2026-07-28 surface

Ports the type definitions this SDK still misses outside of sampling tool use,
which #409 and #420 already cover. Every addition is optional and defaults to
current behaviour, so a connection negotiated on an older revision is
unaffected.

From 2025-11-25, elicitation gains modes. ElicitationMode splits `form` —
build a form from the requested schema — from `url`, which sends the user out
of band and returns only the accept/decline/cancel outcome. That is why
requestedSchema becomes optional and `url` appears beside it.
ClientCapabilities learns the matching sub-capabilities, where an
`elicitation` naming no mode declares form, the only shape that existed
before. Icon gains `theme` from the same revision, and Implementation gains
the `title` BaseMetadata has carried since 2025-06-18.

From 2026-07-28, schemas loosen where the revision loosens them: SEP-2106
drops the object-only restriction, so Tool::outputSchema may describe any JSON
value and CallToolResult::structuredContent follows.

The same revision defines three error codes (-32020 header mismatch, -32021
missing required client capability, -32022 unsupported protocol version).
ProtocolVersionMiddleware switches to the last of them, so a rejected version
carries the supported set as structured data the client can retry from rather
than only as prose.

* [Schema] Reject what the 2026-07-28 types cannot represent

`Implementation::title` reached the typed constructor unchecked, so malformed
wire data raised a TypeError instead of InvalidArgumentException.

`ToolUseContent::input` accepted a list and serialized it as a JSON array,
where the protocol requires an object. The empty array stays exempt: it is
also an empty map and still emits `{}`.

`ToolChoice` and `ElicitRequest` read their mode with isset(), which is false
for an explicit null, so `{"mode": null}` silently became the default instead
of being rejected. Both use array_key_exists() now, letting the existing type
check refuse null.

* [Client][Server] Advertise the implementation title through both builders

`Implementation::title` could be parsed but never sent: neither
`Client\Builder::setClientInfo()` nor `Server\Builder::setServerInfo()`
accepted one, so every SDK user emitted null.

Both gain a trailing optional `$title`. On the server it sits where the
Implementation constructor already puts it, so existing positional calls keep
their meaning; the client builder forwards it by name, leaving the icons and
websiteUrl slots defaulted.

* [Schema] Serialize every non-null structuredContent

The object-only hydration guard was never that: `!is_array()` admitted
`[1, 2, 3]` and `[]`, which serialize to JSON arrays, while rejecting the
scalars 2026-07-28 permits. The truthiness emission gate was backwards in the
same way — it dropped `[]`, `0`, `false` and `""`, yet emitted lists, strings
and an empty stdClass.

Hydration now accepts any JSON value, and `null` alone means absent, matching
`ToolResultContent` which already carries this field that way. Which values a
given revision permits is a question for version-aware serialization, which
results cannot answer yet.

* [Schema][Server] Make url elicitation reachable

`ElicitRequest::forUrl()` built a request no SDK user could send: the only
public gateway method always constructed form mode from an ElicitationSchema,
and `request()` is private.

`elicitUrl()` joins `elicit()`, and both funnel through one send path that
hydrates the result with the request's own mode. Without that, a url-mode
accept — contentless by design — threw, because ElicitResult requires content
whenever the action is accept. The result carries no discriminator of its own,
so the mode has to come from the request it answers.

`supportsElicitationUrl()` reports whether the client named the mode, reusing
the sub-capability reader the sampling checks already use.

* [Schema] Add CHANGELOG entry for the 2026-07-28 surface

* [Capability][Schema][Server] Carry the widened structuredContent end to end

Review follow-up on the SEP-2106 widening, which stopped at the type.

`ToolReference::extractStructuredContent()` returned `?array`, so a tool
declaring a scalar `outputSchema` had its result dropped and logged as
unsendable. It returns `mixed` now and keeps a scalar — but only from
2026-07-28 on, and only when the tool declared an outputSchema: without one
the value is already carried in `content`, and advertising it twice is not an
improvement.

`CallToolHandler` only warned about list-shaped `structuredContent` on a
self-built `CallToolResult`, so a scalar reached revisions that require an
object unremarked. The check is on the shape now, not on the list case alone.

`ElicitResult` retained a `content` the spec says is absent from url-mode
results, leaving a malformed response indistinguishable from a valid one.

`Tool::jsonSerialize()` emitted the empty root schema as `[]`, which is not a
schema at all. Sub-schemas already had this treatment.
This commit is contained in:
Christopher Hertel 2026-08-17 23:09:39 +02:00 • committed by GitHub
commit f84d8f5aa9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 1205 additions and 91 deletions
Download patch file Download diff file Expand all files Collapse all files

79
src/Server/ClientGateway.php
View file

@ -56,9 +56,9 @@ use Mcp\Server\Session\SessionInterface;
* $client->notify(new ProgressNotification("Starting analysis..."));
*
* // Request LLM sampling from client
* $response = $client->request(new SamplingRequest($text));
* $result = $client->sample($text);
*
* return $response->content->text;
* return $result->content->text;
* }
* ```
*
@ -176,7 +176,7 @@ class ClientGateway
}
/**
* Convenience method for elicitation requests.
* Convenience method for form-mode elicitation requests.
*
* Requests additional information from the user via the client. The user can
* accept (providing the requested data), decline, or cancel the request.
@ -191,15 +191,28 @@ class ClientGateway
*/
public function elicit(string $message, ElicitationSchema $requestedSchema, int $timeout = 120): ElicitResult
{
$request = new ElicitRequest($message, $requestedSchema);
return $this->sendElicitation(ElicitRequest::forForm($message, $requestedSchema), $timeout);
}
$response = $this->request($request, $timeout);
if ($response instanceof Error) {
throw new ClientException($response);
/**
* Convenience method for url-mode elicitation requests.
*
* Sends the user to $url to complete the interaction out of band — an OAuth
* consent screen, a checkout, a form hosted elsewhere. The result carries only
* the user's action; unlike form mode there is no content to read back, so
* whatever the user did there has to be picked up through the URL's own channel.
*
* @throws ClientException if the client request results in an error message
* @throws InvalidArgumentException if the client did not declare url-mode elicitation
*/
public function elicitUrl(string $message, string $url, int $timeout = 120): ElicitResult
{
// URL mode only exists from 2025-11-25 on, and only for clients declaring it
if (!$this->supportsElicitationUrl()) {
throw new InvalidArgumentException('The client did not declare the "elicitation.url" capability, so it cannot be sent a url-mode elicitation.');
}
return ElicitResult::fromArray($response->result);
return $this->sendElicitation(ElicitRequest::forUrl($message, $url), $timeout);
}
/**
@ -291,7 +304,7 @@ class ClientGateway
*/
public function supportsSamplingTools(): bool
{
return $this->hasSamplingSubCapability('tools');
return $this->hasSubCapability('sampling', 'tools');
}
/**
@ -304,20 +317,52 @@ class ClientGateway
*/
public function supportsSamplingContext(): bool
{
return $this->hasSamplingSubCapability('context');
return $this->hasSubCapability('sampling', 'context');
}
private function hasSamplingSubCapability(string $name): bool
/**
* Check if the connected client supports url-mode elicitation.
*
* An `elicitation` capability naming no mode declares form mode — the only shape
* that existed before URL elicitation — so url mode has to be named explicitly.
*
* @return bool True if the client supports url-mode elicitation, false otherwise
*/
public function supportsElicitationUrl(): bool
{
return $this->hasSubCapability('elicitation', 'url');
}
/**
* Sub-capabilities are declared by the presence of a (possibly empty) object, so
* only the key matters — not whatever it holds. The value arrives as an object on
* a live session and as an array once the session has round-tripped through JSON,
* hence both shapes.
*/
private function hasSubCapability(string $capability, string $name): bool
{
$capabilities = (array) $this->session->get('client_capabilities', []);
$sampling = $capabilities['sampling'] ?? null;
$declared = $capabilities[$capability] ?? null;
if (!\is_array($sampling) && !\is_object($sampling)) {
return false;
if (\is_array($declared)) {
return \array_key_exists($name, $declared);
}
// MCP spec: capability presence indicates support (value is typically {} or [])
return \array_key_exists($name, (array) $sampling);
return \is_object($declared) && property_exists($declared, $name);
}
/**
* @throws ClientException if the client request results in an error message
*/
private function sendElicitation(ElicitRequest $request, int $timeout): ElicitResult
{
$response = $this->request($request, $timeout);
if ($response instanceof Error) {
throw new ClientException($response);
}
return ElicitResult::fromArray($response->result, $request->mode);
}
/**