{
  "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"
}

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

# 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

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+)

# 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

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

# 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

# Copy link from WordPress → WP Navigator → Connect AI
npx wpnav connect wpnav://connect?site=example.com&token=abc123...

npx wpnav context                # Markdown format
npx wpnav context --compact      # Reduced tokens

npx wpnav role list              # List available roles
npx wpnav role show developer    # Show role details
npx wpnav role set content-editor # Set active role

npx wpnav call wpnav_list_roles           # List available roles
npx wpnav call wpnav_load_role --slug content-editor  # Load a role

npx wpnav call wpnav_list_cookbooks       # List available cookbooks
npx wpnav call wpnav_load_cookbook --slug gutenberg  # Load cookbook

npx wpnav call wpnav_site_health                      # Full health report
npx wpnav call wpnav_site_health --categories security,performance

npx wpnav call wpnav_site_statistics     # Posts, users, comments counts
npx wpnav call wpnav_site_settings       # General settings overview

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

npx wpnav call wpnav_get_option --option woocommerce_currency
npx wpnav call wpnav_set_option --option yoast_seo_title --value "My Site"

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

npx wpnav suggest                        # Get contextual suggestions
npx wpnav suggest --limit 3              # Limit suggestions

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

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

# Credentials (NEVER commit)
wpnav.config.json

# Snapshots (regenerate with wpnav snapshot)
snapshots/

npx wpnav tools                          # List all tools
npx wpnav tools --category gutenberg     # Filter by category
npx wpnav tools --search "create post"   # Search by query

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

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

{
  "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"
}

export WP_APP_USER="admin"
export WP_APP_PASS="xxxx xxxx xxxx xxxx"

ALLOW_INSECURE_HTTP=1 npx wpnav status

{
  "env": {
    "ALLOW_INSECURE_HTTP": "1"
  }
}

npx wpnav init --repair

npx wpnav doctor          # Run system health checks
npx wpnav doctor --json   # JSON output for debugging