@automattic/mcp-wordpress-remote 0.2.1 → 0.2.3

package/README.md

@@ -1,40 +1,482 @@
 # MCP WordPress Remote
 
-The mcp-wordpress-remote package acts as a bridge between local Model Context Protocol (MCP) clients and remote WordPress MCP servers. By leveraging npx, you can execute this package without a global installation, simplifying the setup process.
+**A Model Context Protocol (MCP) server for seamless WordPress integration**
 
-## Requirements
+Connect AI assistants like Claude Desktop to your WordPress sites with multiple authentication methods including OAuth 2.0, JWT tokens, and application passwords.
+
+## Features
+
+- **MCP Authorization Specification Compliant** - Implements MCP Authorization specification 2025-06-18
+- **OAuth 2.1 with PKCE** - Secure authorization code flow with PKCE (RFC 7636)
+- **Resource Indicators** - RFC 8707 compliance for token audience binding
+- **Dynamic Client Registration** - RFC 7591 support for automatic client registration
+- **Protected Resource Metadata Discovery** - RFC 9728 for automatic endpoint discovery
+- **Multiple Authentication Methods** - OAuth 2.1, JWT tokens, and WordPress application passwords
+- **Persistent Token Storage** - OAuth tokens stored securely with automatic validation
+- **Multi-instance Coordination** - Lockfiles prevent authentication conflicts
+- **Automatic Token Management** - Handles validation, refresh, and cleanup
+- **Enhanced Error Handling** - Detailed error messages with proper categorization
+- **Comprehensive Logging** - Structured logging with categories and levels
+- **Complete MCP Support** - Tools, resources, prompts, and more
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install @automattic/mcp-wordpress-remote
+```
+
+### Configuration
+
+Add to your MCP client configuration (e.g., Claude Desktop's `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "npx",
+      "args": ["-y", "@automattic/mcp-wordpress-remote"],
+      "env": {
+        "WP_API_URL": "https://your-wordpress-site.com"
+      }
+    }
+  }
+}
+```
+
+### First Run
+
+1. **Start your MCP client** (Claude Desktop, etc.)
+2. **Choose authentication method** based on your preference:
+   - **OAuth 2.0** (default): Browser opens automatically for authorization
+   - **JWT Token**: Set `JWT_TOKEN` environment variable
+   - **Application Password**: Set `WP_API_USERNAME` and `WP_API_PASSWORD`
+3. **Start using WordPress features** in your AI assistant
+
+## WordPress MCP Plugin
+
+You need to install the [wordpress-mcp](https://github.com/Automattic/wordpress-mcp) plugin on your WordPress website and enable MCP Functionality in Settings > MCP Settings.
+
+## Authentication Methods
+
+### 1. OAuth 2.1 (Recommended - MCP Compliant)
+
+OAuth 2.1 provides the most secure and user-friendly experience with full MCP Authorization specification compliance for **self-hosted WordPress sites**.
+
+#### **For Self-Hosted WordPress Sites:**
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "npx",
+      "args": ["-y", "@automattic/mcp-wordpress-remote"],
+      "env": {
+        "WP_API_URL": "https://your-wordpress-site.com",
+        "OAUTH_ENABLED": "true",
+        "OAUTH_FLOW_TYPE": "authorization_code",
+        "OAUTH_USE_PKCE": "true"
+      }
+    }
+  }
+}
+```
+
+#### **For WordPress.com Sites (Automatic Compatibility):**
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "npx",
+      "args": ["-y", "@automattic/mcp-wordpress-remote"],
+      "env": {
+        "WP_API_URL": "https://yoursite.wordpress.com"
+      }
+    }
+  }
+}
+```
+
+_The system automatically detects WordPress.com sites and uses compatible OAuth2 endpoints._
+
+**MCP Authorization Specification Features:**
+
+- **OAuth 2.1 authorization code flow** with PKCE (RFC 7636)
+- **Resource Indicators** (RFC 8707) for token audience binding
+- **Dynamic Client Registration** (RFC 7591) when supported
+- **Protected Resource Metadata Discovery** (RFC 9728)
+- **Authorization Server Metadata Discovery** (RFC 8414)
+
+**Benefits:**
+
+- Full compliance with MCP Authorization specification 2025-06-18
+- Enhanced security with PKCE protection
+- One-time browser authorization
+- Tokens stored securely with automatic validation
+- Automatic endpoint discovery
+- No need to manage passwords
+- Automatic expiration handling
+
+### 2. JWT Token Authentication
+
+For server-to-server authentication or when OAuth is not available.
 
-- Node.js version 22 or higher
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "npx",
+      "args": ["-y", "@automattic/mcp-wordpress-remote"],
+      "env": {
+        "WP_API_URL": "https://your-wordpress-site.com",
+        "JWT_TOKEN": "your-jwt-token-here"
+      }
+    }
+  }
+}
+```
 
-## WordPress MCP plugin
+### 3. WordPress Application Passwords (Legacy)
 
-You have to install the [wordpress-mcp](https://github.com/Automattic/wordpress-mcp) plugin on your WordPress website, and enable MCP Functionality on Settings > MCP Settings.
+Uses WordPress username and application password for basic authentication.
 
-## Why
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "npx",
+      "args": ["-y", "@automattic/mcp-wordpress-remote"],
+      "env": {
+        "WP_API_URL": "https://your-wordpress-site.com",
+        "WP_API_USERNAME": "your-username",
+        "WP_API_PASSWORD": "your-application-password",
+        "OAUTH_ENABLED": "false"
+      }
+    }
+  }
+}
+```
 
-1. Most of the clients does not suport SSE or Streamable communications protocols.
-2. Improved eficiency. This proxy will not keep an open connection to your website, and it will only make simple REST API requests to your website when needed.
-3. Oauth2.1 is not yet available on wordpress out of the box.
-4. Security trough WordPress API passwords and WooCommerce REST API cosumer key and secret
-5. Easy to use. See installation instructions below.
+To create an application password:
 
-## Usage
+1. Go to your WordPress admin dashboard
+2. Navigate to Users > Profile
+3. Scroll down to "Application Passwords"
+4. Create a new application password for MCP access
+
+## Advanced Configuration
+
+### Custom OAuth Settings
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "npx",
+      "args": ["-y", "@automattic/mcp-wordpress-remote"],
+      "env": {
+        "WP_API_URL": "https://your-wordpress-site.com",
+        "OAUTH_CALLBACK_PORT": "8080",
+        "OAUTH_HOST": "127.0.0.1",
+        "WP_OAUTH_CLIENT_ID": "your-custom-client-id"
+      }
+    }
+  }
+}
+```
+
+### WooCommerce Integration
+
+For WooCommerce-specific tools and reports:
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "npx",
+      "args": ["-y", "@automattic/mcp-wordpress-remote"],
+      "env": {
+        "WP_API_URL": "https://your-wordpress-site.com",
+        "WOO_CUSTOMER_KEY": "ck_your-consumer-key",
+        "WOO_CUSTOMER_SECRET": "cs_your-consumer-secret"
+      }
+    }
+  }
+}
+```
 
 ### Environment Variables
 
-The following environment variables are required:
+| Variable                     | Description                        | Default              | Required |
+| ---------------------------- | ---------------------------------- | -------------------- | -------- |
+| `WP_API_URL`                 | WordPress site URL                 | -                    | ✅       |
+| `OAUTH_ENABLED`              | Enable OAuth authentication        | `true`               | -        |
+| `OAUTH_CALLBACK_PORT`        | OAuth callback port                | `3000`               | -        |
+| `OAUTH_HOST`                 | OAuth callback hostname            | `127.0.0.1`          | -        |
+| `WP_OAUTH_CLIENT_ID`         | Custom OAuth client ID             | -                    | -        |
+| **MCP OAuth 2.1 Settings**   |                                    |                      |          |
+| `OAUTH_FLOW_TYPE`            | OAuth flow type                    | `authorization_code` | -        |
+| `OAUTH_USE_PKCE`             | Use PKCE (required for OAuth 2.1)  | `true`               | -        |
+| `OAUTH_DYNAMIC_REGISTRATION` | Enable dynamic client registration | `true`               | -        |
+| `OAUTH_RESOURCE_INDICATOR`   | Use resource indicators (RFC 8707) | `true`               | -        |
+| **Configuration**            |                                    |                      |          |
+| `WP_MCP_CONFIG_DIR`          | Config directory override          | `~/.mcp-auth`        | -        |
+| `LOG_FILE`                   | Log file path                      | -                    | -        |
+| `LOG_LEVEL`                  | Log level (0-3)                    | `2`                  | -        |
+| **Legacy Authentication**    |                                    |                      |          |
+| `JWT_TOKEN`                  | JWT token for authentication       | -                    | -        |
+| `WP_API_USERNAME`            | WordPress username (legacy)        | -                    | -        |
+| `WP_API_PASSWORD`            | WordPress app password (legacy)    | -                    | -        |
+| `WOO_CUSTOMER_KEY`           | WooCommerce consumer key           | -                    | -        |
+| `WOO_CUSTOMER_SECRET`        | WooCommerce consumer secret        | -                    | -        |
+
+### WordPress.com Compatibility
+
+The package automatically detects WordPress.com sites and uses the appropriate OAuth2 flow for full compatibility with the [WordPress.com OAuth2 API](https://developer.wordpress.com/docs/oauth2/).
+
+#### **Automatic Detection**
+
+WordPress.com sites (\*.wordpress.com) are automatically detected and configured with:
+
+- **Standard OAuth2 implicit flow** (as per WordPress.com documentation)
+- **WordPress.com OAuth endpoints**: `public-api.wordpress.com/oauth2/*`
+- **Bearer token authentication** format
+- **No PKCE requirement** (WordPress.com compatible)
+
+#### **Manual WordPress.com Configuration**
+
+For explicit WordPress.com mode:
+
+```json
+{
+  "env": {
+    "WP_API_URL": "https://yoursite.wordpress.com",
+    "OAUTH_FLOW_TYPE": "implicit",
+    "OAUTH_USE_PKCE": "false",
+    "OAUTH_RESOURCE_INDICATOR": "false"
+  }
+}
+```
+
+### Disable OAuth
+
+To use only JWT or Basic Auth:
+
+```json
+{
+  "env": {
+    "OAUTH_ENABLED": "false",
+    "JWT_TOKEN": "your-jwt-token"
+  }
+}
+```
+
+## Development Mode
+
+For development and testing, you can use the local repository:
+
+### Setup
+
+1. **Clone the repository:**
+
+   ```bash
+   git clone https://github.com/Automattic/mcp-wordpress-remote.git
+   cd mcp-wordpress-remote
+   ```
+
+2. **Install dependencies:**
+
+   ```bash
+   npm install
+   ```
+
+3. **Build the project:**
+   ```bash
+   npm run build
+   ```
+
+### Configuration
+
+Configure your MCP client to use the local version:
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "node",
+      "args": ["/path/to/your/mcp-wordpress-remote/dist/proxy.js"],
+      "env": {
+        "WP_API_URL": "https://your-wordpress-site.com"
+      }
+    }
+  }
+}
+```
+
+### Development Workflow
+
+- **Watch mode:** `npm run build:watch` - Automatically rebuilds on file changes
+- **Testing:** `npm test` - Run the test suite
+- **Type checking:** `npm run check` - Run TypeScript and Prettier checks
+
+## Token Management
+
+### OAuth Token Storage
+
+Tokens are automatically stored in:
+
+```
+~/.mcp-auth/wordpress-remote-{version}/
+```
+
+### Manual Management
+
+```bash
+# View stored tokens
+ls -la ~/.mcp-auth/wordpress-remote-*/
+
+# Clear all tokens (forces re-authentication)
+rm -rf ~/.mcp-auth/wordpress-remote-*/
+
+# Clear tokens for specific version
+rm -rf ~/.mcp-auth/wordpress-remote-0.2.1/
+```
+
+### Token Security
+
+- **Secure file permissions** (600) on all token files
+- **Automatic token validation** before each request
+- **Expired token cleanup** during startup
+- **Version isolation** - each version stores tokens separately
+
+## Multi-Instance Support
+
+The proxy automatically coordinates between multiple instances:
+
+- **Lockfiles** prevent simultaneous OAuth flows
+- **Process coordination** ensures only one authentication at a time
+- **Graceful waiting** when another instance is authenticating
+- **Automatic cleanup** of stale locks
+
+If you see "waiting for other instance" messages, this is normal behavior.
+
+## Troubleshooting
+
+### Authentication Issues
+
+**OAuth browser doesn't open:**
+
+- Check if port 3000 is available
+- Try a different port with `OAUTH_CALLBACK_PORT`
+- Manually open the URL shown in logs
+
+**OAuth authorization fails:**
+
+- Verify WordPress site has MCP plugin installed and enabled
+- Check WordPress admin user permissions
+- Try clearing tokens and re-authenticating
+
+**JWT authentication fails:**
+
+- Verify JWT token is valid and not expired
+- Check token format and encoding
+- Ensure WordPress site supports JWT authentication
+
+**Basic Auth fails:**
+
+- Verify username and application password
+- Check application password is active
+- Ensure user has sufficient permissions
+
+### Connection Issues
+
+**API endpoint not found:**
+
+- Verify WordPress MCP plugin is installed and activated
+- Check plugin is enabled in WordPress admin
+- Confirm `WP_API_URL` is correct
+
+**Permission denied:**
+
+- Check user permissions in WordPress
+- Verify authentication credentials
+- Review WordPress user roles
+
+### Port Conflicts
+
+If port 3000 is already in use:
+
+```json
+{
+  "env": {
+    "OAUTH_CALLBACK_PORT": "8080"
+  }
+}
+```
+
+### Multi-instance Messages
+
+"Waiting for other instance" messages are normal when multiple MCP clients start simultaneously. The system coordinates authentication to prevent conflicts.
+
+### Log Analysis
+
+Enable detailed logging:
+
+```json
+{
+  "env": {
+    "LOG_LEVEL": "3",
+    "LOG_FILE": "/path/to/logfile.log"
+  }
+}
+```
+
+Log levels:
+
+- `0` - Errors only
+- `1` - Warnings and errors
+- `2` - Info, warnings, and errors (default)
+- `3` - Debug, info, warnings, and errors
+
+## Security Features
+
+- **Secure OAuth flow** with state parameters and PKCE
+- **Token encryption** with secure file permissions
+- **Automatic validation** before each API request
+- **Expired token cleanup** and refresh handling
+- **Multi-instance coordination** prevents authentication conflicts
+
+## Why Use MCP WordPress Remote?
+
+1. **Multiple Authentication Methods** - Choose what works best for your setup
+2. **Enhanced Security** - OAuth 2.0 with persistent token storage
+3. **Better User Experience** - One-time setup with automatic token management
+4. **Multi-Instance Support** - Works reliably with multiple MCP clients
+5. **Comprehensive Logging** - Detailed logs for troubleshooting
+6. **Easy Setup** - No global installation required with npx
+
+## Requirements
+
+- **Node.js 22+** (required for fetch API support)
+- **WordPress site** with [wordpress-mcp](https://github.com/Automattic/wordpress-mcp) plugin
+- **WordPress user account** with appropriate permissions
+
+## License
+
+GPL v2 or later
+
+## Contributing
 
-- `WP_API_URL`: The URL of your WordPress site (e.g., `https://example.com`)
-- `WP_API_USERNAME`: Your WordPress username
-- `WP_API_PASSWORD`: Your WordPress [application password](https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/#Getting-Credentials)
-- `WOO_CUSTOMER_KEY`: Your Woocommerce customer key (optional, if you intend to use WooCommerce MCP assets)
-- `WOO_CUSTOMER_SECRET`: Your WooCommerce customer secret (optional, if you intend to use WooCommerce MCP assets)
-- `LOG_FILE`: Optional full path to a log file
+Contributions welcome! This project is maintained by Automattic Inc.
 
-### Configuration in MCP Clients
+## Support
 
-Please check [WordPress-mcp](https://github.com/Automattic/wordpress-mcp?tab=readme-ov-file#mcp-client-configuration) plugin git repository for configuration details
+- **Issues:** [GitHub Issues](https://github.com/Automattic/mcp-wordpress-remote/issues)
+- **Documentation:** Check the troubleshooting section above
+- **WordPress MCP Plugin:** [Plugin Repository](https://github.com/Automattic/wordpress-mcp)
 
-## @todo
+---
 
-As of now, this package is in its early development stages. Any suggestions, bugreports, PR's are welcome.
+**Need help?** Check the [troubleshooting section](#troubleshooting) or open an issue.