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

105
tests/Unit/Server/ClientGatewayTest.php
View file

@ -12,9 +12,18 @@
namespace Mcp\Tests\Unit\Server;
use Mcp\Exception\ClientException;
use Mcp\Exception\InvalidArgumentException;
use Mcp\Schema\ClientCapabilities;
use Mcp\Schema\Elicitation\ElicitationSchema;
use Mcp\Schema\Elicitation\StringSchemaDefinition;
use Mcp\Schema\Enum\ElicitAction;
use Mcp\Schema\Enum\ElicitationMode;
use Mcp\Schema\JsonRpc\Error;
use Mcp\Schema\JsonRpc\Request;
use Mcp\Schema\JsonRpc\Response;
use Mcp\Schema\Request\ElicitRequest;
use Mcp\Schema\Request\ListRootsRequest;
use Mcp\Schema\Result\ElicitResult;
use Mcp\Schema\Result\ListRootsResult;
use Mcp\Server\ClientGateway;
use Mcp\Server\Session\SessionInterface;
@ -63,6 +72,76 @@ final class ClientGatewayTest extends TestCase
$this->assertFalse($gateway->supportsSampling());
}
public function testSupportsSamplingToolsReflectsTheSubCapability(): void
{
$this->assertTrue($this->gatewayFor(['sampling' => ['tools' => []]])->supportsSamplingTools());
$this->assertFalse($this->gatewayFor(['sampling' => []])->supportsSamplingTools());
$this->assertFalse($this->gatewayFor([])->supportsSamplingTools());
}
public function testSupportsSamplingToolsReadsTheObjectShapeToo(): void
{
$capabilities = (new ClientCapabilities(samplingTools: true))->jsonSerialize();
$this->assertTrue($this->gatewayFor((array) $capabilities)->supportsSamplingTools());
}
public function testSupportsElicitationUrlReflectsTheSubCapability(): void
{
$this->assertTrue($this->gatewayFor(['elicitation' => ['url' => []]])->supportsElicitationUrl());
// An `elicitation` naming no mode declares form mode alone.
$this->assertFalse($this->gatewayFor(['elicitation' => []])->supportsElicitationUrl());
$this->assertFalse($this->gatewayFor(['elicitation' => ['form' => []]])->supportsElicitationUrl());
}
public function testElicitUrlSendsAUrlModeRequest(): void
{
$gateway = $this->gatewayFor(['elicitation' => ['url' => []]]);
$request = null;
$result = $this->runInFiber(
static fn (): ElicitResult => $gateway->elicitUrl('Authorize the app', 'https://example.com/consent'),
// A url-mode accept carries no content — the interaction happened out of band.
$this->response(['action' => 'accept']),
ElicitRequest::class,
$request,
);
$this->assertInstanceOf(ElicitRequest::class, $request);
$this->assertSame(ElicitationMode::Url, $request->mode);
$this->assertSame('https://example.com/consent', $request->url);
$this->assertInstanceOf(ElicitResult::class, $result);
$this->assertSame(ElicitAction::Accept, $result->action);
$this->assertNull($result->content);
}
public function testElicitUrlRejectsAClientThatOnlySupportsForms(): void
{
$gateway = $this->gatewayFor(['elicitation' => []]);
$this->expectException(InvalidArgumentException::class);
$this->expectExceptionMessageMatches('/elicitation\.url/');
$gateway->elicitUrl('Authorize the app', 'https://example.com/consent');
}
public function testElicitStillSendsFormMode(): void
{
$gateway = $this->gatewayFor([]);
$request = null;
$result = $this->runInFiber(
static fn (): ElicitResult => $gateway->elicit('Your name?', new ElicitationSchema(['name' => new StringSchemaDefinition('Name')])),
$this->response(['action' => 'accept', 'content' => ['name' => 'Ada']]),
ElicitRequest::class,
$request,
);
$this->assertInstanceOf(ElicitRequest::class, $request);
$this->assertSame(ElicitationMode::Form, $request->mode);
$this->assertSame(['name' => 'Ada'], $result->content);
}
public function testListRootsReturnsRootsFromClient(): void
{
$session = $this->createMock(SessionInterface::class);
@ -98,19 +177,39 @@ final class ClientGatewayTest extends TestCase
}
/**
* Runs the gateway call inside a Fiber, asserts it suspends with a roots/list
* @param array<string, mixed> $capabilities the client capabilities the session reports
*/
private function gatewayFor(array $capabilities): ClientGateway
{
$session = $this->createMock(SessionInterface::class);
$session->method('getId')->willReturn(Uuid::v4());
$session->method('get')->willReturnCallback(
static fn (string $key, mixed $default = null): mixed => 'client_capabilities' === $key ? $capabilities : $default,
);
return new ClientGateway($session);
}
/**
* Runs the gateway call inside a Fiber, asserts it suspends with the expected
* request, then resumes it with the given client response.
*
* @param Response<array<string, mixed>>|Error $response
* @param class-string<Request> $expectedRequest
* @param ?Request $request receives the request the gateway suspended with
*
* @param-out Request $request
*/
private function runInFiber(\Closure $call, Response|Error $response): mixed
private function runInFiber(\Closure $call, Response|Error $response, string $expectedRequest = ListRootsRequest::class, mixed &$request = null): mixed
{
$fiber = new \Fiber($call);
$suspend = $fiber->start();
$this->assertIsArray($suspend);
$this->assertSame('request', $suspend['type']);
$this->assertInstanceOf(ListRootsRequest::class, $suspend['request']);
$this->assertInstanceOf($expectedRequest, $suspend['request']);
$request = $suspend['request'];
$fiber->resume($response);