Skip to main content

Using the Wonder MCP Server

Once the Wonder MCP server is connected, you don't call its tools yourself. You ask your assistant in plain words, and it decides which Wonder tool to use. This article explains what each tool does, so you know what to ask for and what a good answer looks like.


Prompts that work well​

Copy one of these into your assistant to try it out. Mentioning Wonder and your theme version helps the assistant pick the right tool.

Find a setting
In the Wonder theme, how do I show color swatches on product cards? Link the docs you used.
Is there a setting for it?
Is there a setting in Wonder to hide the sticky add-to-cart bar on mobile?
What can I change?
What can I change in Wonder's Image with text section?

An answer that points you to an existing setting is the best outcome: settings survive theme updates, code changes don't.

Something looks wrong
My store runs Wonder 2.5.1. The theme editor freezes after I move the Scrolling text banner. Is this a known issue?
Build a section
Create a custom Wonder section with three trust badges (icon, title, short text) on a light background. Validate it before you give it to me.
Before updating
I'm on Wonder 2.4.0. What do I get by updating to the latest version? Summarise the highlights.
Developer question
How do I open the Wonder cart drawer from my own JavaScript after adding a product with the Ajax API?
Where to find your Wonder version

Shopify admin → Online Store → Themes. The version is shown under the theme name.


The tools​

All tools are read-only. They never change your store, and they never generate code with AI: your assistant writes the code, and the Wonder tools give it the right knowledge and check the result.

ToolWhat your assistant uses it for
search_docsSearches this documentation and returns the matching passages with links
get_known_issuesKnown bugs per Wonder version, the workaround, and the version that fixes them
get_changelogRelease notes: what changed in a version, between two versions, or since when a feature exists
list_sectionsSections and theme blocks of a Wonder version, with category, number of settings, block types and limits. Can be filtered, e.g. "testimonial"
get_section_schemaEvery setting of one section or theme block, with the labels you see in the theme editor, defaults, options and ranges
get_component_apiWonder's documented JavaScript API: events, cart drawer methods and properties, and web components, with links to these docs
get_section_blueprintStarting code for a new custom section that follows Wonder's spacing, headings and naming
validate_sectionChecks a section file against Shopify's schema rules and Wonder conventions
plan_updateTurns a list of changed theme files into an update plan: copy, copy over or merge

search_docs​

Answers how-to questions from support.wonder-theme.com, including the developer reference (JavaScript events, cart drawer API, CSS variables, web components). A good answer links the articles it used. If yours doesn't, ask: "Which Wonder docs did you use?"

get_known_issues​

The assistant should call this first when you report a problem. Here is a real response for a store on an older version:

get_known_issues → response (excerpt)
Latest Wonder release: 2.5.2.

## Theme editor freezes after moving Scrolling text banner / Scrolling icon with text [FIXED in 2.5.2]
Affects: earlier – 2.5.1
Symptom: Reordering homepage sections a few times freezes the theme editor. Closing and
reopening the editor resets it. The live storefront is not affected.
Workaround: Update to 2.5.2 or later. On older versions, reload the editor after reordering
these sections.

get_changelog​

Answers "what's new", "what do I get by updating from 2.4.0" and "since which version does Wonder have Quick Buy?". It reads the same release notes as our Changelog.

list_sections​

Answers "which Wonder sections can show testimonials?" or "does Wonder have a section to compare products?", so the assistant suggests an existing section before building a new one. Real response:

list_sections → response for testimonial
Wonder 2.5.2: 4 sections, 0 theme blocks (filtered from 117).

## Sections
- Testimonial images — sections/testimonial-images.liquid · category: Testimonials · 30 settings · blocks: testimonial
- Testimonial: Marquee — sections/testimonial-marquee.liquid · category: Testimonials · 25 settings · blocks: image
- Testimonial video reels — sections/testimonial-video-reels.liquid · category: Testimonials · 14 settings · blocks: video · max 12 blocks
- Testimonials — sections/testimonials.liquid · category: Testimonials · 13 settings · blocks: image

See also All sections.

get_section_schema​

Answers "is there a setting to hide the sticky add-to-cart bar on mobile?" or "what can I change in the Image with text section?". It returns every setting with the label you see in the theme editor, so the assistant can tell you exactly where to click. Large sections (like Product information) return the section settings plus a summary of the blocks; the assistant then asks for one block at a time.

get_section_schema → response for main-product (excerpt)
Section "Product information" (sections/main-product.liquid), Wonder 2.5.2.
Labels are the English theme-editor labels.

{ "type": "header", "content": "Sticky buy button" },
{ "type": "checkbox", "id": "enable_sticky_buy_button",
"label": "Enable sticky buy button", "default": true },
{ "type": "select", "id": "sticky_button_visibility",
"label": "Sticky buy button visibility",
"options": ["Only on mobile", "Only on desktop", "On both"], "default": "mobile" },
...

get_component_api​

Used when you ask for custom JavaScript, for example "when a customer picks another variant, push the variant id to dataLayer" or "how do I open the cart drawer from my own button?". It returns Wonder's documented events, cart drawer methods and web components, and says whether they exist in your version, so the code hooks into the theme instead of editing its files.

get_component_api → response for variantChangeEnd
variantChangeEnd (event), from "JavaScript Events Reference":
https://support.wonder-theme.com/developer/javascript-events#variantchangeend
Present in Wonder 2.5.2.

Dispatched on the `variant-options` element after the variant UI has fully updated.

Internal components that aren't documented are listed by name only: they can change in any release, so the assistant shouldn't build on them.

get_section_blueprint and validate_section​

Used together whenever you ask for a new section. The blueprint gives the assistant a starting point that already handles Wonder's section spacing, heading style and update-safe file naming (sections/custom-<name>.liquid). The validator then checks the finished file. A first draft often fails, which is exactly why the check exists:

validate_section → response for a first draft
INVALID: 1 error(s), 2 warning(s). Fix the errors and run validate_section again.
- [ERROR] no-scss (line 39): SCSS syntax found ($variables, @mixin/@include or & nesting).
Wonder sections use plain CSS.
- [WARNING] translation-key-label: 1 setting label(s) use t: translation keys (heading).
... in a NEW custom section use literal labels, because locale files are replaced on theme update.
- [WARNING] css-unscoped (line 39): Selector "h3" is not scoped to this section and may
change styles elsewhere in the theme. Prefix it with your section class (e.g. .custom-<name>).

The assistant fixes the problems and validates again until it gets VALID. See the full walkthrough in Tutorial: build a custom section with AI.

plan_update​

Used when you move a customised theme to a new Wonder version. It receives only the names of the files you changed (never their contents) and tells the assistant which ones to copy, which to copy over and which need a merge. See Tutorial: update a customised Wonder theme.


Skills (Wonder AI Toolkit only)​

If you installed the Wonder AI Toolkit plugin, your coding agent also gets five skills: step-by-step workflows that use the tools in the right order. They load on their own when your request matches, so you usually don't need to call them.

SkillStarts when you…
wonder-setupstart working on a Wonder store, or ask how to set things up
wonder-sectionsask for a new section or a change to a custom section
wonder-javascriptask for custom JavaScript: it uses only documented events and components, and says where to put the code and what survives an update
wonder-troubleshootingreport that something looks broken, misaligned or missing
wonder-updatewant to update Wonder, or ask what you lose by updating

In Claude Code you can also run a skill directly:

/wonder-theme:wonder-sections Testimonials slider with star ratings and customer photos

Ready-made prompts (MCP server)​

The server also offers two guided prompts. In clients that support MCP prompts they appear in the prompt or slash-command menu (for example, in Claude Code with the server added as wonder: /mcp__wonder__new-section and /mcp__wonder__debug-issue):

  • new-section: blueprint → adapt → validate → ready-to-paste file with install steps;
  • debug-issue: checks known issues for your version and the docs before suggesting any change.

Rules the assistant follows​

The Wonder tools teach your assistant these rules. If an answer breaks one of them, point it out:

  • Plain CSS only. No SCSS or build tools.
  • The least invasive change wins: a theme setting first, then Theme settings → Custom CSS, then a new custom section, and only as a last resort an edit to a Wonder file.
  • Theme updates don't copy file edits. Theme settings and Theme settings → Custom CSS carry over when you update Wonder. Edited theme files, assets/custom.css, assets/custom.js and custom sections don't: keep a copy.
  • Work on a copy. Test on an unpublished duplicate of your theme, never on the live theme.

If the assistant doesn't use the Wonder tools​

  • Make sure the server is connected: ask "Which Wonder tools do you have?". It should list the nine tools above. If not, see Troubleshooting.
  • Mention Wonder in your question. Without it, the assistant may answer from general Shopify knowledge.
  • In ChatGPT, turn on the Wonder connector for the conversation (see setup).