convertkit / vendor / wordpress / mcp-adapter / includes / Domain / Utils / ContentBlockHelper.php

ContentBlockHelper.php in Kit (formerly ConvertKit) – Email Newsletter, Email Marketing, Membership, Subscribers and Landing Pages 3.4.3, at vendor/wordpress/mcp-adapter/includes/Domain/Utils/ContentBlockHelper.php

255 lines 9.1 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	* Every `_meta` argument passes through {@see McpValidator::normalize_meta()}, so a
33	* PHP list is omitted instead of being serialized where MCP declares a JSON object.
34	*
35	* @since 0.5.0
36	*/
37	final class ContentBlockHelper {
38
39	/**
40	* Creates an ImageContent DTO.
41	*
42	* @param string $data Base64-encoded image data.
43	* @param string $mime_type The MIME type of the image (e.g., 'image/png').
44	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations Optional annotations for the client.
45	* @param array\|null $_meta Optional metadata for the content block.
46	*
47	* @return \WP\McpSchema\Common\Content\DTO\ImageContent The created ImageContent DTO.
48	*/
49	public static function image( string $data, string $mime_type, ?Annotations $annotations = null, ?array $_meta = null ): ImageContent {
50	return ImageContent::fromArray(
51	array(
52	'type' => ImageContent::TYPE,
53	'data' => $data,
54	'mimeType' => $mime_type,
55	'annotations' => $annotations,
56	'_meta' => McpValidator::normalize_meta( $_meta ),
57	)
58	);
59	}
60
61	/**
62	* Creates an AudioContent DTO.
63	*
64	* @param string $data Base64-encoded audio data.
65	* @param string $mime_type The MIME type of the audio (e.g., 'audio/mp3').
66	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations Optional annotations for the client.
67	* @param array\|null $_meta Optional metadata for the content block.
68	*
69	* @return \WP\McpSchema\Common\Content\DTO\AudioContent The created AudioContent DTO.
70	*/
71	public static function audio( string $data, string $mime_type, ?Annotations $annotations = null, ?array $_meta = null ): AudioContent {
72	return AudioContent::fromArray(
73	array(
74	'type' => AudioContent::TYPE,
75	'data' => $data,
76	'mimeType' => $mime_type,
77	'annotations' => $annotations,
78	'_meta' => McpValidator::normalize_meta( $_meta ),
79	)
80	);
81	}
82
83	/**
84	* Creates an EmbeddedResource DTO with TextResourceContents.
85	*
86	* Use this for embedding text-based resources (files, documents, etc.) in content.
87	*
88	* The DTO tree has two levels that each carry their own `_meta`: the content
89	* block wrapper and the resource contents nested inside it. `$_meta` sets the
90	* wrapper's; `$resource_meta` sets the contents'. They are distinct fields in
91	* the spec and are not interchangeable.
92	*
93	* @since 0.6.0 Added the optional $resource_meta parameter.
94	*
95	* @param string $uri The URI of the resource.
96	* @param string $text The text content of the resource.
97	* @param string\|null $mime_type Optional MIME type of the resource.
98	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations Optional annotations for the client.
99	* @param array\|null $_meta Optional metadata for the content block.
100	* @param array\|null $resource_meta Optional metadata for the nested resource contents.
101	*
102	* @return \WP\McpSchema\Common\Protocol\DTO\EmbeddedResource The created EmbeddedResource DTO.
103	*/
104	public static function embedded_text_resource(
105	string $uri,
106	string $text,
107	?string $mime_type = null,
108	?Annotations $annotations = null,
109	?array $_meta = null,
110	?array $resource_meta = null
111	): EmbeddedResource {
112	$resource = TextResourceContents::fromArray(
113	array(
114	'uri' => $uri,
115	'text' => $text,
116	'mimeType' => $mime_type,
117	'_meta' => McpValidator::normalize_meta( $resource_meta ),
118	)
119	);
120
121	return EmbeddedResource::fromArray(
122	array(
123	'type' => EmbeddedResource::TYPE,
124	'resource' => $resource,
125	'annotations' => $annotations,
126	'_meta' => McpValidator::normalize_meta( $_meta ),
127	)
128	);
129	}
130
131	/**
132	* Creates an EmbeddedResource DTO with BlobResourceContents.
133	*
134	* Use this for embedding binary resources (images, PDFs, etc.) in content.
135	*
136	* The DTO tree has two levels that each carry their own `_meta`: the content
137	* block wrapper and the resource contents nested inside it. `$_meta` sets the
138	* wrapper's; `$resource_meta` sets the contents'. They are distinct fields in
139	* the spec and are not interchangeable.
140	*
141	* @since 0.6.0 Added the optional $resource_meta parameter.
142	*
143	* @param string $uri The URI of the resource.
144	* @param string $blob Base64-encoded binary data.
145	* @param string\|null $mime_type Optional MIME type of the resource.
146	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations Optional annotations for the client.
147	* @param array\|null $_meta Optional metadata for the content block.
148	* @param array\|null $resource_meta Optional metadata for the nested resource contents.
149	*
150	* @return \WP\McpSchema\Common\Protocol\DTO\EmbeddedResource The created EmbeddedResource DTO.
151	*/
152	public static function embedded_blob_resource(
153	string $uri,
154	string $blob,
155	?string $mime_type = null,
156	?Annotations $annotations = null,
157	?array $_meta = null,
158	?array $resource_meta = null
159	): EmbeddedResource {
160	$resource = BlobResourceContents::fromArray(
161	array(
162	'uri' => $uri,
163	'blob' => $blob,
164	'mimeType' => $mime_type,
165	'_meta' => McpValidator::normalize_meta( $resource_meta ),
166	)
167	);
168
169	return EmbeddedResource::fromArray(
170	array(
171	'type' => EmbeddedResource::TYPE,
172	'resource' => $resource,
173	'annotations' => $annotations,
174	'_meta' => McpValidator::normalize_meta( $_meta ),
175	)
176	);
177	}
178
179	/**
180	* Creates a TextContent DTO for error messages.
181	*
182	* Convenience method for creating text content specifically for error responses.
183	* This is semantically equivalent to text() but makes the intent clearer in code.
184	*
185	* @param string $message The error message.
186	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations Optional annotations for the client.
187	* @param array\|null $_meta Optional metadata for the content block.
188	*
189	* @return \WP\McpSchema\Common\Content\DTO\TextContent The created TextContent DTO.
190	*/
191	public static function error_text( string $message, ?Annotations $annotations = null, ?array $_meta = null ): TextContent {
192	return self::text( $message, $annotations, $_meta );
193	}
194
195	/**
196	* Creates a TextContent DTO.
197	*
198	* @param string $text The text content.
199	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations Optional annotations for the client.
200	* @param array\|null $_meta Optional metadata for the content block.
201	*
202	* @return \WP\McpSchema\Common\Content\DTO\TextContent The created TextContent DTO.
203	*/
204	public static function text( string $text, ?Annotations $annotations = null, ?array $_meta = null ): TextContent {
205	return TextContent::fromArray(
206	array(
207	'type' => TextContent::TYPE,
208	'text' => $text,
209	'annotations' => $annotations,
210	'_meta' => McpValidator::normalize_meta( $_meta ),
211	)
212	);
213	}
214
215	/**
216	* Creates a TextContent DTO with JSON-encoded data.
217	*
218	* Convenience method for creating text content from structured data.
219	* The data is encoded as JSON and wrapped in a TextContent DTO.
220	*
221	* @param mixed $data The data to JSON-encode.
222	* @param int $flags JSON encoding flags (default: 0).
223	* @param \WP\McpSchema\Common\Protocol\DTO\Annotations\|null $annotations Optional annotations for the client.
224	* @param array\|null $_meta Optional metadata for the content block.
225	*
226	* @return \WP\McpSchema\Common\Content\DTO\TextContent The created TextContent DTO.
227	*/
228	public static function json_text( $data, int $flags = 0, ?Annotations $annotations = null, ?array $_meta = null ): TextContent {
229	$json = wp_json_encode( $data, $flags );
230	if ( false === $json ) {
231	$json = '{}';
232	}
233
234	return self::text( $json, $annotations, $_meta );
235	}
236
237	/**
238	* Converts an array of ContentBlockInterface DTOs to their array representations.
239	*
240	* Use this at the serialization boundary when preparing content blocks for JSON output.
241	*
242	* @param \WP\McpSchema\Common\Protocol\Union\ContentBlockInterface[] $blocks Array of content block DTOs.
243	*
244	* @return array[] Array of content block arrays.
245	*/
246	public static function to_array_list( array $blocks ): array {
247	return array_map(
248	static function ( ContentBlockInterface $block ): array {
249	return $block->toArray();
250	},
251	$blocks
252	);
253	}
254	}
255