@klaudworks/shopify-mcp 1.1.0

package/dist/tools/createProduct.js

@@ -0,0 +1,123 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+// Input schema for creating a product
+const CreateProductInputSchema = z.object({
+    title: z.string().min(1),
+    descriptionHtml: z.string().optional(),
+    handle: z.string().optional().describe("URL slug, e.g. 'black-sunglasses'. Auto-generated from title if omitted."),
+    vendor: z.string().optional(),
+    productType: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    status: z.enum(["ACTIVE", "DRAFT", "ARCHIVED"]).default("DRAFT"),
+    seo: z
+        .object({
+        title: z.string().optional(),
+        description: z.string().optional(),
+    })
+        .optional()
+        .describe("SEO title and description for search engines"),
+    metafields: z
+        .array(z.object({
+        namespace: z.string(),
+        key: z.string(),
+        value: z.string(),
+        type: z.string().describe("Metafield type, e.g. 'single_line_text_field', 'json', 'number_integer'"),
+    }))
+        .optional(),
+    productOptions: z
+        .array(z.object({
+        name: z.string().describe("Option name, e.g. 'Size' or 'Color'"),
+        values: z
+            .array(z.object({ name: z.string() }))
+            .optional()
+            .describe("Option values"),
+    }))
+        .optional()
+        .describe("Product options to create inline (max 3)"),
+    collectionsToJoin: z
+        .array(z.string())
+        .optional()
+        .describe("Collection GIDs to add the product to"),
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const createProduct = {
+    name: "create-product",
+    description: "Create a new product. When using productOptions, Shopify registers all option values but only creates one default variant (first value of each option, price $0). Use manage-product-variants with strategy=REMOVE_STANDALONE_VARIANT afterward to create all real variants with prices.",
+    schema: CreateProductInputSchema,
+    // Add initialize method to set up the GraphQL client
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        mutation productCreate($product: ProductCreateInput!) {
+          productCreate(product: $product) {
+            product {
+              id
+              title
+              handle
+              descriptionHtml
+              vendor
+              productType
+              status
+              tags
+              seo {
+                title
+                description
+              }
+              options {
+                id
+                name
+                values
+              }
+              metafields(first: 10) {
+                edges {
+                  node {
+                    id
+                    namespace
+                    key
+                    value
+                  }
+                }
+              }
+            }
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const variables = {
+                product: input,
+            };
+            const data = (await shopifyClient.request(query, variables));
+            checkUserErrors(data.productCreate.userErrors, "create product");
+            const product = data.productCreate.product;
+            return {
+                product: {
+                    id: product.id,
+                    title: product.title,
+                    handle: product.handle,
+                    descriptionHtml: product.descriptionHtml,
+                    vendor: product.vendor,
+                    productType: product.productType,
+                    status: product.status,
+                    tags: product.tags,
+                    seo: product.seo,
+                    options: product.options,
+                    metafields: product.metafields?.edges.map((e) => e.node) || [],
+                },
+            };
+        }
+        catch (error) {
+            handleToolError("create product", error);
+        }
+    },
+};
+export { createProduct };

package/dist/tools/createRefund.js

@@ -0,0 +1,115 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+const CreateRefundInputSchema = z.object({
+    orderId: z.string().describe("The order GID, e.g. gid://shopify/Order/123"),
+    refundLineItems: z
+        .array(z.object({
+        lineItemId: z.string().describe("The line item GID to refund"),
+        quantity: z.number().describe("Quantity to refund"),
+        restockType: z
+            .enum(["CANCEL", "NO_RESTOCK", "RETURN"])
+            .optional()
+            .describe("How to restock: CANCEL (not yet fulfilled), RETURN (already fulfilled), NO_RESTOCK"),
+        locationId: z.string().optional().describe("Location GID for restocking"),
+    }))
+        .optional()
+        .describe("Line items to refund"),
+    shipping: z
+        .object({
+        amount: z.string().optional().describe("Shipping refund amount"),
+        fullRefund: z.boolean().optional().describe("Whether to fully refund shipping"),
+    })
+        .optional()
+        .describe("Shipping cost refund"),
+    note: z.string().optional().describe("Note attached to the refund"),
+    notify: z.boolean().optional().describe("Whether to send refund notification to customer"),
+    currency: z.string().optional().describe("Currency code if different from shop currency (presentment currency)"),
+});
+let shopifyClient;
+const createRefund = {
+    name: "refund-create",
+    description: "Create a full or partial refund for an order with optional restocking and shipping refund.",
+    schema: CreateRefundInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        mutation refundCreate($input: RefundInput!) {
+          refundCreate(input: $input) {
+            refund {
+              id
+              createdAt
+              note
+              totalRefundedSet {
+                shopMoney {
+                  amount
+                  currencyCode
+                }
+              }
+              refundLineItems(first: 20) {
+                edges {
+                  node {
+                    lineItem {
+                      id
+                      title
+                    }
+                    quantity
+                    restockType
+                  }
+                }
+              }
+            }
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const refundInput = {
+                orderId: input.orderId,
+            };
+            if (input.refundLineItems) {
+                refundInput.refundLineItems = input.refundLineItems;
+            }
+            if (input.shipping) {
+                refundInput.shipping = input.shipping;
+            }
+            if (input.note) {
+                refundInput.note = input.note;
+            }
+            if (input.notify !== undefined) {
+                refundInput.notify = input.notify;
+            }
+            if (input.currency) {
+                refundInput.currency = input.currency;
+            }
+            const data = (await shopifyClient.request(query, { input: refundInput }));
+            checkUserErrors(data.refundCreate.userErrors, "create refund");
+            const refund = data.refundCreate.refund;
+            return {
+                refund: {
+                    id: refund.id,
+                    createdAt: refund.createdAt,
+                    note: refund.note,
+                    totalRefunded: refund.totalRefundedSet?.shopMoney,
+                    lineItems: refund.refundLineItems.edges.map((e) => ({
+                        lineItemId: e.node.lineItem.id,
+                        title: e.node.lineItem.title,
+                        quantity: e.node.quantity,
+                        restockType: e.node.restockType,
+                    })),
+                },
+            };
+        }
+        catch (error) {
+            handleToolError("create refund", error);
+        }
+    },
+};
+export { createRefund };

package/dist/tools/deleteCustomer.js

@@ -0,0 +1,47 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+// Input schema for deleting a customer
+const DeleteCustomerInputSchema = z.object({
+    id: z.string().regex(/^\d+$/, "Customer ID must be numeric")
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const deleteCustomer = {
+    name: "delete-customer",
+    description: "Delete a customer",
+    schema: DeleteCustomerInputSchema,
+    // Add initialize method to set up the GraphQL client
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const { id } = input;
+            // Convert numeric ID to GID format
+            const customerGid = `gid://shopify/Customer/${id}`;
+            const query = gql `
+        #graphql
+
+        mutation customerDelete($input: CustomerDeleteInput!) {
+          customerDelete(input: $input) {
+            deletedCustomerId
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const data = (await shopifyClient.request(query, {
+                input: { id: customerGid }
+            }));
+            checkUserErrors(data.customerDelete.userErrors, "delete customer");
+            return { deletedCustomerId: data.customerDelete.deletedCustomerId };
+        }
+        catch (error) {
+            handleToolError("delete customer", error);
+        }
+    }
+};
+export { deleteCustomer };

package/dist/tools/deleteMetafields.js

@@ -0,0 +1,54 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+const DeleteMetafieldsInputSchema = z.object({
+    metafields: z
+        .array(z.object({
+        ownerId: z.string().describe("GID of the resource that owns the metafield"),
+        namespace: z.string().describe("Metafield namespace"),
+        key: z.string().describe("Metafield key"),
+    }))
+        .min(1)
+        .describe("Metafields to delete, identified by owner + namespace + key"),
+});
+let shopifyClient;
+const deleteMetafields = {
+    name: "delete-metafields",
+    description: "Delete metafields from any Shopify resource by specifying owner ID, namespace, and key.",
+    schema: DeleteMetafieldsInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        mutation metafieldsDelete($metafields: [MetafieldIdentifierInput!]!) {
+          metafieldsDelete(metafields: $metafields) {
+            deletedMetafields {
+              ownerId
+              namespace
+              key
+            }
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const data = (await shopifyClient.request(query, {
+                metafields: input.metafields,
+            }));
+            checkUserErrors(data.metafieldsDelete.userErrors, "delete metafields");
+            return {
+                deletedMetafields: data.metafieldsDelete.deletedMetafields || [],
+            };
+        }
+        catch (error) {
+            handleToolError("delete metafields", error);
+        }
+    },
+};
+export { deleteMetafields };

package/dist/tools/deleteProduct.js

@@ -0,0 +1,43 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+// Input schema for deleteProduct
+const DeleteProductInputSchema = z.object({
+    id: z.string().min(1).describe("Shopify product GID, e.g. gid://shopify/Product/123"),
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const deleteProduct = {
+    name: "delete-product",
+    description: "Delete a product",
+    schema: DeleteProductInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        mutation productDelete($input: ProductDeleteInput!) {
+          productDelete(input: $input) {
+            deletedProductId
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const data = (await shopifyClient.request(query, {
+                input: { id: input.id },
+            }));
+            checkUserErrors(data.productDelete.userErrors, "delete product");
+            return { deletedProductId: data.productDelete.deletedProductId };
+        }
+        catch (error) {
+            handleToolError("delete product", error);
+        }
+    },
+};
+export { deleteProduct };

package/dist/tools/deleteProductVariants.js

@@ -0,0 +1,82 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+// Input schema for deleteProductVariants
+const DeleteProductVariantsInputSchema = z.object({
+    productId: z.string().min(1).describe("Shopify product GID"),
+    variantIds: z.array(z.string().min(1)).min(1).describe("Array of variant GIDs to delete"),
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const deleteProductVariants = {
+    name: "delete-product-variants",
+    description: "Delete one or more variants from a product",
+    schema: DeleteProductVariantsInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const { productId, variantIds } = input;
+            const query = gql `
+        #graphql
+
+        mutation productVariantsBulkDelete(
+          $productId: ID!
+          $variantsIds: [ID!]!
+        ) {
+          productVariantsBulkDelete(
+            productId: $productId
+            variantsIds: $variantsIds
+          ) {
+            product {
+              id
+              title
+              variants(first: 20) {
+                edges {
+                  node {
+                    id
+                    title
+                    price
+                    sku
+                    selectedOptions {
+                      name
+                      value
+                    }
+                  }
+                }
+              }
+            }
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const data = (await shopifyClient.request(query, {
+                productId,
+                variantsIds: variantIds,
+            }));
+            checkUserErrors(data.productVariantsBulkDelete.userErrors, "delete variants");
+            const product = data.productVariantsBulkDelete.product;
+            return {
+                product: {
+                    id: product.id,
+                    title: product.title,
+                    remainingVariants: product.variants.edges.map((e) => ({
+                        id: e.node.id,
+                        title: e.node.title,
+                        price: e.node.price,
+                        sku: e.node.sku,
+                        options: e.node.selectedOptions,
+                    })),
+                },
+            };
+        }
+        catch (error) {
+            handleToolError("delete product variants", error);
+        }
+    },
+};
+export { deleteProductVariants };

package/dist/tools/getCollectionById.js

@@ -0,0 +1,123 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { edgesToNodes, handleToolError } from "../lib/toolUtils.js";
+const GetCollectionByIdInputSchema = z.object({
+    collectionId: z
+        .string()
+        .min(1)
+        .describe("The collection ID (e.g. gid://shopify/Collection/123 or just 123)"),
+    productsFirst: z
+        .number()
+        .min(0)
+        .max(100)
+        .default(25)
+        .optional()
+        .describe("Number of products to include (default 25, max 100, 0 to skip products)"),
+});
+let shopifyClient;
+const getCollectionById = {
+    name: "get-collection-by-id",
+    description: "Get a single collection with full details including products (paginated), rules for smart collections, SEO, and image",
+    schema: GetCollectionByIdInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const collectionId = input.collectionId.startsWith("gid://")
+                ? input.collectionId
+                : `gid://shopify/Collection/${input.collectionId}`;
+            const productsFirst = input.productsFirst ?? 25;
+            const query = gql `
+        #graphql
+
+        query GetCollectionById($id: ID!, $productsFirst: Int!) {
+          collection(id: $id) {
+            id
+            title
+            handle
+            descriptionHtml
+            sortOrder
+            templateSuffix
+            updatedAt
+            productsCount {
+              count
+            }
+            ruleSet {
+              appliedDisjunctively
+              rules {
+                column
+                relation
+                condition
+              }
+            }
+            image {
+              url
+              altText
+              width
+              height
+            }
+            seo {
+              title
+              description
+            }
+            products(first: $productsFirst) {
+              edges {
+                node {
+                  id
+                  title
+                  handle
+                  status
+                  vendor
+                  productType
+                  totalInventory
+                  featuredMedia {
+                    preview {
+                      image {
+                        url
+                        altText
+                      }
+                    }
+                  }
+                  priceRangeV2 {
+                    minVariantPrice {
+                      amount
+                      currencyCode
+                    }
+                    maxVariantPrice {
+                      amount
+                      currencyCode
+                    }
+                  }
+                }
+              }
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
+            }
+          }
+        }
+      `;
+            const data = await shopifyClient.request(query, {
+                id: collectionId,
+                productsFirst,
+            });
+            if (!data.collection) {
+                throw new Error(`Collection not found: ${collectionId}`);
+            }
+            const collection = {
+                ...data.collection,
+                products: {
+                    items: edgesToNodes(data.collection.products),
+                    pageInfo: data.collection.products.pageInfo,
+                },
+            };
+            return { collection };
+        }
+        catch (error) {
+            handleToolError("fetch collection", error);
+        }
+    },
+};
+export { getCollectionById };

package/dist/tools/getCollections.js

@@ -0,0 +1,88 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { edgesToNodes, handleToolError } from "../lib/toolUtils.js";
+const GetCollectionsInputSchema = z.object({
+    first: z
+        .number()
+        .min(1)
+        .max(100)
+        .default(25)
+        .optional()
+        .describe("Number of collections to return (default 25, max 100)"),
+    query: z
+        .string()
+        .optional()
+        .describe("Search query to filter collections (e.g. 'title:Summer' or 'collection_type:smart')"),
+});
+let shopifyClient;
+const getCollections = {
+    name: "get-collections",
+    description: "Query collections (manual & smart) with optional filtering. Returns title, handle, products count, sort order, and rules for smart collections.",
+    schema: GetCollectionsInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        query GetCollections($first: Int!, $query: String) {
+          collections(first: $first, query: $query) {
+            edges {
+              node {
+                id
+                title
+                handle
+                description
+                sortOrder
+                productsCount {
+                  count
+                }
+                templateSuffix
+                updatedAt
+                ruleSet {
+                  appliedDisjunctively
+                  rules {
+                    column
+                    relation
+                    condition
+                  }
+                }
+                image {
+                  url
+                  altText
+                }
+                seo {
+                  title
+                  description
+                }
+              }
+            }
+            pageInfo {
+              hasNextPage
+              endCursor
+            }
+          }
+        }
+      `;
+            const variables = {
+                first: input.first ?? 25,
+            };
+            if (input.query) {
+                variables.query = input.query;
+            }
+            const data = await shopifyClient.request(query, variables);
+            const collections = edgesToNodes(data.collections);
+            return {
+                collectionsCount: collections.length,
+                collections,
+                pageInfo: data.collections.pageInfo,
+            };
+        }
+        catch (error) {
+            handleToolError("fetch collections", error);
+        }
+    },
+};
+export { getCollections };