[Schema][Server] Add MCP Apps extension (io.modelcontextprotocol/ui) support (#281)

* 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>

tests/Unit/Server/BuilderTest.php

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