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`.

Author: CodeWithKyrian

src/JsonRpc/Handler.php

@@ -27,6 +27,7 @@
 use Mcp\Server\MethodHandlerInterface;
 use Mcp\Server\NotificationHandler;
 use Mcp\Server\RequestHandler;
+use Symfony\Component\Uid\Uuid;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
 
@@ -87,7 +88,7 @@ public static function make(
      * @throws ExceptionInterface When a handler throws an exception during message processing
      * @throws \JsonException     When JSON encoding of the response fails
      */
-    public function process(string $input): iterable
+    public function process(string $input, ?Uuid $sessionId): iterable
     {
         $this->logger->info('Received message to process.', ['message' => $input]);
 
@@ -117,7 +118,9 @@ public function process(string $input): iterable
             } catch (\DomainException) {
                 yield null;
             } catch (NotFoundExceptionInterface $e) {
-                $this->logger->warning(\sprintf('Failed to create response: %s', $e->getMessage()), ['exception' => $e],
+                $this->logger->warning(
+                    \sprintf('Failed to create response: %s', $e->getMessage()),
+                    ['exception' => $e],
                 );
 
                 yield $this->encodeResponse(Error::forMethodNotFound($e->getMessage()));

src/Server.php

@@ -18,6 +18,7 @@
 use Mcp\Server\TransportInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
+use Symfony\Component\Uid\Uuid;
 
 /**
  * @author Christopher Hertel <[email protected]>
@@ -45,15 +46,15 @@ public function connect(TransportInterface $transport): void
             'transport' => $transport::class,
         ]);
 
-        $transport->on('message', function (string $message) use ($transport) {
-            $this->handleMessage($message, $transport);
+        $transport->onMessage(function (string $message, ?Uuid $sessionId) use ($transport) {
+            $this->handleMessage($message, $sessionId, $transport);
         });
     }
 
-    private function handleMessage(string $message, TransportInterface $transport): void
+    private function handleMessage(string $message, ?Uuid $sessionId, TransportInterface $transport): void
     {
         try {
-            foreach ($this->jsonRpcHandler->process($message) as $response) {
+            foreach ($this->jsonRpcHandler->process($message, $sessionId) as $response) {
                 if (null === $response) {
                     continue;
                 }

src/Server/Session/SessionFactory.php

@@ -13,13 +13,13 @@
  */
 class SessionFactory implements SessionFactoryInterface
 {
-    public function create(Uuid $id, SessionStoreInterface $store): SessionInterface
+    public function create(SessionStoreInterface $store): SessionInterface
     {
-        return new Session($store, $id);
+        return new Session($store, Uuid::v4());
     }
 
-    public function createNew(SessionStoreInterface $store): SessionInterface
+    public function createWithId(Uuid $id, SessionStoreInterface $store): SessionInterface
     {
-        return $this->create(Uuid::v4(), $store);
+        return new Session($store, $id);
     }
 }

src/Server/Session/SessionFactoryInterface.php

@@ -15,12 +15,14 @@
 interface SessionFactoryInterface
 {
     /**
-     * Create a session with a specific UUID.
+     * Creates a new session with an auto-generated UUID.
+     * This is the standard factory method for creating sessions.
      */
-    public function create(Uuid $id, SessionStoreInterface $store): SessionInterface;
+    public function create(SessionStoreInterface $store): SessionInterface;
 
     /**
-     * Create a new session with a generated UUID.
+     * Creates a session with a specific UUID.
+     * Use this when you need to reconstruct a session with a known ID.
      */
-    public function createNew(SessionStoreInterface $store): SessionInterface;
+    public function createWithId(Uuid $id, SessionStoreInterface $store): SessionInterface;
 }

src/Server/Transport/StdioTransport.php

@@ -12,16 +12,14 @@
 namespace Mcp\Server\Transport;
 
 use Mcp\Server\TransportInterface;
-use Psr\Log\LoggerInterface;
+use Symfony\Component\Uid\Uuid;
+use Symfony\Component\Uid\UuidV4;
 use Psr\Log\NullLogger;
+use Psr\Log\LoggerInterface;
 
-/**
- * Heavily inspired by https://jolicode.com/blog/mcp-the-open-protocol-that-turns-llm-chatbots-into-intelligent-agents.
- */
 class StdioTransport implements TransportInterface
 {
-    /** @var array<string, array<callable>> */
-    private array $listeners = [];
+    private $messageListener;
 
     /**
      * @param resource $input
@@ -30,27 +28,15 @@ class StdioTransport implements TransportInterface
     public function __construct(
         private $input = \STDIN,
         private $output = \STDOUT,
-        private readonly LoggerInterface $logger = new NullLogger(),
+        private readonly Uuid $sessionId = new UuidV4(),
+        private readonly LoggerInterface $logger = new NullLogger()
     ) {}
 
     public function initialize(): void {}
 
-    public function on(string $event, callable $listener): void
+    public function onMessage(callable $listener): void
     {
-        if (!isset($this->listeners[$event])) {
-            $this->listeners[$event] = [];
-        }
-        $this->listeners[$event][] = $listener;
-    }
-
-    public function emit(string $event, mixed ...$args): void
-    {
-        if (!isset($this->listeners[$event])) {
-            return;
-        }
-        foreach ($this->listeners[$event] as $listener) {
-            $listener(...$args);
-        }
+        $this->messageListener = $listener;
     }
 
     public function send(string $data): void
@@ -73,7 +59,7 @@ public function listen(): mixed
             $trimmedLine = trim($line);
             if (!empty($trimmedLine)) {
                 $this->logger->debug('Received message on StdioTransport.', ['line' => $trimmedLine]);
-                $this->emit('message', $trimmedLine);
+                call_user_func($this->messageListener, $trimmedLine, $this->sessionId);
             }
         }
 

src/Server/Transport/StreamableHttpTransport.php

@@ -19,14 +19,15 @@
 use Psr\Http\Message\StreamFactoryInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
+use Symfony\Component\Uid\Uuid;
 
 /**
  * @author Kyrian Obikwelu <[email protected]>
  */
 class StreamableHttpTransport implements TransportInterface
 {
-    /** @var array<string, array<callable>> */
-    private array $listeners = [];
+    private $messageListener;
+    private ?Uuid $sessionId = null;
 
     /** @var string[] */
     private array $outgoingMessages = [];
@@ -42,27 +43,16 @@ public function __construct(
         private readonly ResponseFactoryInterface $responseFactory,
         private readonly StreamFactoryInterface $streamFactory,
         private readonly LoggerInterface $logger = new NullLogger()
-    ) {}
+    ) {
+        $sessionIdString = $this->request->getHeaderLine('Mcp-Session-Id');
+        $this->sessionId = $sessionIdString ? Uuid::fromString($sessionIdString) : null;
+    }
 
     public function initialize(): void {}
 
-    public function on(string $event, callable $listener): void
-    {
-        if (!isset($this->listeners[$event])) {
-            $this->listeners[$event] = [];
-        }
-        $this->listeners[$event][] = $listener;
-    }
-
-    public function emit(string $event, mixed ...$args): void
+    public function onMessage(callable $listener): void
     {
-        if (!isset($this->listeners[$event])) {
-            return;
-        }
-
-        foreach ($this->listeners[$event] as $listener) {
-            $listener(...$args);
-        }
+        $this->messageListener = $listener;
     }
 
     public function send(string $data): void
@@ -106,7 +96,7 @@ protected function handlePostRequest(): ResponseInterface
             return $this->createErrorResponse($error, 400);
         }
 
-        $this->emit('message', $body);
+        call_user_func($this->messageListener, $body, $this->sessionId);
 
         $hasRequestsInInput = str_contains($body, '"id"');
         $hasResponsesInOutput = !empty($this->outgoingMessages);

src/Server/TransportInterface.php

@@ -11,6 +11,8 @@
 
 namespace Mcp\Server;
 
+use Symfony\Component\Uid\Uuid;
+
 /**
  * @author Christopher Hertel <[email protected]>
  * @author Kyrian Obikwelu <[email protected]>
@@ -23,20 +25,11 @@ interface TransportInterface
     public function initialize(): void;
 
     /**
-     * Registers an event listener for the specified event.
-     *
-     * @param string $event The event name to listen for
-     * @param callable $listener The callback function to execute when the event occurs
-     */
-    public function on(string $event, callable $listener): void;
-
-    /**
-     * Triggers an event and executes all registered listeners.
+     * Registers a callback that will be invoked whenever the transport receives an incoming message.
      *
-     * @param string $event The event name to emit
-     * @param mixed ...$args Variable number of arguments to pass to the listeners
+     * @param callable(string $message, ?Uuid $sessionId): void $listener The callback function to execute when the message occurs
      */
-    public function emit(string $event, mixed ...$args): void;
+    public function onMessage(callable $listener): void;
 
     /**
      * Starts the transport's execution process.