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

docs/mcp-elements.md

@@ -170,6 +170,82 @@ public function getMultipleContent(): array
 }
 ```
 
+#### Structured Output
+
+Besides the human-readable `content`, a tool result can carry a machine-readable `structuredContent` value. Declare its
+shape with `outputSchema`, a JSON Schema of type `object`:
+
+```php
+#[McpTool(
+    name: 'get_weather',
+    outputSchema: [
+        'type' => 'object',
+        'properties' => [
+            'temperature' => ['type' => 'number'],
+            'conditions' => ['type' => 'string'],
+        ],
+        'required' => ['temperature', 'conditions'],
+    ]
+)]
+public function getWeather(string $city): array
+{
+    // Sent as `structuredContent`, and JSON-encoded into `content` for clients that ignore it
+    return ['temperature' => 22.5, 'conditions' => 'sunny'];
+}
+```
+
+The same schema can be passed to manual registration:
+
+```php
+$builder->addTool([WeatherHandler::class, 'getWeather'], outputSchema: [/* ... */]);
+```
+
+The SDK fills `structuredContent` whenever the return value qualifies — `outputSchema` is what tells clients to expect it
+and lets them validate it. What qualifies depends on the protocol revision the call is served under:
+
+| Return value | `structuredContent` |
+|---|---|
+| Associative array (`['temperature' => 22.5]`) | The array |
+| Object (`stdClass`, DTO, `JsonSerializable`) that serializes to a JSON object | Its JSON representation |
+| List (`[1, 2, 3]`, `[['id' => 1], ['id' => 2]]`), or an object serializing to one | Omitted before `2026-07-28`, kept from it on |
+| Array holding `Content` instances | Omitted (already carried in `content`) |
+| Scalars, `null`, `Content` instances | Omitted |
+
+Up to revision `2025-11-25`, `structuredContent` had to be a JSON object, so a PHP list — which serializes to a JSON
+array — was not emittable and strict clients rejected the whole tool call over one. [SEP-2106][sep-2106], part of
+revision `2026-07-28`, widened `outputSchema` to any JSON Schema 2020-12 and `structuredContent` to any JSON value
+conforming to it. The SDK picks the rule from the revision negotiated for the call, so a tool serving both eras needs the
+object shape to produce structured output everywhere. Wrap the list in a key for that:
+
+```php
+// Structured content only from 2026-07-28 on: a bare list is not a JSON object
+public function listUsersFlat(): array
+{
+    return [['id' => 1], ['id' => 2]];
+}
+
+#[McpTool(outputSchema: [
+    'type' => 'object',
+    'properties' => [
+        'items' => ['type' => 'array', 'items' => ['type' => 'object']],
+    ],
+    'required' => ['items']
+])]
+public function listUsers(): array
+{
+    return ['items' => [['id' => 1], ['id' => 2]]];
+}
+```
+
+Either way the data reaches the client: a return value with no structured representation is still JSON-encoded into
+`content` as a `TextContent`. When a tool declares an `outputSchema` but returns something that cannot be sent as
+`structuredContent`, the SDK logs a warning — the value is not silently dropped.
+
+A tool that wants to branch on the revision itself can read it from the injected `RequestContext`, see
+[Client Communication](server-client-communication.md#client-gateway).
+
+[sep-2106]: https://modelcontextprotocol.io/specification/2026-07-28/server/tools#structured-content
+
 #### Error Handling
 
 Tool handlers can throw any exception, but the type determines how it's handled:

docs/server-client-communication.md

@@ -30,6 +30,17 @@ class MyService
         $context->getClientGateway()->log(...);
 ```
 
+The same object also carries the protocol revision negotiated for the current request, which is useful when a feature is
+only available from a certain revision on:
+
+```php
+use Mcp\Schema\Enum\ProtocolVersion;
+
+if ($context->getProtocolVersion()->isAtLeast(ProtocolVersion::V2026_07_28)) {
+    // e.g. a bare list is only valid as `structuredContent` from this revision on
+}
+```
+
 ## Sampling
 
 With [sampling](https://modelcontextprotocol.io/specification/2025-11-25/client/sampling) servers can request clients to