respira-wordpress-mcp

<p align="center">
  <a href="https://respira.press">
    <img src="https://respira.press/hero/storefront-hero.jpg" alt="Respira v6.0 Storefront — AI Infrastructure for WordPress" width="100%">
  </a>
</p>

<h1 align="center">Respira WordPress MCP Server</h1>

<p align="center">
  <strong>180+ MCP tools. 12 page builders. Context-aware tool filtering. The AI infrastructure layer for WordPress.</strong><br>
  Element-level editing, full page creation, HTML-to-builder conversion with rendering fidelity validation, per-site tool governance, storefront design intelligence, stock images, bulk operations — all through one MCP server.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@respira/wordpress-mcp-server"><img src="https://img.shields.io/npm/v/@respira/wordpress-mcp-server.svg?style=flat-square&color=10b981" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/@respira/wordpress-mcp-server"><img src="https://img.shields.io/npm/dm/@respira/wordpress-mcp-server.svg?style=flat-square" alt="npm downloads"></a>
  <img src="https://img.shields.io/badge/tools-172+-10b981?style=flat-square" alt="172+ Tools">
  <img src="https://img.shields.io/badge/builders-12-10b981?style=flat-square" alt="12 Page Builders">
  <img src="https://img.shields.io/badge/TypeScript-100%25-blue?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
</p>

<p align="center">
  <a href="https://respira.press">Website</a> •
  <a href="https://respira.press/docs">Docs</a> •
  <a href="https://respira.press/plugin">Plugin</a> •
  <a href="https://respira.press/support">Support</a> •
  <a href="https://respira.press/addons/woocommerce">WooCommerce Add-on</a>
</p>

---

## What this repo is, what it isn't

This repository is the **public listing** for the Respira WordPress MCP server. The actual server source ships on npm as [`@respira/wordpress-mcp-server`](https://www.npmjs.com/package/@respira/wordpress-mcp-server) — that wrapper code is **MIT-licensed** and you're welcome to read, fork, or vendor it.

The server is a **client for the Respira WordPress plugin**, not a standalone product. To do real work it needs:
- The [Respira for WordPress](https://respira.press/plugin) plugin installed on your site
- A valid Respira API key bound to a license

**The plugin (1000+ PHP files implementing builder intelligence, snapshots, governance, etc.) is not open source.** It's distributed under a commercial license. Free trial available at [respira.press](https://respira.press); paid plans start at €9/mo.

In short: the wrapper you `npx -y` is open. The product behind it isn't. If you want a self-contained "AI-edits-WordPress" stack with no commercial dependency, this isn't it — and that's by design. The plugin is built and maintained full-time, and the license fees are how that happens.

For security reports see [SECURITY.md](./SECURITY.md).

---

## What Makes Respira Different

Other WordPress MCP servers wrap the REST API. They can create posts and pages, but **they can't touch your page builder content**.

Respira includes a WordPress plugin that gives AI **native access** to 12 page builders — plus element-level precision, full page creation from structure, HTML-to-builder conversion, storefront design intelligence, stock image search, and bulk operations across hundreds of pages.

### New in v6.0: Context-Aware Tool Filtering

The MCP server automatically filters the tool list based on your site's detected builder and active plugins. A Divi site without WooCommerce sees ~130 tools instead of ~170. Less noise, faster AI responses, lower token usage. Fail-open: if detection fails, the full list is returned.

| Capability | Respira | Other MCP Servers |
|---|---|---|
| Page builder support | **12 builders** (incl. Flatsome) | None |
| Element-level find/update/move/remove | **Yes** | No |
| Build full pages from structure | **Yes** | No |
| Convert HTML to native builder | **Yes** | No |
| Stock image search + sideload | **Yes** | No |
| Bulk operations (100 pages/call) | **Yes** | No |
| 27 widget shortcuts (add_heading, etc.) | **Yes** | No |
| Duplicate-before-edit safety | **Yes** | No |
| Snapshot rollback | **Yes** | No |
| SEO / Core Web Vitals / AEO analysis | **Yes** | No |
| WooCommerce (products, orders, inventory) | **Yes** (add-on) | No |
| Tool governance (per-tool enable/disable) | **Yes** | No |

---

## Quick Start (3 Minutes)

### Step 1: Install the WordPress Plugin

Download from [respira.press/plugin](https://respira.press/plugin) → upload to WordPress → activate → go to **Respira > API Keys** → generate a key.

### Step 2: Configure Your AI Tool

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add respira-wordpress -- npx -y @respira/wordpress-mcp-server
```

</details>

<details>
<summary><b>Cursor</b></summary>

Create `.cursor/mcp.json` in your project:
```json
{
  "mcpServers": {
    "respira-wordpress": {
      "command": "npx",
      "args": ["-y", "@respira/wordpress-mcp-server"]
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

Add to your Windsurf MCP configuration:
```json
{
  "mcpServers": {
    "respira-wordpress": {
      "command": "npx",
      "args": ["-y", "@respira/wordpress-mcp-server"]
    }
  }
}
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
  "mcpServers": {
    "respira-wordpress": {
      "command": "npx",
      "args": ["-y", "@respira/wordpress-mcp-server"]
    }
  }
}
```

</details>

### Step 3: Add Your Site

Create `~/.respira/config.json`:
```json
{
  "sites": [
    {
      "id": "my-site",
      "name": "My WordPress Site",
      "url": "https://yoursite.com",
      "apiKey": "respira_your-api-key",
      "default": true
    }
  ]
}
```

Or run the interactive setup wizard: `npx @respira/wordpress-mcp-server --setup`

### Tool Limit? Use `enabledTools`

Some MCP clients (Antigravity, etc.) have a hard limit on active tools (often 100). Respira exposes 172 tools by default. To stay under the limit, add `enabledTools` to your config — only those tools will appear in the listing:

```json
{
  "sites": [{ "..." : "..." }],
  "preferences": {
    "enabledTools": [
      "respira_read_page",
      "respira_update_page",
      "respira_list_pages",
      "respira_find_element",
      "respira_update_element",
      "respira_build_page",
      "respira_get_site_context",
      "respira_get_builder_info"
    ]
  }
}
```

Site management tools (`respira_list_sites`, `respira_switch_site`, `respira_get_active_site`) are always included. Unlisted tools still work if called — the filter only controls what's advertised to the client.

**Done.** Restart your AI tool and start editing.

---

## v6.3 — MCP Protocol Compliance

### `structuredContent` in All Tool Results
Every successful tool response now includes `structuredContent` — the raw JSON object — alongside the existing `content[0].text` (stringified JSON). This follows the MCP 2025-06-18 spec. Clients that understand `structuredContent` get direct programmatic access to tool results without parsing JSON from text. Older clients are unaffected — the `content` array is still there.

### Improved Error Taxonomy
Unknown tool names now return a proper `CallToolResult` with `isError: true` and a hint to discover available tools, instead of throwing a protocol-level JSON-RPC error. This lets LLMs self-correct gracefully rather than hitting a hard protocol failure.

---

## v6.0 "Storefront" — What's New

### Context-Aware Tool Filtering
The MCP server automatically filters the tool list based on your site's detected builder and active plugins. A Divi site without WooCommerce sees ~130 tools instead of ~170. Less noise, faster AI responses, lower token usage. Fail-open: if detection fails, the full list is returned.

### Flatsome UX Builder (Builder #12)
Full round-trip shortcode editing, element-level precision, declarative page creation, and 55-element intelligence. Detected by active theme — mixed-builder sites handled per-page.

### 15 New WooCommerce Commerce Tools
Storefront design intelligence bridges commerce data and page builder visuals. Bulk pricing, catalog health audits, advanced filtering, natural language product search. Total WooCommerce tools: 36.

### Element-Level Operations
Find, update, move, duplicate, and remove individual elements inside any page builder — by ID, type, CSS class, or content text.

```
respira_find_element({ post_id: 42, identifier_type: "type", identifier_value: "heading" })
respira_update_element({ post_id: 42, identifier_type: "content", identifier_value: "Old Title", updates: { heading: "New Title" } })
```

### Build Full Pages
Create complete pages from a declarative widget structure in one call.

```
respira_build_page({ title: "Services", structure: [
  { type: "heading", settings: { heading: "Our Services", tag: "h1" } },
  { type: "text", settings: { text: "<p>We build amazing things.</p>" } },
  { type: "button", settings: { text: "Get Started", link: "/contact" } }
]})
```

### HTML-to-Builder Conversion
Convert any HTML into native builder widgets — with CSS extraction, responsive mapping, and a fidelity report.

```
respira_convert_html_to_builder({ html: "<section>...</section>", options: { title: "Homepage", preserve_tokens: true } })
→ { page_id: 123, fidelity: { score: 92, sections_matched: 14 } }
```

### Stock Images
Search Openverse (Creative Commons) and sideload directly into the Media Library with auto-attribution.

```
respira_search_stock_images({ query: "mountain landscape", per_page: 10 })
respira_sideload_image({ url: "https://...", caption: "Photo by...", alt: "Mountain" })
```

### Bulk Operations
Apply changes across up to 100 pages in a single call — with mandatory snapshots for rollback.

```
respira_bulk_pages_operation({ page_ids: [