@respira/wordpress-mcp-server 7.3.0 → 7.4.1

package/skills/html-to-bricks/README.md

@@ -0,0 +1,43 @@
+# HTML to Bricks Builder
+
+> Convert raw HTML/CSS into native Bricks elements — design system bound, ACSS aware.
+
+A designer hands you HTML/CSS from a Webflow export. Or you have an old static page you want to bring into your live Bricks site. Or you exported from Figma and need to land it in Bricks for further editing. This skill converts the HTML into a native Bricks element tree, with three protections built in.
+
+## What it does
+
+1. Converts HTML/CSS into Bricks elements (`section`, `block`, `container`, `heading`, `text-basic`, `button`, `image`, etc.) — never inline HTML
+2. **Maps colors and typography to your design system tokens** — so when the design system updates, the page updates with it
+3. **ACSS class mapping** when ACSS is installed — uses ACSS utilities for spacing and typography instead of inline settings
+4. SafeEdit on existing pages — never overwrites a live page directly
+
+## Three input modes
+
+- Paste HTML directly in the conversation
+- Give a public URL (the skill fetches the HTML; external images are flagged, not silently mirrored)
+- Reference an HTML file
+
+## Why this resolves the open feature request
+
+The top open feature request on the Respira board was "HTML to Bricks Builder." It's the most common pain point for designers handing off work to WordPress agencies. This skill closes that gap.
+
+## Triggers
+
+- *"convert this html to bricks"*
+- *"import this design into bricks"*
+- *"paste html into bricks"*
+- *"turn this html into a bricks page"*
+
+## Requires
+
+- Respira for WordPress plugin
+- **Bricks Builder active** (the skill verifies and stops if Bricks isn't the active builder)
+- MCP server connected
+- Recommended: design system synthesized first so token mapping works
+
+## What it does NOT do
+
+- Convert HTML for Elementor, Divi, Gutenberg, or other builders (use the generic `convert_html_to_builder` workflow instead)
+- Re-host external images automatically (flagged, never silently mirrored)
+- Convert HTML forms into Bricks Form element 1:1 (flagged; you wire the form manually)
+- Convert CSS keyframe animations (flagged)

package/skills/html-to-bricks/SKILL.md

@@ -0,0 +1,135 @@
+# HTML to Bricks Builder
+
+**Version:** 1.0.0
+**Updated:** 2026-05-24
+**Category:** migration
+**Status:** stable
+**Requires:** Respira for WordPress plugin 7.1+ + Bricks Builder active + MCP server
+
+---
+
+## Description
+
+Convert raw HTML/CSS — pasted from a design export, a Figma extraction, an existing landing page on another platform, or a competitor's source code — into native Bricks Builder elements. Not a screenshot-to-builder pass; this is a structural conversion that respects Bricks' element schemas, ACSS classes (if installed), and the site's design system.
+
+Resolves [open feature request: HTML to Bricks Builder]. Uses the existing `respira_convert_html_to_builder` MCP tool, with a Bricks-specific workflow layered on top.
+
+---
+
+## When to Use
+
+- A designer hands you HTML/CSS from a Webflow export, a Framer export, or a CodePen
+- You're rebuilding a competitor's landing page (legally — don't copy proprietary work) and want to start from their structure
+- You have an old static HTML page you want to bring into your live Bricks-powered site
+- You're prototyping a section in HTML and want to land it in Bricks for further editing
+
+---
+
+## Trigger Phrases
+
+- "convert this html to bricks"
+- "import this design into bricks"
+- "paste html into bricks"
+- "html to bricks"
+- "turn this html into a bricks page"
+- "bring this codepen into bricks"
+
+---
+
+## Execution Workflow
+
+### Step 1 — Verify Bricks is active
+
+Call `respira_get_builder_info`. If the active builder is NOT Bricks, stop and tell the user: *"This skill targets Bricks Builder. Your active builder is {X}. Use the generic `convert html to builder` workflow instead, or switch the active builder."*
+
+If Bricks is active, capture its version.
+
+### Step 2 — Confirm site + target page
+
+Call `respira_get_active_site`. Ask:
+
+- *"Convert the HTML into a new page (I'll create it), or into an existing page (you tell me which)?"*
+- If existing: confirm the page ID and remind the user that a SafeEdit duplicate will be created.
+
+### Step 3 — Pull design system if present
+
+Call `respira_get_option('respira_design_system')`. If present, capture colors, typography, spacing tokens. The conversion will map raw CSS values (e.g. `#2563EB`) to design system tokens (e.g. `primary`) so the converted page is drift-resistant.
+
+### Step 4 — Accept the HTML input
+
+Three input modes:
+
+- **Mode A — pasted in the conversation.** The user pastes raw HTML directly.
+- **Mode B — URL.** The user gives a public URL; fetch the HTML via WebFetch or `/browse`. **Do NOT silently re-host external assets**; flag external images so the user can decide to mirror them.
+- **Mode C — file.** The user uploads or references a local HTML file path.
+
+In all modes, also accept inline `<style>` blocks and external `<link rel=stylesheet>` references. For external stylesheets, fetch their text content.
+
+### Step 5 — Run the conversion
+
+Call `respira_convert_html_to_builder` with `builder=bricks`, the HTML, the CSS, and the design-system context.
+
+The MCP tool returns a Bricks element tree. Each element has a `name` (Bricks element type — `section`, `block`, `container`, `heading`, `text-basic`, `button`, `image`, etc.) and `settings` matching the Bricks schema.
+
+### Step 6 — Map raw values to design system tokens
+
+For each element in the tree:
+
+- If `settings.color` is a hex value matching one of the design system colors, replace with a token reference
+- If `settings.typography.font-family` matches the design system heading or body family, replace with a token reference
+- If `settings.padding`, `settings.margin`, `settings.gap` are pixel values matching the design system spacing scale, replace with token references
+
+This step is the difference between a one-off conversion and a maintainable page. After the conversion, if the user updates the design system, the converted page reflects it.
+
+### Step 7 — ACSS class mapping (if ACSS detected)
+
+Call `respira_get_option('automatic_css_settings')` or check the active theme for ACSS. If ACSS is installed:
+
+- Map common CSS patterns to ACSS classes
+- `padding: 96px 24px` → ACSS section padding utility
+- `max-width: 1280px; margin: 0 auto` → ACSS container class
+- Heading font sizes → ACSS heading scale classes
+
+This is optional and gated on ACSS being present. If ACSS isn't installed, fall through to inline settings.
+
+### Step 8 — Inject into the page
+
+For a new page: call `respira_build_page` with the Bricks element tree as the page body.
+
+For an existing page: call `respira_create_page_duplicate` first (SafeEdit), then `respira_inject_builder_content` against the duplicate.
+
+Output the new (or duplicate) page URL.
+
+### Step 9 — Verify
+
+Open the new page in the Bricks editor (the URL pattern is `/?bricks=run&page_id={id}`). Visually verify:
+
+- All sections render
+- Typography looks correct
+- Colors map to design system tokens
+- Spacing is consistent
+- Images load (warn if any external image URLs were preserved unmirrored)
+
+If anything is off, the user can refine in the Bricks editor directly. Common issues to flag:
+
+- HTML elements Bricks doesn't have a 1:1 mapping for (e.g. `<details>` collapsible → mapped to Bricks accordion)
+- Forms — HTML `<form>` doesn't convert into Bricks Form element 1:1. Flag and ask the user to wire the form fields manually.
+- Custom animations — CSS keyframes don't convert. Flag.
+
+---
+
+## Hard rules
+
+- **Bricks-only.** This skill is locked to Bricks. For other builders, use the generic `convert_html_to_builder` workflow.
+- **Never inject HTML directly into the page body.** If the conversion can't map an HTML element to a Bricks element, the skill must report the failure and let the user decide. Do not fall back to a "code block" element that pastes raw HTML — that recreates the do-not-write-raw-HTML failure mode.
+- **External assets are flagged, not mirrored.** Don't silently download external images and side-load them. Flag them so the user explicitly decides to mirror.
+- **Always SafeEdit on existing pages.** Never convert HTML into a live page directly. Duplicate first.
+- **Design system tokens take precedence over raw values.** When a CSS hex matches a design system color, use the token. Always.
+
+---
+
+## Telemetry
+
+Records: site URL hash, Bricks version, HTML input size (bytes), elements converted count, design system bound, ACSS detected, success/failure, total duration. No HTML content, no element names, no page IDs sent.
+
+Endpoint: `POST https://www.respira.press/api/skills/track-usage`

package/skills/html-to-bricks/metadata.json

@@ -0,0 +1,41 @@
+{
+  "name": "HTML to Bricks Builder",
+  "slug": "html-to-bricks",
+  "icon": "🧱",
+  "category": "migration",
+  "description": "Convert raw HTML/CSS into native Bricks Builder elements. Maps colors, typography, and spacing to your design system tokens so the result is drift-resistant. ACSS class mapping when ACSS is installed. Resolves the most-upvoted open feature request.",
+  "author": "Respira Team",
+  "author_url": "https://respira.press",
+  "trigger": "convert this html to bricks",
+  "requires_respira": true,
+  "requires_woocommerce_addon": false,
+  "requires_accessibility_addon": false,
+  "is_read_only": false,
+  "is_duplicate_first": true,
+  "version": "1.0.0",
+  "last_updated": "2026-05-24",
+  "tools_used": [
+    "respira_get_active_site",
+    "respira_get_builder_info",
+    "respira_get_option",
+    "respira_convert_html_to_builder",
+    "respira_build_page",
+    "respira_create_page_duplicate",
+    "respira_inject_builder_content"
+  ],
+  "detects": [
+    "active_bricks_version",
+    "design_system_tokens",
+    "acss_installation",
+    "external_assets",
+    "unmappable_html_elements",
+    "form_elements"
+  ],
+  "generates": [
+    "bricks_element_tree",
+    "design_system_bound_settings",
+    "acss_class_mappings",
+    "external_asset_warnings",
+    "new_or_duplicate_page"
+  ]
+}

package/skills/internal-link-builder/SKILL.md

@@ -0,0 +1,258 @@
+# Internal Link Builder
+
+**Version:** 1.2.0
+**Updated:** 2026-06-30
+**Freshly updated:** v1.2.0 snapshots every page with `respira_get_snapshot` before touching links, locates the exact target paragraph with `respira_find_element` and inserts contextual links there with `respira_update_element` instead of rewriting whole pages, applies links across many pages in one pass with `respira_batch_update`, and persists the per-site linking strategy (anchor-text rules, clusters already built, do-not-link pairs) via `respira_get_option` / `respira_update_option` so repeat runs build on prior work.
+
+Strategic internal link building for WordPress sites. Analyzes all published content, maps topic relationships, identifies high-value linking opportunities between pages, and presents a clear plan for approval before making any changes. Use this skill whenever someone mentions internal links, link building, content interlinking, orphaned pages that need links, topic clusters, pillar pages, or wants to improve their site's internal link structure for SEO.
+
+## What This Skill Does
+
+Internal links are one of the highest-leverage on-page SEO tactics — they distribute page authority, help search engines understand site structure, and guide visitors to related content. Most WordPress sites under-link dramatically, leaving value on the table.
+
+This skill reads every published page and post, builds a content relationship map, and finds natural opportunities to connect related content through contextual links. It always shows you the full plan before touching anything.
+
+**Finds:**
+- Orphaned content (pages/posts with zero or few inbound internal links)
+- Hub pages that should link to related sub-pages but don't
+- Blog posts that reference topics covered by other pages without linking
+- Pillar/cluster opportunities (topically related content that should be interlinked)
+- Pages with high authority potential that aren't distributing link equity
+- Over-linked pages (too many outbound links diluting value)
+- Missing contextual links (mentions of topics without corresponding links)
+
+**Recommends:**
+- Specific source page → target page link pairs
+- Suggested anchor text (natural, descriptive, not keyword-stuffed)
+- Link placement context (which paragraph/section the link belongs in)
+- Priority ranking (high/medium/low impact)
+- Reasoning for each recommendation (why this link makes sense)
+
+## Requirements
+
+- Respira for WordPress plugin installed and connected
+- MCP connection active (desktop or WebMCP)
+- Read access to scan site content
+- Write access to create duplicates (only if user approves changes)
+
+## Trigger Phrase
+
+- "build internal links"
+
+## Alternative Triggers
+
+- "improve internal linking"
+- "find internal link opportunities"
+- "interlink my content"
+- "fix orphaned pages"
+- "create topic clusters"
+- "link my pages together"
+- "internal link audit"
+
+## Execution Workflow
+
+### Phase 1: Content Inventory & Mapping
+
+1. Verify Respira + MCP connection via `respira_get_site_context`. If unavailable, stop and show setup guidance.
+2. Load any saved linking strategy for this site via `respira_get_option` (key `respira_internal_link_strategy`). If present, it carries the anchor-text conventions, topic clusters already built, and do-not-link pairs from previous runs. Use it so a repeat run extends prior work instead of re-proposing the same links. If absent, start fresh and write it back in Phase 4.
+3. Fetch all published content:
+   - `respira_list_pages` — get all pages
+   - `respira_list_posts` — get all posts
+4. For each content item, load full content:
+   - `respira_read_page` or `respira_read_post`
+   - Extract: title, URL/slug, headings, main topics, existing internal links, word count
+5. Build a **content map** — a structured index of:
+   - Each page/post's primary topic and subtopics
+   - Keywords and phrases each piece targets
+   - Existing internal links (source → target pairs)
+   - Inbound link count per page
+   - Content type (pillar page, blog post, product page, landing page, etc.)
+
+### Phase 2: Opportunity Analysis
+
+Analyze the content map to find linking opportunities. For each potential link, evaluate:
+
+1. **Topical relevance** — Does the source content naturally relate to the target? Only recommend links where the connection is genuinely useful to a reader. A link should feel like a helpful "read more about this" moment, not a forced SEO play.
+
+2. **Context fit** — Is there a natural place in the source content where the link fits? Look for:
+   - Mentions of the target page's topic without an existing link
+   - Paragraphs that discuss related concepts
+   - Lists or resource sections where the target would be a natural addition
+   - Introductions or conclusions that reference broader topics
+
+3. **Link equity value** — Consider:
+   - Orphaned pages (0-1 inbound links) get priority as targets
+   - High-traffic/high-authority pages are valuable as sources
+   - Deep pages that are hard to reach from navigation benefit most
+   - Don't over-link any single page (diminishing returns after ~3-5 new links per page)
+
+4. **Anchor text quality** — Suggest anchor text that:
+   - Reads naturally in context
+   - Describes what the reader will find (not "click here")
+   - Uses relevant keywords without being spammy
+   - Varies across different links to the same target
+
+### Phase 3: Present the Plan
+
+Present the linking plan as a clear, scannable report. Group recommendations by priority:
+
+```
+## Internal Link Building Plan
+
+### Site Overview
+- Total pages/posts scanned: X
+- Existing internal links found: X
+- Orphaned content (0-1 inbound links): X
+- New links recommended: X
+
+### High Priority (orphaned pages & pillar connections)
+
+1. **[Source Page Title]** → **[Target Page Title]**
+   - Why: [Brief reasoning — e.g., "Source discusses WordPress security but doesn't link to your dedicated security guide"]
+   - Anchor text: "[suggested anchor text]"
+   - Placement: [Where in the source content — e.g., "In the paragraph about plugin vulnerabilities (under H2 'Keeping Your Site Safe')"]
+
+2. ...
+
+### Medium Priority (topical cluster links)
+...
+
+### Low Priority (nice-to-have contextual links)
+...
+
+### Summary
+- High priority: X links (strongly recommended)
+- Medium priority: X links (good for SEO)
+- Low priority: X links (optional enhancement)
+```
+
+Then ask:
+
+> Here's the internal linking plan. Would you like me to:
+> 1. Apply all recommendations (creates duplicates for review)
+> 2. Apply only high-priority links
+> 3. Let you pick specific links to apply
+> 4. Just keep this as a reference — no changes
+
+Wait for explicit confirmation before proceeding.
+
+### Phase 4: Apply Links (Only If Approved)
+
+1. Before any edits, snapshot the pages you're about to touch with `respira_get_snapshot`. One snapshot covers the run and makes the whole pass reversible in one step via `respira_restore_snapshot`. This replaces the older duplicate-first dance for the common case: you edit in place, but the snapshot is the safety net. (Duplicate-first via `respira_create_page_duplicate` / `respira_create_post_duplicate` remains an option when the user explicitly wants a side-by-side draft to review before publishing.)
+2. For each approved link, find the exact insertion point rather than rewriting the page:
+   - Use `respira_find_element` to locate the target paragraph or block where the link belongs (match on the surrounding text or heading recorded in the plan's Placement note)
+   - Apply the link to just that element with `respira_update_element`, inserting `<a href="...">anchor text</a>` inline in the matched text. This leaves the rest of the page byte-for-byte unchanged.
+   - Respect the page builder format (Gutenberg blocks, Divi shortcodes, Elementor data, etc.). For deep structural cases use `respira_extract_builder_content` to understand the node tree first.
+3. When many pages get links in the same run, apply them in one pass with `respira_batch_update` instead of a separate write per page. Build the edit list (page/post id + element target + new markup) from the approved plan and submit it together. Fall back to individual `respira_update_element` / `respira_update_page` / `respira_update_post` calls only for one-off insertions.
+4. After all edits are applied, provide a summary:
+   - Number of pages modified
+   - Total links added
+   - The snapshot id for rollback, plus links to review the modified pages in WordPress admin
+5. Persist the updated linking strategy with `respira_update_option` (key `respira_internal_link_strategy`): record the clusters now built, the anchor-text conventions used, and any do-not-link pairs, so the next run starts from this state.
+
+## Link Quality Rules
+
+These rules prevent the skill from making harmful or spammy recommendations:
+
+- **Relevance first** — Never recommend a link purely for SEO mechanics. Every link must be genuinely useful to a human reader navigating between the two pages.
+- **No self-links** — Don't link a page to itself.
+- **No duplicate links** — Don't recommend a link that already exists on the source page.
+- **Respect existing links** — If a paragraph already has 2+ links, don't add more to it. Link density matters for readability.
+- **Natural anchor text** — No exact-match keyword stuffing. Anchor text should read as part of the sentence.
+- **Builder-aware** — When inserting links, preserve the page builder's content format. Don't break Divi shortcodes, Elementor JSON, or Gutenberg block markup.
+- **Conservative by default** — When in doubt about a link's relevance, leave it out. It's better to recommend 10 great links than 30 mediocre ones.
+
+## Output Format
+
+Always include:
+
+1. **Site content summary** (pages/posts scanned, existing link density)
+2. **Content map highlights** (topic clusters identified, orphaned content found)
+3. **Prioritized linking plan** (high/medium/low with reasoning for each)
+4. **Clear confirmation prompt** — never proceed without approval
+5. **Impact estimate** (which orphaned pages get rescued, which clusters get strengthened)
+
+If changes are applied, also include:
+
+6. **Change summary** (pages modified, links added, snapshot id)
+7. **Review instructions** (which pages to review in WordPress, and how to roll back)
+
+## Safety Model
+
+- Read-only analysis first — full content scan before any changes
+- Explicit user confirmation before any edits
+- Snapshot before writing — `respira_get_snapshot` captures the pages first, so the whole run reverts in one step via `respira_restore_snapshot`
+- Targeted edits — `respira_find_element` + `respira_update_element` change only the matched paragraph, leaving the rest of the page untouched (no whole-page rewrite)
+- Duplicate-first remains available when the user wants a side-by-side draft instead of an in-place edit
+- Provides rollback guidance (restore the snapshot if not wanted)
+- Preserves all existing content and links — only adds, never removes
+
+## Honest Disclaimer
+
+This skill identifies internal linking opportunities and creates optimized duplicates for review.
+
+It cannot:
+- Guarantee ranking improvements
+- Fix external/backlink profile
+- Replace a proper content strategy
+- Publish changes without your review
+
+It can:
+- Find genuine content relationships you've missed
+- Rescue orphaned pages from obscurity
+- Strengthen topical clusters with contextual links
+- Save hours of manual content auditing
+
+## Tooling
+
+**Core WordPress tools**
+- `respira_get_site_context`
+- `respira_list_pages`
+- `respira_list_posts`
+- `respira_read_page`
+- `respira_read_post`
+- `respira_extract_builder_content`
+- `respira_inject_builder_content`
+- `respira_create_page_duplicate`
+- `respira_create_post_duplicate`
+- `respira_update_page`
+- `respira_update_post`
+
+**Targeted insertion (preferred for link edits)**
+- `respira_find_element` — locate the exact target paragraph/block for contextual insertion
+- `respira_update_element` — insert the link into just that element, no whole-page rewrite
+- `respira_batch_update` — apply links across many pages in one pass
+
+**Snapshot & rollback**
+- `respira_get_snapshot` — capture pages before editing
+- `respira_restore_snapshot` — one-step revert
+
+**Per-site strategy persistence**
+- `respira_get_option` — load the saved linking strategy (`respira_internal_link_strategy`)
+- `respira_update_option` — persist clusters built, anchor-text rules, and do-not-link pairs
+
+## Telemetry
+
+After run completion, send fire-and-forget usage tracking to:
+
+- `POST https://www.respira.press/api/skills/track-usage`
+
+Include:
+- `skill_slug = internal-link-builder`
+- site/version context
+- duration and success
+- pages scanned, links recommended, links applied counts
+- tools used
+
+Never block user flow on telemetry failure.
+
+## Related Skills
+
+- SEO & AEO Amplifier (complements this — run SEO audit first, then build links)
+- WordPress Site DNA (understand site structure before linking)
+- Technical Debt Audit
+
+---
+
+Built by Respira Team
+https://respira.press/skills/internal-link-builder

package/skills/internal-link-builder/metadata.json

@@ -0,0 +1,46 @@
+{
+  "name": "Internal Link Builder",
+  "slug": "internal-link-builder",
+  "icon": "🔗",
+  "category": "performance",
+  "description": "Strategic internal link building for WordPress sites. Scans all content, maps topic relationships, identifies linking opportunities between pages, and presents a plan for approval before making changes.",
+  "author": "Respira Team",
+  "author_url": "https://respira.press",
+  "trigger": "build internal links",
+  "requires_respira": true,
+  "requires_woocommerce_addon": false,
+  "requires_accessibility_addon": false,
+  "is_read_only": false,
+  "is_duplicate_first": true,
+  "version": "1.1.0",
+  "last_updated": "2026-05-24",
+  "tools_used": [
+    "respira_get_site_context",
+    "respira_list_pages",
+    "respira_list_posts",
+    "respira_read_page",
+    "respira_read_post",
+    "respira_extract_builder_content",
+    "respira_inject_builder_content",
+    "respira_create_page_duplicate",
+    "respira_create_post_duplicate",
+    "respira_update_page",
+    "respira_update_post"
+  ],
+  "detects": [
+    "orphaned_pages",
+    "missing_contextual_links",
+    "weak_topic_clusters",
+    "over_linked_pages",
+    "under_linked_pages",
+    "hub_pages_without_spokes",
+    "topic_mentions_without_links"
+  ],
+  "generates": [
+    "internal_link_recommendations",
+    "anchor_text_suggestions",
+    "content_relationship_map",
+    "linking_priority_plan",
+    "optimized_duplicates_with_links"
+  ]
+}