PATH:
home
/
thebhoeo
/
.trash
/
backwpup
/
src
/
Abilities
/
MCP
<?php declare(strict_types=1); namespace WPMedia\BackWPup\Abilities\MCP; use WPMedia\BackWPup\Abilities\AbilitiesInterface; /** * DocsOverview Resource * * Provides documentation about the BackWPup MCP server. */ class DocsOverview implements AbilitiesInterface { /** * Ability ID */ private const ABILITY_ID = 'backwpup/docs-overview'; /** * Resource URI */ private const RESOURCE_URI = 'groupone-backwpup-plugin://docs/overview'; /** * Resource name */ private const RESOURCE_NAME = 'backwpup_docs_overview'; /** * Register the ability * * @return void */ public function register(): void { if ( ! function_exists( 'wp_register_ability' ) ) { return; } wp_register_ability( self::ABILITY_ID, [ 'label' => __( 'BackWPup Documentation Overview', 'backwpup' ), 'category' => 'backwpup-jobs', 'description' => __( 'Overview documentation for the BackWPup MCP server', 'backwpup' ), 'execute_callback' => [ $this, 'execute' ], 'permission_callback' => [ $this, 'check_permissions' ], 'meta' => [ // Backward-compat: mcp-adapter <0.5.0 (e.g. WooCommerce) expects the URI at the top level of meta. 'uri' => self::RESOURCE_URI, 'mcp' => [ 'public' => true, 'type' => 'resource', 'uri' => self::RESOURCE_URI, 'name' => 'BackWPup MCP Server Overview', 'mimeType' => 'text/markdown', ], ], ] ); } /** * Check if the current user has permission to execute this ability * * @return bool */ public function check_permissions(): bool { if ( current_user_can( 'backwpup' ) ) { return true; } do_action( 'backwpup_mcp_permission_denied', self::ABILITY_ID, self::RESOURCE_NAME, 'backwpup' ); return false; } /** * Execute the ability - return documentation content * * @param array $args Input arguments (unused for resources). * * @return string Markdown documentation content. */ public function execute( array $args = [] ): string { return $this->get_documentation_content(); } /** * Get the documentation content * * @return string */ private function get_documentation_content(): string { return <<<'MARKDOWN' # BackWPup MCP Server Overview ## Purpose The BackWPup MCP server enables AI assistants to manage WordPress backups proactively. Before performing any risky operation on the WordPress site, the AI should offer to create a backup. ## Available Tools ### 1. **backwpup_list_jobs** Lists all configured backup jobs with their destinations and schedules. **When to call:** - **Before any risky operation** (plugin updates, theme changes, core updates, database migrations) - To offer the user a choice of backup destinations - To check if backup jobs are properly configured **Example usage:** ``` User: Update WooCommerce to the latest version. AI: Let me check your backup configuration first... [calls backwpup_list_jobs] I can see you have: - Job #1: "Daily Backup" → Dropbox - Job #2: "Weekly Full Backup" → Amazon S3 Should I create a backup before updating? I recommend using the Dropbox job for quick recovery. ``` ### 2. **backwpup_get_backup_history** Returns recent backup history and whether a backup is currently running. **When to call:** - **Before triggering a new backup** to avoid duplicates - To inform the user of their backup status - After triggering a backup to confirm it started **Important:** ALWAYS call this before calling `backwpup_run_job` to prevent starting duplicate backups. ### 3. **backwpup_run_job** Triggers an immediate backup - either a specific job or the default "Backup Now". **Parameters:** - `job_id` (optional integer): Pass a job ID from `backwpup_list_jobs` to run a specific job with specific destinations (e.g., Dropbox, S3) - Omit `job_id` to trigger default "Backup Now" (files + database to local folder) **When to call:** - After the user confirms they want a backup - Before risky operations (with user consent) **Workflow:** 1. Call `backwpup_list_jobs` to show available jobs 2. Call `backwpup_get_backup_history` to check if a backup is already running 3. If no backup is running, call `backwpup_run_job` with optional `job_id` 4. Wait briefly, then call `backwpup_get_backup_history` again to confirm it started ### 4. **backwpup_cancel_job** Cancels/aborts a currently running backup job. **When to call:** - When a backup is stuck or taking too long - User explicitly requests to stop the backup - Need to start a different backup job urgently - Before shutdown/maintenance operations **Important:** Always call `backwpup_get_backup_history` first to verify a job is actually running before attempting to cancel. **Example usage:** ``` User: The backup is taking forever, can you stop it? AI: [calls backwpup_get_backup_history] Yes, there's a backup running. Let me cancel it for you. [calls backwpup_cancel_job] ✓ Job "Daily Backup" has been cancelled successfully. ``` **Workflow:** 1. Call `backwpup_get_backup_history` to confirm a job is running 2. If running, call `backwpup_cancel_job` 3. Wait briefly, then call `backwpup_get_backup_history` to confirm cancellation ### 5. **backwpup_get_backup_logs** Retrieves backup log content for troubleshooting and diagnosing backup failures. **Parameters:** - `backup_id` (optional integer): Specific backup ID - most precise way to get logs - `backup_file` (optional string): Backup filename (e.g., "backwpup_1_2024-04-23_10-30-00_ABC123.zip") - `job_id` (optional integer): Get latest log from this job - `lines` (optional integer): Number of log lines to return (default 200, max 1000) **When to call:** - User asks to see backup logs ("show me the latest backup log") - Diagnosing failed backups ("why did the backup fail?") - Troubleshooting errors or warnings - After a backup completes with errors **Important:** Parameters are prioritized: `backup_id` > `backup_file` > `job_id` > latest overall. Omit all to get the most recent log. **Example usage:** ``` User: Can I see the log of the latest backup? AI: [calls backwpup_get_backup_logs with no parameters] Here's the log from your latest backup (Daily Backup, ran 2 hours ago): [Shows truncated log content] Status: Completed with 2 warnings Runtime: 45 seconds User: Show me the log for backup #4 AI: [calls backwpup_get_backup_history to get backup list] [finds backup_id for backup #4] [calls backwpup_get_backup_logs with backup_id] Here's the log for that backup... ``` **Return data includes:** - Log content (plain text, HTML stripped) - Metadata: job name, timestamp, errors/warnings count, runtime - Truncation info if log exceeds requested lines **Workflow:** 1. Call `backwpup_get_backup_history` to see recent backups 2. Use `backup_id` from history to call `backwpup_get_backup_logs` 3. Analyze errors/warnings in the log content 4. Suggest solutions based on common error patterns ## Proactive Backup Suggestions The AI assistant should **proactively suggest backups** in these scenarios: ### Critical Operations (ALWAYS suggest backup): - **WordPress core updates** (minor or major) - **Plugin updates** (especially WooCommerce, security plugins, form builders) - **Theme updates** or theme switches - **Database operations** (migrations, large imports, bulk deletions) - **File system changes** (permission changes, .htaccess modifications) - **PHP version upgrades** ### Moderate Risk Operations (Suggest backup): - Installing new plugins - Modifying plugin/theme code files - Bulk content operations (mass deletes, imports) ### Conversation Flow Example: ``` User: Update WooCommerce to version 9.0.0 AI: Before updating WooCommerce, I strongly recommend creating a backup. [calls backwpup_list_jobs] You have a Dropbox backup job configured. Should I run it? User: Yes AI: [calls backwpup_get_backup_history to check] No backup currently running. [calls backwpup_run_job with Dropbox job ID] ✓ Backup started successfully! Now proceeding with WooCommerce update... ``` ## Best Practices 1. **Always check backup history before triggering** to avoid conflicts 2. **Offer specific job choices** when multiple destinations are available 3. **Confirm backup started** before proceeding with risky operations 4. **Explain why** a backup is recommended (builds user trust) 5. **Don't be pushy** - suggest, don't demand ## Error Handling - If backup is already running: Offer to cancel it with `backwpup_cancel_job` or wait - If no jobs configured: Suggest setting up backup jobs - If backup fails to start: Warn user before proceeding with risky operation - If trying to cancel when no job is running: Inform user no backup is active - If backup completes with errors/warnings: Use `backwpup_get_backup_logs` to diagnose the issue ## Security - All tools require `backwpup` WordPress capability - Log viewing requires `backwpup_logs` capability - Unauthorized requests return permission errors - Job IDs are validated before execution --- **Remember:** The goal is to make backups a natural part of the workflow, protecting users from disasters without adding friction. MARKDOWN; } }
[-] DocsOverview.php
[edit]
[+]
..