# WP Audit MCP Server

MCP (Model Context Protocol) server for comprehensive WordPress site audits on WP Engine.

## What is This?

This is an MCP server that gives [Claude Code](https://claude.ai/claude-code) specialized tools for auditing and optimizing WordPress sites hosted on WP Engine. Instead of manually running PHP scripts and API calls, you can simply ask Claude to audit a site and it will use these tools automatically.

## How It Works

```
┌─────────────────────────────────────────────────────────────────┐
│ Your Computer                                                   │
│                                                                 │
│  Claude Code ◄──stdio──► wp-audit-mcp (Node.js)                │
│                               │                                 │
│                               ├──SSH──► WP Engine sites         │
│                               │         (runs WP-CLI/PHP)       │
│                               │                                 │
│                               └──HTTPS──► CloudFlare API        │
└─────────────────────────────────────────────────────────────────┘
```

1. **Claude Code** starts the MCP server as a local subprocess
2. They communicate via stdin/stdout (not network)
3. When you ask Claude to audit a site, it calls the MCP tools
4. The MCP server connects to WP Engine via SSH and runs PHP scripts
5. For CloudFlare, it makes API calls directly

## Features

| Tool | Description |
|------|-------------|
| `wp_baseline` | Full site audit (content counts, database size, SEO status, plugin artifacts) |
| `wp_cleanup` | Database cleanup (orphaned data, revisions, transients, action scheduler) |
| `wp_plugin_artifacts` | Remove leftover tables/options from deleted plugins |
| `wp_seo_check` | Check meta description coverage |
| `wp_seo_fix` | Auto-generate or manually set meta descriptions |
| `wp_rocket_fix` | Check and optimize WP Rocket settings |
| `wp_clear_cache` | Clear all caches (WordPress, WP Rocket, page builders, WP Engine) |
| `cloudflare_check` | Audit CloudFlare security settings |
| `cloudflare_fix` | Apply recommended CloudFlare settings |
| `ahrefs_extract` | Parse and summarize Ahrefs site audit exports |

---

## Installation

### Prerequisites

#### 1. Node.js 18+

Download from [nodejs.org](https://nodejs.org/) or use a version manager:

```bash
# Check your version
node --version  # Should be v18.x or higher

# macOS (with Homebrew)
brew install node

# Windows (with Chocolatey)
choco install nodejs

# Linux (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
```

#### 2. Claude Code

Install Claude Code if you haven't:

```bash
npm install -g @anthropic-ai/claude-code
```

#### 3. SSH Access to WP Engine

You need SSH key-based authentication to WP Engine sites.

**Generate an SSH key (if you don't have one):**
```bash
ssh-keygen -t ed25519 -C "your-email@example.com"
```

**Add your public key to WP Engine:**
1. Log into [WP Engine Portal](https://my.wpengine.com)
2. Go to **My Profile** → **SSH Keys**
3. Click **Add SSH Key**
4. Paste contents of `~/.ssh/id_ed25519.pub`

**Test the connection:**
```bash
# Replace SITEID with your WP Engine environment name
ssh SITEID@SITEID.ssh.wpengine.net 'echo "Connected successfully"'
```

#### 4. CloudFlare Global API Key (Optional)

Only needed if you want to use the CloudFlare tools.

1. Log into [CloudFlare Dashboard](https://dash.cloudflare.com)
2. Click your profile icon → **My Profile**
3. Go to **API Tokens** tab
4. Find **Global API Key** → Click **View**
5. Copy the key (you'll need this when running CloudFlare tools)

**Note:** Use the Global API Key, not an API Token. The Global API Key works with all zones.

---

### Step-by-Step Installation

#### Step 1: Clone the Repository

```bash
# Clone to a permanent location (not in a project folder)
git clone https://github.com/markahope-aag/wp-audit-mcp.git ~/wp-audit-mcp

# Or on Windows
git clone https://github.com/markahope-aag/wp-audit-mcp.git C:\tools\wp-audit-mcp
```

#### Step 2: Install Dependencies and Build

```bash
cd ~/wp-audit-mcp   # or C:\tools\wp-audit-mcp on Windows

# Install Node.js dependencies
npm install

# Build the TypeScript code
npm run build
```

You should see a `dist/` folder created with the compiled JavaScript.

#### Step 3: Configure Claude Code

Claude Code uses a `.mcp.json` file to know about MCP servers. You need to add this server to that file.

**Option A: Use the configure script**

```bash
# Run from your project directory (where you use Claude Code)
~/wp-audit-mcp/configure.sh .

# Windows
C:\tools\wp-audit-mcp\configure.sh .
```

**Option B: Manual configuration**

Create or edit `.mcp.json` in your project directory:

```json
{
  "mcpServers": {
    "wp-audit": {
      "command": "node",
      "args": ["/Users/yourname/wp-audit-mcp/dist/index.js"]
    }
  }
}
```

**Important:** Use the full absolute path to `dist/index.js`:
- macOS/Linux: `/Users/yourname/wp-audit-mcp/dist/index.js`
- Windows: `C:/tools/wp-audit-mcp/dist/index.js` (use forward slashes)

#### Step 4: Restart Claude Code

```bash
# Start Claude Code in your project directory
cd /path/to/your/project
claude
```

When Claude Code starts, it will automatically start the MCP server. You should see it connect without errors.

#### Step 5: Verify Installation

Ask Claude:
```
What MCP tools do you have available for WordPress audits?
```

Claude should list the wp_baseline, wp_cleanup, and other tools.

---

## Configuration Details

### The .mcp.json File

The `.mcp.json` file tells Claude Code which MCP servers to start. It can be placed in:

- **Project directory** (recommended) - Tools available for that project
- **Home directory** (`~/.mcp.json`) - Tools available globally

Example with multiple servers:
```json
{
  "mcpServers": {
    "wp-audit": {
      "command": "node",
      "args": ["/Users/yourname/wp-audit-mcp/dist/index.js"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-memory"],
      "env": {
        "MEMORY_FILE_PATH": "./.claude/memory.json"
      }
    }
  }
}
```

### How Tools Connect to WP Engine

The MCP server uses SSH to connect to WP Engine and run WP-CLI commands:

```bash
# This is what happens behind the scenes
ssh SITEID@SITEID.ssh.wpengine.net 'wp eval-file /tmp/script.php'
```

The `site_id` parameter you provide is the **WP Engine environment name**, which you can find in:
- WP Engine Portal URL: `my.wpengine.com/installs/SITEID`
- Or in the site's "Overview" page

### SSH Configuration (Optional)

For convenience, you can add WP Engine sites to `~/.ssh/config`:

```
Host wpengine-mysite
    HostName mysite.ssh.wpengine.net
    User mysite
    IdentityFile ~/.ssh/id_ed25519
```

This doesn't affect how the MCP server works, but makes manual SSH easier.

---

## Usage

### Basic Commands

Once installed, just talk to Claude naturally:

```
Audit the WordPress site "mysite" on WP Engine
```

Or be more specific:

```
Use wp_baseline with site_id "mysite"
```

### Example Session

```
You: I need to audit the site "clientsite" - check SEO, clean up the database,
     and fix CloudFlare settings. Zone ID is abc123def456.

Claude: I'll run a comprehensive audit. Let me start with the baseline...
        [Uses wp_baseline]

        Now checking SEO meta descriptions...
        [Uses wp_seo_check]

        I found 15 pages missing meta descriptions. Should I auto-generate them?

You: Yes, generate them.

Claude: [Uses wp_seo_fix with mode "auto"]
        Done. Now checking CloudFlare...
        [Uses cloudflare_check]

        Found issues: SSL is "flexible" (should be "full"), TLS 1.0 (should be 1.2).
        Should I fix these?

You: Yes, fix all CloudFlare issues.

Claude: [Uses cloudflare_fix]
        All CloudFlare settings updated. Let me clear all caches...
        [Uses wp_clear_cache]

        Audit complete! Here's the summary...
```

---

## Tools Reference

### wp_baseline
Run comprehensive baseline audit on a WordPress site.
```
Parameters:
  site_id: WP Engine environment name (required)

Returns: Content counts, database size, orphaned data, SEO status,
         WP Rocket settings, deleted plugin artifacts
```

### wp_cleanup
Clean orphaned data and optimize database.
```
Parameters:
  site_id: WP Engine environment name (required)
  delete_revisions: Delete post revisions (default: true)

Actions: Removes orphaned postmeta, termmeta, commentmeta, auto-drafts,
         transients, old action scheduler entries. Closes pingbacks.
```

### wp_plugin_artifacts
Remove database artifacts from deleted plugins.
```
Parameters:
  site_id: WP Engine environment name (required)
  plugins: Array of plugins to clean (optional - cleans all if empty)
           Options: yoast, rankmath, aioseo, wsal, revslider,
                    layerslider, woocommerce, jetpack
  dry_run: Preview changes without applying (default: false)

Actions: Drops orphaned tables, deletes leftover options
```

### wp_seo_check
Check meta description status for pages/posts.
```
Parameters:
  site_id: WP Engine environment name (required)
  post_type: 'page', 'post', or 'all' (default: 'page')

Returns: Count of pages with/without meta descriptions, list of missing
```

### wp_seo_fix
Add meta descriptions to content.
```
Parameters:
  site_id: WP Engine environment name (required)
  mode: 'auto' or 'manual' (default: 'auto')
  post_type: For auto mode (default: 'page')
  descriptions: For manual mode - {postId: "description"} object
  dry_run: Preview changes (default: false)

Auto mode: Extracts first 155 chars from page content
Manual mode: Sets specific descriptions for specific post IDs
```

### wp_rocket_fix
Check and fix WP Rocket settings.
```
Parameters:
  site_id: WP Engine environment name (required)
  dry_run: Preview changes (default: false)

Fixes: Enables cache preload, sitemap preload, lazy loading, mobile cache
```

### wp_clear_cache
Clear all caches on the site.
```
Parameters:
  site_id: WP Engine environment name (required)

Clears: WordPress object cache, transients, WP Rocket, WP Super Cache,
        Elementor, Beaver Builder, Divi, WP Engine page cache
```

### cloudflare_check
Check CloudFlare security and performance settings.
```
Parameters:
  zone_id: CloudFlare Zone ID (required)
  email: CloudFlare account email (required)
  api_key: CloudFlare Global API Key (required)

Checks: SSL mode, min TLS version, HSTS, Bot Fight Mode,
        AI bot protection, crawler protection
```

### cloudflare_fix
Apply recommended CloudFlare settings.
```
Parameters:
  zone_id: CloudFlare Zone ID (required)
  email: CloudFlare account email (required)
  api_key: CloudFlare Global API Key (required)
  fix_ssl: Fix SSL to 'full' (optional)
  fix_tls: Fix min TLS to 1.2 (optional)
  fix_hsts: Enable HSTS with 6-month max-age (optional)
  fix_bots: Enable bot protection (optional)
  fix_all: Apply all fixes (default: auto-detects what's needed)
```

### ahrefs_extract
Extract and summarize an Ahrefs site audit ZIP file.
```
Parameters:
  zip_path: Full path to Ahrefs ZIP export (required)
  output_dir: Directory to extract to (optional)

Returns: Summary of errors, warnings, and notices from the audit
```

---

## Typical Audit Workflow

1. **Baseline**: `wp_baseline` - Understand the site's current state
2. **Ahrefs**: `ahrefs_extract` - Parse Ahrefs audit file if provided
3. **CloudFlare**: `cloudflare_check` → `cloudflare_fix` - Fix security settings
4. **Database**: `wp_cleanup` → `wp_plugin_artifacts` - Clean up database
5. **SEO**: `wp_seo_check` → `wp_seo_fix` - Fix missing meta descriptions
6. **Caching**: `wp_rocket_fix` - Optimize WP Rocket
7. **Finish**: `wp_clear_cache` - Clear all caches

---

## Troubleshooting

### "SSH connection failed"

1. Verify SSH key is added to WP Engine Portal
2. Test manually: `ssh SITEID@SITEID.ssh.wpengine.net 'echo test'`
3. Check that `site_id` matches the WP Engine environment name exactly

### "MCP server not found"

1. Verify the path in `.mcp.json` is absolute and correct
2. Check that `npm run build` completed without errors
3. Verify `dist/index.js` exists

### "CloudFlare authentication failed"

1. Use the **Global API Key**, not an API Token
2. Verify the email matches your CloudFlare login
3. Check the Zone ID is correct (found in CloudFlare dashboard overview)

### Tools not appearing in Claude

1. Restart Claude Code completely
2. Check `.mcp.json` is in the current directory
3. Look for errors when Claude Code starts

---

## Supported Platforms

- **Windows** - Via Git Bash, WSL, or native (with forward slashes in paths)
- **macOS** - Native terminal
- **Linux** - Native terminal

---

## Development

```bash
# Run in development mode (watches for changes)
npm run dev

# Build for production
npm run build

# The server communicates via stdio, so to test manually:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
```

---

## License

MIT

---

## Contributing

Issues and pull requests welcome at [github.com/markahope-aag/wp-audit-mcp](https://github.com/markahope-aag/wp-audit-mcp).