convertkit / includes / mcp / class-convertkit-mcp.php

class-convertkit-mcp.php in Kit (formerly ConvertKit) – Email Newsletter, Email Marketing, Membership, Subscribers and Landing Pages 3.4.3, at includes/mcp/class-convertkit-mcp.php

444 lines 11.9 KB

Raw Download Zip

1	<?php
2	/**
3	* Kit MCP class.
4	*
5	* @package ConvertKit
6	* @author ConvertKit
7	*/
8
9	/**
10	* Registers Plugin abilities (tools) using the WordPress Abilities API, and exposes
11	* those abilities as MCP tools via the WordPress MCP Adapter (if installed).
12	*
13	* The Abilities API ships with WordPress 6.9 and later.
14	*
15	* The WordPress MCP Adapter is a separate plugin, and not (yet) part of WordPress
16	* core. If it is not active on the site, abilities are still registered and callable
17	* in PHP, but nothing is exposed over the MCP protocol.
18	*
19	* @package ConvertKit
20	* @author ConvertKit
21	*/
22	class ConvertKit_MCP {
23
24	/**
25	* The ability category slug used to group all Kit abilities.
26	*
27	* @since 3.4.0
28	*
29	* @var string
30	*/
31	const CATEGORY_SLUG = 'kit';
32
33	/**
34	* The MCP server ID.
35	*
36	* @since 3.4.0
37	*
38	* @var string
39	*/
40	const SERVER_ID = 'kit/mcp';
41
42	/**
43	* The REST namespace used by the MCP server.
44	*
45	* @since 3.4.0
46	*
47	* @var string
48	*/
49	const SERVER_NAMESPACE = 'kit/mcp';
50
51	/**
52	* The REST version number used by the MCP server.
53	*
54	* @since 3.4.0
55	*
56	* @var string
57	*/
58	const SERVER_ROUTE = 'v1';
59
60	/**
61	* Returns the absolute URL that MCP clients connect to.
62	*
63	* @since 3.4.0
64	*
65	* @return string
66	*/
67	public static function get_server_url() {
68
69	return rest_url( self::SERVER_NAMESPACE . '/' . self::SERVER_ROUTE );
70
71	}
72
73	/**
74	* Constructor.
75	*
76	* @since 3.4.0
77	*/
78	public function __construct() {
79
80	// Register the ability category.
81	add_action( 'wp_abilities_api_categories_init', array( $this, 'register_abilities_category' ) );
82
83	// Register abilities.
84	add_action( 'wp_abilities_api_init', array( $this, 'register_abilities' ) );
85
86	// Register resources and prompts.
87	add_action( 'wp_abilities_api_init', array( $this, 'register_resources' ) );
88	add_action( 'wp_abilities_api_init', array( $this, 'register_prompts' ) );
89
90	// Register resource-list abilities (Forms, Tags, Landing Pages, Products).
91	// These are owned by the Plugin (not by any single block or feature),
92	// so they're added here rather than via a per-class register_abilities().
93	add_filter( 'convertkit_abilities', array( $this, 'register_resource_abilities' ) );
94
95	// Register MCP resources (live-state lists, account, settings and reference docs).
96	add_filter( 'convertkit_resources', array( $this, 'register_mcp_resources' ) );
97
98	// Register MCP prompts (guided workflows).
99	add_filter( 'convertkit_prompts', array( $this, 'register_mcp_prompts' ) );
100
101	// Register settings get / update abilities for each Plugin settings
102	// These are owned by the Plugin (not by any single feature),
103	// so they're added here rather than via a per-class register_abilities().
104	add_filter( 'convertkit_abilities', array( $this, 'register_settings_abilities' ) );
105
106	// Register the per-Post Kit settings get / update abilities. These
107	// operate on the `_wp_convertkit_post_meta` post meta (form,
108	// landing_page, tag, restrict_content) rather than any Plugin-wide
109	// settings group.
110	add_filter( 'convertkit_abilities', array( $this, 'register_post_settings_abilities' ) );
111
112	// Register the per-Category Kit settings get / update abilities.
113	// These operate on the `_wp_convertkit_term_meta` term meta (form,
114	// form_position) for the WordPress `category` taxonomy.
115	add_filter( 'convertkit_abilities', array( $this, 'register_category_settings_abilities' ) );
116
117	// Register the MCP server.
118	add_action( 'mcp_adapter_init', array( $this, 'register_mcp_server' ) );
119
120	}
121
122	/**
123	* Appends the settings get / update abilities for each Plugin settings
124	* group to the convertkit_abilities filter, so they are registered with
125	* the Abilities API and exposed via the MCP server.
126	*
127	* @since 3.4.0
128	*
129	* @param array $abilities Abilities to register.
130	* @return array
131	*/
132	public function register_settings_abilities( $abilities ) {
133
134	// Settings instances to register with MCP.
135	$groups = array(
136	new ConvertKit_Settings(),
137	new ConvertKit_Settings_Broadcasts(),
138	new ConvertKit_Settings_Restrict_Content(),
139	);
140
141	// Iterate through settings groups, registering the get and update abilities.
142	foreach ( $groups as $settings ) {
143	$get = new ConvertKit_MCP_Ability_Settings_Get( $settings );
144	$update = new ConvertKit_MCP_Ability_Settings_Update( $settings );
145
146	$abilities[ $get->get_name() ] = $get;
147	$abilities[ $update->get_name() ] = $update;
148	}
149
150	return $abilities;
151
152	}
153
154	/**
155	* Appends the per-Post Kit settings abilities to the convertkit_abilities
156	* filter, so they are registered with the Abilities API and exposed via
157	* the MCP server.
158	*
159	* @since 3.4.0
160	*
161	* @param array $abilities Abilities to register.
162	* @return array
163	*/
164	public function register_post_settings_abilities( $abilities ) {
165
166	$abilities['kit/post-settings-get'] = new ConvertKit_MCP_Ability_Post_Settings_Get();
167	$abilities['kit/post-settings-update'] = new ConvertKit_MCP_Ability_Post_Settings_Update();
168
169	return $abilities;
170
171	}
172
173	/**
174	* Appends the per-Category Kit settings abilities to the convertkit_abilities
175	* filter, so they are registered with the Abilities API and exposed via
176	* the MCP server.
177	*
178	* @since 3.4.0
179	*
180	* @param array $abilities Abilities to register.
181	* @return array
182	*/
183	public function register_category_settings_abilities( $abilities ) {
184
185	$abilities['kit/category-settings-get'] = new ConvertKit_MCP_Ability_Category_Settings_Get();
186	$abilities['kit/category-settings-update'] = new ConvertKit_MCP_Ability_Category_Settings_Update();
187
188	return $abilities;
189
190	}
191
192	/**
193	* Appends the resource-list abilities (Forms, Tags, Landing Pages,
194	* Products) to the convertkit_abilities filter, so they are registered
195	* with the Abilities API and exposed via the MCP server.
196	*
197	* @since 3.4.0
198	*
199	* @param array $abilities Abilities to register.
200	* @return array
201	*/
202	public function register_resource_abilities( $abilities ) {
203
204	return array_merge(
205	$abilities,
206	array(
207	'kit/forms-list' => new ConvertKit_MCP_Ability_Resource_Forms(),
208	'kit/tags-list' => new ConvertKit_MCP_Ability_Resource_Tags(),
209	'kit/landing-pages-list' => new ConvertKit_MCP_Ability_Resource_Landing_Pages(),
210	'kit/products-list' => new ConvertKit_MCP_Ability_Resource_Products(),
211	)
212	);
213
214	}
215
216	/**
217	* Appends the MCP resources (live-state lists, account, settings and
218	* reference docs) to the convertkit_resources filter, so they are
219	* registered with the Abilities API and exposed as MCP Resources.
220	*
221	* @since 3.5.0
222	*
223	* @param array $resources Resources to register.
224	* @return array
225	*/
226	public function register_mcp_resources( $resources ) {
227
228	$mcp_resources = array(
229	new ConvertKit_MCP_Resource_Forms(),
230	new ConvertKit_MCP_Resource_Tags(),
231	new ConvertKit_MCP_Resource_Landing_Pages(),
232	new ConvertKit_MCP_Resource_Products(),
233	new ConvertKit_MCP_Resource_Account(),
234	new ConvertKit_MCP_Resource_Settings(),
235	new ConvertKit_MCP_Resource_Overview(),
236	new ConvertKit_MCP_Resource_Forms_Reference(),
237	new ConvertKit_MCP_Resource_Restrict_Content_Reference(),
238	new ConvertKit_MCP_Resource_Settings_Reference(),
239	);
240
241	foreach ( $mcp_resources as $resource ) {
242	$resources[ $resource->get_name() ] = $resource;
243	}
244
245	return $resources;
246
247	}
248
249	/**
250	* Appends the MCP prompts (guided workflows) to the convertkit_prompts
251	* filter, so they are registered with the Abilities API and exposed as
252	* MCP Prompts.
253	*
254	* @since 3.5.0
255	*
256	* @param array $prompts Prompts to register.
257	* @return array
258	*/
259	public function register_mcp_prompts( $prompts ) {
260
261	$mcp_prompts = array(
262	new ConvertKit_MCP_Prompt_Setup(),
263	new ConvertKit_MCP_Prompt_Add_Form(),
264	new ConvertKit_MCP_Prompt_Restrict_Content(),
265	new ConvertKit_MCP_Prompt_Configure_Broadcasts_Import(),
266	new ConvertKit_MCP_Prompt_Audit(),
267	);
268
269	foreach ( $mcp_prompts as $prompt ) {
270	$prompts[ $prompt->get_name() ] = $prompt;
271	}
272
273	return $prompts;
274
275	}
276
277	/**
278	* Register the 'kit' ability category.
279	*
280	* @since 3.4.0
281	*/
282	public function register_abilities_category() {
283
284	wp_register_ability_category(
285	self::CATEGORY_SLUG,
286	array(
287	'label' => __( 'Kit', 'convertkit' ),
288	'description' => __( 'Abilities exposed by the Kit Plugin.', 'convertkit' ),
289	)
290	);
291
292	}
293
294	/**
295	* Register abilities with the WordPress Abilities API.
296	*
297	* @since 3.4.0
298	*/
299	public function register_abilities() {
300
301	// Get abilities.
302	$abilities = convertkit_get_abilities();
303
304	// Bail if no abilities are available.
305	if ( ! count( $abilities ) ) {
306	return;
307	}
308
309	// Iterate through abilities, registering them.
310	foreach ( $abilities as $ability ) {
311
312	// Skip if this ability is not an instance of ConvertKit_MCP_Ability.
313	if ( ! ( $ability instanceof ConvertKit_MCP_Ability ) ) {
314	continue;
315	}
316
317	// Register ability.
318	wp_register_ability( $ability->get_name(), $ability->get_ability_args() );
319	}
320
321	}
322
323	/**
324	* Register MCP resources with the WordPress Abilities API.
325	*
326	* @since 3.4.2
327	*/
328	public function register_resources() {
329
330	// Get resources.
331	$resources = convertkit_get_resources();
332
333	// Bail if no resources are available.
334	if ( ! count( $resources ) ) {
335	return;
336	}
337
338	// Iterate through resources, registering each as an ability.
339	foreach ( $resources as $resource ) {
340
341	// Skip if this resource is not an instance of ConvertKit_MCP_Resource.
342	if ( ! ( $resource instanceof ConvertKit_MCP_Resource ) ) {
343	continue;
344	}
345
346	// Register resource.
347	wp_register_ability( $resource->get_name(), $resource->get_ability_args() );
348	}
349
350	}
351
352	/**
353	* Register MCP prompts with the WordPress Abilities API.
354	*
355	* @since 3.4.2
356	*/
357	public function register_prompts() {
358
359	// Get prompts.
360	$prompts = convertkit_get_prompts();
361
362	// Bail if no prompts are available.
363	if ( ! count( $prompts ) ) {
364	return;
365	}
366
367	// Iterate through prompts, registering each as an ability.
368	foreach ( $prompts as $prompt ) {
369
370	// Skip if this prompt is not an instance of ConvertKit_MCP_Prompt.
371	if ( ! ( $prompt instanceof ConvertKit_MCP_Prompt ) ) {
372	continue;
373	}
374
375	// Register prompt.
376	wp_register_ability( $prompt->get_name(), $prompt->get_ability_args() );
377	}
378
379	}
380
381	/**
382	* Register an MCP server that exposes Kit abilities as MCP tools.
383	*
384	* @since 3.4.0
385	*
386	* @param object $adapter The MCP Adapter instance.
387	* @return void
388	*/
389	public function register_mcp_server( $adapter ) {
390
391	// Bail if the MCP server isn't enabled.
392	$settings = new ConvertKit_Settings();
393	$mcp_settings = new ConvertKit_Settings_MCP();
394	if ( ! $mcp_settings->enabled() ) {
395	return;
396	}
397
398	// Get abilities.
399	$abilities = convertkit_get_abilities();
400
401	// Build array of ability names.
402	$ability_names = array();
403	foreach ( $abilities as $ability ) {
404	$ability_names[] = $ability->get_name();
405	}
406
407	// Build array of resource names.
408	$resource_names = array();
409	foreach ( convertkit_get_resources() as $resource ) {
410	$resource_names[] = $resource->get_name();
411	}
412
413	// Build array of prompt names.
414	$prompt_names = array();
415	foreach ( convertkit_get_prompts() as $prompt ) {
416	$prompt_names[] = $prompt->get_name();
417	}
418
419	// Create the MCP server.
420	$result = $adapter->create_server(
421	self::SERVER_ID,
422	self::SERVER_NAMESPACE,
423	self::SERVER_ROUTE,
424	__( 'Kit WordPress Plugin MCP', 'convertkit' ),
425	__( 'Exposes Kit Plugin abilities over the Model Context Protocol.', 'convertkit' ),
426	'1.0.0',
427	array( 'WP\\MCP\\Transport\\HttpTransport' ),
428	'WP\\MCP\\Infrastructure\\ErrorHandling\\ErrorLogMcpErrorHandler',
429	'WP\\MCP\\Infrastructure\\Observability\\NullMcpObservabilityHandler',
430	$ability_names, // Abilities (Tools).
431	$resource_names, // Resources.
432	$prompt_names // Prompts.
433	);
434
435	// If an error occured when creating the server, log it.
436	if ( is_wp_error( $result ) && $settings->debug_enabled() ) {
437	$log = new ConvertKit_Log( CONVERTKIT_PLUGIN_PATH );
438	$log->add( 'MCP: create_server(): Error: ' . $result->get_error_message() );
439	}
440
441	}
442
443	}
444