feat(server): add server lifecycle events

[EdouardCourty]

Add Server Lifecycle Events

This PR introduces a comprehensive PSR-14 compatible event system for the MCP PHP SDK, allowing developers to hook into the server's lifecycle for tools, prompts, resources, ping, and initialize operations.

This will fix #169

Motivation and Context

Currently, there's no standardized way to observe or react to server operations like tool calls, prompt retrievals, or resource reads.

How Has This Been Tested?

• Unit tests added for all new event classes
• Tests for event dispatching in all handlers (CallToolHandler, GetPromptHandler, ReadResourceHandler, InitializeHandler, PingHandler)
• Tests cover request events, result events, and exception events
• All existing tests continue to pass

Breaking Changes

None. This is a purely additive change. The event dispatcher is optional - servers without an event dispatcher configured will continue to work as before.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

New Event Classes

Server Events:

• InitializeRequestEvent - Fired when client sends initialize request
• PingRequestEvent - Fired when client sends ping request

Tool Events:

• CallToolRequestEvent - Before tool execution
• CallToolResultEvent - After successful execution
• CallToolExceptionEvent - On uncaught exception

Prompt Events:

• GetPromptRequestEvent - Before prompt execution
• GetPromptResultEvent - After successful execution
• GetPromptExceptionEvent - On uncaught exception

Resource Events:

• ReadResourceRequestEvent - Before resource read
• ReadResourceResultEvent - After successful read
• ReadResourceExceptionEvent - On uncaught exception

Full documentation available in docs/events.md.

[chr-hertel]

Nice one, thanks - before going into detailed review we should verify if we want that granularity with the events or if it should rather be one level higher like RequestEvent, NotificationEvent and ResponseEvent and ErrorEvent
that would centralize the dispatching a bit more.

you could still check for the method there, like

public function onRequestEvent(RequestEvent $event): void
{
    if ('tools/list' !== $event->getMethod()) {
        return;
    }
}

or similar.

not super sure about it myself, but i just think of change scenarios and number of events - cc @CodeWithKyrian @Nyholm

[chr-hertel]

Hey @EdouardCourty, had a brief alignment with @CodeWithKyrian and we would like to go with more generic events - being a more robust solution with changes over time adding more handlers/notification - or with users adding their own.

So it would be

• RequestEvent
• NotificationEvent
• ResponseEvent
• ErrorEvent

dispatched on Protocol level i assume

do you see that you could solve your use case with that as well?

[EdouardCourty]

Hey @EdouardCourty, had a brief alignment with @CodeWithKyrian and we would like to go with more generic events - being a more robust solution with changes over time adding more handlers/notification - or with users adding their own.

So it would be

• RequestEvent

• NotificationEvent

• ResponseEvent

• ErrorEvent

dispatched on Protocol level i assume

do you see that you could solve your use case with that as well?

Alright, this works!
What do you mean by "Protocol level" tho?

[chr-hertel]

That you presumably would dispatch the events rather in the Protocol class than the RequestHandlerInterface implementations

[Nyholm]

Thank you.

Currently, there's no standardized way to observe or react to server operations like tool calls, prompt retrievals, or resource reads.

Can you please elaborate on why? Do you want to be able to modify the request before it is given to the tool? Or do you want to change the result of the tool?

Ie, What do you want to achieve after this PR is merged?

[EdouardCourty]

Thank you.

Currently, there's no standardized way to observe or react to server operations like tool calls, prompt retrievals, or resource reads.

Can you please elaborate on why? Do you want to be able to modify the request before it is given to the tool? Or do you want to change the result of the tool?

Ie, What do you want to achieve after this PR is merged?

Observing and reacting.

I want to be able to trigger specific logic on each request (like storing these in an external database, or log them in a specific way) or response.

For your other question, I think it could be useful to be able to modify the requests and responses before and after they are processed, leaving the choice to the developers that implement this SDK to use it or not.

[Nyholm]

I like this PR.

I would like you to:

1. Remove the abstract classes
2. Make the event classes final
3. Remove "use once" variables
4. Follow up on this comment: #175 (comment)

If you would like help, let me know.

[Nyholm]

Can you skip the variable here and for other similar places?

Suggested change

	$toolCallRequestEvent = new CallToolRequestEvent($request);
	$this->eventDispatcher?->dispatch($toolCallRequestEvent);
	$this->eventDispatcher?->dispatch($new CallToolRequestEvent($request));

[Nyholm]

Please remove this class

[Nyholm]

Please remove this class

[Nyholm]

Please remove this class

[EdouardCourty]

Hey @EdouardCourty, had a brief alignment with @CodeWithKyrian and we would like to go with more generic events - being a more robust solution with changes over time adding more handlers/notification - or with users adding their own.

So it would be

• RequestEvent
• NotificationEvent
• ResponseEvent
• ErrorEvent

dispatched on Protocol level i assume

do you see that you could solve your use case with that as well?

Hi again (following up after @Nyholm's comment.
I agree to this change, but I'd like a clear confirmation of what you guys want.

The RequestEvent / NotificationEvent / etc VS the more precise CallToolEventRequest / CallToolEventException approach means less different event types to handle, which is a great thing.

Also, should the request or response payload be modifiable from the event? Or should the event be read-only ?

Just give me a confirmation and I will do the changes.

[chr-hertel]

Hey @EdouardCourty, I don't think @Nyholm's comment and what I wrote before are in conflict - take it as guidance while tackling the change to less specific events - that's the direction 👍

[EdouardCourty]

Hey @EdouardCourty, I don't think @Nyholm's comment and what I wrote before are in conflict - take it as guidance while tackling the change to less specific events - that's the direction 👍

Hi, I've updated the PR. I'll wait for your feedback!