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

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

205 lines 5.0 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\AbstractDataTransferObject;
8	use WP\McpSchema\Common\Traits\ValidatesRequiredFields;
9
10	/**
11	* Additional properties describing a Tool to clients.
12	*
13	* NOTE: all properties in ToolAnnotations are hints.
14	* They are not guaranteed to provide a faithful description of
15	* tool behavior (including descriptive properties like `title`).
16	*
17	* Clients should never make tool use decisions based on ToolAnnotations
18	* received from untrusted servers.
19	*
20	* @since 2025-03-26
21	*
22	* @mcp-domain Server
23	* @mcp-subdomain Tools
24	* @mcp-version 2025-11-25
25	*/
26	class ToolAnnotations extends AbstractDataTransferObject
27	{
28	use ValidatesRequiredFields;
29
30	/**
31	* A human-readable title for the tool.
32	*
33	* @since 2025-03-26
34	*
35	* @var string\|null
36	*/
37	protected ?string $title;
38
39	/**
40	* If true, the tool does not modify its environment.
41	*
42	* Default: false
43	*
44	* @since 2025-03-26
45	*
46	* @var bool\|null
47	*/
48	protected ?bool $readOnlyHint;
49
50	/**
51	* If true, the tool may perform destructive updates to its environment.
52	* If false, the tool performs only additive updates.
53	*
54	* (This property is meaningful only when `readOnlyHint == false`)
55	*
56	* Default: true
57	*
58	* @since 2025-03-26
59	*
60	* @var bool\|null
61	*/
62	protected ?bool $destructiveHint;
63
64	/**
65	* If true, calling the tool repeatedly with the same arguments
66	* will have no additional effect on its environment.
67	*
68	* (This property is meaningful only when `readOnlyHint == false`)
69	*
70	* Default: false
71	*
72	* @since 2025-03-26
73	*
74	* @var bool\|null
75	*/
76	protected ?bool $idempotentHint;
77
78	/**
79	* If true, this tool may interact with an "open world" of external
80	* entities. If false, the tool's domain of interaction is closed.
81	* For example, the world of a web search tool is open, whereas that
82	* of a memory tool is not.
83	*
84	* Default: true
85	*
86	* @since 2025-03-26
87	*
88	* @var bool\|null
89	*/
90	protected ?bool $openWorldHint;
91
92	/**
93	* @param string\|null $title @since 2025-03-26
94	* @param bool\|null $readOnlyHint @since 2025-03-26
95	* @param bool\|null $destructiveHint @since 2025-03-26
96	* @param bool\|null $idempotentHint @since 2025-03-26
97	* @param bool\|null $openWorldHint @since 2025-03-26
98	*/
99	public function __construct(
100	?string $title = null,
101	?bool $readOnlyHint = null,
102	?bool $destructiveHint = null,
103	?bool $idempotentHint = null,
104	?bool $openWorldHint = null
105	) {
106	$this->title = $title;
107	$this->readOnlyHint = $readOnlyHint;
108	$this->destructiveHint = $destructiveHint;
109	$this->idempotentHint = $idempotentHint;
110	$this->openWorldHint = $openWorldHint;
111	}
112
113	/**
114	* Creates an instance from an array.
115	*
116	* @param array{
117	* title?: string\|null,
118	* readOnlyHint?: bool\|null,
119	* destructiveHint?: bool\|null,
120	* idempotentHint?: bool\|null,
121	* openWorldHint?: bool\|null
122	* } $data
123	* @phpstan-param array<string, mixed> $data
124	* @return self
125	*/
126	public static function fromArray(array $data): self
127	{
128	return new self(
129	self::asStringOrNull($data['title'] ?? null),
130	self::asBoolOrNull($data['readOnlyHint'] ?? null),
131	self::asBoolOrNull($data['destructiveHint'] ?? null),
132	self::asBoolOrNull($data['idempotentHint'] ?? null),
133	self::asBoolOrNull($data['openWorldHint'] ?? null)
134	);
135	}
136
137	/**
138	* Converts the instance to an array.
139	*
140	* @return array<string, mixed>
141	*/
142	public function toArray(): array
143	{
144	$result = [];
145
146	if ($this->title !== null) {
147	$result['title'] = $this->title;
148	}
149	if ($this->readOnlyHint !== null) {
150	$result['readOnlyHint'] = $this->readOnlyHint;
151	}
152	if ($this->destructiveHint !== null) {
153	$result['destructiveHint'] = $this->destructiveHint;
154	}
155	if ($this->idempotentHint !== null) {
156	$result['idempotentHint'] = $this->idempotentHint;
157	}
158	if ($this->openWorldHint !== null) {
159	$result['openWorldHint'] = $this->openWorldHint;
160	}
161
162	return $result;
163	}
164
165	/**
166	* @return string\|null
167	*/
168	public function getTitle(): ?string
169	{
170	return $this->title;
171	}
172
173	/**
174	* @return bool\|null
175	*/
176	public function getReadOnlyHint(): ?bool
177	{
178	return $this->readOnlyHint;
179	}
180
181	/**
182	* @return bool\|null
183	*/
184	public function getDestructiveHint(): ?bool
185	{
186	return $this->destructiveHint;
187	}
188
189	/**
190	* @return bool\|null
191	*/
192	public function getIdempotentHint(): ?bool
193	{
194	return $this->idempotentHint;
195	}
196
197	/**
198	* @return bool\|null
199	*/
200	public function getOpenWorldHint(): ?bool
201	{
202	return $this->openWorldHint;
203	}
204	}
205