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, including local Elementor meta edits via WP-CLI and companion-local skills/memory.

“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 — 312 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)
• 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)
• 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. Local sites with WP-CLI can edit _elementor_data via stonewright-elementor-data-* (with file backup). Full Elementor 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 create an Application Password.
4. Configure your MCP client to run the companion (see below).
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]
  Plugin[Stonewright plugin]
  REST[WordPress REST API]
  WP[WordPress core]
  Guten[Gutenberg / FSE]
  Elem[Elementor]
  Content[Content / media / menus]
  Mem[Memory / skills]
  Users[Users / comments / widgets]
  WC[WooCommerce read]
  Gates[Backup / validation / readback / audit]

  Client --> Companion
  Companion -->|Plugin mode| Plugin
  Companion -->|Direct mode| REST
  Companion --> Skills[Local skills / memory]
  Plugin --> Gates
  Plugin --> Guten
  Plugin --> Elem
  Plugin --> Content
  Plugin --> Mem
  Plugin --> Users
  Plugin --> WC
  REST --> Users
  REST --> WP
  WP --> Content
  Plugin --> WP

Direct mode has a smaller capability surface (core REST + local Elementor data + skills/memory; 99 tools). Plugin mode exposes 312 abilities. Not every request passes through every component.

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, Skills, Memory, Sandbox, and Audit Log. Theme toggle lives in the admin shell header.

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