Stonewright Wp MCP

Stonewright MCP presents a compact, task-aware surface backed by 361 Plugin abilities and 101 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, enable the site, then connect your client using the guided OAuth or Application Password flow.
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, run post-write verification, then 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
• 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 are derived from docs/ability-truth-matrix.md (plugin) and DIRECT_TOOL_NAMES (Direct). Do not hand-edit totals without regenerating the matrix.

Plugin mode — 361 abilities

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

Direct mode — 101 tools (pluginless)

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 cache invalidation, CSS regeneration, bounded frontend assertions, and an explicit browser verification recipe
• Wire native Elementor Pro 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)
• 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 101 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/). This path has no Elementor schema validation — use Plugin mode elementor-v3-batch-mutate for production engines. 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 / full) control how many abilities appear to clients. 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.

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 \
  --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 --mode plugin-only

Restart the client and run stonewright connect verify site-a --client codex. The receipt must report the requested alias, configured_mode=plugin-only, active_mode=plugin, task-start/status availability, the expected companion, and no required tool refresh. 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 does not write custom PHP/CSS/JS/HTML (no authenticated wp-admin grant boundary).

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 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.

Typed mutation paths may use combinations of:

• Stonewright operating modes (development, staging, production-safe)
• WordPress permissions and capability checks
• 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

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

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:

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"]
  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"]
    Closure["Lease, snapshot, validate, write, readback, rollback, visual QA"]
    Audit["Coalesced audit with actor attribution"]
    Incidents["Incident lifecycle"]
    Memory["Verified repair promotion to memory"]
  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 --> WordPress
  Direct --> DirectState
  Auth --> Plugin
  Step1 --> Surface --> Session --> Plugin
  Step1 --> Revision -. "re-list / restart contract" .-> Client
  Plugin --> WordPress
  Plugin --> Code --> Approval --> WordPress
  Plugin --> Elementor --> Closure --> WordPress
  Plugin --> Audit --> Incidents --> Memory
  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, so it cannot write arbitrary PHP, CSS, JavaScript, HTML, WPCode, Code Snippets, or theme files. Plugin-mode custom-code providers always stop after a typed dry run until the user issues the exact one-time grant.

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 101 tools. Plugin mode exposes 361 abilities. Direct mode skips the plugin’s typed schema validator; 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 element/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, 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.

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.

Admin interface

Plugin mode admin pages include Setup, Dashboard (Site Pulse), Abilities, Prompts, Skills, Memory, Sandbox, and Audit Log. The Audit Log is the single responsive incident view; Sandbox 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 where applicable)
• 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
• Ability truth matrix
• Licensing
• Upstream code reuse ledger
• 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

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