FileMaster
Search
Toggle Dark Mode
Home
/
.
/
wp-content
/
plugins
/
woocommerce
/
vendor
/
wordpress
/
mcp-adapter
/
includes
/
Domain
/
Prompts
Edit File: McpPrompt.php
<?php /** * WordPress MCP Prompt class for representing MCP prompts according to the specification. * * @package McpAdapter */ declare( strict_types=1 ); namespace WP\MCP\Domain\Prompts; use WP\MCP\Core\McpServer; /** * Represents an MCP prompt according to the Model Context Protocol specification. * * Prompts provide structured messages and instructions for interacting with language models. * Each prompt is uniquely identified by a name and can include arguments for customization. * * @link https://modelcontextprotocol.io/specification/2025-06-18/server/prompts */ class McpPrompt { /** * The ability name. * * @var string */ private string $ability; /** * Unique identifier for the prompt. * * @var string */ private string $name; /** * Optional human-readable name of the prompt for display purposes. * * @var string|null */ private ?string $title; /** * Optional human-readable description of the prompt. * * @var string|null */ private ?string $description; /** * Optional list of arguments for prompt customization. * * @var array */ private array $arguments; /** * Optional properties describing prompt metadata. * * @var array */ private array $annotations; /** * The MCP server instance this prompt belongs to. * * @var \WP\MCP\Core\McpServer */ private McpServer $mcp_server; /** * Constructor for McpPrompt. * * @param string $ability The ability name. * @param string $name Unique identifier for the prompt. * @param string|null $title Optional human-readable name for display. * @param string|null $description Optional human-readable description. * @param array $arguments Optional list of arguments for customization. * @param array $annotations Optional properties describing prompt metadata. */ public function __construct( string $ability, string $name, ?string $title = null, ?string $description = null, array $arguments = array(), array $annotations = array() ) { $this->ability = $ability; $this->name = $name; $this->title = $title; $this->description = $description; $this->arguments = $arguments; $this->annotations = $annotations; } /** * Get the prompt name. * * @return string */ public function get_name(): string { return $this->name; } /** * Get the prompt title. * * @return string|null */ public function get_title(): ?string { return $this->title; } /** * Get the prompt description. * * @return string|null */ public function get_description(): ?string { return $this->description; } /** * Get the prompt arguments. * * @return array */ public function get_arguments(): array { return $this->arguments; } /** * Get the annotations. * * @return array */ public function get_annotations(): array { return $this->annotations; } /** * Get the ability name. * * @return \WP_Ability|\WP_Error WP_Ability instance on success, WP_Error on failure. */ public function get_ability() { $ability = wp_get_ability( $this->ability ); if ( ! $ability ) { return new \WP_Error( 'ability_not_found', sprintf( /* translators: %s: ability name */ esc_html__( "WordPress ability '%s' does not exist.", 'mcp-adapter' ), esc_html( $this->ability ) ) ); } return $ability; } /** * Set the prompt title. * * @param string|null $title The title to set. * * @return void */ public function set_title( ?string $title ): void { $this->title = $title; } /** * Set the prompt description. * * @param string|null $description The description to set. * * @return void */ public function set_description( ?string $description ): void { $this->description = $description; } /** * Set the prompt arguments. * * @param array $arguments The arguments to set. * * @return void */ public function set_arguments( array $arguments ): void { $this->arguments = $arguments; } /** * Set the annotations. * * @param array $annotations The annotations to set. * * @return void */ public function set_annotations( array $annotations ): void { $this->annotations = $annotations; } /** * Add an argument to the prompt. * * @param array $argument The argument to add. * * @return void */ public function add_argument( array $argument ): void { $this->arguments[] = $argument; } /** * Remove an argument by name. * * @param string $name The argument name to remove. * * @return void */ public function remove_argument( string $name ): void { $this->arguments = array_filter( $this->arguments, static function ( $argument ) use ( $name ) { return ( $argument['name'] ?? '' ) !== $name; } ); // Re-index array. $this->arguments = array_values( $this->arguments ); } /** * Get an argument by name. * * @param string $name The argument name. * * @return array|null The argument if found, null otherwise. */ public function get_argument( string $name ): ?array { foreach ( $this->arguments as $argument ) { if ( ( $argument['name'] ?? '' ) === $name ) { return $argument; } } return null; } /** * Check if an argument exists. * * @param string $name The argument name. * * @return bool True if argument exists, false otherwise. */ public function has_argument( string $name ): bool { return $this->get_argument( $name ) !== null; } /** * Add an annotation. * * @param string $key The annotation key. * @param mixed $value The annotation value. * * @return void */ public function add_annotation( string $key, $value ): void { $this->annotations[ $key ] = $value; } /** * Remove an annotation. * * @param string $key The annotation key to remove. * * @return void */ public function remove_annotation( string $key ): void { unset( $this->annotations[ $key ] ); } /** * Convert the prompt to an array representation according to MCP specification. * * @return array */ public function to_array(): array { $prompt_data = array( 'name' => $this->name, ); // Add optional fields only if they have values. if ( ! is_null( $this->title ) ) { $prompt_data['title'] = $this->title; } if ( ! is_null( $this->description ) ) { $prompt_data['description'] = $this->description; } if ( ! empty( $this->arguments ) ) { $prompt_data['arguments'] = $this->arguments; } if ( ! empty( $this->annotations ) ) { $prompt_data['annotations'] = $this->annotations; } return $prompt_data; } /** * Convert the prompt to JSON representation. * * @return string */ public function to_json(): string { $json = wp_json_encode( $this->to_array() ); return false !== $json ? $json : '{}'; } /** * Create an McpPrompt instance from an array. * * @param array $data Array containing prompt data. * @param \WP\MCP\Core\McpServer $mcp_server The MCP server instance. * * @return self|\WP_Error Returns a new McpPrompt instance or WP_Error if validation fails. */ public static function from_array( array $data, McpServer $mcp_server ) { $prompt = new self( $data['ability'] ?? '', $data['name'] ?? '', $data['title'] ?? null, $data['description'] ?? null, $data['arguments'] ?? array(), $data['annotations'] ?? array() ); $prompt->set_mcp_server( $mcp_server ); return $prompt->validate( "McpPrompt::from_array::{$data['name']}" ); } /** * Validate the prompt instance. * * @param string $context Optional context for error messages. * * @return self|\WP_Error Returns the validated prompt instance or WP_Error if validation fails. */ public function validate( string $context = '' ) { if ( ! $this->mcp_server->is_mcp_validation_enabled() ) { return $this; } $context_to_use = $context ?: "McpPrompt::{$this->name}"; $validation_result = McpPromptValidator::validate_prompt_instance( $this, $context_to_use ); if ( is_wp_error( $validation_result ) ) { return $validation_result; } return $this; } /** * Create a standard argument definition. * * @param string $name The argument name. * @param string|null $description Optional argument description. * @param bool $required Whether the argument is required. * * @return array The argument definition. */ public static function create_argument( string $name, ?string $description = null, bool $required = false ): array { $argument = array( 'name' => $name, ); if ( ! is_null( $description ) ) { $argument['description'] = $description; } if ( $required ) { $argument['required'] = true; } return $argument; } /** * Get the MCP server instance this tool belongs to. * * @return \WP\MCP\Core\McpServer */ public function get_mcp_server(): McpServer { return $this->mcp_server; } /** * Set the MCP server instance this tool belongs to. * * @param \WP\MCP\Core\McpServer $mcp_server The MCP server instance. * * @return void */ public function set_mcp_server( McpServer $mcp_server ): void { $this->mcp_server = $mcp_server; } /** * Check if this prompt is builder-based (has direct execution capability). * * @return bool True if this prompt can execute directly, false if it needs abilities. */ public function is_builder_based(): bool { return false; // Default: requires abilities } /** * Execute the prompt directly (for builder-based prompts). * * @param array $arguments The arguments passed to the prompt. * * @return array The prompt response. * @throws \Exception If this prompt is not builder-based. */ public function execute_direct( array $arguments ): array { throw new \Exception( 'This prompt does not support direct execution' ); } /** * Check permission directly (for builder-based prompts). * * @param array $arguments The arguments passed to the prompt. * * @return bool True if execution is allowed. * @throws \Exception If this prompt is not builder-based. */ public function check_permission_direct( array $arguments ): bool { throw new \Exception( 'This prompt does not support direct permission checking' ); } }
Save
Back