@respira/wordpress-mcp-server 7.3.0 → 7.4.0

package/skills/woocommerce-health-check/telemetry.ts

@@ -0,0 +1,137 @@
+/**
+ * WooCommerce Health Check — Telemetry helper
+ * Fire-and-forget usage tracking to respira.press/api/skills/track-usage
+ * Never blocks skill execution.
+ */
+
+export interface WooCommerceHealthCheckTelemetry {
+  session_id: string;
+  user_id?: string | null;
+  wordpress_site_url?: string;
+  wordpress_version?: string;
+  php_version?: string;
+  started_at: string;
+  completed_at?: string;
+  duration_ms?: number;
+  success: boolean;
+  error_message?: string | null;
+  issues_found?: number;
+  issues_by_severity?: {
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+    info?: number;
+  };
+  health_score?: number;
+  mcp_tools_used?: string[];
+  findings_summary?: Record<string, unknown>;
+  had_respira_before?: boolean;
+  installed_respira_after?: boolean;
+  assistant_client?: string;
+  assistant_version?: string;
+  assistant_transport?: string;
+  telemetry_source?: string;
+}
+
+const TELEMETRY_ENDPOINT = 'https://www.respira.press/api/skills/track-usage';
+
+function detectAssistantTelemetry(): {
+  assistant_client?: string;
+  assistant_version?: string;
+  assistant_transport?: string;
+  telemetry_source?: string;
+} {
+  const env: Record<string, string | undefined> =
+    typeof process !== 'undefined' && process?.env ? (process.env as Record<string, string | undefined>) : {};
+
+  const explicitClient = env.RESPIRA_AGENT_CLIENT || env.MCP_AGENT_CLIENT || env.AI_AGENT_CLIENT;
+  const explicitTransport = env.RESPIRA_AGENT_TRANSPORT || env.MCP_AGENT_TRANSPORT;
+  const explicitVersion = env.RESPIRA_AGENT_VERSION || env.MCP_AGENT_VERSION || env.AI_AGENT_VERSION;
+
+  const fingerprint = [
+    explicitClient,
+    env.CURSOR_AGENT,
+    env.CURSOR_TRACE_ID,
+    env.CLAUDECODE,
+    env.CLAUDE_CODE_ENTRYPOINT,
+    env.CODEIUM_ENV,
+    env.TERM_PROGRAM,
+    env.TERM_PROGRAM_VERSION,
+    typeof navigator !== 'undefined' ? navigator.userAgent : '',
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase();
+
+  const inferredClient = (() => {
+    if (explicitClient) return explicitClient.toLowerCase();
+    if (fingerprint.includes('cursor')) return 'cursor';
+    if (fingerprint.includes('claude')) return 'claude-code';
+    if (fingerprint.includes('codex')) return 'codex';
+    if (fingerprint.includes('windsurf') || fingerprint.includes('codeium')) return 'windsurf';
+    if (fingerprint.includes('copilot')) return 'copilot';
+    if (fingerprint.includes('gemini')) return 'gemini';
+    return undefined;
+  })();
+
+  return {
+    assistant_client: inferredClient,
+    assistant_version: explicitVersion?.toLowerCase(),
+    assistant_transport: (explicitTransport || 'desktop-mcp').toLowerCase(),
+    telemetry_source: explicitClient ? 'env' : inferredClient ? 'heuristic' : 'skill-fetch',
+  };
+}
+
+/**
+ * Send skill usage telemetry.
+ * Non-blocking: errors are swallowed, never thrown.
+ * Call after the skill completes — success or failure.
+ */
+export function trackSkillUsage(data: WooCommerceHealthCheckTelemetry): void {
+  const detected = detectAssistantTelemetry();
+  const payload = {
+    skill_slug: 'woocommerce-health-check',
+    had_respira_before: true,
+    ...detected,
+    ...data,
+  };
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+  };
+
+  if (payload.assistant_client) {
+    headers['X-Respira-Agent-Client'] = payload.assistant_client;
+  }
+  if (payload.assistant_version) {
+    headers['X-Respira-Agent-Version'] = payload.assistant_version;
+  }
+  if (payload.assistant_transport) {
+    headers['X-Respira-Agent-Transport'] = payload.assistant_transport;
+  }
+
+  // Fire and forget — intentionally not awaited
+  fetch(TELEMETRY_ENDPOINT, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(payload),
+  }).catch(() => {
+    // Silently swallow all errors — telemetry must never break the skill
+  });
+}
+
+/**
+ * Generate a session ID for tracking a single skill run.
+ */
+export function generateSessionId(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  // Fallback for environments without crypto.randomUUID
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}

package/skills/wordpress-ai-image-optimizer/README.md

@@ -0,0 +1,49 @@
+# WordPress AI Image Optimizer
+
+> AI-powered image optimization that processes images locally and updates your WordPress references safely.
+
+## Overview
+
+WordPress AI Image Optimizer scans your entire site image footprint, identifies high-impact optimization opportunities, processes images locally in an AI coding environment (compression, conversion, resize, rename), uploads optimized versions as new media entries, and updates references in duplicate content for review.
+
+## Key Capabilities
+
+- Sitewide image auditing (media library, posts/pages, featured images, builder content, WooCommerce)
+- Compression and format conversion (JPG/PNG to WebP where appropriate)
+- Oversize detection and resizing to practical dimensions
+- SEO-friendly filename generation
+- AI-assisted alt text generation
+- Duplicate-first URL updates with safe rollback path
+- Plugin and CDN awareness (Smush, ShortPixel, EWWW, Imagify, Optimole, Cloudflare, BunnyCDN)
+
+## Safety Model
+
+- Creates new optimized files and keeps originals
+- Applies URL updates in duplicates, not live content
+- Requires explicit review and approval before publish
+- Supports rollback by preserving original media references
+
+## Trigger
+
+Use:
+
+```text
+optimize my wordpress images with ai
+```
+
+## Output
+
+- Image health score
+- Prioritized optimization list (critical/high/medium/low)
+- Before/after size and format comparisons
+- Estimated performance impact summary
+- Review-ready duplicate content references
+
+## Source
+
+- Skill folder: [wordpress-ai-image-optimizer](https://github.com/respira-press/agent-skills-wordpress/tree/main/wordpress-ai-image-optimizer)
+- Live page: https://respira.press/skills/wordpress-ai-image-optimizer
+
+---
+
+Built by Respira Team

package/skills/wordpress-ai-image-optimizer/SKILL.md

@@ -0,0 +1,232 @@
+# WordPress AI Image Optimizer
+
+**Version:** 1.2.0
+**Updated:** 2026-06-30
+**Freshly updated:** v1.2.0 replaces per-image `respira_update_media` loops with a single `respira_update_media_batch` pass (up to ~50 items at once), snapshots the media library with `respira_get_snapshot` before the batch so the whole run is one-step reversible, runs the audit through `respira_analyze_images`, surfaces optional stock replacements via `respira_search_stock_images` + `respira_sideload_image`, and closes with a `respira_generate_activity_report` summary (e.g. "optimized 47 images, saved 1.2GB").
+
+AI-powered image optimization for WordPress sites. Automatically compresses, converts formats, renames files, and updates all references. Processes images locally in AI code editor, creates optimized versions, and preserves originals for safety.
+
+## What This Skill Does
+
+**Scans:**
+- All media library images
+- Images in posts and pages content
+- Featured images
+- Images in page builder elements (Elementor, Divi, Bricks, etc.)
+- WooCommerce product images
+- Images in custom post types
+
+**Detects:**
+- File sizes (actual KB/MB on disk)
+- Image dimensions (width x height in pixels)
+- Format (JPG, PNG, GIF, WebP, AVIF, SVG)
+- Whether width/height attributes are set in HTML
+- Whether alt text exists (and quality)
+- Whether image is being used (orphaned media)
+- Whether responsive image sizes exist (WordPress srcset)
+- Compression quality (estimated from file size)
+- Lazy loading implementation
+- Non-SEO-friendly filenames (IMG_1234.jpg, screenshot.png, etc.)
+- Oversized originals (5000px uploaded when 2000px is max needed)
+- Missing srcset on content images
+- Builder images that bypass WordPress responsive system
+
+**Optimizes via AI Code Editor:**
+- Downloads images from WordPress
+- Compresses with optimal quality settings (80-85% for JPG, lossless for PNG)
+- Converts to modern formats (WebP preferred, AVIF when appropriate)
+- Resizes oversized originals to optimal dimensions
+- Renames with SEO-friendly descriptive filenames
+- Generates missing alt text using AI
+- Regenerates WordPress responsive image sizes
+- Uploads optimized versions back to WordPress
+- Creates new media entries (keeps old files safe)
+- Updates all content references in duplicates
+
+**Provides:**
+- Comprehensive image health score (0-100)
+- Impact-prioritized optimization opportunities
+- Before/after file size comparisons
+- Estimated page speed improvements
+- Plugin/CDN detection and recommendations
+
+## Requirements
+
+- Respira for WordPress plugin installed and connected
+- MCP connection active (desktop or WebMCP)
+- AI code editor with image processing tools (Claude Code, Cursor, etc.)
+- WooCommerce add-on (optional - for product image optimization)
+- Read access to scan images, write access to upload optimized versions
+
+## How to Use
+
+### Trigger Phrase
+"optimize my wordpress images with ai"
+
+### Alternative Triggers
+- "run ai image optimization"
+- "compress and optimize all images"
+- "audit my media library"
+- "improve image performance"
+
+### What Happens
+
+**Phase 1: Comprehensive Image Audit**
+
+1. Scans all images across site:
+   - Media library (all uploaded files)
+   - Content images (posts, pages, custom post types)
+   - Featured images
+   - Builder images (Elementor, Divi, Bricks, etc.)
+   - WooCommerce product images (if WooCommerce active)
+2. Analyzes each image (use `respira_analyze_images` to drive the audit; it returns per-image findings in one call):
+   - File size and format
+   - Actual dimensions vs displayed dimensions
+   - Alt text presence and quality
+   - Filename SEO-friendliness
+   - Usage (which pages/posts use this image)
+   - Responsive image sizes (srcset)
+   - Lazy loading implementation
+3. Detects optimization plugins/CDN:
+   - Smush, ShortPixel, EWWW, Imagify, Optimole
+   - Cloudflare, BunnyCDN, other CDNs
+4. Scores opportunities by impact:
+   - File size x page traffic = optimization priority
+   - Separates quick wins from big wins
+5. Generates comprehensive report
+
+**Phase 2: User Approval**
+
+Presents report and asks which optimizations to run:
+- Compress oversized images
+- Convert JPG/PNG -> WebP
+- Resize unnecessarily large originals
+- Rename non-SEO filenames
+- Add missing alt text
+- Regenerate responsive image sizes
+
+User can choose:
+- "Optimize everything" (all optimizations)
+- "Compress only" (no format changes)
+- "Top 10 images" (highest impact first)
+- "Homepage images only" (critical pages first)
+
+**Phase 3: AI Processing**
+
+6. Snapshot the media library before any writes with `respira_get_snapshot` so the entire batch is reversible in one step (`respira_restore_snapshot`). Take this once, before the batch — not per image.
+7. Downloads images from WordPress to local workspace.
+8. Processes images locally:
+   - Compression
+   - Format conversion
+   - Resizing
+   - SEO-friendly renaming
+   - AI alt text generation
+   - Optional: when an image is low quality or simply wrong for the page, find a replacement with `respira_search_stock_images` and pull it in with `respira_sideload_image` instead of re-optimizing the original
+9. Uploads optimized versions back to WordPress:
+   - Creates NEW media entries (original files untouched)
+   - Applies metadata in one pass with `respira_update_media_batch` rather than one `respira_update_media` call per image. The batch accepts up to ~50 items, so a typical library is updated in a single call (alt text, title, caption, description). Fall back to single `respira_update_media` only for one-off corrections.
+   - Marks old files as "deprecated - replaced by [new-filename]"
+10. Updates content references in duplicates:
+   - Creates duplicates of affected posts/pages
+   - Replaces old image URLs with new optimized URLs
+   - Updates builder and WooCommerce image references
+11. Regenerates responsive image sizes and srcset support
+
+**Phase 4: Review & Publish**
+
+12. Provides before/after comparison:
+   - File size savings
+   - Format changes
+   - Dimension changes
+   - Filename improvements
+   - Pages affected
+13. User reviews duplicates in WordPress admin
+14. User approves publishing
+15. Old files remain available for safety and rollback
+16. Generate a run summary with `respira_generate_activity_report` so the work is auditable in one line (e.g. "optimized 47 images, saved 1.2GB, added alt text to 31"). This reads from the change log Respira already recorded for the batch.
+
+## Honest Disclaimer
+
+This skill downloads images, processes them with AI, and uploads optimized versions. You review all changes before publishing.
+
+**What this skill CANNOT do:**
+- Guarantee perfect quality (compression is lossy)
+- Fix already broken/corrupted image files
+- Optimize CSS background images
+- Process images hosted externally outside WordPress uploads
+- Improve composition/art direction (technical optimization only)
+
+**What this skill CAN do:**
+- Compress images without visible quality loss
+- Convert to WebP for significant size reduction
+- Resize oversized originals to practical dimensions
+- Rename files with SEO-friendly names
+- Generate descriptive alt text
+- Update references automatically in duplicates
+- Preserve originals for safety and rollback
+
+## Safety Model
+
+- Non-destructive: Creates NEW optimized images and keeps old files
+- Duplicate-first: Updates content in duplicates, never live pages
+- User approval required: Review before publishing
+- Rollback ready: Old files preserved and reversible
+- No live site impact until explicit approval
+
+## Technical Details
+
+Uses these Respira MCP tools:
+
+**Audit:**
+- `respira_analyze_images` (drives the Phase 1 audit; per-image findings in one call)
+
+**Media Operations:**
+- `respira_list_media`
+- `respira_get_media`
+- `respira_upload_media`
+- `respira_update_media_batch` (primary metadata writer — up to ~50 items per call)
+- `respira_update_media` (single-item fallback / one-off corrections)
+- `respira_delete_media` (optional cleanup)
+
+**Stock Replacements (optional):**
+- `respira_search_stock_images`
+- `respira_sideload_image`
+
+**Snapshot & Rollback:**
+- `respira_get_snapshot` (capture before the batch)
+- `respira_restore_snapshot` (one-step revert)
+
+**Reporting:**
+- `respira_generate_activity_report` (run summary: images optimized, space saved, alt text added)
+
+**Content Scanning:**
+- `respira_list_pages`
+- `respira_list_posts`
+- `respira_read_page`
+- `respira_read_post`
+- `respira_get_builder_info`
+
+**Content Updates:**
+- `respira_create_page_duplicate`
+- `respira_create_post_duplicate`
+- `respira_update_page`
+- `respira_update_post`
+
+**WooCommerce (optional):**
+- `woocommerce_list_products`
+- `woocommerce_get_product`
+- `woocommerce_update_product`
+
+**Plugin Detection:**
+- `respira_list_plugins`
+
+## Related Skills
+
+- SEO & AEO Amplifier
+- WordPress Site DNA
+- Mobile Experience Report
+
+---
+
+Built by Respira Team
+https://respira.press/skills/wordpress-ai-image-optimizer

package/skills/wordpress-ai-image-optimizer/metadata.json

@@ -0,0 +1,63 @@
+{
+  "name": "WordPress AI Image Optimizer",
+  "slug": "wordpress-ai-image-optimizer",
+  "icon": "🖼️",
+  "category": "performance",
+  "description": "AI-powered image optimization: compress, convert to WebP, resize, rename with SEO-friendly names, generate alt text. Processes images locally in AI code editor and updates all content references.",
+  "author": "Respira Team",
+  "author_url": "https://respira.press",
+  "trigger": "optimize my wordpress images with ai",
+  "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_list_media",
+    "respira_get_media",
+    "respira_upload_media",
+    "respira_update_media",
+    "respira_list_pages",
+    "respira_list_posts",
+    "respira_get_page",
+    "respira_get_post",
+    "respira_detect_page_builder",
+    "respira_create_duplicate",
+    "respira_update_page",
+    "respira_update_post",
+    "respira_list_plugins",
+    "woocommerce_list_products",
+    "woocommerce_get_product",
+    "woocommerce_update_product"
+  ],
+  "processing_tools": [
+    "ImageMagick",
+    "Sharp (Node.js)",
+    "Pillow (Python)"
+  ],
+  "detects": [
+    "oversized_images",
+    "inefficient_formats",
+    "missing_alt_text",
+    "non_seo_filenames",
+    "missing_responsive_sizes",
+    "suboptimal_compression",
+    "png_photos",
+    "no_lazy_loading",
+    "missing_dimensions",
+    "orphaned_media"
+  ],
+  "optimizations": [
+    "image_compression",
+    "format_conversion_webp",
+    "resize_oversized",
+    "seo_friendly_renaming",
+    "ai_alt_text_generation",
+    "responsive_size_regeneration",
+    "lazy_loading_implementation"
+  ],
+  "file_safety": "creates_new_keeps_old",
+  "processing_location": "ai_code_editor_local"
+}

package/skills/wordpress-site-dna/README.md

@@ -0,0 +1,81 @@
+# WordPress Site DNA
+
+**Archaeological analysis of WordPress sites.** Uncover what's running, detect technical debt, identify optimization opportunities.
+
+## What it does
+
+WordPress Site DNA runs a comprehensive audit of your WordPress installation using Respira for WordPress's MCP tools. In ~60 seconds it produces a complete health report covering:
+
+- **Page builder archaeology** — detects ALL installed builders, which pages use each one, orphaned builder data
+- **Plugin analysis** — active vs dead weight, outdated, security risks, performance hogs
+- **Content structure** — orphaned shortcodes, media library, database bloat
+- **Performance opportunities** — page weight, unused assets, image optimization
+- **Security posture** — SSL, admin exposure, file permissions, security plugins
+- **Health score** — 0–100 score with breakdown by category
+
+## Requirements
+
+- Respira for WordPress plugin (any version)
+- Respira for WordPress MCP server connected to Claude
+- WordPress 5.0+ (Gutenberg era)
+
+## Installation
+
+1. Install Respira for WordPress from [respira.press](https://www.respira.press)
+2. Connect via MCP: `npx -y @respira/wordpress-mcp-server --setup`
+3. Open Claude and say: `"analyze my wordpress site"`
+
+## Trigger phrases
+
+```
+analyze my wordpress site
+wordpress site audit
+site dna analysis
+what's running on my site
+wordpress archaeology
+scan my wordpress installation
+check my wordpress setup
+```
+
+## File structure
+
+```
+claude_skills/wordpress-site-dna/
+├── SKILL.md          ← Main skill definition (the actual skill)
+├── README.md         ← This file
+├── telemetry.ts      ← Telemetry helper functions
+└── tests/
+    ├── benchmark.json    ← Benchmark test cases
+    ├── trigger.json      ← Trigger tuning tests
+    └── regression.json   ← Regression test suite
+```
+
+## Telemetry
+
+Usage data is sent to `https://www.respira.press/api/skills/track-usage` after each run. Tracking is anonymous by default (no PII). Data collected:
+
+- Site URL (for analysis, not stored with personal data)
+- WordPress/PHP versions
+- Detected builders and plugin counts
+- Health score and issue counts
+- MCP tools used
+- Execution duration
+
+Telemetry is fire-and-forget — failures are silently swallowed and never affect skill output.
+
+## Evaluation
+
+Run evaluations using the test cases in `/tests/`:
+
+- `benchmark.json` — End-to-end benchmark against manual audits
+- `trigger.json` — Trigger phrase accuracy (target: <5% false positive/negative)
+- `regression.json` — Correctness across varied site configurations
+
+## Version history
+
+### 1.0.0 (2026-03-07)
+- Initial release
+- Core analysis: WordPress/PHP versions, builders, plugins, security, performance
+- Health score calculation (0–100)
+- Telemetry integration
+- Respira for WordPress fix workflow recommendations