sproutos

<p align="center"> <img src="sprout-ui/logo-white.svg" alt="SproutOS" width="200"> </p> <h1 align="center">SproutOS Developer Edition</h1> <p align="center"> <strong>WordPress AI Control API + native MCP server for Claude, Cursor and AI agents, with an administrator-only PHP execution tool.</strong> </p> <p align="center"> <em>The AI Operating System for Modern WordPress Agencies, from the team behind plugins running on 500,000+ WordPress sites.</em> </p> <p align="center"> <a href="#what-is-this">What Is It</a> &bull; <a href="#two-editions-which-one-do-i-install">Two Editions</a> &bull; <a href="#installation">Installation</a> &bull; <a href="#authentication">Auth</a> &bull; <a href="#mcp-tool-server">MCP Tools</a> &bull; <a href="#rest-api">REST API</a> &bull; <a href="#safety-and-controls">Safety</a> </p> <p align="center"> <img src="https://img.shields.io/badge/WordPress-6.9%2B-blue?logo=wordpress" alt="WordPress 6.9+"> <img src="https://img.shields.io/badge/PHP-8.0%2B-777BB4?logo=php" alt="PHP 8.0+"> <img src="https://img.shields.io/badge/MCP-2025--06--18-green" alt="MCP Spec"> <img src="https://img.shields.io/badge/License-GPLv2-orange" alt="License GPLv2"> </p> --- ## What Is This? **SproutOS Developer Edition** is the full, unrestricted build. It contains everything the WordPress.org SproutOS plugin has, the entire `/wp-json/sprout-os/v1/` REST control API and the complete safety layer, and adds one developer-only capability: 1. A **native MCP tool server** at `/wp-json/mcp/sproutos` (JSON-RPC over Streamable HTTP, MCP spec `2025-06-18`), so AI clients such as **Claude**, **Claude Code** and **Cursor** connect directly and see the tools with no cloud proxy. Like the WordPress.org build, it is fully self-contained: no MCP Adapter, no WordPress Abilities API, no bundled third-party libraries. Every endpoint is written from scratch, administrator-gated, and covered by the safety layer. > ⚠️ Because it ships the developer tools folder and full file access, this Developer Edition is **not** on the WordPress.org directory. It is distributed here, on GitHub, as the self-hosted developer build. --- ## Two Editions: Which One Do I Install? SproutOS ships in two editions built from **one identical codebase**. The only difference is a single folder, the developer tools folder, so everything else behaves the same in both. | | **SproutOS** | **SproutOS Developer Edition** | |---|---|---| | Where | [WordPress.org](https://wordpress.org/plugins/sproutos/) | [GitHub](https://github.com/posimyth/sproutos) (this repo) | | Best for | **Live and client sites** | **Local, staging and developer environments** | | REST control API (`/wp-json/sprout-os/v1`) | ✅ | ✅ | | Full safety layer (domain lock, rate limit, protected posts, audit log) | ✅ | ✅ | | Elementor read / write / granular element ops | ✅ | ✅ | | Native MCP server (direct Claude / Cursor connection) | – | ✅ | | File access | Limited and secure | **Full read / write / delete** | **The one difference, in plain terms:** the developer tools folder. In the WordPress.org edition it is left out entirely, so file access stays limited and secure, the right choice for production. In this Developer Edition it adds the direct MCP tool server and **full read / write / delete access to your WordPress files and folders.** That is complete freedom, and complete responsibility for your entire WordPress setup. This is the most powerful build, and it is **recommended that you keep backups and use a staging workflow.** Choose wisely. > 👉 Running production or client sites? Install the safe edition from **[WordPress.org](https://wordpress.org/plugins/sproutos/)** instead. --- ## Relationship To The WordPress.org Build This is a **drop-in** replacement for the WordPress.org `sproutos` plugin: - When `sproutos-dev` is active, the `sproutos` plugin **stands down automatically** (it defines and boots nothing), so there is never a duplicate registration. - It keeps the **same** endpoints (`/wp-json/mcp/sproutos`, `/wp-json/sprout-os/v1`), admin menu and option keys, so moving between the two editions is smooth: same URLs, same settings. Run **one** of the two at a time. Both share the same class and function names; coexistence works only because the WordPress.org build stands down for this one. --- ## Installation 1. Upload to `wp-content/plugins/sproutos-dev/`. 2. Activate **SproutOS Dev** from the Plugins screen. (If the WordPress.org SproutOS is also active, it steps aside automatically.) 3. Open **SproutOS** in the admin menu to create an Application Password. Requires WordPress 6.9+ and PHP 8.0+. --- ## Authentication Every surface is **administrator-only** (`manage_options`). AI clients and REST callers authenticate with a WordPress **Application Password**: ``` Authorization: Basic base64( "username:application-password" ) ``` Create one under **Users → Profile → Application Passwords**, or from the SproutOS admin page. --- ## MCP Tool Server Endpoint: `/wp-json/mcp/sproutos`. Add it as a custom MCP server in your client. **Claude Code:** ```bash claude mcp add --transport http sproutos \ https://your-site.com/wp-json/mcp/sproutos \ --header "Authorization: Basic <base64>" ``` Tools exposed to the client: | Tool | Purpose | |---|---| | `sprout/read` `write` `edit` | Read / create / surgically edit files in the SproutOS workspace | | `sprout/list` `search` | Browse and grep the workspace | | `sprout/delete` `move` | Remove / rename files | Every tool call is administrator-gated and written to the audit log. --- ## REST API The full `/wp-json/sprout-os/v1` surface from the WordPress.org build is included: site, content, post-meta, media, options, plugins (list/toggle/upgrade/install), themes (files/install/upgrade), inspection (users/database/settings/updates/snapshot/server-readiness/theme-docs/builder-probe), Elementor (read/write plus granular get/edit/clone/move/delete/insert). Call `GET /manifest` for the live list. --- ## Safety And Controls Same layer as the WordPress.org build (domain lock, rate limiter, protected-post guard, audit log, secret redaction, executable-upload block), extended to the MCP surface. > ⚠️ The Developer Edition still gives an authenticated administrator full read / write / delete access to your WordPress files and folders. Use it only where you have backups and, ideally, a staging site. --- ## Changelog (1.2.0) - **New:** API-based MCP architecture (replaces the previous abilities-based engine). - **Removed:** PHP execution tool (`sprout/eval`) and its REST twin `POST /sprout-os/v1/eval`. - **Removed:** Memory functionality. - **Removed:** Sandbox environment. - **Removed:** Integrations for Elementor, Bricks, ACF, Pods, Divi, Breakdance, Beaver Builder, Oxygen, ASE, and other page-builder features. - **Improvement:** Simplified and cleaned up the core architecture. See [`CHANGELOG.md`](CHANGELOG.md) for the full history. --- <p align="center"> <strong>Live or client sites? Get the safe edition on <a href="https://wordpress.org/plugins/sproutos/">WordPress.org →</a></strong><br> <a href="https://sproutos.ai">sproutos.ai</a> </p>