[Capability] Harden structuredContent extraction (#417)

* 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.

src/Capability/Registry/ToolReference.php

@@ -13,6 +13,7 @@ namespace Mcp\Capability\Registry;
 
 use Mcp\Capability\Formatter\ToolResultFormatter;
 use Mcp\Schema\Content\Content;
+use Mcp\Schema\Enum\ProtocolVersion;
 use Mcp\Schema\Tool;
 
 /**
@@ -59,22 +60,39 @@ class ToolReference extends ElementReference
     /**
      * Extracts structured content from a tool result using the output schema.
      *
-     * @param mixed $toolExecutionResult the raw value returned by the tool's PHP method
+     * What may be sent as `structuredContent` depends on the protocol revision in
+     * use. Up to `2025-11-25` it has to be a JSON object, and `outputSchema` is
+     * restricted to `type: "object"` to match. From `2026-07-28` on (SEP-2106)
+     * `outputSchema` is any JSON Schema 2020-12 and `structuredContent` is any JSON
+     * value conforming to it — a list included.
      *
-     * @return array<string, mixed>|null the structured content, or null if not extractable
+     * @param mixed            $toolExecutionResult the raw value returned by the tool's PHP method
+     * @param ?ProtocolVersion $protocolVersion     revision the result is produced for; defaults to the
+     *                                              newest handshake revision, whose stricter rule is what
+     *                                              every revision reachable through `initialize` requires
+     *
+     * @return array<array-key, mixed>|null the structured content, or null if not extractable
      *
      * @throws \JsonException if JSON encoding fails for non-Content array/object results
      */
-    public function extractStructuredContent(mixed $toolExecutionResult): ?array
+    public function extractStructuredContent(mixed $toolExecutionResult, ?ProtocolVersion $protocolVersion = null): ?array
     {
+        $objectOnly = ($protocolVersion ?? ProtocolVersion::latestHandshake())->requiresObjectStructuredContent();
+
         if (\is_array($toolExecutionResult)) {
+            // A PHP list serializes to a JSON array, which the revisions predating
+            // SEP-2106 do not allow as `structuredContent` — strict clients reject
+            // the whole tool call when one is sent.
+            if ($objectOnly && array_is_list($toolExecutionResult)) {
+                return null;
+            }
+
             foreach ($toolExecutionResult as $item) {
                 if ($item instanceof Content) {
                     // Content items are already reflected in the result's `content`
-                    // array; a raw array holding one or more of them isn't
-                    // structured data and, if it were serialized as-is, could
-                    // produce a `structuredContent` value that isn't a JSON object
-                    // (e.g. a list), which the spec doesn't allow.
+                    // array; an array holding one or more of them isn't structured
+                    // data. This holds in every revision — it is a duplication rule,
+                    // not a shape rule.
                     return null;
                 }
             }
@@ -88,9 +106,23 @@ class ToolReference extends ElementReference
                 \JSON_PRETTY_PRINT | \JSON_UNESCAPED_SLASHES | \JSON_UNESCAPED_UNICODE | \JSON_THROW_ON_ERROR | \JSON_INVALID_UTF8_SUBSTITUTE
             );
 
-            return json_decode(
+            $decoded = json_decode(
                 $jsonResult, true, 512, \JSON_THROW_ON_ERROR
             );
+
+            // A plain object always encodes to a JSON object, but `JsonSerializable`
+            // can hand back anything. A scalar is dropped whatever the revision
+            // allows: `CallToolResult::$structuredContent` is typed `?array` and
+            // cannot carry one.
+            if (!\is_array($decoded)) {
+                return null;
+            }
+
+            if ($objectOnly && array_is_list($decoded)) {
+                return null;
+            }
+
+            return $decoded;
         }
 
         return null;

src/Schema/Content/ResourceLink.php

@@ -84,6 +84,15 @@ class ResourceLink extends Content
         if (isset($data['_meta']) && !\is_array($data['_meta'])) {
             throw new InvalidArgumentException('Invalid "_meta" in ResourceLink data.');
         }
+        if (isset($data['description']) && !\is_string($data['description'])) {
+            throw new InvalidArgumentException('Invalid "description" in ResourceLink data.');
+        }
+        if (isset($data['mimeType']) && !\is_string($data['mimeType'])) {
+            throw new InvalidArgumentException('Invalid "mimeType" in ResourceLink data.');
+        }
+        if (isset($data['size']) && !\is_int($data['size'])) {
+            throw new InvalidArgumentException('Invalid "size" in ResourceLink data; expected an integer.');
+        }
 
         return new self(
             uri: $data['uri'],
@@ -91,9 +100,9 @@ class ResourceLink extends Content
             title: isset($data['title']) && \is_string($data['title']) ? $data['title'] : null,
             description: $data['description'] ?? null,
             mimeType: $data['mimeType'] ?? null,
-            annotations: isset($data['annotations']) ? Annotations::fromArray($data['annotations']) : null,
-            size: isset($data['size']) ? (int) $data['size'] : null,
-            icons: isset($data['icons']) && \is_array($data['icons']) ? array_map(Icon::fromArray(...), $data['icons']) : null,
+            annotations: Annotations::tryFromArray($data['annotations'] ?? null, 'ResourceLink'),
+            size: $data['size'] ?? null,
+            icons: isset($data['icons']) && \is_array($data['icons']) ? Icon::listFromArray($data['icons'], 'ResourceLink') : null,
             meta: $data['_meta'] ?? null,
         );
     }

src/Schema/Enum/ProtocolVersion.php

@@ -101,6 +101,20 @@ enum ProtocolVersion: string
         return $this->isAtLeast(self::FIRST_MODERN_VERSION);
     }
 
+    /**
+     * Whether this revision restricts `structuredContent` to a JSON object.
+     *
+     * SEP-2106, part of {@see self::V2026_07_28}, widened `outputSchema` to any
+     * JSON Schema 2020-12 and `structuredContent` to any JSON value conforming to
+     * it. Up to `2025-11-25` both are restricted to an object.
+     *
+     * @see https://modelcontextprotocol.io/specification/2026-07-28/server/tools#structured-content
+     */
+    public function requiresObjectStructuredContent(): bool
+    {
+        return !$this->isAtLeast(self::V2026_07_28);
+    }
+
     /**
      * Whether this revision is at least as new as $minimum.
      */

src/Server/Handler/Request/CallToolHandler.php

@@ -22,6 +22,7 @@ use Mcp\Schema\JsonRpc\Request;
 use Mcp\Schema\JsonRpc\Response;
 use Mcp\Schema\Request\CallToolRequest;
 use Mcp\Schema\Result\CallToolResult;
+use Mcp\Server\RequestContext;
 use Mcp\Server\Session\SessionInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
@@ -92,13 +93,37 @@ final class CallToolHandler implements RequestHandlerInterface
         $arguments['_session'] = $session;
         $arguments['_request'] = $request;
 
+        $context = new RequestContext($session, $request);
+
         try {
             $result = $this->referenceHandler->handle($reference, $arguments);
 
+            $protocolVersion = $context->getProtocolVersion();
+
             $structuredContent = null;
             if (!$result instanceof CallToolResult) {
-                $structuredContent = $reference->extractStructuredContent($result);
+                $structuredContent = $reference->extractStructuredContent($result, $protocolVersion);
+
+                if (null === $structuredContent && null !== $reference->tool->outputSchema) {
+                    $this->logger->warning('Tool declares an "outputSchema" but returned a value that cannot be sent as "structuredContent"; the value is only carried in "content".', [
+                        'name' => $toolName,
+                        'result_type' => get_debug_type($result),
+                    ]);
+                }
+
                 $result = new CallToolResult($reference->formatResult($result), structuredContent: $structuredContent);
+            } elseif ($protocolVersion->requiresObjectStructuredContent()
+                && \is_array($result->structuredContent)
+                && [] !== $result->structuredContent
+                && array_is_list($result->structuredContent)
+            ) {
+                // A tool building its own `CallToolResult` bypasses the extraction
+                // rules on purpose, so the value is sent as it was set — but a JSON
+                // array is not valid here before SEP-2106 and clients may reject it.
+                $this->logger->warning('Tool returned a "CallToolResult" whose "structuredContent" is a JSON array, which the negotiated protocol revision does not allow; sending it unchanged.', [
+                    'name' => $toolName,
+                    'protocol_version' => $protocolVersion->value,
+                ]);
             }
 
             $this->logger->debug('Tool executed successfully', [

src/Server/RequestContext.php

@@ -12,6 +12,7 @@
 namespace Mcp\Server;
 
 use Mcp\Capability\Logger\ClientLogger;
+use Mcp\Schema\Enum\ProtocolVersion;
 use Mcp\Schema\JsonRpc\Request;
 use Mcp\Server\Session\SessionInterface;
 
@@ -25,6 +26,14 @@ use Mcp\Server\Session\SessionInterface;
  */
 final class RequestContext
 {
+    /**
+     * `_meta` key carrying the protocol revision of a single request, introduced
+     * with the modern era that replaced the `initialize` handshake.
+     *
+     * @see https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning
+     */
+    private const PROTOCOL_VERSION_META_KEY = 'io.modelcontextprotocol/protocolVersion';
+
     private ?ClientGateway $clientGateway = null;
     private ?ClientLogger $clientLogger = null;
 
@@ -44,6 +53,26 @@ final class RequestContext
         return $this->session;
     }
 
+    /**
+     * The protocol revision this request is served under.
+     *
+     * Modern revisions declare it per request in `_meta`, handshake ones negotiate
+     * it once and keep it on the session. Neither is guaranteed to be present — a
+     * transport may skip `initialize` entirely — so this falls back to the newest
+     * handshake revision, whose rules hold for every revision below it too.
+     */
+    public function getProtocolVersion(): ProtocolVersion
+    {
+        $requested = $this->request->getMeta()[self::PROTOCOL_VERSION_META_KEY]
+            ?? $this->session->get('protocol_version');
+
+        if (!\is_string($requested)) {
+            return ProtocolVersion::latestHandshake();
+        }
+
+        return ProtocolVersion::tryFrom($requested) ?? ProtocolVersion::latestHandshake();
+    }
+
     public function getClientGateway(): ClientGateway
     {
         if (null == $this->clientGateway) {