[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
5 changed files with 751 additions and 10 deletions
|
|
@ -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) {
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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
146
src/Schema/Content/ResourceLink.php
Normal 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;
|
||||
}
|
||||
}
|
||||
|
|
@ -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)),
|
||||
};
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue