Developer Documentation

Question

Accepted Answer

MCP Integration Guide VM Advanced WooCommerce Sales includes native support for the Model Context Protocol (MCP), allowing MCP clients to interact with the plugin programmatically. What is MCP? The Model Context Protocol (MCP) is a protocol for connecting AI assistants and other tools to external data sources and capabilities. Our plugin exposes its functionality through MCP-compatible REST API endpoints. Enabling MCP MCP integration is automatically enabled when the plugin is activated. The MCP server registers REST API endpoints at: /wp-json/vm-woo-advanced-sales/v1/ Authentication All MCP endpoints require: WordPress authentication (logged-in user) manage_woocommerce capability Available Endpoints List All Sales GET /wp-json/vm-woo-advanced-sales/v1/sales Returns an array of all storewide sales. Response: [   {     "id": 1,     "title": "Summer Sale",     "enabled": true,     "amount": 15,     "type": "percentage",     "priority": 1,     ...   } ] Get Single Sale GET /wp-json/vm-woo-advanced-sales/v1/sales/{id} Returns details for a specific sale. Create Sale POST /wp-json/vm-woo-advanced-sales/v1/sales Content-Type: application/json {   "title": "New Sale",   "enabled": true,   "amount": 20,   "type": "percentage",   "start_date": "2024-06-01 00:00:00",   "end_date": "2024-06-30 23:59:59",   "include_categories": [5, 10],   ... } Update Sale PUT /wp-json/vm-woo-advanced-sales/v1/sales/{id} Content-Type: application/json {   "amount": 25,   "enabled": false,   ... } Delete Sale DELETE /wp-json/vm-woo-advanced-sales/v1/sales/{id} Update Priority POST /wp-json/vm-woo-advanced-sales/v1/sales/priority Content-Type: application/json {   "sale_ids": [3, 1, 2] } Reorders sales - first ID gets priority 1, second gets priority 2, etc. Get License Status GET /wp-json/vm-woo-advanced-sales/v1/license/status Returns current license information. Response Format All endpoints return standard WordPress REST API responses: Success: {   "id": 1,   "title": "Sale Name",   ... } Error: {     "code": "not_found",     "message": "Sale not found.",     "data": {         "status": 404     } } Field Reference See API Reference for complete field documentation. Usage Examples Create a Sale via cURL curl -X POST \   https://yoursite.com/wp-json/vm-woo-advanced-sales/v1/sales \   -H 'Content-Type: application/json' \   -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \   -d '{     "title": "Black Friday",     "enabled": true,     "amount": 30,     "type": "percentage"   }' List Sales via JavaScript fetch('/wp-json/vm-woo-advanced-sales/v1/sales', {     headers: {         'X-WP-Nonce': wpApiSettings.nonce,     }, })     .then(response => response.json())     .then(sales => console.log(sales)); MCP Tools Reference For detailed information about available MCP tools, see MCP Tools Reference. Developer Guide For developers extending MCP functionality, see Developer MCP Guide. MCP Tools Reference Complete reference for all MCP tools available in VM Advanced WooCommerce Sales. Overview MCP tools allow MCP clients to interact with storewide sales programmatically. All tools require authentication and the manage_woocommerce capability. Tools list_sales List all storewide sales. Endpoint: GET /wp-json/vm-woo-advanced-sales/v1/sales Description: Returns an array of all storewide sales ordered by priority. Parameters: None Response: Array of sale objects Example: const sales = await mcp.call('list_sales'); get_sale Get details of a specific sale. Endpoint: GET /wp-json/vm-woo-advanced-sales/v1/sales/{id} Description: Returns detailed information about a single sale. Parameters: id (integer, required): Sale post ID Response: Sale object Example: const sale = await mcp.call('get_sale', { id: 1 }); create_sale Create a new storewide sale. Endpoint: POST /wp-json/vm-woo-advanced-sales/v1/sales Description: Creates a new storewide sale with the provided data. Parameters: title (string, required): Sale name enabled (boolean): Whether sale is enabled override_mode (string): Override mode amount (float): Discount amount type (string): "percentage" or "fixed" start_date (string): Start date (YYYY-MM-DD HH:MM:SS) end_date (string): End date priority (integer): Priority number include_products (array): Array of product IDs exclude_products (array): Array of product IDs include_categories (array): Array of category IDs exclude_categories (array): Array of category IDs include_tags (array): Array of tag IDs exclude_tags (array): Array of tag IDs role_restrictions (array): Array of role slugs Response: Created sale object Example: const sale = await mcp.call('create_sale', {   title: 'Summer Sale',   enabled: true,   amount: 20,   type: 'percentage',   include_categories: [5, 10] }); update_sale Update an existing sale. Endpoint: PUT /wp-json/vm-woo-advanced-sales/v1/sales/{id} Description: Updates sale with provided data. Only include fields to update. Parameters: Same as create_sale, plus: id (integer, required): Sale post ID Response: Updated sale object Example: const sale = await mcp.call('update_sale', {   id: 1,   amount: 25,   enabled: false }); delete_sale Delete a sale. Endpoint: DELETE /wp-json/vm-woo-advanced-sales/v1/sales/{id} Description: Permanently deletes a sale. Parameters: id (integer, required): Sale post ID Response: Success confirmation Example: await mcp.call('delete_sale', { id: 1 }); update_priority Update sale priorities. Endpoint: POST /wp-json/vm-woo-advanced-sales/v1/sales/priority Description: Reorders sales by priority. First ID gets priority 1, second gets 2, etc. Parameters: sale_ids (array, required): Array of sale IDs in desired order Response: Object mapping sale IDs to new priorities Example: const result = await mcp.call('update_priority', {   sale_ids: [3, 1, 2] }); // Result: { "3": 1, "1": 2, "2": 3 } get_license_status Get license information. Endpoint: GET /wp-json/vm-woo-advanced-sales/v1/license/status Description: Returns current license status and data. Parameters: None Response: License status object Example: const license = await mcp.call('get_license_status'); // Returns: { status: 'valid', valid: true, data: {...} } Data Structures Sale Object interface Sale {   id: number;   title: string;   enabled: boolean;   override_mode: 'do_not_override' | 'apply_both' | 'override';   amount: number;   type: 'percentage' | 'fixed';   start_date: string | null;   end_date: string | null;   priority: number;   include_products: number[];   exclude_products: number[];   include_categories: number[];   exclude_categories: number[];   include_tags: number[];   exclude_tags: number[];   role_restrictions: string[];   date_created: string;   date_modified: string; } License Status Object interface LicenseStatus {   status: 'valid' | 'invalid' | 'expired' | 'revoked' | 'error';   valid: boolean;   data: {     expires?: string;     activations_left?: number;     [key: string]: any;   }; } Error Handling All tools return standard WordPress REST API error responses on failure: interface ErrorResponse {   code: string;   message: string;   data: {     status: number;   }; } Usage Examples Create a Sale for Specific Products const sale = await mcp.call('create_sale', {   title: 'Product Bundle Sale',   enabled: true,   amount: 15,   type: 'percentage',   include_products: [10, 20, 30],   override_mode: 'override' }); Temporarily Disable All Sales const sales = await mcp.call('list_sales'); for (const sale of sales) {   await mcp.call('update_sale', {     id: sale.id,     enabled: false   }); } Reorder Sales by Date const sales = await mcp.call('list_sales'); // Sort by start date sales.sort((a, b) => new Date(a.start_date) - new Date(b.start_date)); // Update priorities await mcp.call('update_priority', {   sale_ids: sales.map(s => s.id) }); Authentication MCP tools require: WordPress user authentication manage_woocommerce capability Valid nonce (for AJAX requests) See MCP Integration Guide for authentication details. API Reference Complete reference for the VM Advanced WooCommerce Sales REST API and internal APIs. REST API Endpoints Base URL: /wp-json/vm-woo-advanced-sales/v1/ Authentication All endpoints require: WordPress user authentication manage_woocommerce capability Sales Endpoints List Sales GET /wp-json/vm-woo-advanced-sales/v1/sales Returns all storewide sales. Response: [   {     "id": 1,     "title": "Summer Sale",     "enabled": true,     "override_mode": "override",     "amount": "15.00",     "type": "percentage",     "start_date": "2024-06-01 00:00:00",     "end_date": "2024-06-30 23:59:59",     "priority": 1,     "include_products": [],     "exclude_products": [],     "include_categories": [5],     "exclude_categories": [],     "include_tags": [],     "exclude_tags": [],     "role_restrictions": [],     "date_created": "2024-05-15 10:30:00",     "date_modified": "2024-05-20 14:20:00"   } ] Get Sale GET /wp-json/vm-woo-advanced-sales/v1/sales/{id} Returns a single sale by ID. Parameters: id (required): Sale post ID Response: Single sale object (same format as list) Error Response (404): {   "code": "not_found",   "message": "Sale not found.",   "data": {     "status": 404   } } Create Sale POST /wp-json/vm-woo-advanced-sales/v1/sales Content-Type: application/json Creates a new storewide sale. Request Body: {   "title": "New Sale",   "enabled": true,   "override_mode": "override",   "amount": 20,   "type": "percentage",   "start_date": "2024-06-01 00:00:00",   "end_date": "2024-06-30 23:59:59",   "priority": 1,   "include_products": [10, 20],   "exclude_products": [5],   "include_categories": [3, 7],   "exclude_categories": [],   "include_tags": [2],   "exclude_tags": [],   "role_restrictions": ["customer"] } Fields: title (string, required): Sale name enabled (boolean): Whether sale is enabled (default: true) override_mode (string): "do_not_override", "apply_both", or "override" (default: "do_not_override") amount (float): Discount amount type (string): "percentage" or "fixed" start_date (string): Start date in MySQL format (YYYY-MM-DD HH:MM:SS) end_date (string): End date in MySQL format priority (integer): Priority number (lower = higher priority) include_products (array): Array of product IDs exclude_products (array): Array of product IDs include_categories (array): Array of category term IDs exclude_categories (array): Array of category term IDs include_tags (array): Array of tag term IDs exclude_tags (array): Array of tag term IDs role_restrictions (array): Array of WordPress role slugs Response: Created sale object (201 status) Update Sale PUT /wp-json/vm-woo-advanced-sales/v1/sales/{id} Content-Type: application/json Updates an existing sale. Same request body format as Create Sale. Response: Updated sale object (200 status) Delete Sale DELETE /wp-json/vm-woo-advanced-sales/v1/sales/{id} Deletes a sale. Response (200): {   "deleted": true } Update Priority POST /wp-json/vm-woo-advanced-sales/v1/sales/priority Content-Type: application/json Updates sale priorities based on order. Request Body: {   "sale_ids": [3, 1, 2] } First ID gets priority 1, second gets priority 2, etc. Response (200): {   "updated": {     "3": 1,     "1": 2,     "2": 3   } } License Endpoints Get License Status GET /wp-json/vm-woo-advanced-sales/v1/license/status Returns current license information. Response: {   "status": "valid",   "valid": true,   "data": {     "expires": "2025-12-31",     "activations_left": 2   } } Internal PHP API Classes VM_Woo_Advanced_Sales_License License management class. Methods: get_license_key(): Get stored license key get_license_status(): Get license status is_license_valid(): Check if license is valid activate_license( $key ): Activate license deactivate_license(): Deactivate license validate_license( $force = false ): Validate license Example: if ( VM_Woo_Advanced_Sales_License::is_license_valid() ) {     // License is valid } VM_Woo_Advanced_Sales_Price_Handler Price handling class. Methods: clear_cache(): Clear sale cache Example: // Clear cache after manual changes VM_Woo_Advanced_Sales_Price_Handler::clear_cache(); VM_Woo_Advanced_Sales_Restrictions Restriction checking class. Methods: sale_matches_restrictions( $sale_id, $product_id, $user_id = 0, $sale_meta = null ): Check if sale matches restrictions Example: if ( VM_Woo_Advanced_Sales_Restrictions::sale_matches_restrictions( $sale_id, $product_id, $user_id ) ) {     // Sale applies to this product/user combination } Error Codes not_found: Resource not found (404) invalid_data: Invalid request data (400) create_failed: Creation failed (500) delete_failed: Deletion failed (500) permission_denied: Insufficient permissions (403) Rate Limiting No rate limiting is currently enforced. Implement appropriate limits in production. Versioning Current API version: v1 Future versions will maintain backward compatibility when possible. Hooks and Filters Reference VM Advanced WooCommerce Sales provides several hooks and filters for developers to extend functionality. Filters vm_woo_advanced_sales_applicable_sale Filter the applicable sale for a product before price calculation. add_filter( 'vm_woo_advanced_sales_applicable_sale', function( $sale, $product, $user_id ) {     // Modify $sale or return null to skip storewide sale     return $sale; }, 10, 3 ); Parameters: $sale (WP_Post|null): The sale post object or null $product (WC_Product): The product object $user_id (int): Current user ID (0 for guests) Return: WP_Post object or null vm_woo_advanced_sales_calculated_price Filter the calculated sale price. add_filter( 'vm_woo_advanced_sales_calculated_price', function( $price, $regular_price, $sale, $product ) {     // Modify the calculated price     return $price; }, 10, 4 ); Parameters: $price (float): Calculated sale price $regular_price (float): Original regular price $sale (WP_Post): Sale post object $product (WC_Product): Product object Return: float (modified price) vm_woo_advanced_sales_active_sales Filter the list of active sales before processing. add_filter( 'vm_woo_advanced_sales_active_sales', function( $sales, $args ) {     // Modify $sales array    return $sales; }, 10, 2 ); Parameters: $sales (array): Array of WP_Post objects $args (array): Query arguments Return: array of WP_Post objects vm_woo_advanced_sales_restriction_check Filter restriction check results. add_filter( 'vm_woo_advanced_sales_restriction_check', function( $matches, $sale_id, $product_id, $user_id ) {     // Override restriction check     return $matches; // true or false }, 10, 4 ); Parameters: $matches (bool): Whether restrictions match $sale_id (int): Sale post ID $product_id (int): Product ID $user_id (int): User ID Return: bool Actions vm_woo_advanced_sales_before_price_calculation Fires before calculating sale price. add_action( 'vm_woo_advanced_sales_before_price_calculation', function( $product, $sale ) {     // Do something before price calculation }, 10, 2 ); Parameters: $product (WC_Product): Product object $sale (WP_Post): Sale post object vm_woo_advanced_sales_after_price_calculation Fires after calculating sale price. add_action( 'vm_woo_advanced_sales_after_price_calculation', function( $product, $sale, $final_price ) {     // Do something after price calculation }, 10, 3 ); Parameters: $product (WC_Product): Product object $sale (WP_Post): Sale post object $final_price (float): Final calculated price vm_woo_advanced_sales_sale_created Fires when a sale is created. add_action( 'vm_woo_advanced_sales_sale_created', function( $sale_id, $sale_data ) {     // Do something when sale is created }, 10, 2 ); Parameters: $sale_id (int): New sale post ID $sale_data (array): Sale data array vm_woo_advanced_sales_sale_updated Fires when a sale is updated. add_action( 'vm_woo_advanced_sales_sale_updated', function( $sale_id, $sale_data ) {     // Do something when sale is updated }, 10, 2 ); Parameters: $sale_id (int): Updated sale post ID $sale_data (array): Updated sale data array vm_woo_advanced_sales_sale_deleted Fires when a sale is deleted. add_action( 'vm_woo_advanced_sales_sale_deleted', function( $sale_id ) {     // Do something when sale is deleted }, 10, 1 ); Parameters: $sale_id (int): Deleted sale post ID vm_woo_advanced_sales_priority_updated Fires when sale priorities are updated. add_action( 'vm_woo_advanced_sales_priority_updated', function( $sale_ids, $priorities ) {     // Do something when priorities change }, 10, 2 ); Parameters: $sale_ids (array): Array of sale IDs $priorities (array): Array of new priorities (sale_id => priority) vm_woo_advanced_sales_cache_cleared Fires when the sale cache is cleared. add_action( 'vm_woo_advanced_sales_cache_cleared', function() {     // Do something when cache is cleared }, 10, 0 ); Example Usage Add Custom Discount Logic add_filter( 'vm_woo_advanced_sales_calculated_price', function( $price, $regular_price, $sale, $product ) {     // Add $5 discount on top of existing sale for VIP customers     if ( user_has_role( 'vip_customer' ) ) {         $price = max( 0, $price - 5 );     }     return $price; }, 10, 4 ); Log Sale Applications add_action( 'vm_woo_advanced_sales_after_price_calculation', function( $product, $sale, $final_price ) {     error_log( sprintf(          'Sale %d applied to product %d: %s -> %s',         $sale->ID,         $product->get_id(),         $product->get_regular_price(),         $final_price     ) ); }, 10, 3 ); Prevent Sale for Specific Products add_filter( 'vm_woo_advanced_sales_applicable_sale', function( $sale, $product, $user_id ) {     // Never apply sales to products with specific meta     if ( $product->get_meta( 'no_storewide_sales' ) === 'yes' ) {         return null;     }     return $sale; }, 10, 3 ); Best Practices Always return expected types: Filters must return the correct data type Check for null: Sale may be null if no sale applies Performance: Keep hook callbacks efficient Documentation: Document custom hooks in your code Testing: Test hooks thoroughly before production use Deprecated Hooks None currently. Future deprecations will be announced in changelog. Developer Guide: Extending MCP Support This guide is for developers who want to extend or customize the MCP integration in VM Advanced WooCommerce Sales. Architecture The MCP integration consists of two main classes: VM_Woo_Advanced_Sales_MCP: Registers REST API routes and handles authentication VM_Woo_Advanced_Sales_MCP_Tools: Implements the actual tool handlers Adding Custom MCP Tools Step 1: Register the Route In VM_Woo_Advanced_Sales_MCP::register_mcp_routes(): register_rest_route(     'vm-woo-advanced-sales/v1',     '/custom-endpoint',     array(         'methods'             => 'GET',         'callback'            => array( 'VM_Woo_Advanced_Sales_MCP_Tools', 'custom_tool' ),         'permission_callback' => array( 'VM_Woo_Advanced_Sales_MCP', 'check_permissions' ),     ) ); Step 2: Implement the Tool Handler In VM_Woo_Advanced_Sales_MCP_Tools: public static function custom_tool( $request ) {     // Get parameters     $param = $request->get_param( 'param_name' );     // Perform action     $result = do_something( $param );     // Return response     return new WP_REST_Response( $result, 200 ); } Step 3: Handle Errors Return WP_Error for failures: if ( ! $result ) {     return new WP_Error(         'error_code',         __( 'Error message.', 'vm-woo-advanced-sales' ),         array( 'status' => 400 )     ); } Extending Existing Tools Filter Tool Responses Use filters to modify tool responses: add_filter( 'rest_prepare_vm_storewide_sale', function( $response, $post, $request ) {     $data = $response->get_data();     $data['custom_field'] = get_post_meta( $post->ID, '_custom_field', true );     $response->set_data( $data );     return $response; }, 10, 3 ); Override Tool Behavior Replace tool handlers using filters or by extending the class: class Custom_MCP_Tools extends VM_Woo_Advanced_Sales_MCP_Tools {     public static function create_sale( $request ) {         // Custom implementation         // Call parent for default behavior         $response = parent::create_sale( $request );         // Modify response         return $response;     } } Custom Authentication Override permission checking: add_filter( 'vm_woo_advanced_sales_mcp_permissions', function( $has_permission, $request ) {     // Custom permission logic     return $has_permission && custom_check(); }, 10, 2 ); Error Handling Best Practices Use Appropriate HTTP Status Codes: 200: Success 201: Created 400: Bad Request 403: Forbidden 404: Not Found 500: Server Error Provide Helpful Error Messages: return new WP_Error(  'invalid_data',  __( 'Please provide a valid sale amount between 0 and 100.', 'vm-woo-advanced-sales' ),  array( 'status' => 400 ) ); Include Error Data: return new WP_Error(  'validation_failed',  __( 'Validation failed.', 'vm-woo-advanced-sales' ),  array(      'status' => 400,      'errors' => $validation_errors  ) ); Testing MCP Tools Manual Testing with cURL # List sales curl -X GET \   'https://yoursite.com/wp-json/vm-woo-advanced-sales/v1/sales' \   -H 'Authorization: Bearer YOUR_TOKEN' # Create sale curl -X POST \   'https://yoursite.com/wp-json/vm-woo-advanced-sales/v1/sales' \   -H 'Content-Type: application/json' \   -H 'Authorization: Bearer YOUR_TOKEN' \   -d '{"title":"Test Sale","amount":10,"type":"percentage"}' Unit Testing class Test_MCP_Tools extends WP_UnitTestCase {     public function test_list_sales() {         $request = new WP_REST_Request( 'GET', '/vm-woo-advanced-sales/v1/sales' );         $response = VM_Woo_Advanced_Sales_MCP_Tools::list_sales( $request );         $this->assertInstanceOf( 'WP_REST_Response', $response );         $this->assertEquals( 200, $response->get_status() );     } } Performance Considerations Cache Responses When Appropriate: Use WordPress object cache for expensive operations Limit Response Size: Use pagination for large datasets Optimize Queries: Use efficient database queries Batch Operations: Support bulk operations when possible Security Considerations Always Validate Input: Sanitize and validate all input data Check Permissions: Verify user capabilities Use Nonces: Implement nonce verification for state-changing operations Rate Limiting: Consider implementing rate limiting for production Data Sanitization: Escape all output Hooks for MCP Integration vm_woo_advanced_sales_mcp_tool_response Filter MCP tool responses before sending: add_filter( 'vm_woo_advanced_sales_mcp_tool_response', function( $response, $tool_name, $request ) {     // Modify response     return $response; }, 10, 3 ); vm_woo_advanced_sales_mcp_tool_error Filter error responses: add_filter( 'vm_woo_advanced_sales_mcp_tool_error', function( $error, $tool_name, $request ) {     // Log or modify error     return $error; }, 10, 3 ); Best Practices Follow REST API Standards: Use proper HTTP methods and status codes Document Your Tools: Add PHPDoc comments explaining parameters and responses Version Your API: Consider versioning for breaking changes Test Thoroughly: Test all edge cases and error conditions Keep It Simple: Don't overcomplicate tool implementations Example: Custom Reporting Tool class Custom_MCP_Tools extends VM_Woo_Advanced_Sales_MCP_Tools {     public static function get_sale_stats( $request ) {         $sale_id = absint( $request['id'] );         // Get stats         $stats = array(             'applications' => get_sale_application_count( $sale_id ),             'total_discount' => get_total_discount_applied( $sale_id ),             'affected_products' => get_affected_product_count( $sale_id ),         );         return new WP_REST_Response( $stats, 200 );     } } Register in MCP class: register_rest_route(     'vm-woo-advanced-sales/v1',     '/sales/(?P<id>\d+)/stats',     array(         'methods'             => 'GET',         'callback'            => array( 'Custom_MCP_Tools', 'get_sale_stats' ),         'permission_callback' => array( 'VM_Woo_Advanced_Sales_MCP', 'check_permissions' ),     ) ); Resources WordPress REST API Handbook MCP Protocol Documentation WooCommerce REST API Guide