/respira-setup-assistant

name: respira-setup-assistant
description: "Use when the user says 'set up respira', 'respira not connecting', 'check my respira connection', or 'fix respira'. Walks through first-time setup and diagnoses connection failures: timeouts, 401s, 403s, and plugin or server version mismatches."
license: MIT
metadata:
  author: Respira for WordPress
  author_url: https://respira.press
  version: 1.2.0
  mcp-server: respira-wordpress
  category: onboarding

Respira Setup Assistant

**Version:** 1.2.0 **Updated:** 2026-05-24 **Category:** onboarding **Status:** active **Freshly updated:** v1.2.0 reflects the v7.1 Roots React-first admin redesign. Setup walkthrough now references the new /wp-admin/admin.php?page=respira-v71-preview admin shell, the 11 new REST endpoints, and the command-K palette. Diagnostics aware of the 4 new builders (Spectra, Kadence Blocks, GenerateBlocks, SeedProd) and the upgraded Divi 5 108-module catalog. **Requires:** Respira for WordPress plugin (installs via this skill if missing) **Telemetry endpoint:** https://www.respira.press/api/skills/track-usage

---

Description

Diagnose your Respira MCP connection, walk through first-time setup, and fix common connection problems.

The Respira Setup Assistant checks whether the plugin is installed, whether an API key exists, and whether the MCP server version is compatible with the plugin. It gives you a clear status report, walks through any missing steps, and resolves the most common errors (timeouts, 401s, 403s, version mismatches) with plain-language instructions.

Use this skill the first time you connect Respira, after a WordPress update, or whenever Respira tools stop working.

---

Trigger Phrases

This skill activates when the user says any of the following:

• "set up respira"
• "connect respira"
• "respira setup"
• "respira not working"
• "respira connection failed"
• "fix respira"
• "respira setup assistant"
• "check my respira connection"
• "respira health check"
• "diagnose respira"
• "respira mcp setup"
• "is respira connected"
• "respira not connecting"
• "help me set up respira"
• "respira install"

**Do NOT trigger for:** general WordPress tasks, requests that assume Respira is already working, or skill-specific requests like "build internal links" where the skill handles its own Respira check.

---

Execution Workflow

Step 1: Run the Doctor Check

Start by calling `respira_diagnose_connection` (Respira plugin v7.0.16+ / MCP server v6.11.13+). This is the single fastest way to know whether the MCP server reaches the plugin and whether any edge-layer (Cloudflare, WAF) is blocking the REST namespace.

Tool: respira_diagnose_connection
Returns: connection status, version pair, edge-layer block detection (Cloudflare "Bad Bot" pattern, WAF filters), CF allow-list snippet when blocks are detected

If the diagnose tool is unavailable (older plugin or MCP), fall back to `respira_get_server_compatibility`.

Tool: respira_get_server_compatibility
Returns: plugin version, MCP server version, compatibility status, minimum requirements

**Interpret the result:**

| Result | Meaning | |--------|---------| | Returns data successfully | MCP server is connected and plugin is reachable | | Connection refused / timeout | Plugin unreachable — URL or firewall problem | | 401 Unauthorized | API key missing or wrong | | 403 Forbidden | REST API blocked by security plugin or host | | Version mismatch warning | One side needs updating |

If the call succeeds, proceed to Step 2 for a full status report.

If it fails, skip to the **Troubleshooting** section that matches the error.

---

Step 2: Full Site Context

Tool: respira_get_site_context
Returns: WordPress version, PHP version, site URL, active plugins, active theme

From this response, check:

1. **Plugin installed and active** — look for `respira-for-wordpress` in the active plugins list 2. **API key configured** — the context response will include a flag indicating whether an API key is present 3. **WordPress version** — flag if below 6.0 (minimum supported) 4. **PHP version** — flag if below 7.4 (minimum supported)

---

Step 3: Generate Status Report

Present a clear, scannable status report. Use this format:

## Respira Connection Status

### Plugin
- Installed: Yes / No
- Active: Yes / No
- Version: X.X.X (up to date / update available)

### API Key
- Configured: Yes / No

### MCP Server
- Version: X.X.X
- Compatible with plugin: Yes / No

### WordPress
- Version: X.X.X (supported / below minimum)
- PHP Version: X.X (supported / below minimum)

### Overall Status
[CONNECTED — ready to use]
  or
[ACTION NEEDED — see steps below]

Then branch based on status:

---

Branch A: Everything is healthy

Output:

Your Respira connection is healthy.

Quick-start commands to try right now:
- respira_list_pages — see all your pages
- respira_get_builder_info — find out which page builder you're using
- respira_get_site_context — full site overview

Skills available in the marketplace:
- "WordPress Site DNA" — full site audit
- "SEO & AEO Amplifier" — SEO health check
- "Internal Link Builder" — build internal links

---

Branch B: Plugin not installed or not active

Output:

## Respira Plugin Not Found

To connect your AI assistant to WordPress, install the Respira for WordPress plugin.

### Install steps (v7.1 OAuth, recommended):
1. Go to https://respira.press/releases
2. Download the latest version
3. In WordPress admin: Plugins, then Add New, then Upload Plugin
4. Activate the plugin
5. On the Setup screen, click "Connect respira.press account". The OAuth handshake links the licence to the user's respira.press account so plan changes sync automatically and host migrations don't require re-activation.

### Install steps (manual licence-key fallback):
1. Steps 1-4 above
2. On the Setup screen, click "Or paste a licence key manually"
3. Paste the key from respira.press/dashboard/licenses
4. Go to Res