mcp-wordpress 1.1.7 → 1.2.2

package/docs/contract-testing.md

@@ -0,0 +1,183 @@
+# Contract Testing with Live WordPress
+
+This guide explains how to run contract tests against a live WordPress instance using the automated testing setup.
+
+## 🚀 Quick Start (Automated)
+
+The easiest way to test against a live WordPress instance:
+
+```bash
+npm run test:contracts:live
+```
+
+This command will:
+1. 🐳 Start isolated WordPress + MySQL containers (port 8081)
+2. ⚙️ Auto-configure WordPress with test data
+3. 🧪 Run contract tests against the live instance
+4. 🧹 Clean up automatically when done
+
+**No conflicts with existing services** - uses isolated Docker containers with different ports.
+
+## 📋 What the Automated Setup Includes
+
+### WordPress Configuration
+- **URL**: `http://localhost:8081`
+- **Admin User**: `testuser` / `test-password-123`
+- **App Password**: Auto-generated for API access
+- **Test Content**: Pre-created posts and media for testing
+
+### Docker Services
+- **WordPress**: Latest WordPress with auto-setup
+- **MySQL**: 8.0 with optimized configuration
+- **WP-CLI**: For automated WordPress configuration
+
+### Network Isolation
+- Uses separate Docker network: `wordpress-test-network`
+- Port 8081 (different from main development environment)
+- Isolated volumes: `wordpress_test_data`, `db_test_data`
+
+## 🔧 Manual Setup (Alternative)
+
+If you prefer manual setup or need custom configuration:
+
+### 1. Start Services
+```bash
+docker-compose -f docker-compose.test.yml up -d
+```
+
+### 2. Check Status
+```bash
+docker-compose -f docker-compose.test.yml ps
+docker-compose -f docker-compose.test.yml logs -f wordpress-test
+```
+
+### 3. Access WordPress
+- WordPress: http://localhost:8081
+- Admin Panel: http://localhost:8081/wp-admin
+
+### 4. Run Tests
+```bash
+# Set environment variables
+export WORDPRESS_TEST_URL="http://localhost:8081"
+export WORDPRESS_USERNAME="testuser"
+export WORDPRESS_APP_PASSWORD="your-app-password"
+export PACT_LIVE_TESTING="true"
+
+# Run contract tests
+npm run test:contracts
+```
+
+### 5. Cleanup
+```bash
+docker-compose -f docker-compose.test.yml down -v
+```
+
+## 🧪 Test Modes
+
+### Mock Testing (Default)
+```bash
+npm run test:contracts
+```
+- Uses Pact mock provider
+- No external dependencies
+- Fast execution
+- Good for CI/CD
+
+### Live Testing
+```bash
+npm run test:contracts:live
+```
+- Tests against real WordPress
+- Validates actual API behavior
+- Comprehensive integration testing
+- Auto-setup and cleanup
+
+## 📊 Test Coverage
+
+The contract tests verify:
+
+### ✅ Posts API
+- Create posts with proper structure
+- Retrieve posts with pagination
+- Response format validation
+
+### ✅ Media API  
+- File upload handling
+- Multipart form data
+- Media library integration
+
+### ✅ Users API
+- User information retrieval
+- Authentication validation
+- Permission handling
+
+### ✅ Authentication
+- App password authentication
+- Authorization headers
+- Error handling
+
+## 🛠️ Troubleshooting
+
+### Port Already in Use
+```bash
+# Check what's using port 8081
+lsof -i :8081
+
+# Kill process if needed
+kill -9 <PID>
+```
+
+### Docker Issues
+```bash
+# Clean up Docker resources
+docker system prune -f
+docker volume prune -f
+
+# Restart Docker daemon
+sudo service docker restart  # Linux
+# Or restart Docker Desktop   # macOS/Windows
+```
+
+### WordPress Not Ready
+```bash
+# Check WordPress logs
+docker-compose -f docker-compose.test.yml logs wordpress-test
+
+# Check database logs
+docker-compose -f docker-compose.test.yml logs db-test
+
+# Manual health check
+curl http://localhost:8081/wp-json/wp/v2/
+```
+
+### Test Failures
+```bash
+# Run with debug output
+DEBUG=true npm run test:contracts:live
+
+# Check WordPress configuration
+docker-compose -f docker-compose.test.yml exec wordpress-test cat /var/www/html/test-config.json
+```
+
+## 🔒 Security Notes
+
+- Test environment uses isolated containers
+- Default credentials are for testing only
+- Auto-cleanup removes all test data
+- No persistent storage outside containers
+
+## 📈 CI/CD Integration
+
+To use in CI/CD pipelines:
+
+```yaml
+# GitHub Actions example
+- name: Install Docker Compose
+  run: sudo apt-get install docker-compose
+
+- name: Run Contract Tests
+  run: npm run test:contracts:live
+  timeout-minutes: 10
+```
+
+The automated setup is designed to work in CI environments with proper Docker support.

package/docs/developer/NPM_AUTH_SETUP.md

@@ -6,13 +6,13 @@ The project includes a pre-configured `.npmrc` file that uses environment variab
 
 1. **Set your NPM token as environment variable:**
    ```bash
-   export NPM_TOKEN="your_npm_token_here"
+   export NPM_TOKEN="npm_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    ```
 
 2. **Or add to your shell profile:**
    ```bash
    # Add to ~/.bashrc, ~/.zshrc, or ~/.profile
-   echo 'export NPM_TOKEN="your_npm_token_here"' >> ~/.zshrc
+   echo 'export NPM_TOKEN="npm_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"' >> ~/.zshrc
    source ~/.zshrc
    ```
 
@@ -55,7 +55,7 @@ The project includes a pre-configured `.npmrc` file that uses environment variab
 3. **Using environment variable** (more secure):
    ```bash
    # Add to ~/.bashrc or ~/.zshrc
-   export NPM_TOKEN="your_npm_token_here"
+   export NPM_TOKEN="npm_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    
    # Then in .npmrc:
    //registry.npmjs.org/:_authToken=${NPM_TOKEN}

package/docs/wordpress-rest-api-authentication-troubleshooting.md

@@ -0,0 +1,218 @@
+# WordPress REST API Authentication Troubleshooting Guide
+
+## Issue: POST Requests Return 401 Unauthorized with Application Passwords
+
+This document addresses the common issue where WordPress REST API POST/PUT/DELETE requests fail with 401 Unauthorized errors, while GET requests work fine with the same application password credentials.
+
+## Symptoms
+
+- ✅ GET requests work perfectly with application passwords  
+- ✅ WP-CLI commands work with the same credentials
+- ✅ User has administrator role and all necessary capabilities
+- ❌ POST/PUT/DELETE requests return 401 Unauthorized
+- ❌ Error: `rest_cannot_create` or similar permission errors
+
+## Root Causes
+
+### 1. Authorization Header Stripping (.htaccess)
+
+**Most Common Cause:** Apache strips the `Authorization` header by default, particularly affecting write operations.
+
+**Solution:** Add to your `.htaccess` file:
+```apache
+# WordPress REST API - Preserve Authorization Header
+RewriteCond %{HTTP:Authorization} ^(.*)
+RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]
+```
+
+Alternative approach:
+```apache
+RewriteEngine On
+RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
+```
+
+### 2. Docker Environment Configuration
+
+**Issue:** WordPress requires HTTPS for application passwords by default, but Docker development environments typically use HTTP.
+
+**Solution:** Add to your `docker-compose.yml`:
+```yaml
+services:
+  wordpress:
+    environment:
+      WORDPRESS_CONFIG_EXTRA: |
+        define('WP_ENVIRONMENT_TYPE', 'local');
+```
+
+### 3. Wrong Application Password Source
+
+**Issue:** WordPress has multiple places to generate passwords, and using the wrong one causes failures.
+
+**Solution:** Generate application passwords from:
+- ✅ `/wp-admin/profile.php` - User Profile page
+- ❌ NOT from 2FA/Security plugin settings
+
+### 4. HTTP Authentication Interference
+
+**Issue:** Server-level HTTP authentication interferes with WordPress authentication.
+
+**Solution:** Configure server to exclude `/wp-json/` from HTTP auth, or temporarily disable.
+
+## Technical Differences: WP-CLI vs REST API
+
+| Aspect | WP-CLI | REST API |
+|--------|--------|----------|
+| Access Method | Direct file system | HTTP requests |
+| Authentication | Bypasses web server | Requires HTTP headers |
+| Configuration Impact | Not affected | Subject to .htaccess rules |
+| Proxy Impact | Not affected | Can be blocked by proxies |
+
+## Docker-Specific Solutions
+
+### Complete Docker Configuration
+
+```yaml
+version: '3.8'
+services:
+  wordpress:
+    image: wordpress:latest
+    environment:
+      WORDPRESS_DB_HOST: db
+      WORDPRESS_DB_USER: wordpress
+      WORDPRESS_DB_PASSWORD: wordpress
+      WORDPRESS_DB_NAME: wordpress
+      # Enable application passwords in local development
+      WORDPRESS_CONFIG_EXTRA: |
+        define('WP_ENVIRONMENT_TYPE', 'local');
+    volumes:
+      - ./wp-htaccess.conf:/var/www/html/.htaccess
+```
+
+### WordPress .htaccess Template
+
+Create `wp-htaccess.conf`:
+```apache
+# BEGIN WordPress
+RewriteEngine On
+
+# REST API Authorization Header Fix
+RewriteCond %{HTTP:Authorization} ^(.*)
+RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]
+
+# Standard WordPress Rules
+RewriteRule ^index\.php$ - [L]
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+RewriteRule . /index.php [L]
+# END WordPress
+```
+
+## Debugging Steps
+
+### 1. Test Authorization Header Passing
+
+```bash
+# Test if headers reach WordPress
+curl -v -H "Authorization: Basic $(echo -n 'username:app_password' | base64)" \
+     https://your-site.com/wp-json/wp/v2/posts
+```
+
+Look for `Authorization` header in the request output.
+
+### 2. WordPress Debug Information
+
+Add to `wp-config.php`:
+```php
+define('WP_DEBUG', true);
+define('WP_DEBUG_LOG', true);
+define('WP_DEBUG_DISPLAY', false);
+
+// Log REST API authentication attempts
+add_action('rest_authentication_errors', function($result) {
+    error_log('REST Auth Result: ' . print_r($result, true));
+    return $result;
+});
+```
+
+### 3. Test Script
+
+```javascript
+const testAuth = async () => {
+    const username = 'your_username';
+    const appPassword = 'xxxx xxxx xxxx xxxx xxxx xxxx'; // Preserve spaces
+    const siteUrl = 'http://localhost:8081';
+    
+    const auth = Buffer.from(`${username}:${appPassword}`).toString('base64');
+    
+    console.log('Testing GET request...');
+    const getResponse = await fetch(`${siteUrl}/wp-json/wp/v2/posts?per_page=1`, {
+        headers: { 'Authorization': `Basic ${auth}` }
+    });
+    console.log('GET Status:', getResponse.status);
+    
+    console.log('Testing POST request...');
+    const postResponse = await fetch(`${siteUrl}/wp-json/wp/v2/posts`, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Basic ${auth}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+            title: 'Auth Test Post',
+            content: 'Testing authentication',
+            status: 'draft'
+        })
+    });
+    console.log('POST Status:', postResponse.status);
+    
+    if (!postResponse.ok) {
+        const error = await postResponse.json();
+        console.log('Error:', error);
+    }
+};
+
+testAuth();
+```
+
+## Common Security Plugin Issues
+
+### Wordfence
+- Check if REST API is blocked in Wordfence settings
+- Temporarily disable to test
+
+### iThemes Security
+- May block REST API requests
+- Check "WordPress Tweaks" → "Disable REST API"
+
+### Jetpack
+- May interfere with authentication
+- Check Jetpack security settings
+
+## Production Considerations
+
+1. **Always use HTTPS** in production
+2. **Remove WP_ENVIRONMENT_TYPE override** in production
+3. **Monitor failed authentication attempts**
+4. **Use strong application passwords**
+5. **Regularly rotate application passwords**
+
+## Verification Checklist
+
+- [ ] `.htaccess` includes Authorization header preservation
+- [ ] Docker environment sets `WP_ENVIRONMENT_TYPE` to `local`
+- [ ] Application password generated from correct location
+- [ ] No HTTP authentication conflicts
+- [ ] User has administrator role
+- [ ] Security plugins allow REST API access
+- [ ] WordPress debug logging enabled for testing
+
+## Alternative Authentication Methods
+
+If application passwords continue to fail:
+
+1. **JWT Authentication Plugin**
+2. **OAuth 2.0 Plugin** 
+3. **Custom nonce-based authentication**
+4. **API Key plugins**
+
+Remember: The goal is to achieve the same level of functionality that WP-CLI provides, but through the REST API interface.

package/package.json

@@ -1,116 +1,136 @@
 {
   "name": "mcp-wordpress",
-  "version": "1.1.7",
-  "description": "Comprehensive Model Context Protocol server for WordPress management with 54 tools, TypeScript support, and production-ready authentication",
-  "main": "dist/index.js",
+  "version": "1.2.2",
+  "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",
+    "model-context-protocol",
+    "wordpress",
+    "cms",
+    "rest-api",
+    "ai",
+    "assistant"
+  ],
+  "homepage": "https://github.com/thomasdyhr/mcp-wordpress#readme",
+  "bugs": {
+    "url": "https://github.com/thomasdyhr/mcp-wordpress/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thomasdyhr/mcp-wordpress.git"
+  },
+  "license": "MIT",
+  "author": "Thomas Dyhr",
   "type": "module",
+  "main": "dist/index.js",
   "bin": {
     "mcp-wordpress": "bin/mcp-wordpress.js",
     "wordpress-setup": "bin/setup.js",
     "wordpress-status": "bin/status.js"
   },
+  "files": [
+    "dist/",
+    "src/",
+    "bin/",
+    "docs/",
+    "examples/",
+    "cache/",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsc",
     "build:watch": "tsc --watch",
-    "start": "npm run build && node dist/index.js",
+    "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",
+    "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",
+    "docs:validate": "npm run docs:generate && node scripts/validate-docs.js",
+    "docs:watch": "npm run docs:generate && echo 'Watching for changes...' && npm run docs:serve",
+    "fix:rest-auth": "bash scripts/fix-rest-api-auth.sh",
+    "health": "node scripts/health-check.js",
+    "lint": "eslint src/ tests/",
+    "lint:fix": "eslint src/ tests/ --fix",
+    "pre-commit": "lint-staged",
+    "prepare": "husky",
+    "prepublishOnly": "npm run build && npm run check:ignore",
+    "security:audit": "npm audit --production",
+    "security:check": "node scripts/security-check.js",
+    "security:fix": "npm audit fix",
+    "security:test": "node scripts/security-test.js",
     "setup": "node bin/setup.js",
+    "start": "npm run build && node dist/index.js",
     "status": "node bin/status.js",
     "test": "npm run test:typescript",
-    "test:typescript": "npm run build && NODE_OPTIONS=\"--experimental-vm-modules\" jest --config=jest.typescript.config.json",
-    "test:tools": "node scripts/test-all-tools.js",
-    "test:legacy": "npm run build && NODE_OPTIONS=\"--experimental-vm-modules\" jest",
-    "test:watch": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --watch --config=jest.typescript.config.json",
+    "test:auth": "node scripts/test-auth.js",
+    "test:config": "npm run build && NODE_OPTIONS=\"--experimental-vm-modules\" jest tests/config/ --config=jest.typescript.config.json",
+    "test:contracts": "npm run build && NODE_OPTIONS=\"--experimental-vm-modules\" jest tests/contracts/ --config=jest.typescript.config.json",
+    "test:contracts:live": "bash scripts/test-contracts-live.sh",
     "test:coverage": "npm run build && NODE_OPTIONS=\"--experimental-vm-modules\" jest --coverage --collectCoverageFrom='dist/**/*.js' --coverageThreshold='{\"global\":{\"branches\":50,\"functions\":50,\"lines\":50,\"statements\":50}}' --config=jest.typescript.config.json",
     "test:fast": "npm run test:typescript",
-    "test:mcp": "node scripts/test-mcp.js",
     "test:integration": "node scripts/test-integration.js",
-    "test:auth": "node scripts/test-auth.js",
-    "health": "node scripts/health-check.js",
-    "verify-claude": "node scripts/verify-claude-integration.js",
-    "lint": "eslint src/ tests/",
-    "lint:fix": "eslint src/ tests/ --fix",
+    "test:legacy": "npm run build && NODE_OPTIONS=\"--experimental-vm-modules\" jest",
+    "test:mcp": "node scripts/test-mcp.js",
+    "test:performance": "npm run build && NODE_OPTIONS=\"--experimental-vm-modules\" jest tests/performance/ --config=jest.typescript.config.json",
+    "test:property": "npm run build && NODE_OPTIONS=\"--experimental-vm-modules\" jest tests/property/ --config=jest.typescript.config.json",
+    "test:security": "npm run build && NODE_OPTIONS=\"--experimental-vm-modules\" jest tests/security/ --config=jest.typescript.config.json",
+    "test:security:penetration": "npm run build && NODE_OPTIONS=\"--experimental-vm-modules\" jest tests/security/penetration-tests.test.js --config=jest.typescript.config.json",
+    "test:security:validation": "npm run build && NODE_OPTIONS=\"--experimental-vm-modules\" jest tests/security/security-validation.test.js --config=jest.typescript.config.json",
+    "test:tools": "node scripts/test-all-tools-fixed.js",
+    "test:multisite": "node scripts/test-multisite-quick.js",
+    "test:typescript": "npm run build && NODE_OPTIONS=\"--experimental-vm-modules\" jest --config=jest.typescript.config.json",
+    "test:watch": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --watch --config=jest.typescript.config.json",
+    "test:with-env": "bash scripts/start-test-env.sh && npm run test:typescript",
     "typecheck": "tsc --noEmit",
-    "check:ignore": "node scripts/sync-ignore-files.js",
-    "check:npm": "node scripts/test-npm-config.js",
-    "prepare": "husky",
-    "pre-commit": "lint-staged",
-    "prepublishOnly": "npm run build && npm run check:ignore"
+    "verify-claude": "node scripts/verify-claude-integration.js"
+  },
+  "lint-staged": {
+    "*.{ts,js}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.md": [
+      "markdownlint --fix"
+    ],
+    "package.json": [
+      "sort-package-json"
+    ]
   },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "wordpress",
-    "cms",
-    "rest-api",
-    "ai",
-    "assistant"
-  ],
-  "author": "AiondaDotCom",
-  "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "dotenv": "^16.3.1",
     "form-data": "^4.0.0",
     "node-fetch": "^3.3.2",
-    "open": "^9.1.0",
     "zod": "^3.25.67"
   },
   "devDependencies": {
     "@eslint/js": "^9.29.0",
     "@jest/globals": "^30.0.0",
+    "@pact-foundation/pact": "^15.0.1",
+    "@pact-foundation/pact-node": "^10.18.0",
     "@types/jest": "^30.0.0",
-    "@types/nock": "^10.0.3",
     "@types/node": "^20.19.1",
     "@typescript-eslint/parser": "^8.35.0",
     "eslint": "^9.29.0",
     "eslint-plugin-jest": "^29.0.1",
     "eslint-plugin-node": "^11.1.0",
+    "fast-check": "^4.1.1",
     "husky": "^9.1.7",
     "jest": "^30.0.0",
     "lint-staged": "^16.1.2",
     "markdownlint-cli": "^0.45.0",
     "nock": "^14.0.5",
+    "open": "^9.1.0",
     "prettier": "^3.6.2",
     "sort-package-json": "^3.3.1",
-    "ts-jest": "^29.4.0",
-    "ts-node": "^10.9.2",
     "typescript": "^5.8.3"
   },
   "engines": {
     "node": ">=18.0.0"
   },
-  "files": [
-    "dist/",
-    "src/",
-    "bin/",
-    "docs/",
-    "examples/",
-    "cache/",
-    "README.md",
-    "LICENSE"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/AiondaDotCom/mcp-wordpress.git"
-  },
-  "bugs": {
-    "url": "https://github.com/AiondaDotCom/mcp-wordpress/issues"
-  },
-  "homepage": "https://github.com/AiondaDotCom/mcp-wordpress#readme",
   "publishConfig": {
     "access": "public"
-  },
-  "lint-staged": {
-    "*.{ts,js}": [
-      "eslint --fix",
-      "prettier --write"
-    ],
-    "*.md": [
-      "markdownlint --fix"
-    ],
-    "package.json": [
-      "sort-package-json"
-    ]
   }
 }