# WP Navigator MCP

[![npm version](https://img.shields.io/npm/v/@littlebearapps/wp-navigator-mcp.svg)](https://www.npmjs.com/package/@littlebearapps/wp-navigator-mcp)
[![npm downloads](https://img.shields.io/npm/dm/@littlebearapps/wp-navigator-mcp.svg)](https://www.npmjs.com/package/@littlebearapps/wp-navigator-mcp)
[![CI](https://github.com/littlebearapps/wp-navigator-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/littlebearapps/wp-navigator-mcp/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/littlebearapps/wp-navigator-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/littlebearapps/wp-navigator-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**AI-powered WordPress management via Claude Code and MCP-compatible clients.**

Manage posts, pages, media, plugins, themes, and Gutenberg blocks through natural language — all with safe-by-default writes and full rollback support.

<!-- TODO: Add demo GIF when available
![Demo showing WP Navigator in action](https://raw.githubusercontent.com/littlebearapps/wp-navigator-mcp/main/docs/images/demo.gif)
-->

---

> **Coming Soon — January 2025**
>
> The **WP Navigator WordPress plugin** is not yet available. This MCP server requires the plugin to be installed on your WordPress site.
>
> **[Register your interest at wpnav.ai →](https://wpnav.ai)**

---

## Who Is This For?

| **WordPress Developer** | **Content Manager** |
|:---|:---|
| *"I want AI to help build and maintain sites"* | *"I want to manage content with natural language"* |
| You build WordPress sites and want AI assistance for development tasks. | You manage content and want faster, more intuitive workflows. |
| **Key features:** Gutenberg block editing, plugin management, theme switching, bulk operations | **Key features:** Post/page creation, media uploads, safe publishing, content rollback |

---

## What WP Navigator MCP Does

### Content Management

- Create and edit posts/pages with Gutenberg blocks
- Upload media from URLs (sideload images automatically)
- Manage comments, categories, and tags
- Full revision history with rollback support

### Site Management

- Install, activate, and manage plugins
- Switch and customize themes
- View and manage WordPress users

### Safety & Rollback

- **Safe by default** — Writes disabled until explicitly enabled
- **Full revision history** — Rollback any content change
- **Policy-based access** — WordPress plugin enforces granular permissions
- **HTTPS enforced** — Secure connections for non-localhost

---

## Quick Start

### 1. Install WP Navigator Plugin

<details>
<summary><strong>Free Version (WordPress.org)</strong></summary>

Search for "WP Navigator" in WordPress Plugins → Add New, or:

1. Download from [WordPress.org](https://wordpress.org/plugins/wp-navigator/)
2. Upload to `/wp-content/plugins/`
3. Activate the plugin

</details>

<details>
<summary><strong>Pro Version</strong></summary>

1. Purchase at [wpnav.ai/pro](https://wpnav.ai/pro)
2. Download the plugin ZIP
3. Upload via WordPress Admin → Plugins → Add New → Upload
4. Activate and enter your license key

</details>

### 2. Create Application Password

In WordPress Admin: **Users → Your Profile → Application Passwords**

1. Enter a name (e.g., "WP Navigator MCP")
2. Click "Add New Application Password"
3. Copy the password immediately (it won't be shown again)

### 3. Create Configuration File

Create `wpnav.config.json` in your project directory:

```json
{
  "WP_BASE_URL": "https://your-site.com",
  "WP_REST_API": "https://your-site.com/wp-json",
  "WPNAV_BASE": "https://your-site.com/wp-json/wpnav/v1",
  "WPNAV_INTROSPECT": "https://your-site.com/wp-json/wpnav/v1/introspect",
  "WP_APP_USER": "your-username",
  "WP_APP_PASS": "xxxx xxxx xxxx xxxx xxxx xxxx"
}
```

### 4. Configure Your MCP Client

<details>
<summary><strong>Claude Code</strong></summary>

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "wpnav": {
      "command": "npx",
      "args": ["-y", "@littlebearapps/wp-navigator-mcp", "./wpnav.config.json"],
      "env": {
        "WPNAV_ENABLE_WRITES": "1"
      }
    }
  }
}
```

</details>


> **Note**: `WPNAV_ENABLE_WRITES=1` enables create/update/delete operations. Without it, only read operations work (safe by default).

### 5. Verify Connection

In Claude, try:
> "Use wpnav_introspect to check the WordPress connection"

---

## CLI Mode

WP Navigator MCP also works as a standalone CLI for scripts and web-based AI agents.

### Invocation Patterns

```bash
# Recommended: Use the package directly (runs CLI if command provided)
npx @littlebearapps/wp-navigator-mcp init
npx @littlebearapps/wp-navigator-mcp --version
npx @littlebearapps/wp-navigator-mcp tools

# Alternative: Use the wpnav binary (installed globally or via npx -p)
npx -p @littlebearapps/wp-navigator-mcp wpnav init
npm install -g @littlebearapps/wp-navigator-mcp && wpnav init
```

> **Note**: The package is scoped, so `npx wpnav@version` won't work. Use the full package name `@littlebearapps/wp-navigator-mcp`.

### Initialize a Project

```bash
npx wpnav init                   # Interactive wizard (guided mode)
npx wpnav init --mode scaffold   # Quick setup without prompts
npx wpnav init --mode ai-handoff # Create AI-ready handoff document
npx wpnav init --repair          # Fix broken configuration (v2.4.0+)
```

Creates project structure with `wpnavigator.jsonc` manifest and `sample-prompts/` folder containing ready-to-use AI prompts (self-test, add-page, content-audit, etc.).

### Direct Tool Invocation

```bash
# List posts
npx wpnav call wpnav_list_posts --limit 5

# Get site overview
npx wpnav call wpnav_get_site_overview

# Preview a change without executing
npx wpnav call wpnav_update_post --id 1 --title "New Title" --dry-run
```

### Other Commands

```bash
npx wpnav status      # Check WordPress connection and plugin edition
npx wpnav tools       # List available tools
npx wpnav tools --format markdown  # Generate documentation
npx wpnav configure   # Set up credentials interactively
npx wpnav validate    # Validate config and manifest
npx wpnav doctor      # Run system diagnostics
npx wpnav cleanup     # Remove onboarding helper files
```

### Multi-Platform Support (v2.3.0)

```bash
# Generate MCP configuration for your platform
npx wpnav mcp-config --claude    # Claude Code (.mcp.json)
npx wpnav mcp-config --codex     # OpenAI Codex (config.toml)
npx wpnav mcp-config --gemini    # Google Gemini CLI (settings.json)

# Export config as environment variables
npx wpnav export-env             # Shell format
npx wpnav export-env --format docker  # Dockerfile
npx wpnav export-env --format github  # GitHub Actions
```

### Zero-Friction Setup (v2.7.0)

**Magic Link** — Connect instantly from WordPress admin:
```bash
# Copy link from WordPress → WP Navigator → Connect AI
npx wpnav connect wpnav://connect?site=example.com&token=abc123...
```

**Context for non-MCP agents** — Generate context for ChatGPT and other web AI:
```bash
npx wpnav context                # Markdown format
npx wpnav context --compact      # Reduced tokens
```

**Role management** — AI personas with focused tool access:
```bash
npx wpnav role list              # List available roles
npx wpnav role show developer    # Show role details
npx wpnav role set content-editor # Set active role
```

### AI Guidance Features (v2.6.0)

**Roles** — AI personas with focused tool access and behavior guidance:
```bash
npx wpnav call wpnav_list_roles           # List available roles
npx wpnav call wpnav_load_role --slug content-editor  # Load a role
```

Built-in roles: `content-editor`, `developer`, `seo-specialist`, `site-admin`

**Cookbooks** — Plugin-specific AI guidance for Gutenberg, Elementor, and more:
```bash
npx wpnav call wpnav_list_cookbooks       # List available cookbooks
npx wpnav call wpnav_load_cookbook --slug gutenberg  # Load cookbook
```

**MCP Resources** — Context delivery for AI assistants:
- `wpnav://tools/overview` — Categorized tool list
- `wpnav://site/context` — Current site information
- `wpnav://roles/{slug}` — Role definitions
- `wpnav://cookbooks/{slug}` — Plugin guidance

### Site Understanding Tools (v2.8.0)

**Site Health** — WordPress Site Health integration:
```bash
npx wpnav call wpnav_site_health                      # Full health report
npx wpnav call wpnav_site_health --categories security,performance
```

**Site Statistics & Settings** — Comprehensive site metrics:
```bash
npx wpnav call wpnav_site_statistics     # Posts, users, comments counts
npx wpnav call wpnav_site_settings       # General settings overview
```

**Discovery** — Explore WordPress capabilities:
```bash
npx wpnav call wpnav_list_rest_routes    # All REST API endpoints
npx wpnav call wpnav_list_shortcodes     # Registered shortcodes
npx wpnav call wpnav_list_block_patterns # Available block patterns
npx wpnav call wpnav_list_block_templates # FSE block templates
```

**Options Management** — Plugin options (safe by default):
```bash
npx wpnav call wpnav_get_option --option woocommerce_currency
npx wpnav call wpnav_set_option --option yoast_seo_title --value "My Site"
```

> **Security**: `wpnav_set_option` only allows plugin-detected prefixes (e.g., `woocommerce_*`, `yoast_*`). Core WordPress options are blocked.

**Maintenance** — Site maintenance operations:
```bash
npx wpnav call wpnav_flush_rewrite       # Flush rewrite rules
npx wpnav call wpnav_maintenance_mode --enable true   # Enable maintenance
npx wpnav call wpnav_maintenance_mode --enable false  # Disable maintenance
```

**AI-Friendly Suggestions** — Context-aware guidance:
```bash
npx wpnav suggest                        # Get contextual suggestions
npx wpnav suggest --limit 3              # Limit suggestions
```

### Snapshot & Sync Workflow

```bash
npx wpnav snapshot site       # Capture full site index
npx wpnav snapshot page about # Capture single page
npx wpnav diff                # Compare manifest vs WordPress
npx wpnav sync --dry-run      # Preview changes
npx wpnav sync                # Apply manifest to WordPress
npx wpnav rollback <id>       # Restore from pre-sync snapshot
```

See [CLI Reference](docs/cli-reference.md) for complete documentation.

---

## Project Structure

When you initialize a WP Navigator project with `npx wpnav init`, the following structure is created:

```
my-wp-project/
├── wpnavigator.jsonc       # Site manifest (your intent)
├── wpnav.config.json       # Connection configuration
├── .gitignore              # Ignores credentials and snapshots
├── snapshots/              # Site state snapshots
│   ├── site_index.json     # Full site structure
│   └── pages/              # Individual page snapshots
├── roles/                  # Custom AI role definitions
├── cookbooks/              # Custom plugin cookbooks (override bundled)
├── docs/                   # Project documentation
└── sample-prompts/         # Ready-to-use AI prompts
    ├── self-test.txt
    ├── add-page.txt
    └── content-audit.txt
```

### Directory Purposes

| Directory | Purpose | Git Status |
|-----------|---------|------------|
| `snapshots/` | Read-only state from WordPress | Ignore (regeneratable) |
| `roles/` | Custom AI behavior definitions | Commit |
| `cookbooks/` | Plugin-specific AI guidance | Commit |
| `docs/` | Project documentation | Commit |
| `sample-prompts/` | Reusable AI prompts | Commit |

### Recommended .gitignore

```gitignore
# Credentials (NEVER commit)
wpnav.config.json

# Snapshots (regenerate with wpnav snapshot)
snapshots/
```

---

## Available Tools

**93 tools** available through the [Dynamic Toolsets](#dynamic-toolsets-v270) architecture.

### MCP-Exposed Tools (5)

These tools are directly exposed to AI via MCP:

| Tool | Purpose |
|------|---------|
| `wpnav_introspect` | Check connection, policy, plugin status |
| `wpnav_search_tools` | Find tools by query or category |
| `wpnav_describe_tools` | Load full schemas for specific tools |
| `wpnav_execute` | Execute any tool dynamically |
| `wpnav_context` | Get context for non-MCP AI agents |

### Discoverable Tools (93)

All other tools are discovered via `wpnav_search_tools` and executed via `wpnav_execute`:

| Category | Tools | Examples |
|----------|-------|----------|
| **Core** | 7 | `wpnav_get_site_overview`, `wpnav_search`, `wpnav_list_post_types` |
| **Posts** | 7 | `wpnav_list_posts`, `wpnav_create_post_with_blocks` |
| **Pages** | 6 | `wpnav_list_pages`, `wpnav_snapshot_page` |
| **Media** | 4 | `wpnav_upload_media_from_url` |
| **Plugins** | 7 | `wpnav_list_plugins`, `wpnav_activate_plugin` |
| **Themes** | 7 | `wpnav_list_themes`, `wpnav_activate_theme` |
| **Gutenberg** | 7 | `wpnav_gutenberg_insert_block` |
| **Users** | 5 | `wpnav_list_users`, `wpnav_get_user` |
| **Comments** | 5 | `wpnav_list_comments`, `wpnav_create_comment` |
| **Taxonomy** | 12 | `wpnav_list_categories`, `wpnav_create_tag` |
| **Batch** | 3 | `wpnav_batch_get`, `wpnav_batch_update`, `wpnav_batch_delete` |
| **Cookbook** | 3 | `wpnav_list_cookbooks`, `wpnav_load_cookbook` |
| **Roles** | 2 | `wpnav_list_roles`, `wpnav_load_role` |
| **Options** | 2 | `wpnav_get_option`, `wpnav_set_option` |
| **Settings** | 2 | `wpnav_site_settings`, `wpnav_site_statistics` |
| **Health** | 1 | `wpnav_site_health` |
| **Discovery** | 4 | `wpnav_list_rest_routes`, `wpnav_list_shortcodes`, `wpnav_list_block_patterns` |
| **Maintenance** | 2 | `wpnav_flush_rewrite`, `wpnav_maintenance_mode` |

### CLI Tool Discovery

List and search tools via CLI:
```bash
npx wpnav tools                          # List all tools
npx wpnav tools --category gutenberg     # Filter by category
npx wpnav tools --search "create post"   # Search by query
```

---

## Architecture

```
┌─────────────────────┐     MCP Protocol     ┌────────────────────┐
│    Claude Code /    │ ◄──────────────────► │  WP Navigator MCP  │
│    MCP Clients      │                       │   (npm package)    │
└─────────────────────┘                       └─────────┬──────────┘
                                                        │ REST API
                                                        ▼
                                              ┌────────────────────┐
                                              │     WordPress      │
                                              │   + WP Navigator   │
                                              │      Plugin        │
                                              └────────────────────┘
```

### Dynamic Toolsets (v2.7.0)

WP Navigator uses a **Dynamic Toolsets** architecture for token efficiency:

| Approach | Token Usage | Tools Exposed |
|----------|-------------|---------------|
| **v2.6 (legacy)** | ~19,500 tokens | 75 individual tools |
| **v2.7+ (dynamic)** | ~500 tokens | 5 meta-tools (93 discoverable) |

**How it works:**

1. **Search** — AI uses `wpnav_search_tools` to find relevant tools by natural language query
2. **Describe** — AI uses `wpnav_describe_tools` to load full schemas for tools it wants to use
3. **Execute** — AI uses `wpnav_execute` to run tools with validated arguments

**Meta-tools exposed to AI:**

| Tool | Purpose |
|------|---------|
| `wpnav_introspect` | Check connection, policy, plugin status |
| `wpnav_search_tools` | Find tools by query or category |
| `wpnav_describe_tools` | Get full schemas for specific tools |
| `wpnav_execute` | Execute any tool dynamically |
| `wpnav_context` | Get context for non-MCP AI agents |

**Example flow:**
```
AI: "I need to create a blog post"

1. wpnav_search_tools(query: "create blog post")
   → Returns: wpnav_create_post, wpnav_create_post_with_blocks

2. wpnav_describe_tools(tools: ["wpnav_create_post_with_blocks"])
   → Returns: Full schema with parameters

3. wpnav_execute(tool: "wpnav_create_post_with_blocks", arguments: {...})
   → Creates the post
```

---

## Local Development (v2.4.0+)

WP Navigator supports local development environments like LocalWP, Docker, and MAMP.

### Environment Variable Credentials

Keep credentials out of config files using `$VAR` syntax:

```json
{
  "WP_BASE_URL": "http://localhost:8080",
  "WP_REST_API": "http://localhost:8080/wp-json",
  "WPNAV_BASE": "http://localhost:8080/wp-json/wpnav/v1",
  "WPNAV_INTROSPECT": "http://localhost:8080/wp-json/wpnav/v1/introspect",
  "WP_APP_USER": "$WP_APP_USER",
  "WP_APP_PASS": "$WP_APP_PASS"
}
```

Then set environment variables:
```bash
export WP_APP_USER="admin"
export WP_APP_PASS="xxxx xxxx xxxx xxxx"
```

### HTTP for Localhost

For local development without HTTPS:

```bash
ALLOW_INSECURE_HTTP=1 npx wpnav status
```

Or in your MCP config:
```json
{
  "env": {
    "ALLOW_INSECURE_HTTP": "1"
  }
}
```

### Repair Mode

Fix broken or outdated configuration:

```bash
npx wpnav init --repair
```

This validates existing files and regenerates any that are missing or invalid.

---

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `WPNAV_ENABLE_WRITES` | `0` | Enable write operations (create/update/delete) |
| `ALLOW_INSECURE_HTTP` | `0` | Allow HTTP for localhost development |
| `WPNAV_TOOL_TIMEOUT_MS` | `600000` | Per-tool timeout (10 minutes) |
| `WPNAV_MAX_RESPONSE_KB` | `64` | Maximum response size before truncation |
| `WP_APP_USER` | - | WordPress username (for env-based credentials) |
| `WP_APP_PASS` | - | WordPress application password (for env-based credentials) |

---

## Compatibility

| WP Navigator MCP | WP Navigator Free | WP Navigator Pro | Node.js |
|------------------|-------------------|------------------|---------|
| v1.0.x           | v1.0+             | v1.0+            | 18+     |

**MCP Clients:** Claude Code, Gemini CLI, any MCP-compatible client

**Platforms:** macOS (Apple Silicon & Intel), Linux (x64), Windows (via WSL)

---

## Quick Troubleshooting

| Issue | Solution |
|-------|----------|
| "Command starts MCP server" | Update to v2.8.0+, use `npx @littlebearapps/wp-navigator-mcp@latest` |
| "Config not found" | Config auto-discovers from parent dirs; use `--config` for explicit path |
| "401 Unauthorized" | Regenerate Application Password in WordPress Admin → Users → Profile |
| "WRITES_DISABLED" | Set `WPNAV_ENABLE_WRITES=1` environment variable |
| "Plugin not found" (404) | Ensure WP Navigator plugin is installed and activated |
| SSL errors | Use `ALLOW_INSECURE_HTTP=1` for localhost development |

**Full diagnostics:**
```bash
npx wpnav doctor          # Run system health checks
npx wpnav doctor --json   # JSON output for debugging
```

See [Troubleshooting Guide](docs/troubleshooting.md) for detailed solutions.

---

## Documentation

**Getting Started:**
- **[Getting Started](docs/getting-started.md)** — Quick setup in 5 minutes
- **[MCP Setup](docs/mcp-setup.md)** — Configure Claude Code, Codex, Gemini CLI

**Reference:**
- **[CLI Reference](docs/cli-reference.md)** — Complete command documentation
- **[Dynamic Toolsets](docs/DYNAMIC-TOOLSETS.md)** — Token-efficient tool discovery architecture
- **[Security](docs/security.md)** — Security model and best practices

**Guides:**
- **[Best Practices](docs/best-practices.md)** — Token optimization, security, and workflow tips
- **[AI Agent Guide](docs/ai-agent-guide.md)** — Dynamic Toolsets workflow for AI agents
- **[Troubleshooting](docs/troubleshooting.md)** — Common issues and solutions
- **[FAQ](docs/faq.md)** — Frequently asked questions
- **[Contributing](docs/contributing.md)** — How to contribute

---

## Support & Community

- **Bug Reports**: [Open an Issue](https://github.com/littlebearapps/wp-navigator-mcp/issues/new?template=bug_report.yml)
- **Feature Requests**: [Start a Discussion](https://github.com/littlebearapps/wp-navigator-mcp/discussions/new?category=ideas)
- **Questions**: [Ask in Discussions](https://github.com/littlebearapps/wp-navigator-mcp/discussions/new?category=q-a)
- **Documentation**: [wpnav.ai/docs](https://wpnav.ai/docs)

---

## Related Projects

| Project | Description |
|---------|-------------|
| [WP Navigator Free](https://wordpress.org/plugins/wp-navigator/) | WordPress plugin (Free) |
| [WP Navigator Pro](https://wpnav.ai/pro) | WordPress plugin (Premium) |

---

## License

MIT — see [LICENSE](LICENSE) for details.

---

**Made with care by [Little Bear Apps](https://littlebearapps.com)**

[Issues](https://github.com/littlebearapps/wp-navigator-mcp/issues) · [Discussions](https://github.com/littlebearapps/wp-navigator-mcp/discussions) · [Changelog](CHANGELOG.md)