zip-ai / lib / php-mcp-schema / src / Server / Resources / DTO / Resource.php

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

272 lines 7.4 KB

Raw Download Zip

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