---
name: wordpress-seo-cleanup
description: Use when asked to clean up on-page SEO for a WordPress site connected via Cowboy MCP — audits titles, slugs, excerpts, and internal links, then fixes them behind a checkpoint. Notes it cannot create redirects.
---

# WordPress SEO cleanup

Tidy the on-page SEO of a WordPress site through Cowboy MCP: audit titles, slugs, excerpts, and internal links, then fix them safely. Read first, checkpoint before any edit, and be careful with slugs — this toolset has no redirect tool, so a changed URL is a changed URL.

## Before you start

1. Detect the SEO plugin: call `wp_seo_get_provider` (Yoast, Rank Math, or none). This decides how meta titles and descriptions are stored (see Notes).
2. Confirm the connection with `wp_site_info` and review the permalink structure it reports.
3. Create a database checkpoint with `wp_create_checkpoint` (label it "seo-cleanup") and confirm it with `wp_list_checkpoints` before editing.

## Steps

1. **Audit content (read-only).** Call `wp_list_posts` to inventory posts and pages, flagging missing excerpts, weak or duplicate titles, and non-descriptive slugs. Use `wp_get_post` to read a page's title, slug, excerpt, and meta.
2. **Audit rewrite rules (read-only).** Call `wp_get_rewrite_rules` to review the permalink rules and test specific URL paths, so you understand what a slug change would break.
3. **Database hygiene (read-only).** Call `wp_db_health_report` for revision bloat, auto-drafts, and orphaned postmeta worth cleaning.
4. **Fix on-page fields.** Call `wp_update_post` for one post at a time to set a better `title`, `excerpt`, or `slug`. Title and excerpt are safe; treat `slug` as high-risk (step 6).
5. **Fix plugin SEO meta (Rank Math only).** If Rank Math is active, its meta keys (`rank_math_title`, `rank_math_description`) are plain and writable via `wp_update_post`'s `meta` object. Yoast stores these under underscore-protected keys MCP will not write — set those in the Yoast interface.
6. **Repoint internal links after a slug change.** Changing a published slug 404s the old URL, and there is no redirect tool here. After any slug change, call `wp_search_replace` (it defaults to `dry_run: true`) to update internal links pointing at the old URL, and set up a redirect at the server or with a redirect plugin yourself.

## Notes

- The provider-independent SEO levers are the native post fields: `title` (the page `<title>`), `slug` (the URL), and `excerpt` (the meta-description fallback and social snippet). Prefer these.
- No redirect tool exists in this toolset. Never bulk-change slugs on indexed URLs expecting redirects to appear — they will not.
- `wp_search_replace` is destructive; keep `dry_run: true` for the preview, review the match count, then run it again with `dry_run: false`.
- Undo one edit with `wp_undo_change`; restore the whole session with `wp_restore_checkpoint`.

## Report format

Summarize back to the site owner:
- Titles, excerpts, and slugs changed, each old to new, with slug changes called out separately.
- Rank Math meta updated, or a note that Yoast meta needs the plugin interface.
- Any internal-link search-replace run, with the match count.
- Slugs you did NOT change because they would break live URLs without a redirect.
- The checkpoint id for a full rollback via `wp_restore_checkpoint`.