WordPress MCP

# WordPress MCP WP-CLI Commands This document describes the WP-CLI commands available for the WordPress MCP plugin. ## wp mcp validate-tools Validates all registered MCP tools or a specific tool by name using the enhanced `ValidateTool` utility class with multiple validation levels. ### Synopsis ``` wp mcp validate-tools [<tool_name>] [--level=<level>] [--format=<format>] [--errors-only] [--warnings-only] [--detailed] ``` ### Options **`[<tool_name>]`** The name of a specific tool to validate. If not provided, all tools will be validated. **`[--level=<level>]`** Validation level to use. Default: `extended` - `strict` - Validates only against official MCP specification (ignores WordPress-specific fields) - `extended` - Validates MCP compliance + WordPress extensions (default) - `permissive` - Same as extended but reports errors as warnings **`[--format=<format>]`** Output format. Default: `table` - `table` - Human-readable table format - `json` - JSON output - `yaml` - YAML output - `csv` - CSV output **`[--errors-only]`** Show only tools with validation errors. **`[--warnings-only]`** Show only tools with validation warnings. **`[--detailed]`** Show detailed validation messages for each tool. ### Examples #### Basic Usage ```bash # Validate all tools with default (extended) level wp mcp validate-tools # Validate all tools and show detailed information wp mcp validate-tools --detailed # Validate a specific tool wp mcp validate-tools create_post ``` #### Validation Levels ```bash # Strict MCP compliance only (ignores WordPress-specific fields) wp mcp validate-tools --level=strict # Extended validation (MCP + WordPress fields) - Default wp mcp validate-tools --level=extended # Permissive mode (warnings instead of errors) wp mcp validate-tools --level=permissive --detailed ``` #### Filtering and Formatting ```bash # Show only tools with errors in JSON format wp mcp validate-tools --errors-only --format=json # Show only tools with warnings wp mcp validate-tools --warnings-only # Get summary as CSV wp mcp validate-tools --format=csv ``` #### Specific Tool Validation ```bash # Validate specific tool with strict MCP compliance wp mcp validate-tools create_post --level=strict # Check a tool in permissive mode with details wp mcp validate-tools update_post --level=permissive --detailed ``` ### Output #### Table Format (Default) The command displays a validation summary followed by a table with the following columns: - **Status**: ✓ (valid) or ✗ (invalid) - **Name**: Tool name - **Type**: WordPress tool type (create, read, update, delete, action) - **Enabled**: Whether the tool is enabled - **REST**: Whether the tool has REST alias - **Errors**: Number of validation errors - **Warnings**: Number of validation warnings Example output: ``` Validating 15 tools with extended level... Validation Summary (Level: extended) Total Tools: 15 Valid: 12 Invalid: 3 Valid with Warnings: 2 Success Rate: 80.0% +--------+------------------+--------+---------+------+--------+----------+ | Status | Name | Type | Enabled | REST | Errors | Warnings | +--------+------------------+--------+---------+------+--------+----------+ | ✓ | create_post | create | Yes | Yes | 0 | 1 | | ✗ | invalid_tool | read | Yes | No | 2 | 0 | | ✓ | update_post | update | Yes | Yes | 0 | 0 | +--------+------------------+--------+---------+------+--------+----------+ ``` #### Detailed Output When using `--detailed`, the command shows specific error and warning messages: ``` Detailed Validation Results create_post Warnings: - Tool is disabled because REST API CRUD tools are enabled. invalid_tool Errors: - Tool description is required. - Input schema must be an object type. ``` #### Single Tool Output When validating a specific tool: ``` Tool: create_post Status: Valid Type: create Validation Level: extended Enabled: Yes Has REST Alias: Yes Warnings: - Tool is disabled because REST API CRUD tools are enabled. ``` ### Validation Levels Explained #### Strict Level (`--level=strict`) - Validates only against the official MCP specification - Ignores WordPress-specific fields (`type`, `rest_alias`, etc.) - Use when: Preparing tools for other MCP implementations - Strictest compliance checking #### Extended Level (`--level=extended`) - **Default** - Validates MCP compliance + WordPress extensions - Checks all MCP fields: `name`, `description`, `title`, `inputSchema`, `outputSchema`, `annotations` - Validates WordPress-specific fields: `type`, `rest_alias`, enablement flags - Allows additional custom fields - Use when: Standard WordPress MCP tool validation #### Permissive Level (`--level=permissive`) - Same validation rules as Extended - Reports validation issues as warnings instead of errors - Never fails with exit code 1 - Use when: Development, debugging, migration scenarios ### Enhanced MCP Field Validation The enhanced validator now checks these MCP specification fields: #### Core MCP Fields - **`name`** (required): 1-64 characters, alphanumeric + underscore/hyphen - **`description`** (required): Tool description text - **`title`** (optional): Under 200 characters - **`inputSchema`** (optional): JSON Schema for tool inputs - **`outputSchema`** (optional): JSON Schema for tool outputs - **`annotations`** (optional): Metadata with audience, priority, lastModified #### JSON Schema Validation Comprehensive validation of `inputSchema` and `outputSchema`: - Type constraints (string, number, integer, boolean, array, object, null) - String constraints (minLength, maxLength, pattern) - Numeric constraints (minimum, maximum, multipleOf) - Array constraints (minItems, maxItems, items) - Object constraints (properties, required, additionalProperties) #### Annotations Validation - **`audience`**: Array containing 'user' and/or 'assistant' - **`priority`**: Number between 0 and 1 - **`lastModified`**: Valid ISO 8601 timestamp ### Exit Codes - **0**: All validated tools are valid - **1**: One or more tools have validation errors (except in permissive mode) ### Prerequisites - WordPress MCP plugin must be active - WP-CLI must be installed and available - Tools must be registered via `rest_api_init` action ### Error Handling The command handles various error scenarios: - **Plugin not active**: Exits with error message - **Tool not found**: Exits with specific tool name in error - **Invalid validation level**: Lists valid options - **No tools available**: Shows warning message - **Schema validation issues**: Reports as warnings, continues validation ### Troubleshooting #### "WordPress MCP plugin is not active or properly configured" - Ensure the plugin is activated - Check that the WpMcp class is loaded #### "Tool 'toolname' not found" - Run `wp mcp validate-tools` to see all available tools - Check tool name spelling and case sensitivity #### Schema validation warnings - Schema validation failures are reported as warnings - Does not affect tool validation result - Usually indicates missing schema files or JSON decode errors ### Programmatic Usage The validation functionality is also available as a utility class for use in other parts of the plugin: ```php use Automattic\WordpressMcp\Utils\ValidateTool; use Automattic\WordpressMcp\Utils\SchemaValidator; // Validate single tool with different levels $tool = ['name' => 'my_tool', 'description' => 'My custom tool']; $strict_result = ValidateTool::validate_mcp_strict($tool); $extended_result = ValidateTool::validate_wordpress_extended($tool); $permissive_result = ValidateTool::validate_permissive($tool); // Validate multiple tools $tools = [$tool1, $tool2, $tool3]; $results = ValidateTool::validate_tools($tools, ValidateTool::LEVEL_EXTENDED); // Get validation summary $summary = ValidateTool::get_validation_summary($results); echo "Success rate: {$summary['success_rate']}%"; // Filter results $errors_only = ValidateTool::filter_errors_only($results); $warnings_only = ValidateTool::filter_warnings_only($results); // Check individual results if (ValidateTool::has_errors($result)) { $errors = ValidateTool::get_errors($result); foreach ($errors as $error) { error_log("Tool validation error: $error"); } } // Schema validation $mcp_validation = SchemaValidator::validate_mcp_tool($tool); $wp_validation = SchemaValidator::validate_wordpress_tool($tool); ``` ### Architecture The command uses a multi-layered validation architecture: #### ValidateTool Utility Class - **`validate_mcp_strict()`** - MCP specification only - **`validate_wordpress_extended()`** - MCP + WordPress fields - **`validate_permissive()`** - Non-breaking validation - **`validate_tools()`** - Batch validation with level support #### SchemaValidator Utility Class - **JSON Schema loading and caching** - **Comprehensive schema validation** - **MCP specification compliance checking** - **WordPress extension validation** #### Validation Levels - **Static constants** for validation levels - **Flexible error/warning reporting** based on level - **Schema integration** when available This separation allows the validation logic to be used in other contexts beyond just the WP-CLI command, such as: - Admin interfaces for tool management - Automated testing and quality assurance - Plugin activation/update hooks - Developer debugging and troubleshooting