mcp-wordpress 2.3.0 → 2.4.0

package/docs/examples/use-case-workflows.md

@@ -0,0 +1,469 @@
+# Real-World Use Case Workflows
+
+Comprehensive examples of how different types of users can leverage MCP WordPress for their specific needs.
+
+## Content Creator Workflows
+
+### Daily Content Creation Routine
+
+**Morning Content Planning**
+
+```text
+💬 "Analyze my WordPress analytics from last week and suggest 3 trending topics for new blog posts"
+
+💬 "Create a content calendar for the next two weeks based on seasonal trends and my top-performing content categories"
+
+💬 "List all draft posts and prioritize them based on SEO potential and trending keywords"
+```
+
+**Content Production**
+
+```text
+💬 "Create a comprehensive blog post about 'Remote Work Productivity Tips' with:
+    - 2000+ words
+    - SEO-optimized title and meta description  
+    - Proper heading structure (H1, H2, H3)
+    - Focus keyword: 'remote work productivity'
+    - Include call-to-action for newsletter signup"
+
+💬 "Upload these 5 product images and create an optimized gallery with alt text and captions"
+
+💬 "Generate social media snippets from my latest blog post for Twitter, LinkedIn, and Facebook"
+```
+
+**Content Optimization**
+
+```text
+💬 "Review all posts from the last month and update any with broken internal links"
+
+💬 "Find all posts with missing featured images and suggest relevant stock photos"
+
+💬 "Optimize my top 10 posts for better SEO by improving meta descriptions and adding internal links"
+```
+
+**Performance Review**
+
+```text
+💬 "Show me performance metrics for all posts published this month"
+
+💬 "Identify my top 5 performing posts and create similar content ideas"
+
+💬 "Generate a weekly performance report with engagement metrics and optimization recommendations"
+```
+
+## E-commerce Site Management
+
+### Product Launch Workflow
+
+**Pre-Launch Preparation**
+
+```text
+💬 "Create a product launch landing page for the new iPhone 15 case with:
+    - Product specifications and features
+    - High-quality image gallery
+    - Pricing and availability information
+    - Pre-order form integration"
+
+💬 "Set up product category 'Mobile Accessories' and add relevant tags"
+
+💬 "Create an email campaign announcement page with signup form"
+```
+
+**Launch Day Execution**
+
+```text
+💬 "Publish the iPhone 15 case product page and announce it on all social media channels"
+
+💬 "Create a limited-time promotion page with countdown timer and special pricing"
+
+💬 "Monitor and respond to customer questions in the comments section"
+```
+
+**Post-Launch Management**
+
+```text
+💬 "Update inventory status for all iPhone cases and mark out-of-stock items"
+
+💬 "Create customer testimonial posts from recent reviews"
+
+💬 "Generate sales performance report for the first week after launch"
+```
+
+### Seasonal Campaign Management
+
+**Holiday Preparation**
+
+```text
+💬 "Create a Black Friday landing page with:
+    - Featured product showcase
+    - Countdown timer to sale start
+    - Special discount codes
+    - Gift guide categories"
+
+💬 "Update all product pages with holiday-themed descriptions and gift suggestions"
+
+💬 "Create holiday shipping information page with cutoff dates and delivery options"
+```
+
+**Inventory Management**
+
+```text
+💬 "Generate a report of all products that are low in stock (less than 10 units)"
+
+💬 "Create restock notification signup forms for popular out-of-stock items"
+
+💬 "Update all product pages to show estimated restock dates"
+```
+
+## News Website Operations
+
+### Breaking News Workflow
+
+**Rapid Content Publishing**
+
+```text
+💬 "Create a breaking news post about the tech merger announcement with:
+    - SEO-optimized headline
+    - Key facts and timeline
+    - Related article links
+    - Social media integration"
+
+💬 "Add breaking news banner to homepage and category pages"
+
+💬 "Create follow-up article outline based on developing story angles"
+```
+
+**Story Development**
+
+```text
+💬 "Research and create background articles related to today's breaking news"
+
+💬 "Update the main story with new developments and quotes from press conference"
+
+💬 "Create an analysis piece connecting this news to broader industry trends"
+```
+
+**Content Moderation**
+
+```text
+💬 "Review all comments on controversial articles from today and approve legitimate discussion while flagging inappropriate content"
+
+💬 "Create community guidelines reminder post for highly engaged articles"
+
+💬 "Moderate reader submissions and feature the best user-generated content"
+```
+
+### Editorial Calendar Management
+
+**Weekly Planning**
+
+```text
+💬 "Create editorial calendar for next week with:
+    - 5 main news articles
+    - 2 opinion pieces  
+    - 3 feature stories
+    - Daily news roundups"
+
+💬 "Assign categories and tags to planned articles for better organization"
+
+💬 "Schedule social media promotion posts for each planned article"
+```
+
+**Content Gap Analysis**
+
+```text
+💬 "Analyze our coverage compared to competing news sites and identify missing story angles"
+
+💬 "Review trending topics in our industry and suggest 3 urgent articles to publish"
+
+💬 "Find evergreen content opportunities that can drive consistent traffic"
+```
+
+## Agency Client Management
+
+### Multi-Client Campaign Coordination
+
+**Client Onboarding**
+
+```text
+💬 "Create a new client website section for Law Firm XYZ with:
+    - Practice area pages (Personal Injury, Family Law, Criminal Defense)
+    - Attorney profile pages with photos and credentials
+    - Client testimonial showcase
+    - Contact and consultation booking forms"
+
+💬 "Set up content categories specific to legal topics and local SEO"
+
+💬 "Create editorial calendar focused on legal advice and local community involvement"
+```
+
+**Monthly Reporting**
+
+```text
+💬 "Generate performance reports for all 5 agency clients showing:
+    - Website traffic growth
+    - Content engagement metrics
+    - Lead generation performance
+    - SEO ranking improvements"
+
+💬 "Create client-specific improvement recommendations based on performance data"
+
+💬 "Schedule quarterly strategy review meetings and prepare agenda items"
+```
+
+**Bulk Content Operations**
+
+```text
+💬 "Update privacy policies across all client sites to comply with new regulations"
+
+💬 "Add holiday closure notices to all restaurant client websites"
+
+💬 "Create coronavirus safety protocol pages for all healthcare practice clients"
+```
+
+### Campaign Management
+
+**Seasonal Campaigns**
+
+```text
+💬 "Launch summer promotion campaigns for all retail clients with:
+    - Seasonal landing pages
+    - Special offer showcases
+    - Email signup incentives
+    - Social media integration"
+
+💬 "Create back-to-school content for educational clients including:
+    - Course enrollment pages
+    - Academic calendar updates
+    - Student resource guides"
+```
+
+## Educational Institution Management
+
+### Course and Program Management
+
+**Semester Preparation**
+
+```text
+💬 "Create course catalog pages for Fall 2024 semester with:
+    - Course descriptions and prerequisites
+    - Faculty information and credentials
+    - Enrollment deadlines and procedures
+    - Tuition and fee information"
+
+💬 "Update academic calendar with important dates and deadlines"
+
+💬 "Create student orientation information pages and FAQ sections"
+```
+
+**Student Engagement**
+
+```text
+💬 "Create weekly newsletter content highlighting:
+    - Upcoming campus events
+    - Academic deadlines and important dates
+    - Student achievement spotlights
+    - Faculty research news"
+
+💬 "Moderate student discussion forums and highlight valuable contributions"
+
+💬 "Create study resource pages for final exam period"
+```
+
+**Alumni Relations**
+
+```text
+💬 "Create alumni success story features from recent graduate achievements"
+
+💬 "Set up reunion event pages with registration and information"
+
+💬 "Generate annual giving campaign pages with donation tracking"
+```
+
+### Research and Publications
+
+**Faculty Research Showcase**
+
+```text
+💬 "Create research spotlight pages featuring:
+    - Faculty research projects and findings
+    - Publication listings and abstracts
+    - Grant funding acknowledgments
+    - Collaboration opportunities"
+
+💬 "Update faculty profile pages with latest publications and achievements"
+
+💬 "Create research news section highlighting breakthrough discoveries"
+```
+
+## Healthcare Practice Management
+
+### Patient Information and Education
+
+**Health Education Content**
+
+```text
+💬 "Create patient education pages about common conditions with:
+    - Symptoms and causes explanations
+    - Treatment options and procedures
+    - Prevention and self-care tips
+    - When to seek medical attention guidelines"
+
+💬 "Develop seasonal health tips (flu prevention, allergy management, sun safety)"
+
+💬 "Create FAQ sections addressing common patient concerns"
+```
+
+**Practice Management**
+
+```text
+💬 "Update doctor availability schedules and appointment booking information"
+
+💬 "Create new patient welcome pages with:
+    - Registration forms and required documents
+    - Insurance information and billing policies
+    - Office policies and procedures
+    - Contact information and directions"
+
+💬 "Generate monthly health newsletter with practice updates and health tips"
+```
+
+**Compliance and Updates**
+
+```text
+💬 "Update all patient privacy notices to comply with HIPAA requirements"
+
+💬 "Create COVID-19 safety protocol pages with current guidelines"
+
+💬 "Add telehealth service information and booking procedures"
+```
+
+## Non-Profit Organization Workflows
+
+### Fundraising Campaigns
+
+**Campaign Launch**
+
+```text
+💬 "Create fundraising campaign page for disaster relief with:
+    - Compelling story and impact statistics
+    - Donation progress tracker and goals
+    - Multiple giving level options
+    - Volunteer signup opportunities"
+
+💬 "Design thank you pages with donation impact explanations"
+
+💬 "Create corporate sponsorship information packages"
+```
+
+**Volunteer Coordination**
+
+```text
+💬 "Create volunteer opportunity listings with:
+    - Role descriptions and time commitments
+    - Required skills and training information
+    - Application forms and background check procedures
+    - Volunteer appreciation showcase"
+
+💬 "Update volunteer handbook and training resource pages"
+
+💬 "Create volunteer appreciation event pages and photo galleries"
+```
+
+**Impact Reporting**
+
+```text
+💬 "Generate quarterly impact reports showing:
+    - Funds raised and allocation breakdown
+    - Programs served and beneficiaries helped
+    - Volunteer hours contributed
+    - Success stories and testimonials"
+
+💬 "Create annual report pages with downloadable PDF versions"
+
+💬 "Update donor recognition pages with latest contributors"
+```
+
+### Community Outreach
+
+**Event Management**
+
+```text
+💬 "Create community event pages for annual charity run with:
+    - Registration forms and fee information
+    - Route maps and safety guidelines
+    - Sponsorship opportunities
+    - Volunteer role signups"
+
+💬 "Update events calendar with monthly community activities"
+
+💬 "Create post-event recap pages with photos and impact measurements"
+```
+
+## Small Business Operations
+
+### Local Business Optimization
+
+**Local SEO Enhancement**
+
+```text
+💬 "Optimize all pages for local search with:
+    - Location-specific keywords and content
+    - Local business schema markup
+    - Customer review integration
+    - Community involvement highlights"
+
+💬 "Create location-specific landing pages for multiple business locations"
+
+💬 "Update business hours, contact information, and service area descriptions"
+```
+
+**Customer Engagement**
+
+```text
+💬 "Create customer loyalty program information pages"
+
+💬 "Develop email newsletter signup incentives and welcome series"
+
+💬 "Generate customer testimonial showcase pages"
+```
+
+**Service Promotion**
+
+```text
+💬 "Create seasonal service promotion pages (spring cleaning, holiday catering, tax preparation)"
+
+💬 "Update service pricing and package information"
+
+💬 "Create before/after project galleries for visual services"
+```
+
+## Integration with Business Tools
+
+### CRM Integration Workflows
+
+**Lead Management**
+
+```text
+💬 "Create contact forms that integrate with our CRM system"
+
+💬 "Set up automated email sequences for new lead nurturing"
+
+💬 "Generate lead magnet landing pages with downloadable resources"
+```
+
+### Analytics Integration
+
+**Performance Monitoring**
+
+```text
+💬 "Set up conversion tracking for all important business goals"
+
+💬 "Create custom dashboards showing key performance indicators"
+
+💬 "Generate automated monthly performance reports for stakeholders"
+```
+
+These workflows demonstrate how MCP WordPress can streamline complex business processes
+across different industries and use cases, making WordPress management more efficient
+and effective through natural language interactions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-wordpress",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Comprehensive Model Context Protocol server for WordPress management with 59 tools, performance monitoring, intelligent caching, auto-generated documentation, Docker support, TypeScript, and production-ready authentication",
   "keywords": [
     "mcp",
@@ -44,6 +44,9 @@
     "check:ignore": "node scripts/sync-ignore-files.js",
     "check:npm": "node scripts/test-npm-config.js",
     "dev": "npm run build && DEBUG=true node dist/index.js",
+    "docker:build": "docker build -t docdyhr/mcp-wordpress:latest .",
+    "docker:publish": "./scripts/manual-docker-publish.sh",
+    "docker:publish:version": "./scripts/manual-docker-publish.sh",
     "docs:check": "node scripts/validate-docs.js",
     "docs:generate": "npm run build && node scripts/generate-docs.js",
     "docs:serve": "npm run docs:generate && node scripts/serve-docs.js",

package/src/client/api.ts

@@ -48,6 +48,53 @@ import type {
 } from "../types/wordpress.js";
 import { debug, logError, startTimer } from "../utils/debug.js";
 
+/**
+ * WordPress REST API Client
+ * 
+ * A comprehensive client for interacting with the WordPress REST API v2.
+ * Provides full CRUD operations for posts, pages, media, users, comments,
+ * categories, tags, and site settings with robust error handling and performance optimization.
+ * 
+ * Features:
+ * - Multiple authentication methods (App Passwords, JWT, Basic Auth, API Key)
+ * - Automatic retry logic with exponential backoff
+ * - Request rate limiting and queue management
+ * - Comprehensive error handling with detailed messages
+ * - Performance monitoring and request statistics
+ * - Caching support for improved performance
+ * - Multi-site configuration support
+ * 
+ * @example
+ * ```typescript
+ * // Initialize with app password authentication
+ * const client = new WordPressClient({
+ *   baseUrl: 'https://mysite.com',
+ *   auth: {
+ *     method: 'app-password',
+ *     username: 'admin',
+ *     password: 'xxxx xxxx xxxx xxxx xxxx xxxx'
+ *   }
+ * });
+ * 
+ * // Create a new post
+ * const post = await client.createPost({
+ *   title: 'My New Post',
+ *   content: '<p>This is the content</p>',
+ *   status: 'publish'
+ * });
+ * 
+ * // List posts with filtering
+ * const posts = await client.getPosts({
+ *   search: 'WordPress',
+ *   status: 'publish',
+ *   per_page: 10
+ * });
+ * ```
+ * 
+ * @since 1.0.0
+ * @author MCP WordPress Team
+ * @implements {IWordPressClient}
+ */
 export class WordPressClient implements IWordPressClient {
   private baseUrl: string;
   private apiUrl: string;
@@ -61,6 +108,49 @@ export class WordPressClient implements IWordPressClient {
   private jwtToken: string | null = null;
   private _stats: ClientStats;
 
+  /**
+   * Creates a new WordPress API client instance.
+   * 
+   * Initializes the client with configuration options for connecting to a WordPress site.
+   * Supports multiple authentication methods and automatic environment variable detection.
+   * 
+   * @param {Partial<WordPressClientConfig>} [options={}] - Configuration options for the client
+   * @param {string} [options.baseUrl] - WordPress site URL (falls back to WORDPRESS_SITE_URL env var)
+   * @param {number} [options.timeout=30000] - Request timeout in milliseconds
+   * @param {number} [options.maxRetries=3] - Maximum number of retry attempts for failed requests
+   * @param {AuthConfig} [options.auth] - Authentication configuration (auto-detected from env if not provided)
+   * @param {boolean} [options.enableCache=true] - Whether to enable response caching
+   * @param {number} [options.cacheMaxAge=300000] - Cache max age in milliseconds (5 minutes default)
+   * 
+   * @example
+   * ```typescript
+   * // Basic configuration with app password
+   * const client = new WordPressClient({
+   *   baseUrl: 'https://mysite.com',
+   *   auth: {
+   *     method: 'app-password',
+   *     username: 'admin',
+   *     password: 'xxxx xxxx xxxx xxxx xxxx xxxx'
+   *   }
+   * });
+   * 
+   * // Configuration with environment variables
+   * // Set WORDPRESS_SITE_URL, WORDPRESS_USERNAME, WORDPRESS_APP_PASSWORD
+   * const client = new WordPressClient(); // Auto-detects from env
+   * 
+   * // Custom timeout and retry settings
+   * const client = new WordPressClient({
+   *   baseUrl: 'https://mysite.com',
+   *   timeout: 60000,      // 60 seconds
+   *   maxRetries: 5,       // 5 retry attempts
+   *   auth: { method: 'app-password', username: 'user', password: 'pass' }
+   * });
+   * ```
+   * 
+   * @throws {Error} When required configuration is missing or invalid
+   * 
+   * @since 1.0.0
+   */
   constructor(options: Partial<WordPressClientConfig> = {}) {
     this.baseUrl = options.baseUrl || process.env.WORDPRESS_SITE_URL || "";
     this.apiUrl = "";

package/src/tools/media.ts

@@ -8,13 +8,52 @@ import {
 import { getErrorMessage } from "../utils/error.js";
 
 /**
- * Provides tools for managing media on a WordPress site.
- * This class encapsulates tool definitions and their corresponding handlers.
+ * Comprehensive media management tools for WordPress sites.
+ * 
+ * This class provides complete media library functionality including:
+ * - Listing media items with advanced filtering and search
+ * - Uploading new media files with validation and optimization
+ * - Retrieving detailed media information and metadata
+ * - Updating media properties like title, description, and alt text
+ * - Deleting media items with safety checks
+ * 
+ * Supports all WordPress media types including images, videos, audio files,
+ * and documents with proper MIME type validation and security checks.
+ * 
+ * @example
+ * ```typescript
+ * const mediaTools = new MediaTools();
+ * const tools = mediaTools.getTools();
+ * 
+ * // Upload an image
+ * const client = new WordPressClient(config);
+ * const result = await mediaTools.handleUploadMedia(client, {
+ *   file_path: "/path/to/image.jpg",
+ *   title: "My Image",
+ *   alt_text: "Description of the image"
+ * });
+ * ```
+ * 
+ * @since 1.0.0
+ * @author MCP WordPress Team
  */
 export class MediaTools {
   /**
-   * Retrieves the list of media management tools.
-   * @returns An array of MCPTool definitions.
+   * Retrieves the complete list of media management tools available for MCP.
+   * 
+   * Returns an array of tool definitions for comprehensive media library management.
+   * Each tool includes parameter validation, security checks, and detailed error handling.
+   * 
+   * @returns {Array<MCPTool>} Array of MCPTool definitions for media management
+   * 
+   * @example
+   * ```typescript
+   * const mediaTools = new MediaTools();
+   * const tools = mediaTools.getTools();
+   * console.log(tools.length); // 5 tools: list, get, upload, update, delete
+   * ```
+   * 
+   * @since 1.0.0
    */
   public getTools(): any[] {
     return [