@respira/wordpress-mcp-server 8.3.19 → 8.3.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@respira/wordpress-mcp-server",
-  "version": "8.3.19",
+  "version": "8.3.20",
   "mcpName": "io.github.webmyc/respira-wordpress",
   "description": "WordPress MCP server + companion plugin giving AI native access to page builder content, not just the REST API. 220 tools, 325 with WooCommerce, 17 page builders and the Site Editor. Element-level edits, full page creation, HTML to builder conversion, snapshots and rollback on every write. MCP 2026-07-28 with legacy-client support. New in 8.3: Design Direction, one design system per site, applied to native builder stores, checked against the rendered page, with a live preview link for the Art Direction dashboard.",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
   "type": "module",
   "scripts": {
     "build": "npm run bundle-skills && tsc",
-    "bundle-skills": "node -e \"const fs=require('fs'),path=require('path');const src=path.join(__dirname,'..','plugins','respira-wordpress','skills');const dst=path.join(__dirname,'skills');if(!fs.existsSync(src))process.exit(0);fs.rmSync(dst,{recursive:true,force:true});fs.mkdirSync(dst,{recursive:true});for(const e of fs.readdirSync(src,{withFileTypes:true})){if(!e.isDirectory())continue;const s=path.join(src,e.name);const d=path.join(dst,e.name);fs.mkdirSync(d,{recursive:true});for(const f of fs.readdirSync(s,{withFileTypes:true})){if(f.isDirectory())continue;fs.copyFileSync(path.join(s,f.name),path.join(d,f.name));}}console.log('bundled '+fs.readdirSync(dst).length+' skills from plugins/respira-wordpress/skills/');\"",
+    "bundle-skills": "node scripts/bundle-skills.mjs",
     "watch": "tsc --watch",
     "start": "node dist/index.js",
     "setup": "node dist/setup.js --setup",

package/skills/woo-marketing-campaigns/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: woo-marketing-campaigns
+description: "Use when the user says 'plan a campaign', 'promote this product', 'write the copy for our sale', 'what should we push this month', or 'draft the launch for this collection'. Reads what the store actually sells, drafts the campaign around it, and stages every page and product change for approval."
+license: MIT
+metadata:
+  author: "Respira for WordPress"
+  author_url: https://respira.press
+  version: 1.0.0
+  mcp-server: respira-wordpress
+  category: commerce
+---
+
+# Woo Marketing Campaigns
+
+Plans and drafts a campaign for a WooCommerce store from what the store actually sells, rather than from what a model imagines a store like this sells.
+
+## What this skill does
+
+Most campaign copy for a store is written without looking at the store. It names products that were discontinued, promises stock that is not there, and picks a hero product that has sold four units all year. The fix is not better prose, it is reading the shop first.
+
+So this reads sales, stock and catalogue quality before it writes a word, then drafts the campaign against real products at real prices with real availability, and stages every change rather than publishing it.
+
+**Handles:**
+- Choosing what to promote from sales data and stock, not from guesswork
+- Campaign plan: the offer, the products, the dates, the pages that need to exist
+- Landing page and category copy, written to a duplicate for approval
+- Product descriptions and short descriptions for the promoted set
+- The coupon or sale the campaign depends on, through Woo Pricing and Promotions
+- A post-campaign read of what actually sold
+
+## What this skill does NOT do
+
+- **Send anything.** No email, no ads, no social posts. It drafts; a person sends.
+- **Publish.** Copy lands on duplicates. Approval is a human step, always.
+- **Invent stock or dates.** If a product has four units left, the campaign says so or picks something else.
+- **Set the discount.** That is a margin decision, and it belongs to the owner. See Woo Pricing and Promotions.
+- **Claim anything the store cannot support.** No "best", no "award-winning", no delivery promise the shipping settings do not back.
+
+## Requirements
+
+- WooCommerce with the Respira WooCommerce add-on, licensed
+- Enough order history for `get-sales-report` to say something useful. On a store with almost no orders, say that plainly and plan from stock and margin instead of pretending the data speaks.
+
+## Trigger Phrase
+
+- "plan a campaign"
+
+## Alternative Triggers
+
+- "promote this product"
+- "write the copy for our sale"
+- "what should we push this month"
+- "draft the launch for this collection"
+
+## Execution Workflow
+
+### Phase 1: Read the shop
+
+1. `get-sales-report` over the last 30 and 90 days. What sells, what is seasonal, what has stalled.
+2. `list-products-advanced` for stock and price on the candidates. A hero product that goes out of stock on day two is a campaign that ends on day two.
+3. `find-low-stock` to rule those out early.
+4. `analyze-catalog-quality` on the shortlist. A product with no image and a twelve-word description will not convert however good the campaign is, and fixing that comes first.
+
+### Phase 2: Propose, do not assume
+
+Come back with a plan and the reasoning, in the user's terms:
+
+> Three candidates. The waxed jacket is your best seller in this window last year and has 40 in stock. The wool scarf has better margin but 6 left, so it works as an add-on rather than the hero. The boots sell well and have no photography, which is the thing to fix before promoting them.
+>
+> Suggested: jacket as hero, scarf as the add-on, boots held back until they have images.
+
+Get agreement on the products and the offer before writing any copy.
+
+### Phase 3: Fix what would waste the traffic
+
+If the promoted products have catalogue gaps, fix those first with Woo Catalog Perfection. Driving traffic to a product with no image is spending attention on a page that cannot convert.
+
+### Phase 4: Draft
+
+- Landing or category copy through `respira_create_page_duplicate` and the builder tools, never onto the live page
+- `update-product` for descriptions on the promoted set, staged
+- The offer itself through Woo Pricing and Promotions, previewed with `dry_run` first
+
+Every claim traces to something read in Phase 1. Prices come from the product, availability comes from stock, delivery claims come from the shipping settings or are not made.
+
+### Phase 5: Hand over
+
+List the drafts, their preview links, and what remains a human decision: approving the pages, sending whatever is being sent, and the date the offer ends.
+
+### Phase 6: Afterwards
+
+When the campaign has run, `get-sales-report` for the window and compare against the plan. Say what worked and what did not, including when the answer is that the campaign made no measurable difference.
+
+## Safety Model
+
+- Reads before writes, always
+- Copy to duplicates; the live page is not touched
+- Nothing is published or sent by this skill
+- Price changes go through the previewed, snapshotted, guardrailed path
+- Claims are traceable to store data, or they are not made
+
+## Honest Disclaimer
+
+This skill drafts a campaign from a store's own data.
+
+It cannot: know your customers, your brand voice beyond what it can read, your margins, or your competition. It cannot send email or buy ads. It cannot tell you whether a campaign is a good idea.
+
+It can: pick candidates from real sales and stock rather than plausibility, stop you promoting something that is nearly out of stock or has no photograph, draft copy that matches what you actually sell, and stage all of it for you to approve.
+
+## Tooling
+
+`respira_woo_get-sales-report`, `respira_woo_agent-orders-report`, `respira_woo_list-products-advanced`, `respira_woo_find-low-stock`, `respira_woo_analyze-catalog-quality`, `respira_woo_update-product`, `respira_woo_create-coupon`, `respira_woo_schedule-sale`, `respira_create_page_duplicate`, `respira_update_element`, `respira_get_snapshot`
+
+## Telemetry
+
+After run completion, fire-and-forget to `POST https://www.respira.press/api/skills/track-usage` with `skill_slug = woo-marketing-campaigns`, site and version context, duration, products promoted, drafts created. Never block the user on telemetry.
+
+## Related Skills
+
+- Woo Pricing and Promotions (the offer the campaign runs on)
+- Woo Catalog Perfection (fix the products before promoting them)
+- Brand Voice Synthesizer (write in the store's own voice)
+- SEO & AEO Amplifier (make the campaign page findable)
+
+---
+
+Built by Respira Team
+https://respira.press/skills/woo-marketing-campaigns

package/skills/woo-pricing-promotions/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: woo-pricing-promotions
+description: "Use when the user says 'run a sale', 'discount this category', 'set up a coupon', 'reprice these products', 'end the sale', or asks what a discount would cost them. Plans the price change, shows it as a preview before anything moves, writes it with a snapshot, and can put it back."
+license: MIT
+metadata:
+  author: "Respira for WordPress"
+  author_url: https://respira.press
+  version: 1.0.0
+  mcp-server: respira-wordpress
+  category: commerce
+---
+
+# Woo Pricing and Promotions
+
+Runs a sale, a repricing, or a coupon on a live WooCommerce store, and treats the money as money. Every change is previewed before it happens, snapshotted when it does, and reversible afterwards.
+
+## What this skill does
+
+Pricing is the one place on a store where a plausible-looking mistake costs real money before anyone notices. A misplaced decimal is not a broken layout somebody reports; it is orders at the wrong price, and by the time it surfaces the orders exist. So the order of operations here is deliberate: understand the current prices, state the change in money rather than percentages, show it, then write it.
+
+**Handles:**
+- Category-wide or list-based repricing, by percentage, by fixed amount, or to a set value
+- Scheduled sales with start and end dates, so the sale ends without anyone remembering to end it
+- Coupons: fixed, percentage, free shipping, with usage limits and product or category restrictions
+- Sale badges on the storefront
+- Putting a price change back from the snapshot it wrote
+
+## What this skill does NOT do
+
+- **Decide the discount.** Depth is a margin decision. This skill will tell you what a discount costs against recent sales volume; it will not pick one.
+- **Beat the guardrails.** A move over 50%, a discount deeper than 70%, or a price under 0.50 comes back blocked. That is the add-on refusing, and it is refusing on purpose. Say so plainly and ask, rather than resending with the override.
+- **Touch tax, currency, or payment configuration.**
+- **Reprice a variable product's parent and hope.** Variations carry their own prices; name them.
+
+## Requirements
+
+- WooCommerce with the Respira WooCommerce add-on, licensed
+- The store's own reporting for volume, which `get-sales-report` reads
+
+## Trigger Phrase
+
+- "run a sale"
+
+## Alternative Triggers
+
+- "discount this category"
+- "set up a coupon"
+- "reprice these products"
+- "end the sale"
+- "what would 20% off cost me"
+
+## Execution Workflow
+
+### Phase 1: See the current state
+
+Never reprice from memory of what a product costs.
+
+1. `respira_woo_list-products-advanced` for the target set, or `get-product` for a named one. This also matters mechanically: reads are what the add-on records as provenance, and a write to something never read is annotated as unverified.
+2. `get-sales-report` over a comparable recent window, so the discount has a volume to be measured against.
+3. Note anything already on sale. Stacking a new sale on an existing one is the most common way a discount ends up twice as deep as intended.
+
+### Phase 2: State it in money
+
+Convert the ask into per-product numbers, and say them:
+
+> 14 products in Outdoor. Regular prices 24.00 to 189.00. A 20% sale takes the range to 19.20 to 151.20. Against the last 30 days that is about 340 in discount at the same volume. Two of these are already on sale at 15%, so they would go to 32% off unless excluded.
+
+Ask before writing. A percentage sounds smaller than the money it is.
+
+### Phase 3: Preview
+
+Run the write with `dry_run: true` first, every time. The response lists each product with its old and new prices and names anything the guardrails would block. Show that list. A preview is cheap and a repricing is not.
+
+### Phase 4: Write
+
+- `bulk-update-prices` for a repricing, or `schedule-sale` when it should end by itself
+- `create-coupon` for a code, with `usage_limit` set unless the user says otherwise, because an uncapped code is a liability
+- `add-sale-badge` if the storefront should show it
+
+Snapshots are captured automatically. Report the snapshot ids.
+
+### Phase 5: Confirm and hand back the undo
+
+State what changed, in money, and how to reverse it: `revert-pricing` with the product and snapshot id. If the sale was scheduled, say the date it ends without anyone acting.
+
+## Safety Model
+
+- Preview before every write, no exceptions
+- Snapshot before each price change, with a named path back
+- Guardrails refuse outsized moves; treat a block as a question for the user, never as an obstacle to route around
+- Coupons default to a usage limit
+- Nothing here touches an existing order's price
+
+## Honest Disclaimer
+
+This skill changes live prices on a real store.
+
+It cannot: judge whether a discount is good for the business, model demand, know your margins, or see a competitor's pricing. It will not decide depth for you.
+
+It can: show what a change costs before it happens, apply it consistently across a set, schedule an end, and put it back.
+
+## Tooling
+
+`respira_woo_list-products-advanced`, `respira_woo_get-product`, `respira_woo_get-sales-report`, `respira_woo_bulk-update-prices`, `respira_woo_schedule-sale`, `respira_woo_revert-pricing`, `respira_woo_create-coupon`, `respira_woo_update-coupon`, `respira_woo_list-coupons`, `respira_woo_add-sale-badge`
+
+## Telemetry
+
+After run completion, fire-and-forget to `POST https://www.respira.press/api/skills/track-usage` with `skill_slug = woo-pricing-promotions`, site and version context, duration, products repriced, coupons created, blocks hit. Never block the user on telemetry.
+
+## Related Skills
+
+- Woo Catalog Perfection (fix the catalog the sale runs on)
+- Woo Marketing Campaigns (tell people the sale exists)
+- WooCommerce Health Check (state of the store before a promotion)
+
+---
+
+Built by Respira Team
+https://respira.press/skills/woo-pricing-promotions