refactor(core)!: Introduce RegisteredElement objects to encapsulate element logic

This commit introduces a new set of classes under the `PhpMcp\Server\Elements`
namespace (`RegisteredElement`, `RegisteredTool`, `RegisteredResource`,
`RegisteredPrompt`, `RegisteredResourceTemplate`). These classes now
encapsulate:
- The MCP schema DTO (e.g., `PhpMcp\Schema\Tool`).
- The handler invocation logic (previously in `Support\Handler` and
  `Support\ArgumentPreparer`), including argument preparation and type casting,
  now part of the `RegisteredElement` base class.
- Specific execution methods (e.g., `call()` on `RegisteredTool`, `read()` on
  `RegisteredResource`).
- Result formatting logic (previously in `Traits\ResponseFormatter`) moved
  into the respective `Registered*` classes.
- URI template matching logic is now self-contained within
  `RegisteredResourceTemplate`.
- Completion provider storage is now part of `RegisteredTool`,
  `RegisteredPrompt`, and `RegisteredResourceTemplate`.

Author: CodeWithKyrian

examples/02-discovery-http-userprofile/server.php

@@ -67,7 +67,7 @@ public function log($level, \Stringable|string $message, array $context = []): v
 
     $server = Server::make()
         ->withServerInfo('HTTP User Profiles', '1.0.0')
-        ->withCapabilities(ServerCapabilities::make(completionsEnabled: true))
+        ->withCapabilities(ServerCapabilities::make(completionsEnabled: true, loggingEnabled: true))
         ->withLogger($logger)
         ->withContainer($container)
         ->build();

src/Dispatcher.php

@@ -39,16 +39,13 @@
 use PhpMcp\Server\Protocol;
 use PhpMcp\Server\Registry;
 use PhpMcp\Server\Session\SubscriptionManager;
-use PhpMcp\Server\Support\SchemaValidator;
-use PhpMcp\Server\Traits\ResponseFormatter;
+use PhpMcp\Server\Utils\SchemaValidator;
 use Psr\Container\ContainerInterface;
 use Psr\Log\LoggerInterface;
 use Throwable;
 
 class Dispatcher
 {
-    use ResponseFormatter;
-
     protected ContainerInterface $container;
     protected LoggerInterface $logger;
 
@@ -160,12 +157,12 @@ public function handleToolCall(CallToolRequest $request): CallToolResult
         $toolName = $request->name;
         $arguments = $request->arguments;
 
-        ['tool' => $tool, 'handler' => $handler] = $this->registry->getTool($toolName);
-        if (! $tool) {
+        $registeredTool = $this->registry->getTool($toolName);
+        if (! $registeredTool) {
             throw McpServerException::methodNotFound("Tool '{$toolName}' not found.");
         }
 
-        $inputSchema = $tool->inputSchema;
+        $inputSchema = $registeredTool->schema->inputSchema;
 
         $validationErrors = $this->schemaValidator->validateAgainstJsonSchema($arguments, $inputSchema);
 
@@ -188,20 +185,19 @@ public function handleToolCall(CallToolRequest $request): CallToolResult
         }
 
         try {
-            $result = $handler->handle($this->container, $arguments);
-            $formattedResult = $this->formatToolResult($result);
+            $result = $registeredTool->call($this->container, $arguments);
 
-            return new CallToolResult($formattedResult, false);
+            return new CallToolResult($result, false);
         } catch (JsonException $e) {
-            $this->logger->warning('MCP SDK: Failed to JSON encode tool result.', ['tool' => $toolName, 'exception' => $e]);
+            $this->logger->warning('Failed to JSON encode tool result.', ['tool' => $toolName, 'exception' => $e]);
             $errorMessage = "Failed to serialize tool result: {$e->getMessage()}";
 
             return new CallToolResult([new TextContent($errorMessage)], true);
         } catch (Throwable $toolError) {
-            $this->logger->error('MCP SDK: Tool execution failed.', ['tool' => $toolName, 'exception' => $toolError]);
-            $errorContent = $this->formatToolErrorResult($toolError);
+            $this->logger->error('Tool execution failed.', ['tool' => $toolName, 'exception' => $toolError]);
+            $errorMessage = "Tool execution failed: {$toolError->getMessage()}";
 
-            return new CallToolResult($errorContent, true);
+            return new CallToolResult([new TextContent($errorMessage)], true);
         }
     }
 
@@ -231,25 +227,23 @@ public function handleResourceRead(ReadResourceRequest $request): ReadResourceRe
     {
         $uri = $request->uri;
 
-        ['resource' => $resource, 'handler' => $handler, 'variables' => $uriVariables] = $this->registry->getResource($uri);
+        $registeredResource = $this->registry->getResource($uri);
 
-        if (! $resource) {
+        if (! $registeredResource) {
             throw McpServerException::invalidParams("Resource URI '{$uri}' not found.");
         }
 
         try {
-            $arguments = array_merge($uriVariables, ['uri' => $uri]);
-            $result = $handler->handle($this->container, $arguments);
-            $contents = $this->formatResourceContents($result, $uri, $resource->mimeType);
+            $result = $registeredResource->read($this->container, $uri);
 
-            return new ReadResourceResult($contents);
+            return new ReadResourceResult($result);
         } catch (JsonException $e) {
-            $this->logger->warning('MCP SDK: Failed to JSON encode resource content.', ['exception' => $e, 'uri' => $uri]);
+            $this->logger->warning('Failed to JSON encode resource content.', ['exception' => $e, 'uri' => $uri]);
             throw McpServerException::internalError("Failed to serialize resource content for '{$uri}'.", $e);
         } catch (McpServerException $e) {
             throw $e;
         } catch (Throwable $e) {
-            $this->logger->error('MCP SDK: Resource read failed.', ['uri' => $uri, 'exception' => $e]);
+            $this->logger->error('Resource read failed.', ['uri' => $uri, 'exception' => $e]);
             throw McpServerException::resourceReadFailed($uri, $e);
         }
     }
@@ -282,32 +276,31 @@ public function handlePromptGet(GetPromptRequest $request): GetPromptResult
         $promptName = $request->name;
         $arguments = $request->arguments;
 
-        ['prompt' => $prompt, 'handler' => $handler] = $this->registry->getPrompt($promptName);
-        if (! $prompt) {
+        $registeredPrompt = $this->registry->getPrompt($promptName);
+        if (! $registeredPrompt) {
             throw McpServerException::invalidParams("Prompt '{$promptName}' not found.");
         }
 
         $arguments = (array) $arguments;
 
-        foreach ($prompt->arguments as $argDef) {
+        foreach ($registeredPrompt->schema->arguments as $argDef) {
             if ($argDef->required && ! array_key_exists($argDef->name, $arguments)) {
                 throw McpServerException::invalidParams("Missing required argument '{$argDef->name}' for prompt '{$promptName}'.");
             }
         }
 
         try {
-            $result = $handler->handle($this->container, $arguments);
-            $messages = $this->formatPromptMessages($result);
+            $result = $registeredPrompt->get($this->container, $arguments);
 
-            return new GetPromptResult($messages, $prompt->description);
+            return new GetPromptResult($result, $registeredPrompt->schema->description);
         } catch (JsonException $e) {
-            $this->logger->warning('MCP SDK: Failed to JSON encode prompt messages.', ['exception' => $e, 'promptName' => $promptName]);
+            $this->logger->warning('Failed to JSON encode prompt messages.', ['exception' => $e, 'promptName' => $promptName]);
             throw McpServerException::internalError("Failed to serialize prompt messages for '{$promptName}'.", $e);
         } catch (McpServerException $e) {
-            throw $e; // Re-throw known MCP errors
+            throw $e;
         } catch (Throwable $e) {
-            $this->logger->error('MCP SDK: Prompt generation failed.', ['promptName' => $promptName, 'exception' => $e]);
-            throw McpServerException::promptGenerationFailed($promptName, $e); // Use specific factory
+            $this->logger->error('Prompt generation failed.', ['promptName' => $promptName, 'exception' => $e]);
+            throw McpServerException::promptGenerationFailed($promptName, $e);
         }
     }
 
@@ -332,13 +325,13 @@ public function handleCompletionComplete(CompletionCompleteRequest $request, Ses
 
         if ($ref->type === 'ref/prompt') {
             $identifier = $ref->name;
-            ['prompt' => $prompt] = $this->registry->getPrompt($identifier);
-            if (! $prompt) {
+            $registeredPrompt = $this->registry->getPrompt($identifier);
+            if (! $registeredPrompt) {
                 throw McpServerException::invalidParams("Prompt '{$identifier}' not found.");
             }
 
             $foundArg = false;
-            foreach ($prompt->arguments as $arg) {
+            foreach ($registeredPrompt->schema->arguments as $arg) {
                 if ($arg->name === $argumentName) {
                     $foundArg = true;
                     break;
@@ -347,15 +340,17 @@ public function handleCompletionComplete(CompletionCompleteRequest $request, Ses
             if (! $foundArg) {
                 throw McpServerException::invalidParams("Argument '{$argumentName}' not found in prompt '{$identifier}'.");
             }
+
+            $providerClass = $registeredPrompt->getCompletionProvider($argumentName);
         } else if ($ref->type === 'ref/resource') {
             $identifier = $ref->uri;
-            ['resourceTemplate' => $resourceTemplate, 'variables' => $uriVariables] = $this->registry->getResourceTemplate($identifier);
-            if (! $resourceTemplate) {
+            $registeredResourceTemplate = $this->registry->getResourceTemplate($identifier);
+            if (! $registeredResourceTemplate) {
                 throw McpServerException::invalidParams("Resource template '{$identifier}' not found.");
             }
 
             $foundArg = false;
-            foreach ($uriVariables as $uriVariableName) {
+            foreach ($registeredResourceTemplate->getVariableNames() as $uriVariableName) {
                 if ($uriVariableName === $argumentName) {
                     $foundArg = true;
                     break;
@@ -365,11 +360,12 @@ public function handleCompletionComplete(CompletionCompleteRequest $request, Ses
             if (! $foundArg) {
                 throw McpServerException::invalidParams("URI variable '{$argumentName}' not found in resource template '{$identifier}'.");
             }
+
+            $providerClass = $registeredResourceTemplate->getCompletionProvider($argumentName);
         } else {
             throw McpServerException::invalidParams("Invalid ref type '{$ref->type}' for completion complete request.");
         }
 
-        $providerClass = $this->registry->getCompletionProvider($ref->type, $identifier, $argumentName);
         if (! $providerClass) {
             $this->logger->warning("No completion provider found for argument '{$argumentName}' in '{$ref->type}' '{$identifier}'.");
             return new CompletionCompleteResult([]);

src/Support/Handler.php renamed to src/Elements/RegisteredElement.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace PhpMcp\Server\Support;
+namespace PhpMcp\Server\Elements;
 
 use InvalidArgumentException;
 use PhpMcp\Server\Exception\McpServerException;
@@ -14,30 +14,30 @@
 use Throwable;
 use TypeError;
 
-class Handler
+class RegisteredElement
 {
     public function __construct(
-        public readonly string $className,
-        public readonly string $methodName,
-    ) {
-    }
+        public readonly string $handlerClass,
+        public readonly string $handlerMethod,
+        public readonly bool $isManual = false,
+    ) {}
 
     public function handle(ContainerInterface $container, array $arguments): mixed
     {
-        $instance = $container->get($this->className);
+        $instance = $container->get($this->handlerClass);
         $arguments = $this->prepareArguments($instance, $arguments);
-        $method = $this->methodName;
+        $method = $this->handlerMethod;
 
         return $instance->$method(...$arguments);
     }
 
-    private function prepareArguments(object $instance, array $arguments): array
+    protected function prepareArguments(object $instance, array $arguments): array
     {
-        if (! method_exists($instance, $this->methodName)) {
-            throw new ReflectionException("Method does not exist: {$this->className}::{$this->methodName}");
+        if (! method_exists($instance, $this->handlerMethod)) {
+            throw new ReflectionException("Method does not exist: {$this->handlerClass}::{$this->handlerMethod}");
         }
 
-        $reflectionMethod = new ReflectionMethod($instance, $this->methodName);
+        $reflectionMethod = new ReflectionMethod($instance, $this->handlerMethod);
 
         $finalArgs = [];
 
@@ -65,27 +65,14 @@ private function prepareArguments(object $instance, array $arguments): array
                 continue;
             } else {
                 throw McpServerException::internalError(
-                    "Missing required argument `{$paramName}` for {$reflectionMethod->class}::{$this->methodName}."
+                    "Missing required argument `{$paramName}` for {$reflectionMethod->class}::{$this->handlerMethod}."
                 );
             }
         }
 
         return array_values($finalArgs);
     }
 
-    public static function fromArray(array $data): self
-    {
-        return new self($data['className'], $data['methodName']);
-    }
-
-    public function toArray(): array
-    {
-        return [
-            'className' => $this->className,
-            'methodName' => $this->methodName,
-        ];
-    }
-
     /**
      * Attempts type casting based on ReflectionParameter type hints.
      *