Product overview

Guarded Model Context Protocol (MCP) and OAuth 2.1 Control Plane for WordPress Automation

Public product website: sitepilot.tools

SitePilot MCP connects coding agents (such as Claude, ChatGPT, Cursor, and custom agentic frameworks) to WordPress sites. It provides a deterministic policy-enforcement plane for inspecting site health, staging drafts, compiling HTML/CSS to builder layouts, and executing governed, reversible mutations across Gutenberg, Elementor 3 and bounded mixed Elementor 4 documents, WooCommerce, and Enfold Advanced Layout Builder (ALB).

[!TIP] New to SitePilot? Follow the read-only quick start. It uses two commands, one client restart, and one bounded inspection without changing site content.

---

Table of Contents

• What SitePilot Is
• Read-Only Setup
• What SitePilot Refuses to Do
• Key Features
• Builder Compatibility Matrix
• Known Builder Limitations
• System Architecture
  • Architecture Diagram
  • Trust Boundaries & Policy Enforcement
  • Guarded change-set state machine
• Repository Structure
• Tech Stack
• Prerequisites
• Risk Governance & Security Model
  • 4-Tier Risk Matrix
  • Fail-Closed Prohibitions
  • OAuth 2.1 PKCE S256
• Database Schemas
  • WordPress DB Tables
• Configuration & Environment Variables
  • WordPress Constants
• Available Scripts
• Testing & Quality Verification
• Production Deployment
  • Direct WordPress Plugin
• Troubleshooting
• Documentation Index
• License & Security Disclosure

---

What SitePilot Is

SitePilot is deterministic, approval-gated WordPress control for coding agents. The WordPress plugin exposes typed operations over Gutenberg, Elementor 3 and bounded mixed Elementor 4 documents, Enfold, and WooCommerce while the site enforces credentials, scopes, risk tiers, approvals, audit records, and rollback data.

The npm adapter connects clients that need local stdio and installs their configuration without copying credentials into project files. Clients with native remote MCP and OAuth support can connect directly to the WordPress endpoint.

SitePilot is agent-driven and human-gated. It does not give a model general server access.

Read-Only Setup

Requires Node.js 22 or later, Cursor, and an HTTPS WordPress site with SitePilot MCP 0.4.10 or later active. Replace the example URL with your site.

npx -y sitepilot-mcp@0.1.6 login --url https://your-site.example --scopes site:read --profile my-site
npx -y sitepilot-mcp@0.1.6 init --client cursor --profile my-site

Approve the Application Password request in WordPress, reload Cursor once with Developer: Reload Window, then ask the agent to call sitepilot-inspect-site. The connection starts read-only with site:read.

For expected output, cleanup, and a secret-safe evidence template, follow the read-only quick start.

What SitePilot Refuses to Do

These operations are absent from SitePilot’s schemas. An agent cannot request them through the product:

• Execute arbitrary PHP, JavaScript, SQL, shell commands, or WP-CLI.
• Read server secrets or credentials.
• Read or modify wp-config.php, .htaccess, or arbitrary filesystem paths.
• Bypass WordPress capabilities, credential scopes, risk classification, or approval gates.
• Treat a partial rollback as success.

Sensitive supported operations stop at a hash-bound, expiring WordPress approval. Unsupported operations fail closed.

---

Key Features

• 4-Tier Risk Governance: From read-only introspection (Tier 0) and safe draft staging (Tier 1) to standard approval (Tier 2) and admin-gated high-risk operations (Tier 3), every mutation requires explicit authorization, cryptographic binding, and idempotency keys.
• Fail-Closed Security: Raw PHP execution, arbitrary SQL, shell access, WP-CLI invocations, server secret inspection, and wp-config.php edits are strictly prohibited and unrepresented in tool schemas.
• Guarded Change Sets & Compensation: Pre-mutation snapshots capture affected post data and metadata. Rollback replays ordered compensating operations in reverse; a partial rollback is reported as failed, never as restored.
• Deep Enfold ALB Support: Read-only page, runtime-element, theme-token, and page-setting inspection; calibrated native ALB shortcode staging; lossless typed ALB document parsing with UID/path identity; atomic granular edits with conflict detection; and bounded network-disabled best-effort HTML/CSS-to-ALB drafts (design.compile_enfold_html) with early suitability checks, request-first component mappings, coverage manifests, and Media Library URL resolution.
• Guarded Elementor 3/4 Support: Mixed classic/atomic documents inspect with per-region editability. Classic elements support construction and structural edits; existing runtime-only atomic elements permit known typed-setting updates only. Elementor 4 atomic global-style writes fail closed.
• Self-Hosted First: Operates as a completely standalone, self-hosted WordPress plugin over standard HTTP/REST MCP endpoints without mandatory third-party cloud accounts.

---

Builder Compatibility Matrix

Builder / Framework	Inspection	Draft Staging	HTML/CSS Compilation	Granular Element Edit	Publishing Approval	Rollback
Gutenberg (Core)	✅	✅	Native Blocks	Block parser	Tier 2 Approval	✅
Enfold (ALB)	✅ Page outline, elements, globals, settings	✅ (Calibrated)	✅ (best-effort draft + manifest)	✅ (design.edit_elements)	Tier 2 Approval	✅
Elementor 3 + mixed 4.x	✅ Per-region truth	✅ Classic documents	✅ Classic containers/widgets	✅ Classic; atomic known settings only	Tier 2 Approval	✅
WooCommerce	✅	✅ (Catalog/Stock)	N/A	Order/Product APIs	Tier 2/3 Approval	✅

Known Builder Limitations

• Elementor 4 atomic documents: mixed pages inspect per region and existing atomic elements accept known typed-setting updates only. Atomic element construction, structural edits, and Global Classes or Variables writes are unsupported.
• Enfold nested globals: SitePilot reads and writes only inspected scalar colour and typography keys. Uncalibrated nested Enfold 7.x structures in avia_options_enfold remain unsupported and must be changed by an administrator in Enfold.
• Cloud-only evidence: visual regression baselines and whole-site durable builds require the optional SitePilot cloud control plane. The self-hosted plugin and npm adapter do not claim those capabilities.
• Compiler verification: HTML/CSS-to-builder compilation is bounded and best effort. It does not provide a pixel-similarity guarantee; inspect the staged artifact before approval.

• Rollback boundary: WordPress does not provide one transaction across posts, metadata, terms, and commerce records. SitePilot snapshots affected state and applies compensations in reverse order; a partial compensation is reported as failed.

---

System Architecture

Architecture Diagram

graph TD
    Client["AI Agent / MCP Client<br/>(Claude Desktop, Cursor, ChatGPT, Codex)"]

    subgraph WP ["WordPress Policy Enforcement Point (Self-Hosted)"]
        Plugin["SitePilot MCP Plugin<br/>(/wp-json/sitepilot-mcp/v2/mcp)"]
        OAuth["OAuth 2.1 PKCE S256 Server<br/>(Hashed Opaque Grants)"]
        RiskEngine["4-Tier Risk Engine"]
        StateMachine["Guarded Change Sets<br/>& Reverse Compensation"]
        AuditLog[("Audit Log & Snapshots<br/>wp_sitepilot_* Tables")]
        Adapters["Builder Adapters<br/>(Gutenberg, Elementor 3 / mixed 4, Enfold, Woo)"]
    end

    Client -->|Direct MCP / OAuth| Plugin
    Plugin --> OAuth
    Plugin --> RiskEngine
    Plugin --> StateMachine
    StateMachine --> AuditLog
    StateMachine --> Adapters

Trust Boundaries & Policy Enforcement

The self-hosted WordPress plugin is the Policy Enforcement Point (PEP) for all site operations. No client or optional orchestration service can bypass WordPress user capabilities, credential scopes, risk classification, approval gates, optimistic version digests, or database audit logging.

Guarded change-set state machine

Every mutating operation traverses an immutable lifecycle:

[planned] ──> [awaiting_approval] ──> [approved] ──> [executing] ──> [validating] ──> [completed]
                      │                     │                                             │
                      └── (rejection/timeout) └── (execution error) ──> [rolled_back] / [failed]

1. planned: The agent computes changes, validates schemas, and checks expected_version site digests.
2. awaiting_approval: For Tier 2/3 operations, a changeset hash is generated and an approval request is registered (expires in 30 minutes).
3. approved: An authorized operator (or administrator for Tier 3) approves the cryptographic changeset hash.
4. executing: Pre-mutation snapshot is saved to wp_sitepilot_changesets; modifications are applied via builder adapters.
5. validating: Output structure, post status, and design coverage are verified.
6. completed: Audit event is committed to wp_sitepilot_audit.
7. rolled_back: Recorded compensating operations run in reverse order. WordPress has no cross-table transaction here; any partial rollback is terminally failed.

---

Repository Structure

sitepilot-mcp/
├── packages/
│   ├── contracts/              # Published TypeScript schemas, fixtures, and risk contracts
│   └── mcp-server/             # Local stdio/HTTP transport and credential adapter
├── plugins/
│   └── sitepilot-mcp/          # WordPress Plugin & direct MCP Server (PHP 8.2+)
│       ├── languages/          # Translation catalogs (.po / .mo)
│       ├── src/
│       │   ├── Abilities/      # Registered WordPress abilities & MCP tools
│       │   ├── Adapters/       # Gutenberg, Elementor 3 / mixed 4, Enfold & WooCommerce adapters
│       │   ├── Admin/          # WP Admin pages, settings & diagnostics screens
│       │   ├── Artifacts/      # Media import, artifact validation & handoffs
│       │   ├── Changes/        # Changeset state machine, rollback & snapshots
│       │   ├── Infrastructure/ # Database installer, migrations & logging
│       │   ├── OAuth/          # OAuth 2.1 PKCE S256 server implementation
│       │   ├── Policy/         # Risk engine, capabilities & scope verification
│       │   └── Plugin.php      # Main plugin bootstrap & hook registrations
│       ├── tests/              # PHPUnit unit and integration test suites
│       ├── composer.json       # PHP dependencies (Jetpack autoloader, mcp-adapter)
│       └── sitepilot-mcp.php   # Main WordPress plugin entrypoint
├── docs/                       # Technical specifications, ADRs & security guides
│   ├── adr/                    # Architecture Decision Records
│   ├── api-reference.md        # Complete MCP tool schemas & parameters
│   ├── architecture.md         # WordPress trust boundaries and state machine
│   ├── elementor.md            # Elementor builder integration manual
│   ├── enfold.md               # Enfold ALB calibration & HTML compiler guide
│   ├── plugin-guide.md         # Operator handbook, roles & OAuth flows
│   ├── release-gates.md        # Quality assurance & security checklist
│   └── security.md             # Security architecture, STRIDE analysis & policy
├── scripts/                    # Build, test, packaging & signing toolchains
│   ├── check-php-syntax.mjs    # AST syntax verification for PHP code
│   ├── compile-translations.mjs# Compiles .po files to binary .mo catalogs
│   ├── package-plugin.mjs      # Reproducible direct-distribution ZIP packager
├── .wp-env.6.9.json            # WordPress 6.9 Docker environment config
├── .wp-env.7.0.json            # WordPress 7.0 Docker environment config
├── .wp-env.nightly.json        # WordPress nightly Docker environment config
├── package.json                # Root workspace configuration
└── llms.txt                    # LLM discovery manifest for autonomous agents

---

Tech Stack

Layer	Technologies
WordPress Plugin	PHP 8.2+, automattic/jetpack-autoloader, wordpress/mcp-adapter, WordPress 6.9+
Type Contracts	TypeScript 5.9, Zod 4.0
Tooling & QA	ESLint 10, Vitest 4, PHPUnit 11, PHPStan 2, PHPCS (WordPress-Core), @wordpress/env
Cryptography	Ed25519 (PKCS#8), SHA-256, HMAC-SHA256, OAuth 2.1 PKCE S256

---

Prerequisites

Before setting up SitePilot MCP locally, ensure you have the following installed:

• Node.js: v22.0.0 or higher
• npm: v10.0.0 or higher
• PHP: 8.2 or higher with ext-dom, ext-json, ext-openssl, ext-sodium
• Composer: v2.6 or higher
• Docker: Required for running @wordpress/env local instances
• Git: Latest version

---

Public installation and source access

SitePilot’s product repository and internal contributor workflow are private. Public readers should install the released adapter from npm and use the documented client setup.

The published adapter source is available in the public npm mirror. Source-development instructions are provided only to authorized contributors.

Risk Governance & Security Model

4-Tier Risk Matrix

Every SitePilot operation is classified into a strict risk tier:

Tier	Category	Approval Policy	Typical Operations
Tier 0	Read-Only	None (Automatic execution)	sitepilot.inspect_site, sitepilot.search_capabilities, sitepilot.inspect_navigation
Tier 1	Safe Staging	Automatic within scope	Draft page creation, media staging, HTML/CSS compiler passes
Tier 2	Sensitive Mutation	Standard Approval (30 min expiry)	Publishing content, stock/price changes, trash operations, theme documents
Tier 3	High Risk	Administrator Approval Required	Theme activation, plugin installs, WooCommerce order refunds, core updates

Fail-Closed Prohibitions

The following capabilities are deliberately blocked at the architecture level and have no tool definitions:

• ❌ Direct arbitrary PHP code execution (eval, create_function, file injections)
• ❌ Raw SQL query execution or direct table drops
• ❌ Shell commands / exec / system / passthru
• ❌ WP-CLI remote command invocation
• ❌ Modification or reading of wp-config.php, .htaccess, or server secrets
• ❌ Root filesystem deletion

OAuth 2.1 PKCE S256

• Authorization Code Flow with mandatory code_challenge (S256).
• Opaque Hashed Tokens: Access tokens and refresh tokens are SHA-256 hashed prior to database persistence.

---

Database Schemas

WordPress DB Tables

On plugin activation, SitePilot creates isolated tables with the site prefix (wp_sitepilot_*):

Table	Purpose
wp_sitepilot_oauth_clients	Registered dynamic OAuth clients, client IDs, and metadata.
wp_sitepilot_oauth_grants	Active and revoked authorization grants and consented scopes.
wp_sitepilot_oauth_codes	One-time PKCE authorization codes with S256 challenges.
wp_sitepilot_oauth_tokens	SHA-256 hashed bearer and refresh tokens with expiration timestamps.
wp_sitepilot_changesets	Two-phase mutation records, pre-mutation snapshots, and rollback payloads.
wp_sitepilot_approvals	Operator and administrator approval records bound to changeset SHA-256 hashes.
wp_sitepilot_audit	Immutable audit log of all executed mutations, actors, IPs, and results.
wp_sitepilot_artifacts	Staged media and build artifacts pending validation.
wp_sitepilot_idempotency	Idempotency locks and response caches preventing duplicate execution.

Configuration & Environment Variables

WordPress Constants

Define these in wp-config.php as needed:

Constant	Type	Default	Description
SITEPILOT_MCP_ALLOW_INSECURE_LOCAL	bool	false	Allows HTTP connections when WP_ENVIRONMENT_TYPE === 'local'.

Available Scripts

Command	Description
npm run build	Builds TypeScript packages (@instantbuild-sitepilot/contracts) and workspaces.
npm run check	Runs TypeScript typechecks (tsc --noEmit) across all workspaces.
npm run lint	Runs ESLint across all TypeScript and JavaScript files.
npm test	Runs Node script tests and the Vitest suites in @instantbuild-sitepilot/contracts.
npm run check:php-syntax	Checks all PHP files in plugins/sitepilot-mcp/ for syntax errors.
npm run check:runtime-licenses	Rejects missing or GPLv2-only PHP runtime dependency licences.
npm run build:translations	Compiles .po gettext catalogs into binary .mo files.
npm run package:plugin	Packages the direct release WordPress plugin ZIP into dist/ and build/.
composer --working-dir=plugins/sitepilot-mcp test	Runs PHPUnit test suite for the WordPress plugin.
composer --working-dir=plugins/sitepilot-mcp lint	Runs PHP_CodeSniffer with WordPress Coding Standards.
composer --working-dir=plugins/sitepilot-mcp analyse	Runs PHPStan static analysis with WordPress stubs.

---

Testing & Quality Verification

1. Run Complete Repository Test Suite

# 1. Typecheck and lint
npm run check
npm run lint

# 2. Check PHP syntax
npm run check:php-syntax

# 3. Run Vitest & Node unit tests
npm test

2. Run PHPUnit & Static Analysis

cd plugins/sitepilot-mcp

# Run PHPUnit tests
composer test

# Run PHP CodeSniffer (WPCS)
composer lint

# Run PHPStan Level 5+ analysis
composer analyse

3. Multi-Version WordPress Integration Testing

Test compatibility across multiple WordPress releases using @wordpress/env:

# Test on WordPress 6.9
npx wp-env start --config=.wp-env.6.9.json
npm run test:e2e # (if configured)
npx wp-env stop

# Test on WordPress 7.0
npx wp-env start --config=.wp-env.7.0.json
npx wp-env stop

# Test on WordPress Nightly
npx wp-env start --config=.wp-env.nightly.json
npx wp-env stop

---

Production Deployment

Direct WordPress Plugin

1. Build the production package:

   composer install --working-dir=plugins/sitepilot-mcp --no-dev --optimize-autoloader
   npm run build:translations
   npm run package:plugin

2. Upload plugins/sitepilot-mcp/dist/sitepilot-mcp.zip to WordPress (Plugins → Add New → Upload Plugin).
3. Activate the plugin and navigate to SitePilot → Diagnostics to verify environment readiness.

Supported distribution

SitePilot MCP is distributed to authorized operators through an Owner-managed release channel. Public documentation does not publish internal signing, storage, or channel-configuration procedures.

Troubleshooting

1. OAuth Discovery or Authorization Fails

• Symptom: Client reports 404 Not Found or Invalid Redirect URI during OAuth.
• Fix: Verify WordPress home and siteurl use the exact HTTPS origin. Ensure /.well-known/oauth-authorization-server is accessible and not blocked by security plugins or web server rewrite rules.

2. Enfold ALB Profile Unverified

• Symptom: sitepilot_enfold_profile_unverified when attempting ALB mutations.
• Fix: Enfold requires a one-time calibration to detect theme metadata keys. Go to SitePilot → Diagnostics (or run a Tier-3 profile calibration) by saving one native ALB test page to establish the site-specific verified metadata profile.

3. Elementor Styling / CSS Not Updating

• Symptom: A supported Elementor 3 or bounded mixed Elementor 4 update is staged, but frontend styling appears broken.
• Fix: SitePilot executes saves through ElementorDocumentStore, which automatically invalidates Elementor’s CSS file cache. If caching layers exist, purge external page, CDN, and object caches.

4. Insecure Local Development Error

• Symptom: SitePilot MCP requires HTTPS when testing locally over HTTP.
• Fix: Set WP_ENVIRONMENT_TYPE to local and define define('SITEPILOT_MCP_ALLOW_INSECURE_LOCAL', true); in your local wp-config.php.

Documentation Index

Guide	Description
Public SitePilot Website	English-first product overview with Greek under /el/, quick start, security model, compatibility, licensing, and responsible disclosure. Technical guides remain linked below.
Read-Only Quick Start	Beginner-safe two-command setup, one bounded inspection, and a secret-safe evidence checklist.
MCP API Reference	Formal JSON schemas, tool definitions, request/response models, and error codes.
Plugin Operator Guide	Complete guide to WordPress plugin configuration, roles, OAuth grants, and diagnostic checks.
System Architecture	Deep dive into WordPress trust boundaries, state machines, and lifecycle design.
C4 System Context	C4 Level 1 context diagrams, personas, user journeys, and external system boundaries.
Current Product State	Dated canonical product status, verification state, open gates, and limitations.
Security Model & Threat Assessment	STRIDE threat model, OAuth 2.1 PKCE security, envelope encryption, and fail-closed policies.
Enfold ALB Guide	Calibration mechanisms, shortcode AST mapping, HTML-to-ALB compiler, and structure modes.
Elementor Guide	Element-by-element editing, HTML-to-Elementor compilation, global kit tokens, and templates.
Release Gates & QA Checklist	Pre-release verification gates, test requirements, and security audits.
Architecture Decision Records (ADR)	Design rationale, architectural trade-offs, and state machine decisions.

---

License & Security Disclosure

• Licences: The WordPress plugin is AGPL-3.0-or-later; @instantbuild-sitepilot/contracts and the published sitepilot-mcp adapter are Apache-2.0; SitePilot Cloud is proprietary and undistributed. See LICENSING.md for the complete artifact-by-artifact policy.
• Security Vulnerability Reporting: If you discover a potential security issue in SitePilot MCP, please follow the responsible disclosure process detailed in docs/security.md. Do not file public GitHub issues for security vulnerabilities.

---

Public normalization derived from product commit 00c30de825b68dc14535f6455e82c927ad256b47, file README.md. See source-manifest.json for the source digest and declared normalization classes.