@rolepod/wplab

rolepod-wplab

🌐 New here? See what AI can actually do on your WordPress site — plain-English breakdown of the 3 setup tiers.

rolepod-wplab gives Claude Code, Cursor, Codex CLI, Gemini CLI, and opencode a full WordPress operations toolkit — so the AI can actually wp-cli, edit page builders, audit security, migrate dev→staging, and (opt-in) run guarded execute-php against any WordPress site instead of guessing.

One MCP server, 89+ tools, 15 skills, 4 connection kinds (local path / REST + App Password / SSH / Docker). Default-safe — runs wp-cli + REST + scoped fs out of the box. Install the rolepod-wp WordPress plugin to unlock execute-php + runtime introspection + the one-click pair setup wizard.

Standalone vs Combined

Standalone: complete WordPress operations toolkit. 15 skills + 139 MCP tools cover the full lifecycle — connect, introspect, edit, verify, migrate. Use directly via skill commands. No external dependencies.

Combined with rolepod parent (v2.7+): wplab phase-flavored skills narrow to WP-specific tool roles, deferring workflow orchestration to parent. Same 15 skills, smarter division of labor. Detection is a single filesystem marker (<git-root>/.rolepod/parent-active containing v1) written by the parent's SessionStart hook — no install-time coupling, no env-var propagation problems across Claude Code's subprocess boundaries.

Mode summary

Install combos

Evidence path convention:

• standalone: .rolepod-wplab/artifacts/<ts>/
• with-parent: .rolepod/evidence/<ts>-rolepod-wplab-<skill>/

Manifest schema (Extension Protocol v1): src/lib/rolepodEvidence.ts.

What it helps with

• Connect any WP install in one command. connect_local, connect_rest, connect_ssh, connect_docker — same tool surface, four ways to reach a site. App Passwords stored in the OS keychain, never echoed.
• One-click pair via companion. Admin opens Tools → WPLab Setup → clicks "⚡ Generate setup prompt" → pastes the prompt into the AI → AI calls rolepod_wp_pair { siteurl, pair_token } and is connected with full power tools. Token single-use, 60-min TTL.
• Edit page builders without leaving chat. divi_{read,write}, oxygen_{read,write}, bricks_{read,write}, elementor_{read,write} — all backed up before overwrite.
• Bulk SEO + WPML + ACF + Woo writes. yoast_write, rankmath_write, wpml_write (link translations, duplicate for translation), woo_write (bulk price updates), acf_write.
• Scaffold blocks, plugins, themes, patterns. scaffold_block, scaffold_plugin, scaffold_theme, scaffold_pattern — register-block-type-ready files into existing themes/plugins.
• Audit + migrate across many sites. audit_security, audit_many (consolidated report for N sites), migrate_dryrun + migrate_data (plugin version sync dev→staging), clone (full db + wp-content + URL rewrite).
• Diagnose + back up before risky ops. diagnose (plugin conflicts / slow queries / large autoloads / php errors), backup_create + backup_restore, cache_tool, cron_tool, mail_test.
• Audit wp-admin without anyone logging in. rolepod_wp_admin_one_time_link(target_id, destination) mints a 5-minute single-use URL; hand it to rolepod-uiproof browser_open, or to any other browser automation on the machine (Chrome MCP, Playwright) — the link is a plain URL, so not having uiproof blocks nothing — and the whole browser session stays signed in as the admin. The AI says which it used, so nobody waits for a login prompt that never comes; a person clicking the link is the last resort. Whoever opens it holds a full admin session, and a HAR or trace recorded during it contains the auth cookie — treat those as credentials.
• Safe execute-php (companion only). AST screen on Node side AND PHP side, production-block unconditional, append-only audit log.

The 15 skills

Every skill is single-backend — calls the rolepod-wplab server and only this server. If the server is unavailable, the skill fails with a clear diagnostic.

Install

Pick your CLI. All install paths share the same MCP server (@rolepod/wplab on npm) and the same skill set.

Claude Code (recommended)

# Install
claude plugin marketplace add nuttaruj/rolepod-wplab
claude plugin install rolepod-wplab@rolepod-wplab

# Update
claude plugin marketplace update rolepod-wplab
claude plugin install rolepod-wplab@rolepod-wplab

# Uninstall
claude plugin uninstall rolepod-wplab@rolepod-wplab
claude plugin marketplace remove rolepod-wplab

The plugin auto-registers the 14 /wp-* skills AND spawns the MCP server (npx -y @rolepod/wplab@latest serve) on session start.

Cursor IDE

Cursor's plugin marketplace is enterprise-only (Free / Pro cannot install marketplace plugins). For everyone else, drop the workspace MCP config:

# Per project
mkdir -p .cursor
curl -fsSL https://raw.githubusercontent.com/nuttaruj/rolepod-wplab/main/.cursor/mcp.json -o .cursor/mcp.json

# Or global (across every project)
mkdir -p ~/.cursor
curl -fsSL https://raw.githubusercontent.com/nuttaruj/rolepod-wplab/main/.cursor/mcp.json -o ~/.cursor/mcp.json

Then fully restart Cursor — MCP servers load only at startup. Verify under Settings → MCP.

Update: re-run the curl command above to overwrite .cursor/mcp.json, then restart Cursor. Uninstall: delete .cursor/mcp.json (or ~/.cursor/mcp.json for the global install) and restart.

Skills are not auto-registered under Cursor (no unified plugin format yet). The 139 MCP tools are still available; invoke them by name in chat (Use rolepod_wp_pair to …).

Codex CLI

# Install (reads .agents/plugins/marketplace.json + .codex-plugin/plugin.json)
codex plugin marketplace add nuttaruj/rolepod-wplab
codex plugin add rolepod-wplab@rolepod-wplab

# Update
codex plugin marketplace remove rolepod-wplab
codex plugin marketplace add nuttaruj/rolepod-wplab
codex plugin add rolepod-wplab@rolepod-wplab

# Uninstall
codex plugin remove rolepod-wplab@rolepod-wplab
codex plugin marketplace remove rolepod-wplab

If the MCP server doesn't show up in Codex's Settings → MCP after install, fully restart Codex — MCP servers load only at startup.

Or drop-in config (no plugin install — just MCP wiring, also works as "uninstall via config-edit"):

# ~/.codex/config.toml
[mcp_servers.rolepod-wplab]
command = "npx"
args = ["-y", "@rolepod/wplab@latest", "serve"]

Gemini CLI

// ~/.gemini/settings.json
{
  "mcpServers": {
    "rolepod-wplab": {
      "command": "npx",
      "args": ["-y", "@rolepod/wplab@latest", "serve"]
    }
  }
}

Update: no command needed — npx -y @rolepod/wplab@latest serve pulls the latest version on every Gemini restart. Uninstall: remove the rolepod-wplab entry from ~/.gemini/settings.json and restart.

Skills are not auto-registered under Gemini (no unified plugin format yet — gemini-extension.json is still in flux). The 139 MCP tools are still available; invoke them by name in chat (Use rolepod_wp_pair to …).

opencode

One command wires both the MCP server and the skills: it merges a rolepod-wplab server entry and this repo's skill catalog into opencode's config and touches nothing else. Install and update are the same command:

# Global (every project) → ~/.config/opencode/opencode.json
curl -fsSL https://raw.githubusercontent.com/nuttaruj/rolepod-wplab/main/scripts/install-opencode.sh | bash

# This project only → ./.opencode/opencode.json
curl -fsSL https://raw.githubusercontent.com/nuttaruj/rolepod-wplab/main/scripts/install-opencode.sh | bash -s -- --project

# Remove (only the rolepod-wplab entry and its catalog URL are touched)
curl -fsSL https://raw.githubusercontent.com/nuttaruj/rolepod-wplab/main/scripts/install-opencode.sh | bash -s -- --uninstall

# Pin a release tag instead of @latest + main (the variable goes on bash, not on curl)
curl -fsSL https://raw.githubusercontent.com/nuttaruj/rolepod-wplab/main/scripts/install-opencode.sh | ROLEPOD_WPLAB_REF=vX.Y.Z bash

Then opencode service restart. The first prompt in a project connects the server; after that opencode mcp list shows rolepod-wplab connected (before it, the command reports the service's not-yet-loaded instance as No MCP servers configured). Tools surface as rolepod-wplab_<tool>, e.g. rolepod-wplab_rolepod_wp_health_check; skills as /wp-health-check etc., or the model loads one through its skill tool.

What the script writes — paste it by hand if you'd rather not run it:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "rolepod-wplab": {
        "type": "local",
        "command": ["npx", "-y", "@rolepod/wplab@latest", "serve"],
        "environment": { "npm_config_audit": "false", "npm_config_fund": "false" },
        "codemode": false
      }
    }
  },
  "skills": ["https://raw.githubusercontent.com/nuttaruj/rolepod-wplab/main/skills/"]
}

Notes:

• Needs node (the MCP server runs on Node ≥20 anyway) and a plain-JSON config: a file with comments or trailing commas is refused, never rewritten. The previous file is kept as opencode.json.rolepod-wplab-bak.
• Skills come from skills/index.json, an opencode HTTP catalog: opencode fetches every skills/<name>/SKILL.md it lists (plus each skill's references/, examples/ and templates/) and caches them by version, so a new release refreshes the skills without touching your config.
• Why codemode: false: opencode v2 wraps MCP servers in Code Mode by default — the model gets a generic execute/query pair and none of the tools by name, so the skills' by-name calls (rolepod_wp_pair, rolepod_wp_health_check, …) never resolve. With Code Mode off the tools are exposed directly, the same as in every other CLI.
• Why the environment block: a cold npx runs npm audit against the registry, which can take minutes and blows opencode's 30 s startup timeout. With audit and fund off the cold start is seconds.
• A shell that exports OPENCODE_CONFIG_DIR starts opencode with that directory read as well, at higher priority than the global one; the script installs globally and says so, and ROLEPOD_WPLAB_OPENCODE_TARGET="$OPENCODE_CONFIG_DIR" installs there instead.
• From a checkout of this repo, scripts/install-opencode.sh --project points the server at the checkout's own build (npm run build first) — inside this repo npx @rolepod/wplab@<v> resolves to the local package and fails.
• Verified on opencode 2.0.12 (v2 config shape: mcp.servers.<name>, environment, disabled). A v1-style entry (mcp.<name> with enabled) is still normalized by v2; the script replaces one if present.

Direct npm (any MCP-aware tool)

{
  "mcpServers": {
    "rolepod-wplab": {
      "command": "npx",
      "args": ["-y", "@rolepod/wplab@latest", "serve"]
    }
  }
}

139 MCP tools (rolepod_wp_*) will appear in your client. Skills are not surfaced via this path — call the tools by name.

Update: npx -y @rolepod/wplab@latest … always fetches the latest published version. Pin to an exact version (e.g. @rolepod/[email protected]) if you want lockstep behavior. Uninstall: remove the rolepod-wplab entry from your client's MCP config.

Quick start

Path A — one-click pair (recommended)

# 1. Install the Rolepod for WordPress plugin on your WP site (stable URL, always latest)
wp plugin install \
  https://github.com/nuttaruj/rolepod-wp/releases/latest/download/rolepod-wp.zip \
  --activate

# 2. WP admin → Tools → Rolepod WP Setup → ⚡ Generate setup prompt → copy

# 3. Paste prompt into Claude Code / Cursor / Codex / Gemini → AI calls rolepod_wp_pair → done

The pair token is single-use, 60-min TTL. The plugin mints a WP Application Password named wplab-pair-<UTC-timestamp> under your admin user — revocable from profile.php at any time.

The WP plugin (rolepod-wp) is the WordPress arm of the broader Rolepod ecosystem, parallel to rolepod-uiproof. Source: nuttaruj/rolepod-wp. End users do not need to read that repo — everything they need is on this page.

Path B — manual App Password (last resort)

Use only when the plugin cannot be installed (no plugin-install rights, host blocks uploads) or you explicitly do not want it. Path A is one-click and mints + stores the credential for you; here you do those steps by hand.

# 1. Create an App Password: WP admin → Users → Profile → Application Passwords
# 2. Store locally (vault uses OS keychain when available)
rolepod-wplab credentials add walnutztudio.com

# 3. In your AI CLI:
#    "เชื่อม walnutztudio.com แล้ว run health_check"
# Lead → rolepod_wp_connect_rest { url: "https://walnutztudio.com" }

Path B works without the companion plugin — you get all 139 MCP tools EXCEPT execute_php, introspect, hook_state, mail_test (those need the companion).

Verify your setup

npx rolepod-wplab doctor

✓ Node ≥20                       24.14.0
✓ rolepod-wplab MCP binary       1.2.2
✓ wp-cli on PATH                 wp-cli 2.12.0
✓ Credential vault writable      ~/.config/rolepod-wplab/credentials.json (or keychain)
✓ Memory dir writable            ~/.config/rolepod-wplab/memory/
• Docker daemon (optional)       Not running — only needed for connect_docker
• SSH agent (optional)           Not configured — only needed for connect_ssh

✓ = ready · • = optional · ✗ = blocker.

What's inside

• 139 MCP tools — connectivity (4 kinds) + wp-cli passthrough + typed CRUD + page-builder adapters (Elementor / Divi / Oxygen / Bricks) + SEO/i18n (Yoast / RankMath / WPML) + WooCommerce + ACF + forms (Gravity / CF7 / WPForms) + cron + cache + mail + clone + backup + diagnose + scaffold (block / plugin / theme / pattern) + REST dump + user sessions + companion-gated (execute*php / introspect / hook_state) + pair (one-click setup). All prefixed rolepod_wp*\*.
• 4 connection kinds — LocalTarget (filesystem + wp-cli), RestTarget (HTTPS + App Password, no shell needed), SshTarget (node-ssh), DockerTarget (dockerode). Same Target interface, same tools.
• 3 profiles — strict / personal / power. Profile-gated capability map (power required for execute_php; strict blocks all destructive ops).
• Safety floor that always applies — wp-cli allow-list (3-token prefix match, hard-block on db reset/db drop/core multisite-convert), DB SELECT-only by default, scoped fs (resolves symlinks; refuses paths outside wp-content/{themes,plugins,uploads} + wp-config.php), AST screen on every execute_php payload (Node side + PHP side), production-host glob match with unconditional block on power tools, HTTPS-only RestTarget, OS-keychain credential vault.
• Per-site memory — memory_recall / memory_note / memory_list keep context between sessions at ~/.config/rolepod-wplab/memory/<site>/. Local files, $0, no SaaS.
• Audit trail — every companion execute_php writes append-only wplab_audit_<id>.log (mode 0600) + a 1000-entry FIFO in wp_options.

Companion WP plugin

The rolepod-wp WordPress plugin (the WP arm of the Rolepod ecosystem) is optional. Without it, wplab is a complete wp-cli + REST + scoped fs toolkit. With it, you get:

• One-click pair — Tools → Rolepod WP Setup → ⚡ Generate setup prompt produces a ready-to-paste prompt for any AI CLI.
• execute-php — runtime PHP eval, AST-screened, production-blocked.
• introspect — hooks / transients / options / request-state read at runtime.
• mid-request observation + persistent PHP session.

wp plugin install \
  https://github.com/nuttaruj/rolepod-wp/releases/latest/download/rolepod-wp.zip \
  --activate

Use with parent rolepod

If you also use rolepod (the markdown plugin), its phase skills auto-route WP work to rolepod-wplab when the server is present. The two are independent: install rolepod-wplab standalone and get a complete experience via slash commands, or install both together and let parent's phase router pick the right backend automatically.

Docs

• docs/RECIPES.md — 23 end-to-end recipes (connect, scaffold, audit, migrate, edit page builders, pair, diagnose, clone, backup).
• CHANGELOG.md — release history.
• CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md.

Sibling repos

• rolepod — parent ecosystem (markdown plugin + phase router).
• rolepod-wp — optional WP plugin for runtime PHP context + one-click pair.
• rolepod-uiproof — UI / mobile automation sibling.

MIT licensed — see LICENSE. Independent implementation, written from spec, not derived from any GPL/AGPL WordPress AI plugin. Feedback + runtime reports for Cursor / Codex / Gemini install paths especially welcome via issues.