# WordPress MCP Bridge - NPX Usage

## Overview

The NPX method allows you to use the WordPress MCP Bridge without needing absolute file paths. The bridge package can be published to npm and used with `npx`.

## How It Works

1. The bridge package is published to npm (or used locally with `npm link`)
2. When you run `npx wordpress-mcp-bridge`, it:
   - Downloads the bridge script from your WordPress site via the `/bridge` endpoint
   - Caches it locally in `~/.wordpress-mcp-cache/`
   - Executes the cached bridge with your credentials

## Publishing Options

### Option 1: Publish to npm (Public)

```bash
cd /path/to/wp-content/plugins/cws-mcp/bridge
npm publish
```

Then users can use:
```bash
npx wordpress-mcp-bridge https://yoursite.com/wp-json/cws-mcp/v1/messages username "password"
```

### Option 2: Publish to npm (Scoped/Private)

Update `package.json`:
```json
{
  "name": "@your-org/wordpress-mcp-bridge",
  ...
}
```

Publish:
```bash
npm publish --access public
```

Then users can use:
```bash
npx @your-org/wordpress-mcp-bridge https://yoursite.com/wp-json/cws-mcp/v1/messages username "password"
```

### Option 3: Use Locally (Development)

```bash
cd /path/to/wp-content/plugins/cws-mcp/bridge
npm link
```

Then you can use:
```bash
wordpress-mcp-bridge https://yoursite.com/wp-json/cws-mcp/v1/messages username "password"
```

### Option 4: Host on Private npm Registry

If you have a private npm registry (like Verdaccio, GitHub Packages, or GitLab Package Registry):

```bash
npm publish --registry https://your-registry.com
```

## Configuration Examples

### Windsurf

Edit: `%APPDATA%\.codeium\windsurf\mcp_config.json` (Windows) or `~/.codeium/windsurf/mcp_config.json` (macOS/Linux)

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

### Cursor

Edit: `%USERPROFILE%\.cursor\mcp.json` (Windows) or `~/.cursor/mcp.json` (macOS/Linux)

```json
{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": [
        "wordpress-mcp-bridge",
        "https://yoursite.com/wp-json/cws-mcp/v1/messages",
        "your-username",
        "your-app-password"
      ]
    }
  }
}
```

### Claude Desktop

Edit: `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/.config/claude/claude_desktop_config.json` (macOS/Linux)

```json
{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": [
        "wordpress-mcp-bridge",
        "https://yoursite.com/wp-json/cws-mcp/v1/messages",
        "your-username",
        "your-app-password"
      ]
    }
  }
}
```

## Benefits of NPX Method

✅ **No absolute paths** - Works on any machine without configuration changes  
✅ **Auto-updates** - Always uses the latest bridge script from your WordPress site  
✅ **Easy sharing** - Share one configuration across your team  
✅ **Version control friendly** - Configuration files don't contain machine-specific paths  

## Requirements

- Node.js and npm installed
- The bridge package published to npm (or linked locally)
- WordPress site with CWS MCP plugin installed
- Bridge endpoint accessible at `/wp-json/cws-mcp/v1/bridge`

## Testing Locally

Before publishing, test the npx wrapper:

```bash
cd /path/to/wp-content/plugins/cws-mcp/bridge
node bin/wordpress-mcp-bridge.js https://yoursite.com/wp-json/cws-mcp/v1/messages username "password"
```

Type a test request:
```json
{"jsonrpc":"2.0","method":"tools/list","id":1}
```

You should see a JSON response with available tools.

## Deployment Recommendations

### For Public Use
Publish to npm public registry with a clear package name like `wordpress-mcp-bridge` or `@your-org/wordpress-mcp-bridge`.

### For Private/Internal Use
- Use a private npm registry (Verdaccio, GitHub Packages, etc.)
- Or use `npm link` for local development
- Or distribute the package via your own CDN/hosting

### For Enterprise
Consider hosting on your organization's private npm registry with proper authentication and access controls.

## Troubleshooting

### NPX Command Not Found
Make sure npm is installed and in your PATH:
```bash
npm --version
```

### Bridge Download Fails
Check that:
1. Your WordPress site is accessible
2. The CWS MCP plugin is activated
3. The bridge endpoint returns the script: `curl https://yoursite.com/wp-json/cws-mcp/v1/bridge`

### Permission Issues
The bridge caches files in `~/.wordpress-mcp-cache/`. Make sure this directory is writable.

### Package Not Found
If using a scoped package, make sure to include the scope:
```bash
npx @your-org/wordpress-mcp-bridge ...
```

## Security Notes

- The bridge script is downloaded from your WordPress site each time npx runs (first time or when cache expires)
- Credentials are passed as command-line arguments (visible in process list)
- Consider using environment variables for sensitive credentials in production
- The bridge accepts self-signed certificates for local development (NODE_TLS_REJECT_UNAUTHORIZED=0)