Merge pull request #8 from llm-agents-php/feature/registry-refactoring

Registry refactoring

Author: butschster

composer.json

@@ -48,7 +48,7 @@
   },
   "autoload-dev": {
     "psr-4": {
-      "Mcp\\Server\\Tests\\": "tests/Unit"
+      "Mcp\\Server\\Tests\\": "tests"
     }
   },
   "scripts": {

context.yaml

@@ -27,30 +27,37 @@ documents:
           - tests
           - vendor
 
-  - description: Source codes
-    outputPath: source-codes.md
+  - description: Dispatcher
+    outputPath: src/dispatcher.md
     sources:
       - type: file
         sourcePaths:
-          - src
-        notPath:
-          - Attributes
-          - Transports
-          - Session
-          - Defaults
-          - Utils/DocBlockParser.php
-          - Utils/SchemaGenerator.php
+          - src/Dispatcher.php
+          - src/Dispatcher
+          - src/Contracts/DispatcherInterface.php
 
-  - description: Dispatcher
-    outputPath: src/dispatcher.md
+  - description: CompletionProvider
+    outputPath: src/completion-provider.md
     sources:
       - type: file
         sourcePaths:
-          - src/Dispatcher.php
-          - src/DispatcherRoutesFactory.php
-          - src/Contracts/DispatcherRoutesFactoryInterface.php
-          - src/Routes
-          - src/Contracts/RouteInterface.php
+          - src/Defaults/EnumCompletionProvider.php
+          - src/Defaults/ListCompletionProvider.php
+          - src/Contracts/CompletionProviderInterface.php
+
+  - description: Tool executor
+    outputPath: src/tool-executor.md
+    sources:
+      - type: file
+        sourcePaths:
+          - src/Contracts/ToolExecutorInterface.php
+          - src/Defaults/ToolExecutor.php
+          - vendor/php-mcp/schema/src/Content/Content.php
+          - vendor/php-mcp/schema/src/Content/TextContent.php
+          - src/Exception/ToolNotFoundException.php
+          - src/Elements/RegisteredTool.php
+          - vendor/php-mcp/schema/src/Tool.php
+          - tests/Unit/Defaults/ToolExecutorTest.php
 
   - description: Resources
     outputPath: src/resources.md

src/Contracts/DispatcherInterface.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mcp\Server\Contracts;
+
+use Mcp\Server\Context;
+use Mcp\Server\Exception\McpServerException;
+use PhpMcp\Schema\JsonRpc\Notification;
+use PhpMcp\Schema\JsonRpc\Request;
+use PhpMcp\Schema\JsonRpc\Result;
+
+interface DispatcherInterface
+{
+    /**
+     * @throws McpServerException
+     */
+    public function handleRequest(Request $request, Context $context): Result;
+
+    public function handleNotification(Notification $notification, Context $context): void;
+}

src/Contracts/ReferenceProviderInterface.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mcp\Server\Contracts;
+
+use Mcp\Server\Elements\RegisteredPrompt;
+use Mcp\Server\Elements\RegisteredResource;
+use Mcp\Server\Elements\RegisteredResourceTemplate;
+use Mcp\Server\Elements\RegisteredTool;
+use PhpMcp\Schema\Prompt;
+use PhpMcp\Schema\ResourceTemplate;
+use PhpMcp\Schema\Tool;
+
+interface ReferenceProviderInterface
+{
+    public function getTool(string $name): ?RegisteredTool;
+
+    public function getResource(
+        string $uri,
+        bool $includeTemplates = true,
+    ): RegisteredResource|RegisteredResourceTemplate|null;
+
+    public function getResourceTemplate(string $uriTemplate): ?RegisteredResourceTemplate;
+
+    public function getPrompt(string $name): ?RegisteredPrompt;
+
+    /**
+     * @return array<string, Tool>
+     */
+    public function getTools(): array;
+
+    /**
+     * @return array<string, Resource>
+     */
+    public function getResources(): array;
+
+    /**
+     * @return array<string, Prompt>
+     */
+    public function getPrompts(): array;
+
+    /**
+     * @return array<string, ResourceTemplate>
+     */
+    public function getResourceTemplates(): array;
+
+    /**
+     * Checks if any references are currently registered.
+     */
+    public function hasReferences(): bool;
+}

src/Contracts/ReferenceRegistryInterface.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mcp\Server\Contracts;
+
+use Evenement\EventEmitterInterface;
+use PhpMcp\Schema\Prompt;
+use PhpMcp\Schema\Resource;
+use PhpMcp\Schema\ResourceTemplate;
+use PhpMcp\Schema\Tool;
+
+interface ReferenceRegistryInterface extends EventEmitterInterface
+{
+    public function registerTool(
+        Tool $tool,
+        HandlerInterface $handler,
+        bool $isManual = false,
+    ): void;
+
+    public function registerResource(
+        Resource $resource,
+        HandlerInterface $handler,
+        bool $isManual = false,
+    ): void;
+
+    public function registerResourceTemplate(
+        ResourceTemplate $template,
+        HandlerInterface $handler,
+        array $completionProviders = [],
+        bool $isManual = false,
+    ): void;
+
+    public function registerPrompt(
+        Prompt $prompt,
+        HandlerInterface $handler,
+        array $completionProviders = [],
+        bool $isManual = false,
+    ): void;
+}

src/Contracts/ToolExecutorInterface.php

@@ -5,15 +5,19 @@
 namespace Mcp\Server\Contracts;
 
 use Mcp\Server\Context;
-use Mcp\Server\Elements\RegisteredTool;
+use Mcp\Server\Exception\ToolNotFoundException;
 use Mcp\Server\Exception\ValidationException;
+use PhpMcp\Schema\Content\Content;
 
 interface ToolExecutorInterface
 {
     /**
      * Call a registered tool with the given arguments.
      *
+     * @return Content[] The content items for CallToolResult.
+     *
      * @throws ValidationException If arguments do not match the tool's input schema.
+     * @throws ToolNotFoundException If the tool is not registered.
      */
-    public function call(RegisteredTool $registeredTool, array $arguments, Context $context): array;
+    public function call(string $toolName, array $arguments, Context $context): array;
 }

src/Defaults/EnumCompletionProvider.php

@@ -9,8 +9,12 @@
 
 final readonly class EnumCompletionProvider implements CompletionProviderInterface
 {
+    /** @var string[] */
     private array $values;
 
+    /**
+     * @param class-string<\BackedEnum> $enumClass
+     */
     public function __construct(string $enumClass)
     {
         if (!\enum_exists($enumClass)) {

src/Defaults/ListCompletionProvider.php

@@ -9,6 +9,9 @@
 
 final readonly class ListCompletionProvider implements CompletionProviderInterface
 {
+    /**
+     * @param string[] $values
+     */
     public function __construct(
         private array $values,
     ) {}

src/Defaults/ToolExecutor.php

@@ -5,26 +5,111 @@
 namespace Mcp\Server\Defaults;
 
 use Mcp\Server\Context;
+use Mcp\Server\Contracts\ReferenceProviderInterface;
 use Mcp\Server\Contracts\ToolExecutorInterface;
-use Mcp\Server\Elements\RegisteredTool;
+use Mcp\Server\Exception\ToolNotFoundException;
+use PhpMcp\Schema\Content\Content;
+use PhpMcp\Schema\Content\TextContent;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
 
 final readonly class ToolExecutor implements ToolExecutorInterface
 {
     public function __construct(
+        private ReferenceProviderInterface $registry,
         private LoggerInterface $logger = new NullLogger(),
     ) {}
 
-    public function call(
-        RegisteredTool $registeredTool,
-        array $arguments,
-        Context $context,
-    ): array {
+    public function call(string $toolName, array $arguments, Context $context): array
+    {
+        $tool = $this->registry->getTool($toolName);
+
+        if (!$tool) {
+            throw new ToolNotFoundException("Tool '{$toolName}' not found.");
+        }
+
         $this->logger->debug('Calling tool', [
-            'name' => $registeredTool->schema->name,
+            'name' => $tool->schema->name,
         ]);
 
-        return $registeredTool->call($arguments, $context);
+        $result = $tool->handler->handle($arguments, $context);
+
+        return $this->formatResult($result);
+    }
+
+    /**
+     * Formats the result of a tool execution into an array of MCP Content items.
+     *
+     * - If the result is already a Content object, it's wrapped in an array.
+     * - If the result is an array:
+     *   - If all elements are Content objects, the array is returned as is.
+     *   - If it's a mixed array (Content and non-Content items), non-Content items are
+     *     individually formatted (scalars to TextContent, others to JSON TextContent).
+     *   - If it's an array with no Content items, the entire array is JSON-encoded into a single TextContent.
+     * - Scalars (string, int, float, bool) are wrapped in TextContent.
+     * - null is represented as TextContent('(null)').
+     * - Other objects are JSON-encoded and wrapped in TextContent.
+     *
+     * @param mixed $toolExecutionResult The raw value returned by the tool's PHP method.
+     * @return Content[] The content items for CallToolResult.
+     * @throws \JsonException
+     */
+    protected function formatResult(mixed $toolExecutionResult): array
+    {
+        if ($toolExecutionResult instanceof Content) {
+            return [$toolExecutionResult];
+        }
+
+        if (\is_array($toolExecutionResult)) {
+            if (empty($toolExecutionResult)) {
+                return [TextContent::make('[]')];
+            }
+
+            $allAreContent = true;
+            $hasContent = false;
+
+            foreach ($toolExecutionResult as $item) {
+                if ($item instanceof Content) {
+                    $hasContent = true;
+                } else {
+                    $allAreContent = false;
+                }
+            }
+
+            if ($allAreContent && $hasContent) {
+                return $toolExecutionResult;
+            }
+
+            if ($hasContent) {
+                $result = [];
+                foreach ($toolExecutionResult as $item) {
+                    if ($item instanceof Content) {
+                        $result[] = $item;
+                    } else {
+                        $result = \array_merge($result, $this->formatResult($item));
+                    }
+                }
+                return $result;
+            }
+        }
+
+        if ($toolExecutionResult === null) {
+            return [TextContent::make('(null)')];
+        }
+
+        if (\is_bool($toolExecutionResult)) {
+            return [TextContent::make($toolExecutionResult ? 'true' : 'false')];
+        }
+
+        if (\is_scalar($toolExecutionResult)) {
+            return [TextContent::make($toolExecutionResult)];
+        }
+
+        $jsonResult = \json_encode(
+            $toolExecutionResult,
+            JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR | JSON_INVALID_UTF8_SUBSTITUTE,
+        );
+
+        return [TextContent::make($jsonResult)];
     }
 }

src/Dispatcher.php

@@ -4,6 +4,7 @@
 
 namespace Mcp\Server;
 
+use Mcp\Server\Contracts\DispatcherInterface;
 use Mcp\Server\Contracts\DispatcherRoutesFactoryInterface;
 use Mcp\Server\Contracts\RouteInterface;
 use Mcp\Server\Exception\McpServerException;
@@ -12,7 +13,7 @@
 use PhpMcp\Schema\JsonRpc\Result;
 use Psr\Log\LoggerInterface;
 
-final readonly class Dispatcher
+final readonly class Dispatcher implements DispatcherInterface
 {
     /** @var array<string, RouteInterface> */
     private array $routes;