Apply PR review feedback for MCP Apps extension

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

Author: chr-hertel

docs/extensions.md

@@ -9,17 +9,18 @@ use Mcp\Server;
 
 $server = Server::builder()
     ->setServerInfo('My Server', '1.0.0')
-    ->enableExtension(McpApps::class) // or pre-built instances
+    ->enableExtension(new McpApps())
     ->build();
 ```
 
-Pass either a class string (the extension is instantiated with no arguments) or
-a pre-built `ServerExtensionInterface` instance. Multiple extensions can be
-enabled in a single call.
+Pass one or more `ServerExtensionInterface` instances; multiple extensions can
+be enabled in a single call. Enabling the same extension twice throws a
+`LogicException`.
 
-> Note: calling `setCapabilities()` overrides automatic capability detection,
-> so it also overrides the `extensions` field. If you set your own
-> `ServerCapabilities`, include the extensions you want yourself.
+> Note: extensions enabled via `enableExtension()` are merged into the
+> `extensions` capability even when you supply your own `ServerCapabilities` via
+> `setCapabilities()`. An enabled extension overrides any entry under the same
+> id already present in those capabilities.
 
 ## MCP Apps (`io.modelcontextprotocol/ui`)
 
@@ -44,7 +45,7 @@ use Mcp\Schema\Extension\Apps\UiResourcePermissions;
 use Mcp\Schema\Extension\Apps\UiToolMeta;
 
 $server = Server::builder()
-    ->enableExtension(McpApps::class)
+    ->enableExtension(new McpApps())
     ->addResource(
         fn () => new TextResourceContents(
             uri: 'ui://my-app',
@@ -58,7 +59,7 @@ $server = Server::builder()
         ),
         'ui://my-app',
         mimeType: McpApps::MIME_TYPE,
-        meta: ['ui' => new \stdClass()],
+        meta: ['ui' => McpApps::resourceMarker()],
     )
     ->addTool(
         $myToolHandler,
@@ -71,6 +72,12 @@ $server = Server::builder()
     ->build();
 ```
 
+Note the two distinct `_meta.ui` shapes: the resource *descriptor* (its
+`resources/list` entry) carries only an empty marker — `McpApps::resourceMarker()` —
+flagging it as an MCP App, while the resource *content* returned by `resources/read`
+carries the structured `UiResourceContentMeta` with the actual CSP and permission
+configuration.
+
 ### Server-side DTOs
 
 | Class | Purpose |

examples/server/mcp-apps/server.php

@@ -24,17 +24,14 @@
 $server = Server::builder()
     ->setServerInfo('MCP Apps Weather Example', '1.0.0')
     ->setLogger(logger())
-    ->enableExtension(McpApps::class)
+    ->enableExtension(new McpApps())
     ->addResource(
         [WeatherApp::class, 'getWeatherApp'],
         'ui://weather-app',
         'weather-app',
         description: 'Interactive weather dashboard',
         mimeType: McpApps::MIME_TYPE,
-        // Empty `ui` marker on the resource descriptor flags it as an MCP App in
-        // resources/list. The CSP/permissions live on the resource *content* (_meta.ui
-        // in resources/read), set via UiResourceContentMeta in WeatherApp::getWeatherApp().
-        meta: ['ui' => new stdClass()],
+        meta: ['ui' => McpApps::resourceMarker()],
     )
     ->addTool(
         [WeatherApp::class, 'getWeather'],

examples/server/mcp-apps/weather-app.html

@@ -129,6 +129,8 @@
         let requestId = 0;
         const pending = new Map();
 
+        // Target origin is '*' because the iframe cannot know its parent's origin
+        // upfront; the host is responsible for validating event.origin on its side.
         function post(msg) { window.parent.postMessage(msg, '*'); }
 
         function sendRpc(method, params) {

src/Schema/ClientCapabilities.php

@@ -71,8 +71,8 @@ public static function fromArray(array $data): self
             $rootsListChanged,
             $sampling,
             $elicitation,
-            $data['experimental'] ?? null,
-            $data['extensions'] ?? null,
+            \is_array($data['experimental'] ?? null) ? $data['experimental'] : null,
+            \is_array($data['extensions'] ?? null) ? $data['extensions'] : null,
         );
     }
 

src/Schema/Extension/Apps/McpApps.php

@@ -43,4 +43,16 @@ public function getCapabilities(): array
     {
         return ['mimeTypes' => [self::MIME_TYPE]];
     }
+
+    /**
+     * The marker value for the `_meta.ui` field on a UI resource *descriptor*
+     * (its `resources/list` entry), flagging the resource as an MCP App.
+     *
+     * The structured CSP/permissions metadata instead belongs on the resource
+     * *content* (the `resources/read` payload) via {@see UiResourceContentMeta}.
+     */
+    public static function resourceMarker(): \stdClass
+    {
+        return new \stdClass();
+    }
 }

src/Schema/Extension/Apps/UiResourceCsp.php

@@ -62,16 +62,18 @@ public function jsonSerialize(): array
     {
         $data = [];
 
-        if (null !== $this->connectDomains) {
+        // The MCP Apps spec (2026-01-26) defines "empty or omitted" identically
+        // for every CSP allow-list, so empty arrays are dropped, not emitted as `[]`.
+        if ($this->connectDomains) {
             $data['connectDomains'] = $this->connectDomains;
         }
-        if (null !== $this->resourceDomains) {
+        if ($this->resourceDomains) {
             $data['resourceDomains'] = $this->resourceDomains;
         }
-        if (null !== $this->frameDomains) {
+        if ($this->frameDomains) {
             $data['frameDomains'] = $this->frameDomains;
         }
-        if (null !== $this->baseUriDomains) {
+        if ($this->baseUriDomains) {
             $data['baseUriDomains'] = $this->baseUriDomains;
         }
 

src/Schema/Extension/Apps/UiResourcePermissions.php

@@ -41,11 +41,13 @@ public function __construct(
      */
     public static function fromArray(array $data): self
     {
+        // A permission is requested when its key is present with the spec's `{}`
+        // marker; isset() accepts that (array/object forms) and rejects a stray null.
         return new self(
-            camera: \array_key_exists('camera', $data),
-            microphone: \array_key_exists('microphone', $data),
-            geolocation: \array_key_exists('geolocation', $data),
-            clipboardWrite: \array_key_exists('clipboardWrite', $data),
+            camera: isset($data['camera']),
+            microphone: isset($data['microphone']),
+            geolocation: isset($data['geolocation']),
+            clipboardWrite: isset($data['clipboardWrite']),
         );
     }
 

src/Schema/Extension/ServerExtensionInterface.php

@@ -30,6 +30,10 @@ public function getId(): string;
     /**
      * The capability payload announced for this extension.
      *
+     * The returned array is cast to an object and embedded under
+     * `capabilities.extensions[<id>]` in the initialize response, so every value
+     * must be JSON-serializable (scalars, arrays, or `JsonSerializable` objects).
+     *
      * @return array<string, mixed>
      */
     public function getCapabilities(): array;

src/Schema/ServerCapabilities.php

@@ -109,8 +109,32 @@ public static function fromArray(array $data): self
             promptsListChanged: $promptsListChanged,
             logging: $loggingEnabled,
             completions: $completionsEnabled,
-            experimental: $data['experimental'] ?? null,
-            extensions: $data['extensions'] ?? null,
+            experimental: \is_array($data['experimental'] ?? null) ? $data['experimental'] : null,
+            extensions: \is_array($data['extensions'] ?? null) ? $data['extensions'] : null,
+        );
+    }
+
+    /**
+     * Returns a copy with the given protocol extensions merged into the existing ones.
+     *
+     * Entries in $extensions override existing ones sharing the same id.
+     *
+     * @param array<string, array<string, mixed>> $extensions
+     */
+    public function withExtensions(array $extensions): self
+    {
+        return new self(
+            $this->tools,
+            $this->toolsListChanged,
+            $this->resources,
+            $this->resourcesSubscribe,
+            $this->resourcesListChanged,
+            $this->prompts,
+            $this->promptsListChanged,
+            $this->logging,
+            $this->completions,
+            $this->experimental,
+            [...$this->extensions ?? [], ...$extensions],
         );
     }
 

src/Server/Builder.php

@@ -26,6 +26,7 @@
 use Mcp\Capability\Registry\ReferenceHandlerInterface;
 use Mcp\Capability\RegistryInterface;
 use Mcp\Exception\InvalidArgumentException;
+use Mcp\Exception\LogicException;
 use Mcp\JsonRpc\MessageFactory;
 use Mcp\Schema\Annotations;
 use Mcp\Schema\Enum\ProtocolVersion;
@@ -240,22 +241,18 @@ public function setCapabilities(ServerCapabilities $serverCapabilities): self
      * Enable one or more MCP protocol extensions, announced to clients under
      * `capabilities.extensions` during the initialize handshake.
      *
-     * Pass either fully qualified class names (instantiated with no arguments) or
-     * pre-built instances.
-     *
-     * @param class-string<ServerExtensionInterface>|ServerExtensionInterface ...$extensions
+     * @throws LogicException if the same extension is enabled more than once
      */
-    public function enableExtension(string|ServerExtensionInterface ...$extensions): self
+    public function enableExtension(ServerExtensionInterface ...$extensions): self
     {
         foreach ($extensions as $extension) {
-            if (\is_string($extension)) {
-                if (!is_subclass_of($extension, ServerExtensionInterface::class)) {
-                    throw new InvalidArgumentException(\sprintf('Extension class "%s" must implement "%s".', $extension, ServerExtensionInterface::class));
-                }
-                $extension = new $extension();
+            $id = $extension->getId();
+
+            if (isset($this->extensions[$id])) {
+                throw new LogicException(\sprintf('Extension "%s" is already enabled.', $id));
             }
 
-            $this->extensions[$extension->getId()] = $extension->getCapabilities();
+            $this->extensions[$id] = $extension->getCapabilities();
         }
 
         return $this;
@@ -621,6 +618,12 @@ public function build(): Server
             extensions: [] !== $this->extensions ? $this->extensions : null,
         );
 
+        // Extensions enabled via enableExtension() are folded into caller-supplied
+        // capabilities too, so setCapabilities() does not silently drop them.
+        if (null !== $this->serverCapabilities && [] !== $this->extensions) {
+            $capabilities = $capabilities->withExtensions($this->extensions);
+        }
+
         $serverInfo = $this->serverInfo ?? new Implementation();
         $configuration = new Configuration($serverInfo, $capabilities, $this->paginationLimit, $this->instructions, $this->protocolVersion);
         $referenceHandler = $this->referenceHandler ?? new ReferenceHandler($container);