[Schema] Add resource_link content block

[cancan101]

Summary

Implements the spec's resource_link content type (protocol revision 2025-06-18, still present in 2025-11-25), which was missing from the SDK: src/Schema/Content/ had TextContent, ImageContent, AudioContent, and EmbeddedResource, but no way to reference a resource by URI/name without embedding its full contents.

Fixes #399

Spec revision implemented

Per the MCP schema, ResourceLink extends Resource (BaseMetadata + Icons), i.e.:

interface ResourceLink extends Resource {
  type: "resource_link";
}
interface Resource extends BaseMetadata, Icons {
  uri: string;
  description?: string;
  mimeType?: string;
  annotations?: Annotations;
  size?: number;
  _meta?: { [key: string]: unknown };
}

Mcp\Schema\Content\ResourceLink mirrors this exactly: required uri + name, optional title, description, mimeType, annotations, size, icons, _meta — following the same constructor/fromArray/jsonSerialize conventions as the sibling EmbeddedResource and Mcp\Schema\ResourceDefinition classes.

Registration points touched

resource_link is now accepted everywhere resource (EmbeddedResource) content blocks are (de)serialized by type, matching the spec's ContentBlock union (TextContent | ImageContent | AudioContent | ResourceLink | EmbeddedResource):

• Mcp\Schema\Result\CallToolResult::fromArray()
• Mcp\Schema\Content\PromptMessage (constructor type union, fromArray(), phpstan types)
• Mcp\Capability\Formatter\PromptResultFormatter (both the typed-array path and the direct-Content-instance path)

SamplingMessage / CreateSamplingMessageResult are intentionally left untouched — the spec's SamplingMessageContentBlock union does not include ResourceLink.

Also added a doc example (docs/mcp-elements.md) and a CHANGELOG entry.

Test coverage

• tests/Unit/Schema/Content/ResourceLinkTest.php: construction, optional-field defaults, jsonSerialize/fromArray round-trip, invalid-type/missing-field/invalid-_meta rejection.
• tests/Unit/Schema/Content/PromptMessageTest.php: resource_link deserialization, serialization, round-trip, and constructor acceptance.
• tests/Unit/Schema/Result/CallToolResultTest.php: resource_link deserialization alongside other content types in a single result, serialization, and a full round-trip mixing all five content types.
• tests/Unit/Capability/Formatter/PromptResultFormatterTest.php: resource_link through both the PromptMessage-instance path and the raw-array role/content path.

Full unit suite (841 tests / 2557 assertions), php-cs-fixer --dry-run, phpstan analyse, composer validate --strict, and make docs all pass locally.

Downstream use case

pimcore/data-hub-simple-rest#287 — a Pimcore DAM MCP server whose search/tree tools return hits referencing image/video assets that are separately readable via registered resource templates. Per spec, each hit should carry a resource_link block with the template-constructed URI; embedding blobs in a 25-hit search result isn't viable, so tool output was stuck smuggling URIs through text/structured content until this type existed.

🤖 Generated with Claude Code

[chr-hertel]

Hi @cancan101, thanks for working on it and happy to hear Pimcore is adopting MCP 😎 👍

one thing to add, before i jump into review, can you find a meaningful addition to one of our examples here?

getting stuff into the examples also brings in functional test coverage via inspector :)

[cancan101]

Good call — pushed a commit that extends the discovery-userprofile example: lookup_user looks up a user by ID and returns a resource_link pointing at the existing user://{userId}/profile resource template instead of embedding it, mirroring the search-hit-referencing-a-resource use case from the PR description.

This is now exercised by that example's inspector snapshot tests (tools_list, tools_call-lookup_user, tools_call-lookup_user_not_found), and it actually caught a real bug: ToolReference::extractStructuredContent() was passing the raw [TextContent, ResourceLink] return straight through as structuredContent, which serializes to a JSON list — the inspector's MCP client rejected the tool call outright since the spec requires structuredContent to be an object. Fixed by skipping structured-content extraction whenever the raw result contains a Content instance, since those are already reflected in content. Added a unit test for that in RegistryTest.

Ran the full suite locally (Node 20+ for inspector, since 18 can't npx it): unit suite (842 tests), the full tests/Inspector suite, php-cs-fixer, phpstan, and composer validate --strict all green.