refactor: Separate Registry concerns following SOLID principles [WIP]

- Extract ReferenceProvider and ReferenceRegistryInterface interfaces
- Create DefaultToolExecutor with ReferenceHandlerInterface
- Remove execution responsibility from Registry class
- Enable custom handler and executor implementations

Author: butschster

src/Capability/Registry.php

@@ -13,17 +13,15 @@
 
 use Mcp\Capability\Registry\ElementReference;
 use Mcp\Capability\Registry\PromptReference;
-use Mcp\Capability\Registry\ReferenceHandler;
+use Mcp\Capability\Registry\ReferenceProviderInterface;
+use Mcp\Capability\Registry\ReferenceRegistryInterface;
 use Mcp\Capability\Registry\ResourceReference;
 use Mcp\Capability\Registry\ResourceTemplateReference;
 use Mcp\Capability\Registry\ToolReference;
 use Mcp\Event\PromptListChangedEvent;
 use Mcp\Event\ResourceListChangedEvent;
 use Mcp\Event\ResourceTemplateListChangedEvent;
 use Mcp\Event\ToolListChangedEvent;
-use Mcp\Exception\InvalidArgumentException;
-use Mcp\Schema\Content\PromptMessage;
-use Mcp\Schema\Content\ResourceContents;
 use Mcp\Schema\Prompt;
 use Mcp\Schema\Resource;
 use Mcp\Schema\ResourceTemplate;
@@ -36,9 +34,14 @@
 /**
  * @phpstan-import-type CallableArray from ElementReference
  *
+ * Registry implementation that manages MCP element registration and access.
+ * Implements both ReferenceProvider (for access) and ReferenceRegistry (for registration)
+ * following the Interface Segregation Principle.
+ *
  * @author Kyrian Obikwelu <[email protected]>
+ * @author Pavel Buchnev   <[email protected]>
  */
-class Registry
+final class Registry implements ReferenceProviderInterface, ReferenceRegistryInterface
 {
     /**
      * @var array<string, ToolReference>
@@ -61,11 +64,11 @@ class Registry
     private array $resourceTemplates = [];
 
     public function __construct(
-        private readonly ReferenceHandler $referenceHandler = new ReferenceHandler(),
         private readonly ?EventDispatcherInterface $eventDispatcher = null,
         private readonly LoggerInterface $logger = new NullLogger(),
-    ) {
-    }
+    ) {}
+
+    // === ReferenceRegistry interface methods ===
 
     public function getCapabilities(): ServerCapabilities
     {
@@ -74,14 +77,14 @@ public function getCapabilities(): ServerCapabilities
         }
 
         return new ServerCapabilities(
-            tools: true, // [] !== $this->tools,
+            tools: [] !== $this->tools,
             toolsListChanged: $this->eventDispatcher instanceof EventDispatcherInterface,
             resources: [] !== $this->resources || [] !== $this->resourceTemplates,
             resourcesSubscribe: false,
             resourcesListChanged: $this->eventDispatcher instanceof EventDispatcherInterface,
             prompts: [] !== $this->prompts,
             promptsListChanged: $this->eventDispatcher instanceof EventDispatcherInterface,
-            logging: false, // true,
+            logging: false,
             completions: true,
         );
     }
@@ -95,7 +98,9 @@ public function registerTool(Tool $tool, callable|array|string $handler, bool $i
         $existing = $this->tools[$toolName] ?? null;
 
         if ($existing && !$isManual && $existing->isManual) {
-            $this->logger->debug("Ignoring discovered tool '{$toolName}' as it conflicts with a manually registered one.");
+            $this->logger->debug(
+                "Ignoring discovered tool '{$toolName}' as it conflicts with a manually registered one.",
+            );
 
             return;
         }
@@ -114,7 +119,9 @@ public function registerResource(Resource $resource, callable|array|string $hand
         $existing = $this->resources[$uri] ?? null;
 
         if ($existing && !$isManual && $existing->isManual) {
-            $this->logger->debug("Ignoring discovered resource '{$uri}' as it conflicts with a manually registered one.");
+            $this->logger->debug(
+                "Ignoring discovered resource '{$uri}' as it conflicts with a manually registered one.",
+            );
 
             return;
         }
@@ -125,7 +132,7 @@ public function registerResource(Resource $resource, callable|array|string $hand
     }
 
     /**
-     * @param callable|CallableArray|string      $handler
+     * @param callable|CallableArray|string $handler
      * @param array<string, class-string|object> $completionProviders
      */
     public function registerResourceTemplate(
@@ -138,18 +145,25 @@ public function registerResourceTemplate(
         $existing = $this->resourceTemplates[$uriTemplate] ?? null;
 
         if ($existing && !$isManual && $existing->isManual) {
-            $this->logger->debug("Ignoring discovered template '{$uriTemplate}' as it conflicts with a manually registered one.");
+            $this->logger->debug(
+                "Ignoring discovered template '{$uriTemplate}' as it conflicts with a manually registered one.",
+            );
 
             return;
         }
 
-        $this->resourceTemplates[$uriTemplate] = new ResourceTemplateReference($template, $handler, $isManual, $completionProviders);
+        $this->resourceTemplates[$uriTemplate] = new ResourceTemplateReference(
+            $template,
+            $handler,
+            $isManual,
+            $completionProviders,
+        );
 
         $this->eventDispatcher?->dispatch(new ResourceTemplateListChangedEvent());
     }
 
     /**
-     * @param callable|CallableArray|string      $handler
+     * @param callable|CallableArray|string $handler
      * @param array<string, class-string|object> $completionProviders
      */
     public function registerPrompt(
@@ -162,7 +176,9 @@ public function registerPrompt(
         $existing = $this->prompts[$promptName] ?? null;
 
         if ($existing && !$isManual && $existing->isManual) {
-            $this->logger->debug("Ignoring discovered prompt '{$promptName}' as it conflicts with a manually registered one.");
+            $this->logger->debug(
+                "Ignoring discovered prompt '{$promptName}' as it conflicts with a manually registered one.",
+            );
 
             return;
         }
@@ -172,17 +188,6 @@ public function registerPrompt(
         $this->eventDispatcher?->dispatch(new PromptListChangedEvent());
     }
 
-    /**
-     * Checks if any elements (manual or discovered) are currently registered.
-     */
-    public function hasElements(): bool
-    {
-        return !empty($this->tools)
-            || !empty($this->resources)
-            || !empty($this->prompts)
-            || !empty($this->resourceTemplates);
-    }
-
     /**
      * Clear discovered elements from registry.
      */
@@ -220,43 +225,17 @@ public function clear(): void
         }
     }
 
-    public function handleCallTool(string $name, array $arguments): array
-    {
-        $reference = $this->getTool($name);
-
-        if (null === $reference) {
-            throw new InvalidArgumentException(\sprintf('Tool "%s" is not registered.', $name));
-        }
-
-        return $reference->formatResult(
-            $this->referenceHandler->handle($reference, $arguments)
-        );
-    }
+    // === ReferenceProvider interface methods ===
 
     public function getTool(string $name): ?ToolReference
     {
         return $this->tools[$name] ?? null;
     }
 
-    /**
-     * @return ResourceContents[]
-     */
-    public function handleReadResource(string $uri): array
-    {
-        $reference = $this->getResource($uri);
-
-        if (null === $reference) {
-            throw new InvalidArgumentException(\sprintf('Resource "%s" is not registered.', $uri));
-        }
-
-        return $reference->formatResult(
-            $this->referenceHandler->handle($reference, ['uri' => $uri]),
-            $uri,
-        );
-    }
-
-    public function getResource(string $uri, bool $includeTemplates = true): ResourceReference|ResourceTemplateReference|null
-    {
+    public function getResource(
+        string $uri,
+        bool $includeTemplates = true,
+    ): ResourceReference|ResourceTemplateReference|null {
         $registration = $this->resources[$uri] ?? null;
         if ($registration) {
             return $registration;
@@ -282,22 +261,6 @@ public function getResourceTemplate(string $uriTemplate): ?ResourceTemplateRefer
         return $this->resourceTemplates[$uriTemplate] ?? null;
     }
 
-    /**
-     * @return PromptMessage[]
-     */
-    public function handleGetPrompt(string $name, ?array $arguments): array
-    {
-        $reference = $this->getPrompt($name);
-
-        if (null === $reference) {
-            throw new InvalidArgumentException(\sprintf('Prompt "%s" is not registered.', $name));
-        }
-
-        return $reference->formatResult(
-            $this->referenceHandler->handle($reference, $arguments)
-        );
-    }
-
     public function getPrompt(string $name): ?PromptReference
     {
         return $this->prompts[$name] ?? null;
@@ -308,28 +271,42 @@ public function getPrompt(string $name): ?PromptReference
      */
     public function getTools(): array
     {
-        return array_map(fn (ToolReference $tool) => $tool->tool, $this->tools);
+        return array_map(fn(ToolReference $tool) => $tool->tool, $this->tools);
     }
 
     /**
      * @return array<string, resource>
      */
     public function getResources(): array
     {
-        return array_map(fn (ResourceReference $resource) => $resource->schema, $this->resources);
+        return array_map(fn(ResourceReference $resource) => $resource->schema, $this->resources);
     }
 
     /**
      * @return array<string, Prompt>
      */
     public function getPrompts(): array
     {
-        return array_map(fn (PromptReference $prompt) => $prompt->prompt, $this->prompts);
+        return array_map(fn(PromptReference $prompt) => $prompt->prompt, $this->prompts);
     }
 
-    /** @return array<string, ResourceTemplate> */
+    /**
+     * @return array<string, ResourceTemplate>
+     */
     public function getResourceTemplates(): array
     {
-        return array_map(fn ($template) => $template->resourceTemplate, $this->resourceTemplates);
+        return array_map(fn(ResourceTemplateReference $template) => $template->resourceTemplate,
+            $this->resourceTemplates);
+    }
+
+    /**
+     * Checks if any elements (manual or discovered) are currently registered.
+     */
+    public function hasElements(): bool
+    {
+        return !empty($this->tools)
+            || !empty($this->resources)
+            || !empty($this->prompts)
+            || !empty($this->resourceTemplates);
     }
 }

src/Capability/Registry/ReferenceHandler.php

@@ -18,7 +18,7 @@
 /**
  * @author Kyrian Obikwelu <[email protected]>
  */
-class ReferenceHandler
+final class ReferenceHandler implements ReferenceHandlerInterface
 {
     public function __construct(
         private readonly ?ContainerInterface $container = null,

src/Capability/Registry/ReferenceHandlerInterface.php

@@ -0,0 +1,34 @@
+<?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\Capability\Registry;
+
+/**
+ * Interface for handling execution of MCP elements.
+ * Allows custom implementations of element execution logic.
+ *
+ * @author Pavel Buchnev <[email protected]>
+ */
+interface ReferenceHandlerInterface
+{
+    /**
+     * Handles execution of an MCP element reference.
+     *
+     * @param ElementReference     $reference the element reference to execute
+     * @param array<string, mixed> $arguments arguments to pass to the handler
+     *
+     * @return mixed the result of the element execution
+     *
+     * @throws \Mcp\Exception\InvalidArgumentException if the handler is invalid
+     * @throws \Mcp\Exception\RegistryException        if execution fails
+     */
+    public function handle(ElementReference $reference, array $arguments): mixed;
+}