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][Server] Add MCP Apps extension (io.modelcontextprotocol/ui) support (#281)

Browse source 
* feat: add MCP Apps extension (io.modelcontextprotocol/ui) support

Adds support for the MCP Apps protocol extension, which lets servers
expose interactive HTML UIs as resources rendered by spec-conforming
clients (e.g. Goose) in sandboxed iframes.

- Generic extension plumbing: ServerExtensionInterface and
  Builder::enableExtension(), with extensions advertised under
  capabilities.extensions during the initialize handshake.
  ClientCapabilities/ServerCapabilities gain an extensions field.
- Schema DTOs under Mcp\Schema\Extension\Apps: the McpApps marker,
  UiToolMeta, ToolVisibility enum, UiResourceContentMeta,
  UiResourceCsp, and UiResourcePermissions (with empty-object
  presence markers per spec).
- A worked weather example under examples/server/mcp-apps/ with a
  minimal spec-conforming view (ui/initialize handshake, postMessage
  JSONRPCMessage objects, and ResizeObserver-driven size reporting).
- docs/extensions.md guide with pointers from index.md and
  examples.md to the ext-apps repository for the TypeScript SDK and
  richer view-side patterns.
- Unit and inspector snapshot test coverage.

Spec: https://github.com/modelcontextprotocol/ext-apps

* Type UiToolMeta visibility as ToolVisibility enum

Also fix UiResourceContentMeta::jsonSerialize() return phpdoc.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Address review nitpicks for MCP Apps extension

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Apply PR review feedback for MCP Apps extension

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Add regression tests and CHANGELOG entry for capabilities extensions

- Pin the is_array() guards on extensions in ServerCapabilities and
  ClientCapabilities::fromArray() with explicit non-array payload tests.
- Pin the isset()-rejects-null contract in UiResourcePermissions::fromArray().
- Surface the new extensions field on both capability classes in CHANGELOG.
- Inline the ?: idiom in Builder::build() to match the surrounding style.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Christopher Hertel 2026-06-01 09:35:54 +01:00 • committed by GitHub
commit d150772e24
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 1632 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

52
tests/Inspector/Stdio/StdioMcpAppsTest.php Normal file
View file

@ -0,0 +1,52 @@
<?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 Inspector;
use Mcp\Tests\Inspector\Stdio\StdioInspectorSnapshotTestCase;
final class StdioMcpAppsTest extends StdioInspectorSnapshotTestCase
{
public static function provideMethods(): array
{
return [
...parent::provideMethods(),
'Read Weather UI Resource' => [
'method' => 'resources/read',
'options' => [
'uri' => 'ui://weather-app',
],
'testName' => 'read_weather_ui',
],
'Get Weather Tool Call (London)' => [
'method' => 'tools/call',
'options' => [
'toolName' => 'get_weather',
'toolArgs' => ['city' => 'London'],
],
'testName' => 'get_weather_london',
],
'Get Weather Tool Call (Tokyo)' => [
'method' => 'tools/call',
'options' => [
'toolName' => 'get_weather',
'toolArgs' => ['city' => 'Tokyo'],
],
'testName' => 'get_weather_tokyo',
],
];
}
protected function getServerScript(): string
{
return \dirname(__DIR__, 3).'/examples/server/mcp-apps/server.php';
}
}

3
tests/Inspector/Stdio/snapshots/StdioMcpAppsTest-prompts_list.json Normal file
View file

@ -0,0 +1,3 @@
{
"prompts": []
}

13
tests/Inspector/Stdio/snapshots/StdioMcpAppsTest-resources_list.json Normal file
View file

@ -0,0 +1,13 @@
{
"resources": [
{
"name": "weather-app",
"uri": "ui://weather-app",
"description": "Interactive weather dashboard",
"mimeType": "text/html;profile=mcp-app",
"_meta": {
"ui": {}
}
}
]
}

22
tests/Inspector/Stdio/snapshots/StdioMcpAppsTest-resources_read-read_weather_ui.json Normal file
View file

File diff suppressed because one or more lines are too long

3
tests/Inspector/Stdio/snapshots/StdioMcpAppsTest-resources_templates_list.json Normal file
View file

@ -0,0 +1,3 @@
{
"resourceTemplates": []
}

9
tests/Inspector/Stdio/snapshots/StdioMcpAppsTest-tools_call-get_weather_london.json Normal file
View file

@ -0,0 +1,9 @@
{
"content": [
{
"type": "text",
"text": "Weather in London: 15°C, Cloudy, Humidity: 78%"
}
],
"isError": false
}

9
tests/Inspector/Stdio/snapshots/StdioMcpAppsTest-tools_call-get_weather_tokyo.json Normal file
View file

@ -0,0 +1,9 @@
{
"content": [
{
"type": "text",
"text": "Weather in Tokyo: 22°C, Partly Cloudy, Humidity: 65%"
}
],
"isError": false
}

28
tests/Inspector/Stdio/snapshots/StdioMcpAppsTest-tools_list.json Normal file
View file

@ -0,0 +1,28 @@
{
"tools": [
{
"name": "get_weather",
"description": "Get current weather for a city",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": [
"city"
]
},
"_meta": {
"ui": {
"resourceUri": "ui://weather-app",
"visibility": [
"model",
"app"
]
}
}
}
]
}

223
tests/Unit/Schema/Extension/Apps/McpAppsTest.php Normal file
View file

@ -0,0 +1,223 @@
<?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\Extension\Apps;
use Mcp\Schema\Extension\Apps\McpApps;
use Mcp\Schema\Extension\Apps\ToolVisibility;
use Mcp\Schema\Extension\Apps\UiResourceContentMeta;
use Mcp\Schema\Extension\Apps\UiResourceCsp;
use Mcp\Schema\Extension\Apps\UiResourcePermissions;
use Mcp\Schema\Extension\Apps\UiToolMeta;
use PHPUnit\Framework\TestCase;
class McpAppsTest extends TestCase
{
public function testServerExtensionInterface(): void
{
$extension = new McpApps();
$this->assertSame('io.modelcontextprotocol/ui', $extension->getId());
$this->assertSame(['mimeTypes' => ['text/html;profile=mcp-app']], $extension->getCapabilities());
}
public function testUiResourceCspSerialization(): void
{
$csp = new UiResourceCsp(
connectDomains: ['https://api.example.com'],
resourceDomains: ['https://cdn.example.com'],
frameDomains: ['https://embed.example.com'],
baseUriDomains: ['https://example.com'],
);
$serialized = $csp->jsonSerialize();
$this->assertSame(['https://api.example.com'], $serialized['connectDomains']);
$this->assertSame(['https://cdn.example.com'], $serialized['resourceDomains']);
$this->assertSame(['https://embed.example.com'], $serialized['frameDomains']);
$this->assertSame(['https://example.com'], $serialized['baseUriDomains']);
}
public function testUiResourceCspOmitsNullFields(): void
{
$csp = new UiResourceCsp(connectDomains: ['https://api.example.com']);
$serialized = $csp->jsonSerialize();
$this->assertArrayHasKey('connectDomains', $serialized);
$this->assertArrayNotHasKey('resourceDomains', $serialized);
$this->assertArrayNotHasKey('frameDomains', $serialized);
$this->assertArrayNotHasKey('baseUriDomains', $serialized);
}
public function testUiResourceCspFromArray(): void
{
$csp = UiResourceCsp::fromArray([
'connectDomains' => ['https://api.example.com'],
'frameDomains' => ['https://embed.example.com'],
]);
$this->assertSame(['https://api.example.com'], $csp->connectDomains);
$this->assertNull($csp->resourceDomains);
$this->assertSame(['https://embed.example.com'], $csp->frameDomains);
$this->assertNull($csp->baseUriDomains);
}
public function testUiResourcePermissionsSerialization(): void
{
$perms = new UiResourcePermissions(
camera: true,
microphone: false,
geolocation: true,
clipboardWrite: false,
);
$serialized = $perms->jsonSerialize();
// Per spec, each requested permission is an empty object marker.
$this->assertEquals(new \stdClass(), $serialized['camera']);
$this->assertArrayNotHasKey('microphone', $serialized);
$this->assertEquals(new \stdClass(), $serialized['geolocation']);
$this->assertArrayNotHasKey('clipboardWrite', $serialized);
$this->assertSame('{"camera":{},"geolocation":{}}', json_encode($perms));
}
public function testUiResourcePermissionsOmitsUnrequestedFields(): void
{
$perms = new UiResourcePermissions(clipboardWrite: true);
$serialized = $perms->jsonSerialize();
$this->assertArrayNotHasKey('camera', $serialized);
$this->assertArrayNotHasKey('microphone', $serialized);
$this->assertArrayNotHasKey('geolocation', $serialized);
$this->assertArrayHasKey('clipboardWrite', $serialized);
}
public function testUiResourcePermissionsFromArray(): void
{
// Spec wire shape: presence indicates a request; the value is an empty object.
$perms = UiResourcePermissions::fromArray([
'camera' => [],
'clipboardWrite' => [],
]);
$this->assertTrue($perms->camera);
$this->assertFalse($perms->microphone);
$this->assertFalse($perms->geolocation);
$this->assertTrue($perms->clipboardWrite);
}
public function testUiResourcePermissionsFromArrayTreatsNullAsNotRequested(): void
{
// isset() rejects null values, so 'camera' => null must read as "not requested",
// not as "requested with a null marker".
// @phpstan-ignore-next-line — intentionally off-spec payload
$perms = UiResourcePermissions::fromArray(['camera' => null, 'geolocation' => []]);
$this->assertFalse($perms->camera);
$this->assertTrue($perms->geolocation);
}
public function testUiResourceContentMetaSerialization(): void
{
$meta = new UiResourceContentMeta(
csp: new UiResourceCsp(connectDomains: ['https://api.example.com']),
permissions: new UiResourcePermissions(clipboardWrite: true),
domain: 'example.com',
prefersBorder: true,
);
$serialized = $meta->jsonSerialize();
$this->assertArrayHasKey('csp', $serialized);
$this->assertArrayHasKey('permissions', $serialized);
$this->assertSame('example.com', $serialized['domain']);
$this->assertTrue($serialized['prefersBorder']);
}
public function testUiResourceContentMetaOmitsNullFields(): void
{
$meta = new UiResourceContentMeta(prefersBorder: true);
$serialized = $meta->jsonSerialize();
$this->assertArrayNotHasKey('csp', $serialized);
$this->assertArrayNotHasKey('permissions', $serialized);
$this->assertArrayNotHasKey('domain', $serialized);
$this->assertArrayHasKey('prefersBorder', $serialized);
}
public function testUiResourceContentMetaFromArray(): void
{
$meta = UiResourceContentMeta::fromArray([
'csp' => ['connectDomains' => ['https://api.example.com']],
'permissions' => ['clipboardWrite' => []],
'domain' => 'example.com',
'prefersBorder' => false,
]);
$this->assertInstanceOf(UiResourceCsp::class, $meta->csp);
$this->assertSame(['https://api.example.com'], $meta->csp->connectDomains);
$this->assertInstanceOf(UiResourcePermissions::class, $meta->permissions);
$this->assertTrue($meta->permissions->clipboardWrite);
$this->assertSame('example.com', $meta->domain);
$this->assertFalse($meta->prefersBorder);
}
public function testUiToolMetaSerialization(): void
{
$meta = new UiToolMeta(
resourceUri: 'ui://my-app',
visibility: [ToolVisibility::Model, ToolVisibility::App],
);
$serialized = $meta->jsonSerialize();
$this->assertSame('ui://my-app', $serialized['resourceUri']);
$this->assertSame(['model', 'app'], $serialized['visibility']);
}
public function testUiToolMetaOmitsNullFields(): void
{
$meta = new UiToolMeta(resourceUri: 'ui://my-app');
$serialized = $meta->jsonSerialize();
$this->assertArrayHasKey('resourceUri', $serialized);
$this->assertArrayNotHasKey('visibility', $serialized);
}
public function testUiToolMetaFromArray(): void
{
$meta = UiToolMeta::fromArray([
'resourceUri' => 'ui://my-app',
'visibility' => ['app'],
]);
$this->assertSame('ui://my-app', $meta->resourceUri);
$this->assertSame([ToolVisibility::App], $meta->visibility);
}
public function testToolVisibilityEnum(): void
{
$this->assertSame('model', ToolVisibility::Model->value);
$this->assertSame('app', ToolVisibility::App->value);
}
public function testResourceMarkerSerializesToEmptyObject(): void
{
$marker = McpApps::resourceMarker();
$this->assertEquals(new \stdClass(), $marker);
$this->assertSame('{}', json_encode($marker));
}
}

232
tests/Unit/Schema/Extension/CapabilitiesExtensionsTest.php Normal file
View file

@ -0,0 +1,232 @@
<?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\Extension;
use Mcp\Schema\ClientCapabilities;
use Mcp\Schema\Extension\Apps\McpApps;
use Mcp\Schema\ServerCapabilities;
use PHPUnit\Framework\TestCase;
class CapabilitiesExtensionsTest extends TestCase
{
public function testServerCapabilitiesWithExtensions(): void
{
$extensions = [
McpApps::EXTENSION_ID => (new McpApps())->getCapabilities(),
];
$caps = new ServerCapabilities(
tools: true,
resources: true,
extensions: $extensions,
);
$this->assertSame($extensions, $caps->extensions);
}
public function testServerCapabilitiesExtensionsDefaultNull(): void
{
$caps = new ServerCapabilities();
$this->assertNull($caps->extensions);
}
public function testServerCapabilitiesJsonSerializeWithExtensions(): void
{
$caps = new ServerCapabilities(
tools: true,
resources: true,
prompts: false,
extensions: [
McpApps::EXTENSION_ID => (new McpApps())->getCapabilities(),
],
);
$json = $caps->jsonSerialize();
$this->assertArrayHasKey('extensions', $json);
$this->assertObjectHasProperty(McpApps::EXTENSION_ID, $json['extensions']);
}
public function testServerCapabilitiesJsonSerializeWithoutExtensions(): void
{
$caps = new ServerCapabilities(tools: true);
$json = $caps->jsonSerialize();
$this->assertArrayNotHasKey('extensions', $json);
}
public function testServerCapabilitiesFromArrayWithExtensions(): void
{
$data = [
'tools' => new \stdClass(),
'extensions' => [
McpApps::EXTENSION_ID => ['mimeTypes' => ['text/html;profile=mcp-app']],
],
];
$caps = ServerCapabilities::fromArray($data);
$this->assertTrue($caps->tools);
$this->assertNotNull($caps->extensions);
$this->assertArrayHasKey(McpApps::EXTENSION_ID, $caps->extensions);
$this->assertSame(['text/html;profile=mcp-app'], $caps->extensions[McpApps::EXTENSION_ID]['mimeTypes']);
}
public function testServerCapabilitiesFromArrayWithoutExtensions(): void
{
$caps = ServerCapabilities::fromArray(['tools' => new \stdClass()]);
$this->assertNull($caps->extensions);
}
public function testServerCapabilitiesFromArrayRejectsNonArrayExtensions(): void
{
// @phpstan-ignore-next-line — intentionally malformed payload
$caps = ServerCapabilities::fromArray(['tools' => new \stdClass(), 'extensions' => 'not-an-array']);
$this->assertNull($caps->extensions);
}
public function testServerCapabilitiesWithExtensionsMerges(): void
{
$caps = new ServerCapabilities(
tools: true,
extensions: ['a' => ['x' => 1], 'b' => ['y' => 2]],
);
$merged = $caps->withExtensions(['b' => ['y' => 99], 'c' => ['z' => 3]]);
$this->assertSame(['x' => 1], $merged->extensions['a']);
$this->assertSame(['y' => 99], $merged->extensions['b'], 'new entry overrides existing id');
$this->assertSame(['z' => 3], $merged->extensions['c']);
$this->assertSame(['a' => ['x' => 1], 'b' => ['y' => 2]], $caps->extensions, 'original is unchanged');
}
public function testClientCapabilitiesWithExtensions(): void
{
$extensions = [
McpApps::EXTENSION_ID => (new McpApps())->getCapabilities(),
];
$caps = new ClientCapabilities(
extensions: $extensions,
);
$this->assertSame($extensions, $caps->extensions);
}
public function testClientCapabilitiesExtensionsDefaultNull(): void
{
$caps = new ClientCapabilities();
$this->assertNull($caps->extensions);
}
public function testClientCapabilitiesJsonSerializeWithExtensions(): void
{
$caps = new ClientCapabilities(
extensions: [
McpApps::EXTENSION_ID => (new McpApps())->getCapabilities(),
],
);
$json = $caps->jsonSerialize();
$this->assertArrayHasKey('extensions', $json);
$this->assertObjectHasProperty(McpApps::EXTENSION_ID, $json['extensions']);
}
public function testClientCapabilitiesJsonSerializeWithoutExtensions(): void
{
$caps = new ClientCapabilities();
$json = $caps->jsonSerialize();
// ClientCapabilities returns \stdClass when empty (so it serializes as `{}`, not `[]`).
if (\is_array($json)) {
$this->assertArrayNotHasKey('extensions', $json);
} else {
$this->assertObjectNotHasProperty('extensions', $json);
}
}
public function testClientCapabilitiesFromArrayWithExtensions(): void
{
$data = [
'roots' => ['listChanged' => true],
'extensions' => [
McpApps::EXTENSION_ID => ['mimeTypes' => ['text/html;profile=mcp-app']],
],
];
$caps = ClientCapabilities::fromArray($data);
$this->assertTrue($caps->roots);
$this->assertTrue($caps->rootsListChanged);
$this->assertNotNull($caps->extensions);
$this->assertArrayHasKey(McpApps::EXTENSION_ID, $caps->extensions);
}
public function testClientCapabilitiesFromArrayWithoutExtensions(): void
{
$caps = ClientCapabilities::fromArray(['roots' => ['listChanged' => true]]);
$this->assertNull($caps->extensions);
}
public function testClientCapabilitiesFromArrayRejectsNonArrayExtensions(): void
{
// @phpstan-ignore-next-line — intentionally malformed payload
$caps = ClientCapabilities::fromArray(['roots' => ['listChanged' => true], 'extensions' => 'not-an-array']);
$this->assertNull($caps->extensions);
}
public function testBackwardCompatibilityServerCapabilities(): void
{
$caps = new ServerCapabilities(
tools: true,
toolsListChanged: false,
resources: true,
resourcesSubscribe: false,
resourcesListChanged: false,
prompts: true,
promptsListChanged: false,
logging: false,
completions: false,
experimental: null,
);
$this->assertNull($caps->extensions);
$json = $caps->jsonSerialize();
$this->assertArrayNotHasKey('extensions', $json);
}
public function testBackwardCompatibilityClientCapabilities(): void
{
$caps = new ClientCapabilities(
roots: true,
rootsListChanged: true,
sampling: true,
elicitation: true,
experimental: null,
);
$this->assertNull($caps->extensions);
$json = $caps->jsonSerialize();
$this->assertArrayNotHasKey('extensions', $json);
}
}

57
tests/Unit/Server/BuilderTest.php
View file

@ -13,11 +13,15 @@ namespace Mcp\Tests\Unit\Server;
use Mcp\Capability\Registry\ElementReference;
use Mcp\Capability\Registry\ReferenceHandlerInterface;
use Mcp\Exception\LogicException;
use Mcp\Schema\Content\TextContent;
use Mcp\Schema\Extension\Apps\McpApps;
use Mcp\Schema\JsonRpc\Response;
use Mcp\Schema\Request\CallToolRequest;
use Mcp\Schema\ServerCapabilities;
use Mcp\Server;
use Mcp\Server\Handler\Request\CallToolHandler;
use Mcp\Server\Handler\Request\InitializeHandler;
use Mcp\Server\Session\SessionInterface;
use PHPUnit\Framework\Attributes\TestDox;
use PHPUnit\Framework\TestCase;
@ -79,6 +83,59 @@ final class BuilderTest extends TestCase
$this->assertSame('intercepted', $result);
}
#[TestDox('enableExtension() registers an extension and announces its capability payload')]
public function testEnableExtensionRegistersExtension(): void
{
$server = Server::builder()
->setServerInfo('test', '1.0.0')
->enableExtension(new McpApps())
->build();
$capabilities = $this->extractServerCapabilities($server);
$this->assertNotNull($capabilities->extensions);
$this->assertArrayHasKey(McpApps::EXTENSION_ID, $capabilities->extensions);
$this->assertSame(['mimeTypes' => [McpApps::MIME_TYPE]], $capabilities->extensions[McpApps::EXTENSION_ID]);
}
#[TestDox('enableExtension() throws when the same extension is enabled twice')]
public function testEnableExtensionRejectsDuplicate(): void
{
$this->expectException(LogicException::class);
$this->expectExceptionMessage(McpApps::EXTENSION_ID);
Server::builder()->enableExtension(new McpApps(), new McpApps());
}
#[TestDox('enableExtension() extensions are merged into capabilities set via setCapabilities()')]
public function testEnableExtensionMergesIntoCustomCapabilities(): void
{
$server = Server::builder()
->setServerInfo('test', '1.0.0')
->setCapabilities(new ServerCapabilities(tools: true))
->enableExtension(new McpApps())
->build();
$capabilities = $this->extractServerCapabilities($server);
$this->assertNotNull($capabilities->extensions);
$this->assertArrayHasKey(McpApps::EXTENSION_ID, $capabilities->extensions);
}
private function extractServerCapabilities(Server $server): ServerCapabilities
{
$protocol = (new \ReflectionClass($server))->getProperty('protocol')->getValue($server);
$requestHandlers = (new \ReflectionClass($protocol))->getProperty('requestHandlers')->getValue($protocol);
foreach ($requestHandlers as $handler) {
if ($handler instanceof InitializeHandler) {
return $handler->configuration->capabilities;
}
}
$this->fail('InitializeHandler not found in request handlers');
}
private function callTool(Server $server, string $toolName): mixed
{
$protocol = (new \ReflectionClass($server))->getProperty('protocol')->getValue($server);