McpTool.php
7 months ago
McpToolValidator.php
7 months ago
RegisterAbilityAsMcpTool.php
7 months ago
McpToolValidator.php
295 lines
| 1 | <?php |
| 2 | /** |
| 3 | * MCP Tool Validator class for validating MCP tools according to the specification. |
| 4 | * |
| 5 | * @package McpAdapter |
| 6 | */ |
| 7 | |
| 8 | declare( strict_types=1 ); |
| 9 | |
| 10 | namespace WP\MCP\Domain\Tools; |
| 11 | |
| 12 | use stdClass; |
| 13 | |
| 14 | /** |
| 15 | * Validates MCP tools against the Model Context Protocol specification. |
| 16 | * |
| 17 | * Provides minimal, resource-efficient validation to ensure tools conform |
| 18 | * to the MCP schema requirements without heavy processing overhead. |
| 19 | * |
| 20 | * @link https://modelcontextprotocol.io/specification/2025-06-18/server/tools |
| 21 | */ |
| 22 | class McpToolValidator { |
| 23 | |
| 24 | /** |
| 25 | * Validate the MCP tool data array against the MCP schema. |
| 26 | * |
| 27 | * @param array $tool_data The tool data to validate. |
| 28 | * @param string $context Optional context for error messages. |
| 29 | * |
| 30 | * @return bool|\WP_Error True if valid, WP_Error if validation fails. |
| 31 | */ |
| 32 | public static function validate_tool_data( array $tool_data, string $context = '' ) { |
| 33 | $validation_errors = self::get_validation_errors( $tool_data ); |
| 34 | |
| 35 | if ( ! empty( $validation_errors ) ) { |
| 36 | $error_message = $context ? "[{$context}] " : ''; |
| 37 | $error_message .= sprintf( |
| 38 | /* translators: %s: comma-separated list of validation errors */ |
| 39 | __( 'Tool validation failed: %s', 'mcp-adapter' ), |
| 40 | implode( ', ', $validation_errors ) |
| 41 | ); |
| 42 | return new \WP_Error( 'tool_validation_failed', esc_html( $error_message ) ); |
| 43 | } |
| 44 | |
| 45 | return true; |
| 46 | } |
| 47 | |
| 48 | /** |
| 49 | * Validate an McpTool instance against the MCP schema. |
| 50 | * |
| 51 | * @param \WP\MCP\Domain\Tools\McpTool $tool The tool instance to validate. |
| 52 | * @param string $context Optional context for error messages. |
| 53 | * |
| 54 | * @return bool|\WP_Error True if valid, WP_Error if validation fails. |
| 55 | */ |
| 56 | public static function validate_tool_instance( McpTool $tool, string $context = '' ) { |
| 57 | $uniqueness_result = self::validate_tool_uniqueness( $tool, $context ); |
| 58 | if ( is_wp_error( $uniqueness_result ) ) { |
| 59 | return $uniqueness_result; |
| 60 | } |
| 61 | |
| 62 | return self::validate_tool_data( $tool->to_array(), $context ); |
| 63 | } |
| 64 | |
| 65 | /** |
| 66 | * Get validation error details for debugging purposes. |
| 67 | * This is the core validation method - all other validation methods use this. |
| 68 | * |
| 69 | * @param array $tool_data The tool data to validate. |
| 70 | * |
| 71 | * @return array Array of validation errors, empty if valid. |
| 72 | */ |
| 73 | public static function get_validation_errors( array $tool_data ): array { |
| 74 | $errors = array(); |
| 75 | |
| 76 | // Sanitize string inputs. |
| 77 | if ( isset( $tool_data['name'] ) && is_string( $tool_data['name'] ) ) { |
| 78 | $tool_data['name'] = trim( $tool_data['name'] ); |
| 79 | } |
| 80 | if ( isset( $tool_data['description'] ) && is_string( $tool_data['description'] ) ) { |
| 81 | $tool_data['description'] = trim( $tool_data['description'] ); |
| 82 | } |
| 83 | if ( isset( $tool_data['title'] ) && is_string( $tool_data['title'] ) ) { |
| 84 | $tool_data['title'] = trim( $tool_data['title'] ); |
| 85 | } |
| 86 | |
| 87 | // Check the required fields. |
| 88 | if ( empty( $tool_data['name'] ) || ! is_string( $tool_data['name'] ) || ! self::validate_tool_name( $tool_data['name'] ) ) { |
| 89 | $errors[] = __( 'Tool name is required and must only contain letters, numbers, hyphens (-), and underscores (_), and be 255 characters or less', 'mcp-adapter' ); |
| 90 | } |
| 91 | |
| 92 | if ( empty( $tool_data['description'] ) || ! is_string( $tool_data['description'] ) ) { |
| 93 | $errors[] = __( 'Tool description is required and must be a non-empty string', 'mcp-adapter' ); |
| 94 | } |
| 95 | |
| 96 | // Validate inputSchema (required field). |
| 97 | $input_schema_errors = self::get_schema_validation_errors( $tool_data['inputSchema'] ?? null, 'inputSchema' ); |
| 98 | if ( ! empty( $input_schema_errors ) ) { |
| 99 | $errors = array_merge( $errors, $input_schema_errors ); |
| 100 | } |
| 101 | |
| 102 | // Check optional fields if present. |
| 103 | if ( isset( $tool_data['title'] ) && ! is_string( $tool_data['title'] ) ) { |
| 104 | $errors[] = __( 'Tool title must be a string if provided', 'mcp-adapter' ); |
| 105 | } |
| 106 | |
| 107 | // Validate outputSchema (optional field). |
| 108 | if ( isset( $tool_data['outputSchema'] ) ) { |
| 109 | $output_schema_errors = self::get_schema_validation_errors( $tool_data['outputSchema'], 'outputSchema' ); |
| 110 | if ( ! empty( $output_schema_errors ) ) { |
| 111 | $errors = array_merge( $errors, $output_schema_errors ); |
| 112 | } |
| 113 | } |
| 114 | |
| 115 | if ( isset( $tool_data['annotations'] ) && ! is_array( $tool_data['annotations'] ) ) { |
| 116 | $errors[] = __( 'Tool annotations must be an array if provided', 'mcp-adapter' ); |
| 117 | } |
| 118 | |
| 119 | return $errors; |
| 120 | } |
| 121 | |
| 122 | /** |
| 123 | * Get detailed validation errors for a schema object. |
| 124 | * |
| 125 | * @param array|mixed $schema The schema to validate. |
| 126 | * @param string $field_name The name of the field being validated (for error messages). |
| 127 | * |
| 128 | * @return array Array of validation errors, empty if valid. |
| 129 | */ |
| 130 | private static function get_schema_validation_errors( $schema, string $field_name ): array { |
| 131 | // Normalize stdClass to array for validation, and reject scalars/null. |
| 132 | if ( $schema instanceof stdClass ) { |
| 133 | $schema = (array) $schema; |
| 134 | } |
| 135 | |
| 136 | // Schema must be an array/object - early return for performance. |
| 137 | if ( ! is_array( $schema ) ) { |
| 138 | return array( |
| 139 | sprintf( |
| 140 | /* translators: %s: field name (inputSchema or outputSchema) */ |
| 141 | __( 'Tool %s must be a valid JSON schema object', 'mcp-adapter' ), |
| 142 | $field_name |
| 143 | ), |
| 144 | ); |
| 145 | } |
| 146 | |
| 147 | $errors = array(); |
| 148 | |
| 149 | // Input schemas commonly describe an object of arguments. Allow omitted type (empty schema) or type 'object'. |
| 150 | // For output schemas, do not enforce a specific type; any valid JSON Schema is acceptable per MCP. |
| 151 | if ( 'inputSchema' === $field_name && isset( $schema['type'] ) && 'object' !== $schema['type'] ) { |
| 152 | $errors[] = sprintf( |
| 153 | /* translators: %s: field name */ |
| 154 | __( 'Tool %s, if specifying a type, must use type \'object\'', 'mcp-adapter' ), |
| 155 | $field_name |
| 156 | ); |
| 157 | } |
| 158 | |
| 159 | // If properties exist, they must be an array/object. |
| 160 | if ( isset( $schema['properties'] ) && ! is_array( $schema['properties'] ) ) { |
| 161 | $errors[] = sprintf( |
| 162 | /* translators: %s: field name */ |
| 163 | __( 'Tool %s properties must be an object/array', 'mcp-adapter' ), |
| 164 | $field_name |
| 165 | ); |
| 166 | } |
| 167 | |
| 168 | // If required exists, it must be an array. |
| 169 | if ( isset( $schema['required'] ) && ! is_array( $schema['required'] ) ) { |
| 170 | $errors[] = sprintf( |
| 171 | /* translators: %s: field name */ |
| 172 | __( 'Tool %s required field must be an array', 'mcp-adapter' ), |
| 173 | $field_name |
| 174 | ); |
| 175 | } |
| 176 | |
| 177 | // If properties are provided, validate their basic structure. |
| 178 | if ( isset( $schema['properties'] ) && is_array( $schema['properties'] ) ) { |
| 179 | foreach ( $schema['properties'] as $property_name => $property ) { |
| 180 | if ( ! is_array( $property ) ) { |
| 181 | $errors[] = sprintf( |
| 182 | /* translators: %1$s: field name, %2$s: property name */ |
| 183 | __( 'Tool %1$s property \'%2$s\' must be an object', 'mcp-adapter' ), |
| 184 | $field_name, |
| 185 | $property_name |
| 186 | ); |
| 187 | continue; |
| 188 | } |
| 189 | |
| 190 | // Each property should have a type (though not strictly required by JSON Schema). |
| 191 | if ( ! isset( $property['type'] ) || is_string( $property['type'] ) || is_array( $property['type'] ) ) { |
| 192 | continue; |
| 193 | } |
| 194 | |
| 195 | // If type is neither string nor array, it's invalid. |
| 196 | $errors[] = sprintf( |
| 197 | /* translators: %1$s: field name, %2$s: property name */ |
| 198 | __( 'Tool %1$s property \'%2$s\' type must be a string or array of strings (union type)', 'mcp-adapter' ), |
| 199 | $field_name, |
| 200 | $property_name |
| 201 | ); |
| 202 | } |
| 203 | } |
| 204 | |
| 205 | // If required array is provided, validate its structure. |
| 206 | if ( isset( $schema['required'] ) && is_array( $schema['required'] ) ) { |
| 207 | foreach ( $schema['required'] as $required_field ) { |
| 208 | if ( ! is_string( $required_field ) ) { |
| 209 | $errors[] = sprintf( |
| 210 | /* translators: %s: field name */ |
| 211 | __( 'Tool %s required field names must be strings', 'mcp-adapter' ), |
| 212 | $field_name |
| 213 | ); |
| 214 | continue; |
| 215 | } |
| 216 | |
| 217 | // Check that required fields exist in properties (if properties are defined). |
| 218 | if ( ! isset( $schema['properties'] ) || isset( $schema['properties'][ $required_field ] ) ) { |
| 219 | continue; |
| 220 | } |
| 221 | |
| 222 | $errors[] = sprintf( |
| 223 | /* translators: %1$s: field name, %2$s: required field */ |
| 224 | __( 'Tool %1$s required field \'%2$s\' does not exist in properties', 'mcp-adapter' ), |
| 225 | $field_name, |
| 226 | $required_field |
| 227 | ); |
| 228 | } |
| 229 | } |
| 230 | |
| 231 | return $errors; |
| 232 | } |
| 233 | |
| 234 | /** |
| 235 | * Check if tool data is valid without throwing exceptions. |
| 236 | * |
| 237 | * @param array $tool_data The tool data to validate. |
| 238 | * |
| 239 | * @return bool True if valid, false otherwise. |
| 240 | */ |
| 241 | public static function is_valid_tool_data( array $tool_data ): bool { |
| 242 | return empty( self::get_validation_errors( $tool_data ) ); |
| 243 | } |
| 244 | |
| 245 | /** |
| 246 | * Check if a tool name follows MCP naming conventions. |
| 247 | * |
| 248 | * @param string $name The tool name to validate. |
| 249 | * |
| 250 | * @return bool True if valid, false otherwise. |
| 251 | */ |
| 252 | public static function validate_tool_name( string $name ): bool { |
| 253 | // Tool names should not be empty. |
| 254 | if ( empty( $name ) ) { |
| 255 | return false; |
| 256 | } |
| 257 | |
| 258 | // Check length constraints (reasonable limits). |
| 259 | if ( strlen( $name ) > 255 ) { |
| 260 | return false; |
| 261 | } |
| 262 | |
| 263 | // Only allow letters, numbers, hyphens, and underscores. |
| 264 | return (bool) preg_match( '/^[a-zA-Z0-9_-]+$/', $name ); |
| 265 | } |
| 266 | |
| 267 | /** |
| 268 | * Validate that the tool name is unique within the server. |
| 269 | * |
| 270 | * @param \WP\MCP\Domain\Tools\McpTool $tool The tool instance to validate. |
| 271 | * @param string $context Optional context for error messages. |
| 272 | * |
| 273 | * @return bool|\WP_Error True if unique, WP_Error if the tool name is not unique. |
| 274 | */ |
| 275 | public static function validate_tool_uniqueness( McpTool $tool, string $context = '' ) { |
| 276 | $this_tool_name = $tool->get_name(); |
| 277 | $server = $tool->get_mcp_server(); |
| 278 | $existing_tool = $server->get_tool( $this_tool_name ); |
| 279 | |
| 280 | // Check if a tool with this name already exists. |
| 281 | if ( $existing_tool ) { |
| 282 | $error_message = $context ? "[{$context}] " : ''; |
| 283 | $error_message .= sprintf( |
| 284 | /* translators: %1$s: tool name, %2$s: server ID */ |
| 285 | __( 'Tool name \'%1$s\' is not unique. A tool with this name already exists on server \'%2$s\'.', 'mcp-adapter' ), |
| 286 | $this_tool_name, |
| 287 | $server->get_server_id() |
| 288 | ); |
| 289 | return new \WP_Error( 'tool_not_unique', esc_html( $error_message ) ); |
| 290 | } |
| 291 | |
| 292 | return true; |
| 293 | } |
| 294 | } |
| 295 |