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

[Schema] Add resource_link content block (#400)

Browse source 
* 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>
This commit is contained in:
Alex Rothberg 2026-08-14 17:20:56 -04:00 • committed by GitHub
commit fc456125e2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
17 changed files with 751 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

1
CHANGELOG.md
View file

@ -9,6 +9,7 @@ All notable changes to `mcp/sdk` will be documented in this file.
* Prompt generators returning content as typed arrays (`['type' => 'text', ...]` etc.) no longer lose the optional fields: `annotations` on every content type, and `_meta` and an explicit `mimeType` on embedded resource contents, now carry through to the resulting `PromptMessage` instead of being silently dropped. A missing resource `mimeType` still defaults to `text/plain`/`application/octet-stream` as before.
* Add `annotations` support to `ImageContent` (constructor, `fromArray()`, `fromFile()`, `fromString()`, `jsonSerialize()`), matching `TextContent` and `AudioContent`.
* Add client-side `roots/list` handler (`ListRootsRequestHandler` + `RootsCallbackInterface`) and `Client::sendRootsListChanged()`, plus server-side `ClientGateway::listRoots()` / `supportsRoots()` and `ListRootsResult::fromArray()`.
* Add `Mcp\Schema\Content\ResourceLink` for the spec's `resource_link` content block (protocol revision 2025-06-18+), letting tool results and prompt messages reference a resource by URI/name without embedding its contents. Accepted anywhere `resource` (`EmbeddedResource`) content is (de)serialized: `CallToolResult::fromArray()`, `PromptMessage::fromArray()`, and `PromptResultFormatter`.
0.7.0
-----

13
docs/mcp-elements.md
View file

@ -107,7 +107,7 @@ public function returnVoid(): void { /* no return */ } // Empty conten
For fine control over output formatting:
```php
use Mcp\Schema\Content\{TextContent, ImageContent, AudioContent, EmbeddedResource};
use Mcp\Schema\Content\{TextContent, ImageContent, AudioContent, ResourceLink, EmbeddedResource};
public function getFormattedCode(): TextContent
{
@ -142,6 +142,17 @@ public function getEmbeddedResource(): EmbeddedResource
resource: ['uri' => 'file://data.json', 'text' => 'File content']
);
}
public function getResourceLink(): ResourceLink
{
// Reference a resource by URI without embedding its contents, e.g. when
// a tool result would otherwise need to inline many or large resources.
return new ResourceLink(
uri: 'file://data.json',
name: 'data.json',
mimeType: 'application/json'
);
}
```
#### Multiple Content Items

41
examples/server/discovery-userprofile/McpElements.php
View file

@ -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).

11
src/Capability/Formatter/PromptResultFormatter.php
View file

@ -18,6 +18,7 @@ use Mcp\Schema\Content\Content;
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;
@ -141,18 +142,19 @@ final class PromptResultFormatter
/**
* Formats content into a proper Content object.
*/
private function formatContent(mixed $content, ?int $index = null): TextContent|ImageContent|AudioContent|EmbeddedResource
private function formatContent(mixed $content, ?int $index = null): TextContent|ImageContent|AudioContent|ResourceLink|EmbeddedResource
{
$indexStr = null !== $index ? " at index {$index}" : '';
if ($content instanceof Content) {
if (
$content instanceof TextContent || $content instanceof ImageContent
|| $content instanceof AudioContent || $content instanceof EmbeddedResource
|| $content instanceof AudioContent || $content instanceof ResourceLink
|| $content instanceof EmbeddedResource
) {
return $content;
}
throw new RuntimeException("Invalid Content type{$indexStr}. PromptMessage only supports TextContent, ImageContent, AudioContent, or EmbeddedResource.");
throw new RuntimeException("Invalid Content type{$indexStr}. PromptMessage only supports TextContent, ImageContent, AudioContent, ResourceLink, or EmbeddedResource.");
}
if (\is_string($content)) {
@ -182,7 +184,7 @@ final class PromptResultFormatter
*
* @param array<string, mixed> $content
*/
private function formatTypedContent(array $content, ?int $index = null): TextContent|ImageContent|AudioContent|EmbeddedResource
private function formatTypedContent(array $content, ?int $index = null): TextContent|ImageContent|AudioContent|ResourceLink|EmbeddedResource
{
$indexStr = null !== $index ? " at index {$index}" : '';
$type = $content['type'];
@ -199,6 +201,7 @@ final class PromptResultFormatter
'image' => ImageContent::fromArray($content),
'audio' => AudioContent::fromArray($content),
'resource' => EmbeddedResource::fromArray($content),
'resource_link' => ResourceLink::fromArray($content),
default => throw new RuntimeException("Invalid content type '{$type}'{$indexStr}."),
};
} catch (InvalidArgumentException $e) {

11
src/Capability/Registry/ToolReference.php
View file

@ -68,6 +68,17 @@ class ToolReference extends ElementReference
public function extractStructuredContent(mixed $toolExecutionResult): ?array
{
if (\is_array($toolExecutionResult)) {
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.
return null;
}
}
return $toolExecutionResult;
}

12
src/Schema/Content/PromptMessage.php
View file

@ -20,11 +20,12 @@ use Mcp\Schema\Enum\Role;
* @phpstan-import-type TextContentData from TextContent
* @phpstan-import-type ImageContentData from ImageContent
* @phpstan-import-type AudioContentData from AudioContent
* @phpstan-import-type ResourceLinkData from ResourceLink
* @phpstan-import-type EmbeddedResourceData from EmbeddedResource
*
* @phpstan-type PromptMessageData array{
* role: string,
* content: TextContentData|ImageContentData|AudioContentData|EmbeddedResourceData,
* content: TextContentData|ImageContentData|AudioContentData|ResourceLinkData|EmbeddedResourceData,
* }
*
* @author Kyrian Obikwelu <koshnawaza@gmail.com>
@ -34,12 +35,12 @@ class PromptMessage extends Content
/**
* Create a new PromptMessage instance.
*
* @param Role $role The role of the message
* @param TextContent|ImageContent|AudioContent|EmbeddedResource $content The content of the message
* @param Role $role The role of the message
* @param TextContent|ImageContent|AudioContent|ResourceLink|EmbeddedResource $content The content of the message
*/
public function __construct(
public readonly Role $role,
public readonly TextContent|ImageContent|AudioContent|EmbeddedResource $content,
public readonly TextContent|ImageContent|AudioContent|ResourceLink|EmbeddedResource $content,
) {
parent::__construct('prompt');
}
@ -67,6 +68,7 @@ class PromptMessage extends Content
'image' => ImageContent::fromArray($contentData),
'audio' => AudioContent::fromArray($contentData),
'resource' => EmbeddedResource::fromArray($contentData),
'resource_link' => ResourceLink::fromArray($contentData),
default => throw new InvalidArgumentException(\sprintf('Invalid content type "%s" for PromptMessage.', $contentType)),
};
@ -82,7 +84,7 @@ class PromptMessage extends Content
*
* @return array{
* role: string,
* content: TextContent|ImageContent|AudioContent|EmbeddedResource
* content: TextContent|ImageContent|AudioContent|ResourceLink|EmbeddedResource
* }
*/
public function jsonSerialize(): array

146
src/Schema/Content/ResourceLink.php Normal file
View file

@ -0,0 +1,146 @@
<?php
/*
* This file is part of the official PHP MCP SDK.
*
* A collaboration between Symfony and the PHP Foundation.
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/
namespace Mcp\Schema\Content;
use Mcp\Exception\InvalidArgumentException;
use Mcp\Schema\Annotations;
use Mcp\Schema\Icon;
/**
* Represents a link to a resource, without embedding its contents.
*
* A resource that the server is capable of reading, included in a prompt or
* tool call result. Unlike `EmbeddedResource`, this points to a resource
* without including its full content, allowing clients to fetch it separately.
*
* @phpstan-import-type AnnotationsData from Annotations
* @phpstan-import-type IconData from Icon
*
* @phpstan-type ResourceLinkData array{
* type: 'resource_link',
* uri: string,
* name: string,
* title?: string,
* description?: string,
* mimeType?: string,
* annotations?: AnnotationsData,
* size?: int,
* icons?: IconData[],
* _meta?: array<string, mixed>,
* }
*
* @author Alex Rothberg <cancan101@users.noreply.github.com>
*/
class ResourceLink extends Content
{
/**
* @param string $uri the URI of this resource
* @param string $name a short identifier for this resource
* @param ?string $title optional human-readable title for display in UI
* @param ?string $description a description of what this resource represents. This can be used by clients to improve the LLM's understanding of available resources
* @param ?string $mimeType the MIME type of this resource, if known
* @param ?Annotations $annotations optional annotations for the client
* @param ?int $size the size of the raw resource content, in bytes (before base64 encoding or any tokenization), if known
* @param ?Icon[] $icons optional icons representing the resource
* @param ?array<string, mixed> $meta optional metadata
*/
public function __construct(
public readonly string $uri,
public readonly string $name,
public readonly ?string $title = null,
public readonly ?string $description = null,
public readonly ?string $mimeType = null,
public readonly ?Annotations $annotations = null,
public readonly ?int $size = null,
public readonly ?array $icons = null,
public readonly ?array $meta = null,
) {
parent::__construct('resource_link');
}
/**
* @param ResourceLinkData $data
*/
public static function fromArray(array $data): self
{
if (($data['type'] ?? null) !== 'resource_link') {
throw new InvalidArgumentException('Invalid type for ResourceLink.');
}
if (empty($data['uri']) || !\is_string($data['uri'])) {
throw new InvalidArgumentException('Invalid or missing "uri" in ResourceLink data.');
}
if (empty($data['name']) || !\is_string($data['name'])) {
throw new InvalidArgumentException('Invalid or missing "name" in ResourceLink data.');
}
if (isset($data['_meta']) && !\is_array($data['_meta'])) {
throw new InvalidArgumentException('Invalid "_meta" in ResourceLink data.');
}
return new self(
uri: $data['uri'],
name: $data['name'],
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,
meta: $data['_meta'] ?? null,
);
}
/**
* @return array{
* type: 'resource_link',
* uri: string,
* name: string,
* title?: string,
* description?: string,
* mimeType?: string,
* annotations?: Annotations,
* size?: int,
* icons?: Icon[],
* _meta?: array<string, mixed>,
* }
*/
public function jsonSerialize(): array
{
$data = [
'type' => $this->type,
'uri' => $this->uri,
'name' => $this->name,
];
if (null !== $this->title) {
$data['title'] = $this->title;
}
if (null !== $this->description) {
$data['description'] = $this->description;
}
if (null !== $this->mimeType) {
$data['mimeType'] = $this->mimeType;
}
if (null !== $this->annotations) {
$data['annotations'] = $this->annotations;
}
if (null !== $this->size) {
$data['size'] = $this->size;
}
if (null !== $this->icons) {
$data['icons'] = $this->icons;
}
if (null !== $this->meta) {
$data['_meta'] = $this->meta;
}
return $data;
}
}

2
src/Schema/Result/CallToolResult.php
View file

@ -16,6 +16,7 @@ use Mcp\Schema\Content\AudioContent;
use Mcp\Schema\Content\Content;
use Mcp\Schema\Content\EmbeddedResource;
use Mcp\Schema\Content\ImageContent;
use Mcp\Schema\Content\ResourceLink;
use Mcp\Schema\Content\TextContent;
use Mcp\Schema\JsonRpc\ResultInterface;
@ -105,6 +106,7 @@ class CallToolResult implements ResultInterface
'image' => ImageContent::fromArray($item),
'audio' => AudioContent::fromArray($item),
'resource' => EmbeddedResource::fromArray($item),
'resource_link' => ResourceLink::fromArray($item),
default => throw new InvalidArgumentException(\sprintf('Invalid content type in CallToolResult data: "%s".', $type)),
};
}

16
tests/Inspector/Http/HttpDiscoveryUserProfileTest.php
View file

@ -17,6 +17,22 @@ final class HttpDiscoveryUserProfileTest extends HttpInspectorSnapshotTestCase
{
return [
...parent::provideMethods(),
'Lookup User Tool' => [
'method' => 'tools/call',
'options' => [
'toolName' => 'lookup_user',
'toolArgs' => ['userId' => '"101"'],
],
'testName' => 'lookup_user',
],
'Lookup User Tool (Not Found)' => [
'method' => 'tools/call',
'options' => [
'toolName' => 'lookup_user',
'toolArgs' => ['userId' => '"999"'],
],
'testName' => 'lookup_user_not_found',
],
'Send Welcome Tool' => [
'method' => 'tools/call',
'options' => [

16
tests/Inspector/Http/snapshots/HttpDiscoveryUserProfileTest-tools_call-lookup_user.json Normal file
View file

@ -0,0 +1,16 @@
{
"content": [
{
"type": "text",
"text": "Found user Alice (admin)."
},
{
"name": "user_profile",
"uri": "user://101/profile",
"description": "Full profile for Alice.",
"mimeType": "application/json",
"type": "resource_link"
}
],
"isError": false
}

9
tests/Inspector/Http/snapshots/HttpDiscoveryUserProfileTest-tools_call-lookup_user_not_found.json Normal file
View file

@ -0,0 +1,9 @@
{
"content": [
{
"type": "text",
"text": "User ID 999 not found."
}
],
"isError": false
}

16
tests/Inspector/Http/snapshots/HttpDiscoveryUserProfileTest-tools_list.json
View file

@ -23,6 +23,22 @@
]
}
},
{
"name": "lookup_user",
"description": "Looks up a user and returns a reference to their profile resource.\n\nRather than embedding the full profile (as `resources/read` on\n`user://{userId}/profile` would), this returns a `resource_link` block\npointing at that resource template so the caller can fetch it\nseparately if needed. This mirrors how a tool like a search returning\nmany hits would reference each matching resource by URI instead of\ninlining every one of them.",
"inputSchema": {
"type": "object",
"properties": {
"userId": {
"type": "string",
"description": "the ID of the user to look up"
}
},
"required": [
"userId"
]
}
},
{
"name": "send_welcome",
"description": "Sends a welcome message to a user.\n\n(This is a placeholder - in a real app, it might queue an email).",

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

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

16
tests/Unit/Capability/RegistryTest.php
View file

@ -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);

84
tests/Unit/Schema/Content/PromptMessageTest.php Normal file
View file

@ -0,0 +1,84 @@
<?php
/*
* This file is part of the official PHP MCP SDK.
*
* A collaboration between Symfony and the PHP Foundation.
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/
namespace Mcp\Tests\Unit\Schema\Content;
use Mcp\Exception\InvalidArgumentException;
use Mcp\Schema\Content\PromptMessage;
use Mcp\Schema\Content\ResourceLink;
use Mcp\Schema\Enum\Role;
use PHPUnit\Framework\TestCase;
final class PromptMessageTest extends TestCase
{
public function testFromArrayDeserializesResourceLinkContent(): void
{
$message = PromptMessage::fromArray([
'role' => 'user',
'content' => [
'type' => 'resource_link',
'uri' => 'file:///project/src/main.rs',
'name' => 'main.rs',
],
]);
$this->assertSame(Role::User, $message->role);
$this->assertInstanceOf(ResourceLink::class, $message->content);
$this->assertSame('file:///project/src/main.rs', $message->content->uri);
$this->assertSame('main.rs', $message->content->name);
}
public function testJsonSerializeIncludesResourceLinkContent(): void
{
$message = new PromptMessage(Role::Assistant, new ResourceLink('file:///a.png', 'a.png'));
$this->assertSame([
'role' => 'assistant',
'content' => [
'type' => 'resource_link',
'uri' => 'file:///a.png',
'name' => 'a.png',
],
], json_decode(json_encode($message), true));
}
public function testRoundTripWithResourceLink(): void
{
$original = new PromptMessage(Role::User, new ResourceLink('file:///a.png', 'a.png', mimeType: 'image/png'));
$decoded = json_decode(json_encode($original), true);
$rehydrated = PromptMessage::fromArray($decoded);
$this->assertSame(Role::User, $rehydrated->role);
$this->assertInstanceOf(ResourceLink::class, $rehydrated->content);
$this->assertSame('file:///a.png', $rehydrated->content->uri);
$this->assertSame('image/png', $rehydrated->content->mimeType);
}
public function testFromArrayRejectsUnknownContentType(): void
{
$this->expectException(InvalidArgumentException::class);
/* @phpstan-ignore argument.type */
PromptMessage::fromArray([
'role' => 'user',
'content' => ['type' => 'not-a-real-type'],
]);
}
public function testConstructorAcceptsResourceLinkContent(): void
{
$link = new ResourceLink('file:///a.png', 'a.png');
$message = new PromptMessage(Role::User, $link);
$this->assertSame($link, $message->content);
}
}

231
tests/Unit/Schema/Content/ResourceLinkTest.php Normal file
View file

@ -0,0 +1,231 @@
<?php
/*
* This file is part of the official PHP MCP SDK.
*
* A collaboration between Symfony and the PHP Foundation.
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/
namespace Mcp\Tests\Unit\Schema\Content;
use Mcp\Exception\InvalidArgumentException;
use Mcp\Schema\Annotations;
use Mcp\Schema\Content\ResourceLink;
use Mcp\Schema\Enum\Role;
use Mcp\Schema\Icon;
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;
final class ResourceLinkTest extends TestCase
{
private const VALID_URI = 'file:///project/src/main.rs';
public function testConstructorSetsType(): void
{
$link = new ResourceLink(self::VALID_URI, 'main.rs');
$this->assertSame('resource_link', $link->type);
$this->assertSame(self::VALID_URI, $link->uri);
$this->assertSame('main.rs', $link->name);
$this->assertNull($link->title);
$this->assertNull($link->description);
$this->assertNull($link->mimeType);
$this->assertNull($link->annotations);
$this->assertNull($link->size);
$this->assertNull($link->icons);
$this->assertNull($link->meta);
}
public function testConstructorWithAllFields(): void
{
$annotations = new Annotations([Role::User], 0.5);
$icons = [new Icon('https://example.com/icon.png')];
$link = new ResourceLink(
uri: self::VALID_URI,
name: 'main.rs',
title: 'Main Source File',
description: 'Primary application entry point',
mimeType: 'text/x-rust',
annotations: $annotations,
size: 1024,
icons: $icons,
meta: ['origin' => 'test'],
);
$this->assertSame(self::VALID_URI, $link->uri);
$this->assertSame('main.rs', $link->name);
$this->assertSame('Main Source File', $link->title);
$this->assertSame('Primary application entry point', $link->description);
$this->assertSame('text/x-rust', $link->mimeType);
$this->assertSame($annotations, $link->annotations);
$this->assertSame(1024, $link->size);
$this->assertSame($icons, $link->icons);
$this->assertSame(['origin' => 'test'], $link->meta);
}
public function testJsonSerializeMinimal(): void
{
$link = new ResourceLink(self::VALID_URI, 'main.rs');
$this->assertSame([
'type' => 'resource_link',
'uri' => self::VALID_URI,
'name' => 'main.rs',
], $link->jsonSerialize());
}
public function testJsonSerializeWithAllFields(): void
{
$annotations = new Annotations([Role::User], 0.5);
$icons = [new Icon('https://example.com/icon.png')];
$link = new ResourceLink(
uri: self::VALID_URI,
name: 'main.rs',
title: 'Main Source File',
description: 'Primary application entry point',
mimeType: 'text/x-rust',
annotations: $annotations,
size: 1024,
icons: $icons,
meta: ['origin' => 'test'],
);
$data = $link->jsonSerialize();
$this->assertSame('resource_link', $data['type']);
$this->assertSame(self::VALID_URI, $data['uri']);
$this->assertSame('main.rs', $data['name']);
$this->assertSame('Main Source File', $data['title']);
$this->assertSame('Primary application entry point', $data['description']);
$this->assertSame('text/x-rust', $data['mimeType']);
$this->assertSame($annotations, $data['annotations']);
$this->assertSame(1024, $data['size']);
$this->assertSame($icons, $data['icons']);
$this->assertSame(['origin' => 'test'], $data['_meta']);
}
public function testOptionalFieldsOmittedWhenNull(): void
{
$link = new ResourceLink(self::VALID_URI, 'main.rs');
$data = $link->jsonSerialize();
$this->assertArrayNotHasKey('title', $data);
$this->assertArrayNotHasKey('description', $data);
$this->assertArrayNotHasKey('mimeType', $data);
$this->assertArrayNotHasKey('annotations', $data);
$this->assertArrayNotHasKey('size', $data);
$this->assertArrayNotHasKey('icons', $data);
$this->assertArrayNotHasKey('_meta', $data);
}
public function testFromArrayMinimal(): void
{
$link = ResourceLink::fromArray([
'type' => 'resource_link',
'uri' => self::VALID_URI,
'name' => 'main.rs',
]);
$this->assertSame(self::VALID_URI, $link->uri);
$this->assertSame('main.rs', $link->name);
$this->assertNull($link->title);
$this->assertNull($link->annotations);
$this->assertNull($link->icons);
$this->assertNull($link->meta);
}
public function testFromArrayWithAllFields(): void
{
$link = ResourceLink::fromArray([
'type' => 'resource_link',
'uri' => self::VALID_URI,
'name' => 'main.rs',
'title' => 'Main Source File',
'description' => 'Primary application entry point',
'mimeType' => 'text/x-rust',
'annotations' => ['audience' => ['user'], 'priority' => 0.5],
'size' => 1024,
'icons' => [['src' => 'https://example.com/icon.png']],
'_meta' => ['origin' => 'test'],
]);
$this->assertSame('Main Source File', $link->title);
$this->assertSame('Primary application entry point', $link->description);
$this->assertSame('text/x-rust', $link->mimeType);
$this->assertInstanceOf(Annotations::class, $link->annotations);
$this->assertSame(1024, $link->size);
$this->assertCount(1, $link->icons);
$this->assertInstanceOf(Icon::class, $link->icons[0]);
$this->assertSame(['origin' => 'test'], $link->meta);
}
public function testRoundTripThroughJsonSerializeAndFromArray(): void
{
$original = new ResourceLink(
uri: self::VALID_URI,
name: 'main.rs',
title: 'Main Source File',
description: 'Primary application entry point',
mimeType: 'text/x-rust',
annotations: new Annotations([Role::User], 0.5),
size: 1024,
icons: [new Icon('https://example.com/icon.png')],
meta: ['origin' => 'test'],
);
$decoded = json_decode(json_encode($original), true);
$rehydrated = ResourceLink::fromArray($decoded);
$this->assertSame($original->uri, $rehydrated->uri);
$this->assertSame($original->name, $rehydrated->name);
$this->assertSame($original->title, $rehydrated->title);
$this->assertSame($original->description, $rehydrated->description);
$this->assertSame($original->mimeType, $rehydrated->mimeType);
$this->assertSame($original->size, $rehydrated->size);
$this->assertSame($original->meta, $rehydrated->meta);
$this->assertEquals($original->annotations, $rehydrated->annotations);
}
public function testFromArrayRejectsWrongType(): void
{
$this->expectException(InvalidArgumentException::class);
$this->expectExceptionMessage('Invalid type for ResourceLink.');
/* @phpstan-ignore argument.type */
ResourceLink::fromArray([
'type' => 'resource',
'uri' => self::VALID_URI,
'name' => 'main.rs',
]);
}
#[DataProvider('provideInvalidData')]
public function testFromArrayRejectsInvalidData(array $input, string $expectedExceptionMessage): void
{
$this->expectException(InvalidArgumentException::class);
$this->expectExceptionMessage($expectedExceptionMessage);
ResourceLink::fromArray($input);
}
public static function provideInvalidData(): iterable
{
yield 'missing uri' => [
['type' => 'resource_link', 'name' => 'main.rs'],
'Invalid or missing "uri" in ResourceLink data.',
];
yield 'missing name' => [
['type' => 'resource_link', 'uri' => self::VALID_URI],
'Invalid or missing "name" in ResourceLink data.',
];
yield 'invalid _meta' => [
['type' => 'resource_link', 'uri' => self::VALID_URI, 'name' => 'main.rs', '_meta' => 'not-an-array'],
'Invalid "_meta" in ResourceLink data.',
];
}
}

112
tests/Unit/Schema/Result/CallToolResultTest.php Normal file
View file

@ -0,0 +1,112 @@
<?php
/*
* This file is part of the official PHP MCP SDK.
*
* A collaboration between Symfony and the PHP Foundation.
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/
namespace Mcp\Tests\Unit\Schema\Result;
use Mcp\Exception\InvalidArgumentException;
use Mcp\Schema\Content\AudioContent;
use Mcp\Schema\Content\EmbeddedResource;
use Mcp\Schema\Content\ImageContent;
use Mcp\Schema\Content\ResourceLink;
use Mcp\Schema\Content\TextContent;
use Mcp\Schema\Result\CallToolResult;
use PHPUnit\Framework\TestCase;
final class CallToolResultTest extends TestCase
{
public function testFromArrayDeserializesResourceLinkContent(): void
{
$result = CallToolResult::fromArray([
'content' => [
[
'type' => 'resource_link',
'uri' => 'file:///project/src/main.rs',
'name' => 'main.rs',
'mimeType' => 'text/x-rust',
],
],
'isError' => false,
]);
$this->assertCount(1, $result->content);
$this->assertInstanceOf(ResourceLink::class, $result->content[0]);
$this->assertSame('file:///project/src/main.rs', $result->content[0]->uri);
$this->assertSame('main.rs', $result->content[0]->name);
$this->assertSame('text/x-rust', $result->content[0]->mimeType);
}
public function testFromArrayDeserializesMixedContentTypes(): void
{
$result = CallToolResult::fromArray([
'content' => [
['type' => 'text', 'text' => 'search results'],
['type' => 'resource_link', 'uri' => 'file:///a.png', 'name' => 'a.png'],
['type' => 'resource_link', 'uri' => 'file:///b.png', 'name' => 'b.png'],
],
]);
$this->assertCount(3, $result->content);
$this->assertInstanceOf(TextContent::class, $result->content[0]);
$this->assertInstanceOf(ResourceLink::class, $result->content[1]);
$this->assertInstanceOf(ResourceLink::class, $result->content[2]);
}
public function testFromArrayRejectsUnknownContentType(): void
{
$this->expectException(InvalidArgumentException::class);
CallToolResult::fromArray([
'content' => [
['type' => 'not-a-real-type'],
],
]);
}
public function testJsonSerializeIncludesResourceLinkContent(): void
{
$result = new CallToolResult([
new ResourceLink('file:///project/src/main.rs', 'main.rs'),
]);
$data = $result->jsonSerialize();
$this->assertSame([
'type' => 'resource_link',
'uri' => 'file:///project/src/main.rs',
'name' => 'main.rs',
], $data['content'][0]->jsonSerialize());
}
public function testRoundTripWithResourceLinkAlongsideOtherContentTypes(): void
{
$original = new CallToolResult([
new TextContent('25 results found'),
new ResourceLink('file:///a.png', 'a.png', mimeType: 'image/png'),
new ImageContent(base64_encode('binary'), 'image/png'),
new AudioContent(base64_encode('binary'), 'audio/mpeg'),
EmbeddedResource::fromText('file:///readme.txt', 'hello'),
]);
$decoded = json_decode(json_encode($original), true);
$rehydrated = CallToolResult::fromArray($decoded);
$this->assertCount(5, $rehydrated->content);
$this->assertInstanceOf(TextContent::class, $rehydrated->content[0]);
$this->assertInstanceOf(ResourceLink::class, $rehydrated->content[1]);
$this->assertInstanceOf(ImageContent::class, $rehydrated->content[2]);
$this->assertInstanceOf(AudioContent::class, $rehydrated->content[3]);
$this->assertInstanceOf(EmbeddedResource::class, $rehydrated->content[4]);
$this->assertSame('file:///a.png', $rehydrated->content[1]->uri);
$this->assertSame('a.png', $rehydrated->content[1]->name);
$this->assertSame('image/png', $rehydrated->content[1]->mimeType);
}
}