, ability_property: string|null}> */ private static array $mcp_annotations = array( // Shared annotations - Resources only (NOT Tools or Prompt templates per MCP spec). // ToolAnnotations is a separate type that does not include these fields. // Prompt templates do not support annotations; only content blocks inside messages do. 'audience' => array( 'type' => 'array', 'features' => array( 'resource' ), 'ability_property' => null, ), 'lastModified' => array( 'type' => 'string', 'features' => array( 'resource' ), 'ability_property' => null, ), 'priority' => array( 'type' => 'number', 'features' => array( 'resource' ), 'ability_property' => null, ), // Tool-specific annotations (ToolAnnotations type per MCP 2025-11-25 spec). 'readOnlyHint' => array( 'type' => 'boolean', 'features' => array( 'tool' ), 'ability_property' => 'readonly', ), 'destructiveHint' => array( 'type' => 'boolean', 'features' => array( 'tool' ), 'ability_property' => 'destructive', ), 'idempotentHint' => array( 'type' => 'boolean', 'features' => array( 'tool' ), 'ability_property' => 'idempotent', ), 'openWorldHint' => array( 'type' => 'boolean', 'features' => array( 'tool' ), 'ability_property' => null, ), 'title' => array( 'type' => 'string', 'features' => array( 'tool' ), 'ability_property' => null, ), ); /** * Map WordPress ability annotation property names to MCP field names. * * Maps WordPress-format field names to MCP equivalents (e.g., readonly → readOnlyHint). * Only includes annotations applicable to the specified feature type. * Null values are excluded from the result. * * @param array $ability_annotations WordPress ability annotations. * @param string $feature_type The MCP feature type ('tool', 'resource', or 'prompt'). * * @return array Mapped annotations for the specified feature type. */ public static function map( array $ability_annotations, string $feature_type ): array { $result = array(); foreach ( self::$mcp_annotations as $mcp_field => $config ) { if ( ! in_array( $feature_type, $config['features'], true ) ) { continue; } $value = self::resolve_annotation_value( $ability_annotations, $mcp_field, $config['ability_property'] ); if ( null === $value ) { continue; } $normalized = self::normalize_annotation_value( $config['type'], $value ); if ( null === $normalized ) { continue; } $result[ $mcp_field ] = $normalized; } return $result; } /** * Resolve the annotation value, preferring WordPress-format overrides when available. * * @param array $annotations Raw annotations from the ability. * @param string $mcp_field The MCP field name. * @param string|null $ability_property Optional WordPress-format field name, or null if mapping 1:1. * * @return mixed The annotation value, or null if not found. */ private static function resolve_annotation_value( array $annotations, string $mcp_field, ?string $ability_property ) { // WordPress-format overrides take precedence when present. if ( null !== $ability_property && array_key_exists( $ability_property, $annotations ) && ! is_null( $annotations[ $ability_property ] ) ) { return $annotations[ $ability_property ]; } if ( array_key_exists( $mcp_field, $annotations ) && ! is_null( $annotations[ $mcp_field ] ) ) { return $annotations[ $mcp_field ]; } return null; } /** * Normalize annotation values to the types expected by MCP. * * @param string $field_type Expected MCP type (boolean, string, array, number). * @param mixed $value Raw annotation value. * * @return mixed|null Normalized value or null if invalid. */ private static function normalize_annotation_value( string $field_type, $value ) { switch ( $field_type ) { case 'boolean': return self::normalize_boolean( $value ); case 'string': if ( ! is_scalar( $value ) ) { return null; } $trimmed = trim( (string) $value ); return '' === $trimmed ? null : $trimmed; case 'array': return is_array( $value ) && ! empty( $value ) ? $value : null; case 'number': return is_numeric( $value ) ? (float) $value : null; default: return $value; } } /** * Normalize a value to a strict boolean. * * Accepts only well-defined boolean representations to avoid ambiguous conversions. * PHP's default (bool) cast incorrectly converts 'false' string to true. * * Accepted values: * - true, false (PHP booleans) * - 1, 0 (integers) * - '1', '0', 'true', 'false' (case-insensitive strings) * * @param mixed $value The value to normalize. * * @return bool|null The normalized boolean, or null if value cannot be safely converted. */ private static function normalize_boolean( $value ): ?bool { // Already a boolean - return as-is. if ( is_bool( $value ) ) { return $value; } // Integer 1 or 0. if ( is_int( $value ) ) { if ( 1 === $value ) { return true; } if ( 0 === $value ) { return false; } // Other integers are invalid (e.g., 2, -1). return null; } // String representations (case-insensitive). if ( is_string( $value ) ) { $lower = strtolower( trim( $value ) ); if ( 'true' === $lower || '1' === $lower ) { return true; } if ( 'false' === $lower || '0' === $lower ) { return false; } // Other strings are invalid (e.g., 'yes', 'no', empty string). return null; } // All other types (arrays, objects, floats, null) are invalid. return null; } }