[Server] Reorganize server handlers and transport structure for better organization (#86)

* refactor: reorganize server handlers and transport structure

* feat: move the test files to corresponding directories

* fix: linter issues

* fix: correct PHPDoc formatting and streamline handler imports

* refactor: update import statement for ServerBuilder to Builder

src/Server/Handler/Request/CallToolHandler.php

@@ -0,0 +1,62 @@
+<?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\Server\Handler\Request;
+
+use Mcp\Capability\Tool\ToolCallerInterface;
+use Mcp\Exception\ExceptionInterface;
+use Mcp\Schema\JsonRpc\Error;
+use Mcp\Schema\JsonRpc\HasMethodInterface;
+use Mcp\Schema\JsonRpc\Response;
+use Mcp\Schema\Request\CallToolRequest;
+use Mcp\Server\Handler\MethodHandlerInterface;
+use Mcp\Server\Session\SessionInterface;
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
+
+/**
+ * @author Christopher Hertel <mail@christopher-hertel.de>
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class CallToolHandler implements MethodHandlerInterface
+{
+    public function __construct(
+        private readonly ToolCallerInterface $toolCaller,
+        private readonly LoggerInterface $logger = new NullLogger(),
+    ) {
+    }
+
+    public function supports(HasMethodInterface $message): bool
+    {
+        return $message instanceof CallToolRequest;
+    }
+
+    public function handle(CallToolRequest|HasMethodInterface $message, SessionInterface $session): Response|Error
+    {
+        \assert($message instanceof CallToolRequest);
+
+        try {
+            $content = $this->toolCaller->call($message);
+        } catch (ExceptionInterface $exception) {
+            $this->logger->error(
+                \sprintf('Error while executing tool "%s": "%s".', $message->name, $exception->getMessage()),
+                [
+                    'tool' => $message->name,
+                    'arguments' => $message->arguments,
+                ],
+            );
+
+            return Error::forInternalError('Error while executing tool', $message->getId());
+        }
+
+        return new Response($message->getId(), $content);
+    }
+}

src/Server/Handler/Request/GetPromptHandler.php

@@ -0,0 +1,50 @@
+<?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\Server\Handler\Request;
+
+use Mcp\Capability\Prompt\PromptGetterInterface;
+use Mcp\Exception\ExceptionInterface;
+use Mcp\Schema\JsonRpc\Error;
+use Mcp\Schema\JsonRpc\HasMethodInterface;
+use Mcp\Schema\JsonRpc\Response;
+use Mcp\Schema\Request\GetPromptRequest;
+use Mcp\Server\Handler\MethodHandlerInterface;
+use Mcp\Server\Session\SessionInterface;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class GetPromptHandler implements MethodHandlerInterface
+{
+    public function __construct(
+        private readonly PromptGetterInterface $promptGetter,
+    ) {
+    }
+
+    public function supports(HasMethodInterface $message): bool
+    {
+        return $message instanceof GetPromptRequest;
+    }
+
+    public function handle(GetPromptRequest|HasMethodInterface $message, SessionInterface $session): Response|Error
+    {
+        \assert($message instanceof GetPromptRequest);
+
+        try {
+            $messages = $this->promptGetter->get($message);
+        } catch (ExceptionInterface) {
+            return Error::forInternalError('Error while handling prompt', $message->getId());
+        }
+
+        return new Response($message->getId(), $messages);
+    }
+}

src/Server/Handler/Request/InitializeHandler.php

@@ -0,0 +1,50 @@
+<?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\Server\Handler\Request;
+
+use Mcp\Schema\Implementation;
+use Mcp\Schema\JsonRpc\HasMethodInterface;
+use Mcp\Schema\JsonRpc\Response;
+use Mcp\Schema\Request\InitializeRequest;
+use Mcp\Schema\Result\InitializeResult;
+use Mcp\Schema\ServerCapabilities;
+use Mcp\Server\Handler\MethodHandlerInterface;
+use Mcp\Server\Session\SessionInterface;
+
+/**
+ * @author Christopher Hertel <mail@christopher-hertel.de>
+ */
+final class InitializeHandler implements MethodHandlerInterface
+{
+    public function __construct(
+        public readonly ?ServerCapabilities $capabilities = new ServerCapabilities(),
+        public readonly ?Implementation $serverInfo = new Implementation(),
+    ) {
+    }
+
+    public function supports(HasMethodInterface $message): bool
+    {
+        return $message instanceof InitializeRequest;
+    }
+
+    public function handle(InitializeRequest|HasMethodInterface $message, SessionInterface $session): Response
+    {
+        \assert($message instanceof InitializeRequest);
+
+        $session->set('client_info', $message->clientInfo->jsonSerialize());
+
+        return new Response(
+            $message->getId(),
+            new InitializeResult($this->capabilities, $this->serverInfo),
+        );
+    }
+}

src/Server/Handler/Request/ListPromptsHandler.php

@@ -0,0 +1,53 @@
+<?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\Server\Handler\Request;
+
+use Mcp\Capability\Registry\ReferenceProviderInterface;
+use Mcp\Exception\InvalidCursorException;
+use Mcp\Schema\JsonRpc\HasMethodInterface;
+use Mcp\Schema\JsonRpc\Response;
+use Mcp\Schema\Request\ListPromptsRequest;
+use Mcp\Schema\Result\ListPromptsResult;
+use Mcp\Server\Handler\MethodHandlerInterface;
+use Mcp\Server\Session\SessionInterface;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class ListPromptsHandler implements MethodHandlerInterface
+{
+    public function __construct(
+        private readonly ReferenceProviderInterface $registry,
+        private readonly int $pageSize = 20,
+    ) {
+    }
+
+    public function supports(HasMethodInterface $message): bool
+    {
+        return $message instanceof ListPromptsRequest;
+    }
+
+    /**
+     * @throws InvalidCursorException
+     */
+    public function handle(ListPromptsRequest|HasMethodInterface $message, SessionInterface $session): Response
+    {
+        \assert($message instanceof ListPromptsRequest);
+
+        $page = $this->registry->getPrompts($this->pageSize, $message->cursor);
+
+        return new Response(
+            $message->getId(),
+            new ListPromptsResult($page->references, $page->nextCursor),
+        );
+    }
+}

src/Server/Handler/Request/ListResourcesHandler.php

@@ -0,0 +1,53 @@
+<?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\Server\Handler\Request;
+
+use Mcp\Capability\Registry\ReferenceProviderInterface;
+use Mcp\Exception\InvalidCursorException;
+use Mcp\Schema\JsonRpc\HasMethodInterface;
+use Mcp\Schema\JsonRpc\Response;
+use Mcp\Schema\Request\ListResourcesRequest;
+use Mcp\Schema\Result\ListResourcesResult;
+use Mcp\Server\Handler\MethodHandlerInterface;
+use Mcp\Server\Session\SessionInterface;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class ListResourcesHandler implements MethodHandlerInterface
+{
+    public function __construct(
+        private readonly ReferenceProviderInterface $registry,
+        private readonly int $pageSize = 20,
+    ) {
+    }
+
+    public function supports(HasMethodInterface $message): bool
+    {
+        return $message instanceof ListResourcesRequest;
+    }
+
+    /**
+     * @throws InvalidCursorException
+     */
+    public function handle(ListResourcesRequest|HasMethodInterface $message, SessionInterface $session): Response
+    {
+        \assert($message instanceof ListResourcesRequest);
+
+        $page = $this->registry->getResources($this->pageSize, $message->cursor);
+
+        return new Response(
+            $message->getId(),
+            new ListResourcesResult($page->references, $page->nextCursor),
+        );
+    }
+}

src/Server/Handler/Request/ListToolsHandler.php

@@ -0,0 +1,54 @@
+<?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\Server\Handler\Request;
+
+use Mcp\Capability\Registry\ReferenceProviderInterface;
+use Mcp\Exception\InvalidCursorException;
+use Mcp\Schema\JsonRpc\HasMethodInterface;
+use Mcp\Schema\JsonRpc\Response;
+use Mcp\Schema\Request\ListToolsRequest;
+use Mcp\Schema\Result\ListToolsResult;
+use Mcp\Server\Handler\MethodHandlerInterface;
+use Mcp\Server\Session\SessionInterface;
+
+/**
+ * @author Christopher Hertel <mail@christopher-hertel.de>
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class ListToolsHandler implements MethodHandlerInterface
+{
+    public function __construct(
+        private readonly ReferenceProviderInterface $registry,
+        private readonly int $pageSize = 20,
+    ) {
+    }
+
+    public function supports(HasMethodInterface $message): bool
+    {
+        return $message instanceof ListToolsRequest;
+    }
+
+    /**
+     * @throws InvalidCursorException When the cursor is invalid
+     */
+    public function handle(ListToolsRequest|HasMethodInterface $message, SessionInterface $session): Response
+    {
+        \assert($message instanceof ListToolsRequest);
+
+        $page = $this->registry->getTools($this->pageSize, $message->cursor);
+
+        return new Response(
+            $message->getId(),
+            new ListToolsResult($page->references, $page->nextCursor),
+        );
+    }
+}

src/Server/Handler/Request/PingHandler.php

@@ -0,0 +1,37 @@
+<?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\Server\Handler\Request;
+
+use Mcp\Schema\JsonRpc\HasMethodInterface;
+use Mcp\Schema\JsonRpc\Response;
+use Mcp\Schema\Request\PingRequest;
+use Mcp\Schema\Result\EmptyResult;
+use Mcp\Server\Handler\MethodHandlerInterface;
+use Mcp\Server\Session\SessionInterface;
+
+/**
+ * @author Christopher Hertel <mail@christopher-hertel.de>
+ */
+final class PingHandler implements MethodHandlerInterface
+{
+    public function supports(HasMethodInterface $message): bool
+    {
+        return $message instanceof PingRequest;
+    }
+
+    public function handle(PingRequest|HasMethodInterface $message, SessionInterface $session): Response
+    {
+        \assert($message instanceof PingRequest);
+
+        return new Response($message->getId(), new EmptyResult());
+    }
+}

src/Server/Handler/Request/ReadResourceHandler.php

@@ -0,0 +1,53 @@
+<?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\Server\Handler\Request;
+
+use Mcp\Capability\Resource\ResourceReaderInterface;
+use Mcp\Exception\ExceptionInterface;
+use Mcp\Exception\ResourceNotFoundException;
+use Mcp\Schema\JsonRpc\Error;
+use Mcp\Schema\JsonRpc\HasMethodInterface;
+use Mcp\Schema\JsonRpc\Response;
+use Mcp\Schema\Request\ReadResourceRequest;
+use Mcp\Server\Handler\MethodHandlerInterface;
+use Mcp\Server\Session\SessionInterface;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class ReadResourceHandler implements MethodHandlerInterface
+{
+    public function __construct(
+        private readonly ResourceReaderInterface $resourceReader,
+    ) {
+    }
+
+    public function supports(HasMethodInterface $message): bool
+    {
+        return $message instanceof ReadResourceRequest;
+    }
+
+    public function handle(ReadResourceRequest|HasMethodInterface $message, SessionInterface $session): Response|Error
+    {
+        \assert($message instanceof ReadResourceRequest);
+
+        try {
+            $contents = $this->resourceReader->read($message);
+        } catch (ResourceNotFoundException $e) {
+            return new Error($message->getId(), Error::RESOURCE_NOT_FOUND, $e->getMessage());
+        } catch (ExceptionInterface) {
+            return Error::forInternalError('Error while reading resource', $message->getId());
+        }
+
+        return new Response($message->getId(), $contents);
+    }
+}