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
This commit is contained in:
Kyrian Obikwelu 2025-09-21 11:12:40 +01:00 • committed by GitHub
commit 719262b15d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 1614 additions and 406 deletions

View file

@ -20,6 +20,7 @@ use Mcp\Schema\JsonRpc\Response;
use Mcp\Schema\Request\CallToolRequest;
use Mcp\Schema\Result\CallToolResult;
use Mcp\Server\RequestHandler\CallToolHandler;
use Mcp\Server\Session\SessionInterface;
use PHPUnit\Framework\MockObject\MockObject;
use PHPUnit\Framework\TestCase;
use Psr\Log\LoggerInterface;
@ -27,16 +28,18 @@ use Psr\Log\LoggerInterface;
class CallToolHandlerTest extends TestCase
{
private CallToolHandler $handler;
private ToolCallerInterface|MockObject $toolExecutor;
private ToolCallerInterface|MockObject $toolCaller;
private LoggerInterface|MockObject $logger;
private SessionInterface|MockObject $session;
protected function setUp(): void
{
$this->toolExecutor = $this->createMock(ToolCallerInterface::class);
$this->toolCaller = $this->createMock(ToolCallerInterface::class);
$this->logger = $this->createMock(LoggerInterface::class);
$this->session = $this->createMock(SessionInterface::class);
$this->handler = new CallToolHandler(
$this->toolExecutor,
$this->toolCaller,
$this->logger,
);
}
@ -53,7 +56,7 @@ class CallToolHandlerTest extends TestCase
$request = $this->createCallToolRequest('greet_user', ['name' => 'John']);
$expectedResult = new CallToolResult([new TextContent('Hello, John!')]);
$this->toolExecutor
$this->toolCaller
->expects($this->once())
->method('call')
->with($request)
@ -63,7 +66,7 @@ class CallToolHandlerTest extends TestCase
->expects($this->never())
->method('error');
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertEquals($request->getId(), $response->id);
@ -75,13 +78,13 @@ class CallToolHandlerTest extends TestCase
$request = $this->createCallToolRequest('simple_tool', []);
$expectedResult = new CallToolResult([new TextContent('Simple result')]);
$this->toolExecutor
$this->toolCaller
->expects($this->once())
->method('call')
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -99,13 +102,13 @@ class CallToolHandlerTest extends TestCase
$request = $this->createCallToolRequest('complex_tool', $arguments);
$expectedResult = new CallToolResult([new TextContent('Complex result')]);
$this->toolExecutor
$this->toolCaller
->expects($this->once())
->method('call')
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -116,7 +119,7 @@ class CallToolHandlerTest extends TestCase
$request = $this->createCallToolRequest('nonexistent_tool', ['param' => 'value']);
$exception = new ToolNotFoundException($request);
$this->toolExecutor
$this->toolCaller
->expects($this->once())
->method('call')
->with($request)
@ -133,7 +136,7 @@ class CallToolHandlerTest extends TestCase
],
);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Error::class, $response);
$this->assertEquals($request->getId(), $response->id);
@ -146,7 +149,7 @@ class CallToolHandlerTest extends TestCase
$request = $this->createCallToolRequest('failing_tool', ['param' => 'value']);
$exception = new ToolCallException($request, new \RuntimeException('Tool execution failed'));
$this->toolExecutor
$this->toolCaller
->expects($this->once())
->method('call')
->with($request)
@ -163,7 +166,7 @@ class CallToolHandlerTest extends TestCase
],
);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Error::class, $response);
$this->assertEquals($request->getId(), $response->id);
@ -176,13 +179,13 @@ class CallToolHandlerTest extends TestCase
$request = $this->createCallToolRequest('null_tool', []);
$expectedResult = new CallToolResult([]);
$this->toolExecutor
$this->toolCaller
->expects($this->once())
->method('call')
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -193,13 +196,13 @@ class CallToolHandlerTest extends TestCase
$request = $this->createCallToolRequest('error_tool', []);
$expectedResult = CallToolResult::error([new TextContent('Tool error occurred')]);
$this->toolExecutor
$this->toolCaller
->expects($this->once())
->method('call')
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -208,7 +211,7 @@ class CallToolHandlerTest extends TestCase
public function testConstructorWithDefaultLogger(): void
{
$handler = new CallToolHandler($this->toolExecutor);
$handler = new CallToolHandler($this->toolCaller);
$this->assertInstanceOf(CallToolHandler::class, $handler);
}
@ -218,7 +221,7 @@ class CallToolHandlerTest extends TestCase
$request = $this->createCallToolRequest('test_tool', ['key1' => 'value1', 'key2' => 42]);
$exception = new ToolCallException($request, new \RuntimeException('Custom error message'));
$this->toolExecutor
$this->toolCaller
->expects($this->once())
->method('call')
->willThrowException($exception);
@ -234,7 +237,7 @@ class CallToolHandlerTest extends TestCase
],
);
$this->handler->handle($request);
$this->handler->handle($request, $this->session);
}
public function testHandleWithSpecialCharactersInToolName(): void
@ -242,13 +245,13 @@ class CallToolHandlerTest extends TestCase
$request = $this->createCallToolRequest('tool-with_special.chars', []);
$expectedResult = new CallToolResult([new TextContent('Special tool result')]);
$this->toolExecutor
$this->toolCaller
->expects($this->once())
->method('call')
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -264,13 +267,13 @@ class CallToolHandlerTest extends TestCase
$request = $this->createCallToolRequest('unicode_tool', $arguments);
$expectedResult = new CallToolResult([new TextContent('Unicode handled')]);
$this->toolExecutor
$this->toolCaller
->expects($this->once())
->method('call')
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);

View file

@ -22,6 +22,7 @@ use Mcp\Schema\JsonRpc\Response;
use Mcp\Schema\Request\GetPromptRequest;
use Mcp\Schema\Result\GetPromptResult;
use Mcp\Server\RequestHandler\GetPromptHandler;
use Mcp\Server\Session\SessionInterface;
use PHPUnit\Framework\MockObject\MockObject;
use PHPUnit\Framework\TestCase;
@ -29,10 +30,12 @@ class GetPromptHandlerTest extends TestCase
{
private GetPromptHandler $handler;
private PromptGetterInterface|MockObject $promptGetter;
private SessionInterface|MockObject $session;
protected function setUp(): void
{
$this->promptGetter = $this->createMock(PromptGetterInterface::class);
$this->session = $this->createMock(SessionInterface::class);
$this->handler = new GetPromptHandler($this->promptGetter);
}
@ -61,7 +64,7 @@ class GetPromptHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertEquals($request->getId(), $response->id);
@ -93,7 +96,7 @@ class GetPromptHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -116,7 +119,7 @@ class GetPromptHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -139,7 +142,7 @@ class GetPromptHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -164,7 +167,7 @@ class GetPromptHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -182,7 +185,7 @@ class GetPromptHandlerTest extends TestCase
->with($request)
->willThrowException($exception);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Error::class, $response);
$this->assertEquals($request->getId(), $response->id);
@ -201,7 +204,7 @@ class GetPromptHandlerTest extends TestCase
->with($request)
->willThrowException($exception);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Error::class, $response);
$this->assertEquals($request->getId(), $response->id);
@ -241,7 +244,7 @@ class GetPromptHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -269,7 +272,7 @@ class GetPromptHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -289,7 +292,7 @@ class GetPromptHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -318,7 +321,7 @@ class GetPromptHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);

View file

@ -16,14 +16,17 @@ use Mcp\Schema\JsonRpc\Response;
use Mcp\Schema\Request\PingRequest;
use Mcp\Schema\Result\EmptyResult;
use Mcp\Server\RequestHandler\PingHandler;
use Mcp\Server\Session\SessionInterface;
use PHPUnit\Framework\TestCase;
class PingHandlerTest extends TestCase
{
private PingHandler $handler;
private SessionInterface $session;
protected function setUp(): void
{
$this->session = $this->createMock(SessionInterface::class);
$this->handler = new PingHandler();
}
@ -38,7 +41,7 @@ class PingHandlerTest extends TestCase
{
$request = $this->createPingRequest();
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertEquals($request->getId(), $response->id);
@ -50,8 +53,8 @@ class PingHandlerTest extends TestCase
$request1 = $this->createPingRequest();
$request2 = $this->createPingRequest();
$response1 = $this->handler->handle($request1);
$response2 = $this->handler->handle($request2);
$response1 = $this->handler->handle($request1, $this->session);
$response2 = $this->handler->handle($request2, $this->session);
$this->assertInstanceOf(Response::class, $response1);
$this->assertInstanceOf(Response::class, $response2);
@ -66,8 +69,8 @@ class PingHandlerTest extends TestCase
$request = $this->createPingRequest();
// Handle same request multiple times
$response1 = $this->handler->handle($request);
$response2 = $this->handler->handle($request);
$response1 = $this->handler->handle($request, $this->session);
$response2 = $this->handler->handle($request, $this->session);
// Both responses should be identical
$this->assertEquals($response1->id, $response2->id);
@ -80,7 +83,7 @@ class PingHandlerTest extends TestCase
public function testEmptyResultIsCorrectType(): void
{
$request = $this->createPingRequest();
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(EmptyResult::class, $response->result);
@ -96,8 +99,8 @@ class PingHandlerTest extends TestCase
$request = $this->createPingRequest();
$response1 = $handler1->handle($request);
$response2 = $handler2->handle($request);
$response1 = $handler1->handle($request, $this->session);
$response2 = $handler2->handle($request, $this->session);
// Both handlers should produce equivalent results
$this->assertEquals($response1->id, $response2->id);
@ -125,7 +128,7 @@ class PingHandlerTest extends TestCase
// Create multiple ping requests
for ($i = 0; $i < 5; ++$i) {
$requests[$i] = $this->createPingRequest();
$responses[$i] = $this->handler->handle($requests[$i]);
$responses[$i] = $this->handler->handle($requests[$i], $this->session);
}
// All responses should be valid

View file

@ -21,6 +21,7 @@ use Mcp\Schema\JsonRpc\Response;
use Mcp\Schema\Request\ReadResourceRequest;
use Mcp\Schema\Result\ReadResourceResult;
use Mcp\Server\RequestHandler\ReadResourceHandler;
use Mcp\Server\Session\SessionInterface;
use PHPUnit\Framework\MockObject\MockObject;
use PHPUnit\Framework\TestCase;
@ -28,10 +29,12 @@ class ReadResourceHandlerTest extends TestCase
{
private ReadResourceHandler $handler;
private ResourceReaderInterface|MockObject $resourceReader;
private SessionInterface|MockObject $session;
protected function setUp(): void
{
$this->resourceReader = $this->createMock(ResourceReaderInterface::class);
$this->session = $this->createMock(SessionInterface::class);
$this->handler = new ReadResourceHandler($this->resourceReader);
}
@ -60,7 +63,7 @@ class ReadResourceHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertEquals($request->getId(), $response->id);
@ -84,7 +87,7 @@ class ReadResourceHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -112,7 +115,7 @@ class ReadResourceHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -131,7 +134,7 @@ class ReadResourceHandlerTest extends TestCase
->with($request)
->willThrowException($exception);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Error::class, $response);
$this->assertEquals($request->getId(), $response->id);
@ -154,7 +157,7 @@ class ReadResourceHandlerTest extends TestCase
->with($request)
->willThrowException($exception);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Error::class, $response);
$this->assertEquals($request->getId(), $response->id);
@ -188,7 +191,7 @@ class ReadResourceHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -216,7 +219,7 @@ class ReadResourceHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -239,7 +242,7 @@ class ReadResourceHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -287,7 +290,7 @@ class ReadResourceHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);
@ -311,7 +314,7 @@ class ReadResourceHandlerTest extends TestCase
->with($request)
->willThrowException($exception);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Error::class, $response);
$this->assertEquals(Error::RESOURCE_NOT_FOUND, $response->code);
@ -330,7 +333,7 @@ class ReadResourceHandlerTest extends TestCase
->with($request)
->willReturn($expectedResult);
$response = $this->handler->handle($request);
$response = $this->handler->handle($request, $this->session);
$this->assertInstanceOf(Response::class, $response);
$this->assertSame($expectedResult, $response->result);