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

CodeWithKyrian · web-flow · commit 41486bfaa492 · 2025-09-29T00:58:04.000+02:00
* 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
diff --git a/src/Capability/Registry.php b/src/Capability/Registry.php
@@ -23,12 +23,12 @@
 use Mcp\Event\ResourceTemplateListChangedEvent;
 use Mcp\Event\ToolListChangedEvent;
 use Mcp\Exception\InvalidCursorException;
+use Mcp\Schema\Page;
 use Mcp\Schema\Prompt;
 use Mcp\Schema\Resource;
 use Mcp\Schema\ResourceTemplate;
 use Mcp\Schema\ServerCapabilities;
 use Mcp\Schema\Tool;
-use Mcp\Server\RequestHandler\Reference\Page;
 use Psr\EventDispatcher\EventDispatcherInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
diff --git a/src/Capability/Registry/ReferenceProviderInterface.php b/src/Capability/Registry/ReferenceProviderInterface.php
@@ -11,7 +11,7 @@
 
 namespace Mcp\Capability\Registry;
 
-use Mcp\Server\RequestHandler\Reference\Page;
+use Mcp\Schema\Page;
 
 /**
  * Interface for providing access to registered MCP elements.
diff --git a/src/Schema/Page.php b/src/Schema/Page.php
@@ -9,15 +9,17 @@
  * file that was distributed with this source code.
  */
 
-namespace Mcp\Server\RequestHandler\Reference;
+namespace Mcp\Schema;
 
 /**
- * @extends \ArrayObject<int|string, mixed>
+ * @phpstan-type PageItem Tool|Prompt|ResourceTemplate|Resource
+ *
+ * @extends \ArrayObject<int|string, PageItem>
  */
 final class Page extends \ArrayObject
 {
     /**
-     * @param array<int|string, mixed> $references Items can be Tool, Prompt, ResourceTemplate, or Resource
+     * @param array<int|string, PageItem> $references Items can be Tool, Prompt, ResourceTemplate, or Resource
      */
     public function __construct(
         public readonly array $references,
diff --git a/src/Server.php b/src/Server.php
@@ -11,9 +11,9 @@
 
 namespace Mcp;
 
-use Mcp\JsonRpc\Handler;
 use Mcp\Server\Builder;
-use Mcp\Server\TransportInterface;
+use Mcp\Server\Handler\JsonRpcHandler;
+use Mcp\Server\Transport\TransportInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
 use Symfony\Component\Uid\Uuid;
@@ -25,7 +25,7 @@
 final class Server
 {
     public function __construct(
-        private readonly Handler $jsonRpcHandler,
+        private readonly JsonRpcHandler $jsonRpcHandler,
         private readonly LoggerInterface $logger = new NullLogger(),
     ) {
     }
diff --git a/src/Server/Builder.php b/src/Server/Builder.php
@@ -29,7 +29,6 @@
 use Mcp\Capability\Tool\ToolCaller;
 use Mcp\Capability\Tool\ToolCallerInterface;
 use Mcp\Exception\ConfigurationException;
-use Mcp\JsonRpc\Handler;
 use Mcp\Schema\Annotations;
 use Mcp\Schema\Implementation;
 use Mcp\Schema\Prompt;
@@ -39,6 +38,7 @@
 use Mcp\Schema\Tool;
 use Mcp\Schema\ToolAnnotations;
 use Mcp\Server;
+use Mcp\Server\Handler\JsonRpcHandler;
 use Mcp\Server\Session\InMemorySessionStore;
 use Mcp\Server\Session\SessionFactory;
 use Mcp\Server\Session\SessionFactoryInterface;
@@ -334,7 +334,7 @@ public function build(): Server
         $sessionStore = $this->sessionStore ?? new InMemorySessionStore($sessionTtl);
 
         return new Server(
-            jsonRpcHandler: Handler::make(
+            jsonRpcHandler: JsonRpcHandler::make(
                 registry: $registry,
                 referenceProvider: $registry,
                 implementation: $this->serverInfo,
diff --git a/src/Server/Handler/JsonRpcHandler.php b/src/Server/Handler/JsonRpcHandler.php
@@ -9,7 +9,7 @@
  * file that was distributed with this source code.
  */
 
-namespace Mcp\JsonRpc;
+namespace Mcp\Server\Handler;
 
 use Mcp\Capability\Prompt\PromptGetterInterface;
 use Mcp\Capability\Registry\ReferenceProviderInterface;
@@ -20,15 +20,14 @@
 use Mcp\Exception\HandlerNotFoundException;
 use Mcp\Exception\InvalidInputMessageException;
 use Mcp\Exception\NotFoundExceptionInterface;
+use Mcp\JsonRpc\MessageFactory;
 use Mcp\Schema\Implementation;
 use Mcp\Schema\JsonRpc\Error;
 use Mcp\Schema\JsonRpc\HasMethodInterface;
 use Mcp\Schema\JsonRpc\Request;
 use Mcp\Schema\JsonRpc\Response;
 use Mcp\Schema\Request\InitializeRequest;
-use Mcp\Server\MethodHandlerInterface;
-use Mcp\Server\NotificationHandler;
-use Mcp\Server\RequestHandler;
+use Mcp\Server\Handler;
 use Mcp\Server\Session\SessionFactoryInterface;
 use Mcp\Server\Session\SessionInterface;
 use Mcp\Server\Session\SessionStoreInterface;
@@ -41,7 +40,7 @@
  *
  * @author Christopher Hertel <mail@christopher-hertel.de>
  */
-class Handler
+class JsonRpcHandler
 {
     /**
      * @var array<int, MethodHandlerInterface>
@@ -80,15 +79,15 @@ public static function make(
             sessionFactory: $sessionFactory,
             sessionStore: $sessionStore,
             methodHandlers: [
-                new NotificationHandler\InitializedHandler(),
-                new RequestHandler\InitializeHandler($registry->getCapabilities(), $implementation),
-                new RequestHandler\PingHandler(),
-                new RequestHandler\ListPromptsHandler($referenceProvider, $paginationLimit),
-                new RequestHandler\GetPromptHandler($promptGetter),
-                new RequestHandler\ListResourcesHandler($referenceProvider, $paginationLimit),
-                new RequestHandler\ReadResourceHandler($resourceReader),
-                new RequestHandler\CallToolHandler($toolCaller, $logger),
-                new RequestHandler\ListToolsHandler($referenceProvider, $paginationLimit),
+                new Notification\InitializedHandler(),
+                new Handler\Request\InitializeHandler($registry->getCapabilities(), $implementation),
+                new Handler\Request\PingHandler(),
+                new Handler\Request\ListPromptsHandler($referenceProvider, $paginationLimit),
+                new Handler\Request\GetPromptHandler($promptGetter),
+                new Handler\Request\ListResourcesHandler($referenceProvider, $paginationLimit),
+                new Handler\Request\ReadResourceHandler($resourceReader),
+                new Handler\Request\CallToolHandler($toolCaller, $logger),
+                new Handler\Request\ListToolsHandler($referenceProvider, $paginationLimit),
             ],
             logger: $logger,
         );
diff --git a/src/Server/Handler/MethodHandlerInterface.php b/src/Server/Handler/MethodHandlerInterface.php
@@ -9,7 +9,7 @@
  * file that was distributed with this source code.
  */
 
-namespace Mcp\Server;
+namespace Mcp\Server\Handler;
 
 use Mcp\Exception\ExceptionInterface;
 use Mcp\Schema\JsonRpc\Error;
diff --git a/src/Server/Handler/Notification/InitializedHandler.php b/src/Server/Handler/Notification/InitializedHandler.php
@@ -9,13 +9,13 @@
  * file that was distributed with this source code.
  */
 
-namespace Mcp\Server\NotificationHandler;
+namespace Mcp\Server\Handler\Notification;
 
 use Mcp\Schema\JsonRpc\Error;
 use Mcp\Schema\JsonRpc\HasMethodInterface;
 use Mcp\Schema\JsonRpc\Response;
 use Mcp\Schema\Notification\InitializedNotification;
-use Mcp\Server\MethodHandlerInterface;
+use Mcp\Server\Handler\MethodHandlerInterface;
 use Mcp\Server\Session\SessionInterface;
 
 /**
diff --git a/src/Server/Handler/Request/CallToolHandler.php b/src/Server/Handler/Request/CallToolHandler.php
@@ -9,15 +9,15 @@
  * file that was distributed with this source code.
  */
 
-namespace Mcp\Server\RequestHandler;
+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\MethodHandlerInterface;
+use Mcp\Server\Handler\MethodHandlerInterface;
 use Mcp\Server\Session\SessionInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
diff --git a/src/Server/Handler/Request/GetPromptHandler.php b/src/Server/Handler/Request/GetPromptHandler.php
@@ -9,15 +9,15 @@
  * file that was distributed with this source code.
  */
 
-namespace Mcp\Server\RequestHandler;
+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\MethodHandlerInterface;
+use Mcp\Server\Handler\MethodHandlerInterface;
 use Mcp\Server\Session\SessionInterface;
 
 /**
diff --git a/src/Server/Handler/Request/InitializeHandler.php b/src/Server/Handler/Request/InitializeHandler.php
@@ -9,15 +9,15 @@
  * file that was distributed with this source code.
  */
 
-namespace Mcp\Server\RequestHandler;
+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\MethodHandlerInterface;
+use Mcp\Server\Handler\MethodHandlerInterface;
 use Mcp\Server\Session\SessionInterface;
 
 /**
diff --git a/src/Server/Handler/Request/ListPromptsHandler.php b/src/Server/Handler/Request/ListPromptsHandler.php
@@ -9,15 +9,15 @@
  * file that was distributed with this source code.
  */
 
-namespace Mcp\Server\RequestHandler;
+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\MethodHandlerInterface;
+use Mcp\Server\Handler\MethodHandlerInterface;
 use Mcp\Server\Session\SessionInterface;
 
 /**
diff --git a/src/Server/Handler/Request/ListResourcesHandler.php b/src/Server/Handler/Request/ListResourcesHandler.php
@@ -9,15 +9,15 @@
  * file that was distributed with this source code.
  */
 
-namespace Mcp\Server\RequestHandler;
+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\MethodHandlerInterface;
+use Mcp\Server\Handler\MethodHandlerInterface;
 use Mcp\Server\Session\SessionInterface;
 
 /**
diff --git a/src/Server/Handler/Request/ListToolsHandler.php b/src/Server/Handler/Request/ListToolsHandler.php
@@ -9,15 +9,15 @@
  * file that was distributed with this source code.
  */
 
-namespace Mcp\Server\RequestHandler;
+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\MethodHandlerInterface;
+use Mcp\Server\Handler\MethodHandlerInterface;
 use Mcp\Server\Session\SessionInterface;
 
 /**
diff --git a/src/Server/Handler/Request/PingHandler.php b/src/Server/Handler/Request/PingHandler.php
@@ -9,13 +9,13 @@
  * file that was distributed with this source code.
  */
 
-namespace Mcp\Server\RequestHandler;
+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\MethodHandlerInterface;
+use Mcp\Server\Handler\MethodHandlerInterface;
 use Mcp\Server\Session\SessionInterface;
 
 /**
diff --git a/src/Server/Handler/Request/ReadResourceHandler.php b/src/Server/Handler/Request/ReadResourceHandler.php
@@ -9,7 +9,7 @@
  * file that was distributed with this source code.
  */
 
-namespace Mcp\Server\RequestHandler;
+namespace Mcp\Server\Handler\Request;
 
 use Mcp\Capability\Resource\ResourceReaderInterface;
 use Mcp\Exception\ExceptionInterface;
@@ -18,7 +18,7 @@
 use Mcp\Schema\JsonRpc\HasMethodInterface;
 use Mcp\Schema\JsonRpc\Response;
 use Mcp\Schema\Request\ReadResourceRequest;
-use Mcp\Server\MethodHandlerInterface;
+use Mcp\Server\Handler\MethodHandlerInterface;
 use Mcp\Server\Session\SessionInterface;
 
 /**
diff --git a/src/Server/Transport/InMemoryTransport.php b/src/Server/Transport/InMemoryTransport.php
@@ -11,7 +11,6 @@
 
 namespace Mcp\Server\Transport;
 
-use Mcp\Server\TransportInterface;
 use Symfony\Component\Uid\Uuid;
 
 /**
diff --git a/src/Server/Transport/StdioTransport.php b/src/Server/Transport/StdioTransport.php
@@ -11,7 +11,6 @@
 
 namespace Mcp\Server\Transport;
 
-use Mcp\Server\TransportInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
 use Symfony\Component\Uid\Uuid;
diff --git a/src/Server/Transport/StreamableHttpTransport.php b/src/Server/Transport/StreamableHttpTransport.php
@@ -12,7 +12,6 @@
 namespace Mcp\Server\Transport;
 
 use Mcp\Schema\JsonRpc\Error;
-use Mcp\Server\TransportInterface;
 use Psr\Http\Message\ResponseFactoryInterface;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
diff --git a/src/Server/Transport/TransportInterface.php b/src/Server/Transport/TransportInterface.php
@@ -9,7 +9,7 @@
  * file that was distributed with this source code.
  */
 
-namespace Mcp\Server;
+namespace Mcp\Server\Transport;
 
 use Symfony\Component\Uid\Uuid;
 
diff --git a/tests/Unit/JsonRpc/HandlerTest.php b/tests/Unit/JsonRpc/HandlerTest.php
@@ -11,10 +11,10 @@
 
 namespace Mcp\Tests\Unit\JsonRpc;
 
-use Mcp\JsonRpc\Handler;
 use Mcp\JsonRpc\MessageFactory;
 use Mcp\Schema\JsonRpc\Response;
-use Mcp\Server\MethodHandlerInterface;
+use Mcp\Server\Handler\JsonRpcHandler;
+use Mcp\Server\Handler\MethodHandlerInterface;
 use Mcp\Server\Session\SessionFactoryInterface;
 use Mcp\Server\Session\SessionInterface;
 use Mcp\Server\Session\SessionStoreInterface;
@@ -56,7 +56,7 @@ public function testHandleMultipleNotifications()
         $sessionFactory->method('createWithId')->willReturn($session);
         $sessionStore->method('exists')->willReturn(true);
 
-        $jsonRpc = new Handler(
+        $jsonRpc = new JsonRpcHandler(
             MessageFactory::make(),
             $sessionFactory,
             $sessionStore,
@@ -102,7 +102,7 @@ public function testHandleMultipleRequests()
         $sessionFactory->method('createWithId')->willReturn($session);
         $sessionStore->method('exists')->willReturn(true);
 
-        $jsonRpc = new Handler(
+        $jsonRpc = new JsonRpcHandler(
             MessageFactory::make(),
             $sessionFactory,
             $sessionStore,
diff --git a/tests/Unit/Server/Handler/Request/CallToolHandlerTest.php b/tests/Unit/Server/Handler/Request/CallToolHandlerTest.php
@@ -9,7 +9,7 @@
  * file that was distributed with this source code.
  */
 
-namespace Mcp\Tests\Unit\Server\RequestHandler;
+namespace Mcp\Tests\Unit\Server\Handler\Request;
 
 use Mcp\Capability\Tool\ToolCallerInterface;
 use Mcp\Exception\ToolCallException;
@@ -19,7 +19,7 @@
 use Mcp\Schema\JsonRpc\Response;
 use Mcp\Schema\Request\CallToolRequest;
 use Mcp\Schema\Result\CallToolResult;
-use Mcp\Server\RequestHandler\CallToolHandler;
+use Mcp\Server\Handler\Request\CallToolHandler;
 use Mcp\Server\Session\SessionInterface;
 use PHPUnit\Framework\MockObject\MockObject;
 use PHPUnit\Framework\TestCase;
diff --git a/tests/Unit/Server/Handler/Request/GetPromptHandlerTest.php b/tests/Unit/Server/Handler/Request/GetPromptHandlerTest.php
diff --git a/tests/Unit/Server/Handler/Request/ListPromptsHandlerTest.php b/tests/Unit/Server/Handler/Request/ListPromptsHandlerTest.php
diff --git a/tests/Unit/Server/Handler/Request/ListResourcesHandlerTest.php b/tests/Unit/Server/Handler/Request/ListResourcesHandlerTest.php
diff --git a/tests/Unit/Server/Handler/Request/ListToolsHandlerTest.php b/tests/Unit/Server/Handler/Request/ListToolsHandlerTest.php
diff --git a/tests/Unit/Server/Handler/Request/PingHandlerTest.php b/tests/Unit/Server/Handler/Request/PingHandlerTest.php
diff --git a/tests/Unit/Server/Handler/Request/ReadResourceHandlerTest.php b/tests/Unit/Server/Handler/Request/ReadResourceHandlerTest.php
diff --git a/tests/Unit/ServerTest.php b/tests/Unit/ServerTest.php
