ability = $ability; } /** * Build clean revision-neutral tool data and adapter metadata. * * This method returns protocol-only data and provides the adapter metadata * separately. Projection through each selected MCP schema happens in McpTool. * wiring to protocol surfaces. * * @param \WP_Ability $ability The ability. * * @return array{tool_data: array, adapter_meta: array}|\WP_Error * @since 0.5.0 * */ public static function build( \WP_Ability $ability ) { $tool = new self( $ability ); $data = $tool->build_tool_data(); if ( is_wp_error( $data ) ) { return $data; } return array( 'tool_data' => $data['tool_data'], 'adapter_meta' => $data['adapter_meta'], ); } /** * Build tool data and adapter metadata. * * @return array{tool_data: array, adapter_meta: array}|\WP_Error * @since 0.5.0 * */ private function build_tool_data() { // Resolve tool name first (can fail). $tool_name = $this->resolve_tool_name(); if ( is_wp_error( $tool_name ) ) { return $tool_name; } $mcp_meta = McpAbilityMeta::mcp( $this->ability ); if ( is_wp_error( $mcp_meta ) ) { return $mcp_meta; } // Transform input schema to MCP-compatible object format. $input_transform = SchemaTransformer::transform_to_object_schema( $this->ability->get_input_schema() ); // Label and description are carried as given; core requires both to be // non-empty strings, so nothing is trimmed or suppressed here. $label = $this->ability->get_label(); $tool_data = array( 'name' => $tool_name, 'description' => $this->ability->get_description(), // Retain the empty properties object historically supplied by the schema DTO. 'inputSchema' => $input_transform['schema'] + array( 'properties' => new \stdClass() ), 'title' => $label, ); // Add optional output schema, transformed to object format if needed. $output_schema = $this->ability->get_output_schema(); $output_transform = null; if ( ! empty( $output_schema ) ) { $output_transform = SchemaTransformer::transform_to_object_schema( $output_schema, 'result' ); $tool_data['outputSchema'] = $output_transform['schema'] + array( 'properties' => new \stdClass() ); } // Map annotations from ability meta to MCP format using unified mapper. $ability_meta = $this->ability->get_meta(); if ( ! empty( $ability_meta['annotations'] ) && is_array( $ability_meta['annotations'] ) ) { $mcp_annotations = McpAnnotationMapper::map( $ability_meta['annotations'], 'tool' ); if ( ! empty( $mcp_annotations ) ) { $tool_data['annotations'] = $mcp_annotations; } } // Set annotations.title from label if annotations exist but don't have a title. if ( isset( $tool_data['annotations'] ) && ! isset( $tool_data['annotations']['title'] ) ) { $tool_data['annotations']['title'] = $label; } // Store transformation metadata as internal metadata (stripped before responding to clients). // Only record keys when semantically meaningful to keep metadata minimal and accurate. $adapter_meta = array( 'ability' => $this->ability->get_name(), ); // Only record input transformation metadata when a wrapper was actually applied. if ( ! empty( $input_transform['was_transformed'] ) ) { $adapter_meta['input_schema_transformed'] = true; $adapter_meta['input_schema_wrapper'] = $input_transform['wrapper_property']; } // Only record output transformation metadata when outputSchema exists. // Record wrapper only when transformation actually occurred. if ( null !== $output_transform && ! empty( $output_transform['was_transformed'] ) ) { $adapter_meta['output_schema_transformed'] = true; $adapter_meta['output_schema_wrapper'] = $output_transform['wrapper_property']; } // Icons and `_meta` come from ability.meta.mcp and are carried as given; the // schema decides whether they fit. Adapter metadata is NEVER included in // protocol meta; it is returned separately in adapter_meta. if ( isset( $mcp_meta['icons'] ) ) { $tool_data['icons'] = $mcp_meta['icons']; } if ( isset( $mcp_meta['_meta'] ) ) { $tool_data['_meta'] = $mcp_meta['_meta']; } return array( 'tool_data' => $tool_data, 'adapter_meta' => $adapter_meta, ); } /** * Resolve the MCP tool name from ability. * * Sanitizes the ability name to MCP-valid format, applies filter, and validates result. * * @return string|\WP_Error Valid tool name or error. * @since 0.5.0 * */ private function resolve_tool_name() { // Sanitize ability name to MCP-valid format. $sanitized_name = McpNameSanitizer::sanitize_name( $this->ability->get_name() ); if ( is_wp_error( $sanitized_name ) ) { return $sanitized_name; } /** * Filters the MCP tool name derived from an ability. * * @since 0.5.0 * * @param string $name The sanitized tool name. * @param \WP_Ability $ability The source ability instance. */ $filtered_name = apply_filters( 'mcp_adapter_tool_name', $sanitized_name, $this->ability ); // Validate post-filter (in case filter broke it). if ( ! is_string( $filtered_name ) || ! McpValidator::validate_name( $filtered_name ) ) { return new WP_Error( 'mcp_tool_name_filter_invalid', sprintf( /* translators: %s: invalid tool name returned by filter */ __( 'Filter returned invalid MCP tool name: %s', 'mcp-adapter' ), is_string( $filtered_name ) ? $filtered_name : gettype( $filtered_name ) ) ); } return $filtered_name; } }