zip-ai / lib / php-mcp-schema / src / Server / Tools / DTO / Tool.php

Tool.php in ZIP AI – AI Website Builder & AI Agent (Beta) 0.0.8, at lib/php-mcp-schema/src/Server/Tools/DTO/Tool.php

294 lines 9.2 KB

Raw Download Zip

1	<?php
2
3	declare(strict_types=1);
4
5	namespace WP\McpSchema\Server\Tools\DTO;
6
7	use WP\McpSchema\Common\Core\DTO\Icon;
8	use WP\McpSchema\Common\Protocol\DTO\BaseMetadata;
9	use WP\McpSchema\Common\Traits\ValidatesRequiredFields;
10
11	/**
12	* Definition for a tool the client can call.
13	*
14	* @since 2024-11-05
15	* @last-updated 2025-11-25 (added properties: execution, icons; modified property: annotations)
16	*
17	* @mcp-domain Server
18	* @mcp-subdomain Tools
19	* @mcp-version 2025-11-25
20	*/
21	class Tool extends BaseMetadata
22	{
23	use ValidatesRequiredFields;
24
25	/**
26	* A human-readable description of the tool.
27	*
28	* This can be used by clients to improve the LLM's understanding of available tools. It can be thought of like a "hint" to the model.
29	*
30	* @since 2024-11-05
31	*
32	* @var string\|null
33	*/
34	protected ?string $description;
35
36	/**
37	* A JSON Schema object defining the expected parameters for the tool.
38	*
39	* @since 2024-11-05
40	*
41	* @var \WP\McpSchema\Server\Tools\DTO\ToolInputSchema
42	*/
43	protected ToolInputSchema $inputSchema;
44
45	/**
46	* Execution-related properties for this tool.
47	*
48	* @since 2025-11-25
49	*
50	* @var \WP\McpSchema\Server\Tools\DTO\ToolExecution\|null
51	*/
52	protected ?ToolExecution $execution;
53
54	/**
55	* An optional JSON Schema object defining the structure of the tool's output returned in
56	* the structuredContent field of a CallToolResult.
57	*
58	* Defaults to JSON Schema 2020-12 when no explicit $schema is provided.
59	* Currently restricted to type: "object" at the root level.
60	*
61	* @since 2025-06-18
62	*
63	* @var \WP\McpSchema\Server\Tools\DTO\ToolOutputSchema\|null
64	*/
65	protected ?ToolOutputSchema $outputSchema;
66
67	/**
68	* Optional additional tool information.
69	*
70	* Display name precedence order is: title, annotations.title, then name.
71	*
72	* @since 2025-03-26
73	*
74	* @var \WP\McpSchema\Server\Tools\DTO\ToolAnnotations\|null
75	*/
76	protected ?ToolAnnotations $annotations;
77
78	/**
79	* See [General fields: `_meta`](/specification/2025-11-25/basic/index#meta) for notes on `_meta` usage.
80	*
81	* @since 2025-06-18
82	*
83	* @var array<string, mixed>\|null
84	*/
85	protected ?array $_meta;
86
87	/**
88	* Optional set of sized icons that the client can display in a user interface.
89	*
90	* Clients that support rendering icons MUST support at least the following MIME types:
91	* - `image/png` - PNG images (safe, universal compatibility)
92	* - `image/jpeg` (and `image/jpg`) - JPEG images (safe, universal compatibility)
93	*
94	* Clients that support rendering icons SHOULD also support:
95	* - `image/svg+xml` - SVG images (scalable but requires security precautions)
96	* - `image/webp` - WebP images (modern, efficient format)
97	*
98	* @since 2025-11-25
99	*
100	* @var array<\WP\McpSchema\Common\Core\DTO\Icon>\|null
101	*/
102	protected ?array $icons;
103
104	/**
105	* @param string $name @since 2024-11-05
106	* @param \WP\McpSchema\Server\Tools\DTO\ToolInputSchema $inputSchema @since 2024-11-05
107	* @param string\|null $title @since 2025-06-18
108	* @param string\|null $description @since 2024-11-05
109	* @param \WP\McpSchema\Server\Tools\DTO\ToolExecution\|null $execution @since 2025-11-25
110	* @param \WP\McpSchema\Server\Tools\DTO\ToolOutputSchema\|null $outputSchema @since 2025-06-18
111	* @param \WP\McpSchema\Server\Tools\DTO\ToolAnnotations\|null $annotations @since 2025-03-26
112	* @param array<string, mixed>\|null $_meta @since 2025-06-18
113	* @param array<\WP\McpSchema\Common\Core\DTO\Icon>\|null $icons @since 2025-11-25
114	*/
115	public function __construct(
116	string $name,
117	ToolInputSchema $inputSchema,
118	?string $title = null,
119	?string $description = null,
120	?ToolExecution $execution = null,
121	?ToolOutputSchema $outputSchema = null,
122	?ToolAnnotations $annotations = null,
123	?array $_meta = null,
124	?array $icons = null
125	) {
126	parent::__construct($name, $title);
127	$this->inputSchema = $inputSchema;
128	$this->description = $description;
129	$this->execution = $execution;
130	$this->outputSchema = $outputSchema;
131	$this->annotations = $annotations;
132	$this->_meta = $_meta;
133	$this->icons = $icons;
134	}
135
136	/**
137	* Creates an instance from an array.
138	*
139	* @param array{
140	* name: string,
141	* title?: string\|null,
142	* description?: string\|null,
143	* inputSchema: array<string, mixed>\|\WP\McpSchema\Server\Tools\DTO\ToolInputSchema,
144	* execution?: array<string, mixed>\|\WP\McpSchema\Server\Tools\DTO\ToolExecution\|null,
145	* outputSchema?: array<string, mixed>\|\WP\McpSchema\Server\Tools\DTO\ToolOutputSchema\|null,
146	* annotations?: array<string, mixed>\|\WP\McpSchema\Server\Tools\DTO\ToolAnnotations\|null,
147	* _meta?: array<string, mixed>\|null,
148	* icons?: array<array<string, mixed>\|\WP\McpSchema\Common\Core\DTO\Icon>\|null
149	* } $data
150	* @phpstan-param array<string, mixed> $data
151	* @return self
152	*/
153	public static function fromArray(array $data): self
154	{
155	self::assertRequired($data, ['name', 'inputSchema']);
156
157	/** @var \WP\McpSchema\Server\Tools\DTO\ToolInputSchema $inputSchema */
158	$inputSchema = is_array($data['inputSchema'])
159	? ToolInputSchema::fromArray(self::asArray($data['inputSchema']))
160	: $data['inputSchema'];
161
162	/** @var \WP\McpSchema\Server\Tools\DTO\ToolExecution\|null $execution */
163	$execution = isset($data['execution'])
164	? (is_array($data['execution'])
165	? ToolExecution::fromArray(self::asArray($data['execution']))
166	: $data['execution'])
167	: null;
168
169	/** @var \WP\McpSchema\Server\Tools\DTO\ToolOutputSchema\|null $outputSchema */
170	$outputSchema = isset($data['outputSchema'])
171	? (is_array($data['outputSchema'])
172	? ToolOutputSchema::fromArray(self::asArray($data['outputSchema']))
173	: $data['outputSchema'])
174	: null;
175
176	/** @var \WP\McpSchema\Server\Tools\DTO\ToolAnnotations\|null $annotations */
177	$annotations = isset($data['annotations'])
178	? (is_array($data['annotations'])
179	? ToolAnnotations::fromArray(self::asArray($data['annotations']))
180	: $data['annotations'])
181	: null;
182
183	/** @var array<\WP\McpSchema\Common\Core\DTO\Icon>\|null $icons */
184	$icons = isset($data['icons'])
185	? array_map(
186	static fn($item) => is_array($item)
187	? Icon::fromArray($item)
188	: $item,
189	self::asArray($data['icons'])
190	)
191	: null;
192
193	return new self(
194	self::asString($data['name']),
195	$inputSchema,
196	self::asStringOrNull($data['title'] ?? null),
197	self::asStringOrNull($data['description'] ?? null),
198	$execution,
199	$outputSchema,
200	$annotations,
201	self::asArrayOrNull($data['_meta'] ?? null),
202	$icons
203	);
204	}
205
206	/**
207	* Converts the instance to an array.
208	*
209	* @return array<string, mixed>
210	*/
211	public function toArray(): array
212	{
213	$result = parent::toArray();
214
215	if ($this->description !== null) {
216	$result['description'] = $this->description;
217	}
218	$result['inputSchema'] = $this->inputSchema->toArray();
219	if ($this->execution !== null) {
220	$result['execution'] = $this->execution->toArray();
221	}
222	if ($this->outputSchema !== null) {
223	$result['outputSchema'] = $this->outputSchema->toArray();
224	}
225	if ($this->annotations !== null) {
226	$result['annotations'] = $this->annotations->toArray();
227	}
228	if ($this->_meta !== null) {
229	$result['_meta'] = $this->_meta;
230	}
231	if ($this->icons !== null) {
232	$result['icons'] = array_map(static fn($item) => $item->toArray(), $this->icons);
233	}
234
235	return $result;
236	}
237
238	/**
239	* @return string\|null
240	*/
241	public function getDescription(): ?string
242	{
243	return $this->description;
244	}
245
246	/**
247	* @return \WP\McpSchema\Server\Tools\DTO\ToolInputSchema
248	*/
249	public function getInputSchema(): ToolInputSchema
250	{
251	return $this->inputSchema;
252	}
253
254	/**
255	* @return \WP\McpSchema\Server\Tools\DTO\ToolExecution\|null
256	*/
257	public function getExecution(): ?ToolExecution
258	{
259	return $this->execution;
260	}
261
262	/**
263	* @return \WP\McpSchema\Server\Tools\DTO\ToolOutputSchema\|null
264	*/
265	public function getOutputSchema(): ?ToolOutputSchema
266	{
267	return $this->outputSchema;
268	}
269
270	/**
271	* @return \WP\McpSchema\Server\Tools\DTO\ToolAnnotations\|null
272	*/
273	public function getAnnotations(): ?ToolAnnotations
274	{
275	return $this->annotations;
276	}
277
278	/**
279	* @return array<string, mixed>\|null
280	*/
281	public function get_meta(): ?array
282	{
283	return $this->_meta;
284	}
285
286	/**
287	* @return array<\WP\McpSchema\Common\Core\DTO\Icon>\|null
288	*/
289	public function getIcons(): ?array
290	{
291	return $this->icons;
292	}
293	}
294