feat(server): add server lifecycle events

Author: EdouardCourty

README.md

@@ -255,6 +255,7 @@ $server = Server::builder()
 - [Transports](docs/transports.md) - STDIO and HTTP transport setup and usage
 - [MCP Elements](docs/mcp-elements.md) - Creating tools, resources, and prompts
 - [Client Communication](docs/client-communication.md) - Communicating back to the client from server-side
+- [Events](docs/events.md) - Hooking into server lifecycle with events
 
 **Learning:**
 - [Examples](docs/examples.md) - Comprehensive example walkthroughs

docs/events.md

@@ -0,0 +1,94 @@
+# Events
+
+The MCP SDK provides a PSR-14 compatible event system that allows you to hook into the server's lifecycle. Events enable logging, monitoring, validation, caching, and other custom behaviors.
+
+## Table of Contents
+
+- [Setup](#setup)
+- [List Change Events](#list-change-events)
+- [Lifecycle Events](#lifecycle-events)
+  - [Tool Events](#tool-events)
+  - [Prompt Events](#prompt-events)
+  - [Resource Events](#resource-events)
+- [Server Events](#server-events)
+- [Use Cases](#use-cases)
+
+## Setup
+
+Configure an event dispatcher when building your server:
+
+```php
+use Mcp\Server;
+use Symfony\Component\EventDispatcher\EventDispatcher;
+
+$dispatcher = new EventDispatcher();
+
+// Register your listeners
+$dispatcher->addListener(CallToolResultEvent::class, function (CallToolResultEvent $event) {
+    // Handle event
+});
+
+$server = Server::builder()
+    ->setEventDispatcher($dispatcher)
+    ->build();
+```
+
+## List Change Events
+
+These events are dispatched when the lists of available capabilities change:
+
+| Event | Description |
+|-------|-------------|
+| `ToolListChangedEvent` | Dispatched when the list of available tools changes |
+| `ResourceListChangedEvent` | Dispatched when the list of available resources changes |
+| `ResourceTemplateListChangedEvent` | Dispatched when the list of available resource templates changes |
+| `PromptListChangedEvent` | Dispatched when the list of available prompts changes |
+
+These events carry no data and are used to notify clients that they should refresh their capability lists.
+
+```php
+use Mcp\Event\ToolListChangedEvent;
+
+$dispatcher->addListener(ToolListChangedEvent::class, function (ToolListChangedEvent $event) {
+    $logger->info('Tool list has changed, clients should refresh');
+});
+```
+
+## Lifecycle Events
+
+### Tool Events
+
+Events for the tool call lifecycle:
+
+| Event | Timing                     | Data |
+|-------|----------------------------|------|
+| `CallToolRequestEvent` | Before tool execution      | `request` |
+| `CallToolResultEvent` | After successful execution | `request`, `result` |
+| `CallToolExceptionEvent` | On uncaught exception      | `request`, `throwable` |
+
+### Prompt Events
+
+Events for the prompt retrieval lifecycle:
+
+| Event | Timing                     | Data |
+|-------|----------------------------|------|
+| `GetPromptRequestEvent` | Before prompt execution    | `request` |
+| `GetPromptResultEvent` | After successful execution | `request`, `result` |
+| `GetPromptExceptionEvent` | On uncaught exception      | `request`, `throwable` |
+
+### Resource Events
+
+Events for the resource read lifecycle:
+
+| Event | Timing                | Data |
+|-------|-----------------------|------|
+| `ReadResourceRequestEvent` | Before resource read  | `request` |
+| `ReadResourceResultEvent` | After successful read | `request`, `result` |
+| `ReadResourceExceptionEvent` | On uncaught exception | `request`, `throwable` |
+
+## Server Events
+
+| Event | Timing | Data |
+|-------|--------|------|
+| `InitializeRequestEvent` | When client sends initialize request | `request` (InitializeRequest) |
+| `PingRequestEvent` | When client sends ping request | `request` (PingRequest) |

src/Event/InitializeRequestEvent.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Event;
+
+use Mcp\Schema\Request\InitializeRequest;
+
+/**
+ * @author Edouard Courty <edouard.courty2@gmail.com>
+ */
+class InitializeRequestEvent
+{
+    public function __construct(
+        private readonly InitializeRequest $request,
+    ) {
+    }
+
+    public function getRequest(): InitializeRequest
+    {
+        return $this->request;
+    }
+}

src/Event/PingRequestEvent.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Event;
+
+use Mcp\Schema\Request\PingRequest;
+
+/**
+ * @author Edouard Courty <edouard.courty2@gmail.com>
+ */
+class PingRequestEvent
+{
+    public function __construct(
+        private readonly PingRequest $request,
+    ) {
+    }
+
+    public function getRequest(): PingRequest
+    {
+        return $this->request;
+    }
+}

src/Event/Prompt/AbstractGetPromptEvent.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Event\Prompt;
+
+use Mcp\Schema\Request\GetPromptRequest;
+
+/**
+ * @author Edouard Courty <edouard.courty2@gmail.com>
+ */
+abstract class AbstractGetPromptEvent
+{
+    public function __construct(
+        private readonly GetPromptRequest $request,
+    ) {
+    }
+
+    public function getRequest(): GetPromptRequest
+    {
+        return $this->request;
+    }
+}

src/Event/Prompt/GetPromptExceptionEvent.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Event\Prompt;
+
+use Mcp\Schema\Request\GetPromptRequest;
+
+/**
+ * @author Edouard Courty <edouard.courty2@gmail.com>
+ */
+class GetPromptExceptionEvent extends AbstractGetPromptEvent
+{
+    public function __construct(
+        GetPromptRequest $request,
+        private readonly \Throwable $throwable,
+    ) {
+        parent::__construct($request);
+    }
+
+    public function getThrowable(): \Throwable
+    {
+        return $this->throwable;
+    }
+}

src/Event/Prompt/GetPromptRequestEvent.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Event\Prompt;
+
+/**
+ * @author Edouard Courty <edouard.courty2@gmail.com>
+ */
+class GetPromptRequestEvent extends AbstractGetPromptEvent
+{
+}

src/Event/Prompt/GetPromptResultEvent.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Event\Prompt;
+
+use Mcp\Schema\Request\GetPromptRequest;
+use Mcp\Schema\Result\GetPromptResult;
+
+/**
+ * @author Edouard Courty <edouard.courty2@gmail.com>
+ */
+class GetPromptResultEvent extends AbstractGetPromptEvent
+{
+    public function __construct(
+        GetPromptRequest $request,
+        private readonly GetPromptResult $result,
+    ) {
+        parent::__construct($request);
+    }
+
+    public function getResult(): GetPromptResult
+    {
+        return $this->result;
+    }
+}

src/Event/Resource/AbstractReadResourceEvent.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Event\Resource;
+
+use Mcp\Schema\Request\ReadResourceRequest;
+
+/**
+ * @author Edouard Courty <edouard.courty2@gmail.com>
+ */
+abstract class AbstractReadResourceEvent
+{
+    public function __construct(
+        private readonly ReadResourceRequest $request,
+    ) {
+    }
+
+    public function getRequest(): ReadResourceRequest
+    {
+        return $this->request;
+    }
+}

src/Event/Resource/ReadResourceExceptionEvent.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Event\Resource;
+
+use Mcp\Schema\Request\ReadResourceRequest;
+
+/**
+ * @author Edouard Courty <edouard.courty2@gmail.com>
+ */
+class ReadResourceExceptionEvent extends AbstractReadResourceEvent
+{
+    public function __construct(
+        ReadResourceRequest $request,
+        private readonly \Throwable $throwable,
+    ) {
+        parent::__construct($request);
+    }
+
+    public function getThrowable(): \Throwable
+    {
+        return $this->throwable;
+    }
+}