Shopify/dev-mcp

introspect_graphql_schema

This tool introspects and returns the portion of the Shopify Admin API GraphQL schema relevant to the user prompt, including scope information for queries, mutations, and objects. Only use this for the Shopify Admin API, and not any other APIs like the Shopify Storefront GraphQL API or the Shopify Functions API.

🚨 CRITICAL: This is your primary tool when working with GraphQL APIs, especially when exploring schema fields or when search_docs_chunks returns an error (HTTP 500/503 or "fetch failed").

⚠️ API CONTEXT WARNING:
- If you've already called learn_shopify_api with a specific API (e.g., "admin")

- You MUST continue using that same API for ALL subsequent tool calls
- DO NOT switch to "admin" or any other API unless explicitly requested by the user
- The 'api' parameter should match what you used in learn_shopify_api

USAGE TIPS:
- Search for operations by their action: "create", "update", "delete", "list", "capture", "refund"
- Search for specific objects: "product", "order", "customer", "discount"
- Search for specific fields: "version", "publicApiVersions", "shop"
- Try multiple variations if first search returns nothing

    - For camelCase names, search for individual words: "captureSession" → try "capture" or "session"

FALLBACK STRATEGY:
1. Start with the most specific term from the user's request
2. If no results, try broader terms or related words
3. For "list" operations, try "all", "list", or the plural object name
4. For mutations, try the action verb: "create", "update", "delete", etc.

The schema HAS THE ANSWERS - if the first introspection call doesn't yield expected results, try searching for shorter words that are part of your initial query!

learn_shopify_api

🚨 MANDATORY FIRST STEP: This tool MUST be called before any other Shopify tools.

⚠️  ALL OTHER SHOPIFY TOOLS WILL FAIL without a conversationId from this tool.
This tool generates a conversationId that is REQUIRED for all subsequent tool calls. After calling this tool, you MUST extract the conversationId from the response and pass it to every other Shopify tool call.

🔄 MULTIPLE API SUPPORT: You MUST call this tool multiple times in the same conversation when you need to learn about different Shopify APIs. THIS IS NOT OPTIONAL. Just pass the existing conversationId to maintain conversation continuity while loading the new API context.

For example, a user might ask a question about the Admin API, then switch to the Functions API, then ask a question about polaris UI components. In this case I would expect you to call learn_shopify_api three times with the following arguments:

- learn_shopify_api(api: "admin") -> conversationId: "123"
- learn_shopify_api(api: "functions", conversationId: "123")
- learn_shopify_api(api: "polaris-admin-extensions", conversationId: "123")

This is because the conversationId is used to maintain conversation continuity while loading the new API context.

🚨 Valid arguments for `api` are:
    - Admin API: The Admin GraphQL API lets you build apps and integrations that extend and enhance the Shopify admin.
- Storefront GraphQL API: Use for custom storefronts requiring direct GraphQL queries/mutations for data fetching and cart operations. Choose this when you need full control over data fetching and rendering your own UI. NOT for Web Components - if the prompt mentions HTML tags like <shopify-store>, <shopify-cart>, use storefront-web-components instead.
- Partner API: The Partner API lets you programmatically access data about your Partner Dashboard, including your apps, themes, and affiliate referrals.
- Customer Account API: The Customer Account API allows customers to access their own data including orders, payment methods, and addresses.
- Payments Apps API: The Payments Apps API enables payment providers to integrate their payment solutions with Shopify's checkout.
- Shopify Functions: Shopify Functions allow developers to customize the backend logic that powers parts of Shopify. Available APIs: Discount, Cart and Checkout Validation, Cart Transform, Pickup Point Delivery Option Generator, Delivery Customization, Fulfillment Constraints, Local Pickup Delivery Option Generator, Order Routing Location Rule, Payment Customization
- Polaris App Home: Build your app's primary user interface embedded in the Shopify admin. If the prompt just mentions `Polaris` and you can't tell based off of the context what API they meant, assume they meant this API.
- Polaris Admin Extensions: Add custom actions and blocks from your app at contextually relevant spots throughout the Shopify Admin. Admin UI Extensions also supports scaffolding new adminextensions using Shopify CLI commands.
- Polaris Checkout Extensions: Build custom functionality that merchants can install at defined points in the checkout flow, including product information, shipping, payment, order summary, and Shop Pay. Checkout UI Extensions also supports scaffolding new checkout extensions using Shopify CLI commands.
- Polaris Customer Account Extensions: Build custom functionality that merchants can install at defined points on the Order index, Order status, and Profile pages in customer accounts. Customer Account UI Extensions also supports scaffolding new customer account extensions using Shopify CLI commands.
- POS UI: Build point-of-sale applications using Shopify's POS UI components. These components provide a consistent and familiar interface for POS applications. POS UI Extensions also supports scaffolding new POS extensions using Shopify CLI commands.
- Liquid: Liquid is an open-source templating language created by Shopify. It is the backbone of Shopify themes and is used to load dynamic content on storefronts. Keywords: liquid, theme, shopify-theme, liquid-component, liquid-block, liquid-section, liquid-snippet, liquid-schemas, shopify-theme-schemas

🔄 WORKFLOW:
1. Call learn_shopify_api first with the initial API
2. Extract the conversationId from the response
3. Pass that same conversationId to ALL other Shopify tools
4. If you need to know more about a different API at any point in the conversation, call learn_shopify_api again with the new API and the same conversationId


DON'T SEARCH THE WEB WHEN REFERENCING INFORMATION FROM THIS DOCUMENTATION. IT WILL NOT BE ACCURATE.
PREFER THE USE OF THE fetch_full_docs TOOL TO RETRIEVE INFORMATION FROM THE DEVELOPER DOCUMENTATION SITE.

validate_theme

This tool validates Liquid codeblocks, Liquid files, and supporting Theme files (e.g. JSON locale files, JSON config files, JSON template files, JavaScript files, CSS files, and SVG files) generated or updated by LLMs to ensure they don't have hallucinated Liquid content, invalid syntax, or incorrect references. Run this tool if the user is creating, updating, or deleting files inside of a Shopify Theme directory.

search_docs_chunks

This tool will take in the user prompt, search shopify.dev, and return relevant documentation and code examples that will help answer the user's question.

fetch_full_docs

Use this tool to retrieve a list of full documentation pages from shopify.dev. When you find relevant document chunks using the search_docs_chunks tool, YOU MUST USE THIS TOOL TO RETRIEVE THE FULL DOCUMENTATION PAGES. THIS IS IMPORTANT. You can use the url attribute of the chunks.

validate_component_codeblocks

🚨 MANDATORY VALIDATION TOOL - MUST BE CALLED WHEN COMPONENTS FROM SHOPIFY PACKAGES ARE USED. DONT ASK THE USER TO DO THIS. DON'T CONTEXT SWITCH.

This tool MUST be used to validate ALL code blocks containing Shopify components, regardless of size or complexity.

⚠️  CRITICAL REQUIREMENTS:
- Call this tool IMMEDIATELY after generating ANY Shopify component code
- NEVER skip validation, even for simple examples or snippets
- ALWAYS use this tool when generating JSX, TSX, or web component code
- This validation prevents hallucinated components, props, and prop values

📥 INPUTS:
- code: Array of markdown code blocks containing components to validate
- apiName: API name to validate against (e.g., 'pos-ui', 'polaris-app-home')
- conversationId: Required ID from learn_shopify_api tool

📤 OUTPUTS:
- Comprehensive validation results with specific error details
- Clear guidance on how to fix any validation failures
- Component-by-component validation status

🔄 WORKFLOW: Generate Code → Validate → Fix Errors and replace code → Re-validate if needed

validate_graphql_codeblocks

This tool validates GraphQL code blocks against the Shopify GraphQL schema to ensure they don't contain hallucinated fields or operations. If a user asks for an LLM to generate a GraphQL operation, this tool should always be used to ensure valid code was generated.

It returns a comprehensive validation result with details for each code block explaining why it was valid or invalid. This detail is provided so LLMs know how to modify code snippets to remove errors.