# Building Standalone Executables

This guide explains how to build standalone executables of the WordPress MCP Bridge that don't require Node.js to be installed.

## Why Build Standalone Executables?

- **No Node.js Required**: Users can run the bridge without installing Node.js
- **Simpler Distribution**: Single executable file per platform
- **Easier for Non-Developers**: Just download and run

## Prerequisites

- Node.js 16+ installed (for building only)
- npm or yarn package manager

## Installation

1. Navigate to the bridge directory:
```bash
cd wp-content/plugins/cws-mcp/bridge
```

2. Install dependencies:
```bash
npm install
```

This will install `pkg` which packages Node.js applications into executables.

## Building Executables

### Build All Platforms

Build executables for Windows, macOS, and Linux:

```bash
npm run build
```

This creates:
- `../dist/wordpress-mcp-bridge-win.exe` (Windows)
- `../dist/wordpress-mcp-bridge-macos` (macOS)
- `../dist/wordpress-mcp-bridge-linux` (Linux)

### Build Individual Platforms

**Windows only:**
```bash
npm run build:win
```

**macOS only:**
```bash
npm run build:mac
```

**Linux only:**
```bash
npm run build:linux
```

## Output Location

Executables are created in:
```
wp-content/plugins/cws-mcp/dist/
```

## Using the Executables

### Windows

Replace the Node.js command in your MCP config:

**Before:**
```json
{
  "mcpServers": {
    "wordpress": {
      "command": "node",
      "args": [
        "D:\\path\\to\\wordpress-mcp-bridge.js",
        "https://yoursite.com/wp-json/cws-mcp/v1/messages",
        "username",
        "password"
      ]
    }
  }
}
```

**After:**
```json
{
  "mcpServers": {
    "wordpress": {
      "command": "D:\\path\\to\\wordpress-mcp-bridge-win.exe",
      "args": [
        "https://yoursite.com/wp-json/cws-mcp/v1/messages",
        "username",
        "password"
      ]
    }
  }
}
```

### macOS/Linux

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

**After:**
```json
{
  "mcpServers": {
    "wordpress": {
      "command": "/path/to/wordpress-mcp-bridge-macos",
      "args": [
        "https://yoursite.com/wp-json/cws-mcp/v1/messages",
        "username",
        "password"
      ]
    }
  }
}
```

**Note:** On macOS/Linux, make the executable runnable:
```bash
chmod +x wordpress-mcp-bridge-macos
# or
chmod +x wordpress-mcp-bridge-linux
```

## Distribution

### For Plugin Releases

1. Build all platform executables
2. Include them in the plugin distribution under `dist/` folder
3. Update documentation to reference executable paths
4. Users can choose between Node.js script or standalone executable

### File Sizes

Standalone executables are larger than the script (typically 40-50MB) because they include:
- Node.js runtime
- All dependencies
- The bridge script

This is normal and expected for `pkg` builds.

## Troubleshooting

### "pkg: command not found"

**Solution:** Install dependencies first:
```bash
npm install
```

### Build fails with permission errors

**Solution:** Ensure you have write permissions to the `dist/` directory:
```bash
mkdir -p ../dist
chmod 755 ../dist
```

### Executable won't run on macOS

**Solution:** macOS may block unsigned executables. Users need to:
1. Right-click the executable
2. Select "Open"
3. Click "Open" in the security dialog

Or run:
```bash
xattr -d com.apple.quarantine wordpress-mcp-bridge-macos
```

### Executable won't run on Windows

**Solution:** Windows Defender may flag the executable. This is a false positive common with `pkg` builds. Users can:
1. Add an exception in Windows Defender
2. Or use the Node.js script version instead

## Advanced Configuration

### Custom Build Targets

Edit `package.json` to add more targets:

```json
{
  "scripts": {
    "build:arm": "pkg . --targets node18-macos-arm64 --output ../dist/wordpress-mcp-bridge-macos-arm64"
  }
}
```

Available targets:
- `node18-win-x64` - Windows 64-bit
- `node18-win-x86` - Windows 32-bit
- `node18-macos-x64` - macOS Intel
- `node18-macos-arm64` - macOS Apple Silicon
- `node18-linux-x64` - Linux 64-bit
- `node18-linux-arm64` - Linux ARM64

### Reducing File Size

Add to `package.json`:

```json
{
  "pkg": {
    "compress": "GZip"
  }
}
```

This compresses the executable but may increase startup time slightly.

## Continuous Integration

### GitHub Actions Example

```yaml
name: Build Executables

on:
  release:
    types: [created]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '18'
      - run: cd bridge && npm install
      - run: cd bridge && npm run build
      - uses: actions/upload-artifact@v2
        with:
          name: executables
          path: dist/
```

## Security Considerations

1. **Code Signing**: For production, sign executables:
   - Windows: Use `signtool`
   - macOS: Use `codesign`
   - Linux: Use GPG signatures

2. **Checksums**: Provide SHA256 checksums for verification:
```bash
sha256sum wordpress-mcp-bridge-* > checksums.txt
```

3. **Updates**: Implement version checking in the bridge script

## Support

For issues with:
- **Building**: Check Node.js and npm versions
- **Running**: Check executable permissions and antivirus settings
- **Distribution**: Ensure all platforms are tested before release

## Alternative: Docker Container

For users who prefer containers:

```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY wordpress-mcp-bridge.js .
ENTRYPOINT ["node", "wordpress-mcp-bridge.js"]
```

Build and run:
```bash
docker build -t wordpress-mcp-bridge .
docker run -i wordpress-mcp-bridge https://site.com/wp-json/cws-mcp/v1/messages user pass
```