=== Acadium Agent Publisher ===
Contributors: anselbrandt
Tags: ai, mcp, claude, abilities, content
Requires at least: 6.9
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.8.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Let Claude and other AI agents draft, review and publish posts, upload images and look up categories and tags, within rules you set.

== Description ==

Acadium Agent Publisher lets an AI agent, such as Claude, write and publish blog posts for your site through the WordPress Abilities API and the Model Context Protocol (MCP). The official MCP Adapter library is built in, so there is nothing else to install.

The agent signs in as its own WordPress user with an Application Password, and that user gets the **AI Agent** role that this plugin adds. Under **Settings > Agent Publisher** you decide how far the agent may go:

* **Drafts only** (default): the agent creates and edits its own drafts, and a person publishes them.
* **Submit for review**: the agent can also move its drafts to "Pending review" for an editor.
* **Publish**: the agent can also publish or schedule its own posts, after the checks you set, and unpublish them again.
* **Publish and edit live posts**: the agent can also change its own posts after they are live.

Checks before an agent publishes:

* a title and content are always required
* optional: a featured image with alt text
* optional: allowed categories
* optional: a daily limit

Every agent action is listed under Recent agent activity on the settings page.

= Connect Claude in a few clicks =

The **Connect Claude** section under Settings > Agent Publisher creates the AI Agent user, turns on connector sign-in (OAuth) and shows the connection URL. In Claude Desktop, claude.ai or the Claude mobile apps, add the site as a custom connector with that URL: no Application Password and no software on your computer.

**Connection checks** on the same page test HTTPS, permalinks, the connection URL, the Authorization header and connector sign-in from the server itself, and explain how to fix what fails (with a one-click .htaccess fix for the Authorization header on Apache). Sites that can't use the connector (for example, WordPress in a subfolder) can use the Claude Desktop extension instead: download it from the same page, create an Application Password there, and open the file. Claude Desktop installs it and runs it with its own Node.js, so there's nothing else to install and no configuration file to edit.

When you connect, an administrator logs in to WordPress and approves the connection, choosing which AI Agent user it acts as. The connection never gets the administrator's own permissions. Connected apps are listed on the settings page, and you can disconnect any of them.

= Safety =

* **The AI Agent role never has publishing rights.** It has only read, edit_posts, delete_posts and upload_files. Publishing, scheduling, unpublishing and editing live posts happen only through this plugin's abilities, which check your settings first. Even if the agent calls the regular REST API directly with its password, it cannot publish or change live content.
* **Agents only change their own posts.** They cannot touch other users' posts.
* **Unsafe HTML is removed.** WordPress strips scripts, iframes and event handlers from what the agent writes.
* **Uploads are checked.** The real file type must be JPEG, PNG, GIF or WebP, the size is limited, and URL uploads only fetch from public https addresses.
* **OAuth is off by default.** When it's on:
  * Every connection needs an administrator's approval.
  * PKCE is required.
  * Access tokens expire after an hour, and refresh tokens are single-use.
  * Tokens are stored only as hashes, and they work only for the MCP and Abilities API routes.

Publishing can trigger things that unpublishing cannot undo, such as subscriber emails or social media posts from other plugins. Start with "Drafts only".

= Abilities =

* `agent-publisher/get-capabilities` (read-only): what the site allows
* `agent-publisher/list-terms` (read-only)
* `agent-publisher/get-post` (read-only; any status, including published)
* `agent-publisher/create-post` (as a draft, for review, or published in one step with its featured image)
* `agent-publisher/update-draft-post`
* `agent-publisher/upload-media`
* `agent-publisher/find-media` (read-only: find images in the Media Library)
* `agent-publisher/submit-for-review`
* `agent-publisher/publish-post` (publish now or schedule)
* `agent-publisher/unpublish-post`
* `agent-publisher/update-published-post` (including replacing the featured image)

They are available through the core Abilities REST API (`/wp-json/wp-abilities/v1/`; read-only abilities use GET, the others POST) and, as one MCP tool each, at the plugin's MCP endpoint `/wp-json/acadium-agent-publisher/mcp` for clients such as claude.ai, Claude Desktop and Claude Code.

= For developers =

Filters:

* `agent_publisher_post_types`: post types the post abilities work on (default: `post`).
* `agent_publisher_post_meta`: custom field keys agents may read and write (default: none).
* `agent_publisher_upload_mimes`: accepted image types (default: JPEG, PNG, GIF, WebP).
* `agent_publisher_max_upload`: maximum upload size in bytes (default: 10 MB).

Development happens on GitHub: https://github.com/Acadium/acadium-agent-publisher

== Installation ==

1. Under Settings > Permalinks, choose any structure except "Plain" (for example "Post name"). The plugin offers a one-click button if you forget.
2. Install and activate Acadium Agent Publisher. This adds the **AI Agent** role.
3. Go to Users > Add New User and create a user for the agent (for example `claude`) with the role **AI Agent**. Do not give the agent the Author, Editor or Administrator role.
4. Edit that user and create an Application Password under "Application Passwords". Copy it; it is shown once.
5. Choose what the agent may do under Settings > Agent Publisher (default: Drafts only).
6. Connect your AI client, either way:
   * **claude.ai (web, desktop, mobile):** turn on "Allow OAuth connections" under Settings > Agent Publisher. In claude.ai, go to Settings > Connectors > Add custom connector and enter `https://your-site/wp-json/acadium-agent-publisher/mcp`. Log in to WordPress as an administrator when asked, choose the AI Agent user and click Allow. You can skip step 4.
   * **Claude Desktop or Claude Code with an Application Password:** point the client at `https://your-site/wp-json/acadium-agent-publisher/mcp` with the agent's username and Application Password. The GitHub README has ready-to-paste configurations.

Your site must use HTTPS (WordPress disables Application Passwords on plain HTTP).

== Frequently Asked Questions ==

= Can the agent publish posts? =

Only if you choose "Publish" or "Publish and edit live posts" under Settings > Agent Publisher. By default it can only create drafts, and a person publishes them.

= Can the agent bypass these settings through the REST API? =

No. The AI Agent role has no publishing capabilities, so the regular REST API refuses to publish or edit live posts for it in every mode. Only this plugin's abilities can do that, after checking your settings.

= Can I use it from the Claude mobile app? =

Yes. Turn on "Allow OAuth connections" under Settings > Agent Publisher and add your site as a custom connector in claude.ai. Connectors added there are also available in the Claude mobile apps.

= Do I need the MCP Adapter plugin? =

No. The plugin includes the official MCP Adapter (https://github.com/WordPress/mcp-adapter) library. If the MCP Adapter plugin, or another plugin that includes it (such as WooCommerce), is also active, WordPress loads the newest copy once, so they do not conflict. The MCP Adapter's default endpoint, `/wp-json/mcp/mcp-adapter-default-server`, keeps working for connections made with version 1.2 or earlier.

= Who can approve an OAuth connection? =

Only administrators. The connection always acts as the AI Agent user the administrator picks, never as the administrator. Disconnect it under Settings > Agent Publisher > Connected apps.

= Does this plugin connect to external services? =

No. It does not contact any server on its own. The upload ability downloads an image only when the agent supplies an image URL, and only from public https addresses. With OAuth on, apps such as claude.ai call your site's OAuth endpoints; your site does not call them.

= Do scheduled posts need anything special? =

They are published by WordPress' scheduler (WP-Cron), like posts you schedule yourself. If your site disables WP-Cron, make sure a server cron job runs it.

= How do I revoke access? =

Revoke the agent's Application Password under Users > (agent) > Application Passwords, or delete the agent user. Deactivating the plugin removes the abilities.

= claude.ai cannot connect =

Check that "Allow OAuth connections" is on and that `https://your-site/.well-known/oauth-authorization-server` shows a JSON document. OAuth discovery requires WordPress to be installed at the root of its domain, not in a subdirectory. A firewall or CDN must pass `/.well-known/` and `/agent-publisher-oauth/` requests to WordPress, and must forward the Authorization header.

= The agent gets a 401 error although the password is correct =

Your web server may be removing the Authorization header, which is common with Apache and CGI/FastCGI. Add `SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1` to your .htaccess, and make sure security plugins allow Application Passwords and REST API access for logged-in users.

== Changelog ==

= 1.8.0 =
* Featured images under the minimum width are refused when publishing or replacing a live post's image, by default (Settings > Agent Publisher > Images; untick to allow them with a warning).
* Built-in minimum of 1,200 px when the site sets none, and a recommended width (the largest size WordPress generates) in get-capabilities, so agents always have a target.
* Agents are told never to reduce an image's resolution to fit it through base64, and a small image sent as base64 gets a warning pointing to the upload route (Media > Add New, then find-media).

= 1.7.0 =
* New find-media tool: Claude finds images in the Media Library by title or file name. For large images, upload them in WordPress and ask Claude to use them.
* Image guidance under Settings > Agent Publisher > Images: minimum width, the aspect ratios your theme crops featured images to, and guidance for agents. get-capabilities reports it along with accepted types, the size limit and the sizes WordPress generates. Images that don't fit get warnings in the result; "Strict" refuses to publish with them.
* update-draft-post and update-published-post accept featured_image, so a live post's featured image can be replaced in one step. Post results include the featured image and the sizes WordPress generated from it.
* get-post reads the agent's own published and scheduled posts.
* Base64 uploads accept line breaks, data: prefixes, URL-safe characters and missing padding; errors show what's wrong and where. An optional sha256 refuses corrupted uploads. upload-media returns the file's size and sha256.

= 1.6.1 =
* Fix: connector requests failed with a server error (HTTP 500, "Couldn't connect to the server" in Claude) on sites where another plugin checks the logged-in user early, such as Limit Login Attempts Reloaded. Introduced in 1.5.0.

= 1.6.0 =
* Claude Desktop extension (MCP Bundle) for sites that can't use the connector: download it from Settings > Agent Publisher, create an Application Password there, and open the file. Claude Desktop installs it with its own Node.js; no Node.js install, npx path or JSON editing. The password is stored securely by Claude Desktop.
* The Application Password panel now shows the connection URL, username and password with Copy buttons, for the extension's install dialog. The claude_desktop_config.json block is still available for manual setups.
* The extension pins the WordPress MCP bridge to a tested version instead of fetching the latest from npm at every start.

= 1.5.0 =
* New "Connect Claude" setup on the settings page: create the AI Agent user, turn on connector sign-in and copy the connection URL in a few clicks. An Application Password and a ready-made Claude Desktop configuration are available for sites that can't use the connector.
* New connection checks: HTTPS, permalinks, whether the connection URL answers, whether the Authorization header reaches WordPress (with a one-click .htaccess fix on Apache) and whether connector sign-in can be discovered.
* Security: publishing, unpublishing and editing live posts through the abilities is now limited to AI Agent users; other users need their own WordPress capabilities (for example, Contributors can no longer publish through the abilities in Publish mode).
* Security: OAuth access tokens work only on the MCP and Abilities REST routes, checked on the route actually dispatched; never in wp-admin, admin-ajax, cron or XML-RPC.
* Security: invalid authorization requests show an error page instead of redirecting; the consent screen shows the app's address and flags apps outside claude.ai as unverified; administrators who also hold the AI Agent role can't be chosen as a connection's user.
* Security: reusing a rotated refresh token revokes the connection; clients can only revoke their own tokens; token and revocation rate limits are per client (new filter agent_publisher_client_ip for sites behind a proxy).
* Image downloads stop at the size limit instead of fetching the whole file first.
* MCP errors are written to the PHP error log only when WP_DEBUG is on.

= 1.4.0 =
* New `create-post` replaces `create-draft-post`. In one call it creates the post with categories, tags and a featured image (`featured_image` uploads it), and can submit it for review or publish or schedule it when the site mode allows. An agent now needs one approval for a finished post instead of up to three.
* If a pre-publish check fails, `create-post` creates nothing (including the uploaded image), so the agent can fix its input and try again.
* Tool descriptions and server instructions no longer tell agents to ask again in chat for something the user already requested.

= 1.3.1 =
* Fix: when no custom fields are enabled, the create, update and update-published tools no longer send an invalid schema. MCP clients such as Claude Desktop skipped those tools, so agents could not create posts.

= 1.3.0 =
* The MCP Adapter is now built in; the separate MCP Adapter plugin is no longer needed.
* New MCP endpoint `/wp-json/acadium-agent-publisher/mcp` lists each ability as its own tool. The MCP Adapter default endpoint keeps working, including with OAuth.
* A notice with a one-click fix when the site uses "Plain" permalinks, which AI clients cannot connect through.
* Setup status on the settings page now shows permalinks and the connection URL.

= 1.2.0 =
* OAuth 2.1 for MCP clients, so claude.ai (web, desktop and mobile apps) can connect as a custom connector without an Application Password. Includes discovery metadata (RFC 9728, RFC 8414), dynamic client registration (RFC 7591), authorization code with PKCE, rotating refresh tokens and revocation (RFC 7009).
* Administrator consent screen: each connection acts as a chosen AI Agent user.
* Connected apps list with Disconnect on the settings page.
* OAuth is off by default ("Allow OAuth connections").

= 1.1.0 =
* Publishing modes under Settings > Agent Publisher: drafts only (default), submit for review, publish, publish and edit live posts.
* New abilities: get-capabilities, submit-for-review, publish-post (now or scheduled), unpublish-post, update-published-post.
* Pre-publish checks: featured image with alt text, allowed categories, daily limit.
* Recent agent activity on the settings page.
* The AI Agent role (previously "AI Agent (drafts only)") never has publishing capabilities; publishing goes only through the plugin's abilities.
* Write abilities now all use POST in the core Abilities REST API (update-draft-post previously required DELETE).

= 1.0.0 =
* First release: list terms, get post, create draft post, update draft post and upload media abilities, plus the AI Agent (drafts only) role.

== Upgrade Notice ==

= 1.8.0 =
Agents can no longer publish with featured images under 1,200 px wide (or your site's minimum) unless you allow it under Settings > Agent Publisher > Images.

= 1.7.0 =
Adds image guidance and checks, a find-media tool for images you upload yourself, and one-step featured image replacement on live posts.

= 1.6.1 =
Fixes Claude connectors failing with a server error on sites that run Limit Login Attempts Reloaded or similar plugins.

= 1.6.0 =
Adds a one-click Claude Desktop extension for sites that can't use the connector. Includes the 1.5.0 security fixes.

= 1.5.0 =
Security release: recommended for all sites, especially those in a Publish mode. Adds one-click setup and connection checks under Settings > Agent Publisher.

= 1.4.0 =
create-draft-post is now create-post, which can also publish and set a featured image in one step. Restart Claude Desktop (or reconnect) after updating so it picks up the new tools.

= 1.3.1 =
Fixes Claude Desktop not loading the tools that create and edit posts. Reconnect Claude (or restart Claude Desktop) after updating.

= 1.3.0 =
The MCP Adapter is built in, and the new connection URL is /wp-json/acadium-agent-publisher/mcp. Existing connections keep working.

= 1.2.0 =
Adds optional OAuth so claude.ai and the Claude mobile apps can connect. Off until you enable it under Settings > Agent Publisher.

= 1.1.0 =
Adds optional publishing. The default stays "Drafts only"; nothing changes until you pick another mode under Settings > Agent Publisher.
