"i only speak liquid" #81: Shopify MCP & Agentic Development tips

Hey everyone,

We are back! This is Vitalii’s 1st edit of “i_only_speak_liquid”! Whoop whoop.

—

Vitalii is a full-stack JavaScript and Shopify developer who’s worked with brands like CDLP and Represent.

He specializes in building high-performance Next.js and Remix storefronts, along with custom Shopify solutions that drive revenue and customer satisfaction.

Ofc: He’s an expert on Storetasker 😉 apply here.

Let’s dive in 🤿

What I’ve been thinking about:

Last week Shopify MCP shipped an update for Liquid.

Everyone has already seen the new Shopify editor, but in my view, it only becomes genuinely useful once it has full agent or MCP support. Without that, it's still limited in providing accurate code suggestions, API context, or validation, which means most of the benefits we expect from AI-assisted development just don't materialize.

Why MCP/Agents are worth attention:

For me, MCP/Agents has become one of the most useful tools when working with Shopify. Most AI-assisted coding fails on Shopify projects because the model doesn't have the right context about Liquid, the API schema, or object patterns. MCP fixes that by giving the model the actual definitions and documentation. When you ask it to generate Liquid or make an API call, it's pulling from the real Shopify ecosystem instead of guessing.

It's also very effective with Shopify Functions. MCP always provides the latest Function API docs and type definitions, which makes writing Rust or JavaScript handlers faster, more accurate, and less likely to break after updates.

That said, MCP doesn't always behave exactly as you'd want. Sometimes it gives you something close but not quite right. In those cases, it's worth leaning on more specific tool calling - for example, using shopify_admin_graphql for exact mutations, introspect_graphql_schema to check field availability, or validate_graphql_codeblocks to confirm queries. You can also pull in documentation directly with learn_shopify_api, fetch_full_docs, or search_docs_chunks when you need precise references instead of relying on a generic prompt.

My Rules for Pain-Free Development:

Here's my rules suggestion to make development less painful. Following these guidelines helps reduce errors, speeds up iteration, and keeps your theme organized and maintainable. It's all about building a workflow where Liquid, sections, snippets, and APIs work together smoothly, so you spend less time troubleshooting and more time shipping features that actually work.

Cursor Rules for Shopify Liquid Development:

Here's a practical .cursorrules file that will make your Shopify theme development much smoother:

---

description: Best-practice rules for Shopify Liquid snippets and theme development

---

###  **Available MCP Tools**

Use these MCP tools to get the latest up-to-date data:

| Tool | Purpose |

|------|---------|

| introspect_graphql_schema | Explore Shopify's GraphQL schema structure |

| learn_shopify_api | Get knowledge about Shopify's APIs |

| search_docs_chunks | Search through Shopify developer documentation |

| fetch_full_docs | Retrieve complete documentation pages |

| validate_graphql_codeblocks | Validate GraphQL code against schemas |

| shopify_admin_graphql | Write accurate Admin API operations |

---

### 🔍 **MCP Validation Rules**

- ** MCP Check:** Verify your development environment and tools are up to date by querying the latest Shopify API versions and documentation schemas using Shopify MCP tools.

- ** MCP Check:** Check the validity of snippet and block parameters, descriptions, and examples to ensure they align with the defined LiquidDoc standard.

  **Rule:** **Enable and use LiquidDoc in snippets and blocks.** This is a native Shopify feature that adds structured documentation to your reusable components, making your code easier to read and validate. **Do not use LiquidDoc in sections**, as it isn't supported there. Section settings and documentation are handled by the schema.json file.

- ** MCP Check:** Analyze the theme's file and directory structure to ensure it follows a modular, organized pattern with clear separation between sections, snippets, and templates.

  **Rule:** Maintain a clean, logical file structure. Break down themes into a modular architecture using sections and snippets. Store reusable components (like headers or product cards) in snippets to reduce redundancy and improve maintainability.

- ** MCP Check:** Run a comprehensive validation of all theme files, checking for syntax errors, security vulnerabilities, and adherence to established best practices.

- ** MCP Check:** Evaluate code for readability, consistency, and adherence to naming conventions and commenting standards.

  **Rule:** **Write clean, readable code.**

    - Maintain consistent code formatting and indentation.

    - Use meaningful variable names that are easy to understand.

    - Add inline comments to explain complex logic or unique functionality.

- ** MCP Check:** Scan Liquid templates for common error-prone patterns, such as trying to access properties on a potentially nil object.

  **Rule:** **Implement robust error handling.** Always check if objects or arrays exist before trying to display data (e.g., {% if collection.products.size > 0 %}). Use blank or empty instead of empty strings to handle nil values correctly.

- ** MCP Check:** Query the theme's schema and Liquid to ensure it effectively uses Online Store 2.0 features like JSON templates and metafields.

- ** Remember that Liquid can't access query parameters directly - you'll need to use Shopify's built-in objects and filters. Always compare Liquid logic with Shopify MCP tools before deploying.

Agentic Development Tips

Pro Tip: Large files can easily confuse agents, making suggestions less accurate or even wrong.

By breaking your theme into well-named snippets and clear sections, you not only keep your code neat but also make it easier for MCP/Agents to understand context and provide precise recommendations.

Additionally, keeping a Markdown (.md) file that documents big logic changes or complex workflows helps agents follow your intent more accurately. When everything is clearly explained and tracked, MCP/Agents can reference it for better suggestions, reducing errors and misunderstandings.

When you revisit a project months later, you'll immediately know where to make changes. Combined with accurate context from MCP/Agents, this approach gives you a smart assistant plus a clean workflow, letting you focus on building features and improving UX instead of chasing bugs or syntax issues.

Key Setup Steps:

1. Install the Shopify Liquid extension in Cursor

2. Add this .cursorrules file to your theme root

3. Enable Shopify CLI theme check for validation

4. Use Cursor's AI with specific Shopify context prompts

3 links you can’t miss:

• Shopify Dev MCP - Connect an AI assistant to Shopify's docs and API schemas

• SVGco.de  - Turn raster images into clean, editable SVGs instantly

• Linear.app - Fast project tracking for product teams

1 app I like:

Uplinkly Digital Downloads - Makes selling digital products simple with automatic download links and file management.

One learning as a freelancer:

With tech moving this fast, it's not about knowing everything. It's about being able to adapt quickly and pull in new, valuable context that you can actually use in your work.

-Vitalii