=== WEBO MCP ===
Contributors: phuongwebo
Author URI: https://webomcp.com
Tags: mcp, model context protocol, ai agent, json-rpc, automation
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 3.0.22
License: GPL v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

WordPress MCP server for AI agents and automation, with JSON-RPC tools over REST for Claude, Cursor, n8n, and MCP clients.

== Description ==
WEBO MCP securely connects authenticated AI agents and MCP-compatible clients to WordPress through JSON-RPC tools over REST. It provides bounded access to content, media, users, settings, site health, and extensible WordPress abilities while preserving native capability checks.

Use Application Passwords or an authenticated WordPress session, discover tools with `tools/list`, and invoke exact tools through `tools/call`. Optional API-key, HMAC, scoped connector-token, allowlist, and audit controls are available for administrators. Documentation and ecosystem details: https://webomcp.com

== Installation ==

**WEBO MCP** is a WordPress MCP server — a complete **Model Context Protocol** gateway for WordPress. It lets AI agents and MCP-compatible clients (Claude Desktop, Cursor, Windsurf, n8n, and more) call well-defined tools over REST using JSON-RPC, instead of scraping the admin or sharing broad credentials.

Official WEBO MCP website, documentation, and ecosystem hub: https://webomcp.com

**Why use WEBO MCP as your WordPress MCP server?**

- **Token-optimized unified tools:** every domain exposes two abilities — `*-query` (all reads) and `*-mutate` (all writes) — with a single `action` discriminator. `tools/list` payload is up to 70% smaller than per-operation APIs, which means less of the model's context window is consumed by tool schemas, lower cost per session, and fewer hallucinated tool names.
- Primary router endpoint: `POST /wp-json/mcp/v1/router`
- Standard MCP-style flow: `initialize` → `tools/list` → `tools/call`
- Session lifecycle for clients (pass `session_id` or `Mcp-Session-Id` after `initialize`)
- Built-in tool registry for common WordPress operations (posts, media, terms, menus, options, and more)
- Bundled Abilities API + MCP Adapter integration, with automatic bridging from registered abilities to MCP tools (configurable)
- WordPress 7.0/Core-aware bridge mode that uses Core Abilities/API surfaces when available and falls back only when needed
- Public tool policy controls (category filters and optional allowlists) plus optional internal tool exposure for private environments
- Bounded MCP audit log, optional per-user/role/client tool allowlists, and a read-only administrator health/status tool

**Security model (high level)**

- MCP access requires a real WordPress user context: Application Password over HTTP Basic, or an existing logged-in session.
- Optional site-wide or per-user API key and HMAC can be enabled in Settings as an additional gate (they do not replace WordPress authentication). Generate/rotate from Settings → Security; by default they are skipped for Application Password and Bearer clients unless you enable “Require for App Password / Bearer”. Do not put the normal WEBO API key in URLs. For clients that cannot send headers, create a short-lived scoped `mcp_token` URL connector token in Settings -> WEBO MCP.
- Default access expectations for the router and `GET /wp-json/webo-mcp/v1/tools`: users who are super admins, can `manage_options`, or can `edit_posts`, consistent with typical site operator and editor workflows (filterable).

**Client guidance**

Always discover tools before calling them: run `tools/list`, pick an exact tool name from the response, validate required arguments, then call `tools/call`. This reduces mistakes and keeps automation predictable in production.

**Further documentation and optional integrations**

- Official website, documentation, and ecosystem notes: https://webomcp.com
- Optional n8n community node (separate package): https://www.npmjs.com/package/n8n-nodes-webo-mcp
- Release notes and migration map: see docs/RELEASE_NOTES_2.1.0.md and docs/MIGRATION_GUIDE_2.1.0.md in the GitHub repository
- Cross-addon dispatcher map (granular legacy names removed from discovery): docs/MCP_TOOL_MIGRATION.md

Compatibility note: any MCP-capable client can be used; which large language model runs inside the client is outside this plugin.

Standalone core tools included:
- Site info
- Content (posts/pages): `webo/content-query` (list, get, find-by-url, search-replace, list-revisions, get-revision; with author/date/taxonomy filters) and `webo/content-mutate` (create, update, delete, bulk-update-status, restore-revision, change-author)
- Users: `webo/list-users` and `webo/user-mutate` (add-to-blog, set-role)
- Media: `webo/media-query` (list with search/MIME/post_id filters, get) and `webo/media-mutate` (upload, update, delete)
- Comments: `webo/comment-query` (list, get) and `webo/comment-mutate` (create, update, delete)
- Taxonomy/Terms: `webo/taxonomy-query` (discover, list, get) and `webo/taxonomy-mutate` (create, update, delete)
- Nav menus: list menus, list menu items (menu_order, db_id), add menu link from post (explicit post_id + menu_order required)
- Plugins: `webo/plugin-query` (installed, active, updates, …) and `webo/plugin-mutate` (install, activate, deactivate; supports child-site `site_id` / `blog_id` activation for network admins)
- Health: `webo/health-status` (REST/router status, Application Password support, permalinks, cron, object cache, plugin update summary, WordPress/PHP versions, and redacted MCP config)
- Client health: `webo/client-health-report` (score 0–100, grade A–D, Markdown scoreboard for agency clients; hybrid foundation for Pro collectors later)
- 404 logs: `webo/get-404-logs` (read-only Rank Math / Redirection 404 monitor: url, hits, accessed, referrer)
- Abilities bridge: `webo/ability-query` and `webo/ability-execute` in default layered mode. Only abilities with `meta.mcp.public === true` are visible and executable through WEBO MCP.
- Themes: `webo/theme-query` (installed themes) and `webo/theme-mutate` (install from WordPress.org by slug, switch installed theme)
- Theme context: `webo/theme-context` (active theme info, block editor settings, style presets, registered blocks)
- Block patterns: `webo/block-patterns` (list/get patterns, list/get synced patterns)
- Site stats: `webo/site-stats` (overview, post counts, comment counts, user counts, media stats, activity summary)
- Activity log: `webo/activity-log` (list events, summary, clear)
- User profile: `webo/user-profile` (get own profile, update display name / bio / preferences)
- Site settings: `webo/site-settings` (get and update the 20 most common WordPress options via MCP)
- Content search: `webo/content-search` (full-text cross-post-type search with grouped results)
- Menus: `webo/menu-query`, `webo/menu-mutate` (navigation menu items; not post/CPT list order)
- Post/CPT order (optional): `webo/reorder-query`, `webo/reorder-mutate` when [Webo Reorder](https://github.com/mrphuong-webo/webo-reorder) is active — see docs/abilities/reorder.md
- Options: get/update (safe allowlist only), set site icon/favicon from media
- SEO (WordPress post): seo/article-analysis — requires post_id; merges Rank Math meta when available (same data path as webo-rank-math/get-post-seo-meta); optional related-keyword suggestions via outbound request unless no_autocomplete is true

Excluded by default in standalone-safe mode:
- Bulk/mass execution tools
- Plugin/theme write-management abilities
- Multisite-specific abilities

== Privacy ==

This plugin does not phone home or send telemetry. MCP traffic is initiated by clients you configure. Some tools may perform outbound HTTP requests only when a client invokes them (for example seo/article-analysis may request keyword suggestions from a third-party suggest API unless you pass no_autocomplete).

The plugin stores the following options in the WordPress database when configured:
- `webo_mcp_api_key`: API key used to authenticate MCP requests.
- `webo_mcp_hmac_secret`: HMAC secret used to sign and validate MCP requests.
- `webo_mcp_require_secondary_credentials`: when enabled, also require API key/HMAC for Application Password and Bearer clients (off by default so standard connectors are not blocked).
- `webo_mcp_url_connector_tokens`: hashed, expirable, revocable URL connector tokens for clients that cannot send headers. Raw tokens are shown once and are not stored.
- `webo_mcp_tool_allowlist_enabled` and `webo_mcp_tool_allowlist_rules`: optional administrator-configured MCP tool allowlist policy.
- `webo_mcp_audit_log_enabled`, `webo_mcp_audit_log_max_entries`, and `webo_mcp_audit_log`: bounded MCP tool-call audit log settings and compact audit events. Audit entries include user/tool/action/status data, anonymized IPs, and hashed session IDs; they do not store request payloads, API keys, HMAC secrets, or Application Passwords.
- `webo_mcp_installed_at` and `webo_mcp_review_notice`: local timestamps/state for an optional WordPress.org review request notice (not sent off-site; dismissible).

These options are removed when the plugin is uninstalled via the WordPress Plugins screen.

== External services ==

This plugin can connect to Google Suggest (Autocomplete) when a client calls the `seo/article-analysis` tool and does not set `no_autocomplete` to true. This external request is used to return related keyword suggestions for SEO analysis.

Service provider: Google LLC (Google Suggest / Autocomplete API endpoint).

Data sent and when:
- Sent only when `seo/article-analysis` is called with autocomplete enabled.
- Sends the analysis query text to `https://suggestqueries.google.com/complete/search` as the `q` parameter.
- Sends standard HTTP request metadata such as IP address and User-Agent as part of the web request.

Terms of Service: https://policies.google.com/terms
Privacy Policy: https://policies.google.com/privacy

== Developer Hooks ==

The plugin exposes the following actions and filters for developers:

=== Actions ===

- `webo_mcp_register_tools`
  Fired during plugin bootstrap after standalone tools are registered. Use this to register custom MCP tools from other plugins.

=== Filters ===

- `webo_mcp_current_user_can_use_mcp` (bool $allowed, int $user_id)
  Gate for all MCP REST access. Default: super admin OR `manage_options` OR `edit_posts`. Override to tighten (e.g. super-admin only) in hardened installs.

- `webo_mcp_secondary_credentials_exempt` (bool $exempt, WP_REST_Request $request)
  When true, skip optional API key / HMAC after WordPress auth. Default true for Application Password (Basic) and Bearer sessions unless Settings → Security → “Require for App Password / Bearer” is enabled. Return false to always enforce `X-WEBO-*` headers.

- `webo_mcp_allow_internal_tools` (bool $allow_internal, WP_REST_Request $request)
  Controls whether internal tools are included in tools/list responses. Defaults to false for public environments.

- `webo_mcp_public_categories` (array $categories, WP_REST_Request $request, array $tool)
  Filters which tool categories are exposed as public. Defaults to array( 'wordpress' ).

- `webo_mcp_rate_limit_per_hour` (int $limit, string $client, array|null $profile)
  Adjust effective hourly limit (fallback for both buckets).

- `webo_mcp_rate_limit_read_per_hour` / `webo_mcp_rate_limit_mutate_per_hour` (int $limit, string $client, array|null $profile)
  Per-bucket limits after admin/profile resolution.

- `webo_mcp_tool_is_mutating` (bool $is_mutating, string $tool_name, array|null $tool_definition, array $arguments)
  Override mutating classification for rate limits and read-only profiles.

- `webo_mcp_tool_arguments_allow_extra` (bool $allow, string $tool_name, array $schema, array $arguments)
  When true, unknown tool argument keys are passed through (default false).

- `webo_mcp_disallow_url_token_query` (bool $disallowed)
  Block URL connector tokens in query strings (admin setting is the default source).

- `webo_mcp_rest_bom_guard_json_api_requests` (bool $activate, string $uri_raw)
  Opt-in BOM sanitizer for all `/wp-json/` responses (default false; MCP routes only).

- `webo_mcp_bridge_deny_patterns` (array $patterns)
  Controls which abilities are excluded when auto-bridging abilities into MCP tools (e.g. bulk, themes/, multisite/).

- `webo_mcp_auto_bridge_abilities` (bool $enabled)
  Enables or disables automatic bridging of registered abilities into MCP tools. Defaults to true; bridge mode still controls whether the bridge is off, layered, or full.

- `webo_mcp_bridge_mode` (string $mode)
  Controls Abilities bridge mode after the `WEBO_MCP_BRIDGE_MODE` constant and before the stored option. Values: `off`, `layered`, `full`. Default: `layered`.

- `webo_mcp_enable_adapter` (bool $enabled)
  Enables or disables the bundled WordPress MCP Adapter runtime. Defaults to true.

- `webo_mcp_validate_media_fetch_url` (true|\WP_Error $ok, string $url, array $parsed)
  Reject unsafe URLs for webo/media-mutate upload action (return WP_Error to block).

- `webo_mcp_tool_allowlist_allowed` (bool $allowed, string $tool_name, WP_REST_Request $request, array $params, array $allowed_tools)
  Filters the optional per-user/role/client allowlist decision.

= Quick start =
1. Upload the plugin folder to /wp-content/plugins/webo-mcp
2. Run composer install inside the plugin folder
3. Activate the plugin in WordPress Admin
4. Send JSON-RPC requests to POST /wp-json/mcp/v1/router

For release packaging, use scripts/build-release.ps1 to create a clean zip with .distignore exclusions.

== Frequently Asked Questions ==

= Which endpoint should MCP clients use? =
POST /wp-json/mcp/v1/router

= Where is the official website and the n8n package? =
The project hub is https://webomcp.com. For n8n, install the community node from npm: https://www.npmjs.com/package/n8n-nodes-webo-mcp

= Is webomcp.com the official WEBO MCP website? =
Yes. The official WEBO MCP website, documentation hub, and ecosystem landing page is https://webomcp.com.

= Can this run WordPress abilities by itself? =
Yes. On WordPress versions where Core provides the Abilities API, WEBO MCP uses Core and does not load a duplicate bundled Abilities API. On older WordPress versions it falls back to the bundled Composer package. The default bridge mode is `layered`, which exposes compact `webo/ability-query` and `webo/ability-execute` tools instead of one tool per ability. You can set bridge mode to `off`, `layered`, or `full` with `WEBO_MCP_BRIDGE_MODE`, the `webo_mcp_bridge_mode` filter, or the `webo_mcp_bridge_mode` option.

= Which abilities are exposed through WEBO MCP? =
Only abilities that explicitly set `meta.mcp.public` to true are exposed. Execution also checks the ability permission callback, WEBO allowlist/policy, and scope/risk metadata such as `meta.webo_mcp.scope` and `meta.webo_mcp.risk`.

= How do I migrate from legacy one-operation tool names? =
Use `tools/list` to discover the dispatcher tool names on your site, then pass the correct `action` (or query/mutate discriminant) for each operation. Use docs/MIGRATION_GUIDE_2.1.0.md for the 2.1.0 rollout narrative and docs/MCP_TOOL_MIGRATION.md for a consolidated addon-by-addon map (Rank Math, Rocket, WooCommerce groups, etc.).

= Can I expose internal tools? =
Yes, via filter webo_mcp_allow_internal_tools in private environments.

= Can I limit public tools by category? =
Yes, via filter webo_mcp_public_categories.

= Can I keep only WordPress.org-safe features? =
Yes. Default bridge rules exclude patterns for bulk, themes, and multisite abilities.

= Is this plugin suitable for production? =
Yes, when used with proper authentication, TLS, and a limited tool exposure policy.

= How do I authenticate MCP clients? =
Use a WordPress **Application Password** (Users → Profile → Application Passwords) and send it with HTTP Basic Auth (username = WordPress username, password = the application password). Optional **API Key** (`X-WEBO-API-KEY`) and **HMAC** (`X-WEBO-TIMESTAMP` + `X-WEBO-SIGNATURE`) are managed under Settings → WEBO MCP → Security (generate/rotate; secrets are shown once). By default those optional headers are **not** required for Application Password or Bearer clients; enable “Require for App Password / Bearer” if your client can send `X-WEBO-*` headers. HMAC signature: `sha256=` + HMAC-SHA256( `timestamp + "." + raw_body`, secret ), skew ≤ 300s. If a client cannot send headers, create a short-lived scoped URL connector token and pass it as `?mcp_token=...`; it is shown once, stored only as a hash, limited to an explicit tool scope, expirable, and revocable.

= Does WEBO MCP reorder posts and pages? =
Use **`webo/reorder-query`** and **`webo/reorder-mutate`** when the separate **Webo Reorder** plugin is installed and active. Those tools control post `menu_order` and taxonomy-specific order — not navigation menus. For Appearance → Menus, use **`webo/menu-query`** and **`webo/menu-mutate`**. See `docs/abilities/reorder.md` in the plugin repository.

== Screenshots ==
1. MCP endpoint working in a REST client (initialize)
2. tools/list response with public tools
3. tools/call response for a WordPress tool

== Changelog ==

= 3.0.22 =
* Security: block server-local paths in `webo-media/upload-file`; accept only connector-rewritten file objects, validated remote URLs, or caller-provided file data.
* Preserve ChatGPT sandbox file rewriting without allowing Author-level users to read files from WordPress, uploads, or temporary directories.
* Fix the WordPress 7.1 Ability API identifier used for the legacy plugin mutation alias.
* Resolve all remaining WordPress Plugin Check findings for the resubmission package.

Historical release notes are maintained in CHANGELOG.md in the public source repository.

== Upgrade Notice ==
= 3.0.22 =
Security update. Upgrade immediately to prevent authenticated Author-level users from reading and republishing server-local files through the media upload tool.

= 3.0.18 =
Multisite site admins can keep style and script tags in MCP content when Trusted raw HTML is enabled. Enable it under Settings → WEBO MCP → Security.

= 2.3.2 =
Recommended for Claude Desktop and other MCP SDK clients: SSE keepalive, standard tools/call content format, and safer AI editing via content checkpoint tools.

= 2.3.1 =
Recommended compatibility update for installs using SCF or plugins that register abilities during activation.

= 2.2.1 =
Recommended compatibility update for sites relying on bundled MCP schema classes or layered ability execution through MCP clients.

= 2.1.23 =
Opt-in fix for multisite Elementor/custom HTML workflows that need trusted administrators to preserve raw HTML tags. Disabled by default.

= 2.1.17 =
Adds post password updates to `webo/content-mutate` for protected content workflows.

= 2.1.14 =
Recommended for multisite networks using child-site plugin activation through MCP; fixes WordPress capability checks after `switch_to_blog()`.

= 2.1.13 =
Adds core plugin mutation plus child-site plugin activation/deactivation via `site_id` or `blog_id` for multisite network admins.

= 2.1.12 =
Adds MCP audit logging, optional tool allowlists, and an administrator health/status tool. Existing MCP access remains unchanged unless allowlist enforcement is enabled in Settings.

= 2.1.11 =
Recommended security hardening release: MCP tools now enforce object-level post/media/term capabilities and only list tools the current user can call.

= 2.1.10 =
Registers the missing **`webo/plugin-query`** tool (plugin inventory and updates via MCP). Recommended for automation that lists pending plugin updates.

= 2.1.9 =
Internal refactor (standalone tool bootstrap file only). No MCP tool renaming; safe routine update.

= 2.1.8 =
Critical for `webo.vn` / multi-BOM REST bodies: fixes BOM sanitizer regex so repeated UTF-8 BOM prefixes are actually removed.

= 2.1.7 =
Recommended if MCP/remote clients still hit `Unexpected token` / invalid JSON — BOM strip now defaults on for **all** REST API responses.

= 2.1.6 =
Use this if MCP clients still fail JSON parse on `discover-abilities` / ability tools — BOM strip now covers `wp-abilities` REST routes.

= 2.1.5 =
If MCP clients still parse-fail on BOM: this release starts the BOM-stripping buffer before `rest_api_init` for MCP-like URLs.

= 2.1.4 =
Further hardening for leading-BOM MCP JSON failures: earlier buffer bootstrap on MCP-like REST URLs.

= 2.1.3 =
Recommended if MCP clients show JSON parse errors (leading BOM) on `tools/list` or `tools/call` — response body is sanitized for MCP REST routes.

= 2.1.2 =
Restores packaged agent **`skills/`** in the upstream repo clone; upgrade if you rely on Cursor/Codex skills from GitHub.

= 2.1.1 =
Documentation-only refresh: use docs/MCP_TOOL_MIGRATION.md when mapping old MCP tool names to dispatchers + `action`. No behavioral change vs 2.1.0 expected.

= 2.0.40 =
Recommended update for MCP clients that batch process posts or rely on seo/article-analysis; list-posts pagination and H1/schema detection are more accurate.

= 2.0.35 =
Adds theme discovery and theme switching tools for MCP clients. This release also carries the shortened WordPress.org short description into the new tagged version.

= 2.0.34 =
Recommended update if you manage homepage reading settings via MCP; adds safe support for `show_on_front` and `page_on_front` updates.

= 2.0.33 =
Documentation-only refresh on WordPress.org listings; recommended if you rely on the plugin directory description for onboarding.

= 2.0.32 =
Recommended update for WP 6.9+ sites using Abilities API and MCP adapter integration.

= 2.0.31 =
Maintenance update.

= 2.0.30 =
Maintenance update.

= 2.0.29 =
Maintenance update for runtime stability and cleaner CLI output. If you use WEBO MCP Pro, review/update the Pro package compatibility notice before deploying this version to production.

= 2.0.28 =
WordPress.org compliance update: readme now documents Google Suggest external service usage with Terms/Privacy links, and nav-menu API loading no longer relies on WPINC.

= 2.0.27 =
MCP clients must send WordPress Application Password (HTTP Basic) or use a logged-in session. API key/HMAC alone are no longer sufficient when calling the router.

= 2.0.26 =
Adds seo/article-analysis for post-level SEO diagnostics (optional outbound suggest API; set no_autocomplete to skip).

= 2.0.7 =
Readme and GitHub README now link webomcp.com and the n8n-nodes-webo-mcp npm package.

= 2.0.6 =
License declaration aligned between readme and main plugin file for WordPress.org review.

= 2.0.5 =
Plugin header updates for Plugin Check and WordPress.org tooling (@wordpress-plugin, GPLv2 license slug).

= 2.0.4 =
Plugin header formatting for WordPress.org Plugin Check (Description, Version, License).

= 2.0.3 =
Plugin Check and packaging fixes; upload the release zip from scripts/build-release.ps1 for WordPress.org.

= 2.0.2 =
Packaging and readme updates for WordPress.org review. Always upload the zip from scripts/build-release.ps1, not the raw git folder.

= 2.0.0 =
Major rename: reinstall from folder webo-mcp (or deploy to new path), then activate WEBO MCP. Settings are preserved via migration.

= 1.1.1 =
Recommended update to fix tools/call validation for core tools with no input.

= 1.0.2 =
Recommended update to support active plugin verification via MCP tool.

= 1.0.1 =
Recommended update to refresh plugin metadata and improve tools/list compatibility.

= 1.0.0 =
Initial public release of WEBO MCP (formerly WEBO WordPress MCP).

== Credits ==
Special thanks to the authors and open source projects that contributed to this plugin:
- WordPress (https://wordpress.org)
- Abilities API (https://github.com/WordPress/abilities-api)
  Reference: https://make.wordpress.org/ai/2025/07/17/abilities-api/
- MCP Adapter (https://github.com/WordPress/mcp-adapter)
  Reference: https://make.wordpress.org/ai/2025/07/17/mcp-adapter/
- Composer (https://getcomposer.org)
- Other PHP and JS libraries from the community

If you use this plugin, please give credit to the authors of these libraries.

== License ==
This plugin is licensed under the GPLv2 or later.
See https://www.gnu.org/licenses/gpl-2.0.html for details.