[Server] Add Bidirectional Client Communication Support (#109)

* feat(server): add bidirectional client communication support

* fix(server): use correct session ID string conversion method

* fix: clean up docblocks for request handler methods in Builder

* fix: merge artifacts

src/Server/Transport/TransportInterface.php

@@ -11,11 +11,21 @@
 
 namespace Mcp\Server\Transport;
 
+use Mcp\Schema\JsonRpc\Error;
+use Mcp\Schema\JsonRpc\Response;
 use Symfony\Component\Uid\Uuid;
 
 /**
  * @template TResult
  *
+ * @phpstan-type FiberReturn (Response<mixed>|Error)
+ * @phpstan-type FiberResume (FiberReturn|null)
+ * @phpstan-type FiberSuspend (
+ *    array{type: 'notification', notification: \Mcp\Schema\JsonRpc\Notification}|
+ *    array{type: 'request', request: \Mcp\Schema\JsonRpc\Request, timeout?: int}
+ * )
+ * @phpstan-type McpFiber \Fiber<null, FiberReturn, FiberReturn, FiberSuspend>
+ *
  * @author Christopher Hertel <mail@christopher-hertel.de>
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
  */
@@ -26,15 +36,6 @@ interface TransportInterface
      */
     public function initialize(): void;
 
-    /**
-     * Register callback for ALL incoming messages.
-     *
-     * The transport calls this whenever ANY message arrives, regardless of source.
-     *
-     * @param callable(string $message, ?Uuid $sessionId): void $listener
-     */
-    public function onMessage(callable $listener): void;
-
     /**
      * Starts the transport's execution process.
      *
@@ -47,32 +48,85 @@ interface TransportInterface
     public function listen(): mixed;
 
     /**
-     * Send a message to the client.
+     * Send a message to the client immediately (bypassing session queue).
      *
-     * The transport decides HOW to send based on context
+     * Used for session resolution errors when no session is available.
+     * The transport decides HOW to send based on context.
      *
      * @param array<string, mixed> $context Context about this message:
      *                                      - 'session_id': Uuid|null
      *                                      - 'type': 'response'|'request'|'notification'
-     *                                      - 'in_reply_to': int|string|null (ID of request this responds to)
-     *                                      - 'expects_response': bool (if this is a request needing response)
+     *                                      - 'status_code': int (HTTP status code for errors)
      */
     public function send(string $data, array $context): void;
 
     /**
-     * Register callback for session termination.
+     * Closes the transport and cleans up any resources.
+     */
+    public function close(): void;
+
+    /**
+     * Register callback for ALL incoming messages.
      *
-     * This can happen when a client disconnects or explicitly ends their session.
+     * The transport calls this whenever ANY message arrives, regardless of source.
+     *
+     * @param callable(string $message, ?Uuid $sessionId): void $listener
+     */
+    public function onMessage(callable $listener): void;
+
+    /**
+     * Register a listener for when a session is terminated.
+     *
+     * The transport calls this 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.
+     * Set a provider function to retrieve all queued outgoing messages.
      *
-     * This method should be called when the transport is no longer needed.
-     * It should clean up any resources and close any connections.
+     * The transport calls this to retrieve all queued messages for a session.
+     *
+     * @param callable(Uuid $sessionId): array<int, array{message: string, context: array<string, mixed>}> $provider
      */
-    public function close(): void;
+    public function setOutgoingMessagesProvider(callable $provider): void;
+
+    /**
+     * Set a provider function to retrieve all pending server-initiated requests.
+     *
+     * The transport calls this to decide if it should wait for a client response before resuming a Fiber.
+     *
+     * @param callable(Uuid $sessionId): array<int, array<string, mixed>> $provider
+     */
+    public function setPendingRequestsProvider(callable $provider): void;
+
+    /**
+     * Set a finder function to check for a specific client response.
+     *
+     * @param callable(int, Uuid):FiberResume $finder
+     */
+    public function setResponseFinder(callable $finder): void;
+
+    /**
+     * Set a handler for processing values yielded from a suspended Fiber.
+     *
+     * The transport calls this to let the Protocol handle new requests/notifications
+     * that are yielded from a Fiber's execution.
+     *
+     * @param callable(FiberSuspend|null, ?Uuid $sessionId): void $handler
+     */
+    public function setFiberYieldHandler(callable $handler): void;
+
+    /**
+     * @param McpFiber $fiber
+     */
+    public function attachFiberToSession(\Fiber $fiber, Uuid $sessionId): void;
+
+    /**
+     * Set the session ID for the current transport context.
+     *
+     * @param Uuid|null $sessionId The session ID, or null to clear
+     */
+    public function setSessionId(?Uuid $sessionId): void;
 }