# Niwa AI MCP — Agent Integration Notes

## ⚠️ CRITICAL: Always Use Raw JSON

When calling Niwa MCP tools from external agents (Claude, Codex, GPT, etc.),
**always send raw JSON strings** — never use language-level object serialization.

### Why?

PowerShell's `ConvertTo-Json` silently converts integers to strings and can
mangle Unicode. Python's `json.dumps()` works correctly. Node.js `JSON.stringify()`
works correctly. But PowerShell is unreliable.

**Bad (PowerShell):**
```powershell
# This will convert product_id 29 to "29" and may break tools
$args = @{ product_id = 29 } | ConvertTo-Json
```

**Good (raw JSON string):**
```powershell
$body = '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_page","arguments":{"page_id":29}}}'
```

## Tool Parameter Names

Some tools have specific parameter names that differ from what you might expect:

| Tool | Parameter | NOT this |
|------|-----------|----------|
| `set_product_featured_image_from_url` | `product_query` (string) or `product_id` (int) | ~~`product`~~ |
| `send_email_message` | `to_email` | ~~`to`~~, ~~`recipient_email`~~ |
| `trash_posts_by_query` | `search_query` | ~~`query`~~ |
| `elementor_find_widgets` | `widget_types` (array) | ~~`widget_type`~~ (singular) |
| `update_wp_settings` | `description` (for tagline) | ~~`tagline`~~, ~~`blogdescription`~~ |

## Tool Execution Flow

**Read-only tools** (get_*, list_*, search_*, woo_report_*):
→ Direct execution, no preview step.

**Write tools** (create_*, update_*, delete_*, trash_*):
→ Preview → Validate → Execute pipeline with automatic rollback support.

## Rollback

Every write operation stores rollback data. Call `rollback_last_action` to undo
the last change. Works for product changes, page edits, Elementor updates, etc.

## Known Working Tools (Tested 2026-03-18)

### ✅ Fully Working
- `get_site_info` — Site metadata, plugins, theme, content stats
- `get_wp_settings` — All WP settings
- `woo_report_sales` / `woo_report_orders_totals` / `woo_report_products_totals`
- `elementor_list_pages` — All Elementor pages
- `elementor_find_widgets` — Find widgets by type (use `widget_types` array)
- `elementor_update_widget_content` — Change heading/text content
- `elementor_update_widget_styles` — Change colors, typography
- `elementor_search_text` — Search ALL Elementor pages for text (returns widget IDs)
- `search_pages` / `search_media` / `search_users`
- `blog_posts_list` / `blog_post_get`
- `create_niwa_blog` — Canonical Markdown blog pipeline with governed taxonomy, contextual links, safe assets/schema, and a structured blocking quality report; creates drafts only
- `create_blog_post` — HTML compatibility adapter to that same pipeline, never a raw fallback
- `update_blog_post` — Canonical managed update with dependent asset/meta regeneration and rollback snapshot
- `publish_blog_post` — Publish the exact approved managed revision after a fresh current-state quality gate
- `create_product` / `update_simple_product` — WooCommerce products
- `create_page` — WordPress pages
- `upload_image_to_media` — Image upload from URL (auto WebP conversion)
- `create_wc_category` / `create_tag` — Taxonomy management
- `send_email_message` — Email via WordPress/SMTP (use `to_email` param)
- `file_read` / `file_create` — Read/write files in WP environment
- `skill_create` — Create custom Niwa skills
- `rollback_last_action` — Undo last write operation
- `trash_posts_by_query` — Trash posts/pages by search
- `list_wc_categories` / `list_categories` / `list_tags`
- `list_custom_post_types`
- `wp_option_get` — Read any WP option

### ⚠️ Known Issues
- `set_product_featured_image_from_url` — Use `product_query` (name string) not just `product_id`. Fix in progress to support direct ID lookup.
- `update_wp_settings` — May not pass `description` parameter through MCP bridge. Debug logging added. Investigating.
- `cache_settings_get` — Returns error if LiteSpeed Cache is not installed (expected behavior).
- `search_stock_images` — Requires API keys configured in Niwa settings (Pexels/Unsplash/Lummi).

## Image Source Smart Routing

`search_stock_images` uses smart routing based on content analysis:
- **Lummi AI** → marketing, tech, abstract, UI/UX, branding, people in business context
- **Pexels** → food, nature, places, architecture, lifestyle, physical products
- **Unsplash** → fallback

Each user/site provides their own API keys (not shared). Configure in Niwa AI Settings.
