sitepilot-mcp

sitepilot-mcp is the local transport and credential adapter for a WordPress site running the SitePilot MCP plugin. WordPress remains the policy-enforcement point: this package forwards the site's live tools/list and tools/call surface and does not register independent tools or safety policy.

Quick start

Requires Node.js 22 or later and an HTTPS WordPress site with SitePilot MCP 0.4.8 or later.

npx sitepilot-mcp login --url https://wordpress.example --scopes site:read
npx sitepilot-mcp init --client cursor --profile wordpress-example

Restart the client after init. Application Password login is the default; add --oauth for OAuth 2.1 with PKCE. Saved secrets live in ~/.config/sitepilot/profiles.json, are written with mode 0600 where the OS supports it, and are referenced—not copied—by generated client configuration.

The quick start intentionally resolves the current npm release. The generated client configuration does not: init writes the exact installed package version (for example, [email protected]) so a client restart cannot silently change the executable.

Run directly without a saved profile:

npx sitepilot-mcp --profile wordpress-example --transport http --port 8770

The HTTP transport binds to loopback and serves /mcp. Clients that support remote MCP and OAuth discovery can instead connect directly to https://wordpress.example/wp-json/sitepilot-mcp/v2/mcp without this package.

Client setup

init merges the sitepilot entry into an existing configuration and creates one pristine .bak copy before the first edit. Later runs preserve that original backup. It never writes a credential into a client file.

The primary compatibility matrix covers five independent coding-agent products: Claude Code, Codex, Cursor, Antigravity CLI, and Windsurf. Google replaced Gemini CLI with Antigravity CLI; its executable is agy. Antigravity IDE and Claude Desktop remain supported secondary installation targets and are verified separately rather than counted as additional products.

| Client | Configuration | Operating rules | Restart instruction | |---|---|---|---| | Claude Code (primary) | .mcp.json | CLAUDE.md | Restart the Claude Code session | | Codex (primary) | .codex/config.toml | AGENTS.md | Trust the project so Codex loads project-scoped configuration; restart the session; verify with /mcp | | Cursor (primary) | .cursor/mcp.json | .cursorrules | Developer: Reload Window | | Antigravity CLI (primary; agy alias) | .agents/mcp_config.json | AGENTS.md | Restart agy; verify with /mcp | | Antigravity IDE | ~/.gemini/config/mcp_config.json | .agents/rules/sitepilot.md | Refresh MCP servers; start a new Agent session | | Claude Desktop | platform Claude config | Site playbooks | Quit and reopen Claude Desktop | | Windsurf (primary) | ~/.codeium/windsurf/mcp_config.json | AGENTS.md | Reload Window |

Use --client major for the Owner-approved five-product primary set, or --client all to include Antigravity IDE and Claude Desktop. Clients without an independent installation marker are reported as skipped. SitePilot writes each client's documented local and remote field shape rather than treating the formats as interchangeable. Use --remote for native Streamable HTTP plus OAuth discovery:

npx sitepilot-mcp init --client codex --remote --url https://wordpress.example

That writes only the HTTPS MCP URL and transport. The npm command and local profile reference are omitted. The WordPress plugin also advertises editable site playbooks through prompts/list; bodies are fetched lazily with prompts/get, labelled as untrusted site-authored instructions, and never grant scope or approval.

Claude Code uses OAuth discovery when no scopes are supplied. To cap its request deliberately, pass init --client claude-code --remote --scopes site:read,content:write; the generated string-form oauth.scopes value is a ceiling, not a hint. Antigravity CLI and IDE accept only the documented URL-only remote shape; their documented oauth object is for client credentials and has no scope field. SitePilot therefore enforces their least-privilege default at the WordPress authorization server: a dynamically registered client that omits RFC 7591 scope is registered with site:read, and any broader authorization request is reduced to that ceiling before consent and token issue. Clients that intentionally need more authority must include the desired space-separated scope in Dynamic Client Registration. The npm adapter does this during login --oauth; its generated Antigravity configuration remains URL-only. init --scopes is rejected for every client except Claude Code because the other generated formats do not encode an equivalent ceiling. For Claude Code, when --profile names a saved credential and --scopes is omitted, init reuses that profile's granted scopes only if its normalized site URL matches the requested remote URL; a mismatch stops before any client configuration is written.

Zed, Cline, Warp, Continue, OpenCode, VS Code with Copilot, and other standards-compatible clients can use the same exact-version stdio command or canonical remote URL. They are generic MCP compatibility targets until their own real-install acceptance run is recorded; they are not silently counted as passed by the five-client matrix.

Commands

sitepilot-mcp login --url <url> [--oauth] [--scopes a,b] [--label text]
sitepilot-mcp logout --profile <name>
sitepilot-mcp init --client claude-code|claude-desktop|codex|cursor|agy|antigravity-cli|antigravity-ide|windsurf|major|all (--profile <name> | --remote --url <url>)
sitepilot-mcp init --client claude-code --remote (--profile <name> | --url <url>) [--scopes a,b]
sitepilot-mcp doctor --url <url>
sitepilot-mcp tools --url <url> [--json]
sitepilot-mcp call <tool> --input @plan.json [--dry-run]

Common flags: --profile, --api-version v1|v2, --timeout, --read-only, --allow-tier 0|1|2|3, and --version.

For migration compatibility, the former gemini and gemini-cli selections map to antigravity-cli; new documentation and generated output use agy/antigravity-cli.

Ambiguous family aliases are rejected: use claude-code or claude-desktop, and antigravity-cli/agy or antigravity-ide.

--read-only and --allow-tier are local ergonomics that avoid unwanted attempts. They are not a security boundary. WordPress capabilities, bounded credential scopes, risk classification, approvals, optimistic concurrency, auditing, and rollback remain authoritative in the plugin.

Before forwarding execute-change or rollback-change, the client performs one additional get-change-status call so it can enforce the local --allow-tier preference. The requested mutation and its arguments are otherwise forwarded unchanged; WordPress remains authoritative.

Run sitepilot-mcp doctor to distinguish insecure HTTP, unreachable REST, missing or inactive plugin, stripped authorization headers, invalid or revoked credentials, and insufficient scopes.

License

Apache-2.0. The WordPress plugin is licensed separately under AGPL-3.0-or-later.