commercebird
/
vendor
/
wordpress
/
mcp-adapter
/
includes
/
Domain
/
Contracts
/
McpComponentInterface.php
McpComponentInterface.php
94 lines
| 1 | <?php |
| 2 | /** |
| 3 | * Contract for MCP component classes (tools, resources, prompts). |
| 4 | * |
| 5 | * @package McpAdapter |
| 6 | */ |
| 7 | |
| 8 | declare( strict_types=1 ); |
| 9 | |
| 10 | namespace WP\MCP\Domain\Contracts; |
| 11 | |
| 12 | use WP\McpSchema\Common\AbstractDataTransferObject; |
| 13 | |
| 14 | /** |
| 15 | * Interface McpComponentInterface. |
| 16 | * |
| 17 | * Classes implementing this interface encapsulate: |
| 18 | * - a clean protocol DTO (Tool/Resource/Prompt) that is safe to expose to MCP clients, and |
| 19 | * - MCP Adapter internal metadata and execution wiring (ability-backed OR direct-callable). |
| 20 | * |
| 21 | * This keeps protocol DTOs free of internal adapter fields, while still |
| 22 | * providing a uniform execution and permission-check surface for handlers. |
| 23 | * |
| 24 | * @internal |
| 25 | * |
| 26 | * @since 0.5.0 |
| 27 | */ |
| 28 | interface McpComponentInterface { |
| 29 | |
| 30 | /** |
| 31 | * Get the clean protocol DTO for MCP responses. |
| 32 | * |
| 33 | * This DTO is used only for protocol serialization and MUST NOT include |
| 34 | * internal adapter metadata or execution wiring. |
| 35 | * |
| 36 | * @return \WP\McpSchema\Common\AbstractDataTransferObject Protocol-only DTO. |
| 37 | * @since 0.5.0 |
| 38 | * |
| 39 | */ |
| 40 | public function get_protocol_dto(): AbstractDataTransferObject; |
| 41 | |
| 42 | /** |
| 43 | * Execute the component using the configured strategy. |
| 44 | * |
| 45 | * Implementations MUST execute via either: |
| 46 | * - an attached WordPress ability, or |
| 47 | * - a direct callable handler (for non-ability registrations). |
| 48 | * |
| 49 | * @param mixed $arguments Component arguments (typically an associative array). |
| 50 | * |
| 51 | * @return mixed Execution result. |
| 52 | * @since 0.5.0 |
| 53 | * |
| 54 | */ |
| 55 | public function execute( $arguments ); |
| 56 | |
| 57 | /** |
| 58 | * Check whether execution is permitted for the current request. |
| 59 | * |
| 60 | * Implementations MUST check permissions via either: |
| 61 | * - the attached WordPress ability, or |
| 62 | * - a direct permission callback (for non-ability registrations). |
| 63 | * |
| 64 | * @param mixed $arguments Component arguments (typically an associative array). |
| 65 | * |
| 66 | * @return bool|\WP_Error True when permitted, false or WP_Error otherwise. |
| 67 | * @since 0.5.0 |
| 68 | * |
| 69 | */ |
| 70 | public function check_permission( $arguments ); |
| 71 | |
| 72 | /** |
| 73 | * Get MCP Adapter internal metadata for this component. |
| 74 | * |
| 75 | * This metadata MUST NOT be stored on protocol DTOs and MUST NOT be exposed to MCP clients. |
| 76 | * |
| 77 | * @return array<string, mixed> Internal metadata. |
| 78 | * @since 0.5.0 |
| 79 | * |
| 80 | */ |
| 81 | public function get_adapter_meta(): array; |
| 82 | |
| 83 | /** |
| 84 | * Get observability context tags for logging/metrics. |
| 85 | * |
| 86 | * This replaces legacy approaches that derived observability tags from DTO `_meta`. |
| 87 | * |
| 88 | * @return array<string, mixed> Observability tags (component_type, source, etc.). |
| 89 | * @since 0.5.0 |
| 90 | * |
| 91 | */ |
| 92 | public function get_observability_context(): array; |
| 93 | } |
| 94 |