=== Cmdlane Agent Link ===
Contributors: paghdarakshay
Tags: mcp, ai agents, wp-cli, abilities api, automation
Requires at least: 6.9
Tested up to: 7.1
Stable tag: 1.0.0
Requires PHP: 8.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect AI assistants to WordPress via WPTerminal: content tools by default, optional admin tools and WP-CLI, signed changes, approval for risky ones.

== Description ==

Cmdlane Agent Link connects your site to the WPTerminal service, so AI assistants that support the Model Context Protocol (MCP), such as Claude and ChatGPT, can work on your site. Reading and small content changes (drafts, alt text, media uploads, comment replies, categories and tags) run straight away. Publishing, editing published content, deleting, settings, plugins, WP-CLI changes and theme code wait for a person's approval in WPTerminal (or in the chat, for assistants that support it). Every change is logged on your site.

The plugin registers its tools with the WordPress Abilities API and authenticates with WordPress Application Passwords.

= What AI agents can do =

* Create, edit and trash posts and pages, and make targeted find-and-replace edits without resending whole pages.
* Save Elementor, Bricks, Breakdance and Beaver Builder layouts through each builder's own code.
* Upload media (including from a public URL) and update alt text, titles and captions. SVG files are sanitized.
* Moderate and reply to comments; manage categories, tags and menus.
* Read and update SEO titles and descriptions (Yoast SEO, Rank Math, All in One SEO).
* Read form entries (WPForms, Gravity Forms, Fluent Forms, Flamingo) and WooCommerce data; create coupons; change prices, stock and order status.

With administrative tools turned on (off by default):

* Run WP-CLI commands, emulated inside WordPress so no WP-CLI install is needed: plugins, themes, users, options, posts, terms, comments, cron, caches, WordPress updates and database queries.
* Edit a draft copy of your theme, preview it privately, and publish it with a backup. PHP is checked for syntax errors and duplicate functions before it is saved.
* Read the PHP error log, with passwords, tokens and the WordPress installation path masked.

= How access works =

When you connect, the plugin creates a separate user account for AI agents ("cmdlane-agent", role "AI Agent (Cmdlane Agent Link)") and WordPress issues an Application Password named "Cmdlane Agent Link" for that account only. The WPTerminal service stores it encrypted. Your own account and password are never shared, and everything the agent does is recorded under its own account.

By default the account works on content: it has an editor's capabilities without `unfiltered_html`, plus reading form entries and WooCommerce orders, customers, products and coupons (and changing products, coupons and order status), editing menus and flushing caches. When an administrator turns on **Allow administrative tools** (on the approval screen or under Settings > Agent Link), the account also gets the administrator role's capabilities, for WP-CLI commands, plugins, themes, users, settings and the theme draft. Turning the setting off removes them again. At either level, these checks apply:

* **Signed changes.** An Application Password alone cannot change anything. Every change made with it must carry a proof signed by the WPTerminal service with an Ed25519 key; only the public key is in this plugin. Each proof is bound to your site, to the credential, to one operation, to the exact request, and expires within five minutes. A leaked password cannot be used to write from anywhere else, and a captured request cannot be replayed or altered. The agent account cannot sign in over XML-RPC.
* **Approvals.** WP-CLI commands are classified as read, write or destructive. Reads run straight away. Writes and destructive commands run only when the signed proof records a person's approval, which this plugin checks itself. WPTerminal makes each approval of a destructive command (deleting plugins, themes, posts or users, changing users, updating WordPress, database writes) valid for that exact command once.
* **Only through this plugin.** The agent account can change the site only through this plugin's own tools. WordPress core and other plugins' REST routes are read-only for it, whatever capabilities it has.
* **Hard limits.** Some changes are always refused, whatever is approved: creating administrators or giving out administrator-level roles, changing or deleting administrators, setting passwords, editing options that control site URLs, access or active code, changing the database schema, deleting the active theme, and deactivating or deleting this plugin. Database queries cannot read or write the users, usermeta and options tables (or the multisite tables), so password hashes, sessions, Application Passwords and stored API keys are never returned.
* **No code execution.** The plugin never runs a shell, starts a process or evaluates PHP sent to it. WP-CLI commands outside a fixed list (eval, shell, config, search-replace, db import and others) do not exist. The one exception is the theme draft, with administrative tools on: PHP the agent writes into the draft theme runs when the draft is previewed through its private link, and on the live site only after a person approves publishing it. Each theme file change is approved on its own.

= Receipts =

Each signed operation leaves a receipt, so when a response is lost on the way back, WPTerminal can check whether the change was made instead of sending it twice.

= Respects people who are editing =

If someone (including you) has a post open in the editor, the agent's change to that post is refused with a message saying who is editing it, so neither side overwrites the other. The agent can try again once the post is closed.

= Connection checks =

Settings > Agent Link shows why a connection does or does not work: whether Application Passwords are available or switched off by a security plugin, whether the connection's Application Password still exists, why the last sign-in was refused, and (on request) whether your REST API answers with JSON or a firewall page. When WordPress refuses the connection's password, the error it returns names the cause. Every error the agent receives also says whether trying again can help and what to do instead.

= Live notices =

While the site is connected, people editing content in wp-admin see a short notice when the agent completes a change, and a warning if the agent changes the post they have open.

= Activity log =

Every change the agent sends is recorded in a local operation log before it runs (kept 7 days, see Receipts). WP-CLI commands, theme changes, connection events and refused requests are also written to an activity log whose latest entries appear in a Dashboard widget for administrators. Secrets are masked; long content is stored only as a size and hash, and WP-CLI command lines are stored shortened to 500 characters.

== External services ==

This plugin connects your site to **WPTerminal** ([wpterminal.com](https://wpterminal.com)), a service run by the plugin's author. WPTerminal provides the MCP endpoint that AI assistants connect to, and forwards their requests to your site. A WPTerminal account is required; the Free plan works with this plugin.

Nothing is sent when the plugin is activated. Data is exchanged only in these cases:

* **Connecting.** When an administrator clicks "Connect to WPTerminal" on Settings > Agent Link, the browser opens wpterminal.com with your site's address, its wp-admin address and the address of the settings screen. After the administrator approves the connection, the browser is sent back to wpterminal.com with a request ID, your site's address, the settings screen address and a one-time code. WPTerminal then exchanges that code, together with a secret only it holds, for the AI agent account's Application Password, by calling your site's `/wp-json/cmdlane-agent-link/v1/pair/exchange` endpoint.
* **Checking the connection.** While connected, opening Settings > Agent Link sends your site's address to `https://wpterminal.com/api/wp/site-status`, about once a minute, to confirm the site is still connected in WPTerminal.
* **WordPress.org.** When an AI agent runs WP-CLI commands that list, search, install, update or verify plugins, themes, translations or WordPress itself, your site contacts api.wordpress.org and downloads.wordpress.org exactly as the Plugins, Themes and Updates screens do. Updating a plugin or theme that comes from elsewhere contacts its vendor's update server, as in wp-admin. These commands need administrative tools turned on and, except lists, searches and checks, a person's approval. See the [WordPress.org privacy policy](https://wordpress.org/about/privacy/).
* **Downloading media.** When an AI assistant uses the "upload media from URL" tool, your site downloads the file from the public URL the assistant gave. Private and local network addresses are refused.
* **Agent requests.** When an AI assistant you connected to WPTerminal uses a tool, WPTerminal calls your site's REST API with that Application Password. The data the tool returns (for example post content, comments, form entries, user lists, WP-CLI output, database query results, or WooCommerce orders and customer names and email addresses) is sent to WPTerminal and to the AI provider whose assistant made the request.

WPTerminal stores the Application Password encrypted. You can revoke it at any time with the Disconnect button, or under Users > Profile for the agent account.

* Service: [https://wpterminal.com](https://wpterminal.com)
* Terms of Service: [https://wpterminal.com/terms](https://wpterminal.com/terms)
* Privacy Policy: [https://wpterminal.com/privacy](https://wpterminal.com/privacy)

== Installation ==

1. Install and activate the plugin.
2. Go to Settings > Agent Link and click "Connect to WPTerminal".
3. Sign in to WPTerminal, then approve the connection back in WordPress.
4. Add the MCP server URL shown on the settings screen to your AI assistant.

Application Passwords must be enabled. They are on by default on sites served over HTTPS.

== Frequently Asked Questions ==

= Does activating the plugin contact an external server? =

No. Nothing is sent until an administrator clicks "Connect to WPTerminal".

= Can an AI agent install plugins, create users or change settings? =

Only if an administrator turns on administrative tools, and then only after a person approves it in WPTerminal. Approving a kind of change (for example "plugin activate") covers changes of that kind on the site for 30 days, and you can revoke it at any time. Deleting things, changing users, updating WordPress and database writes are approved one exact command at a time. Creating administrators, setting passwords and changing site URLs are always refused.

= Can someone who steals the Application Password change my site? =

No. Changes need a proof signed by the WPTerminal service, which the password alone cannot produce. With the password alone, someone could still read what the agent account can read through the REST API, so disconnect if you think it leaked.

= How do I stop all access? =

Click Disconnect on Settings > Agent Link. This revokes the Application Password immediately. Deactivating or deleting the plugin has the same effect; on multisite, network deactivation revokes it on every site.

= What happens when I delete the plugin? =

The Application Password is revoked, the agent account is removed from the site and its content is reassigned to an administrator (on multisite the account stays in the network without access to the site; with no administrator to reassign to, the account is kept without a role so no content is lost), and the plugin's tables, settings and temporary data are deleted. Theme drafts and theme backups in wp-content/themes are left for you to keep or delete.

== Changelog ==

= 1.0.0 =
* First release.

== Upgrade Notice ==

= 1.0.0 =
First release.
