---
title: "Resources & prompts"
description: "The three MCP resources and two prompts the Theme Dev server ships, and when an agent should reach for each"
---

> API Reference Index
> Fetch the complete API index at: https://docs.firearmcart.com/api/llms.txt
> Use this file to discover all available pages before exploring further.

# Resources & prompts

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-family` that is not in the platform's Google Fonts allowlist. The `@font-face` request 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 ship `div:empty { display: none }` in `base.css` at 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 against `active: true`, duplicate if needed, then read `liquid-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: none` in 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 existing `assets/*`; everything else uses the platform's designed placeholders via `placeholder_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-file` returns the file, where an `image_picker` reads `"image": null`. Their actual choice lives in the theme's settings, so a `null` you write back means "not specified" and is preserved — never force one through with `""` to try to clear it.

---

## Related documentation

- [Theme Dev MCP server](/api/mcp) — connecting, abilities and rate limits
- [Tools](/api/mcp/tools) — all 33 tools and their arguments
- [Liquid variables](/themes/liquid-variables) — the merchant-facing reference for the same drops
- [Sections](/themes/sections) — how sections and section groups behave in the editor

Source: https://docs.firearmcart.com/api/mcp/resources/index.mdx