[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>
This commit is contained in:
Alex Rothberg
GitHub
parent
bdc9d86671
commit
fc456125e2
3 changed files with 751 additions and 10 deletions
84
tests/Unit/Schema/Content/PromptMessageTest.php
Normal file
84
tests/Unit/Schema/Content/PromptMessageTest.php
Normal 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
231
tests/Unit/Schema/Content/ResourceLinkTest.php
Normal 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
112
tests/Unit/Schema/Result/CallToolResultTest.php
Normal 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);
|
||||
}
|
||||
}
|
||||
Loading…
Reference in a new issue