HelperMCP Developer Documentation

Version 1.2.5 · by Helpblogger

HelperMCP turns a WordPress site into an MCP (Model Context Protocol) server. Connect Claude, ChatGPT or any MCP client and it can manage content, media, SEO, plugins, themes, site settings and menus, diagnose PHP errors and fix them in plugin and theme files, and drive any other plugin through its REST API. Developers can add their own tools with the Addon API.

This document covers installation, the security model, every built-in tool, and how to write addons.

Contents#

1. Quick start
2. How it works
3. Safety model
4. Settings reference
5. SEO plugin support
6. Instruction playbooks
7. Troubleshooting and fixing errors
8. Access control: scopes, OAuth, approvals, restore points
9. Site care tools
10. Tool reference
11. Writing addons
12. Hooks and filters reference
13. MCP protocol reference
14. Hardening checklist
15. FAQ
16. Changelog

1. Quick start#

Install#

1. Upload helpermcp-v1.2.5.zip under Plugins > Add New > Upload Plugin, then activate. (The folder inside the zip is helpermcp/, so updates replace the old version cleanly.)
2. Open HelperMCP > Connect.
3. Click Generate New Token and copy it. It is shown once.

Your endpoint is:

https://YOUR-SITE.com/wp-json/helpermcp/v1/mcp

Connect a client#

Claude (custom connector). Add a custom connector and paste the URL with the token as a query parameter:

https://YOUR-SITE.com/wp-json/helpermcp/v1/mcp?token=hmcp_xxxxxxxx

Clients that support headers (Claude Code, Cursor, many others) should send the token as a bearer header instead, which keeps it out of server logs:

Authorization: Bearer hmcp_xxxxxxxx

Example for Claude Code:

claude mcp add --transport http helpermcp https://YOUR-SITE.com/wp-json/helpermcp/v1/mcp \
  --header "Authorization: Bearer hmcp_xxxxxxxx"

Verify with curl#

curl -s https://YOUR-SITE.com/wp-json/helpermcp/v1/mcp \
  -H "Authorization: Bearer hmcp_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

You should get a JSON list of tools. A good first prompt for your AI is: "Call get_site_overview and tell me what you can do on this site."

What is on by default#

Reading, content writing, SEO, media, taxonomies, comments, menus, redirects, schema, security scanning, performance audits and diagnostics are on. Anything that installs, edits or removes code or configuration, or deletes data, starts switched off (plugin and theme management, site and plugin settings writes, file editing, the database tool, the REST bridge, users, image optimisation, database clean-up, core updates, quarantine). Turn them on, one by one if you like, under HelperMCP > Tools. To connect an app without a token, use OAuth (section 8.2).

2. How it works#

 AI client ──JSON-RPC over HTTPS──▶ /wp-json/helpermcp/v1/mcp
                                      │
                                      ├─ bearer token → WordPress user
                                      ├─ tool enabled? (Tools page)
                                      ├─ user has the capability? (edit_post, install_plugins ...)
                                      ├─ site setting allows it? (publishing, deleting ...)
                                      └─ tool runs → result (or error) → activity log

• Every token acts as one WordPress user. The tool runs as that user, so it can never do more than that person could do in wp-admin. A token belonging to an Editor cannot install plugins, no matter which tools are on.
• Tools are the only way in. There is no arbitrary code execution. The widest tools (rest_request, db_query, file tools) are individually switchable and sandboxed as described in section 3.
• Playbooks (Markdown files) are injected into the AI's instructions when it connects, so it follows your house style.
• Addons register extra tools through a small PHP API (section 11).

File locations#

Uploads folders are protected with .htaccess and an index.php. On Nginx, deny direct access to /wp-content/uploads/helpermcp/ in your server config.

3. Safety model#

Several independent layers sit between the AI and your site. All of them must allow an action.

1. Authentication. Bearer tokens only; stored as SHA-256 hashes; revocable; the plaintext is shown once. Prefix hmcp_.
2. User capabilities. Every tool checks the token owner's real WordPress capabilities (edit_post, publish_posts, upload_files, install_plugins, manage_options and so on). Tools that declare a capability are refused up front.
3. Tool switches. Each tool can be turned off. Disabled tools are hidden from the AI and refused if called. High-impact tools start off.
4. Site settings. Publishing, trashing, permanent deletion, media, custom fields, terms and site-wide search/replace each have their own switch (section 4).
5. Confirmation flags. Destructive tools need an explicit flag such as confirm: true. Site-wide replace defaults to a dry run.
6. Protected targets.
   • HelperMCP will not deactivate, update, delete or edit itself through its own connection.
   • Options such as siteurl, home, admin_email, active_plugins, user roles, salts and every helpermcp_* option cannot be written. Option values that look like secrets are masked when read.
   • wp-config.php, .env, key files, SQL dumps and .git can never be read or written.
   • The site file root is read-only; only plugin:<folder>, theme:<folder> and mu-plugin can be written, and only for text file types.
   • The database tool is read-only and cannot touch password hashes, session tokens or HelperMCP tokens.
   • The REST bridge cannot reach HelperMCP's own routes or the core plugin/theme routes.
7. Automatic rollback. Activating a plugin, switching a theme, and every file write run a loopback health check before and after. If the site was healthy and then returns an error, the change is undone automatically.
8. Backups. Every file change is backed up first and can be restored with restore_backup.
9. Audit log. Every write is recorded under HelperMCP > Activity.
10. Token limits. Scoped access levels, expiry, IP allowlists and rate limits (section 8.1).
11. Approval gate. Optionally hold risky or all changes until you approve them (section 8.3).
12. Restore points. Automatic snapshots before bulk and settings changes (section 8.4).

Rollback: what to know#

The health check requests your homepage from the server itself. It works on almost every host. If a host blocks loopback requests, the tool says so in its result (WARNING: the automatic site check could not run), and you should open the site to confirm it loads. After a write, HelperMCP calls opcache_invalidate so the check sees the new code.

4. Settings reference#

HelperMCP > Content & Safety

HelperMCP > SEO Plugins: choose a specific SEO plugin or leave on Automatic; toggle built-in SEO output when no SEO plugin is active. HelperMCP > Addons: toggle loading of drop-in addon files. HelperMCP > Tools: the per-tool and per-group switches.

5. SEO plugin support#

The AI always uses the same normalized fields. HelperMCP translates them to whichever SEO plugin is active:

title, description, focus_keywords, canonical, noindex, nofollow, og_title, og_description, og_image, twitter_title, twitter_description, twitter_image

Any field a plugin cannot store is kept in HelperMCP's own meta (_helpermcp_seo_*) so nothing is lost, and set_seo tells you which fields went there (fallback_fields).

Category/tag SEO (get_term_seo, set_term_seo) supports Yoast, Rank Math, SEOPress and built-in storage.

Compatibility note. The Yoast and Rank Math mappings were verified by simulating their stored fields; test All in One SEO and the others on a staging site before relying on them in production. Use get_seo_status to see what HelperMCP detected.

6. Instruction playbooks#

Playbooks are Markdown files (HelperMCP > Instructions, or written by the AI itself with save_instruction / append_instruction). A pinned playbook is injected into the AI's instructions on every connection and its front matter sets defaults for new content.

---
default_status: draft
default_post_type: post
default_author: 2
default_category: News
default_tags: nigeria, tech
default_featured_image: 123
featured_image: required
content_format: markdown
alt_text: from_title
---

# House style
- Short paragraphs, plain English.
- Every article gets a featured image with alt text.

Later pinned files (alphabetical) override earlier ones. Files are capped at 200 KB; up to 30 KB of pinned text is injected per session. Only administrators can create, change, pin or delete playbooks.

7. Troubleshooting and fixing errors#

HelperMCP can find the exact file, line and cause of a PHP error and fix it.

Step 1: switch on logging (once)#

Add to wp-config.php above the "stop editing" line:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Step 2: diagnose#

Ask your AI: "Something is broken, run diagnose_errors." The tool:

• reads the tail of the debug log and groups repeated errors;
• reads WordPress's own list of paused plugins and themes;
• for each error returns: type, message, file and line, whether it belongs to a plugin, theme or core (and which), the source code around the line, a plain-language likely cause and a suggested fix, plus the root and path to use with the file tools.

Step 3: fix#

If the Plugin & theme files tools are enabled (they start off, enable them under HelperMCP > Tools), the AI continues with:

1. read_file around the reported line.
2. patch_file with an exact find/replace. The edit is syntax-checked, backed up, written, and the site is health-checked. A change that breaks the site is rolled back automatically.
3. diagnose_errors again to confirm the error stopped.

If something goes wrong: list_backups then restore_backup.

If the file tools stay off, the AI will explain the exact fix, or recommend deactivate_plugin for the offender.

Guardrails specific to file edits#

• Writable: plugin:<folder>, theme:<folder>, mu-plugin. Read-only: site.
• Never writable: HelperMCP itself, WordPress core, wp-config.php.
• Writable file types: php, js, css, json, html, htm, txt, md, xml, svg, twig, yml, yaml, ini, scss, less, pot, po, mjs. Maximum 1 MB per write.
• Respects DISALLOW_FILE_EDIT and the edit_plugins / edit_themes capabilities. If your host or wp-config disables the built-in editor, the file write tools are refused too.

Errors the finder recognizes#

Undefined function, class not found, memory exhausted, member function on null, undefined variable/key/property, syntax and parse errors, execution timeout, cannot redeclare, PHP 8 type errors, dynamic property deprecations, headers already sent, failed to open stream, too few arguments, division by zero, uncaught errors/exceptions. Anything else still gets file, line, code and a generic next step.

8. Access control: scopes, OAuth, approvals, restore points#

8.1 Token scopes, expiry, IP allowlist, rate limits#

Every token (HelperMCP > Connect) can be narrowed when you create it. Scopes only ever narrow access: a scoped token still needs the tool to be switched on and its WordPress user to hold the required capability.

A tool outside a token's scope is hidden from tools/list and refused if called, and the AI is told its access level when it connects. The control group (check_approval, restore points) is always reachable.

8.2 Sign in with WordPress (OAuth)#

Connectors that support OAuth (Claude's custom connectors and other MCP clients) can connect without pasting a token. Switch it on or off under Connect > Allow sign-in with WordPress (OAuth).

Flow. The client registers itself, opens a WordPress login and consent screen where you choose Content & SEO, Read-only, or (administrators only) Everything, then receives a short-lived access token and a rotating refresh token. Each issued token is an ordinary HelperMCP token owned by the person who approved, so all the usual checks apply.

Rules enforced: PKCE with S256 is required; authorization codes are single use and expire after 10 minutes; redirect URIs must be https (or http://localhost) and exactly match what the client registered; access tokens last 1 hour; refresh tokens last 60 days and rotate on every use (the old one is revoked); registrations are limited to 20 per hour per IP and 100 clients in total. Disconnect any app from Connect > Connected apps.

Requirements: pretty permalinks, and your web server must pass /.well-known/... to WordPress. Default Apache .htaccess rules and the usual Nginx try_files $uri $uri/ /index.php?$args do this. Some hosts, firewalls and CDNs intercept /.well-known/; if discovery fails, allow those two paths through. When a request has no valid token, HelperMCP answers 401 with a WWW-Authenticate header pointing at the resource metadata, as the MCP authorization spec requires.

Verified end to end with a scripted client (registration, login, consent, PKCE, code reuse, refresh rotation). Test it with your actual connector on a staging site first.

8.3 Approval gate#

Under HelperMCP > Control choose which actions need your approval:

A held tool is not executed. It returns approval_required with an approval_id, and the AI is instructed to tell you and wait. You approve or deny in wp-admin (a count shows on the Control tab). On approval the tool runs exactly as the AI requested, as the user who asked, with all capability checks repeated; the AI collects the result with check_approval. Requests expire after 24 hours; each user can have at most 50 pending. Read-only tools and the Control tools are never held.

8.4 Restore points#

A restore point stores the previous state of posts (title, content, excerpt, status, slug, dates, author, terms, SEO fields, featured image, public custom fields) and/or options. HelperMCP takes one automatically before: bulk_update_posts, replace_in_content (when applied), update_site_settings, update_option_value, delete_option_value, set_theme_mod, convert_to_webp, block template edits and resets, and update_global_styles. Take one on demand with create_restore_point. The result of each of those tools includes restore_point_id.

Roll back from Control > Restore points or with restore_restore_point (needs confirm: true). The newest 150 are kept; a single restore point is capped at 8 MB.

Not covered: plugin and theme files (file edits have their own backups, section 7), media files, plugin installs, and database content outside posts and options. Take a database backup (create_db_backup) before anything bigger.

9. Site care tools#

These tools turn "check on my site" into prompts. They report and fix, with dry runs and backups wherever data could be lost.

9.1 Security scan#

security_scan reviews core integrity, PHP files in uploads, backdoor and obfuscation patterns (eval of decoded data, command execution from request input, known webshell signatures, very long encoded strings), administrator accounts, risky configuration (public debug.log, displayed errors, XML-RPC, file editor, wp-config.php permissions, HTTPS, PHP and WordPress versions) and plugin health (updates, inactive plugins, plugins unmaintained for over 2 years, plugins missing from WordPress.org). Add recent_changes for a list of recently modified PHP files.

• Findings are indicators, not verdicts. Legitimate security and cache plugins contain some of these patterns. Review with read_file, and confirm WordPress.org plugins with verify_plugin_files.
• There is no vulnerability database. For known-CVE checks use a service such as Wordfence Intelligence or Patchstack.
• verify_core_files and verify_plugin_files compare against official checksums and need outbound access to api.wordpress.org / downloads.wordpress.org. Premium plugins have no official checksums.
• If you find a real backdoor: quarantine_file (reversible), change all admin passwords, update everything, reinstall core, check for new admin users, and look for how it got in. A scanner cannot guarantee a site is clean.

9.2 Performance#

1. performance_audit: autoloaded options (with the plugin that owns the largest), expired transients, revisions, auto-drafts, trash, spam, orphaned custom fields, largest tables, cache and PHP configuration, overdue cron. It returns prioritised recommendations.
2. measure_page: response time, size, compression, cache headers, script/CSS/image counts, render-blocking scripts, heaviest images (same-site URLs only).
3. create_db_backup, then cleanup_database with dry_run (default) to preview, then dry_run: false to apply (needs "Allow permanent deletion").
4. set_option_autoload to stop a big option loading on every request (the value is unchanged).

9.3 Images#

image_audit finds heavy and oversized images and estimates savings. optimize_images resizes (default max 2000 px) and recompresses in the same format, keeping URLs; originals are kept in uploads/helpermcp/image-backups/ and restore_image undoes it; dry_run defaults to true and each call handles up to 25 images. convert_to_webp converts one JPEG/PNG to WebP and rewrites the old URLs in post content and Elementor data (a restore point is taken first). Other page builders may store image URLs elsewhere, so spot-check and clear caches. bulk_fix_alt_text fills missing alt text from the parent post title or a cleaned file name (generic fallbacks, write real descriptions for important images).

9.4 Redirects, 404s and broken links#

HelperMCP runs its own redirect rules on the front end (types 301, 302, 307, 308 and 410; exact paths or regular expressions; targets can reference $1). If another redirect plugin handles a URL first, HelperMCP never sees it. Safeguards: duplicate sources, self-redirects, redirect loops and redirecting the homepage are refused; imports are validated with a dry run.

Visitors' 404s are logged (bot probes, .php and admin paths are ignored; the newest 5000 are kept). suggest_redirect finds the best matching page by slug and title similarity (and WordPress's record of previous slugs), and fix_404s creates 301s for confident matches (min_score default 0.8, dry_run default true). scan_broken_links checks every link in chosen or recent posts (40 distinct URLs per call) and returns link_index values for replace_link / remove_link. Links answering 401, 403 or 429 are not reported because many sites block automated checks.

9.5 Schema, robots.txt and sitemaps#

set_custom_schema adds JSON-LD (FAQPage, Product, Recipe, Event, LocalBusiness, HowTo, VideoObject, Article and others) to a post; it is printed in the page head and sanitised (URL fields must be http/https). Required properties are enforced locally; this is not Google's Rich Results Test. Run get_post_schema first: it shows what your SEO plugin already outputs and flags duplicate types. get_robots_txt / set_robots_txt manage the file crawlers receive (a physical file is backed up and edited; otherwise a virtual file overrides SEO plugin editors); a rule that blocks the whole site is refused unless allow_block_all is set. get_sitemap_info finds the sitemap, counts URLs and checks that robots.txt references it.

9.6 Block themes#

For block themes: list and edit templates and template parts, create patterns, read merged theme.json, and merge changes into Global Styles. Edits are stored as user customisations (the theme file is untouched), a restore point is taken first, and reset_block_template returns to the theme original. On a classic theme these tools explain that and point to the Customizer tools.

9.7 Backups and core updates#

create_db_backup writes a gzip SQL export of this site's tables to wp-content/uploads/helpermcp/dbbackups/ (protected folder; it contains password hashes, so treat it as sensitive and copy it off the server). It keeps the newest 5 and refuses databases over 1.5 GB. HelperMCP does not restore databases remotely; restore with gunzip < file.sql.gz | mysql -u USER -p DATABASE or phpMyAdmin. run_backup_plugin can start UpdraftPlus; other backup plugins are detected and reported. update_core refuses unless a HelperMCP database backup from the last 24 hours exists (or you pass backup_confirmed: true for a full backup elsewhere), health-checks the site afterwards, and WordPress finishes any database upgrade the next time wp-admin opens.

10. Tool reference#

HelperMCP ships with 165 tools (plus 8 hidden aliases that keep older HelperSEO prompts working). Tools marked off by default must be enabled under HelperMCP > Tools before the AI can see or use them.

Types: read never changes anything. write changes something. guarded is destructive and needs an explicit confirmation.

Posts, pages & custom post types#

20 tools, 20 on by default.

get_site_overview#

Site overview · read · on by default

Start here. Returns the site name and URL, WordPress version, the connected user, the SEO plugin HelperMCP is writing through, every post type you may manage with counts per status, taxonomies, what the settings allow (publishing, deleting, media), and the names of the instruction playbooks.

No parameters.

list_post_types#

List post types · read · on by default

Every post type you can manage (posts, pages and custom types), with labels, whether it is hierarchical, which taxonomies and features it supports, page templates, and counts per status.

No parameters.

list_authors#

List authors · read · on by default

Users who can write content, with ID, display name and login. Use an ID from here as author in create_post or update_post.

list_posts#

Search and list posts · read · on by default

Search or browse any post type with filters. Returns compact rows (ID, title, slug, URL, status, dates, author, word count, whether it has a featured image). Use "missing" to find content that lacks an SEO title, SEO description, focus keyword, featured image or excerpt.

get_post#

Get a post · read · on by default

Everything about one post or page: fields, full body content, featured image, taxonomy terms, SEO fields (read through the active SEO plugin), custom fields, template and URLs. Call this before editing.

get_post_content#

Get exact post content · read · on by default

The exact, complete body stored for a post. Use before update_post_content, since that tool replaces the whole body. For small edits prefer patch_post_content, which needs no full rewrite.

find_post_by_url#

Find a post by URL · read · on by default

Resolve a public URL or path on this site to its post ID and details.

create_post#

Create a post, page or custom post type entry · write · on by default

Creates new content of any managed post type in one call: title, body, excerpt, slug, status, schedule date, author, parent, template, categories/tags/any taxonomy, featured image (by media ID or by URL, downloaded for you), SEO fields (through the active SEO plugin) and custom fields. Defaults to the site default status, normally draft, so nothing goes live unless you ask. Respects the defaults in any pinned instruction playbook (default category, author, featured image rule and so on).

update_post#

Update a post · write · on by default

Changes any fields of an existing post, page or custom post type entry. Only the fields you pass change. Can set the body (full replacement), taxonomies, featured image, SEO fields, custom fields, status, schedule date, author, parent, template and more in a single call.

update_post_content#

Replace post content · write · on by default

Replaces a post's ENTIRE body. Fetch the exact current text with get_post_content first, edit it, and pass the complete result back. For surgical edits use patch_post_content instead.

patch_post_content#

Find and replace inside one post · write · on by default

Surgical edits to a post body without resending it. Each edit is an exact find string and its replacement. By default a find that matches more than once is refused, so you never change the wrong spot; set all true to replace every match, or use regex true for a pattern. Use dry_run true to preview.

insert_post_content#

Insert content into a post · write · on by default

Adds content at the start or end of a post, or immediately before or after a given piece of text or a heading, without touching the rest.

change_post_status#

Change post status · write · on by default

Changes only the status (draft, pending, publish, private, future). For future, pass a date to schedule.

schedule_post#

Schedule a post · write · on by default

Schedules a post to publish automatically at a future date and time (site timezone).

duplicate_post#

Duplicate a post · write · on by default

Copies a post with its taxonomies, featured image, custom fields and SEO meta into a new draft.

trash_post#

Trash or delete a post · guarded · on by default

Moves content to the trash by default (recoverable). Permanent deletion needs permanent true AND confirm_permanent_delete true, and must be enabled in HelperMCP settings.

restore_post#

Restore from trash · write · on by default

Brings a trashed post back (as a draft).

bulk_update_posts#

Bulk update posts · write · on by default

Applies update_post to many posts in one call. Each item is an object with post_id plus the same fields update_post accepts. Items run independently and the result lists success or error per item. Capped by the bulk limit in settings.

list_revisions#

List revisions · read · on by default

Saved revisions of a post, newest first.

restore_revision#

Restore a revision · write · on by default

Rolls a post back to a saved revision.

SEO#

7 tools, 7 on by default.

get_seo_status#

SEO plugin status · read · on by default

Which SEO plugin HelperMCP is reading and writing through (Yoast, Rank Math, All in One SEO, SEOPress, The SEO Framework, SmartCrawl, Slim SEO, HelperSEO or its own built-in output), and which SEO fields that plugin supports.

No parameters.

get_seo#

Get SEO fields · read · on by default

A post's SEO title, meta description, focus keywords, canonical, noindex/nofollow and social (Open Graph, Twitter) fields, read from the active SEO plugin.

set_seo#

Set SEO fields · write · on by default

Writes any subset of SEO fields for a post through the active SEO plugin: title, description, focus_keywords, canonical, noindex, nofollow, og_title, og_description, og_image, twitter_title, twitter_description, twitter_image. Pass an empty string to clear a field.

analyze_post#

Analyze on-page SEO · read · on by default

Scores a post (or a draft you pass in directly) against an on-page checklist: title and description length, focus keyword placement and density, word count, headings, image alt text, internal and external links, and readability. Pass post_id for a saved post, or content/title/description/focus_keyword/slug for unsaved text.

seo_audit#

Site SEO audit · read · on by default

Scans the most recent published content and reports how many items are missing an SEO title, meta description, focus keyword, featured image or excerpt, are noindexed, have over-long titles or descriptions, or are thin, with example post IDs for each so you can fix them in bulk.

get_term_seo#

Get category/tag SEO · read · on by default

SEO title, description, focus keywords, canonical and robots for a category, tag or other taxonomy term (Yoast, Rank Math, SEOPress and built-in storage).

set_term_seo#

Set category/tag SEO · write · on by default

Writes SEO fields for a category, tag or other taxonomy term. Only the fields you pass change.

Categories, tags & terms#

6 tools, 6 on by default.

list_taxonomies#

List taxonomies · read · on by default

Categories, tags and custom taxonomies for the post types you manage, with whether each is hierarchical.

get_terms#

List terms · read · on by default

Terms of a taxonomy (default category) with ID, name, slug, parent and post count.

create_term#

Create a term · write · on by default

Creates a category, tag or custom taxonomy term.

update_term#

Edit a term · write · on by default

Renames, re-slugs, re-describes or re-parents a term. SEO fields are separate, use set_term_seo.

delete_term#

Delete a term · guarded · on by default

Permanently deletes a term. Posts keep existing but lose that term. Needs confirm true.

set_post_terms#

Set a post's terms · write · on by default

Sets (or with append true, adds to) a post's terms in one taxonomy. Terms can be IDs or names, missing names are created.

Media#

8 tools, 8 on by default.

list_media#

List media · read · on by default

Browse the media library. Filter by search text, mime type (e.g. image) or unattached only.

get_media#

Get a media item · read · on by default

Details of one media item: URL, sizes, mime type, alt text, caption, description and where it is attached.

upload_media#

Upload media · write · on by default

Adds a file to the media library from a URL (downloaded for you) or from base64 data. Optionally sets title, alt text, caption, description, attaches it to a post, and sets it as that post's featured image.

update_media#

Edit a media item · write · on by default

Changes a media item's title, alt text, caption or description.

set_featured_image#

Set featured image · write · on by default

Sets a post's featured image from a media ID or an image URL (downloaded for you), or removes it with remove true.

delete_media#

Delete media · guarded · on by default

Permanently deletes a media item and its files. Needs confirm true and permanent deletion enabled in settings.

find_images_missing_alt#

Find images missing alt text · read · on by default

Lists images with no alt text, either inside one post's body (pass post_id) or across the media library.

fix_image_alt_text#

Fix image alt text · write · on by default

Sets alt text. Pass attachment_id with alt to write a specific description, or without alt to derive one from the parent post title. Pass post_id to fill every empty alt inside that post's body from the post title. Never overwrites existing alt text.

Links#

5 tools, 5 on by default.

get_post_links#

List links in a post · read · on by default

Every link in a post body, in order, each with a link_index for replace_link and remove_link. Call right before editing links.

replace_link#

Replace a link · write · on by default

Changes an existing link's URL, anchor text and/or rel (e.g. nofollow sponsored). Pass expected_anchor_text from get_post_links as a safety check.

remove_link#

Remove a link · write · on by default

Unlinks text and keeps the words (default). keep_text false plus confirm_delete_text true also deletes the words.

suggest_internal_links#

Suggest internal links · read · on by default

Finds natural sentences in other content that could link to a target post, matched on its focus keyword and title. Returns the exact sentence apply_internal_link needs.

apply_internal_link#

Insert an internal link · write · on by default

Wraps an exact phrase of existing plain text in a source post with a link to a target post or URL.

Custom fields#

3 tools, 3 on by default.

get_post_meta#

Get custom fields · read · on by default

A post's custom fields (keys not starting with an underscore). Pass key for one field.

set_post_meta#

Set a custom field · write · on by default

Creates or updates a custom field (uses ACF when present). Value can be text, number, boolean, array or object.

delete_post_meta#

Delete a custom field · guarded · on by default

Deletes a custom field from a post.

Site-wide search & replace#

2 tools, 2 on by default.

search_content#

Search all content · read · on by default

Finds an exact string (or regex) inside post bodies across the managed post types and returns each match with a snippet and count.

replace_in_content#

Find and replace across the site · write · on by default

Replaces a string (or regex) inside post bodies across many posts. dry_run defaults to TRUE so you see exactly what would change first; set dry_run false to apply. Capped by the bulk limit.

Instruction playbooks#

6 tools, 6 on by default.

list_instructions#

List instruction playbooks · read · on by default

Markdown playbooks saved on this site (style guides, standing instructions, publishing checklists), with whether each is pinned. Pinned playbooks are already part of your instructions.

No parameters.

get_instruction#

Read a playbook · read · on by default

Full Markdown of one playbook.

save_instruction#

Save a playbook · write · on by default

Creates or overwrites a Markdown playbook. Optional front matter at the top (between --- lines) sets defaults for new content: default_status, default_post_type, default_author, default_category, default_tags, default_featured_image (media ID or URL), featured_image (none, optional, required), content_format (html, markdown), alt_text (from_title). Pin it so every future session follows it automatically.

append_instruction#

Append to a playbook · write · on by default

Adds text to the end of a playbook (creating it if needed), for recording new standing rules without rewriting the file.

pin_instruction#

Pin or unpin a playbook · write · on by default

Pinned playbooks are injected into the AI's instructions on every connection and their front-matter defaults apply to new content.

delete_instruction#

Delete a playbook · guarded · on by default

Permanently deletes a playbook. There is no trash.

Comments#

3 tools, 3 on by default.

list_comments#

List comments · read · on by default · requires moderate_comments

Comments with author, content, status and the post they belong to. Filter by status (hold, approve, spam, trash), post or search text.

set_comment_status#

Moderate a comment · write · on by default · requires moderate_comments

Approves, unapproves, marks as spam, trashes or restores a comment.

reply_to_comment#

Reply to a comment · write · on by default · requires moderate_comments

Posts a reply to a comment as the connected user.

Menus#

6 tools, 6 on by default.

list_menus#

List menus · read · on by default · requires edit_theme_options

Navigation menus, their item counts, and which theme locations they are assigned to.

No parameters.

get_menu_items#

Get menu items · read · on by default · requires edit_theme_options

Items of one menu (ID, name or slug) with parent, order and target.

create_menu#

Create a menu · write · on by default · requires edit_theme_options

Creates a navigation menu, optionally assigning it to a theme location.

add_menu_item#

Add a menu item · write · on by default · requires edit_theme_options

Adds an item to a menu: a custom link (url), or a post/page (post_id), or a term (term_id and taxonomy).

remove_menu_item#

Remove a menu item · guarded · on by default · requires edit_theme_options

Removes one item from a menu.

set_menu_location#

Assign a menu to a location · write · on by default · requires edit_theme_options

Assigns a menu to a theme location (see list_menus for location names).

Users#

4 tools, 0 on by default.

list_users#

List users · read · off by default (high impact) · requires list_users

Users with ID, login, display name, email, roles and registration date.

create_user#

Create a user · write · off by default (high impact) · requires create_users

Creates a user and emails them a password-setup link. Creating an administrator needs confirm_admin true.

set_user_role#

Change a user role · write · off by default (high impact) · requires promote_users

Changes a user's role. Granting administrator needs confirm_admin true. You cannot change your own role.

send_password_reset#

Send a password reset · write · off by default (high impact) · requires edit_users

Emails a user a password reset link. Passwords are never set directly.

Plugins#

9 tools, 3 on by default.

list_plugins#

List plugins · read · on by default · requires activate_plugins

Every installed plugin with name, version, active state, whether an update is available, auto-update state and whether WordPress has paused it because of an error.

search_plugin_directory#

Search the WordPress.org plugin directory · read · on by default · requires install_plugins

Searches WordPress.org for plugins to install. Returns slug, name, version, rating, active installs and a short description.

install_plugin#

Install a plugin · write · off by default (high impact) · requires install_plugins

Installs a plugin from the WordPress.org directory (slug) or from a https zip URL. Optionally activates it, with an automatic safety check that deactivates it again if the site breaks.

activate_plugin#

Activate a plugin · write · off by default (high impact) · requires activate_plugins

Activates an installed plugin. A loopback check runs afterwards and the plugin is deactivated again automatically if the site starts returning errors.

deactivate_plugin#

Deactivate a plugin · write · off by default (high impact) · requires activate_plugins

Deactivates a plugin without deleting it. Use this first when a plugin is suspected of causing an error.

update_plugin#

Update plugins · write · off by default (high impact) · requires update_plugins

Updates one plugin, or every plugin with an update when plugin is "all".

delete_plugin#

Delete a plugin · guarded · off by default (high impact) · requires delete_plugins

Permanently deletes an INACTIVE plugin and its files. Needs confirm true and permanent deletion enabled in settings.

set_auto_updates#

Set automatic updates · write · off by default (high impact) · requires update_plugins

Turns automatic background updates on or off for plugins or themes.

check_updates#

Check for updates · read · on by default · requires update_plugins

Refreshes and lists available updates for WordPress core, plugins and themes.

No parameters.

Themes#

5 tools, 1 on by default.

list_themes#

List themes · read · on by default · requires switch_themes

Every installed theme with version, which is active, parent theme, and update availability.

No parameters.

install_theme#

Install a theme · write · off by default (high impact) · requires install_themes

Installs a theme from WordPress.org (slug) or a https zip URL.

activate_theme#

Activate a theme · write · off by default (high impact) · requires switch_themes

Switches the active theme. If the site breaks afterwards the previous theme is restored automatically.

update_theme#

Update themes · write · off by default (high impact) · requires update_themes

Updates one theme or all themes with an update ("all").

delete_theme#

Delete a theme · guarded · off by default (high impact) · requires delete_themes

Permanently deletes an inactive theme. Needs confirm true and permanent deletion enabled in settings.

Site & plugin settings#

8 tools, 4 on by default.

get_site_settings#

Get site settings · read · on by default · requires manage_options

Site name, tagline, logo, favicon (site icon), language, timezone, date and time format, front page, posts per page, permalinks, search engine visibility, comment and registration defaults.

No parameters.

update_site_settings#

Update site settings · write · off by default (high impact) · requires manage_options

Changes site-wide settings. Any subset of: site_title, tagline, timezone, date_format, time_format, start_of_week, language, posts_per_page, show_on_front (posts|page), front_page (page ID or slug), posts_page (ID or slug), search_engine_visibility (visible|hidden), permalink_structure, default_category, default_comment_status (open|closed), comment_moderation (bool), users_can_register (bool), default_role. Logo: logo_id or logo_url, remove_logo. Favicon: favicon_id or favicon_url, remove_favicon. The site URL and admin email are deliberately not changeable here.

list_options#

List options · read · on by default · requires manage_options

Searches the wp_options table by name, so you can find the settings key of ANY plugin or theme (for example search "woocommerce" or "yoast"). Returns names and sizes only.

get_option_value#

Read an option · read · on by default · requires manage_options

Reads any option by exact name, which is how plugin and theme settings are stored. Values that look like secrets (keys, tokens, passwords) are masked unless reveal is true.

update_option_value#

Write an option · write · off by default (high impact) · requires manage_options

Writes a plugin or theme setting. Value can be text, number, boolean, array or object. With merge true an object is merged into the existing array option instead of replacing it. Site URL, active plugins, user roles and HelperMCP's own settings are protected.

delete_option_value#

Delete an option · guarded · off by default (high impact) · requires manage_options

Deletes an option. Protected options cannot be deleted.

get_theme_mods#

Get theme settings · read · on by default · requires edit_theme_options

Customizer and theme settings (theme mods) of the active theme, or of another theme by folder name.

set_theme_mod#

Set a theme setting · write · off by default (high impact) · requires edit_theme_options

Sets one Customizer/theme setting. Use get_theme_mods first to see the keys.

Maintenance & cache#

4 tools, 3 on by default.

clear_cache#

Clear caches · write · on by default · requires manage_options

Flushes the object cache and expired transients and asks every common caching plugin (WP Rocket, LiteSpeed, W3 Total Cache, WP Super Cache, Autoptimize, WP Fastest Cache, SG Optimizer, Cloudflare) to purge itself.

No parameters.

flush_rewrite_rules#

Flush permalinks · write · on by default · requires manage_options

Regenerates rewrite rules. Fixes 404 errors on custom post types after a plugin change.

No parameters.

list_cron_events#

List scheduled tasks · read · on by default · requires manage_options

WP-Cron events with hook, next run time and recurrence. Helps spot stuck or missing jobs.

run_cron_hook#

Run a scheduled task now · write · off by default (high impact) · requires manage_options

Runs a hook that is already scheduled in WP-Cron immediately, once.

Diagnostics & error finder#

3 tools, 3 on by default.

diagnose_errors#

Find and explain PHP errors · read · on by default · requires manage_options

THE tool to start with when something is broken. Reads the WordPress debug log and WordPress's own list of paused plugins/themes, groups the errors, and for each one reports the type, message, the exact file and line, whether it belongs to a plugin, theme or core (and which), the surrounding source code, a plain-language likely cause and a suggested fix. If the debug log is missing it says how to switch it on. Follow up with read_file and patch_file to apply the fix.

get_debug_log#

Read the debug log · read · on by default · requires manage_options

The tail of the WordPress debug log (wp-content/debug.log or the configured path), optionally filtered by a search string.

get_site_health#

Site health report · read · on by default · requires manage_options

PHP and WordPress versions, memory limit, key PHP extensions, debug constants, database version, writable folders, HTTPS, cron state, active theme and plugin counts, paused plugins and pending updates. Quick overview before troubleshooting.

No parameters.

Plugin & theme files (developer)#

8 tools, 0 on by default.

list_files#

List files · read · off by default (high impact) · requires manage_options

Lists files and folders inside a plugin, theme or the site (read-only).

read_file#

Read a file · read · off by default (high impact) · requires manage_options

Reads a source file with line numbers. Use start_line and end_line to read just the part an error points at.

search_files#

Search inside files · read · off by default (high impact) · requires manage_options

Searches file contents in a plugin, theme or the site for a string or regex, returning file, line and text. Use it to find where a function, hook or option is defined or used.

lint_file#

Check PHP syntax · read · off by default (high impact) · requires manage_options

Checks a PHP file for syntax errors and reports the line.

patch_file#

Fix a file (find and replace) · write · off by default (high impact) · requires edit_plugins

Edits a plugin or theme file with exact find/replace edits, the safest way to apply a fix. PHP is syntax-checked first, the original is backed up, and the change is rolled back automatically if the site breaks. Use dry_run to preview. A find that matches more than once is refused unless all is true.

write_file#

Write or create a file · write · off by default (high impact) · requires edit_plugins

Replaces a file's full contents or creates a new one in a plugin or theme. Same protections as patch_file: syntax check, backup, automatic rollback. Prefer patch_file for fixes.

list_backups#

List file backups · read · off by default (high impact) · requires manage_options

Backups HelperMCP made before changing files, newest first.

restore_backup#

Restore a file backup · write · off by default (high impact) · requires edit_plugins

Puts a file back exactly as it was before a change.

REST API bridge (any plugin)#

2 tools, 0 on by default.

list_rest_routes#

Discover REST API routes · read · off by default (high impact) · requires edit_posts

Lists REST API routes registered by WordPress and by every active plugin (WooCommerce, ACF, forms, LMS, anything). Search by text or namespace to find the endpoint for a plugin, then call it with rest_request.

rest_request#

Call any REST API route · write · off by default (high impact) · requires edit_posts

Calls any WordPress REST API route internally AS THE CONNECTED USER, so it works with every plugin that has a REST API, and always respects that plugin's own permission checks. For GET pass params as the query. For POST/PUT/PATCH/DELETE pass body fields in body.

Database (read-only)#

2 tools, 0 on by default.

list_db_tables#

List database tables · read · off by default (high impact) · requires manage_options

Tables in the WordPress database with row counts and size. Includes tables created by any plugin.

db_query#

Run a read-only SQL query · read · off by default (high impact) · requires manage_options

Runs ONE read-only query (SELECT, SHOW, DESCRIBE, EXPLAIN). Use {prefix} for the table prefix, e.g. SELECT * FROM {prefix}posts WHERE post_status = 'draft'. Capped at 200 rows. Password hashes, session tokens and HelperMCP tokens cannot be queried.

Control: approvals & restore points#

6 tools, 6 on by default.

check_approval#

Check an approval request · read · on by default · requires edit_posts

When a tool answers "approval_required", the site owner must approve it in wp-admin. Call this with the approval_id to see whether it is pending, approved (with the tool's result), denied, expired or failed. Do not retry the original call, wait for the answer.

list_approvals#

List my approval requests · read · on by default · requires edit_posts

Your own recent approval requests and their status.

create_restore_point#

Create a restore point · write · on by default · requires edit_posts

Saves the CURRENT state of the listed posts and/or options so you can roll back after a risky change. Restore points are also taken automatically before bulk updates, site-wide replace and settings changes.

list_restore_points#

List restore points · read · on by default · requires edit_posts

Recent restore points with what they cover, newest first.

restore_restore_point#

Roll back to a restore point · write · on by default · requires edit_posts

Puts the posts and options in a restore point back exactly as they were (content, title, status, terms, SEO fields, featured image, options). Needs confirm true.

delete_restore_point#

Delete a restore point · guarded · on by default · requires manage_options

Deletes a restore point permanently.

Security scan#

6 tools, 4 on by default.

security_scan#

Security scan · read · on by default · requires manage_options

Reviews the site for security problems and returns prioritised findings with fix hints. Checks (all except recent_changes by default, ask for that one explicitly): core_integrity (official checksums), uploads_php (PHP files in uploads), suspicious_code (backdoor and obfuscation patterns in plugins, themes, uploads), recent_changes (PHP files changed lately), users (administrator accounts), config (debug exposure, XML-RPC, file editor, permissions, PHP/WordPress versions), plugins (abandoned or outdated plugins). Findings are indicators to review, not proof of infection.

verify_core_files#

Verify WordPress core files · read · on by default · requires manage_options

Compares wp-admin and wp-includes against the official WordPress.org checksums for this version and lists modified, missing and unexpected files. Needs outbound access to api.wordpress.org.

No parameters.

verify_plugin_files#

Verify a plugin's files · read · on by default · requires manage_options

Compares an installed WordPress.org plugin with the official checksums for its exact version and lists modified, missing and added files. Does not work for premium or custom plugins.

quarantine_file#

Quarantine a suspicious file · write · off by default (high impact) · requires manage_options

Moves a file out of wp-content into a protected quarantine folder (reversible with restore_quarantined). Only files under wp-content can be quarantined, never core files, wp-config or HelperMCP. Needs confirm true.

list_quarantine#

List quarantined files · read · on by default · requires manage_options

Files HelperMCP has quarantined.

No parameters.

restore_quarantined#

Restore a quarantined file · write · off by default (high impact) · requires manage_options

Moves a quarantined file back to its original location.

Performance#

4 tools, 2 on by default.

performance_audit#

Performance audit · read · on by default · requires manage_options

Finds what is slowing the site down from the inside: autoloaded options bloat (with the plugin that owns the biggest ones), expired transients, post revisions, auto-drafts, trash, spam, orphaned custom fields, biggest database tables, cache and PHP configuration, overdue scheduled tasks. Returns prioritised recommendations. Follow with cleanup_database and set_option_autoload to fix.

No parameters.

measure_page#

Measure a page · read · on by default · requires manage_options

Requests a page on this site and reports response time, HTML size, compression, caching headers, how many scripts, stylesheets and images it loads, render-blocking scripts in the head, images missing dimensions or lazy-loading, and the heaviest images. Defaults to the homepage. Only this site's own URLs are allowed.

cleanup_database#

Clean up the database · write · off by default (high impact) · requires manage_options

Removes clutter. actions: expired_transients, revisions (keeps the newest keep_revisions per post), auto_drafts (older than 7 days), trashed_posts (older than older_than_days), spam_comments, trashed_comments, orphan_postmeta, oembed_cache, optimize_tables. dry_run defaults to TRUE and just counts. Applying needs dry_run false and permanent deletion enabled in HelperMCP settings. Take a backup first (create_db_backup).

set_option_autoload#

Change an option's autoload · write · off by default (high impact) · requires manage_options

Stops a large option from loading on every page request (autoload false) or turns it back on. The standard fix for autoload bloat found by performance_audit. Does not change the option's value.

Image optimisation#

5 tools, 2 on by default.

image_audit#

Audit the image library · read · on by default · requires upload_files

Scans the media library for heavy images (over 500 KB), oversized dimensions (wider than 2560 px), missing alt text and format mix, with an estimate of how much could be saved. Run before optimize_images.

optimize_images#

Compress and resize images · write · off by default (high impact) · requires upload_files

Resizes images wider than max_width and re-compresses JPEG/PNG/WebP, keeping the original format and URLs. Originals are backed up (restore_image undoes it). dry_run defaults to TRUE and reports the savings without changing anything. Processes up to 25 images per call.

restore_image#

Restore an original image · write · off by default (high impact) · requires upload_files

Puts back the original file saved before optimize_images or convert_to_webp.

convert_to_webp#

Convert an image to WebP · write · off by default (high impact) · requires upload_files

Converts one JPEG/PNG attachment to WebP (smaller files, same quality) and optionally rewrites its URLs inside post content and Elementor data so nothing breaks. A restore point of the affected posts is taken first, and the original file is kept in a backup. dry_run defaults to TRUE and lists the posts that would be edited.

bulk_fix_alt_text#

Fill missing alt text in bulk · write · on by default · requires upload_files

Finds library images with no alt text and fills them from the title of the post they are attached to, or a cleaned-up file name. Never overwrites existing alt text. dry_run defaults to TRUE.

Redirects, 404s & broken links#

11 tools, 11 on by default.

list_redirects#

List redirects · read · on by default · requires edit_posts

Redirect rules with source, target, type, hit count and last hit.

create_redirect#

Create a redirect · write · on by default · requires manage_options

Creates a redirect rule. source is a path on this site such as /old-page (or a regex when regex is true, e.g. ^/blog/(\d+)/ with target /news/$1). target is a path or full URL. Refuses duplicates, self-redirects and obvious loops.

update_redirect#

Edit a redirect · write · on by default · requires manage_options

Changes a redirect's target, type, active state or note.

delete_redirect#

Delete a redirect · guarded · on by default · requires manage_options

Deletes a redirect rule. Needs confirm true.

import_redirects#

Import redirects · write · on by default · requires manage_options

Imports many rules from CSV text, one per line: source,target[,type[,regex]]. dry_run defaults to TRUE and validates without saving. Up to 500 lines.

test_redirect#

Test where a URL goes · read · on by default · requires edit_posts

Shows which rule matches a path and follows the chain to the final destination, flagging loops and long chains.

list_404s#

List 404 errors · read · on by default · requires edit_posts

URLs visitors and bots requested that do not exist, most frequent first, with last referrer and whether a redirect already exists.

suggest_redirect#

Suggest where a 404 should go · read · on by default · requires edit_posts

Finds the best existing page for a missing URL by slug and title similarity (and WordPress's record of previous slugs). Returns candidates with confidence scores.

fix_404s#

Auto-fix 404s with redirects · write · on by default · requires manage_options

For the most-hit 404 URLs, creates a 301 to the best matching page when the match confidence is at least min_score (0 to 1, default 0.8). dry_run defaults to TRUE and lists what it would create.

clear_404_log#

Clear the 404 log · guarded · on by default · requires manage_options

Empties the 404 log.

scan_broken_links#

Scan posts for broken links · read · on by default · requires edit_posts

Checks every link in the given posts (or the most recent published ones) and reports broken links (404/410/5xx/timeouts) and redirected links, each with its link_index so replace_link or remove_link can fix it. Checks up to 40 distinct URLs per call.

Schema, robots.txt & sitemap#

8 tools, 6 on by default.

get_post_schema#

Get a page's structured data · read · on by default · requires edit_posts

Shows every JSON-LD block a published page outputs (from the SEO plugin, theme and HelperMCP) with the schema types found, plus HelperMCP's own custom schema for the post. Use it to see what is missing or duplicated.

set_custom_schema#

Add structured data to a post · write · on by default · requires edit_posts

Adds JSON-LD schema (FAQPage, Product, Recipe, Event, LocalBusiness, HowTo, VideoObject, Article and more) to a post. It is printed in the page head. replace true overwrites existing custom schema, otherwise nodes are added. Run validate_schema first. Avoid adding a type the SEO plugin already outputs, check get_post_schema.

remove_custom_schema#

Remove custom structured data · write · on by default · requires edit_posts

Removes HelperMCP custom schema from a post (all of it, or just one @type).

validate_schema#

Validate structured data · read · on by default · requires edit_posts

Checks JSON-LD for required and recommended properties for common types (Article, FAQPage, Product, Recipe, Event, LocalBusiness, Organization, HowTo, VideoObject, BreadcrumbList, WebSite, Person, JobPosting, Review). Pass schema directly, or post_id to check what is saved. This is a quick local check, not Google's Rich Results Test.

get_robots_txt#

Read robots.txt · read · on by default · requires manage_options

The robots.txt crawlers actually receive, and where it comes from (a physical file, WordPress's virtual file, or an SEO plugin), plus warnings.

No parameters.

set_robots_txt#

Write robots.txt · write · off by default (high impact) · requires manage_options

Sets robots.txt. If a physical robots.txt file exists it is backed up and overwritten, otherwise the content is stored and served as the virtual robots.txt (overriding SEO plugin editors). Blocks a rule that would disallow the entire site unless allow_block_all is true.

reset_robots_txt#

Reset robots.txt · write · off by default (high impact) · requires manage_options

Removes HelperMCP's stored robots.txt so WordPress or your SEO plugin serves its default again.

No parameters.

get_sitemap_info#

Inspect the XML sitemap · read · on by default · requires edit_posts

Finds the sitemap (WordPress core, Yoast, Rank Math, AIOSEO, SEOPress, others), lists the child sitemaps with URL counts, and checks that robots.txt points to it.

No parameters.

Block theme (templates & styles)#

8 tools, 5 on by default.

list_block_templates#

List block templates · read · on by default · requires edit_theme_options

Templates or template parts of the active block theme (home, single, page, archive, header, footer ...), showing whether each is the theme's original or has been customised.

get_block_template#

Read a block template · read · on by default · requires edit_theme_options

The block markup of one template or template part. id is theme//slug as shown by list_block_templates.

update_block_template#

Edit a block template · write · off by default (high impact) · requires edit_theme_options

Saves new block markup for a template or template part as a user customisation (the theme file is untouched). A restore point is taken first. Pass the COMPLETE markup. Reverse it with reset_block_template.

reset_block_template#

Reset a template to the theme default · guarded · off by default (high impact) · requires edit_theme_options

Deletes the user customisation so the theme's original template is used again. For custom templates that have no theme file this deletes the template. Needs confirm true.

list_block_patterns#

List block patterns · read · on by default · requires edit_posts

Registered patterns (theme, core and plugin) and the site's own saved patterns/reusable blocks.

create_block_pattern#

Create a block pattern · write · on by default · requires edit_theme_options

Saves a reusable pattern from block markup. sync true makes it a synced pattern (edits update everywhere), default false (a copy is inserted).

get_theme_json#

Read theme.json (merged) · read · on by default · requires edit_theme_options

The merged theme.json settings and styles in effect (core defaults, theme, and user global styles): colour palette, typography, spacing, layout. Pass path to read one section, e.g. settings.color.palette.

update_global_styles#

Change global styles · write · off by default (high impact) · requires edit_theme_options

Merges a patch into the user's Global Styles (what the Site Editor > Styles screen changes): colours, fonts, spacing, layout, per-block styles. Example patch: {"settings":{"color":{"palette":{"custom":[...]}}},"styles":{"color":{"background":"#fff"}}}. A restore point is taken first. Invalid values are dropped by WordPress.

Backups & core updates#

6 tools, 3 on by default.

get_backup_status#

Backup status · read · on by default · requires manage_options

Whether a recent database backup exists (HelperMCP's own), and which backup plugins are installed (UpdraftPlus, BackWPup, Duplicator, WPvivid, Solid Backups, Jetpack, All-in-One WP Migration, BlogVault).

No parameters.

create_db_backup#

Back up the database · write · on by default · requires manage_options

Exports every table with this site's prefix to a gzip SQL file in a protected folder (wp-content/uploads/helpermcp/dbbackups). Fast and safe, and required before update_core. Keeps the newest 5. Does not include files or media.

list_db_backups#

List database backups · read · on by default · requires manage_options

Backups HelperMCP has made, with size and date, and how to restore them.

No parameters.

delete_db_backup#

Delete a database backup · guarded · off by default (high impact) · requires manage_options

Deletes one backup file permanently.

run_backup_plugin#

Run the backup plugin · write · off by default (high impact) · requires manage_options

Starts a full backup (files and database) with the installed backup plugin. Currently supported: UpdraftPlus. For other plugins it reports what is installed so you can run it from wp-admin.

No parameters.

update_core#

Update WordPress core · write · off by default (high impact) · requires manage_options

Updates WordPress to the latest (or a given) version. Refuses unless a HelperMCP database backup from the last 24 hours exists, or backup_confirmed is true (you have a full backup elsewhere). Health-checks the site afterwards. WordPress finishes the database upgrade the next time wp-admin is opened.

11. Writing addons#

An addon is any PHP code that registers extra tools with HelperMCP. A connected AI then sees and uses your tools exactly like the built-in ones, and the site owner can switch each one on or off.

You can ship an addon as:

• A normal WordPress plugin (recommended): installable, updatable, can depend on its own code.
• A drop-in file in wp-content/helpermcp-addons/ (my-addon.php or my-addon/addon.php) for quick site-specific tools. Loaded when the setting Load addon files from the drop-in folder is on.

Addons run as PHP with full access, exactly like any plugin. Only install code you trust.

11.1 Minimal addon (plugin)#

<?php
/**
 * Plugin Name: My HelperMCP Addon
 * Version: 1.0.0
 */
if ( ! defined( 'ABSPATH' ) ) exit;

add_action( 'helpermcp_register_addons', function () {

    helpermcp_register_addon( [
        'slug'         => 'my-addon',
        'name'         => 'My Addon',
        'version'      => '1.0.0',
        'author'       => 'You',
        'description'  => 'Lets the AI manage widgets.',
        // Optional text added to the AI's briefing when it connects:
        'instructions' => 'Use widgets_list before widgets_update. Widget names are unique.',
    ] );

    helpermcp_register_tool( [
        'addon'       => 'my-addon',
        'name'        => 'widgets_list',
        'title'       => 'List widgets',
        'description' => 'Lists every widget with its ID, name and status.',
        'mode'        => 'read',
        'capability'  => 'edit_posts',
        'properties'  => [
            'status' => [ 'type' => 'string', 'enum' => [ 'active', 'archived' ], 'description' => 'Filter by status.' ],
        ],
        'required'    => [],
        'callback'    => function ( array $args ) {
            $widgets = my_addon_query_widgets( $args['status'] ?? 'active' );
            return [ 'widgets' => $widgets, 'count' => count( $widgets ) ];
        },
    ] );
} );

That is all. The tool appears on HelperMCP > Tools (group Addons) and in the Addons tab.

11.2 Tool definition reference#

Pass an array to helpermcp_register_tool():

11.3 Callback rules#

• The callback runs as the token's WordPress user (get_current_user_id() is set). Capability checks like current_user_can( 'edit_post', $id ) work as normal. Always check object-level capabilities for the specific item, not only the global capability.
• Return an array (becomes the JSON result), or any scalar (wrapped as {"result": ...}).
• Return a WP_Error or throw an exception to report a failure. The message is shown to the AI with isError: true. Write messages the AI can act on: say what was wrong and what to do instead.
• Validate and sanitize every argument. Treat all input as untrusted.
• Keep responses reasonably small (a few KB to tens of KB). Paginate large lists with limit and page arguments.
• Do not rely on globals set during page rendering; this is a REST request.

11.4 Writing good schemas#

• Use JSON Schema types: string, integer, number, boolean, array, object.
• Add description to every property, include formats ("YYYY-MM-DD") and units.
• Use enum for fixed choices.
• Accept IDs and human-friendly values where it helps ("category ID or name").
• Name destructive confirmations explicitly (confirm), as the built-in tools do.

'properties' => [
    'order_id' => [ 'type' => 'integer', 'description' => 'WooCommerce order ID.' ],
    'status'   => [ 'type' => 'string', 'enum' => [ 'processing', 'completed', 'cancelled' ] ],
    'note'     => [ 'type' => 'string', 'description' => 'Optional private note added to the order.' ],
],
'required' => [ 'order_id', 'status' ],

11.5 Full example: WooCommerce order addon#

<?php
/**
 * Plugin Name: HelperMCP for Orders
 * Version: 1.0.0
 */
if ( ! defined( 'ABSPATH' ) ) exit;

add_action( 'helpermcp_register_addons', function () {
    if ( ! function_exists( 'wc_get_order' ) ) return; // WooCommerce not active

    helpermcp_register_addon( [
        'slug' => 'orders', 'name' => 'Orders', 'version' => '1.0.0',
        'instructions' => 'Confirm with the person before changing an order status.',
    ] );

    helpermcp_register_tool( [
        'addon' => 'orders', 'name' => 'orders_recent', 'title' => 'Recent orders', 'mode' => 'read',
        'description' => 'Lists the most recent WooCommerce orders with total, status and customer name.',
        'capability'  => 'edit_shop_orders',
        'properties'  => [ 'limit' => [ 'type' => 'integer', 'description' => 'Default 10, max 50.' ] ],
        'callback'    => function ( $a ) {
            $orders = wc_get_orders( [ 'limit' => min( 50, max( 1, (int) ( $a['limit'] ?? 10 ) ) ), 'orderby' => 'date', 'order' => 'DESC' ] );
            return [ 'orders' => array_map( fn( $o ) => [
                'id' => $o->get_id(), 'status' => $o->get_status(), 'total' => $o->get_total(),
                'customer' => trim( $o->get_billing_first_name() . ' ' . $o->get_billing_last_name() ),
                'date' => $o->get_date_created() ? $o->get_date_created()->date( 'Y-m-d H:i' ) : null,
            ], $orders ) ];
        },
    ] );

    helpermcp_register_tool( [
        'addon' => 'orders', 'name' => 'orders_set_status', 'title' => 'Change order status', 'mode' => 'write', 'risky' => true,
        'description' => 'Changes a WooCommerce order status and optionally adds a private note.',
        'capability'  => 'edit_shop_orders',
        'properties'  => [
            'order_id' => [ 'type' => 'integer' ],
            'status'   => [ 'type' => 'string', 'enum' => [ 'processing', 'completed', 'cancelled', 'on-hold' ] ],
            'note'     => [ 'type' => 'string' ],
        ],
        'required'    => [ 'order_id', 'status' ],
        'callback'    => function ( $a ) {
            $order = wc_get_order( (int) $a['order_id'] );
            if ( ! $order ) return new WP_Error( 'not_found', 'Order not found. Use orders_recent to find valid IDs.' );
            if ( ! current_user_can( 'edit_shop_order', $order->get_id() ) ) return new WP_Error( 'forbidden', 'Your user cannot edit this order.' );
            $order->update_status( sanitize_key( $a['status'] ), sanitize_text_field( $a['note'] ?? '' ) );
            return [ 'order_id' => $order->get_id(), 'status' => $order->get_status(), 'message' => 'Order status updated.' ];
        },
    ] );
} );

You may not need an addon at all. list_rest_routes and rest_request already let the AI call any plugin's REST API (WooCommerce's /wc/v3/orders, for example) as the connected user, and list_options / get_option_value read any plugin's settings. Write an addon when you want a tighter, safer, better-described interface than raw REST, or when the plugin has no REST API.

11.6 Drop-in addons#

Create wp-content/helpermcp-addons/ and add a PHP file. It is loaded early (on plugins_loaded), so register on the same helpermcp_register_addons action:

<?php
// wp-content/helpermcp-addons/site-tools.php
add_action( 'helpermcp_register_addons', function () {
    helpermcp_register_addon( [ 'slug' => 'site-tools', 'name' => 'Site Tools' ] );
    helpermcp_register_tool( [
        'addon' => 'site-tools', 'name' => 'sitetools_ping', 'mode' => 'read',
        'description' => 'Returns pong and the server time.',
        'callback' => fn() => [ 'pong' => true, 'time' => current_time( 'mysql' ) ],
    ] );
} );

Loaded files are listed on HelperMCP > Addons. A file with a fatal error is reported there; a syntax error in a drop-in will still break the request like any plugin, so test it first. Turn the folder loading off with the Addons tab toggle.

11.7 Registration timing#

• Register inside the helpermcp_register_addons action. It fires once per request, the first time the tool list is built.
• Alternatively add to the helpermcp_register_tools filter, which receives and returns the array of tool definitions.
• Tools registered after the list has been built in the current request are not included.

11.8 Naming, versioning and distribution#

• Prefix tool names with a short unique addon prefix (orders_, acme_).
• Never rename a published tool; the AI's saved prompts and playbooks may reference it. Add a new tool and deprecate the old one in its description.
• Put risky => true on anything that spends money, sends email, changes configuration or deletes data.
• Document every tool's arguments in its schema, not in a readme: the schema is what the AI reads.
• Declare Requires Plugins: helpermcp in your plugin header (WordPress 6.5+) or check function_exists( 'helpermcp_register_tool' ) before registering.

11.9 Testing your addon#

List tools:

curl -s https://SITE/wp-json/helpermcp/v1/mcp -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call your tool:

curl -s https://SITE/wp-json/helpermcp/v1/mcp -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"widgets_list","arguments":{"status":"active"}}}'

Checklist:

• The tool appears under HelperMCP > Tools > Addons and is on (or off if risky).
• A token for a user without your capability is refused.
• Bad arguments return a clear message, not a PHP notice.
• Large results are paginated.
• Nothing in the result leaks secrets (API keys, password hashes).

11.10 Addon security checklist#

• Set the narrowest capability that makes sense, then check object-level capabilities inside the callback.
• Sanitize input, escape output, use $wpdb->prepare().
• Never accept raw PHP, SQL or shell commands from arguments.
• Never write outside the directories your plugin owns.
• Mark destructive or costly tools risky and require a confirm argument.
• Do not store tokens or keys in tool results.

12. Hooks and filters reference#

Functions:

Example: log every tool call to your own system:

add_action( 'helpermcp_after_tool', function ( $tool, $args, $result ) {
    error_log( sprintf( 'HelperMCP %s by user %d', $tool, get_current_user_id() ) );
}, 10, 3 );

13. MCP protocol reference#

• Endpoint: POST /wp-json/helpermcp/v1/mcp (Streamable HTTP, single JSON response per request).
• Protocol version: 2025-06-18.
• Auth: Authorization: Bearer <token> or ?token=<token>. Every method except ping and notifications/* requires a valid token, including initialize (its briefing contains your pinned playbooks).
• Capabilities: tools and resources. GET and DELETE return 405 (no server-initiated stream).

Methods#

Errors#

Authentication failures also set the HTTP status: 401 invalid, missing, revoked or expired token (with a WWW-Authenticate header pointing at the OAuth metadata when OAuth is on), 403 IP not allowed or user no longer permitted, 429 rate limit reached (with Retry-After). Everything else answers 200.

Tool failures are returned as a normal result with isError: true and a plain-language message, so the AI can read it and recover.

14. Hardening checklist#

• Serve the site over HTTPS only.
• Use a dedicated WordPress user for the connection, with the lowest role that does the job (Editor for content work). Reserve Administrator tokens for site-management work.
• Leave Allow permanent deletion off unless needed.
• Leave the files, database, REST bridge, plugins, themes, users tools off until you need them, then turn them off again.
• Give each app the narrowest access level, set an expiry, and add an IP allowlist and rate limit where you can (section 8.1).
• Consider the approval gate on "High-impact" while you build trust (section 8.3).
• Prefer OAuth or the Authorization header over ?token=; query strings can appear in server logs.
• Revoke tokens you are not using (Connect tab). Tokens are hashed at rest.
• Add define( 'DISALLOW_FILE_EDIT', true ); if you never want file editing through any route.
• Block direct web access to /wp-content/uploads/helpermcp/ on Nginx.
• Review Activity regularly.
• Keep backups. HelperMCP backs up files it edits and can export the database, but it is not a full backup solution. Copy database backups off the server.

15. FAQ#

Does this replace my SEO plugin? No. It writes through it. Without an SEO plugin, HelperMCP outputs basic tags itself.

Will it publish things by itself? Not unless you allow it. New content is a draft by default, and the AI is instructed to publish only when you ask.

Can it break my site? It can change what you let it. High-impact tools start off, file edits are syntax-checked and rolled back if the site errors, and plugin/theme switches are health-checked. Keep your own backups regardless.

Why can't it update itself? Changing the plugin that serves the connection mid-request is risky. Update HelperMCP from wp-admin.

It says a tool is switched off. Enable it under HelperMCP > Tools.

Install or update says it needs FTP credentials. Your server cannot write files directly as the web user, or DISALLOW_FILE_MODS is set. WordPress itself cannot install plugins there either.

The health check says it could not run. Your host blocks loopback requests. Tools still work, but check the site manually after risky changes.

Does it work with WooCommerce, Elementor, ACF and so on? Yes through rest_request (any plugin with a REST API), list_options (any plugin's settings), custom field tools (ACF aware) and diagnose_errors for any plugin's PHP errors. Write an addon for a dedicated interface.

What has been tested? Every tool group was exercised against a real WordPress install, including live HTTP checks for redirects, 404 logging, robots.txt, schema output, the OAuth flow, token scopes, rate limits and automatic rollback. Not verifiable in the test environment, so try them on staging first: anything that needs WordPress.org (plugin and theme install, directory search, core and plugin checksums, core updates), the UpdraftPlus trigger, All in One SEO writes, SQL backup structure export on your MySQL/MariaDB version, and OAuth with your specific connector.

What can I undo? Posts and options changed by bulk or settings tools (restore points), files edited through HelperMCP (file backups), quarantined files, optimised images (originals kept) and block template edits. You cannot undo permanent deletions, database clean-up or plugin deletions, which is why those need confirmation and a backup first.

Is the security scan a real malware scanner? No. It surfaces suspicious patterns and risky settings for review. It is a good first pass and a way to catch obvious backdoors, not a replacement for a dedicated security service.

OAuth connect fails at the discovery step. Your server or CDN is probably not passing /.well-known/ to WordPress, or permalinks are plain. Open https://YOUR-SITE/.well-known/oauth-authorization-server in a browser, you should see JSON.

Multisite? Not specifically tested. Network-level plugin and theme management is not provided.

16. Changelog#

1.2.5#

• Access control: token scopes (Content & SEO, Read-only, Custom), expiry, IP allowlist, rate limits.
• OAuth sign-in for connectors with PKCE, dynamic client registration and rotating refresh tokens.
• Approval gate for high-impact or all changes; restore points with automatic snapshots; Control tab.
• Security scan, core and plugin checksum verification, file quarantine.
• Performance audit, page measurement, database clean-up, autoload fixes.
• Image audit, compression, WebP conversion with URL rewriting, bulk alt text.
• Redirect engine, 404 log with auto-fix suggestions, broken-link scanner.
• Structured data (JSON-LD) tools, robots.txt and sitemap tools.
• Block theme tools: templates, patterns, theme.json, global styles.
• Database backups, UpdraftPlus trigger, backup-gated core updates.

1.2.4#

• Plugin and theme management: list, search directory, install, activate, deactivate, update, delete, auto-updates, with health check and automatic rollback.
• Site settings: name, tagline, logo, favicon, language, timezone, formats, front page, permalinks, visibility, comments, registration. Any plugin's options (masked secrets) and theme settings.
• Developer tools: error finder, debug log, site health, file read/search/lint/patch/write with backups and rollback, read-only database, REST bridge.
• Menus, comments, users, cache and cron tools.
• Per-tool and per-group on/off switches; high-impact tools default off.
• Addon API with drop-in loader and developer hooks.

1.2.3#

• First standalone release, extracted from HelperSEO: posts, pages, custom post types, media, taxonomies, links, custom fields, site-wide replace, SEO through any SEO plugin, Markdown playbooks, tokens, activity log.