# WordPress MCP Bridge

This bridge allows stdio-based MCP clients (like Cursor, Windsurf, Zed) to connect to the HTTP-based WordPress MCP server.

## Why is this needed?

Code editors like Cursor and Windsurf expect MCP servers to communicate via **stdio** (standard input/output), but the WordPress MCP plugin uses **HTTP/REST API**. This bridge translates between the two protocols.

## Installation

### Prerequisites

- Node.js installed on your system
- WordPress MCP plugin activated
- Application Password created in WordPress
- `curl` installed (for URL-based method)

### Setup Methods

There are two ways to use the bridge:

1. **URL-based (Recommended)** - Downloads the bridge script automatically from your WordPress site
2. **File-based** - Uses an absolute file path to the bridge script

## Configuration

### Method 1: URL-based Configuration (Recommended)

This method downloads the bridge script directly from your WordPress site, eliminating the need for absolute file paths.

**Benefits:**
- No need to specify absolute file paths
- Works across different machines without configuration changes
- Automatically uses the latest version of the bridge script
- Easier to share configurations with team members

#### For Windsurf (URL-based)

Edit your MCP config file at:
- **Windows:** `%APPDATA%\.codeium\windsurf\mcp_config.json`
- **macOS/Linux:** `~/.codeium/windsurf/mcp_config.json`

**Windows Configuration:**
```json
{
  "mcpServers": {
    "wordpress": {
      "command": "cmd",
      "args": [
        "/c",
        "curl -k -s https://yoursite.com/wp-json/cws-mcp/v1/bridge | node - https://yoursite.com/wp-json/cws-mcp/v1/messages your-username \"your-app-password\""
      ],
      "disabled": false,
      "env": {}
    }
  }
}
```

**macOS/Linux Configuration:**
```json
{
  "mcpServers": {
    "wordpress": {
      "command": "bash",
      "args": [
        "-c",
        "curl -k -s https://yoursite.com/wp-json/cws-mcp/v1/bridge | node - https://yoursite.com/wp-json/cws-mcp/v1/messages your-username \"your-app-password\""
      ],
      "disabled": false,
      "env": {}
    }
  }
}
```

#### For Cursor (URL-based)

Edit your MCP config file at:
- **Windows:** `%USERPROFILE%\.cursor\mcp.json`
- **macOS/Linux:** `~/.cursor/mcp.json`

Use the same configuration format as Windsurf above.

---

### Method 2: File-based Configuration

This method uses an absolute file path to the bridge script. Use this if you prefer not to download the script on each connection.

#### For Windsurf (File-based)

Edit your MCP config file at:
- **Windows:** `%APPDATA%\.codeium\windsurf\mcp_config.json`
- **macOS/Linux:** `~/.codeium/windsurf/mcp_config.json`

**Configuration:**
```json
{
  "mcpServers": {
    "wordpress": {
      "command": "node",
      "args": [
        "/absolute/path/to/wordpress-mcp-bridge.js",
        "https://yoursite.com/wp-json/cws-mcp/v1/messages",
        "your-username",
        "your-app-password"
      ],
      "disabled": false,
      "env": {}
    }
  }
}
```

**Windows Example:**
```json
{
  "mcpServers": {
    "wordpress": {
      "command": "node",
      "args": [
        "D:\\Projects\\WordPress\\mcp-test\\app\\public\\wp-content\\plugins\\cws-mcp\\bridge\\wordpress-mcp-bridge.js",
        "https://mcp-test.local/wp-json/cws-mcp/v1/messages",
        "admin",
        "aR0d Kg8v iVfp ZgFP 0e36 ntCB"
      ],
      "disabled": false,
      "env": {}
    }
  }
}
```

#### For Cursor (File-based)

Edit your MCP config file at:
- **Windows:** `%USERPROFILE%\.cursor\mcp.json`
- **macOS/Linux:** `~/.cursor/mcp.json`

Use the same configuration format as Windsurf above.

#### For Zed

Edit your Zed settings:
- **macOS:** `~/.config/zed/settings.json`
- **Linux:** `~/.config/zed/settings.json`
- **Windows:** `%APPDATA%\Zed\settings.json`

Add:
```json
{
  "context_servers": {
    "wordpress": {
      "command": {
        "path": "node",
        "args": [
          "/absolute/path/to/wordpress-mcp-bridge.js",
          "https://yoursite.com/wp-json/cws-mcp/v1/messages",
          "your-username",
          "your-app-password"
        ]
      }
    }
  }
}
```

## Testing the Bridge

### Manual Test

```bash
# Navigate to the bridge directory
cd /path/to/wp-content/plugins/cws-mcp/bridge

# Run the bridge manually
node wordpress-mcp-bridge.js https://yoursite.com/wp-json/cws-mcp/v1/messages admin "your-app-password"

# Type a JSON-RPC request (press Enter after):
{"jsonrpc":"2.0","method":"tools/list","id":1}

# You should see a response with available tools
```

### Test with echo

```bash
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node wordpress-mcp-bridge.js https://yoursite.com/wp-json/cws-mcp/v1/messages admin "your-app-password"
```

## Troubleshooting

### Issue: "Cannot find module"

**Solution:** Make sure Node.js is installed and in your PATH.

```bash
node --version
```

### Issue: "ECONNREFUSED" or connection errors

**Solutions:**
1. Verify WordPress site is accessible
2. Check the endpoint URL is correct
3. Test the endpoint directly:
   ```bash
   curl -X POST https://yoursite.com/wp-json/cws-mcp/v1/messages \
     -H "Content-Type: application/json" \
     -u "username:password" \
     -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
   ```

### Issue: "401 Unauthorized"

**Solutions:**
1. Verify Application Password is correct
2. Check username is correct
3. Ensure Application Passwords are enabled in WordPress
4. Try creating a new Application Password

### Issue: "UNABLE_TO_VERIFY_LEAF_SIGNATURE" (SSL errors)

The bridge automatically accepts self-signed certificates for local development. If you need to disable this in production:

Edit `wordpress-mcp-bridge.js` and remove this line:
```javascript
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
```

### Issue: Bridge not showing in editor

**Solutions:**
1. Restart your code editor completely
2. Check the MCP config file syntax is valid JSON
3. Verify the absolute path to the bridge script is correct
4. Check editor logs for MCP errors

### Viewing Bridge Logs

The bridge logs to stderr (not stdout, to avoid interfering with MCP communication).

To see logs:
```bash
node wordpress-mcp-bridge.js https://yoursite.com/wp-json/cws-mcp/v1/messages admin "password" 2> bridge.log
```

Then check `bridge.log` for error messages.

## How It Works

1. **Editor** sends JSON-RPC request via stdin
2. **Bridge** receives request from stdin
3. **Bridge** forwards request to WordPress via HTTP POST
4. **WordPress** processes request and returns JSON-RPC response
5. **Bridge** sends response back to editor via stdout

```
┌─────────┐     stdio      ┌────────┐     HTTP      ┌───────────┐
│ Editor  │ ←────────────→ │ Bridge │ ←───────────→ │ WordPress │
│(Cursor) │   JSON-RPC     │(Node.js)│  JSON-RPC    │    MCP    │
└─────────┘                └────────┘               └───────────┘
```

## Security Notes

1. **Never commit** your Application Password to version control
2. Use environment variables for sensitive data in production
3. The bridge accepts self-signed certificates for local development only
4. Application Passwords can be revoked at any time in WordPress

## Alternative: Use Claude Desktop

If you prefer not to use the bridge, **Claude Desktop** natively supports HTTP-based MCP servers and works directly with the WordPress plugin without any bridge:

**Claude Desktop config** (`~/.config/claude/config.json`):
```json
{
  "mcpServers": {
    "wordpress": {
      "url": "https://yoursite.com/wp-json/cws-mcp/v1/messages",
      "auth": {
        "type": "basic",
        "username": "your-username",
        "password": "your-app-password"
      }
    }
  }
}
```

## Support

For issues with:
- **The bridge:** Check this README
- **WordPress MCP plugin:** See main plugin documentation
- **Your code editor:** Check editor's MCP documentation