Stonewright Wp MCP

Stonewright is a WordPress MCP stack for AI coding agents. Elementor is a first-class surface in Plugin mode (typed engines, DesignSpec, kit globals). Direct mode works against core REST with an Application Password without installing the plugin: companion-local skills/memory, and Elementor document edits without opening the editor via WP-CLI (local) or REST meta when registered (remote). Full batch-mutate engines remain plugin-only.

“Safe” here is a design goal: operating modes, permissions, confirmations, backups, validation, readback, and audit logging make agent-driven changes more recoverable. It is not an absolute security guarantee. Use staging, review changes, and keep normal WordPress backups.

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 — 329 abilities

Direct mode — 99 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)
• 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
• 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)
• Plugin-less Direct mode for core REST
• 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 99 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. See docs/direct-mode-e2e.md and docs/install-prompts.md.

Quick Start

Plugin mode (about five steps):

1. Download the latest stonewright-*.zip from GitHub Releases (includes prereleases).
2. In WordPress: Plugins → Add New → Upload Plugin → activate Stonewright.
3. Open Stonewright → Setup, enable abilities, and choose OAuth (recommended) or create an Application Password.
4. Follow the client-specific OAuth instructions shown in Setup. Use the companion configuration below only for Application Password or local WP-CLI workflows.
5. In Setup, run Verify connection (live MCP loopback). Optionally run npx @stonewright/companion doctor from a shell.
6. Call stonewright-task-start (or stonewright-context-bootstrap as a compatibility path) before WordPress work.

MCP surface modes (bootstrap / essential / full) control how many plugin abilities appear to clients. Public ability and Direct-tool contracts live under docs/contracts/. Elementor multi-step edits use the transaction envelope.

Use the latest release companion package URL from Releases (do not hardcode a stale alpha):

{
  "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_WP_URL": "https://your-site.example.com",
        "STONEWRIGHT_WP_USERNAME": "admin",
        "STONEWRIGHT_WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx",
        "STONEWRIGHT_MCP_TOOL_PROFILE": "essential"
      }
    }
  }
}

Replace VERSION with the exact release version without the leading v, as shown on the GitHub Releases page. Site MCP endpoint when using the WordPress MCP adapter directly:

https://your-site.example.com/wp-json/mcp/stonewright

HTTP local sites are supported; Setup treats plain HTTP as informational, not a hard failure.

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. Run the companion init command from the latest release package (or configure env vars) and paste the MCP JSON into your client:

   npx -y --package https://github.com/cosmincraciun97/stonewright-wp-mcp/releases/download/vVERSION/stonewright-companion-VERSION.tgz stonewright-companion init
   

3. First calls: stonewright-site-discover, stonewright-setup-profile.

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

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.

Architecture

flowchart LR
  Client[AI / MCP client]
  Companion[Stonewright Companion]
  CompFilter[Companion profile filter]
  Plugin[Stonewright plugin]
  Surface[Surface gate: bootstrap / essential / full]
  Session[Per-session tool profile]
  Rev[surface_revision -> tools/list_changed]
  REST[WordPress REST API]
  WP[WordPress core]
  Guten[Gutenberg / FSE]
  Elem[Elementor]
  Integrity[Elementor integrity gate: double-encode / size-collapse / widgetType-remap / delta-scoped validate]
  Content[Content / media / menus]
  Mem[Memory / skills]
  Users[Users / comments / widgets]
  WC[WooCommerce read]
  Gates[Backup / validation / readback / audit]

  Client --> Companion
  Companion --> CompFilter
  CompFilter -->|Plugin mode| Plugin
  CompFilter -->|Direct mode| REST
  Companion --> Skills[Local skills / memory]
  Plugin --> Surface
  Surface --> Session
  Session --> Rev
  Rev -. re-list .-> Client
  Plugin --> Gates
  Plugin --> Guten
  Plugin --> Elem
  Elem --> Integrity
  Plugin --> Content
  Plugin --> Mem
  Plugin --> Users
  Plugin --> WC
  REST --> Users
  REST --> WP
  WP --> Content
  Plugin --> WP

Tool visibility is filtered twice before a client sees it: the plugin’s surface gate (bootstrap / essential / full) and optional per-session tool profile decide which abilities the MCP endpoint exposes, then the companion profile filter narrows that set again for the client. A monotonic surface_revision on every gateway response drives tools/list_changed so clients re-list when the surface changes.

Direct mode has a smaller capability surface: core REST, local Elementor data, and skills/memory across 99 tools. Plugin mode exposes 329 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.

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

Supported workflows and clients

Stonewright speaks standard MCP (stdio via the companion, and 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, Blueprints, Design Studio, Visual Workspace, Skills, Memory, Sandbox, and Audit Log. Theme toggle lives in the admin shell header.

Design Studio holds design directions: the validated design intent a site works to, versioned, with provenance and revisions. Visual Workspace opens a post in the browser workspace, resolves the live editor adapter, and walks read → preview → confirm → apply → verify with the active direction on screen. Neither page certifies that a page looks right; a change applied without evidence behind it is reported as unverified rather than as a success. See docs/visual.md.

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 alpha prereleases. APIs, tools, configuration, and behavior may still change. 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
• Direct mode capability matrix
• Companion
• Security · SECURITY.md
• Ability truth matrix
• Licensing
• Upstream code reuse ledger
• Release notes (five-release retention)

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

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