zip-ai / lib / mcp-adapter / includes / Domain / Contracts / McpComponentInterface.php

McpComponentInterface.php in ZIP AI – AI Website Builder & AI Agent (Beta) 0.0.8, at lib/mcp-adapter/includes/Domain/Contracts/McpComponentInterface.php

94 lines 2.5 KB

Raw Download Zip

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