@klaudworks/shopify-mcp 1.1.0

package/dist/tools/manageProductVariants.js

@@ -0,0 +1,203 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+// Input schema for manageProductVariants
+const VariantOptionSchema = z.object({
+    optionName: z.string().describe("Option name, e.g. 'Size' or 'Color'"),
+    name: z.string().describe("Option value, e.g. '8x10' or 'Black'"),
+});
+const VariantSchema = z.object({
+    id: z.string().optional().describe("Variant GID for updates. Omit to create new."),
+    price: z.string().optional().describe("Price as string, e.g. '49.00'"),
+    compareAtPrice: z.string().optional().describe("Compare-at price for showing discounts, e.g. '79.00'"),
+    sku: z.string().optional().describe("SKU for the variant (mapped to inventoryItem.sku)"),
+    tracked: z.boolean().optional().describe("Whether inventory is tracked. Set false for print-on-demand."),
+    taxable: z.boolean().optional().describe("Whether the variant is taxable"),
+    barcode: z.string().optional(),
+    weight: z.number().optional().describe("Weight of the variant"),
+    weightUnit: z.enum(["GRAMS", "KILOGRAMS", "OUNCES", "POUNDS"]).optional().describe("Unit of weight"),
+    optionValues: z.array(VariantOptionSchema).optional(),
+});
+const ManageProductVariantsInputSchema = z.object({
+    productId: z.string().min(1).describe("Shopify product GID"),
+    variants: z.array(VariantSchema).min(1).describe("Variants to create or update"),
+    strategy: z
+        .enum(["DEFAULT", "REMOVE_STANDALONE_VARIANT", "PRESERVE_STANDALONE_VARIANT"])
+        .optional()
+        .describe("Strategy for handling the standalone 'Default Title' variant when creating. DEFAULT removes it automatically."),
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const manageProductVariants = {
+    name: "manage-product-variants",
+    description: "Create or update product variants. Omit variant id to create new, include id to update existing.",
+    schema: ManageProductVariantsInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const { productId, variants } = input;
+            // Split into creates and updates
+            const toCreate = variants.filter((v) => !v.id);
+            const toUpdate = variants.filter((v) => v.id);
+            const results = {
+                created: [],
+                updated: [],
+            };
+            // Bulk create new variants
+            if (toCreate.length > 0) {
+                const createQuery = gql `
+          #graphql
+
+          mutation productVariantsBulkCreate(
+            $productId: ID!
+            $variants: [ProductVariantsBulkInput!]!
+            $strategy: ProductVariantsBulkCreateStrategy
+          ) {
+            productVariantsBulkCreate(
+              productId: $productId
+              variants: $variants
+              strategy: $strategy
+            ) {
+              productVariants {
+                id
+                title
+                price
+                sku
+                selectedOptions {
+                  name
+                  value
+                }
+              }
+              userErrors {
+                field
+                message
+              }
+            }
+          }
+        `;
+                const createVariants = toCreate.map((v) => {
+                    const variant = {};
+                    if (v.price)
+                        variant.price = v.price;
+                    if (v.compareAtPrice)
+                        variant.compareAtPrice = v.compareAtPrice;
+                    if (v.barcode)
+                        variant.barcode = v.barcode;
+                    if (v.taxable !== undefined)
+                        variant.taxable = v.taxable;
+                    // sku and tracked both go under inventoryItem
+                    const inventoryItem = {};
+                    if (v.sku)
+                        inventoryItem.sku = v.sku;
+                    if (v.tracked !== undefined)
+                        inventoryItem.tracked = v.tracked;
+                    if (v.weight !== undefined) {
+                        inventoryItem.measurement = { weight: { value: v.weight, unit: v.weightUnit || 'GRAMS' } };
+                    }
+                    if (Object.keys(inventoryItem).length > 0)
+                        variant.inventoryItem = inventoryItem;
+                    if (v.optionValues) {
+                        variant.optionValues = v.optionValues.map((ov) => ({
+                            optionName: ov.optionName,
+                            name: ov.name,
+                        }));
+                    }
+                    return variant;
+                });
+                const createData = (await shopifyClient.request(createQuery, {
+                    productId,
+                    variants: createVariants,
+                    ...(input.strategy && { strategy: input.strategy }),
+                }));
+                checkUserErrors(createData.productVariantsBulkCreate.userErrors, "create variants");
+                results.created =
+                    createData.productVariantsBulkCreate.productVariants.map((v) => ({
+                        id: v.id,
+                        title: v.title,
+                        price: v.price,
+                        sku: v.sku,
+                        options: v.selectedOptions,
+                    }));
+            }
+            // Bulk update existing variants
+            if (toUpdate.length > 0) {
+                const updateQuery = gql `
+          #graphql
+
+          mutation productVariantsBulkUpdate(
+            $productId: ID!
+            $variants: [ProductVariantsBulkInput!]!
+          ) {
+            productVariantsBulkUpdate(
+              productId: $productId
+              variants: $variants
+            ) {
+              productVariants {
+                id
+                title
+                price
+                sku
+                selectedOptions {
+                  name
+                  value
+                }
+              }
+              userErrors {
+                field
+                message
+              }
+            }
+          }
+        `;
+                const updateVariants = toUpdate.map((v) => {
+                    const variant = { id: v.id };
+                    if (v.price)
+                        variant.price = v.price;
+                    if (v.compareAtPrice)
+                        variant.compareAtPrice = v.compareAtPrice;
+                    if (v.barcode)
+                        variant.barcode = v.barcode;
+                    if (v.taxable !== undefined)
+                        variant.taxable = v.taxable;
+                    const inventoryItem = {};
+                    if (v.sku)
+                        inventoryItem.sku = v.sku;
+                    if (v.tracked !== undefined)
+                        inventoryItem.tracked = v.tracked;
+                    if (v.weight !== undefined) {
+                        inventoryItem.measurement = { weight: { value: v.weight, unit: v.weightUnit || 'GRAMS' } };
+                    }
+                    if (Object.keys(inventoryItem).length > 0)
+                        variant.inventoryItem = inventoryItem;
+                    if (v.optionValues) {
+                        variant.optionValues = v.optionValues.map((ov) => ({
+                            optionName: ov.optionName,
+                            name: ov.name,
+                        }));
+                    }
+                    return variant;
+                });
+                const updateData = (await shopifyClient.request(updateQuery, {
+                    productId,
+                    variants: updateVariants,
+                }));
+                checkUserErrors(updateData.productVariantsBulkUpdate.userErrors, "update variants");
+                results.updated =
+                    updateData.productVariantsBulkUpdate.productVariants.map((v) => ({
+                        id: v.id,
+                        title: v.title,
+                        price: v.price,
+                        sku: v.sku,
+                        options: v.selectedOptions,
+                    }));
+            }
+            return results;
+        }
+        catch (error) {
+            handleToolError("manage product variants", error);
+        }
+    },
+};
+export { manageProductVariants };

package/dist/tools/manageTags.js

@@ -0,0 +1,79 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+const ManageTagsInputSchema = z.object({
+    id: z.string().describe("GID of the resource (order, product, customer, draft order, or article)"),
+    tags: z.array(z.string()).min(1).describe("Tags to add or remove"),
+    action: z.enum(["add", "remove"]).describe("Whether to add or remove the tags"),
+});
+let shopifyClient;
+const manageTags = {
+    name: "manage-tags",
+    description: "Add or remove tags on any taggable resource (orders, products, customers, draft orders, articles).",
+    schema: ManageTagsInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            if (input.action === "add") {
+                const query = gql `
+          #graphql
+
+          mutation tagsAdd($id: ID!, $tags: [String!]!) {
+            tagsAdd(id: $id, tags: $tags) {
+              node {
+                id
+              }
+              userErrors {
+                field
+                message
+              }
+            }
+          }
+        `;
+                const data = (await shopifyClient.request(query, {
+                    id: input.id,
+                    tags: input.tags,
+                }));
+                checkUserErrors(data.tagsAdd.userErrors, "add tags");
+                return {
+                    id: data.tagsAdd.node?.id,
+                    action: "add",
+                    tags: input.tags,
+                };
+            }
+            else {
+                const query = gql `
+          #graphql
+
+          mutation tagsRemove($id: ID!, $tags: [String!]!) {
+            tagsRemove(id: $id, tags: $tags) {
+              node {
+                id
+              }
+              userErrors {
+                field
+                message
+              }
+            }
+          }
+        `;
+                const data = (await shopifyClient.request(query, {
+                    id: input.id,
+                    tags: input.tags,
+                }));
+                checkUserErrors(data.tagsRemove.userErrors, "remove tags");
+                return {
+                    id: data.tagsRemove.node?.id,
+                    action: "remove",
+                    tags: input.tags,
+                };
+            }
+        }
+        catch (error) {
+            handleToolError(`${input.action} tags`, error);
+        }
+    },
+};
+export { manageTags };

package/dist/tools/mergeCustomers.js

@@ -0,0 +1,74 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+const MergeCustomersInputSchema = z.object({
+    customerOneId: z.string().describe("GID of the first customer"),
+    customerTwoId: z.string().describe("GID of the second customer"),
+    overrideFields: z
+        .object({
+        customerIdOfFirstNameToKeep: z.string().optional().describe("Customer GID whose first name to keep"),
+        customerIdOfLastNameToKeep: z.string().optional().describe("Customer GID whose last name to keep"),
+        customerIdOfEmailToKeep: z.string().optional().describe("Customer GID whose email to keep"),
+        customerIdOfPhoneNumberToKeep: z.string().optional().describe("Customer GID whose phone to keep"),
+        customerIdOfDefaultAddressToKeep: z.string().optional().describe("Customer GID whose default address to keep"),
+        note: z.string().optional().describe("Note to keep on the merged customer"),
+        tags: z.array(z.string()).optional().describe("Tags to keep on the merged customer"),
+    })
+        .optional()
+        .describe("Override default merge rules for specific fields"),
+});
+let shopifyClient;
+const mergeCustomers = {
+    name: "customer-merge",
+    description: "Merge two customer records into one. Optionally override which fields to keep from which customer.",
+    schema: MergeCustomersInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        mutation customerMerge(
+          $customerOneId: ID!
+          $customerTwoId: ID!
+          $overrideFields: CustomerMergeOverrideFields
+        ) {
+          customerMerge(
+            customerOneId: $customerOneId
+            customerTwoId: $customerTwoId
+            overrideFields: $overrideFields
+          ) {
+            resultingCustomerId
+            job {
+              id
+              done
+            }
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const variables = {
+                customerOneId: input.customerOneId,
+                customerTwoId: input.customerTwoId,
+            };
+            if (input.overrideFields) {
+                variables.overrideFields = input.overrideFields;
+            }
+            const data = (await shopifyClient.request(query, variables));
+            checkUserErrors(data.customerMerge.userErrors, "merge customers");
+            return {
+                resultingCustomerId: data.customerMerge.resultingCustomerId,
+                job: data.customerMerge.job,
+            };
+        }
+        catch (error) {
+            handleToolError("merge customers", error);
+        }
+    },
+};
+export { mergeCustomers };

package/dist/tools/orderCancel.js

@@ -0,0 +1,77 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+const OrderCancelInputSchema = z.object({
+    orderId: z.string().describe("The order GID, e.g. gid://shopify/Order/123"),
+    reason: z.enum(["CUSTOMER", "DECLINED", "FRAUD", "INVENTORY", "OTHER", "STAFF"]).describe("Reason for cancellation"),
+    restock: z.boolean().describe("Whether to restock inventory"),
+    notifyCustomer: z.boolean().default(false).describe("Whether to notify the customer"),
+    staffNote: z.string().optional().describe("Internal note (not visible to customer)"),
+    refund: z.boolean().optional().describe("Whether to refund to the original payment method"),
+});
+let shopifyClient;
+const orderCancel = {
+    name: "order-cancel",
+    description: "Cancel an order with options for refunding, restocking inventory, and customer notification. Cancellation is irreversible.",
+    schema: OrderCancelInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        mutation orderCancel(
+          $orderId: ID!
+          $reason: OrderCancelReason!
+          $restock: Boolean!
+          $notifyCustomer: Boolean
+          $staffNote: String
+          $refundMethod: OrderCancelRefundMethodInput
+        ) {
+          orderCancel(
+            orderId: $orderId
+            reason: $reason
+            restock: $restock
+            notifyCustomer: $notifyCustomer
+            staffNote: $staffNote
+            refundMethod: $refundMethod
+          ) {
+            job {
+              id
+              done
+            }
+            orderCancelUserErrors {
+              field
+              message
+              code
+            }
+          }
+        }
+      `;
+            const variables = {
+                orderId: input.orderId,
+                reason: input.reason,
+                restock: input.restock,
+                notifyCustomer: input.notifyCustomer,
+                ...(input.staffNote && { staffNote: input.staffNote }),
+            };
+            if (input.refund !== undefined) {
+                variables.refundMethod = {
+                    originalPaymentMethodsRefund: input.refund,
+                };
+            }
+            const data = (await shopifyClient.request(query, variables));
+            checkUserErrors(data.orderCancel.orderCancelUserErrors, "cancel order");
+            return {
+                job: data.orderCancel.job,
+                message: "Order cancellation initiated successfully",
+            };
+        }
+        catch (error) {
+            handleToolError("cancel order", error);
+        }
+    },
+};
+export { orderCancel };

package/dist/tools/orderCloseOpen.js

@@ -0,0 +1,74 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+const OrderCloseOpenInputSchema = z.object({
+    orderId: z.string().describe("The order GID, e.g. gid://shopify/Order/123"),
+    action: z.enum(["close", "open"]).describe("Whether to close or open the order"),
+});
+let shopifyClient;
+const orderCloseOpen = {
+    name: "order-close-open",
+    description: "Close or reopen an order. Closing marks all items fulfilled and finances complete. Opening reopens a closed order.",
+    schema: OrderCloseOpenInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            if (input.action === "close") {
+                const query = gql `
+          #graphql
+
+          mutation orderClose($input: OrderCloseInput!) {
+            orderClose(input: $input) {
+              order {
+                id
+                name
+                closed
+                closedAt
+              }
+              userErrors {
+                field
+                message
+              }
+            }
+          }
+        `;
+                const data = (await shopifyClient.request(query, {
+                    input: { id: input.orderId },
+                }));
+                checkUserErrors(data.orderClose.userErrors, "close order");
+                return { order: data.orderClose.order };
+            }
+            else {
+                const query = gql `
+          #graphql
+
+          mutation orderOpen($input: OrderOpenInput!) {
+            orderOpen(input: $input) {
+              order {
+                id
+                name
+                closed
+                closedAt
+              }
+              userErrors {
+                field
+                message
+              }
+            }
+          }
+        `;
+                const data = (await shopifyClient.request(query, {
+                    input: { id: input.orderId },
+                }));
+                checkUserErrors(data.orderOpen.userErrors, "open order");
+                return { order: data.orderOpen.order };
+            }
+        }
+        catch (error) {
+            handleToolError(`${input.action} order`, error);
+        }
+    },
+};
+export { orderCloseOpen };

package/dist/tools/orderMarkAsPaid.js

@@ -0,0 +1,51 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+const OrderMarkAsPaidInputSchema = z.object({
+    orderId: z.string().describe("The order GID, e.g. gid://shopify/Order/123"),
+});
+let shopifyClient;
+const orderMarkAsPaid = {
+    name: "order-mark-as-paid",
+    description: "Mark an order as paid. Useful for manual/offline payments (cash, bank deposit, etc.).",
+    schema: OrderMarkAsPaidInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        mutation orderMarkAsPaid($input: OrderMarkAsPaidInput!) {
+          orderMarkAsPaid(input: $input) {
+            order {
+              id
+              name
+              displayFinancialStatus
+              totalPriceSet {
+                shopMoney {
+                  amount
+                  currencyCode
+                }
+              }
+            }
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const data = (await shopifyClient.request(query, {
+                input: { id: input.orderId },
+            }));
+            checkUserErrors(data.orderMarkAsPaid.userErrors, "mark order as paid");
+            return { order: data.orderMarkAsPaid.order };
+        }
+        catch (error) {
+            handleToolError("mark order as paid", error);
+        }
+    },
+};
+export { orderMarkAsPaid };

package/dist/tools/registry.js

@@ -0,0 +1,106 @@
+// Product tools
+import { getProducts } from "./getProducts.js";
+import { getProductById } from "./getProductById.js";
+import { createProduct } from "./createProduct.js";
+import { updateProduct } from "./updateProduct.js";
+import { deleteProduct } from "./deleteProduct.js";
+import { manageProductVariants } from "./manageProductVariants.js";
+import { deleteProductVariants } from "./deleteProductVariants.js";
+import { manageProductOptions } from "./manageProductOptions.js";
+// Order tools
+import { getOrders } from "./getOrders.js";
+import { getOrderById } from "./getOrderById.js";
+import { updateOrder } from "./updateOrder.js";
+import { createDraftOrder } from "./createDraftOrder.js";
+import { completeDraftOrder } from "./completeDraftOrder.js";
+import { orderCancel } from "./orderCancel.js";
+import { orderCloseOpen } from "./orderCloseOpen.js";
+import { orderMarkAsPaid } from "./orderMarkAsPaid.js";
+import { createFulfillment } from "./createFulfillment.js";
+import { createRefund } from "./createRefund.js";
+// Customer tools
+import { getCustomers } from "./getCustomers.js";
+import { getCustomerById } from "./getCustomerById.js";
+import { getCustomerOrders } from "./getCustomerOrders.js";
+import { createCustomer } from "./createCustomer.js";
+import { updateCustomer } from "./updateCustomer.js";
+import { deleteCustomer } from "./deleteCustomer.js";
+import { mergeCustomers } from "./mergeCustomers.js";
+import { manageCustomerAddress } from "./manageCustomerAddress.js";
+// Metafield tools
+import { getMetafields } from "./getMetafields.js";
+import { setMetafields } from "./setMetafields.js";
+import { deleteMetafields } from "./deleteMetafields.js";
+// Convenience / cross-resource tools
+import { manageTags } from "./manageTags.js";
+import { setInventoryQuantities } from "./setInventoryQuantities.js";
+// Configuration & discovery tools
+import { getShopInfo } from "./getShopInfo.js";
+import { getMetafieldDefinitions } from "./getMetafieldDefinitions.js";
+import { getLocations } from "./getLocations.js";
+import { getMarkets } from "./getMarkets.js";
+import { getCollections } from "./getCollections.js";
+// Enhanced order & fulfillment tools
+import { getOrderTransactions } from "./getOrderTransactions.js";
+import { getFulfillmentOrders } from "./getFulfillmentOrders.js";
+import { getOrderRefundDetails } from "./getOrderRefundDetails.js";
+import { getCollectionById } from "./getCollectionById.js";
+// Inventory & pricing read tools
+import { getInventoryLevels } from "./getInventoryLevels.js";
+import { getInventoryItems } from "./getInventoryItems.js";
+import { getPriceLists } from "./getPriceLists.js";
+import { getProductVariantsDetailed } from "./getProductVariantsDetailed.js";
+export const tools = [
+    // Products (8)
+    getProducts,
+    getProductById,
+    createProduct,
+    updateProduct,
+    deleteProduct,
+    manageProductVariants,
+    deleteProductVariants,
+    manageProductOptions,
+    // Orders (10)
+    getOrders,
+    getOrderById,
+    updateOrder,
+    createDraftOrder,
+    completeDraftOrder,
+    orderCancel,
+    orderCloseOpen,
+    orderMarkAsPaid,
+    createFulfillment,
+    createRefund,
+    // Customers (8)
+    getCustomers,
+    getCustomerById,
+    getCustomerOrders,
+    createCustomer,
+    updateCustomer,
+    deleteCustomer,
+    mergeCustomers,
+    manageCustomerAddress,
+    // Metafields (3)
+    getMetafields,
+    setMetafields,
+    deleteMetafields,
+    // Convenience (2)
+    manageTags,
+    setInventoryQuantities,
+    // Configuration & discovery (5)
+    getShopInfo,
+    getMetafieldDefinitions,
+    getLocations,
+    getMarkets,
+    getCollections,
+    // Enhanced order & fulfillment (4)
+    getOrderTransactions,
+    getFulfillmentOrders,
+    getOrderRefundDetails,
+    getCollectionById,
+    // Inventory & pricing reads (4)
+    getInventoryLevels,
+    getInventoryItems,
+    getPriceLists,
+    getProductVariantsDetailed,
+];