refactor: extract MCP handlers from Server class into separate handler classes

Benefits:
- Better separation of concerns with domain-specific handlers
- Enhanced testability through interface-based dependency injection
- Cleaner Server class that acts as coordinator rather than handling all logic
- Consistent error handling and logging patterns across handler types
- Easier maintenance and extension of MCP functionality

Author: butschster

src/McpServer/McpServerBootloader.php

@@ -38,6 +38,12 @@
 use Butschster\ContextGenerator\McpServer\ProjectService\ProjectServiceInterface;
 use Butschster\ContextGenerator\McpServer\Prompt\McpPromptBootloader;
 use Butschster\ContextGenerator\McpServer\Registry\McpItemsRegistry;
+use Butschster\ContextGenerator\McpServer\Routing\Handler\Prompts\PromptsHandler;
+use Butschster\ContextGenerator\McpServer\Routing\Handler\Prompts\PromptsHandlerInterface;
+use Butschster\ContextGenerator\McpServer\Routing\Handler\Resources\ResourcesHandler;
+use Butschster\ContextGenerator\McpServer\Routing\Handler\Resources\ResourcesHandlerInterface;
+use Butschster\ContextGenerator\McpServer\Routing\Handler\Tools\ToolsHandler;
+use Butschster\ContextGenerator\McpServer\Routing\Handler\Tools\ToolsHandlerInterface;
 use Butschster\ContextGenerator\McpServer\Routing\McpResponseStrategy;
 use Butschster\ContextGenerator\McpServer\Routing\RouteRegistrar;
 use Butschster\ContextGenerator\McpServer\Tool\McpToolBootloader;
@@ -116,6 +122,12 @@ public function boot(ConsoleBootloader $console): void
     public function defineSingletons(): array
     {
         return [
+            // MCP Handlers
+            PromptsHandlerInterface::class => PromptsHandler::class,
+            ResourcesHandlerInterface::class => ResourcesHandler::class,
+            ToolsHandlerInterface::class => ToolsHandler::class,
+
+            // Server infrastructure
             ServerRunnerInterface::class => function (
                 McpConfig $config,
                 ServerRunner $factory,

src/McpServer/Routing/Handler/BaseHandler.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Butschster\ContextGenerator\McpServer\Routing\Handler;
+
+use Butschster\ContextGenerator\McpServer\ProjectService\ProjectServiceInterface;
+use Butschster\ContextGenerator\McpServer\Routing\Mcp2PsrRequestAdapter;
+use Laminas\Diactoros\Response\JsonResponse;
+use League\Route\Router;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Abstract base class providing common functionality for all MCP handlers
+ */
+abstract readonly class BaseHandler
+{
+    public function __construct(
+        protected Router $router,
+        protected LoggerInterface $logger,
+        protected ProjectServiceInterface $projectService,
+        protected Mcp2PsrRequestAdapter $requestAdapter,
+    ) {}
+
+    /**
+     * Handle a route using the router system
+     */
+    protected function handleRoute(string $method, array $params = []): mixed
+    {
+        $this->logger->debug("Handling route: $method", $params);
+
+        // Create PSR request from MCP method and params
+        $request = $this->requestAdapter->createPsrRequest($method, $params);
+
+        try {
+            $response = $this->router->dispatch($request);
+            \assert($response instanceof JsonResponse);
+
+            // Convert the response back to appropriate MCP type
+            return $this->projectService->processResponse($response->getPayload());
+        } catch (\Throwable $e) {
+            $this->logger->error('Route handling error', [
+                'method' => $method,
+                'error' => $e->getMessage(),
+                'trace' => $e->getTraceAsString(),
+            ]);
+
+            throw $e;
+        }
+    }
+
+    /**
+     * Log error and return error result
+     */
+    protected function logError(string $context, string $method, \Throwable $e): void
+    {
+        $this->logger->error("$context error", [
+            'method' => $method,
+            'error' => $e->getMessage(),
+            'trace' => $e->getTraceAsString(),
+        ]);
+    }
+}

src/McpServer/Routing/Handler/Prompts/PromptsHandler.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Butschster\ContextGenerator\McpServer\Routing\Handler\Prompts;
+
+use Butschster\ContextGenerator\McpServer\Routing\Handler\BaseHandler;
+use Laminas\Diactoros\Response\JsonResponse;
+use Mcp\Types\GetPromptRequestParams;
+use Mcp\Types\GetPromptResult;
+use Mcp\Types\ListPromptsResult;
+
+/**
+ * Handler for prompt-related MCP requests
+ */
+final readonly class PromptsHandler extends BaseHandler implements PromptsHandlerInterface
+{
+    #[\Override]
+    public function handlePromptsList(): ListPromptsResult
+    {
+        try {
+            return $this->handleRoute('prompts/list');
+        } catch (\Throwable $e) {
+            $this->logError('Prompts list', 'prompts/list', $e);
+            return new ListPromptsResult([]);
+        }
+    }
+
+    #[\Override]
+    public function handlePromptsGet(GetPromptRequestParams $params): GetPromptResult
+    {
+        $params = $this->projectService->processPromptRequestParams($params);
+
+        $name = $params->name;
+        $arguments = $params->arguments;
+        $method = 'prompt/' . $name;
+
+        $this->logger->debug('Handling prompt get', [
+            'prompt' => $name,
+            'method' => $method,
+            'arguments' => (array) $arguments->jsonSerialize(),
+        ]);
+
+        try {
+            // Create PSR request with the prompt name in the path and arguments as POST body
+            $request = $this->requestAdapter->createPsrRequest($method, (array) $arguments->jsonSerialize());
+
+            $response = $this->router->dispatch($request);
+            \assert($response instanceof JsonResponse);
+
+            return $response->getPayload();
+        } catch (\Throwable $e) {
+            $this->logError('Prompt get', $method, $e);
+            return new GetPromptResult([]);
+        }
+    }
+}

src/McpServer/Routing/Handler/Prompts/PromptsHandlerInterface.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Butschster\ContextGenerator\McpServer\Routing\Handler\Prompts;
+
+use Mcp\Types\GetPromptRequestParams;
+use Mcp\Types\GetPromptResult;
+use Mcp\Types\ListPromptsResult;
+
+/**
+ * Interface for handling prompt-related MCP requests
+ */
+interface PromptsHandlerInterface
+{
+    /**
+     * Handle prompts/list request
+     */
+    public function handlePromptsList(): ListPromptsResult;
+
+    /**
+     * Handle prompts/get request
+     */
+    public function handlePromptsGet(GetPromptRequestParams $params): GetPromptResult;
+}

src/McpServer/Routing/Handler/Resources/ResourcesHandler.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Butschster\ContextGenerator\McpServer\Routing\Handler\Resources;
+
+use Butschster\ContextGenerator\McpServer\Routing\Handler\BaseHandler;
+use Laminas\Diactoros\Response\JsonResponse;
+use Mcp\Types\ListResourcesResult;
+use Mcp\Types\ReadResourceRequestParams;
+use Mcp\Types\ReadResourceResult;
+
+/**
+ * Handler for resource-related MCP requests
+ */
+final readonly class ResourcesHandler extends BaseHandler implements ResourcesHandlerInterface
+{
+    #[\Override]
+    public function handleResourcesList(): ListResourcesResult
+    {
+        try {
+            return $this->handleRoute('resources/list');
+        } catch (\Throwable $e) {
+            $this->logError('Resources list', 'resources/list', $e);
+            return new ListResourcesResult([]);
+        }
+    }
+
+    #[\Override]
+    public function handleResourcesRead(ReadResourceRequestParams $params): ReadResourceResult
+    {
+        $params = $this->projectService->processResourceRequestParams($params);
+
+        [$type, $path] = \explode('://', $params->uri, 2);
+        $method = 'resource/' . $type . '/' . $path;
+
+        $this->logger->debug('Handling resource read', [
+            'resource' => $params->uri,
+            'type' => $type,
+            'path' => $path,
+            'method' => $method,
+        ]);
+
+        try {
+            // Create PSR request with the resource path
+            $request = $this->requestAdapter->createPsrRequest($method);
+
+            $response = $this->router->dispatch($request);
+            \assert($response instanceof JsonResponse);
+
+            return $response->getPayload();
+        } catch (\Throwable $e) {
+            $this->logError('Resource read', $method, $e);
+            return new ReadResourceResult([]);
+        }
+    }
+}

src/McpServer/Routing/Handler/Resources/ResourcesHandlerInterface.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Butschster\ContextGenerator\McpServer\Routing\Handler\Resources;
+
+use Mcp\Types\ListResourcesResult;
+use Mcp\Types\ReadResourceRequestParams;
+use Mcp\Types\ReadResourceResult;
+
+/**
+ * Interface for handling resource-related MCP requests
+ */
+interface ResourcesHandlerInterface
+{
+    /**
+     * Handle resources/list request
+     */
+    public function handleResourcesList(): ListResourcesResult;
+
+    /**
+     * Handle resources/read request
+     */
+    public function handleResourcesRead(ReadResourceRequestParams $params): ReadResourceResult;
+}

src/McpServer/Routing/Handler/Tools/ToolsHandler.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Butschster\ContextGenerator\McpServer\Routing\Handler\Tools;
+
+use Butschster\ContextGenerator\McpServer\Routing\Handler\BaseHandler;
+use Laminas\Diactoros\Response\JsonResponse;
+use Mcp\Types\CallToolRequestParams;
+use Mcp\Types\CallToolResult;
+use Mcp\Types\ListToolsResult;
+use Mcp\Types\TextContent;
+
+/**
+ * Handler for tool-related MCP requests
+ */
+final readonly class ToolsHandler extends BaseHandler implements ToolsHandlerInterface
+{
+    #[\Override]
+    public function handleToolsList(): ListToolsResult
+    {
+        try {
+            return $this->handleRoute('tools/list');
+        } catch (\Throwable $e) {
+            $this->logError('Tools list', 'tools/list', $e);
+            return new ListToolsResult([]);
+        }
+    }
+
+    #[\Override]
+    public function handleToolsCall(CallToolRequestParams $params): CallToolResult
+    {
+        $params = $this->projectService->processToolRequestParams($params);
+
+        $method = 'tools/call/' . $params->name;
+        $arguments = $params->arguments ?? [];
+
+        $this->logger->debug('Handling tool call', [
+            'tool' => $params->name,
+            'method' => $method,
+            'arguments' => $arguments,
+        ]);
+
+        try {
+            // Create PSR request with the tool name in the path and arguments as POST body
+            $request = $this->requestAdapter->createPsrRequest($method, $arguments);
+
+            $response = $this->router->dispatch($request);
+            \assert($response instanceof JsonResponse);
+
+            return $response->getPayload();
+        } catch (\Throwable $e) {
+            $this->logError('Tool call', $method, $e);
+            return new CallToolResult([new TextContent(text: $e->getMessage())], isError: true);
+        }
+    }
+}

src/McpServer/Routing/Handler/Tools/ToolsHandlerInterface.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Butschster\ContextGenerator\McpServer\Routing\Handler\Tools;
+
+use Mcp\Types\CallToolRequestParams;
+use Mcp\Types\CallToolResult;
+use Mcp\Types\ListToolsResult;
+
+/**
+ * Interface for handling tool-related MCP requests
+ */
+interface ToolsHandlerInterface
+{
+    /**
+     * Handle tools/list request
+     */
+    public function handleToolsList(): ListToolsResult;
+
+    /**
+     * Handle tools/call request
+     */
+    public function handleToolsCall(CallToolRequestParams $params): CallToolResult;
+}