[Schema] Add resource_link content block (#400)

* Add resource_link content block

The spec's `resource_link` content type (protocol revision 2025-06-18,
still present in 2025-11-25) had no corresponding schema class: it lets a
tool result or prompt message reference a resource by URI/name without
embedding its full contents, the way `EmbeddedResource` does. Without it,
tools returning many or large resource references (e.g. search results
over a DAM) are stuck smuggling URIs through text/structured content.

Add `Mcp\Schema\Content\ResourceLink`, mirroring the spec's `Resource`
shape (uri, name, title, description, mimeType, annotations, size, icons,
_meta) with a fixed `type: "resource_link"`, following the conventions of
the sibling `EmbeddedResource`/`ResourceDefinition` classes.

Register it everywhere `resource` content blocks are (de)serialized by
type per the spec's `ContentBlock` union:
- `CallToolResult::fromArray()`
- `PromptMessage` (constructor type, `fromArray()`, phpstan types)
- `PromptResultFormatter` (typed-array and direct-instance paths)

`SamplingMessage`/`CreateSamplingMessageResult` are intentionally left
unchanged: the spec's `SamplingMessageContentBlock` does not include
`ResourceLink`.

Fixes #399

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Add resource_link example coverage to discovery-userprofile

Add a lookup_user tool to the discovery-userprofile example: given a
userId, it returns a short text summary plus a resource_link pointing
at the existing user://{userId}/profile resource template, instead of
embedding the profile. This mirrors the PR's motivating use case (a
tool referencing many/large resources by URI rather than inlining
them) and exercises resource_link through the example's own inspector
snapshot tests (tools_call-lookup_user[_not_found], tools_list).

Wiring this up surfaced a real bug: ToolReference::extractStructuredContent()
passed any raw array return value straight through as structuredContent,
even when it held Content instances (e.g. the TextContent/ResourceLink
pair above). That serializes to a JSON list, which fails the spec's
requirement that structuredContent be an object - the inspector's MCP
client rejected the tool call outright until fixed. Skip structuredContent
extraction whenever the raw result contains a Content item, since those
are already represented in `content` and were never meant to double as
structured data.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Alex Rothberg <51059+cancan101@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

examples/server/discovery-userprofile/McpElements.php

@@ -18,6 +18,9 @@ use Mcp\Capability\Attribute\McpResourceTemplate;
 use Mcp\Capability\Attribute\McpTool;
 use Mcp\Exception\PromptGetException;
 use Mcp\Exception\ResourceReadException;
+use Mcp\Schema\Content\Content;
+use Mcp\Schema\Content\ResourceLink;
+use Mcp\Schema\Content\TextContent;
 use Psr\Log\LoggerInterface;
 
 /**
@@ -87,6 +90,44 @@ final class McpElements
         return array_keys($this->users);
     }
 
+    /**
+     * Looks up a user and returns a reference to their profile resource.
+     *
+     * Rather than embedding the full profile (as `resources/read` on
+     * `user://{userId}/profile` would), this returns a `resource_link` block
+     * pointing at that resource template so the caller can fetch it
+     * separately if needed. This mirrors how a tool like a search returning
+     * many hits would reference each matching resource by URI instead of
+     * inlining every one of them.
+     *
+     * @param string $userId the ID of the user to look up
+     *
+     * @return Content[] a short summary plus a resource_link to the user's profile
+     */
+    #[McpTool(name: 'lookup_user')]
+    public function lookupUser(
+        #[CompletionProvider(values: ['101', '102', '103'])]
+        string $userId,
+    ): array {
+        $this->logger->info('Executing tool: lookup_user', ['userId' => $userId]);
+
+        if (!isset($this->users[$userId])) {
+            return [new TextContent("User ID {$userId} not found.")];
+        }
+
+        $user = $this->users[$userId];
+
+        return [
+            new TextContent("Found user {$user['name']} ({$user['role']})."),
+            new ResourceLink(
+                uri: "user://{$userId}/profile",
+                name: 'user_profile',
+                description: "Full profile for {$user['name']}.",
+                mimeType: 'application/json',
+            ),
+        ];
+    }
+
     /**
      * Sends a welcome message to a user.
      * (This is a placeholder - in a real app, it might queue an email).