# dapper-mcp-wp

An MCP server that lets Claude (Claude Code, Claude Desktop, claude.ai) connect to
your WordPress sites and **read context, create pages, and edit pages** — instead of
copy-pasting into the admin by hand.

Built for the builders you actually use: **WPBakery / Visual Composer, Gutenberg,
and Classic** — all of which keep content in `post_content`, so they're fully
editable over the standard WordPress REST API. No companion plugin required.

> Elementor stores layout as JSON in post meta and needs a companion plugin to edit
> safely — that's a later phase, not part of this REST-only core.

## How it works

```
Claude  ──MCP──>  dapper-mcp-wp  ──REST + App Password──>  WordPress site(s)
                  (this server)
```

- **Auth:** WordPress core **Application Passwords** (Settings → Users → your bot
  user). Scoped, revocable, never exposes a real login.
- **Safety:** new pages default to **draft**; edits rely on WordPress **revisions**
  (every save is auto-versioned → one-click rollback).
- **Context:** `get_site_context` reports theme, plugins, detected builder, and
  recent pages. Pair it with a hand-maintained profile in [`sites/`](./sites).

## Setup

1. **Install deps & build**
   ```bash
   npm install
   npm run build
   ```

2. **Create the bot user on each site**
   In WP admin: add a user (e.g. `dapper-bot`, role Editor or Admin) →
   edit the user → **Application Passwords** → add one → copy the generated password.

3. **Add the connection** — copy the example and fill in real values:
   ```bash
   cp sites.example.json sites.local.json   # sites.local.json is gitignored
   ```
   ```json
   [
     { "name": "acme", "url": "https://acme.example.com",
       "username": "dapper-bot", "appPassword": "xxxx xxxx xxxx xxxx xxxx xxxx" }
   ]
   ```

4. **Smoke-test the connection**
   ```bash
   npm run doctor
   ```

5. **Point Claude Code at it** (`.mcp.json` in a project, or your user config):
   ```json
   {
     "mcpServers": {
       "dapper-wp": { "command": "node", "args": ["dist/index.js"] }
     }
   }
   ```
   (Use an absolute path to `dist/index.js`, or `tsx src/index.ts` during dev.)

## Tools

| Tool | What it does |
|------|--------------|
| `list_sites` | List configured sites |
| `get_site_context` | Auth check + theme, plugins, builder, recent pages |
| `list_pages` | List/search pages |
| `get_page` | Fetch one page's raw editable content |
| `create_page` | Create a page (draft by default) |
| `update_page` | Edit title/content/status (revision-safe) |

## Roadmap

- **Phase 1 (here):** REST-only core for WPBakery / Gutenberg / Classic.
- **Phase 2:** `get_design_tokens` (colors/fonts), richer per-site profiles,
  WPBakery shortcode helpers imported from the skill file.
- **Phase 3:** optional `dapper-connector` WP plugin — one-click onboarding
  (auto-provision bot user + App Password) and Elementor/Divi support.

## Security

`sites.local.json` and `.env` are gitignored. **Never commit site credentials.**
Each site's Application Password can be revoked independently from WP admin.