Blaze: add MCP-exposed prepare-campaign write ability (ADS-953)#48349
Open
j6ll wants to merge 10 commits intoadd/ads-952-blaze-mcp-abilityfrom
Open
Blaze: add MCP-exposed prepare-campaign write ability (ADS-953)#48349j6ll wants to merge 10 commits intoadd/ads-952-blaze-mcp-abilityfrom
j6ll wants to merge 10 commits intoadd/ads-952-blaze-mcp-abilityfrom
Conversation
Adds `blaze-ads/create-campaign` to the existing Blaze_Abilities class, opted into Woo's MCP server alongside the read-only list-campaigns ability shipped in ADS-952. Architecture: - Cross-cutting guardrails (TOS / payment check, per-session spend ceiling) live in a registration-time wrapper applied via the `wp_register_ability_args` filter to any ability marked `meta.annotations.readonly => false`. Future Phase 3 write abilities inherit them automatically. - Audit log via `wp_after_execute_ability` listener, filtered to our write-path slugs. - Kill-switch via `blaze_abilities_create_campaign_enabled` filter (default true). - Successful response includes a draft campaign reference plus a deep-link to the Blaze widget for merchant approval. Phase 2 deliberately keeps approval in-browser; chat-native preview is tracked as ADS-988. Stubs to fill in: TOS / payment check, spend ceiling enforcement, Picard moderation (pending intent decision), integration tests.
Contributor
|
Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.
Interested in more tips and information?
|
Contributor
|
Thank you for your PR! When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:
This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖 🔴 Action required: Please include detailed testing steps, explaining how to test your change, like so: 🔴 Action required: We would recommend that you add a section to the PR description to specify whether this PR includes any changes to data or privacy, like so: Follow this PR Review Process:
If you have questions about anything, reach out in #jetpack-developers for guidance! |
github-actions
Bot
added
the
[Status] Needs Author Reply
Reading vendor/wordpress/mcp-adapter ToolsHandler.php confirms it only forwards WP_Error->message and ->code to MCP clients — the data field is dropped. So the original spec's "deep-link in WP_Error data" pattern won't reach Claude / other MCP clients via the MCP route. Update the stub example to embed the deep-link as a URL inside the error message text, so MCP clients can present it to the merchant. Keep the data field too as belt-and-braces for direct WP Abilities REST callers (standard WP REST serialization preserves it). Code change is doc-only (the stub still returns true). The real implementation will follow this pattern when wired up.
The wrapper now enforces a TOS / Blaze-eligibility gate using the existing Blaze::site_supports_blaze() helper (proxies the WPCOM /sites/<id>/blaze/status endpoint with a day-long transient cache, so per-call cost is a transient lookup). When the site isn't yet eligible the wrapper returns a WP_Error with the deep-link embedded in the message text (so Claude / other MCP clients pass it through to the merchant) and also in the data field as belt-and-braces for direct WP Abilities REST callers. Removes the check_spend_ceiling() stub. The "session" semantics for spend ceiling and the gate-vs-log-only call for Picard moderation are both real product decisions that don't need to block hack-month delivery — split out into ADS-989 as a post-RSM follow-up. The wrapper keeps a clearly-marked insertion point where ADS-989 will plug in.
Covers: - Wrapper passes through unowned and read-only abilities unchanged - Wrapper no-ops when execute_callback is missing - Wrapper replaces execute_callback for owned write abilities - Wrapped callback delegates to original when TOS / Blaze-eligibility passes - Wrapped callback short-circuits with WP_Error when site is not eligible - Deep-link URL is embedded in WP_Error message text (the Woo MCP adapter strips WP_Error::data, so this is the only way the URL reaches MCP clients) - Deep-link URL also lives in the data field as belt-and-braces for direct REST callers - Kill-switch via blaze_abilities_create_campaign_enabled removes create-campaign from registration without affecting list-campaigns - opt_into_woo_mcp toggles ON for both owned slugs and leaves foreign slugs at their default Inheritance is documented inline rather than dynamically tested — adding a new write slug to OWNED_ABILITY_SLUGS is the only step a Phase 3 ability needs to take to inherit the wrapper. Tests follow the WorDBless + transient-pre-population pattern; no Brain Monkey or runtime mocking needed since site eligibility is cached via transient and the wrapper is a static method we can call directly.
…rite)
Phase 2 v1 deliberately drops the direct DSP write from the agent
path. The ability now derives sensible defaults from the target post
+ the caller's input, bundles them into a structured prefill payload,
and returns a deep-link the merchant clicks to land in the existing
Blaze widget with every field already populated. The actual DSP write
happens when the merchant submits via the widget — we trust that flow.
Why this shape:
- The full DSP creation contract is 13 fields, several of which (payment
method, T&C acceptance, exact dates, etc.) are merchant-context the
AI can't reasonably fill in. Forcing an MCP-side draft would either
fail at DSP validation or land an incomplete campaign on the merchant's
account.
- The Blaze widget already renders the proper preview, audience, and
approval UX. Reusing it is much faster than rebuilding any of that
inside chat.
- The widget's prefill-from-URL behaviour is a separate piece of work
in dsp-client that this PR doesn't ship; until that lands the
merchant can still follow the link and edit manually.
Behaviour:
- Validates target_urn, resolves the post, and returns clean WP_Errors
for invalid URN (400) or missing post (404).
- Builds prefill payload with: target_urn, type, site_name (post title
or override), text_snippet (post excerpt, content fallback, or
override), target_url, main_image (featured image), budget (mode +
amount + currency from Woo or USD), duration_days, is_evergreen
(default true), objective (default VIEWS).
- Builds prefill_url with the payload base64url-encoded in a
blaze_prefill query param, inserted before the SPA hash so it
reaches the widget bootstrap.
- Returns { status: "pending_merchant_review", message, prefill_url,
prefill }. The message embeds the URL verbatim so MCP clients that
strip structured fields still surface the link to the merchant.
Tests cover: invalid URN, missing post, happy-path payload + URL
shape, caller overrides winning over post-derived defaults, content
fallback when no excerpt is set.
Two prefill defaults that the widget needed to render a complete form without any post-prefill clobbering on the client side: - `cta_text`: defaults to "Shop Now" for products, "Learn More" for posts/pages. The widget treats CTA as a required field; without a default the merchant lands on a form with a validation error immediately after the agent's deep-link. - `currency`: always USD. The DSP only bills in USD, so reading the Woo store currency just produced a misleading number for non-USD merchants — the DSP would treat the amount as USD regardless. Until the DSP gains multi-currency support, normalize at the prefill edge. 🤖 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Two new optional inputs the agent can pass through to narrow targeting: - `languages`: array of ISO 639-1 codes (lowercased on the way through). - `countries`: array of ISO 3166-1 alpha-2 codes (uppercased; codes that aren't 2 chars are dropped on the floor). Empty arrays are stripped before they hit the payload so the widget keeps its "all languages / worldwide" defaults instead of being forced into an empty selection. Schema-prose work (steering agents toward sensible defaults when the user is vague) is intentionally out of scope here and tracked as a Phase 2 follow-on. 🤖 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
j6ll
changed the title
Member
Author
|
MCP/JN smoke test passed. Validated through the Woo MCP adapter on the JN site:
No campaign was submitted by the MCP tool; it correctly stopped at merchant review/approval. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 2 of ADS-953. Adds a
blaze-ads/prepare-campaignwrite ability that lets an MCP client prepare a Blaze campaign proposal on the merchant's behalf.This ability deliberately does not write to the DSP. It derives sensible defaults from the target post (title → ad heading, excerpt → snippet, featured image, permalink) and optional caller input (natural-language goal, budget, duration, copy, image, and audience overrides), bundles the result into a structured
blaze_prefillpayload, and returns a deep-link the merchant clicks to land in the existing Blaze widget with every field already populated. The merchant reviews, accepts payment / T&C, and submits from inside the widget — that's where the actual DSP write happens, through the existing flow.The Blaze widget's prefill-from-URL behaviour is a separate piece of work in
dsp-client; until that lands the merchant can still follow the link and edit manually.How it works
blaze-ads/prepare-campaignability registered with input/output schema, opted into Woo's MCP viawoocommerce_mcp_include_ability, and gated behind ablaze_abilities_prepare_campaign_enabledkill-switch (default true) so we can disable centrally without a release.target_urnis required.budget_total,duration_days,goal,revision_instruction, copy/image overrides, and language/country audience overrides are optional. The raw DSPobjectiveis not exposed as MCP input.meta.annotations.readonly => falseruns through a TOS / Blaze-eligibility check (viaBlaze::site_supports_blaze()) before its execute callback. Future Phase 3 write abilities inherit the safety layer automatically — adding a slug toOWNED_ABILITY_SLUGSis the only step needed.permission_callbackorwp_before_execute_ability? The Abilities API stripsWP_Error::datafrompermission_callbackreturns (security stance) and the before/after action hooks are fire-and-forget so they can't gate the call. Thewp_register_ability_argsfilter is the only API-level injection point that lets a guardrail return a structuredWP_Errorand short-circuit the call.wp_after_execute_ability, scoped to our slugs.WP_Errorconstraint: the Woo MCP adapter stripsWP_Error::datawhen forwarding errors to MCP clients (onlymessageandcodesurvive). Deep-links are embedded in the error message text so they reach Claude / other MCP clients; thedatafield is kept too as belt-and-braces for direct REST callers.What's deferred (designed to plug into the same wrapper)
Test plan
Prereqs: a JN site with WooCommerce 10.7+, MCP Integration feature toggled on, Jetpack with this branch active and connected, a user with
manage_woocommerce, and at least one published post on the site.Two surfaces, two auth schemes:
1. WP Abilities REST endpoint (Application Password):
Expected: 200 with
{ status: "pending_merchant_review", prefill_url: "...?blaze_prefill=...", prefill: {...}, message: "..." }.2. Woo MCP server (REST API key + MCP client):
tools/listincludesblaze-ads-prepare-campaign.tools/callwith the same minimal input returns the same payload.Checklist
prefill_url,prefillpayload with post-derived defaults, andpending_merchant_reviewstatus.target_urnalone prepares a proposal with server-owned defaults.site_name/text_snippet/cta_text/ image / language / country overrides beats post-derived defaults.objectiveinput.target_urnreturns a 400WP_Errorwith codeblaze_invalid_target_urn.WP_Errorwith codeblaze_post_not_found.text_snippet.manage_woocommerce→ 403. Disconnected Jetpack user → 403.WP_Errorwith the Blaze setup deep-link in the message text (and the same URL in thedatafield for non-MCP REST callers).add_filter( 'blaze_abilities_prepare_campaign_enabled', '__return_false' )removes the ability from the registry; subsequent MCPtools/listno longer includes it.error_logon each invocation, with ability slug, user_id, site_id, input, is_error.Linear: ADS-953