mcp-wordpress 1.2.2 → 1.3.0

package/docs/user-guides/DTX_SETUP.md

@@ -0,0 +1,327 @@
+# DTX (Desktop Extension) Setup Guide
+
+This guide provides step-by-step instructions for setting up the MCP WordPress server using the DTX (Desktop Extension) package format for Claude Desktop.
+
+---
+
+## 🖼️ What is DTX?
+
+DTX (Desktop Extension) is a package format for Claude Desktop that provides:
+
+- **One-Click Installation** - Install directly through Claude Desktop
+- **Secure Configuration** - Credentials stored in OS keychain
+- **Built-in Documentation** - Tool descriptions and usage examples
+- **User-Friendly Setup** - No command line required
+- **Automatic Updates** - Easy version management
+
+## 🚀 Quick DTX Installation
+
+### Method 1: Install from Built Package
+
+1. **Download the DTX Package**
+
+   ```bash
+   # Download the latest release
+   curl -L https://github.com/docdyhr/mcp-wordpress/releases/latest/download/mcp-wordpress.dxt -o mcp-wordpress.dxt
+   ```
+
+2. **Install in Claude Desktop**
+   - Open Claude Desktop
+   - Go to **Extensions** menu
+   - Click **Install Extension**
+   - Select the `mcp-wordpress.dxt` file
+   - Follow the configuration prompts
+
+### Method 2: Build DTX Package Yourself
+
+1. **Clone and Build**
+
+   ```bash
+   git clone https://github.com/docdyhr/mcp-wordpress.git
+   cd mcp-wordpress
+   npm install
+   npm run build
+   npm run dxt:package
+   ```
+
+2. **Install the Generated Package**
+   - The package will be created as `mcp-wordpress.dxt`
+   - Install through Claude Desktop Extensions menu
+
+## ⚙️ DTX Configuration
+
+After installation, Claude Desktop will prompt you to configure:
+
+### Single-Site Configuration (Default)
+
+The DTX GUI interface supports single-site configuration:
+
+1. **WordPress Site URL**
+   - Enter your full WordPress site URL
+   - Example: `https://yoursite.com`
+
+2. **WordPress Username**
+   - Your WordPress admin username
+   - Must have appropriate permissions
+
+3. **WordPress Application Password**
+   - Generate in WordPress: Admin → Users → Profile → Application Passwords
+   - Format: `xxxx xxxx xxxx xxxx xxxx xxxx`
+
+4. **Authentication Method** (Optional)
+   - **Application Password** (Recommended)
+   - JWT Authentication
+   - Basic Authentication
+   - API Key Authentication
+
+5. **Debug Mode** (Optional)
+   - Enable for troubleshooting
+   - Provides verbose logging
+
+### Multi-Site Configuration (Manual Setup)
+
+The DTX package supports multi-site configuration, but requires manual setup:
+
+#### Method 1: Using mcp-wordpress.config.json (Recommended)
+
+1. **After DTX installation**, create a `mcp-wordpress.config.json` file in your home directory:
+
+```json
+{
+  "sites": [
+    {
+      "id": "site1",
+      "name": "Main Site",
+      "config": {
+        "WORDPRESS_SITE_URL": "https://site1.com",
+        "WORDPRESS_USERNAME": "admin",
+        "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
+      }
+    },
+    {
+      "id": "site2",
+      "name": "Blog Site",
+      "config": {
+        "WORDPRESS_SITE_URL": "https://blog.site2.com",
+        "WORDPRESS_USERNAME": "editor",
+        "WORDPRESS_APP_PASSWORD": "yyyy yyyy yyyy yyyy yyyy yyyy"
+      }
+    }
+  ]
+}
+```
+
+2. **Place the file** in one of these locations:
+   - **macOS/Linux**: `~/mcp-wordpress.config.json`
+   - **Windows**: `%USERPROFILE%\mcp-wordpress.config.json`
+   - **DTX Install Directory**: Next to the DTX package files
+
+3. **Skip the DTX configuration** prompts (or enter dummy values)
+
+4. **Restart Claude Desktop** - the server will detect and use your config file
+
+#### Method 2: Environment Variable Override
+
+Set the `MCP_WORDPRESS_CONFIG_PATH` environment variable to point to your config file:
+
+```bash
+# macOS/Linux
+export MCP_WORDPRESS_CONFIG_PATH=/path/to/mcp-wordpress.config.json
+
+# Windows
+set MCP_WORDPRESS_CONFIG_PATH=C:\path\to\mcp-wordpress.config.json
+```
+
+Then restart Claude Desktop.
+
+### How Multi-Site Works with DTX
+
+When using multi-site configuration:
+
+1. **All sites are available** in every tool by using the `--site` parameter
+2. **Example**: `wp_list_posts --site="site1"`
+3. **If `--site` is omitted**:
+   - Single site: Uses the configured site
+   - Multi-site: Shows error if more than one site exists
+
+### Testing Multi-Site Configuration
+
+After setup, test with these commands:
+
+```text
+# List posts from specific site
+wp_list_posts --site="site1"
+
+# Get stats from another site
+wp_get_site_stats --site="site2"
+
+# See all configured sites
+wp_test_auth
+```
+
+## 🔧 DTX Development Commands
+
+### Building DTX Package
+
+```bash
+# Clean previous builds
+npm run dxt:clean
+
+# Build the DTX package
+npm run dxt:build
+
+# Package everything (clean + build)
+npm run dxt:package
+
+# Validate the package (requires dxt CLI)
+npm run dxt:validate
+```
+
+### DTX Package Structure
+
+The DTX package includes:
+
+```
+mcp-wordpress.dxt/
+├── manifest.json          # DTX configuration and metadata
+├── icon.png              # Extension icon
+├── screenshots/          # Usage screenshots
+├── dist/                 # Compiled application
+└── node_modules/         # Dependencies (production only)
+```
+
+## 📋 DTX Features
+
+### Automatic Configuration
+
+The DTX package automatically configures:
+
+- **22 Primary Tools** - Complete WordPress management toolkit
+- **4 Built-in Prompts** - Pre-configured workflows
+- **Secure Credentials** - Stored in OS keychain
+- **Environment Variables** - Automatically set based on user input
+
+### Built-in Prompts
+
+After installation, you'll have access to these prompts:
+
+1. **Setup WordPress** - Initial site setup and configuration
+2. **Content Management** - Content creation and management workflow  
+3. **Performance Optimization** - Performance monitoring and optimization
+4. **Multi-Site Management** - Multi-site administration workflow
+
+### Tool Categories
+
+The DTX includes 59 tools across:
+
+- **Posts & Pages** - Content management
+- **Media Library** - File uploads and management
+- **Users & Comments** - User administration and moderation
+- **Categories & Tags** - Taxonomy management
+- **Site Settings** - Configuration and statistics
+- **Authentication** - Security and access management
+- **Cache Management** - Performance optimization
+- **Performance Monitoring** - Real-time analytics
+
+## 🔍 DTX Troubleshooting
+
+### Installation Issues
+
+**Problem**: "Package format not recognized"
+
+- **Solution**: Ensure you have the latest Claude Desktop version
+
+**Problem**: "Installation failed"
+
+- **Solution**: Check that the DTX file isn't corrupted; rebuild if necessary
+
+### Configuration Issues
+
+**Problem**: "Authentication failed"
+
+- **Solution**: Verify your Application Password is correct and has no quotes
+
+**Problem**: "Site not accessible"
+
+- **Solution**: Check your WordPress URL and ensure REST API is enabled
+
+### Debugging DTX
+
+1. **Enable Debug Mode** in the DTX configuration
+2. **Check Claude Desktop logs** in Console.app (macOS)
+3. **Test manually** with NPX: `npx -y mcp-wordpress`
+
+## 🆚 DTX vs Other Installation Methods
+
+### DTX Advantages
+
+✅ **One-click installation** through Claude Desktop  
+✅ **Secure credential storage** in OS keychain  
+✅ **Built-in documentation** and prompts  
+✅ **No command line required**  
+✅ **Automatic dependency management**  
+
+### DTX Limitations
+
+❌ **Less flexibility** than manual configuration  
+❌ **Limited customization** options  
+❌ **Requires DTX-compatible Claude Desktop**  
+
+### When to Use DTX
+
+- You want the simplest installation experience
+- You prefer GUI configuration over command line
+- You don't need custom configurations
+- You want automatic updates and management
+
+### When to Use Other Methods
+
+- You need custom configurations
+- You're developing or contributing to the project
+- You prefer command line control
+- You need to modify the source code
+
+## 🔄 Updating DTX Package
+
+### Automatic Updates
+
+- Claude Desktop will notify you of available updates
+- Click **Update** when prompted
+
+### Manual Updates
+
+1. Download the latest DTX package
+2. Go to Extensions → Manage Extensions
+3. Remove the old version
+4. Install the new version
+5. Re-configure if necessary
+
+## 📦 DTX Package Distribution
+
+### For Users
+
+- Download from GitHub Releases
+- Install directly in Claude Desktop
+
+### For Developers
+
+```bash
+# Build and test locally
+npm run dxt:package
+# Install the generated mcp-wordpress.dxt file
+
+# Validate before distribution
+npm run dxt:validate
+```
+
+---
+
+## 🎯 Quick Start Summary
+
+1. **Download**: Get `mcp-wordpress.dxt` from releases
+2. **Install**: Extensions menu in Claude Desktop
+3. **Configure**: Enter WordPress credentials
+4. **Test**: Try "List my WordPress posts"
+5. **Explore**: Use built-in prompts and tools
+
+The DTX format provides the easiest way to get started with WordPress management in Claude Desktop!

package/docs/user-guides/NPM_SETUP.md

@@ -0,0 +1,109 @@
+# NPM Setup Guide (Local Development)
+
+This guide provides step-by-step instructions for setting up the MCP WordPress server locally for development, customization, and contribution.
+
+---
+
+## 📦 Local NPM Setup
+
+For local development, customization, or contributing to the project:
+
+### 1. Install Dependencies
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/docdyhr/mcp-wordpress.git
+cd mcp-wordpress
+npm install
+```
+
+### 2. Run the Setup Wizard
+
+Run the interactive setup wizard:
+
+```bash
+npm run setup
+```
+
+### 3. Build the Project
+
+Compile TypeScript to JavaScript:
+
+```bash
+npm run build
+```
+
+### 4. Start the Server
+
+Start the MCP WordPress server:
+
+```bash
+npm start
+```
+
+### 5. Test the Tools
+
+Run tests to verify functionality:
+
+```bash
+npm run test:tools
+```
+
+### 6. Claude Desktop Configuration (Local)
+
+For local development, use this Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "mcp-wordpress": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-wordpress/dist/index.js"],
+      "env": {
+        "DEBUG": "false",
+        "MCP_DEBUG": "false"
+      }
+    }
+  }
+}
+```
+
+### 7. Development Commands
+
+```bash
+npm run dev             # Development mode with auto-rebuild
+npm run build:watch     # Watch mode compilation
+npm run test:watch      # Watch mode testing
+npm run lint            # Code linting
+npm run format          # Code formatting
+```
+
+### 8. Maintenance Commands
+
+```bash
+npm run status          # Check WordPress connection
+npm run health          # Full system health check
+npm run verify-claude   # Verify Claude Desktop integration
+npm run docs:generate   # Generate API documentation
+```
+
+## 🔧 Local Development Benefits
+
+- **Full Control**: Complete access to source code for customization
+- **Offline Work**: No internet required after initial setup
+- **Debugging**: Direct access to code for troubleshooting
+- **Contributing**: Make changes and submit pull requests
+- **Version Control**: Lock to specific versions or branches
+- **Custom Features**: Add your own tools and modifications
+
+## 🚨 Important Notes
+
+- **Build Required**: Must compile TypeScript before running
+- **Dependencies**: Requires Node.js 18+ and npm installed
+- **Updates**: Manual process to get latest changes
+- **Space**: Uses local disk space for code and dependencies
+
+---
+
+After setup, restart Claude Desktop and test with commands like "List my WordPress posts" or "Show me my site statistics".

package/docs/user-guides/NPX_SETUP.md

@@ -0,0 +1,281 @@
+# NPX Setup Guide
+
+This guide provides step-by-step instructions for using the MCP WordPress server with NPX - the quickest way to get started without local installation.
+
+---
+
+## 🚀 What is NPX?
+
+NPX is a package runner that comes with npm 5.2+. It allows you to:
+
+- Run packages without installing them locally
+- Always use the latest published version
+- Avoid global installations
+- Get started in seconds
+
+## 📋 Prerequisites
+
+- Node.js 18+ with npm 5.2+ (check with `npx --version`)
+- WordPress site with REST API enabled
+- WordPress Application Password (recommended)
+
+## 🎯 Quick Start
+
+### 1. Claude Desktop Configuration
+
+Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+#### Single-Site Setup
+
+```json
+{
+  "mcpServers": {
+    "mcp-wordpress": {
+      "command": "npx",
+      "args": ["-y", "mcp-wordpress"],
+      "env": {
+        "WORDPRESS_SITE_URL": "https://your-site.com",
+        "WORDPRESS_USERNAME": "your_username",
+        "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx",
+        "WORDPRESS_AUTH_METHOD": "app-password"
+      }
+    }
+  }
+}
+```
+
+#### Multi-Site Setup
+
+First, create `mcp-wordpress.config.json` in your home directory:
+
+```json
+{
+  "sites": [
+    {
+      "id": "site1",
+      "name": "Main Site",
+      "config": {
+        "WORDPRESS_SITE_URL": "https://site1.com",
+        "WORDPRESS_USERNAME": "admin",
+        "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
+      }
+    },
+    {
+      "id": "site2",
+      "name": "Blog Site",
+      "config": {
+        "WORDPRESS_SITE_URL": "https://blog.site2.com",
+        "WORDPRESS_USERNAME": "editor",
+        "WORDPRESS_APP_PASSWORD": "yyyy yyyy yyyy yyyy yyyy yyyy"
+      }
+    }
+  ]
+}
+```
+
+Then use this simpler Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "mcp-wordpress": {
+      "command": "npx",
+      "args": ["-y", "mcp-wordpress"]
+    }
+  }
+}
+```
+
+### 2. Generate WordPress Application Password
+
+1. Log into WordPress Admin
+2. Go to Users → Your Profile
+3. Scroll to "Application Passwords"
+4. Enter a name (e.g., "Claude Desktop")
+5. Click "Add New Application Password"
+6. Copy the generated password (format: `xxxx xxxx xxxx xxxx xxxx xxxx`)
+
+### 3. Restart Claude Desktop
+
+After updating the configuration, restart Claude Desktop to load the NPX-based server.
+
+## 🧪 Testing NPX Setup
+
+### Manual Testing (Terminal)
+
+Test the NPX setup before using in Claude Desktop:
+
+```bash
+# Single-site test
+WORDPRESS_SITE_URL=https://your-site.com \
+WORDPRESS_USERNAME=your_username \
+WORDPRESS_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
+npx -y mcp-wordpress
+
+# Multi-site test (with config file in current directory)
+npx -y mcp-wordpress
+```
+
+### Claude Desktop Testing
+
+After configuration, test with these commands:
+
+- "List my WordPress posts"
+- "Show my site statistics"
+- "What WordPress tools are available?"
+
+## 🔧 NPX Options
+
+### Force Latest Version
+
+```json
+{
+  "command": "npx",
+  "args": ["--yes", "--package=mcp-wordpress@latest", "mcp-wordpress"]
+}
+```
+
+### Use Specific Version
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "mcp-wordpress@1.2.4"]
+}
+```
+
+### Clear NPX Cache
+
+If you're having issues with cached versions:
+
+```bash
+# Clear npx cache
+rm -rf ~/.npm/_npx
+
+# Or force fresh download
+npx --ignore-existing mcp-wordpress
+```
+
+## 🆚 NPX vs Other Methods
+
+### NPX Advantages
+
+✅ **No installation required** - Just configure and use  
+✅ **Always latest version** - Automatic updates  
+✅ **No maintenance** - No local files to manage  
+✅ **Quick setup** - Under 30 seconds  
+✅ **Cross-platform** - Works everywhere Node.js works  
+
+### NPX Limitations
+
+❌ **Requires internet** - Downloads package on first run  
+❌ **Slower startup** - Initial download takes time  
+❌ **No customization** - Can't modify the code  
+❌ **No offline work** - Needs internet connection  
+
+### When to Use NPX
+
+- ✅ You just want to use WordPress tools
+- ✅ You want automatic updates
+- ✅ You don't need to modify code
+- ✅ You have reliable internet
+
+### When NOT to Use NPX
+
+- ❌ You need to customize the tools
+- ❌ You're developing new features
+- ❌ You work offline frequently
+- ❌ You need a specific version locked
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+**"Command not found: npx"**
+
+- Install Node.js 18+ which includes npx
+- Or install npx globally: `npm install -g npx`
+
+**"No matching version found"**
+
+- Check your internet connection
+- Try clearing npm cache: `npm cache clean --force`
+
+**"Authentication failed"**
+
+- Verify Application Password has no extra spaces
+- Check WordPress username is correct
+- Ensure REST API is accessible
+
+**"Config file not found"**
+
+- For multi-site, ensure `mcp-wordpress.config.json` is in:
+  - Home directory: `~/mcp-wordpress.config.json`
+  - Or current directory when testing
+
+### Debug Mode
+
+Enable debug output by adding to env:
+
+```json
+{
+  "env": {
+    "DEBUG": "true",
+    "LOG_LEVEL": "debug"
+  }
+}
+```
+
+## 📊 Performance Tips
+
+### NPX Caching
+
+NPX caches packages after first download:
+
+- First run: Downloads package (5-10 seconds)
+- Subsequent runs: Uses cache (instant)
+- Cache location: `~/.npm/_npx/`
+
+### Network Optimization
+
+For slow connections, pre-cache the package:
+
+```bash
+# Pre-download the package
+npx -y mcp-wordpress --help
+
+# Now it's cached for Claude Desktop use
+```
+
+## 🎯 Quick Reference
+
+### Essential Commands
+
+```bash
+# Check npx version
+npx --version
+
+# Test connection
+npx -y mcp-wordpress
+
+# Clear cache
+rm -rf ~/.npm/_npx
+
+# View package info
+npm view mcp-wordpress
+```
+
+### Environment Variables
+
+```bash
+WORDPRESS_SITE_URL      # Required: Your WordPress URL
+WORDPRESS_USERNAME      # Required: WordPress username
+WORDPRESS_APP_PASSWORD  # Required: Application password
+WORDPRESS_AUTH_METHOD   # Optional: Auth method (default: app-password)
+DEBUG                   # Optional: Enable debug output
+LOG_LEVEL              # Optional: Logging level (debug, info, warn, error)
+```
+
+---
+
+NPX provides the fastest way to get started with WordPress tools in Claude Desktop - no installation, no maintenance, just pure functionality!