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

[Capability] Harden structuredContent extraction (#417)

Browse source 
* Address review feedback on resource_link

Three follow-ups from review of the resource_link work:

* PromptResultFormatter: add a regression test proving the optional
  fields of a typed resource_link block (title, description, mimeType,
  size, annotations, _meta) survive formatting. The delegation to
  ResourceLink::fromArray() already landed while rebasing onto the
  PromptResultFormatter refactor, but the existing test only supplied
  uri/name and so could not catch a reintroduced field drop.

* ResourceLink::fromArray(): validate optional fields consistently, the
  way the equivalent ResourceDefinition::fromArray() already does.
  description, mimeType and size now raise InvalidArgumentException
  instead of surfacing a TypeError (or silently coercing, for size's
  (int) cast); annotations goes through Annotations::tryFromArray(),
  which carries the is_array() guard that icons already had; icons uses
  Icon::listFromArray() so a non-array entry is reported in context.

* ToolReference::extractStructuredContent(): never emit a list as
  structuredContent. The Content guard added earlier fixed only one
  instance of the real invariant - structuredContent must be a JSON
  object, and a PHP list can never be one. Tool::fromArray() already
  enforces the matching rule by rejecting an outputSchema whose type is
  not "object", so this aligns the runtime path with it. The test
  asserting the opposite for an array-typed outputSchema contradicted
  the phpstan type and the fromArray() check introduced alongside it in
  the same commit, so it is replaced by tests for the two list shapes.

* Apply the structuredContent object rule to object results too

`extractStructuredContent()` guards raw array results against being emitted
as a JSON array, but the object branch handed back whatever `json_decode()`
produced. A `JsonSerializable` returning a list or a scalar slipped straight
through, producing exactly the `structuredContent` the array guard exists to
prevent — and a return value that contradicts the method's own
`array<string, mixed>|null` signature.

Check the decoded value before returning it, and cover the object branch,
which had no tests at all.

* Document structured tool output

`outputSchema` and `structuredContent` were undocumented: the tool return
value docs covered only the `content` side, and the schema generation
section is about tool parameters.

Add a "Structured Output" subsection covering how to declare the schema,
which return values populate `structuredContent`, and why a list has to be
wrapped in a key to get structured output at all.

* Gate structuredContent on the negotiated protocol revision

SEP-2106 (revision 2026-07-28) widens structuredContent to any JSON value;
earlier revisions require an object. Resolve the revision per request and
apply the matching rule, and warn when a declared outputSchema yields none.

* Resolve the protocol revision on RequestContext

Keeps the `_meta`-then-session lookup in one place instead of per handler,
and exposes the negotiated revision to tool handlers.

* Document reading the negotiated revision from RequestContext

* Warn when a self-built CallToolResult carries an invalid structuredContent

Returning a CallToolResult opts out of the extraction rules, so the value is
still sent unchanged — but a JSON array is not valid before SEP-2106.
This commit is contained in:
Christopher Hertel 2026-08-15 04:03:20 +02:00 • committed by GitHub
commit becce29c41
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 616 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

33
tests/Unit/Capability/Formatter/PromptResultFormatterTest.php
View file

@ -55,6 +55,39 @@ class PromptResultFormatterTest extends TestCase
$this->assertSame('a.png', $result[0]->content->name);
}
public function testFormatTypedResourceLinkContentPreservesOptionalFields(): void
{
$result = (new PromptResultFormatter())->format([
[
'role' => 'user',
'content' => [
'type' => 'resource_link',
'uri' => 'file:///a.png',
'name' => 'a.png',
'title' => 'A picture',
'description' => 'The first picture',
'mimeType' => 'image/png',
'size' => 1024,
'annotations' => ['audience' => ['user'], 'priority' => 0.5],
'_meta' => ['origin' => 'test'],
],
],
]);
$content = $result[0]->content;
$this->assertInstanceOf(ResourceLink::class, $content);
$this->assertSame('file:///a.png', $content->uri);
$this->assertSame('a.png', $content->name);
$this->assertSame('A picture', $content->title);
$this->assertSame('The first picture', $content->description);
$this->assertSame('image/png', $content->mimeType);
$this->assertSame(1024, $content->size);
$this->assertNotNull($content->annotations);
$this->assertSame([Role::User], $content->annotations->audience);
$this->assertSame(0.5, $content->annotations->priority);
$this->assertSame(['origin' => 'test'], $content->meta);
}
public function testFormatUserAssistantShorthand(): void
{
$result = (new PromptResultFormatter())->format([