# WPCafe MCP Server

Connect any MCP-compatible AI assistant — Claude, ChatGPT, Cursor, and others — to your WordPress site running the **WPCafe** restaurant plugin.

Once connected, your AI assistant can manage reservations, food orders, locations, QR codes, settings, analytics, and every other feature available in the WPCafe admin panel.

---

## What you can do

| Category | Actions |
|---|---|
| **Reservations** | List, get, create, update, delete, bulk delete, cancel, check time slots, check capacity |
| **Food Orders** | List, get, update status, delete (WooCommerce orders) |
| **Products** | List food menu items, get product details, list categories |
| **Locations** | List, get, create, update, delete, bulk delete branches |
| **QR Codes** | List, get, create, update, delete scan-to-order QR codes |
| **Settings** | Get all settings, get public settings, update settings |
| **Dashboard** | Overview stats, food order analytics, reservation analytics, top-selling products |
| **Modules** | List extensions, enable/disable modules, get integrations, get addon plugins |
| **Pro — Seat Plans** | List, get, create, update, delete visual floor layouts |
| **Pro — Discounts** | List, get, create, update, delete discount codes |
| **Pro — Receipts** | List receipt layouts, get order receipt |
| **Pro — Timed Products** | List, create time-availability rules for menu items |

---

## Prerequisites

- Node.js 18 or later
- WPCafe plugin (free) installed and active on your WordPress site
- WordPress user with **Administrator** or **Shop Manager** role
- A WordPress **Application Password** (created in WP Admin → Users → Your Profile)

---

## Setup

### Step 1 — Create a WordPress Application Password

1. Go to **WordPress Admin → Users → Your Profile**
2. Scroll down to **Application Passwords**
3. Enter a name (e.g. `WPCafe MCP`) and click **Add New Application Password**
4. Copy the password shown — it looks like `xxxx xxxx xxxx xxxx xxxx xxxx`
5. Keep it somewhere safe; WordPress will not show it again

### Step 2 — Configure your AI client

#### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "wpcafe": {
      "command": "npx",
      "args": ["-y", "github:themewinter/wpcafe-mcp"],
      "env": {
        "WPCAFE_SITE_URL": "https://yoursite.com",
        "WPCAFE_USERNAME": "your-admin-username",
        "WPCAFE_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}
```

Restart Claude Desktop. WPCafe tools will appear automatically.

#### Cursor / VS Code (MCP extension)

```json
{
  "servers": {
    "wpcafe": {
      "command": "npx",
      "args": ["-y", "github:themewinter/wpcafe-mcp"],
      "env": {
        "WPCAFE_SITE_URL": "https://yoursite.com",
        "WPCAFE_USERNAME": "your-admin-username",
        "WPCAFE_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}
```

#### Any other MCP client

The server speaks standard MCP over stdio. Use `npx -y github:themewinter/wpcafe-mcp` as the command with the three env vars set.

---

## Example prompts

```
Show me all pending reservations for today.

Create a reservation for John Smith (john@example.com) on 2026-07-01 at 7pm for 4 guests.

List all food orders with status "processing".

What were the top 10 selling items this month?

Update the primary color in WPCafe settings to #FF5722.

Create a QR code named "Table 12" for location ID 3.

Enable the Delivery module.

Show me the dashboard overview for the past week.
```

---

## Optional: Enable full write access

By default the server works with Application Password authentication. A small subset of WPCafe operations (reservation creation, food-order listing) use WordPress's CSRF nonce system, which requires a one-time server-side snippet.

If you hit a message like **"This operation requires a WordPress security nonce"**, add this to your site's `functions.php` (or any active plugin):

```php
add_action( 'rest_api_init', function () {
    register_rest_route( 'wpcafe/v2', '/nonce', [
        'methods'             => 'GET',
        'callback'            => fn() => [
            'nonce'   => wp_create_nonce( 'wp_rest' ),
            'expires' => time() + 43200,
        ],
        'permission_callback' => 'is_user_logged_in',
    ] );
} );
```

Alternatively, upload `wordpress-plugin/wpcafe-mcp-bridge.php` (included in this repo) to your `wp-content/plugins/` directory and activate it in WP Admin — same effect, no code editing required.

---

## Security

### How authentication works

1. You create an **Application Password** in your WordPress profile — it is separate from your login password and can be revoked at any time.
2. The MCP server sends it with every request as an `Authorization: Basic` header.
3. WordPress verifies it and authenticates the request as that user.
4. All WPCafe permission checks (capabilities, roles) still apply — the MCP server does not bypass them.

### What the MCP server does NOT do

- It does not store or cache credentials on disk.
- It does not bypass WordPress capability checks.
- It does not expose any endpoint that isn't already in the WPCafe REST API.
- It does not run any code inside WordPress — it only calls the existing REST API.

### HTTPS requirement

**Always use HTTPS** for `WPCAFE_SITE_URL`. Application Passwords are sent in every request header; without HTTPS anyone on the network can read them. The server warns (but does not block) if it detects an HTTP URL for a non-localhost host.

### Revoking access

Go to **WordPress Admin → Users → Your Profile → Application Passwords** and delete the `WPCafe MCP` entry. The server immediately loses access.

### Role capabilities

| Role | List / Get | Create | Update | Delete |
|---|---|---|---|---|
| Administrator | All resources | All resources | All resources | All resources |
| Shop Manager | Reservations, Orders, Products | Reservations | Order status, Reservation status | — |
| Staff (wpcafe_manage_*) | Own + all reservations/orders | — | Status only | — |

---

## Troubleshooting

**"HTTP 401 Unauthorized"**
- Check that `WPCAFE_USERNAME` and `WPCAFE_APP_PASSWORD` are correct.
- Make sure Application Passwords are enabled (some security plugins disable them).
- Verify the user exists and has the right role.

**"HTTP 403 Forbidden"**
The authenticated user does not have the required capability. Use an administrator or shop manager account.

**"This operation requires a WordPress security nonce"**
Add the `functions.php` snippet above, or install `wordpress-plugin/wpcafe-mcp-bridge.php`.

**Pro tools return 404**
The wpcafe-pro plugin is not installed or not active. Pro tools are registered but return 404 on free-only installations.

---

## Development

```bash
git clone https://github.com/themewinter/wpcafe-mcp.git
cd wpcafe-mcp
npm install
npm run dev      # Run with tsx (no build step)
npm run build    # Compile TypeScript to dist/
npm start        # Run compiled output
```

To add new tools, create a register function in `src/tools/` following the pattern of existing files, then call it in `src/index.ts`.

---

## License

GPL-2.0-or-later — same license as the WPCafe WordPress plugin.