zip-ai / lib / mcp-adapter / includes / Domain / Utils / ContentBlockHelper.php

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

232 lines 7.6 KB

Raw Download Zip

1	<?php
2	/**
3	* ContentBlockHelper - Factory for creating MCP content block DTOs.
4	*
5	* This helper provides convenience methods for constructing typed content block DTOs
6	* from the php-mcp-schema library. It simplifies the creation of TextContent,
7	* ImageContent, AudioContent, and EmbeddedResource instances.
8	*
9	* @package WP\MCP\Domain\Utils
10	*/
11
12	declare( strict_types=1 );
13
14	namespace WP\MCP\Domain\Utils;
15
16	use WP\McpSchema\Common\Content\DTO\AudioContent;
17	use WP\McpSchema\Common\Content\DTO\ImageContent;
18	use WP\McpSchema\Common\Content\DTO\TextContent;
19	use WP\McpSchema\Common\Protocol\DTO\Annotations;
20	use WP\McpSchema\Common\Protocol\DTO\BlobResourceContents;
21	use WP\McpSchema\Common\Protocol\DTO\EmbeddedResource;
22	use WP\McpSchema\Common\Protocol\DTO\TextResourceContents;
23	use WP\McpSchema\Common\Protocol\Union\ContentBlockInterface;
24
25	/**
26	* Helper class for creating MCP content block DTOs.
27	*
28	* Provides static factory methods to create typed content blocks that implement
29	* ContentBlockInterface. These DTOs are used in tool call results, prompt messages,
30	* and resource contents throughout the MCP protocol.
31	*
32	* @since 0.5.0
33	*/
34	final class ContentBlockHelper {
35
36	/**
37	* Creates an ImageContent DTO.
38	*
39	* @param string $data Base64-encoded image data.
40	* @param string $mime_type The MIME type of the image (e.g., 'image/png').
41	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations Optional annotations for the client.
42	* @param array\|null $_meta Optional metadata.
43	*
44	* @return \WP\McpSchema\Common\Content\DTO\ImageContent The created ImageContent DTO.
45	*/
46	public static function image( string $data, string $mime_type, ?Annotations $annotations = null, ?array $_meta = null ): ImageContent {
47	return ImageContent::fromArray(
48	array(
49	'type' => ImageContent::TYPE,
50	'data' => $data,
51	'mimeType' => $mime_type,
52	'annotations' => $annotations,
53	'_meta' => $_meta,
54	)
55	);
56	}
57
58	/**
59	* Creates an AudioContent DTO.
60	*
61	* @param string $data Base64-encoded audio data.
62	* @param string $mime_type The MIME type of the audio (e.g., 'audio/mp3').
63	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations Optional annotations for the client.
64	* @param array\|null $_meta Optional metadata.
65	*
66	* @return \WP\McpSchema\Common\Content\DTO\AudioContent The created AudioContent DTO.
67	*/
68	public static function audio( string $data, string $mime_type, ?Annotations $annotations = null, ?array $_meta = null ): AudioContent {
69	return AudioContent::fromArray(
70	array(
71	'type' => AudioContent::TYPE,
72	'data' => $data,
73	'mimeType' => $mime_type,
74	'annotations' => $annotations,
75	'_meta' => $_meta,
76	)
77	);
78	}
79
80	/**
81	* Creates an EmbeddedResource DTO with TextResourceContents.
82	*
83	* Use this for embedding text-based resources (files, documents, etc.) in content.
84	*
85	* @param string $uri The URI of the resource.
86	* @param string $text The text content of the resource.
87	* @param string\|null $mime_type Optional MIME type of the resource.
88	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations Optional annotations for the client.
89	* @param array\|null $_meta Optional metadata.
90	*
91	* @return \WP\McpSchema\Common\Protocol\DTO\EmbeddedResource The created EmbeddedResource DTO.
92	*/
93	public static function embedded_text_resource(
94	string $uri,
95	string $text,
96	?string $mime_type = null,
97	?Annotations $annotations = null,
98	?array $_meta = null
99	): EmbeddedResource {
100	$resource = TextResourceContents::fromArray(
101	array(
102	'uri' => $uri,
103	'text' => $text,
104	'mimeType' => $mime_type,
105	)
106	);
107
108	return EmbeddedResource::fromArray(
109	array(
110	'type' => EmbeddedResource::TYPE,
111	'resource' => $resource,
112	'annotations' => $annotations,
113	'_meta' => $_meta,
114	)
115	);
116	}
117
118	/**
119	* Creates an EmbeddedResource DTO with BlobResourceContents.
120	*
121	* Use this for embedding binary resources (images, PDFs, etc.) in content.
122	*
123	* @param string $uri The URI of the resource.
124	* @param string $blob Base64-encoded binary data.
125	* @param string\|null $mime_type Optional MIME type of the resource.
126	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations Optional annotations for the client.
127	* @param array\|null $_meta Optional metadata.
128	*
129	* @return \WP\McpSchema\Common\Protocol\DTO\EmbeddedResource The created EmbeddedResource DTO.
130	*/
131	public static function embedded_blob_resource(
132	string $uri,
133	string $blob,
134	?string $mime_type = null,
135	?Annotations $annotations = null,
136	?array $_meta = null
137	): EmbeddedResource {
138	$resource = BlobResourceContents::fromArray(
139	array(
140	'uri' => $uri,
141	'blob' => $blob,
142	'mimeType' => $mime_type,
143	)
144	);
145
146	return EmbeddedResource::fromArray(
147	array(
148	'type' => EmbeddedResource::TYPE,
149	'resource' => $resource,
150	'annotations' => $annotations,
151	'_meta' => $_meta,
152	)
153	);
154	}
155
156	/**
157	* Creates a TextContent DTO for error messages.
158	*
159	* Convenience method for creating text content specifically for error responses.
160	* This is semantically equivalent to text() but makes the intent clearer in code.
161	*
162	* @param string $message The error message.
163	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations Optional annotations for the client.
164	* @param array\|null $_meta Optional metadata.
165	*
166	* @return \WP\McpSchema\Common\Content\DTO\TextContent The created TextContent DTO.
167	*/
168	public static function error_text( string $message, ?Annotations $annotations = null, ?array $_meta = null ): TextContent {
169	return self::text( $message, $annotations, $_meta );
170	}
171
172	/**
173	* Creates a TextContent DTO.
174	*
175	* @param string $text The text content.
176	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations Optional annotations for the client.
177	* @param array\|null $_meta Optional metadata.
178	*
179	* @return \WP\McpSchema\Common\Content\DTO\TextContent The created TextContent DTO.
180	*/
181	public static function text( string $text, ?Annotations $annotations = null, ?array $_meta = null ): TextContent {
182	return TextContent::fromArray(
183	array(
184	'type' => TextContent::TYPE,
185	'text' => $text,
186	'annotations' => $annotations,
187	'_meta' => $_meta,
188	)
189	);
190	}
191
192	/**
193	* Creates a TextContent DTO with JSON-encoded data.
194	*
195	* Convenience method for creating text content from structured data.
196	* The data is encoded as JSON and wrapped in a TextContent DTO.
197	*
198	* @param mixed $data The data to JSON-encode.
199	* @param int $flags JSON encoding flags (default: 0).
200	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations Optional annotations for the client.
201	* @param array\|null $_meta Optional metadata.
202	*
203	* @return \WP\McpSchema\Common\Content\DTO\TextContent The created TextContent DTO.
204	*/
205	public static function json_text( $data, int $flags = 0, ?Annotations $annotations = null, ?array $_meta = null ): TextContent {
206	$json = wp_json_encode( $data, $flags );
207	if ( false === $json ) {
208	$json = '{}';
209	}
210
211	return self::text( $json, $annotations, $_meta );
212	}
213
214	/**
215	* Converts an array of ContentBlockInterface DTOs to their array representations.
216	*
217	* Use this at the serialization boundary when preparing content blocks for JSON output.
218	*
219	* @param \WP\McpSchema\Common\Protocol\Union\ContentBlockInterface[] $blocks Array of content block DTOs.
220	*
221	* @return array[] Array of content block arrays.
222	*/
223	public static function to_array_list( array $blocks ): array {
224	return array_map(
225	static function ( ContentBlockInterface $block ): array {
226	return $block->toArray();
227	},
228	$blocks
229	);
230	}
231	}
232