Tools are what an agent does. Resources and prompts are what it knows before it starts, and on this server that distinction carries real weight: FirearmCart’s Liquid has its own rules, and most of the ways a theme edit goes wrong here fail silently — no error, no exception, just a header that renders twice or a font that never loads.
The server ships three resources and two prompts to close that gap.
Read liquid-guidelines before you write any Liquid
This is the server’s own instruction, stated in the initialize handshake as step 2 of the standard workflow, ahead of touching a single file. Treat it as a precondition rather than background reading.
The reason is that the guidelines document failure modes that produce no error at all:
- A hardcoded
font-familythat is not in the platform’s Google Fonts allowlist. The@font-facerequest 400s, the stylesheet comes back empty, and the browser falls back with nothing logged anywhere. - An overlay written as an empty
<div>. Five of the base themes shipdiv:empty { display: none }inbase.cssat specificity (0,1,1), which beats your class — the layer simply never paints. - A hand-rolled page container. It silently overrides the merchant’s Page width setting, so they set 1600px in the editor and your sections stay pinned wherever you hardcoded them.
- A
<header>inside a body section. Header and footer already render on every page from their section groups, so the page gets two. - A snippet referenced by the wrong filename.
{% render %}404s silently and the hamburger just never opens.
None of these surface in a screenshot diff as an obvious break, and none of them are guessable from general Liquid experience. An agent that skips the resource will hit several of them.
The resources
All three are markdown, served from files on the server. If a source file is missing, the resource returns an error naming it rather than empty content.
liquid-guidelines
| URI | theme://liquid-guidelines |
| MIME type | text/markdown |
| Ability | Readable by any connected token |
The platform’s Liquid rulebook, and the longest of the three by a wide margin. It covers file anatomy and the theme path scheme, section authoring with a minimal skeleton, where CSS and JS may go, the common setting types (including the image_picker round-trip and the color_scheme duality), FirearmCart’s own product drops, a filter cheat-sheet, and the preprocessing quirks specific to this Liquid implementation.
It also carries the judgement calls that the tool descriptions only allude to: what you own versus what the platform owns, one section per page region, when to rebuild chrome and when to ask, the mobile contract a custom header owes, why to restyle the shell but reuse the machinery, icons versus pictures, and why a blank image is a finished result rather than a gap.
Read it once per session, before the first write. Everything else in this section assumes you have.
theme-json-shapes
| URI | theme://theme-json-shapes |
| MIME type | text/markdown |
| Ability | Readable by any connected token |
The exact JSON shapes for page templates, section groups and settings_schema, with a worked example of adding a section to templates/index.json.
Read it before writing or editing any .json theme file. Page templates are where most theme work actually lands — configuring an existing section through templates/*.json is preferred over authoring a new one — and the shape has rules that a plausible-looking guess will violate. Every key in sections must also appear in order; the header and footer groups use the same {sections, order} shape but live in section rows rather than page templates; image settings in a template have their own round-trip. A malformed template is rejected by the save validator, so a guess costs a round trip at best.
plugin-liquid
| URI | theme://plugin-liquid |
| MIME type | text/markdown |
| Ability | Readable by any connected token |
Recipes for the storefront features that come from plugins rather than the theme: Product Reviews, Events & Classes, Reload subscribe & save, and Klaviyo back-in-stock. For each it gives the exact section types, the drops available, and the form endpoints.
Read it before building any of those features — and call list-plugins first. Plugin sections (fc-*) are not theme files: never create or edit them, only reference them by type from a page template. Building a feature whose plugin is not active ships a widget with no data behind it. The resource also lists what is not theme-controllable at all.
The prompts
Prompts are parameterised workflows. Your client surfaces them as slash commands, a picker, or whatever its own convention is; invoking one returns a checklist the agent then follows.
recreate-from-mockup
Recreate a storefront mockup screenshot: pick a safe workspace theme, settle the header/footer, rebuild the body section by section on desktop, then a tablet/mobile responsive pass.
| Argument | Required | Description |
|---|---|---|
theme |
No | Theme id or UUID to work on. Omit to pick or duplicate a safe workspace in phase 0. |
notes |
No | Notes about the mockup or the target page. |
The server’s flagship workflow, and the reason most of the guardrails exist. It runs in four phases:
- Phase 0 — safe workspace.
list-themes, never build againstactive: true, duplicate if needed, then readliquid-guidelines. - Phase 1 — split the mockup, settle the chrome. A page template holds only the body; header and footer belong to the section groups. Whether the chrome is yours to rebuild depends on whether this is a whole-theme mockup or one secondary page — and on a secondary page the instruction is to ask the user, not to guess either way.
- Phase 2 — recreate the body on desktop. One section per band of the mockup, screenshot, diff, refine.
- Phase 3 — responsive pass. Only after desktop matches. The mobile header is called out as the most common casualty: a flat wrapped nav instead of a hamburger, or a search/cart icon lost to a
display: nonein a media query.
It finishes with an explicit accounting step — present all three viewports, say plainly whether the chrome matches or is still stock, confirm the mobile header is a hamburger with working search and cart, and report the merchant checklist of images to upload and settings that cannot be changed over MCP. publish-theme is called only when the user explicitly asks to go live.
build-section
Checklist for authoring one new Liquid section with schema presets and screenshots.
| Argument | Required | Description |
|---|---|---|
purpose |
Yes | What the section should do or look like. |
theme |
Yes | Theme id or UUID. |
The narrow counterpart: six steps for one section. Read liquid-guidelines, grep-theme for something similar to reuse, create sections/<name>.liquid with settings-driven markup, a {% style %} block for Liquid-valued CSS and a {% schema %} carrying at least one preset, save through the validator, add the instance to a page template’s sections map and its order, then screenshot desktop and mobile.
Things no resource can give you
Worth stating, because agents reliably try:
- Raster images. Tools take text only. There is no upload path for png, jpg or webp. Real photography comes from
list-media(the merchant’s own library, with CDN URLs) or existingassets/*; everything else uses the platform’s designed placeholders viaplaceholder_svg_tag. - The store logo. It comes from the merchant’s Settings → General, not the theme, and cannot be set over MCP. A header must emit the global
settings.logo; a section-level image setting silently never renders. - The merchant’s chosen setting values inside files.
read-theme-filereturns the file, where animage_pickerreads"image": null. Their actual choice lives in the theme’s settings, so anullyou write back means “not specified” and is preserved — never force one through with""to try to clear it.
Related documentation
- Theme Dev MCP server — connecting, abilities and rate limits
- Tools — all 33 tools and their arguments
- Liquid variables — the merchant-facing reference for the same drops
- Sections — how sections and section groups behave in the editor