@respira/wordpress-mcp-server 7.3.0 → 7.4.1

package/skills/seo-aeo-amplifier/SKILL.md

@@ -0,0 +1,277 @@
+# SEO & AEO Amplifier
+
+**Version:** 1.3.0
+**Updated:** 2026-06-30
+**Freshly updated:** v1.3.0 takes a snapshot with respira_get_snapshot before any edit so every change is one-click reversible, switches from full extract/inject to surgical respira_find_element + respira_update_element edits for meta titles, descriptions and H1s, applies schema and meta across many pages in a single safe pass with respira_batch_update, and wires respira_generate_activity_report into the "SEO work done -> client report" handoff. Also leans on the real SEO analysis tools (respira_analyze_seo, respira_analyze_aeo, respira_analyze_rankmath, respira_check_seo_issues, respira_check_structured_data) instead of hand-rolled scoring.
+
+Comprehensive on-page SEO and Answer Engine Optimization (AEO) audit and auto-fix system for WordPress sites. Scans all content, detects issues, generates intelligent schema markup, and creates optimized duplicates for review.
+
+## What This Skill Does
+
+**Finds:**
+- Missing or weak title tags and meta descriptions
+- Poor heading structure (multiple H1s, skipped heading levels, non-descriptive headings)
+- Missing image alt text across all media
+- Thin content (pages under 300 words)
+- Broken internal links
+- Orphaned pages (no internal links pointing to them)
+- Non-descriptive URL slugs
+- Content that could answer questions but lacks FAQ schema
+- Missing structured data (Article, HowTo, Product, Event, Video, Review)
+- Content not optimized for featured snippets
+- Missing table of contents on long-form content
+- No clear Q&A structure for "People Also Ask" boxes
+
+**Provides:**
+- Comprehensive SEO health score (0-100)
+- Page-by-page opportunity analysis
+- Automated duplicate creation with all fixes applied
+- Intelligent schema markup generation based on content type
+- Before/after comparison for every fix
+- Plugin-specific guidance (Yoast SEO, Rank Math, or plugin-agnostic)
+
+**Generates Schema Markup:**
+- Article schema (blog posts, news)
+- FAQ schema (Q&A content detected)
+- HowTo schema (tutorial/guide content)
+- Product schema (WooCommerce products - requires WooCommerce add-on)
+- Event schema (event content detected)
+- Video schema (embedded videos detected)
+- Review schema (review content detected)
+- Breadcrumb schema (site navigation)
+- Organization/Website schema (site-wide)
+
+## Requirements
+
+- Respira for WordPress plugin installed and connected
+- MCP connection active (desktop or WebMCP)
+- WooCommerce add-on (optional - for product schema)
+- Read access to scan site, write access to create duplicates
+
+## Trigger Phrase
+
+- "amplify my seo and aeo"
+
+## Alternative Triggers
+
+- "optimize my site for search engines"
+- "run seo aeo audit"
+- "improve my search visibility"
+- "scan for seo opportunities"
+
+## Execution Workflow
+
+### Phase 1: Comprehensive Audit
+
+1. Verify Respira + MCP connection via `respira_get_site_context`. If unavailable, stop and show setup guidance.
+2. Detect SEO plugin setup using `respira_list_plugins`:
+   - Yoast SEO
+   - Rank Math
+   - No SEO plugin
+3. Scan all published pages and posts:
+   - `respira_list_pages`
+   - `respira_list_posts`
+4. For each content item, load content and metadata:
+   - `respira_read_page` or `respira_read_post`
+   - `respira_get_builder_info` when needed
+5. Analyze on-page SEO. Prefer the real analysis tools over hand-rolled checks:
+   - `respira_analyze_seo` for the on-page SEO pass (title, meta, headings, content depth, links)
+   - `respira_check_seo_issues` for the prioritized issue list per page
+   - `respira_analyze_rankmath` when Rank Math is detected (reads its score and recommendations)
+   - `respira_check_structured_data` to see which schema types already exist vs are missing
+   - Supplement with `respira_list_media` + in-content image checks for alt text coverage
+   - Cross-checks the tools cover: title quality, meta description quality, heading hierarchy (single H1, no level skips), content depth, internal links / orphaned pages, URL slug descriptiveness
+6. Analyze AEO opportunities with `respira_analyze_aeo` (answer-engine readiness), plus `respira_check_structured_data`:
+   - FAQ potential (question patterns)
+   - HowTo potential (step-by-step patterns)
+   - Featured snippet opportunities
+   - Missing table of contents on long-form pages
+   - Missing structured data per content type
+7. Build opportunity scoring:
+   - Critical / High / Medium / Low
+   - Per-page opportunity score (0-100)
+8. Produce full report with:
+   - Overall health score
+   - Priority matrix
+   - Top opportunity pages
+   - Plugin-specific integration notes
+
+### Phase 2: Ask for Confirmation
+
+After report, ask:
+
+> I found [X] pages with SEO/AEO opportunities. Would you like me to create optimized duplicates for all of them? You will review before publishing.
+
+If user declines, stop after delivering recommendations.
+
+### Phase 3: Auto-Fix on Duplicates (Only If Approved)
+
+1. **Snapshot first.** Before touching anything, take a snapshot with `respira_get_snapshot` so the whole pass is one-click reversible via `respira_restore_snapshot` if a fix looks wrong.
+2. For each selected page/post:
+   - Create the review copy with `respira_create_page_duplicate` (pages) or `respira_create_post_duplicate` (posts)
+3. Apply fixes on the duplicate only. Use surgical edits, not full extract/inject:
+   - **Locate the exact node first** with `respira_find_element` (find the meta title, meta description, and the H1 / heading elements), then change only that node with `respira_update_element`. This avoids re-writing the whole page and keeps the builder's structure intact.
+   - Optimize title tags (target < 60 chars)
+   - Generate/rewrite meta descriptions (target 150-160 chars)
+   - Fix heading structure (single H1, logical hierarchy)
+   - Add/repair image alt text
+   - Add table of contents for long-form pages
+   - Restructure Q&A blocks for FAQ readiness
+   - Generate and inject JSON-LD schema markup
+   - Improve URL slug when safe and requested
+4. **Apply the same fix across many pages in one safe pass** with `respira_batch_update` (for example, the same Organization/WebSite schema or a meta pattern across a set of duplicates) instead of looping one slow update at a time.
+5. Save remaining page-level changes with `respira_update_page` / `respira_update_post`.
+6. Verify with `respira_check_seo_issues` / `respira_check_structured_data` on a sample of the fixed duplicates to confirm the issues actually cleared.
+7. Produce before/after comparison snapshots for representative pages.
+8. Summarize totals:
+   - Duplicates created
+   - Titles/meta/schema/alt/headings fixed
+   - Snapshot id (so the user knows the rollback point)
+
+## Plugin Integration Behavior
+
+### Yoast SEO detected
+
+- Read Yoast metadata
+- Populate Yoast-compatible meta fields on duplicates
+- Add JSON-LD schema only where Yoast does not already cover the content type
+- Suggest focus keywords and readability improvements
+
+### Rank Math detected
+
+- Read Rank Math metadata
+- Populate Rank Math-compatible meta fields on duplicates
+- Add JSON-LD schema where missing
+
+### No SEO plugin detected
+
+- Insert meta tags and JSON-LD directly in duplicate content
+- Recommend optional Yoast or Rank Math adoption
+
+## Schema Generation Rules
+
+Generate schema based on detected content intent:
+
+- **Article:** blog/news/editorial content
+- **FAQPage:** clear Q&A content patterns
+- **HowTo:** procedural/step-by-step content
+- **Product:** WooCommerce products (if add-on/tools available)
+- **Event:** event date/location content
+- **VideoObject:** embedded YouTube/Vimeo/video blocks
+- **Review:** clear review/rating content
+- **BreadcrumbList:** URL hierarchy
+- **Organization / WebSite:** site-level identity signals
+
+All schema must be JSON-LD and valid structure-first (no fabricated claims).
+
+## Output Format
+
+Always include:
+
+1. **Executive summary**
+2. **Overall score + severity counts**
+3. **Top opportunities with impact rationale**
+4. **Plugin integration notes**
+5. **Clear confirmation prompt for duplicate creation**
+
+If auto-fix is run, also include:
+
+6. **Fix summary totals**
+7. **Before/after samples**
+8. **Review instructions in WordPress admin**
+
+## Safety Model
+
+- Read-only audit first
+- Snapshot via `respira_get_snapshot` before any write, restore with `respira_restore_snapshot`
+- Explicit user confirmation before changes
+- Duplicate-first changes only
+- Never auto-publish
+- Provide rollback guidance
+- Preserve live content unless user explicitly approves publishing workflow
+
+## Client Report Handoff
+
+When the audit and (optional) fixes are done, turn the SEO work into a deliverable the customer can hand to a client or keep for their own records:
+
+- Call `respira_generate_activity_report` to pull the actual edits made in this session (titles, meta, schema, alt text, headings) into a structured "SEO work done" report.
+- Pair it with the before/after samples and the snapshot id from Phase 3 so the report shows what changed and how to roll it back.
+- Good fit for monthly retainers: run the audit, apply approved fixes on duplicates, then export the activity report as the month's SEO summary.
+
+## Honest Disclaimer
+
+This skill identifies SEO/AEO opportunities and creates optimized duplicates for review.
+
+It cannot:
+- Guarantee rankings
+- Fix off-page SEO or backlinks
+- Fix server-level technical SEO by itself
+- Publish without review
+
+It can:
+- Find broad on-page SEO and AEO gaps
+- Generate structured schema recommendations and implementation
+- Create transparent before/after duplicate drafts quickly
+
+## Tooling
+
+**Core WordPress tools**
+- `respira_get_site_context`
+- `respira_list_pages`
+- `respira_list_posts`
+- `respira_read_page`
+- `respira_read_post`
+- `respira_get_builder_info`
+- `respira_list_media`
+- `respira_list_plugins`
+- `respira_create_page_duplicate`
+- `respira_create_post_duplicate`
+- `respira_update_page`
+- `respira_update_post`
+
+**SEO / AEO analysis tools**
+- `respira_analyze_seo`
+- `respira_analyze_aeo`
+- `respira_analyze_rankmath`
+- `respira_check_seo_issues`
+- `respira_check_structured_data`
+
+**Precision edit + safety tools**
+- `respira_find_element` (locate meta title / description / H1 nodes)
+- `respira_update_element` (change only that node)
+- `respira_batch_update` (apply schema/meta across many pages in one pass)
+- `respira_get_snapshot` (snapshot before edits)
+- `respira_restore_snapshot` (one-click rollback)
+
+**Reporting**
+- `respira_generate_activity_report` (SEO work done -> client report)
+
+**WooCommerce tools (optional)**
+- `woocommerce_list_products`
+- `woocommerce_get_product`
+
+## Telemetry
+
+After run completion, send fire-and-forget usage tracking to:
+
+- `POST https://www.respira.press/api/skills/track-usage`
+
+Include:
+- `skill_slug = seo-aeo-amplifier`
+- site/version context
+- duration and success
+- issues found and fixes applied counts
+- tools used
+
+Never block user flow on telemetry failure.
+
+## Related Skills
+
+- WordPress Site DNA
+- Technical Debt Audit
+- Mobile Experience Report
+
+---
+
+Built by Respira Team  
+https://respira.press/skills/seo-aeo-amplifier

package/skills/seo-aeo-amplifier/metadata.json

@@ -0,0 +1,62 @@
+{
+  "name": "SEO & AEO Amplifier",
+  "slug": "seo-aeo-amplifier",
+  "icon": "🚀",
+  "category": "performance",
+  "description": "Comprehensive on-page SEO and AEO audit with automated optimization. Scans all content, detects issues, generates intelligent schema markup, and creates optimized duplicates for review.",
+  "author": "Respira Team",
+  "author_url": "https://respira.press",
+  "trigger": "amplify my seo and aeo",
+  "requires_respira": true,
+  "requires_woocommerce_addon": false,
+  "requires_accessibility_addon": false,
+  "is_read_only": false,
+  "is_duplicate_first": true,
+  "version": "1.2.0",
+  "last_updated": "2026-05-24",
+  "tools_used": [
+    "respira_get_site_context",
+    "respira_list_pages",
+    "respira_list_posts",
+    "respira_get_page",
+    "respira_get_post",
+    "respira_detect_page_builder",
+    "respira_list_media",
+    "respira_list_plugins",
+    "respira_create_duplicate",
+    "respira_update_page",
+    "respira_update_post",
+    "woocommerce_list_products",
+    "woocommerce_get_product"
+  ],
+  "detects": [
+    "missing_title_tags",
+    "weak_meta_descriptions",
+    "poor_heading_structure",
+    "missing_alt_text",
+    "thin_content",
+    "broken_internal_links",
+    "orphaned_pages",
+    "non_descriptive_urls",
+    "missing_faq_schema",
+    "missing_article_schema",
+    "missing_howto_schema",
+    "missing_toc",
+    "no_qa_structure"
+  ],
+  "generates": [
+    "article_schema",
+    "faq_schema",
+    "howto_schema",
+    "product_schema",
+    "event_schema",
+    "video_schema",
+    "review_schema",
+    "breadcrumb_schema",
+    "organization_schema",
+    "optimized_titles",
+    "optimized_meta_descriptions",
+    "image_alt_text",
+    "table_of_contents"
+  ]
+}

package/skills/stale-content-detector/README.md

@@ -0,0 +1,41 @@
+# Stale Content Detector
+
+> Find the content drag on your site in 30 seconds.
+
+Categorizes every page and post on your site by how long it's been since last update. Tells you what to refresh, what to redirect, and what to archive — based on age, traffic signal, and internal link count.
+
+## What you get
+
+| Bucket | Age | Suggested action |
+|---|---|---|
+| Fresh | < 6 months | leave alone |
+| Aging | 6–12 months | review headline + opener, refresh if outdated |
+| Stale | 12–24 months | refresh content meaningfully |
+| Archive-candidate | 24+ months (low traffic / orphan) | archive, redirect, or 410 |
+
+Plus a "what I'd refresh first" top-5 list ranked by traffic + internal link equity, so you know where to start.
+
+## Why it matters
+
+Stale content is an SEO drag and a credibility tax. If your "2023 trends" article still ranks but nobody's touched it since 2023, you're losing trust the day a reader notices the date. The skill finds these items fast so you can decide: refresh, redirect, or archive.
+
+## Triggers
+
+- *"find old content"*
+- *"what's stale"*
+- *"what needs refreshing"*
+- *"audit my content age"*
+- *"what should I archive"*
+
+## Hard rule
+
+Never deletes a page directly. Even archive-candidates get a recommendation, not a deletion. You decide.
+
+## Pairs with
+
+[SEO & AEO Amplifier](https://respira.press/skills/seo-aeo-amplifier) — once you've identified what to refresh, the Amplifier handles the actual content updates.
+
+## Requires
+
+- Respira for WordPress plugin
+- MCP server connected

package/skills/stale-content-detector/SKILL.md

@@ -0,0 +1,156 @@
+# Stale Content Detector
+
+**Version:** 1.0.0
+**Updated:** 2026-05-24
+**Category:** audit
+**Status:** stable
+**Requires:** Respira for WordPress plugin 7.1+ + MCP server
+
+---
+
+## Description
+
+Find pages and posts that haven't been updated in a long time, categorize them as fresh / aging / stale / archive-candidate, and suggest action per item: refresh, redirect, archive, or leave alone. Stale content is an SEO drag and a credibility tax — if your "2023 trends" article still ranks but nobody's touched it since 2023, you're losing trust the day a reader notices the date.
+
+This skill is intentionally focused. It's not a content audit (use [SEO & AEO Amplifier](https://respira.press/skills/seo-aeo-amplifier) for that). It's the "what's old" question, answered fast.
+
+---
+
+## What it categorizes
+
+| Bucket | Age since last update | Suggested action |
+|---|---|---|
+| Fresh | < 6 months | leave alone |
+| Aging | 6–12 months | review the headline + opening paragraph; if still accurate, leave; if outdated, refresh the date |
+| Stale | 12–24 months | refresh the content meaningfully (new data, new examples), update the modified date |
+| Archive-candidate | 24+ months **and** low traffic / orphan | archive, redirect, or 410 — depends on if anything links to it |
+
+Plus an "evergreen" override: pages tagged as evergreen (`/about/`, `/contact/`, `/pricing/`, `/privacy/`) skip the staleness check entirely.
+
+---
+
+## When to Use
+
+- Quarterly content review
+- Migrating a site and trying to decide what to bring vs leave behind
+- After a content team change — find the inherited backlog of old work
+- Before publishing the next batch of new content (so the old stuff doesn't drag the rankings of the new stuff)
+- After a Google update that emphasizes "freshness" signals
+
+---
+
+## Trigger Phrases
+
+- "find old content"
+- "what's stale"
+- "what needs refreshing"
+- "audit my content age"
+- "find content to update"
+- "stale content scan"
+- "what should i archive"
+
+---
+
+## Execution Workflow
+
+### Step 1 — Confirm site
+
+Call `respira_get_active_site` + `respira_get_site_context`.
+
+### Step 2 — Pull pages and posts
+
+Call:
+
+- `respira_list_pages(per_page=100)` for pages
+- `respira_list_posts(per_page=100, status=publish)` for posts
+- `respira_list_custom_posts(post_type=<each non-default CPT>, per_page=100)` for any CPT detected via `respira_list_post_types`
+
+Each result includes `modified` and `date`. Sort by `modified` ascending — oldest first.
+
+### Step 3 — Identify evergreen pages
+
+Pull the list of pages and check each against the evergreen list (`/about`, `/contact`, `/pricing`, `/privacy`, `/terms`, `/legal`, `/imprint`, `/faq`, `/support`). If the URL or slug matches, flag as evergreen and skip the staleness check.
+
+Also check if the post type has `has_archive=false` and a single URL pattern matching contact/legal/utility — those are usually evergreen.
+
+### Step 4 — Compute staleness
+
+For each non-evergreen page or post, compute days-since-modified. Bucket:
+
+- 0–180 days → **fresh**
+- 181–365 days → **aging**
+- 366–730 days → **stale**
+- 731+ days → **archive-candidate** (further filtering in Step 5)
+
+### Step 5 — Add traffic + orphan signals (archive-candidate filter)
+
+For items in the archive-candidate bucket, we need to know if anyone is reading them or linking to them. Two signals:
+
+1. **Internal link count.** Call `respira_find_element` with the page's URL as a search term. Count incoming internal links. If zero, the page is an orphan.
+2. **External traffic** (if available — depends on whether the site has Plausible / GA4 / similar wired to Respira). If not available, skip.
+
+Recompute:
+
+- Archive-candidate + orphan + no traffic → **archive (or 410)**
+- Archive-candidate + has internal links + no traffic → **archive + redirect** (preserve link equity)
+- Archive-candidate + has traffic → **refresh** (downgrade from archive-candidate to stale)
+
+### Step 6 — Output the report
+
+```markdown
+## Content age audit for {site_url}
+
+Scanned {n_pages} pages + {n_posts} posts + {n_custom} custom posts ({n_total} total). Evergreen pages skipped: {n_evergreen}.
+
+### Summary
+
+| Bucket | Count | % |
+|---|---|---|
+| Fresh (<6mo) | {n_fresh} | {pct_fresh}% |
+| Aging (6–12mo) | {n_aging} | {pct_aging}% |
+| Stale (12–24mo) | {n_stale} | {pct_stale}% |
+| Archive-candidate (24+mo) | {n_archive} | {pct_archive}% |
+
+### Stale (12–24 months)
+
+| Title | Last modified | Action |
+|---|---|---|
+| {title} | {modified} ({days_ago}d) | refresh |
+| ... | | |
+
+### Archive-candidate (24+ months)
+
+| Title | Last modified | Internal links | Suggested action |
+|---|---|---|---|
+| {title} | {modified} ({days_ago}d) | {link_count} | {action} |
+| ... | | | |
+
+### What I'd refresh first (top 5 by traffic or link equity)
+
+1. **{title}** ({days_ago}d old) — {one-line reason: high incoming link count / high traffic / topical relevance to current focus}
+2. ...
+```
+
+### Step 7 — Offer to act on a chosen item
+
+Ask: *"Want me to refresh one of these now? I can pull the existing content, suggest updates, create a duplicate with the refresh applied, and you review."*
+
+If yes, route to the SEO & AEO Amplifier skill or directly compose `respira_create_page_duplicate` + targeted updates.
+
+---
+
+## Hard rules
+
+- **Never delete a page directly.** Even archive-candidates get a recommendation, not a deletion. The user decides. Use `respira_delete_page` only if the user explicitly asks for deletion of a specific named page.
+- **The evergreen list is opinionated but overridable.** Output the list at the top of the report so the user can see what got skipped and add/remove items.
+- **Don't conflate stale with bad.** A 2-year-old page that still has 1,000 monthly views is not a problem. The "refresh" recommendation is based on age, not quality.
+- **Modified date is canonical.** Don't read `date` (published) as a staleness signal. A 2018 post updated last month is fresh.
+- **Custom post types matter.** Case studies, podcast episodes, properties — these often need different staleness windows. If the user runs a podcast and the latest episode is 6 months old, that's stale for podcast content even though "fresh" for blog posts. Offer to set per-CPT windows on a v1.1 of this skill.
+
+---
+
+## Telemetry
+
+Records: site URL hash, n_pages / n_posts / n_custom counted, bucket distribution, success/failure, total duration. No page titles, no URLs, no decisions sent.
+
+Endpoint: `POST https://www.respira.press/api/skills/track-usage`

package/skills/stale-content-detector/metadata.json

@@ -0,0 +1,43 @@
+{
+  "name": "Stale Content Detector",
+  "slug": "stale-content-detector",
+  "icon": "🕰️",
+  "category": "audit",
+  "description": "Find pages and posts that haven't been updated in a long time. Categorize as fresh / aging / stale / archive-candidate. Suggest refresh, redirect, or archive per item — based on age, traffic signal, and internal link count.",
+  "author": "Respira Team",
+  "author_url": "https://respira.press",
+  "trigger": "find old content",
+  "requires_respira": true,
+  "requires_woocommerce_addon": false,
+  "requires_accessibility_addon": false,
+  "is_read_only": true,
+  "is_duplicate_first": false,
+  "version": "1.0.0",
+  "last_updated": "2026-05-24",
+  "tools_used": [
+    "respira_get_active_site",
+    "respira_get_site_context",
+    "respira_list_pages",
+    "respira_list_posts",
+    "respira_list_post_types",
+    "respira_list_custom_posts",
+    "respira_find_element"
+  ],
+  "detects": [
+    "modified_date",
+    "evergreen_pages",
+    "fresh_content",
+    "aging_content",
+    "stale_content",
+    "archive_candidate_content",
+    "orphan_pages",
+    "internal_link_count"
+  ],
+  "generates": [
+    "staleness_bucket_distribution",
+    "stale_items_table",
+    "archive_candidates_table",
+    "refresh_priority_list",
+    "per_item_action_recommendation"
+  ]
+}