[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

Author: CodeWithKyrian

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;

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.

…Server/RequestHandler/Reference/Page.php src/Schema/Page.phpsrc/Server/RequestHandler/Reference/Page.php renamed to src/Schema/Page.php src/Server/RequestHandler/Reference/Page.php renamed to 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,

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(),
     ) {
     }

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,

src/JsonRpc/Handler.php src/Server/Handler/JsonRpcHandler.phpsrc/JsonRpc/Handler.php renamed to 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,
         );

src/Server/MethodHandlerInterface.php …erver/Handler/MethodHandlerInterface.phpsrc/Server/MethodHandlerInterface.php renamed to src/Server/Handler/MethodHandlerInterface.php src/Server/MethodHandlerInterface.php renamed to 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;

…tificationHandler/InitializedHandler.php …dler/Notification/InitializedHandler.phpsrc/Server/NotificationHandler/InitializedHandler.php renamed to src/Server/Handler/Notification/InitializedHandler.php src/Server/NotificationHandler/InitializedHandler.php renamed to 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;
 
 /**

…erver/RequestHandler/CallToolHandler.php …rver/Handler/Request/CallToolHandler.phpsrc/Server/RequestHandler/CallToolHandler.php renamed to src/Server/Handler/Request/CallToolHandler.php src/Server/RequestHandler/CallToolHandler.php renamed to 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;

…rver/RequestHandler/GetPromptHandler.php …ver/Handler/Request/GetPromptHandler.phpsrc/Server/RequestHandler/GetPromptHandler.php renamed to src/Server/Handler/Request/GetPromptHandler.php src/Server/RequestHandler/GetPromptHandler.php renamed to 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;
 
 /**