README

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

code-wheel / mcp-events

Maintainers

Details