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

src/Server/Builder.php

@@ -28,9 +28,11 @@ use Mcp\Capability\Registry\ReferenceHandler;
 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;
+use Mcp\Schema\Extension\ServerExtensionInterface;
 use Mcp\Schema\Icon;
 use Mcp\Schema\Implementation;
 use Mcp\Schema\Prompt;
@@ -207,6 +209,11 @@ final class Builder
 
     private ?ServerCapabilities $serverCapabilities = null;
 
+    /**
+     * @var array<string, array<string, mixed>>
+     */
+    private array $extensions = [];
+
     /**
      * @var LoaderInterface[]
      */
@@ -263,6 +270,27 @@ final class Builder
         return $this;
     }
 
+    /**
+     * Enable one or more MCP protocol extensions, announced to clients under
+     * `capabilities.extensions` during the initialize handshake.
+     *
+     * @throws LogicException if the same extension is enabled more than once
+     */
+    public function enableExtension(ServerExtensionInterface ...$extensions): self
+    {
+        foreach ($extensions as $extension) {
+            $id = $extension->getId();
+
+            if (isset($this->extensions[$id])) {
+                throw new LogicException(\sprintf('Extension "%s" is already enabled.', $id));
+            }
+
+            $this->extensions[$id] = $extension->getCapabilities();
+        }
+
+        return $this;
+    }
+
     /**
      * Register a single custom method handler.
      *
@@ -661,8 +689,15 @@ final class Builder
             promptsListChanged: $this->eventDispatcher instanceof EventDispatcherInterface,
             logging: true,
             completions: true,
+            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);