stonewright-wp-mcp

Stonewright MCP presents a compact, task-aware surface backed by 397 Plugin abilities and 105 Direct tools. Elementor is a first-class Plugin surface; Gutenberg, WooCommerce, WordPress REST, and tokenized WP-CLI workflows use the same evidence-oriented operating model.

Stonewright does not promise that automation cannot fail. It adds concrete controls around supported changes: permissions, operating modes, confirmation tokens, pre-write snapshots, validation, typed readback, audit evidence, and restore paths. Use staging and normal infrastructure backups for production work.

How it works

Inspect → plan or dry-run → approve when required → back up → write → read back and verify → audit or restore.

Not every operation needs every gate. Stonewright selects the controls required by the typed ability, active mode, target surface, and risk. Custom code stops for human approval; supported Elementor and design writes take a snapshot before mutation; destructive production-safe operations require a scoped confirmation token.

Start in four steps

1. Download the current Plugin ZIP and install it in Plugins → Add New → Upload Plugin.
2. Open Stonewright → Setup, turn on AI abilities in the Settings view, then connect your client using the guided OAuth or Application Password flow. If the client still cannot connect, open Stonewright → Troubleshoot and run diagnostics (the page stays put and shows a loading state).
3. Fully restart the client and run the generated connection verification. A saved or parseable config is not runtime proof.
4. Confirm stonewright-task-start is visible and call it first with the real task. Use essential for normal work; bootstrap is startup diagnostics only.

The Setup screen provides client-specific commands and keeps credentials out of copied prompts. Installation covers the default path; advanced connection options cover Direct mode, local WP-CLI, remote HTTP, browser consent, profiles, and recovery.

Common workflows

• Repair an Elementor page: read the live control schema, plan one surgical batch, snapshot the document, write once, call stonewright-elementor-css-regenerate when generated CSS must be rebuilt, then run observation-only stonewright-elementor-post-write-verify and complete the browser recipe. Elementor closure contract
• Change custom code: discover the provider, dry-run the exact target, stop for human approval, apply the approved bytes, read back, and retain rollback evidence. Custom-code recovery contract
• Run repeatable local maintenance safely: save a parameterized WP-CLI recipe once, plan it, approve writes with a one-use hash, and get verified readback on every run. Command recipes
• Stop repeating a failure: classify the recurrence, surface a ranked incident action, verify the repair against correlated audit events, then promote one reusable lesson. Verified learning

Why Stonewright MCP compares this evidence chain with a generic WordPress API bridge without relying on raw tool counts.

Capabilities

Counts come from docs/ability-truth-matrix.md (plugin) and DIRECT_TOOL_NAMES (Direct). Do not hand-edit totals without regenerating the matrix.

Plugin mode — 397 abilities

Counts below are grouped by the includes/Abilities/ subdirectory each ability lives in, and sum to the total. Regenerate with composer docs:matrix.

Category	Count	Highlights
Elementor widgets (compat)	94	Generated per-widget builders
Elementor widget builder	4	Custom widget project helpers
Elementor V3	35	Structure edit, batch-mutate, CSS regenerate, observation-only post-write verification, performance audit, legacy-debt report, kit globals, build-from-spec, transactions
Elementor V4	14	Atomic nodes, variables, classes (experimental)
Design	33	DesignSpec validate/render, native plan, intent, versioned Design Directions, motion plans, manifests, comparison, guarded kit sync, rendered quality checks
Elementor native	2	Provider discovery and certified native execution inside the snapshot, lock, readback, and rollback closure; see Elementor MCP
Site	17	Snapshot, inventory, health, pulse, plugins, theme, shortcodes
Gutenberg	13	Parse, insert, update, batch-mutate, query-loop, render/apply
Finalizer abilities	6	Queue, runtime, pending, finalize, cancel, and finalizer URL for static/third-party blocks
FSE + patterns	17	theme.json, templates, navigation, pattern CRUD
Blocks library introspection	3	GenerateBlocks / Kadence / Spectra setup, list, and schema
Content + media	16	Pages/posts, bulk upsert, upload, stock
ACF + SEO	8	Field groups/values, multi-plugin SEO
Comments / users / widgets / settings / themes / theme builder / plugins / revisions	35	REST-parity admin ops (themes row excludes chrome)
Theme chrome	2	Blocksy / Kadence Theme / GeneratePress color, type, header, footer
WP-CLI	6	Status, discover, run, batch, jobs
Memory + skills + expertise + knowledge	20	Learning, memory generalization, skills, expertise packs
Section reuse	2	Find sections the site already has and extract one as a portable payload; the copy is an insert operation of the V3, V4 and block batch writers
Security + sandbox	18	Tokens, one-time links, incident repair receipts, rescue status and rollback, change history list, diff and rollback, sandbox lifecycle
Diagnostics	3	OAuth header, form delivery, and object capability diagnostics
System	11	Task start, native rules, tool profiles, ability list
System discover-execute	3	Compact catalog, bounded schema, gated execute without the full tool list
Menus, blueprints, brand kits, runtime, search, WooCommerce, content model, custom code	35	Native Woo catalog CRUD/audit and typed approval-gated code providers; see full matrix

Direct mode — 105 tools (pluginless)

The 105 are the Direct tools. A companion session also lists its own local tools (connection and diagnostics tools and the WP-CLI tools: 20 with the full profile), so tools/list shows 125 in Direct mode with full, and 37 with essential (22 Direct tools and 15 local tools).

Area	Tools (group)	Notes
Content & Gutenberg	list/get/create/update + compose + validate + blocks-batch-mutate	Block-level validation (balanced comments, JSON attributes, block names, custom code); path-based block edits with a content hash, a saved copy and a readback
Elementor (local WP-CLI)	status / data-get / data-update	File backup before every write, restorable with stonewright-direct-backup-restore; the document is read back after the write; refuses custom CSS and HTML widgets; preserves CSS metadata, runs no CSS flush, and requires Plugin-mode guarded CSS closure
Media, menus, taxonomy, templates, global styles	REST	Core endpoints; template, template-part and global-styles updates save a pre-image first; every typed write is read back
Backups	direct-backup-list / direct-backup-restore	List and restore the saved copies (hash-checked, needs a confirmation, undoable)
Comments, users, app passwords, widgets	REST	Write-gated
Plugins, themes, settings, health	REST	Destructive confirms
WooCommerce	products/orders/sales	Read-only; catalog writes require Plugin mode
ACF / SEO	fields get/update, seo-head	REST when plugins expose them
Self-improvement	skill-*, memory (scored, with memory-delete), learning-record, verified incident repair, task-start, agents-md-sync	Private per-site ~/.stonewright/ storage; a saved skill is a disabled candidate; a lesson that tells an agent to override the rules is kept as needs_review and never offered at task start
Native rules	rules-get	Same shipped registry as Plugin mode; cache by digest
WP-CLI	status/discover/run/batch/jobs	Tokenized execFile argv; batch-run is read-oriented only; a command that changes the site is a gated Direct write (task-start, confirmation, plugin guard, audit row)
Safety	write gating, confirmations bound to the call, plugin guard, custom-code screening, audit JSONL, pre-images and Elementor file backups	Task-start required before writes (default); no change sets or Plugin-mode confirmation tokens (saved copies are restorable, typed writes are read back, and a destructive call needs the confirmation_id a refused call returns, or confirm:true on a local site)

What you can do with Stonewright

• Inspect an existing WordPress site before changing it
• Create or update Gutenberg content and block-theme structures (Plugin mode; partial Direct mode for core posts/pages)
• Build and modify Elementor documents through validated DesignSpec workflows (Plugin mode)
• Close Elementor writes with post-scoped HTML-cache invalidation, then stonewright-elementor-css-regenerate for the resolved post or loop target (it also purges the cached page of that one post in the supported page-cache plugins once the stylesheet version moves), then observation-only stonewright-elementor-post-write-verify, then an explicit browser verification recipe
• Wire licensed Elementor Loop Grid/Carousel widgets transactionally from an existing loop-item template or a validated template spec (Plugin mode)
• Manage content, media, navigation, and selected site settings
• Manage WooCommerce products, variations, catalog terms, global attributes, and shipping classes through dry-run-first native abilities
• Create snapshots or revisions before supported mutations
• Validate DesignSpec payloads and read back important changes
• Restore supported changes when something goes wrong (Plugin mode audit/restore paths)
• Preserve project conventions and learned corrections (Plugin mode memory/skills)
• Perform guarded WP-CLI-assisted operations via the companion
• Use core REST workflows without installing the plugin through Direct mode

Why Stonewright

• Elementor widget and schema intelligence — live controls and typed writes (Plugin mode)
• Gutenberg, FSE, templates, patterns, and theme.json
• Persistent project memory and learned corrections (Plugin mode)
• Controlled schema learning — only verified repairs become active, scoped to matching Elementor runtimes
• Validation and readback on DesignSpec and major write paths
• Audit logging and change history (Plugin mode): the audit log records what agents did; the change history keeps the content before and after each change, shows it as a diff on Stonewright > Activity > Changes, and undoes or redoes a recorded change
• Backups and restore workflows for supported post mutations
• Tool-surface and token-budget management (profiles, priorities, client caps)
• Native WooCommerce catalog workflows with dry-run, permission, production confirmation, audit, and readback gates
• Plugin-less Direct mode for core REST and read-only WooCommerce
• Explicit operating modes (development, staging, production-safe) and confirmation tokens for destructive work

Choose your setup

Capabilities differ between modes. Prefer Plugin mode when you need Elementor, blueprints, memory, skills, audit, or full DesignSpec engines.

Plugin mode — recommended for full capabilities

Install the Stonewright plugin for advanced Elementor workflows, blueprints and brand kits, memory and skills, audit/restore, DesignSpec validation, php-execute, and the broader ability surface.

Direct mode — plugin-less core REST + local Elementor data

The companion authenticates with a WordPress Application Password and exposes 105 tools without installing Stonewright. Elementor documents can be edited without the Elementor editor via stonewright-elementor-data-get / data-update (local WP-CLI preferred; remote Direct falls back to core REST meta when _elementor_data is registered, with a file backup under ~/.stonewright/backups/ that stonewright-direct-backup-restore restores). This path has no Elementor schema validation and refuses custom CSS and HTML widgets — use Plugin mode elementor-v3-batch-mutate for production engines. What Direct mode protects, and what it does not do yet, is listed in docs/direct-mode-e2e.md. DesignSpec, php-execute, and site-hosted skills remain plugin-only; Direct keeps private local memory and user skills under ~/.stonewright/. See docs/direct-mode-e2e.md and docs/install-prompts.md.

Advanced connection options

The four-step Plugin path above is the default. The sections below are for local WP-CLI, explicit Application Password configuration, Direct mode, multiple sites, and clients that need manual profile control.

MCP surface modes (bootstrap / essential-static / essential / low-tools / full) control how many abilities appear to clients. Opt-in discover-execute is a companion profile for catalog + gated execute without the full tool list; auto routing never selects it. Opt-in inspect is a read-only profile of discovery, read, and verify tools with no php-execute and no write tool; auto routing never selects it either, and activating it never widens the saved surface. stonewright-php-execute is full-profile only, and the Full surface is chosen only by an administrator in wp-admin (Stonewright > Setup > Settings > MCP tool surface); stonewright-tool-profile and the settings route cannot switch an agent to it, and the abilities that run or write code are never added to another profile through extras. Known clients normally use the bounded working profile essential; essential-static is the safe fallback for an unknown client with stale tool-list behavior. Public ability and Direct-tool contracts live under docs/contracts/. Elementor multi-step edits use the transaction envelope. The durable audit, OAuth, write-receipt, and diagnostics contract is documented here. Client certification vs compatibility is defined in docs/releases/client-acceptance-template.md.

Use the versioned installer from the latest release. Because this flow starts from an installed plugin, choose plugin-only; it fails closed instead of silently falling back to Direct mode.

Codex CLI is the canonical local client and uses ~/.codex/config.toml. --client codex-cli, --client codex, and the compatibility alias --client chatgpt-desktop all resolve to that same Codex TOML adapter. See getting-started/codex.md.

npx -y --package https://github.com/cosmincraciun97/stonewright-wp-mcp/releases/download/vVERSION/stonewright-companion-VERSION.tgz stonewright connect add \
  --alias site-a --url https://site-a.example --username editor \
  --env production --mode plugin-only --client codex-cli \
  --plugin-enabled yes --wp-mode production-safe --wp-surface essential

The installer requests the Application Password through a hidden prompt, stores it in the OS credential store, and writes a collision-safe named client entry containing STONEWRIGHT_SITE_ALIAS, never the password. If the alias is already registered, reuse its saved credential and switch the existing entry:

npx -y --package https://github.com/cosmincraciun97/stonewright-wp-mcp/releases/download/vVERSION/stonewright-companion-VERSION.tgz stonewright connect repair site-a --client codex-cli --mode plugin-only

Restart the client and run stonewright connect verify site-a --client codex-cli. The receipt must report the requested alias, configured_mode=plugin-only, active_mode=plugin, the expected companion, and the successful ordered calls task-start → setup-profile → wordpress-mcp-status → client-surface-check. An empty refresh list is not success when the final surface check says a required client tool is not registered. OAuth remote HTTP is a separate connection to /wp-json/mcp/stonewright-oauth; do not combine both transports under one generic stonewright server name.

1. Create a WordPress Application Password for an admin user. On plain HTTP local sites, set WP_ENVIRONMENT_TYPE to local in wp-config.php if Application Passwords require it.

2. Register a named site and client from the latest release package. The hidden prompt keeps the Application Password out of argv and shell history:

   npx -y --package https://github.com/cosmincraciun97/stonewright-wp-mcp/releases/download/vVERSION/stonewright-companion-VERSION.tgz stonewright connect add \
     --alias site-a --url https://site-a.example --username admin \
     --mode direct-only --client cursor
   

3. Restart the client, then run stonewright connect verify site-a --client cursor. This spawns the saved server entry and requires task-start and status to complete; a config-file parse alone is not runtime proof.

4. First in-client call: stonewright-task-start. Use stonewright-site-discover for endpoint and capability details, and stonewright-setup-profile for setup diagnostics.

5. Read docs/direct-mode-e2e.md for the capability matrix and smoke script.

Example env for Direct mode:

{
  "mcpServers": {
    "stonewright": {
      "command": "npx",
      "args": [
        "-y",
        "--package",
        "https://github.com/cosmincraciun97/stonewright-wp-mcp/releases/download/vVERSION/stonewright-companion-VERSION.tgz",
        "stonewright-mcp"
      ],
      "env": {
        "STONEWRIGHT_MODE": "direct",
        "STONEWRIGHT_WP_URL": "http://your-local-site.local",
        "STONEWRIGHT_WP_USERNAME": "admin",
        "STONEWRIGHT_WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx",
        "STONEWRIGHT_MCP_TOOL_PROFILE": "essential"
      }
    }
  }
}

Replace VERSION with the latest release version (the companion is distributed through GitHub Releases, not the npm registry). Direct mode refuses custom PHP/CSS/JS/HTML in every write tool, before anything is sent (no authenticated wp-admin grant boundary), and refuses writes on a site where the Stonewright plugin is active.

Multiple sites and environments

Each (canonical URL, environment) is unique and each site has a stable alias. ~/.stonewright/sites.json contains metadata and credential references only; Application Passwords remain in Keychain, Windows protected storage, Linux Secret Service, or an explicit env:// reference. A client entry carries only STONEWRIGHT_SITE_ALIAS, so startup resolves exactly that site without loading unrelated credentials. The explicit alias is authoritative over inherited legacy STONEWRIGHT_WP_* values. Secure v1 migration collapses duplicate aliases for the same canonical site/environment to one stable record. The registry also retains Direct/Plugin policy, WordPress mode and tool surface, Elementor V4 selection, plus the browser choice and its separate scan/install consent for each client. See Installation.

Fresh installs start with no user memory, user-created skills, or audit events. Generic built-in skills and native rules are product assets. Updates preserve existing plugin and Direct state. See Updating Stonewright for the plugin/companion matrix and exact steps.

How Stonewright makes agent changes safer

Stonewright is designed to make agent-driven WordPress changes safer and more recoverable, not to provide a perfect security sandbox. Most typed mutation workflows pass through combinations of permission checks, operating modes, confirmations, backups, validation, readback, and audit logging.

stonewright/php-execute is an advanced full WordPress-runtime capability. It is on the full profile only, which an administrator chooses in wp-admin and an agent cannot switch to; it needs an administrator who can edit plugins (edit_plugins and manage_options, a super admin on multisite), and where DISALLOW_FILE_MODS is set it refuses code that calls file-modification APIs. It is permission- and mode-gated, audited, and subject to targeted restrictions, but it is not a strict sandbox and does not receive the same structural guarantees as typed DesignSpec or validated mutation workflows. The other abilities that run or write code (sandbox writers, WP-CLI runners, the custom-code provider, custom widget definers) are never added to a surface by name; only the full profile or the profile built for them (wp-cli, content-model) lists them.

Typed mutation paths may use combinations of:

• Stonewright operating modes (development, staging, production-safe)
• WordPress permissions and capability checks, made against the object a call touches (the post, user, comment, template or option) and not only the role
• Human approval for what an agent must not decide alone: custom code and snippet rollback (a one-time grant on Stonewright > Custom code > Approvals), promotion of skills and expertise (Stonewright > Knowledge > Skills), memory flagged needs_review (Stonewright > Knowledge > Memory), and undo of code from the Changes page. An approval link comes back in the MCP error, and the agent stops
• Confirmation tokens for destructive operations in production-safe mode
• Backups or revisions before supported Elementor/theme/content mutations
• Schema and DesignSpec validation before render
• Readback verification on selected write paths
• Audit logging
• Rollback or restore workflows where supported
• Change sets: one change_set shape for what a write planned, applied, and missed, with before and after hashes and a rollback reference (Change set)
• Rescue: a change journal, a health probe after risky writes, and an automatic rollback when the site stops loading
• Change history: the content before and after each change, kept for 90 days, 500 changes and 100 MB by default, with a diff view and undo or redo of any restorable change (Rescue)

Not every surface uses every gate. Prefer typed abilities over unrestricted PHP when a typed path exists. Read SECURITY.md and docs/security.md.

Rescue

Before a risky change, Stonewright records how to undo it. Afterwards it asks the site whether it still loads, rolls the change back when it does not, and tells the agent what happened. A change it cannot undo stays open as an incident that an administrator or an agent can finish from Stonewright > Activity > Rescue, stonewright-rescue-rollback, or wp stonewright rescue.

Rescue covers post, option, theme-file, plugin, sandbox, and custom-code writes made through Stonewright abilities. A health probe that cannot reach the site reports it as unavailable and never as healthy. Rescue cannot fix a fatal in WordPress core or wp-config.php, or a database that is down. See Rescue.

Change history

Stonewright records each change it makes to posts, Elementor documents, options, menus, widgets, theme and custom code, users, comments, media, WooCommerce items, skills, design directions and memory, with the content before and after it. Secrets are never stored and other credentials are masked. Stonewright > Activity > Changes lists the history with filters, shows one change as a diff, and undoes it or redoes an undo; the undo writes the content back through the path the original write used and probes the site afterwards, and puts the earlier state back if the site stops loading. An administrator at the page approves the undo of code; an agent or WP-CLI call gets an approval-required answer. stonewright-change-history-list, stonewright-change-diff-get, stonewright-change-rollback and wp stonewright changes do the same for agents and operators. History is kept for 90 days, 500 changes and 100 MB by default. See Rescue and Changes.

Elementor MCP

Elementor 4.3 has an MCP module of its own that registers elementor/* abilities. Turn it on in wp-admin (Elementor > Elementor MCP) and Stonewright discovers them, certifies each one against a contract, and runs the certified ones through stonewright-elementor-native-execute inside its snapshot, lock, readback, rollback and audit closure. Connect only Stonewright to your AI client: a call on Elementor's own MCP server skips that closure. Elementor has announced V3 support; V3 documents stay on the Stonewright V3 writers until their abilities are verified. See Elementor MCP with Stonewright.

Section reuse

When you ask an agent to build a page, it can offer to copy a section that already exists on another page of the site, then adapt it to your instructions and the active Design Direction. It works inside one builder family (Gutenberg, Elementor V3, or Elementor V4) and never converts between them. Candidates come only from pages, posts, Elementor saved templates, and Gutenberg patterns that you can read and edit, whether they are published, draft, pending, scheduled or private; an Elementor container nested inside a section can be copied on its own; the page the section is copied from is never changed, and its status is never changed to copy from it. A copy is written in the same dry run and apply as the text and image changes, with the same snapshot, readback, CSS handling, change set, and audit as any other write. Stonewright > Setup > Settings > Reuse saved sections turns it off; agents learn the value on their next call. See Section reuse.

Native rules

Stonewright ships a registry of operating rules that apply to every site rather than to one project's memory. Each record states the rule, why it exists, its severity, its scope, and how it is enforced:

Severity	Meaning
hard	A runtime guard makes the violation fail. enforcement.guard names that guard.
strong	Surfaced in every task payload. Deviation must be justified. Not mechanically checkable, so these never claim a runtime guard.
advisory	Surfaced on matching tasks only.

The distinction is deliberate: advertising enforcement that does not exist is worse than advertising none. Rules that PHP cannot mechanically verify say so.

stonewright-task-start returns only the registry digest and the name of the tool that resolves it, because rule bodies would consume most of a compact task payload. Fetch the bodies once with stonewright-rules-get, cache them by digest, and refetch only when task start reports a different digest. Filter by severity or scope; a scoped request still includes the globally scoped rules, since those apply everywhere. Pass knownDigest to get unchanged: true with the bodies omitted.

Both modes serve the same registry: Plugin mode from plugin/data/global-rules.json, Direct mode from the copy shipped with the companion. stonewright-rules-get exists in both, and in Direct mode it is on the bootstrap surface so a cold client can resolve the digest task start just handed it.

Cheaper reads

Two optional inputs cut payload without losing precision:

• stonewright_fields — available on every ability. Give it dot-separated response paths, as a list or a comma-separated string ("meta.title, outline.id"), and the response carries only those branches. Unknown paths are ignored rather than raising an error, top-level fields required by the ability output schema remain present, and errors come back unprojected so you can still see why a call failed.
• knownHash on stonewright-elementor-v3-get-page-structure — pass the hash a previous read returned. If the document has not moved, the answer is { post_id, active, hash, unchanged: true } and no outline or tree is built. The hash is taken from the decoded tree, so a re-save that only reorders JSON keys does not read as a change, and both response modes report the same value.

Architecture

flowchart TD
  Client["AI / MCP client"]
  Browser["Optional user-approved browser provider"]

  subgraph Local["Local stdio and client configuration"]
    Adapters["Transactional per-client adapters"]
    Registry["Multi-site registry: alias, environment, mode, Step 1 expectations"]
    Credentials["OS credential store or explicit env reference"]
    Companion["Stonewright Companion"]
    CompFilter["Companion profile: bootstrap, essential-static, essential, low-tools, full"]
    Direct["Pluginless Direct adapters"]
    DirectState["Private Direct skills, memory, and redacted audit"]
    DirectGuards["Direct guards: session site, plugin guard, custom-code screen, bound confirmation_id, saved copies and restore, readback, WP-CLI gate"]
  end

  subgraph PluginMode["Plugin mode"]
    Auth["OAuth grant or Application Password boundary"]
    Step1["Step 1: enabled, mode, surface, Elementor V4"]
    Surface["Plugin surface gate: bootstrap, essential, full"]
    Session["Per-session task profile"]
    Revision["surface_revision and tools/list_changed"]
    Plugin["Stonewright plugin ability kernel"]
    Code["Typed custom-code providers"]
    Approval["Dry run, human grant, confirmation, snapshot, readback"]
    Elementor["Elementor V3 / V4 / kit schema routing"]
    Native["Native Elementor MCP: certified elementor/* abilities run by native-execute"]
    Observer["Observer: records Elementor ability calls made outside native-execute"]
    Closure["Lease, snapshot, validate, write, readback, rollback, visual QA"]
    Audit["Coalesced audit with actor attribution"]
    Incidents["Incident lifecycle"]
    Memory["Verified repair promotion to memory"]
    Sets["Change set: planned, applied, missing, hashes, rollback recipe"]
    Sections["Section reuse: find, extract, insert_section copy"]
    Journal["Rescue journal armed before a risky write"]
    Probe["Health probe after the write, one retry on a silent leg"]
    Rollback["Automatic rollback from the recorded recipe"]
    RescueIncident["Rescue incident: rollback failed or PHP fatal recorded"]
    Helper["Must-use rescue helper: fatal capture and safe mode"]
    Undo["Undo of the last 50 verified changes, code only by an administrator in wp-admin"]
    Ledger["Change history: content before and after each change, 90 days, 500 changes, 100 MB"]
    ChangesPage["Changes page: filters, diff, Undo and Redo"]
    ChangeUndo["Undo or redo of any recorded change, code only by an administrator in wp-admin"]
    ChangeTools["Change abilities and WP-CLI: list, diff, rollback"]
  end

  WordPress["WordPress core, REST, Gutenberg/FSE, content, WooCommerce"]

  Client -->|"local stdio"| Companion
  Client -->|"remote Streamable HTTP"| Auth
  Client --> Adapters
  Adapters --> Registry
  Registry --> Credentials
  Registry --> Companion
  Companion --> CompFilter
  CompFilter -->|"Plugin mode"| Auth
  CompFilter -->|"Direct mode"| Direct
  Direct --> DirectGuards -->|"REST, local WP-CLI"| WordPress
  Direct --> DirectState
  Auth --> Plugin
  Step1 --> Surface --> Session --> Plugin
  Step1 --> Revision -. "re-list / restart contract" .-> Client
  Plugin --> WordPress
  Plugin --> Code --> Approval --> Journal
  Plugin --> Elementor --> Closure --> Journal
  Elementor -->|"certified ability"| Native -->|"inside the same closure"| Closure
  Observer -. "snapshot, change row, audit row" .-> Ledger
  Observer -. "audit row" .-> Audit
  Plugin --> Audit --> Incidents --> Memory
  Plugin -->|"write receipt"| Sets
  Sets -->|"change_set_id, repair_of"| Audit
  Plugin --> Sections
  Sections -->|"insert_section, V3 and V4"| Elementor
  Sections -->|"insert_section, blocks"| Journal
  Journal -->|"write runs"| WordPress
  Journal --> Probe
  Probe -. "loopback requests" .-> WordPress
  Probe -->|"site fails"| Rollback
  Rollback -->|"restore"| WordPress
  Rollback -->|"error result"| Audit
  Rollback -->|"rollback failed"| RescueIncident
  Helper -->|"fatal after a change"| RescueIncident
  RescueIncident -->|"audit row"| Audit
  Journal -. "last 50 changes" .-> Undo
  Undo -->|"same recipe"| Rollback
  Plugin -->|"records before and after"| Ledger
  Journal -. "state of each change" .-> Ledger
  Ledger --> ChangesPage --> ChangeUndo
  Plugin --> ChangeTools
  ChangeTools -->|"history, diff"| Ledger
  ChangeTools -->|"rollback, code is refused"| ChangeUndo
  ChangeUndo -->|"original write path, then probe"| WordPress
  ChangeUndo -->|"rollback or redo row"| Ledger
  ChangeUndo -->|"one audit row per call"| Audit
  ChangeUndo -. "open Rescue entry: Rescue rollback" .-> Rollback
  Client -. "provider choice plus scan/install consent" .-> Browser
  Browser -. "rendered verification or approved dashboard action" .-> WordPress

Tool visibility is filtered twice before a client sees it: the plugin’s surface gate (bootstrap, essential, or full) and optional per-session task profile decide which abilities the MCP endpoint exposes, then the companion profile filter (bootstrap, essential-static, essential, low-tools, or full) may narrow that set for the client. A monotonic surface_revision on every gateway response drives tools/list_changed; clients that cannot process it use the documented re-list/restart path. bootstrap is diagnostic, while essential is the normal bounded working profile for known clients.

OAuth credentials remain inside the plugin grant/token boundary. Application Passwords stay in private client configuration or the OS-backed site registry; paste-to-agent prompts contain placeholders. Direct mode has no plugin approval boundary and no tool for WPCode, Code Snippets, or theme files, and its content, template, blueprint, widget, global-styles, Elementor data, ACF, media, menu, comment, taxonomy-term, settings, and user writes refuse custom CSS, script, and HTML-type markup. Plugin-mode custom-code providers always stop after a typed dry run until the user issues the exact one-time grant. Generic create/update/duplicate/bulk writers reject executable-code post types and route them to the approval-gated provider pipeline.

Audit success does not erase unrelated failures. Events coalesce noisy OAuth terminals, preserve the best available actor attribution, and feed an explicit incident lifecycle. Only a correlated verified repair or user correction may promote durable guidance into memory.

Browser automation is external and consent-bound. The agent asks once per site/client whether to use Playwright (recommended), another connected browser, or none; scanning and installation require separate permission. A browser may verify output or perform an explicitly approved dashboard interaction, but it never bypasses custom-code dry-run/approval, backup, permission, or confirmation gates.

Direct mode has a smaller capability surface: core REST, read-only WooCommerce, local Elementor data, and skills/memory across 105 tools. Plugin mode exposes 397 abilities. Direct mode skips the plugin’s typed schema validator, change sets, confirmation tokens, and Rescue; it saves a copy before whole-document writes and restores it on request (stonewright-direct-backup-list / -restore), reads every typed write back and compares it, can check the public page after a page, post or template write, binds each destructive confirmation to the exact call (confirmation_id), acts on the session's site (STONEWRIGHT_SITE_ALIAS), and refuses writes on a site where the plugin is active; Elementor writes in both modes pass an integrity gate that blocks double-encoding, mass size-collapse, and widgetType remaps. Local Direct Elementor writes invalidate post HTML cache without deleting CSS metadata and report browser verification as still required; remote Direct writes cannot claim server-side Elementor cache closure. WooCommerce catalog writes require Plugin mode; see WooCommerce support.

See docs/install-prompts.md for copy-paste AI client setup (plugin and Direct).

Connection methods, in plain language

• Local stdio: Codex, Claude Code, Grok Build / CLI, or another AI client starts the Stonewright companion on your computer and exchanges MCP messages with that local process through standard input/output. The companion is required for local stdio, pluginless Direct mode, and local WP-CLI.
• Remote Streamable HTTP: the AI client connects straight to the Stonewright WordPress plugin over HTTPS. No companion process runs on the user's computer.

Companion status, doctor, and task-start reports use schema version 3. stonewright-task-start is the first call; on a degraded session it reconnects once and either continues or returns a truthful local result. Terminal OAuth failures set reauthentication_required with a model-visible user_action. In Plugin mode the companion sends each WordPress MCP request once and does not repeat it after a timeout or network error. (Direct mode's REST client retries a request once after some network errors.) On OAuth connections an HTTP 401 refreshes the access token and the request is sent once more, a tool call included.

Direct mode is a capability mode inside the companion, not a third transport. If the plugin is absent and you use Direct mode, you are using local stdio and therefore need the companion.

Supported workflows and clients

Stonewright speaks standard MCP (local stdio via the companion, and remote HTTP MCP when the WordPress MCP adapter is active). Configuration samples in this repository follow the common MCP server JSON shape used by several clients.

Area	Status	Notes
Companion stdio MCP	Documented	Primary install path in docs
WordPress MCP endpoint /wp-json/mcp/stonewright	Documented	Plugin + MCP adapter
Direct mode core REST	Documented + smoke script	docs/direct-mode-e2e.md
Specific desktop/CLI AI clients	Catalog + smoke template	Setup shares one client tablist for OAuth and Application Password. Grok Build / CLI stays compatible until a dated runtime smoke report exists.

Admin interface

Plugin mode admin pages are grouped into six hubs under Stonewright: Overview, Setup (Setup and Troubleshoot), AI Abilities, Knowledge (Skills, Memory, Context, Design and Prompt library), Custom code (Drafts, Library, Active, Crash recovery and Approvals) and Activity (Audit log, Block queue, Rescue and Changes); see docs/admin/navigation.md. The Audit log is the single responsive incident view; Custom code does not duplicate it. The admin ships one supported light theme; there is no theme toggle. Its maintained tokens, component contracts, responsive rules, and page-by-page release checklist live in DESIGN.md.

The Design Library admin group—Blueprints, Design Studio, and Visual Workspace—is disabled. Its routes and prompt starters are not registered. Persistent user data and the typed MCP design/blueprint engines remain intact; figma-to-native-pixel remains the supported evidence-led design workflow.

Requirements

• WordPress 6.7+ (plugin mode uses wordpress/mcp-adapter ^0.6.1)
• PHP 8.1+
• Node.js 20+ for the companion
• Elementor 3.21+ only when using Elementor abilities
• WP-CLI optional for tokenized companion CLI workflows

Current project status and limitations

Stonewright ships a public beta. APIs, tools, configuration, and behavior may still change before 1.0 stable. Test on staging or local environments first. Keep site backups independent of Stonewright. Report security issues privately per SECURITY.md.

This project is not marketed as production-ready in the sense of a frozen stable API. Use production-safe mode and review when operating on live sites.

Documentation

• Installation
• Updating Stonewright
• Direct mode capability matrix
• WooCommerce support and safety
• Companion
• Security · SECURITY.md
• Rescue
• Elementor MCP with Stonewright
• Ability truth matrix
• Beta.13 runtime evidence template
• Motion and UI excellence
• Licensing
• Release notes

Development and testing

cd plugin
composer install
composer test
composer phpstan
composer phpcs

cd ../companion
npm install
npm run typecheck
npm test
npm run build

Components and licenses

Component	Path	License
Plugin	plugin/	GPL-2.0-or-later
Visual workspace	visual/	GPL-2.0-or-later
Companion	companion/	MIT
Skill packs (shipped inside the plugin)	skills/	GPL-2.0-or-later
Documentation	docs/	GPL-2.0-or-later

See component licensing for scope and third-party terms.

Support, security, and contributing

• Bugs and features: GitHub Issues using the templates
• Security: SECURITY.md (private disclosure)
• Support guide: SUPPORT.md
• Contributing: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md