mcp-wordpress 1.2.3 → 1.3.1

package/docs/user-guides/DOCKER_SETUP.md

@@ -0,0 +1,264 @@
+# Docker Setup Guide
+
+This guide provides step-by-step instructions for setting up the MCP WordPress server using Docker, specifically for Claude Desktop integration.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Pull the Docker Image
+
+```bash
+docker pull docdyhr/mcp-wordpress:latest
+```
+
+### 2. Add to Claude Desktop configuration
+
+## 🎯 Claude Desktop Integration (Recommended)
+
+### Single-Site Setup
+
+Add this to your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "mcp-wordpress": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "-e",
+        "WORDPRESS_SITE_URL=https://your-site.com",
+        "-e",
+        "WORDPRESS_USERNAME=your_username",
+        "-e",
+        "WORDPRESS_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx",
+        "docdyhr/mcp-wordpress:latest"
+      ]
+    }
+  }
+}
+```
+
+### Multi-Site Setup (Recommended)
+
+1. **Create `mcp-wordpress.config.json`**:
+
+```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. **Add to Claude Desktop configuration**:
+
+```json
+{
+  "mcpServers": {
+    "mcp-wordpress": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "-v",
+        "/absolute/path/to/mcp-wordpress.config.json:/app/mcp-wordpress.config.json:ro",
+        "docdyhr/mcp-wordpress:latest"
+      ]
+    }
+  }
+}
+```
+
+## 🔧 Standalone Docker Usage
+
+### Single-Site Mode
+
+```bash
+# Interactive mode (recommended for testing)
+docker run --rm -i \
+  -e WORDPRESS_SITE_URL=https://your-site.com \
+  -e WORDPRESS_USERNAME=your_username \
+  -e WORDPRESS_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
+  docdyhr/mcp-wordpress:latest
+
+# Background mode (for debugging/logs)
+docker run -d --name mcp-wordpress-debug \
+  -e WORDPRESS_SITE_URL=https://your-site.com \
+  -e WORDPRESS_USERNAME=your_username \
+  -e WORDPRESS_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
+  docdyhr/mcp-wordpress:latest
+```
+
+### Multi-Site Mode
+
+```bash
+# Interactive mode
+docker run --rm -i \
+  -v ./mcp-wordpress.config.json:/app/mcp-wordpress.config.json:ro \
+  docdyhr/mcp-wordpress:latest
+
+# Background mode (for debugging/logs)
+docker run -d --name mcp-wordpress-multisite \
+  -v ./mcp-wordpress.config.json:/app/mcp-wordpress.config.json:ro \
+  docdyhr/mcp-wordpress:latest
+```
+
+## 🐳 Docker Compose Setup
+
+Create `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  mcp-wordpress:
+    image: docdyhr/mcp-wordpress:latest
+    container_name: mcp-wordpress
+    restart: unless-stopped
+    volumes:
+      # Mount configuration file (choose one approach)
+      - ./mcp-wordpress.config.json:/app/mcp-wordpress.config.json:ro
+      # OR mount .env file for single-site
+      - ./.env:/app/.env:ro
+    environment:
+      - NODE_ENV=production
+    # Note: No ports exposed - MCP uses stdin/stdout
+```
+
+**Start with Docker Compose:**
+
+```bash
+docker-compose up -d
+```
+
+## 🛠️ Development & Debugging
+
+### View Logs
+
+```bash
+# For named containers
+docker logs mcp-wordpress-debug
+docker logs -f mcp-wordpress-multisite  # Follow logs
+
+# For Docker Compose
+docker-compose logs -f mcp-wordpress
+```
+
+### Container Management
+
+```bash
+# List running containers
+docker ps
+
+# Stop containers
+docker stop mcp-wordpress-debug
+docker-compose down
+
+# Remove containers
+docker rm mcp-wordpress-debug
+```
+
+### Test Configuration
+
+```bash
+# Test single-site setup
+echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | \
+docker run --rm -i \
+  -e WORDPRESS_SITE_URL=https://your-site.com \
+  -e WORDPRESS_USERNAME=your_username \
+  -e WORDPRESS_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
+  docdyhr/mcp-wordpress:latest
+
+# Test multi-site setup
+echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | \
+docker run --rm -i \
+  -v ./mcp-wordpress.config.json:/app/mcp-wordpress.config.json:ro \
+  docdyhr/mcp-wordpress:latest
+```
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+**1. MCP Integration Not Working**
+
+- ❌ **Problem**: Using `-d` flag in Claude Desktop config
+- ✅ **Solution**: Remove `-d` flag, use `--rm -i` instead
+
+**2. Configuration File Not Found**
+
+- ❌ **Problem**: Wrong mount path `/app/config/mcp-wordpress.config.json`
+- ✅ **Solution**: Use correct path `/app/mcp-wordpress.config.json`
+
+**3. Permission Denied**
+
+- ❌ **Problem**: Config file not readable by container
+- ✅ **Solution**: Use absolute paths and check file permissions
+
+**4. App Password with Spaces**
+
+- ❌ **Problem**: Spaces in password breaking Docker args
+- ✅ **Solution**: Quote the password in command line, or use config file
+
+### Validation Commands
+
+```bash
+# Verify image exists
+docker images | grep mcp-wordpress
+
+# Check container health
+docker run --rm docdyhr/mcp-wordpress:latest --health-check
+
+# Validate config file
+docker run --rm -i \
+  -v ./mcp-wordpress.config.json:/app/mcp-wordpress.config.json:ro \
+  docdyhr/mcp-wordpress:latest --validate-config
+```
+
+## 🚨 Important Notes
+
+### ✅ Do's
+
+- ✅ Use `--rm -i` for Claude Desktop integration
+- ✅ Mount config file to `/app/mcp-wordpress.config.json`
+- ✅ Use absolute paths for volume mounts
+- ✅ Quote passwords with spaces in command line
+
+### ❌ Don'ts  
+
+- ❌ **Never use `-d` flag with Claude Desktop** (breaks MCP communication)
+- ❌ **Don't expose ports** like `-p 3000:3000` (unnecessary for MCP)
+- ❌ **Don't use named containers** with `--name` for MCP (can cause conflicts)
+- ❌ **Don't mount to `/app/config/`** (wrong path)
+
+## 🔄 After Setup
+
+1. **Restart Claude Desktop** to load the new configuration
+2. **Test the integration** with commands like:
+   - "List my WordPress posts"
+   - "Show my site statistics"
+   - "What WordPress sites do I have configured?"
+
+The Docker container will start automatically when Claude Desktop needs to use WordPress tools.

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".