DOCSEARCHbyAlgolia
Submit Docs

Shopify AI Toolkit

repository·main·Indexed 19 days ago

https://github.com/shopify/shopify-ai-toolkit

A toolkit providing the Shopify Dev MCP, an AI Agent Plugin that connects tools like Claude Code, Cursor, and VS Code Copilot to the Shopify platform. It enables AI agents to search documentation, validate GraphQL and Liquid code against official schemas, and manage stores via the Shopify CLI. Includes specialized skills for Admin GraphQL, App Store pre-submission compliance checks, and managing Metafields and Metaobjects via TOML and API.

Tokens
161.6K
Snippets
522
Records
646
Agent score
61%

What's inside shopify-ai-toolkit

  1. Capabilities of the Shopify Dev MCP Plugin

    main

    Once installed, the plugin provides the following capabilities to your AI agent:

    • Docs and API schemas: Search Shopify's documentation and API schemas directly within your editor.
    • Code validation: Validate GraphQL queries, Liquid templates, and UI extensions against official Shopify schemas.
    • Store management: Manage your Shopify store using the CLI's store execute capabilities.
    • Auto-updates: The plugin automatically updates as new capabilities are released.

  2. Use the shopify-customer skill for Customer Account API development

    main

    The shopify-customer skill is an AI agent plugin designed to help developers write GraphQL queries or mutations specifically for the Shopify Customer Account API.

    Key Concepts

    • Customer Account API vs. Admin API: The Customer Account API is for authenticated customers to manage their own data (orders, addresses, payment methods). It is distinct from the Admin API, which is for merchant operations.
    • Context: Operations run in a customer context; customers can only access their own data.
    • Capabilities: The skill assists in generating valid GraphQL operations for order history, address management, profile updates, and payment methods while adhering to privacy and PCI compliance considerations.

  3. Run a Shopify App Store pre-submission compliance check

    main

    The shopify-app-store-review skill allows an AI agent (compatible with Claude Code, Claude Desktop, and Cursor) to perform a pre-submission compliance check against your Shopify app's local codebase. It evaluates your code against official Shopify App Store requirements to surface potential issues before you submit for official review.

    How it works

    1. Requirement Fetching: The agent uses the Shopify CLI to fetch the latest, canonical list of requirements directly from Shopify.
    2. Codebase Evaluation: The agent searches your local files, configurations, and API patterns to assign one of three statuses to each requirement:
      • ✅ Likely passing: Positive evidence of compliance found.
      • ❌ Likely failing: Clear violations or missing required implementations detected.
      • ⚠️ Needs review: Ambiguous signals that require human judgment.
    3. Reporting: You receive a summarized report highlighting failing requirements, items needing manual review, and groups that were skipped (e.g., because they were conditional or opt-in).

  4. Use the shopify-shopifyql skill for analytics and reporting

    main

    The shopify-shopifyql skill is designed to answer merchant questions regarding analytics and reporting using ShopifyQL.

    When to use this skill

    Use this skill (instead of the admin skill) whenever the request involves numbers, totals, trends, or breakdowns rather than fetching or mutating individual records.

    Common use cases include:

    • Total, gross, or net sales and revenue
    • Order counts and average order value
    • Refunds and quantity sold
    • Sessions, conversion rates, and traffic
    • Slicing data by product, channel, region, or customer
    • Trending data over time or period-over-period comparisons (e.g., "sales this year vs last year")

    When NOT to use this skill

    Do not use this skill for general Admin GraphQL operations, such as fetching or mutating individual resources (e.g., a specific order or customer). For those tasks, use the admin skill.

  5. Use the shopify-dev skill for general documentation search

    main

    The shopify-dev skill is a general-purpose tool used to search across all of Shopify's developer documentation on shopify.dev.

    When to use it: Use this skill ONLY when no API-specific skill (such as shopify-admin-graphql, shopify-liquid, or shopify-checkout-extensions) applies to the task. It is intended for questions that span multiple APIs or do not fit into a specific category.

    Requirements:

    • Requires Node.js environment.
    • Compatibility: Node.js.

  6. Use the shopify-storefront-graphql skill

    main

    The shopify-storefront-graphql skill is designed for custom storefronts that require direct GraphQL queries or mutations for data fetching and cart operations. Use this skill when you need full control over data fetching and UI rendering.

    When NOT to use this skill: Do not use this skill if the user prompt mentions HTML tags like <shopify-store> or <shopify-cart>. In those cases, use the storefront-web-components skill instead.

    Key Capabilities:

    • Generates valid GraphQL queries and mutations for the Shopify Storefront API.
    • Provides documentation links for all operations used.
    • Ensures payload minimization by including only essential fields.

  7. Use the shopify-admin skill for Admin GraphQL

    main

    The shopify-admin skill is designed to help developers write or explain Admin GraphQL queries and mutations for apps and integrations.

    When to use shopify-admin:

    • You want to understand, design, or generate a GraphQL operation.
    • You need help authoring a specific query or mutation.

    When NOT to use shopify-admin (Use use-shopify-cli instead):

    • Executing Admin GraphQL via Shopify CLI.
    • Validating app or extension configuration files (e.g., shopify.app.toml, shopify.extension.toml).
    • Store workflows like handle/SKU/location lookups or inventory changes.
    • CLI setup or troubleshooting.

  8. Use the shopify-partner skill for Partner API development

    main

    The shopify-partner skill is an AI agent plugin designed to help developers write GraphQL queries and mutations for the Shopify Partner API. It allows you to programmatically access data regarding your Partner Dashboard, including apps, themes, and affiliate referrals.

    To use this skill effectively, an AI agent must follow a strict workflow of searching documentation and validating code before presenting it to the user. This ensures that the generated GraphQL operations adhere to the specific Partner schema, including correct root fields, connection pagination, and enum values.

  9. Use the shopify-hydrogen skill for Hydrogen storefront development

    main

    The shopify-hydrogen skill is designed to assist developers in writing UI Framework code for Shopify Hydrogen storefronts.

    Key Constraints:

    • API Selection: When working with Hydrogen, you MUST use the api:"hydrogen" context. Do NOT use api:"storefront" (Storefront GraphQL) when the user mentions 'Hydrogen'.
    • Package Usage: Use the @shopify/hydrogen package. Do NOT use @shopify/hydrogen-react.
    • Component Nature: Many Hydrogen components (like Image, Video, ExternalVideo, MediaFile, and Money) are React UI components that render data; they are not GraphQL data types. They consume data fetched from the Storefront API but are part of the Hydrogen UI framework.

    Available Recipes: The skill provides access to a 'Hydrogen Cookbook' containing recipes for:

    • B2B Commerce
    • Bundles
    • Combined Listings
    • Custom Cart Methods
    • Dynamic Content with Metaobjects
    • Express Server
    • Google Tag Manager Integration
    • Infinite Scroll
    • Legacy Customer Account Flow
    • Markets
    • Partytown + Google Tag Manager
    • Subscriptions
    • Third-party API Queries and Caching

  10. Key UCP response fields and conventions

    main

    When working with UCP data, follow these technical conventions:

    • Business Identity: Use seller.domain as the value for the --business flag. seller.url is for buyer-facing homepage text and is not the preferred handoff target.
    • Variant IDs: variants[M].id is merchant-specific; pass it verbatim into cart or checkout operations.
    • Currency/Amounts: All amounts are represented in minor currency units (e.g., 15000 = $150.00 USD). Always check the paired currency field.
    • Pricing Location: Cart and checkout pricing is located in result.totals[]. There is no result.cost field.
    • Fulfillment: Cart fulfillment numbers are estimates; checkout fulfillment is the final selectable surface.
    • Shipping Estimates: To get shipping estimates before checkout, introspect the schema using ucp cart update --input-schema --business <seller-domain>. If supported, update the cart with a destination.

  11. Write ShopifyQL queries using the FROM...SHOW syntax

    main

    ShopifyQL is a read-only query language for aggregated store metrics. When writing queries, follow these rules:

    1. Syntax Pattern: Always use the FROM ... SHOW ... pattern. Never use SELECT.
    2. Schema Selection: Choose the FROM schema deliberately. ShopifyQL has multiple schemas; a metric owned by one schema will not exist in another. Always search the developer documentation to confirm which schema owns the required metric or business noun.
    3. Verbatim Names: Only use field names, metrics, tables, or clauses explicitly found in the documentation. Never guess or "SQL-ify" names (e.g., do not use table.column paths unless documented).
    4. Single Query: Write exactly one query per request, accompanied by a short plain-language note explaining what it returns.
    FROM sales SHOW total_sales SINCE -7d

  12. Use the HydrogenCart object for cart operations

    main

    The HydrogenCart type represents a high-level interface that aggregates various cart manipulation methods into a single object. Instead of calling individual ...Default functions, you can use the methods directly on a HydrogenCart instance.

    Available methods include:

    • Lines: addLines, updateLines, removeLines
    • Codes: updateDiscountCodes, updateGiftCardCodes, addGiftCardCodes, removeGiftCardCodes
    • Addresses: addDeliveryAddresses, removeDeliveryAddresses, updateDeliveryAddresses, replaceDeliveryAddresses
    • Metadata/Identity: updateBuyerIdentity, updateNote, updateAttributes, setMetafields, deleteMetafield
    • Selection: updateSelectedDeliveryOption
    • Core: get, create, getCartId, setCartId
    // Example usage of the aggregated HydrogenCart object
const result = await cart.addDeliveryAddresses([
  {
    address1: '123 Main St',
    city: 'Anytown',
    countryCode: 'US'
  }
], {
  someOptionalParam: 'value'
});