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

tests/Unit/Capability/Formatter/PromptResultFormatterTest.php

@@ -17,6 +17,7 @@ use Mcp\Schema\Content\AudioContent;
 use Mcp\Schema\Content\EmbeddedResource;
 use Mcp\Schema\Content\ImageContent;
 use Mcp\Schema\Content\PromptMessage;
+use Mcp\Schema\Content\ResourceLink;
 use Mcp\Schema\Content\TextContent;
 use Mcp\Schema\Enum\Role;
 use PHPUnit\Framework\TestCase;
@@ -31,6 +32,29 @@ class PromptResultFormatterTest extends TestCase
         $this->assertSame($message, $result[0]);
     }
 
+    public function testFormatPromptMessageWithResourceLinkContent(): void
+    {
+        $message = new PromptMessage(Role::User, new ResourceLink('file:///a.png', 'a.png'));
+        $result = (new PromptResultFormatter())->format($message);
+        $this->assertCount(1, $result);
+        $this->assertSame($message, $result[0]);
+    }
+
+    public function testFormatRoleContentArrayWithResourceLinkContent(): void
+    {
+        $result = (new PromptResultFormatter())->format([
+            [
+                'role' => 'user',
+                'content' => ['type' => 'resource_link', 'uri' => 'file:///a.png', 'name' => 'a.png'],
+            ],
+        ]);
+        $this->assertCount(1, $result);
+        $this->assertSame(Role::User, $result[0]->role);
+        $this->assertInstanceOf(ResourceLink::class, $result[0]->content);
+        $this->assertSame('file:///a.png', $result[0]->content->uri);
+        $this->assertSame('a.png', $result[0]->content->name);
+    }
+
     public function testFormatUserAssistantShorthand(): void
     {
         $result = (new PromptResultFormatter())->format([

tests/Unit/Capability/RegistryTest.php

@@ -22,6 +22,8 @@ use Mcp\Capability\RegistryInterface;
 use Mcp\Exception\PromptNotFoundException;
 use Mcp\Exception\ResourceNotFoundException;
 use Mcp\Exception\ToolNotFoundException;
+use Mcp\Schema\Content\ResourceLink;
+use Mcp\Schema\Content\TextContent;
 use Mcp\Schema\Prompt;
 use Mcp\Schema\ResourceDefinition;
 use Mcp\Schema\ResourceTemplate;
@@ -536,6 +538,20 @@ class RegistryTest extends TestCase
         ], $structuredContent);
     }
 
+    public function testExtractStructuredContentReturnsNullForArrayOfContentItems(): void
+    {
+        $tool = $this->createValidTool('lookup_thing', null);
+        $toolReturnValue = [
+            new TextContent('Found it.'),
+            new ResourceLink(uri: 'thing://1', name: 'thing_1'),
+        ];
+
+        $this->registry->registerTool($tool, static fn () => $toolReturnValue);
+
+        $toolRef = $this->registry->getTool('lookup_thing');
+        $this->assertNull($toolRef->extractStructuredContent($toolReturnValue));
+    }
+
     public function testConfiguredLoaderIsNotRunUntilFirstRead(): void
     {
         $loader = $this->createMock(LoaderInterface::class);