convertkit / vendor / wordpress / mcp-adapter / includes / Abilities / GetAbilityInfoAbility.php

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

192 lines 5.8 KB

Raw Download Zip

1	<?php
2	/**
3	* Ability for getting detailed information about WordPress abilities.
4	*
5	* @package McpAdapter
6	*/
7
8	declare( strict_types=1 );
9
10	namespace WP\MCP\Abilities;
11
12	use WP_Error;
13
14	/**
15	* Get Ability Info - Get detailed information about a specific WordPress ability.
16	*
17	* This ability provides detailed information about any registered WordPress ability,
18	* including its input/output schemas, description, and usage examples.
19	*
20	* SECURITY CONSIDERATIONS:
21	* - This ability exposes detailed schemas and metadata about abilities
22	* - Only abilities with effective MCP public exposure can be queried via default MCP server.
23	* - Requires proper WordPress capability checks for secure operation
24	*
25	* @see https://developer.wordpress.org/apis/security/ for detailed security guidance
26	*/
27	final class GetAbilityInfoAbility {
28	use McpAbilityHelperTrait;
29
30	/**
31	* Register the ability.
32	*/
33	public static function register(): void {
34	wp_register_ability(
35	'mcp-adapter/get-ability-info',
36	array(
37	'label' => 'Get Ability Info',
38	'description' => 'Get detailed information about a specific WordPress ability including its input/output schema, description, and usage examples.',
39	'category' => 'mcp-adapter',
40	'input_schema' => array(
41	'type' => 'object',
42	'properties' => array(
43	'ability_name' => array(
44	'type' => 'string',
45	'description' => 'The full name of the ability to get information about',
46	),
47	),
48	'required' => array( 'ability_name' ),
49	),
50	'output_schema' => array(
51	'type' => 'object',
52	'properties' => array(
53	'name' => array( 'type' => 'string' ),
54	'label' => array( 'type' => 'string' ),
55	'description' => array( 'type' => 'string' ),
56	'input_schema' => array(
57	'type' => 'object',
58	'description' => 'JSON Schema for the ability input parameters',
59	),
60	'output_schema' => array(
61	'type' => 'object',
62	'description' => 'JSON Schema for the ability output structure',
63	),
64	'meta' => array(
65	'type' => 'object',
66	'description' => 'Additional metadata about the ability',
67	),
68	),
69	'required' => array( 'name', 'label', 'description', 'input_schema' ),
70	),
71	'permission_callback' => array( self::class, 'check_permission' ),
72	'execute_callback' => array( self::class, 'execute' ),
73	'meta' => array(
74	'annotations' => array(
75	'readonly' => true,
76	'destructive' => false,
77	'idempotent' => true,
78	),
79	),
80	)
81	);
82	}
83
84	/**
85	* Execute the get ability info functionality.
86	*
87	* Note: Permission checks are handled by the WP_Ability::execute() framework method
88	* before this callback is invoked (see WP_Ability::execute() line 605).
89	*
90	* @param array $input Input parameters containing ability_name.
91	*
92	* @return array Array containing detailed ability information.
93	*/
94	public static function execute( $input = array() ): array {
95	$ability_name = $input['ability_name'] ?? '';
96
97	if ( empty( $ability_name ) ) {
98	return array(
99	'error' => 'Ability name is required',
100	);
101	}
102
103	$ability = wp_get_ability( $ability_name );
104
105	if ( ! $ability ) {
106	return array(
107	'error' => "Ability '{$ability_name}' not found",
108	);
109	}
110
111	$ability_info = array(
112	'name' => $ability->get_name(),
113	'label' => $ability->get_label(),
114	'description' => $ability->get_description(),
115	'input_schema' => $ability->get_input_schema(),
116	);
117
118	// Add output schema if available
119	$output_schema = $ability->get_output_schema();
120	if ( ! empty( $output_schema ) ) {
121	$ability_info['output_schema'] = $output_schema;
122	}
123
124	// Add meta information if available
125	$meta = $ability->get_meta();
126	if ( ! empty( $meta ) ) {
127	$ability_info['meta'] = $meta;
128	}
129
130	return $ability_info;
131	}
132
133	/**
134	* Check permissions for getting ability info.
135	*
136	* Validates user capabilities, caller identity, and MCP exposure restrictions.
137	*
138	* @param array $input Input parameters containing ability_name.
139	*
140	* @return bool\|\WP_Error True if the user has permission to get ability info.
141	*/
142	public static function check_permission( $input = array() ) {
143	$ability_name = $input['ability_name'] ?? '';
144
145	if ( empty( $ability_name ) ) {
146	return new WP_Error( 'missing_ability_name', 'Ability name is required' );
147	}
148
149	// Validate user authentication and capabilities
150	$user_check = self::validate_user_access();
151	if ( is_wp_error( $user_check ) ) {
152	return $user_check;
153	}
154
155	// Check MCP exposure restrictions
156	return self::check_ability_mcp_exposure( $ability_name );
157	}
158
159	/**
160	* Validate user authentication and basic capabilities for get ability info.
161	*
162	* @return bool\|\WP_Error True if valid, WP_Error if validation fails.
163	*/
164	private static function validate_user_access() {
165	// Verify caller identity - ensure user is authenticated
166	if ( ! is_user_logged_in() ) {
167	return new WP_Error( 'authentication_required', 'User must be authenticated to access this ability' );
168	}
169
170	/**
171	* Filters the capability required to get ability information.
172	*
173	* This capability is checked before returning detailed information about
174	* a specific WordPress ability through the mcp-adapter-get-ability-info tool.
175	*
176	* @since 0.3.0
177	*
178	* @param string $capability The required capability. Default 'read'.
179	*/
180	$required_capability = apply_filters( 'mcp_adapter_get_ability_info_capability', 'read' );
181	// phpcs:ignore WordPress.WP.Capabilities.Undetermined -- Capability is determined dynamically via filter
182	if ( ! current_user_can( $required_capability ) ) {
183	return new WP_Error(
184	'insufficient_capability',
185	sprintf( 'User lacks required capability: %s', $required_capability )
186	);
187	}
188
189	return true;
190	}
191	}
192