feat(server): Rework transport architecture and add StreamableHttpTransport (#49)

* feat(server): Rework transport architecture and add StreamableHttpTransport

- `Server::connect()` no longer contains a processing loop.
- `TransportInterface` is updated with `setMessageHandler()` and `listen()`.
- `StdioTransport` is updated to implement the new interface.
- A new, minimal `StreamableHttpTransport` is added for stateless HTTP.

* refactor(server): use  event-driven message handling

* feat(server): Introduce a formal session management system

* fix: ensure session elements are preserved when building server (regression from #46)

* refactor: consolidate HTTP example to use shared dependencies

* feat(server): Enhance message handling with session support

- Updated `TransportInterface` to use `onMessage` for handling incoming messages with session IDs.
- Refactored `Server`, `Handler`, and transport classes to accommodate session management using `Uuid`.
- Introduced methods for creating sessions with auto-generated and specific UUIDs in `SessionFactory` and `SessionFactoryInterface`.

* feat(server): Integrate session management in message handling

- Added session support to the `Server` and `Handler` classes, allowing for session data to be managed during message processing.
- Updated `TransportInterface` to include session context in the `send` method.
- Refactored various request handlers to utilize session information, ensuring proper session handling for incoming requests.
- Introduced a file-based session store for persistent session data management

* feat: Update session builder method to use set* instead of with*

* feat: Fix test compatibility with new session management architecture

* chore: apply code style fixes

* fix: remove deprecated SSE transport and resolve PHPStan issues

src/Server/TransportInterface.php

@@ -11,18 +11,58 @@
 
 namespace Mcp\Server;
 
+use Symfony\Component\Uid\Uuid;
+
 /**
  * @author Christopher Hertel <mail@christopher-hertel.de>
+ * @author Kyrian Obikwelu <koshnawaza@gmail.com>
  */
 interface TransportInterface
 {
+    /**
+     * Initializes the transport.
+     */
     public function initialize(): void;
 
-    public function isConnected(): bool;
+    /**
+     * Registers a callback that will be invoked whenever the transport receives an incoming message.
+     *
+     * @param callable(string $message, ?Uuid $sessionId): void $listener The callback function to execute when the message occurs
+     */
+    public function onMessage(callable $listener): void;
 
-    public function receive(): \Generator;
+    /**
+     * Starts the transport's execution process.
+     *
+     * - For a blocking transport like STDIO, this method will run a continuous loop.
+     * - For a single-request transport like HTTP, this will process the request
+     *   and return a result (e.g., a PSR-7 Response) to be sent to the client.
+     *
+     * @return mixed the result of the transport's execution, if any
+     */
+    public function listen(): mixed;
 
-    public function send(string $data): void;
+    /**
+     * Sends a raw JSON-RPC message string back to the client.
+     *
+     * @param string               $data    The JSON-RPC message string to send
+     * @param array<string, mixed> $context The context of the message
+     */
+    public function send(string $data, array $context): void;
 
+    /**
+     * Registers a callback that will be invoked when a session needs to be destroyed.
+     * This can happen when a client disconnects or explicitly ends their session.
+     *
+     * @param callable(Uuid $sessionId): void $listener The callback function to execute when destroying a session
+     */
+    public function onSessionEnd(callable $listener): void;
+
+    /**
+     * Closes the transport and cleans up any resources.
+     *
+     * This method should be called when the transport is no longer needed.
+     * It should clean up any resources and close any connections.
+     */
     public function close(): void;
 }