Pro module20 abilities
Spectra
These abilities register when Spectra is detected on the site and a Pro licence is active. If either is missing the module stays absent rather than failing at call time.
At a glance
Spectra registers 20 abilities: 10 that only read, 4 that write, and 6 marked destructive. That split is the practical answer to how much of this module can run unattended. Reads cost nothing and are safe to repeat, so discovery is the part to be generous with; the writes are where review belongs, and the destructive calls stop for an explicit confirmation every single time regardless of which profile is active.
What this module is for
Discover Spectra blocks and schemas, manage activation and editor settings, inspect form blocks, and operate Pro popup workflows when the extension is present.
Before you rely on it: Treat popup activation and display conditions as production-impacting changes that require audience checks.
Typical workflows
- Audit active blocks before standardizing an editor setup
- Inspect a form block before changing its fields
- Review popup conditions before enabling a campaign
The Spectra integration page covers the same module from the workflow side, with the capability map and the questions worth asking before a first write.
Availability on your site
The Spectra module needs three things at once: WPPilot Free as the MCP foundation, an active Pro licence, and the companion plugin detected on the site. Miss any one and the module does not register, which is deliberate: an ability that appears in the tool list but fails at call time is worse than an ability that was never offered. What the connected agent can actually call is then narrowed twice more: by the safety profile active on the site, and by the WordPress capabilities of the user behind the credential. A read that succeeds for an administrator can be absent entirely for an editor.
Every write these abilities perform is recorded in the change ledger, and destructive calls can be routed through the approval queue so a person signs off before anything is applied. A successful tool result means the operation returned, not that the front end, the cache, and every dependent template are correct: that still needs a look.
Reads
Available in every safety profile, including Read Only. Inspection costs nothing and is not rate limited.
| Ability | What it does |
|---|---|
wppilot/spectra-check-setupCheck Spectra Setup | Returns the Spectra (UAGB / Ultimate Addons for Gutenberg) runtime state in one call: plugin active, version, min-supported, min-satisfied; Spectra Pro add-on active + version + min-satisfied; block registry counts (free + pro); popup count; UAGB form-block usage count. Call this BEFORE any other Spectra ability — every other call is gated on plugin.active && plugin.min_satisfied, and Pro-only abilities additionally require pro.active && pro.min_satisfied. |
wppilot/spectra-get-block-schemaGet Spectra Block Schema | Return the attribute schema of a single Spectra block (name = uagb/xxx or spectra-pro/xxx). Output includes the block title, category, family (free|pro), whether it renders via PHP (dynamic_render), the supports map, and the full attributes map. Use wppilot/spectra-list-blocks first to pick a name, or after check-setup to inspect a specific block. |
wppilot/spectra-get-popupGet Spectra Popup | Read a single Spectra Popup Builder post (spectra-popup CPT) in full: title, status, slug, content (block markup, byte-capped by default), full meta bundle (popup_type, enabled, repetition), modified timestamp. Use max_field_bytes to override the 20_000-byte content cap (0 disables truncation). Progressive-disclosure counterpart of wppilot/spectra-list-popups. |
wppilot/spectra-get-settingsGet Spectra Settings | Read the current Spectra plugin settings — editor UX toggles (uag_enable_*), container defaults, Google Fonts hosting mode, and reCAPTCHA site-key presence. Values are returned as a flat map. reCAPTCHA SECRET keys are NEVER echoed; only a recaptcha.has_secret_v2 / has_secret_v3 boolean flag is exposed. Whitelist-only — settings outside the map are not read here (use wppilot/execute-php for one-off reads of niche keys). |
wppilot/spectra-list-blocksList Spectra Blocks | Enumerate the Spectra blocks registered with WordPress. Returns compact records (name, family free|pro, category, dynamic_render, title). Filters: family (free|pro|all — default all), name_contains (substring match on the block name; case-insensitive), category (exact match on the block editor category). Progressive-disclosure: use wppilot/spectra-get-block-schema for the full attribute schema of a specific block. |
wppilot/spectra-list-form-blocksList Spectra Form Blocks | Locate posts / pages that contain at least one Spectra uagb/forms block. Returns compact records (id, title, status, post_type, form_count) so an agent can pick a target for edit-block via wppilot/gutenberg-*. Bounded LIKE query with a hard 500-row cap and a truncated flag — the ability never scans the entire posts table on production stores. UAGB Free does NOT persist form submissions; use wppilot/execute-php + the uagb_form_success action hook for that surface. |
wppilot/spectra-list-google-fontsList Spectra Google Fonts | Enumerate the Google Fonts Spectra currently loads globally. Merges three UAGB sources: uag_select_font_globally (Settings → Global Fonts), spectra_gbs_google_fonts (per-Global-Block-Style fonts), and spectra_global_fse_fonts (FSE theme.json bridge). Each record reports source. Also returns the three delivery-mode flags — loaded_locally, preload_local, load_fse_globally — so an agent can distinguish "not loaded" from "loaded remotely". |
wppilot/spectra-list-popupsList Spectra Popups | Enumerate Spectra Popup Builder posts (spectra-popup CPT) as compact records: id, title, status, popup_type (modal|slide-in|banner|…), enabled (bool), modified. Filters: status (WP post_status; default: publish+draft+private), enabled (bool), popup_type (exact match), search (title substring). Progressive-disclosure: use wppilot/spectra-get-popup for full content and full meta (Sprint 2). |
wppilot/spectra-pro-check-setupCheck Spectra Pro Setup | Returns the Spectra Pro (spectra-pro/spectra-pro.php) runtime state: plugin active, version, min-supported, min-satisfied, plus the Spectra Pro license status. Call this BEFORE any other wppilot/spectra-pro-* ability. Every Pro ability additionally gates on plugin.active && plugin.min_satisfied at registration time (they are not loaded when the gate fails), so this call is only reached when Pro is at or above the supported floor. |
wppilot/spectra-pro-list-popup-conditionsList Spectra Pro Popup Conditions | Read the Spectra Pro display-condition bundle for one popup: trigger (open trigger — click, scroll, exit-intent, time-delay), trigger_delay (seconds), display_inclusions (where the popup MAY appear — page targets), and display_exclusions (where it MUST NOT appear). All four keys are the meta rows the Spectra Pro popup extension (Spectra_Pro_Popup_Builder::register_pro_meta()) writes on the free spectra-popup CPT. Reading is safe on any popup — missing rows return empty defaults, mirroring the reader shape wppilot/spectra-pro-set-popup-conditions writes. |
Writes
Gated by the active profile and your WordPress capabilities. Rate limited to 120 per minute per credential.
| Ability | What it does |
|---|---|
wppilot/spectra-create-popupCreate Spectra Popup | Create a new Spectra Popup Builder post (spectra-popup CPT). Accepts short names (title, content, status) or their WP-native aliases (post_title, post_content, post_status) — passing both is rejected. When content is omitted the popup is seeded with the locked wp:uagb/popup-builder root block so the popup builder editor opens on a valid tree. Meta defaults: popup_type=modal, enabled=true, repetition=0. |
wppilot/spectra-disable-popupDisable Spectra Popup | Flip the spectra-popup-enabled meta flag to false (stores an empty string, the UAGB storage convention). Idempotent — calling on an already-disabled popup returns the same response. Paired with wppilot/spectra-enable-popup for the reverse operation. |
wppilot/spectra-duplicate-popupDuplicate Spectra Popup | Deep-copy a Spectra Popup into a brand-new draft: post content + slug + every canonical meta key (popup_type, enabled, repetition) plus any additional spectra-popup-* / spectra-pro-* meta the source carries (Pro adds display conditions). Optional title_suffix (default " (Copy)") is appended to the copied title so agents can find the new row. |
wppilot/spectra-enable-popupEnable Spectra Popup | Flip the spectra-popup-enabled meta flag to true. Idempotent — calling on an already-enabled popup returns the same response. Paired with wppilot/spectra-disable-popup for the reverse operation. Meta writes flush the post cache so a follow-up read sees the fresh value. |
Destructive
Marked destructive in the source, so each call needs an explicit confirmation flag, every time.
| Ability | What it does |
|---|---|
wppilot/spectra-delete-popupDelete Spectra Popup | Permanently delete a Spectra Popup (skips the trash). Requires confirm: true in the payload — a safety interlock so an agent cannot destroy the row from a single-argument tool call. Returns the deleted id + title so the caller can log which popup went away. |
wppilot/spectra-edit-popupEdit Spectra Popup | Merge-update a Spectra Popup. Every field is optional — only the keys the caller passes are written. Accepts short names (title, content, status, slug) or WP-native aliases (post_title, post_content, post_status, post_name); passing both aliases of the same field returns spectra_alias_conflict. Meta subset (popup_type, enabled, repetition) also mergeable. The post cache is flushed after the write so a follow-up get-popup sees fresh values. |
wppilot/spectra-pro-set-popup-conditionsSet Spectra Pro Popup Conditions | Write the Spectra Pro display-condition bundle for one popup. Every field is optional (at least one MUST accompany id). display_inclusions and display_exclusions are REPLACE-ALL writes (the whole bundle is overwritten). trigger accepts the Spectra Pro trigger vocabulary (typically load, click, time-delay, exit-intent, scroll); the ability stores the string verbatim and lets Spectra Pro validate at render time. written[] in the response lists keys whose stored value actually changed on this call — a key already at target does NOT appear (idempotent no-op). Post cache is flushed after the write. All-or-nothing type validation: every submitted field is type-checked before the first write, so a bad type never leaves a partial write behind. Not transaction-safe against a mid-sequence storage failure (e.g. a caching-plugin filter short-circuiting one row after another has committed) OR against concurrent callers overlapping keys — last-write-wins per meta row. On such a mid-sequence failure the returned WP_Error carries the list of already-persisted rows under data.partial_writes and the post cache is flushed for them. |
wppilot/spectra-set-block-activationSet Spectra Block Activation | Enable or disable a single Spectra block (uagb/xxx or spectra-pro/xxx) in the _uagb_blocks registry. Atomic read-modify-write so concurrent admin writes on unrelated blocks in the same option row do not clobber each other. The block must be present in the plugin catalogue (verified against wppilot/spectra-list-blocks). Spectra front-end + editor caches are flushed after the write. |
wppilot/spectra-set-editor-settingsSet Spectra Editor Settings | Write one or more Spectra editor / container settings. Whitelist-only — accepts the same 17 keys that wppilot/spectra-get-settings exposes. Toggles (uag_enable_*, uag_load_gfonts_locally, uag_preload_local_fonts, uag_load_fse_font_globally) accept the strings "enabled" / "disabled" (UAGB storage shape); container-default keys and the visibility/dynamic-content mode keys accept free-form strings. Unknown or non-whitelisted keys return spectra_unknown_setting. Cache is flushed after the write so the front end serves fresh CSS. |
wppilot/spectra-set-google-fonts-modeSet Spectra Google Fonts Mode | Toggle Spectra Google Fonts delivery mode. At least one of mode, preload_local, load_fse_globally MUST be provided — omitted keys stay untouched. local enables the UAGB local-hosting pipeline (fonts served from wp-content/uploads/spectra/), remote disables it so the front end links Google's CDN. preload_local and load_fse_globally are secondary flags exposed only for completeness. Same cache-flush semantics as spectra-set-editor-settings — the front end serves refreshed CSS after the write. |