MCP Events

Standardized event classes for MCP (Model Context Protocol) tool execution lifecycle in PHP.

Zero dependencies - pure PHP 8.1+, framework-agnostic.

Installation

composer require code-wheel/mcp-events

Usage

These events follow a standard structure for MCP tool execution observability. Use them with any PSR-14 compatible event dispatcher.

Dispatching Events

use CodeWheel\McpEvents\ToolExecutionStartedEvent;
use CodeWheel\McpEvents\ToolExecutionSucceededEvent;
use CodeWheel\McpEvents\ToolExecutionFailedEvent;

// When tool execution starts
$startEvent = new ToolExecutionStartedEvent(
    toolName: 'create_user',
    pluginId: 'my_module.create_user',
    arguments: ['username' => 'john', 'email' => '[redacted]'],
    requestId: 'req-123',
    timestamp: microtime(true),
);
$dispatcher->dispatch($startEvent);

// On success
$successEvent = new ToolExecutionSucceededEvent(
    toolName: 'create_user',
    pluginId: 'my_module.create_user',
    arguments: ['username' => 'john', 'email' => '[redacted]'],
    result: $callToolResult,
    durationMs: 45.2,
    requestId: 'req-123',
);
$dispatcher->dispatch($successEvent);

// On failure
$failEvent = new ToolExecutionFailedEvent(
    toolName: 'create_user',
    pluginId: 'my_module.create_user',
    arguments: ['username' => 'john'],
    reason: ToolExecutionFailedEvent::REASON_VALIDATION,
    result: null,
    exception: $validationException,
    durationMs: 12.5,
    requestId: 'req-123',
);
$dispatcher->dispatch($failEvent);

Listening to Events

use CodeWheel\McpEvents\ToolExecutionStartedEvent;
use CodeWheel\McpEvents\ToolExecutionSucceededEvent;
use CodeWheel\McpEvents\ToolExecutionFailedEvent;

class ToolExecutionLogger {

    public function onStart(ToolExecutionStartedEvent $event): void {
        $this->logger->info('Tool started', [
            'tool' => $event->toolName,
            'request_id' => $event->requestId,
        ]);
    }

    public function onSuccess(ToolExecutionSucceededEvent $event): void {
        $this->metrics->histogram('tool_duration_ms', $event->durationMs, [
            'tool' => $event->toolName,
        ]);
    }

    public function onFailure(ToolExecutionFailedEvent $event): void {
        $context = [
            'tool' => $event->toolName,
            'reason' => $event->reason,
            'duration_ms' => $event->durationMs,
        ];

        if ($event->hasException()) {
            $context['exception'] = $event->exception->getMessage();
        }

        if ($event->isPolicyFailure()) {
            $this->logger->warning('Tool blocked by policy', $context);
        } else {
            $this->logger->error('Tool execution failed', $context);
        }
    }
}

Events

ToolExecutionStartedEvent

Dispatched when tool execution begins.

| Property | Type | Description | |----------|------|-------------| | toolName | string | MCP tool name | | pluginId | string | Implementation plugin ID | | arguments | array | Sanitized tool arguments | | requestId | string|int|null | MCP request correlation ID | | timestamp | float | Start timestamp (microtime) |

ToolExecutionSucceededEvent

Dispatched when tool execution completes successfully.

| Property | Type | Description | |----------|------|-------------| | toolName | string | MCP tool name | | pluginId | string | Implementation plugin ID | | arguments | array | Sanitized tool arguments | | result | object | Result object (e.g., CallToolResult from mcp/sdk) | | durationMs | float | Execution duration in ms | | requestId | string|int|null | MCP request correlation ID |

ToolExecutionFailedEvent

Dispatched when tool execution fails.

| Property | Type | Description | |----------|------|-------------| | toolName | string | MCP tool name | | pluginId | string | Implementation plugin ID | | arguments | array | Sanitized tool arguments | | reason | string | Failure reason constant | | result | object|null | Result object if available | | exception | Throwable|null | Exception if thrown | | durationMs | float | Duration until failure in ms | | requestId | string|int|null | MCP request correlation ID |

Failure Reasons

| Constant | Description | |----------|-------------| | REASON_VALIDATION | Input validation failed | | REASON_ACCESS_DENIED | Permission denied | | REASON_INSTANTIATION | Failed to create tool instance | | REASON_INVALID_TOOL | Tool not found or invalid | | REASON_RESULT | Result processing failed | | REASON_EXECUTION | General execution failure | | REASON_POLICY | Blocked by policy | | REASON_POLICY_APPROVAL | Requires approval | | REASON_POLICY_BUDGET | Budget exceeded | | REASON_POLICY_DRY_RUN | Dry run mode | | REASON_POLICY_SCOPE | Insufficient scope |

Helper Methods

// Check if failure was policy-related
if ($event->isPolicyFailure()) {
    // Handle policy block differently
}

// Check if exception was thrown
if ($event->hasException()) {
    $exception = $event->exception;
}

// Get all valid failure reasons
$allReasons = ToolExecutionFailedEvent::allReasons();
// ['REASON_VALIDATION' => 'validation_failed', ...]

// Validate a reason string
if (ToolExecutionFailedEvent::isValidReason($reason)) {
    // Valid reason
}

JSON Serialization

All events implement JsonSerializable for easy logging:

// Direct serialization
$json = json_encode($event);

// Or get the array
$data = $event->jsonSerialize();

// Example output for ToolExecutionFailedEvent:
// {
//   "event": "tool_execution_failed",
//   "tool_name": "create_user",
//   "plugin_id": "my_module.create_user",
//   "reason": "validation_failed",
//   "duration_ms": 12.5,
//   "request_id": "req-123",
//   "is_policy_failure": false,
//   "has_exception": true,
//   "exception_class": "InvalidArgumentException",
//   "exception_message": "Email is required"
// }

Note: The result object is intentionally excluded from serialization as it may contain sensitive data.

Framework Integration

This package has zero dependencies. When using with mcp/sdk, the result object will be a CallToolResult:

// With mcp/sdk (optional)
use Mcp\Schema\Result\CallToolResult;

$event = new ToolExecutionSucceededEvent(
    toolName: 'my_tool',
    pluginId: 'my_module.my_tool',
    arguments: [],
    result: $callToolResult, // CallToolResult from mcp/sdk
    durationMs: 10.5,
    requestId: null,
);

// Access result properties
$structured = $event->result->structuredContent;

License

MIT