@klaudworks/shopify-mcp 1.1.0

package/dist/lib/formatters.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+// ── Shared Zod schemas ────────────────────────────────────────────────
+/**
+ * Mailing address schema shared by createDraftOrder (shipping + billing)
+ * and manageCustomerAddress. Uses countryCode/provinceCode (API input type).
+ *
+ * NOTE: updateOrder.shippingAddress intentionally uses country/province
+ * (different Shopify input type) and is NOT shared here.
+ */
+export const shippingAddressSchema = z.object({
+    address1: z.string().optional(),
+    address2: z.string().optional(),
+    city: z.string().optional(),
+    company: z.string().optional(),
+    countryCode: z.string().optional().describe("Two-letter country code"),
+    firstName: z.string().optional(),
+    lastName: z.string().optional(),
+    phone: z.string().optional().describe("Phone in E.164 format, e.g. +16135551111"),
+    provinceCode: z.string().optional(),
+    zip: z.string().optional(),
+});
+/**
+ * Format a line-item connection into a clean array.
+ * Used by getOrders, getOrderById, and getCustomerOrders.
+ */
+export function formatLineItems(lineItems) {
+    return lineItems.edges.map((edge) => {
+        const item = edge.node;
+        return {
+            id: item.id,
+            title: item.title,
+            quantity: item.quantity,
+            originalTotal: item.originalTotalSet.shopMoney,
+            variant: item.variant
+                ? {
+                    id: item.variant.id,
+                    title: item.variant.title,
+                    sku: item.variant.sku,
+                }
+                : null,
+        };
+    });
+}
+/**
+ * Format a raw order node into the standard order summary shape.
+ * Used by getOrders, getCustomerOrders, and getOrderById (as a base).
+ */
+export function formatOrderSummary(order) {
+    return {
+        id: order.id,
+        name: order.name,
+        createdAt: order.createdAt,
+        financialStatus: order.displayFinancialStatus,
+        fulfillmentStatus: order.displayFulfillmentStatus,
+        totalPrice: order.totalPriceSet.shopMoney,
+        subtotalPrice: order.subtotalPriceSet.shopMoney,
+        totalShippingPrice: order.totalShippingPriceSet.shopMoney,
+        totalTax: order.totalTaxSet.shopMoney,
+        customer: order.customer
+            ? {
+                id: order.customer.id,
+                firstName: order.customer.firstName,
+                lastName: order.customer.lastName,
+                email: order.customer.defaultEmailAddress?.emailAddress || null,
+            }
+            : null,
+        shippingAddress: order.shippingAddress,
+        lineItems: formatLineItems(order.lineItems),
+        tags: order.tags,
+        note: order.note,
+    };
+}

package/dist/lib/shopifyAuth.js

@@ -0,0 +1,96 @@
+/**
+ * Shopify OAuth Client Credentials flow.
+ *
+ * As of January 1 2026 Shopify no longer exposes static Admin API access
+ * tokens in the UI.  New apps created in the Dev Dashboard receive a
+ * client_id + client_secret pair which must be exchanged for a short-lived
+ * access token (expires_in ≈ 86 400 s / 24 h).
+ *
+ * This module handles the token exchange and transparent refresh so the
+ * rest of the codebase can keep using a plain access-token string.
+ */
+// Refresh 5 minutes before actual expiry to avoid race conditions.
+const REFRESH_MARGIN_MS = 5 * 60 * 1000;
+export class ShopifyAuth {
+    constructor(config) {
+        this.accessToken = null;
+        this.expiresAt = 0;
+        this.refreshTimer = null;
+        this.graphqlClient = null;
+        this.config = config;
+    }
+    /** Attach the GraphQL client so the token can be hot-swapped on refresh. */
+    setGraphQLClient(client) {
+        this.graphqlClient = client;
+    }
+    /** Fetch an initial token. Must be called before the server starts. */
+    async initialize() {
+        await this.fetchToken();
+        this.scheduleRefresh();
+        return this.accessToken;
+    }
+    /** Return the current (valid) access token. */
+    getAccessToken() {
+        if (!this.accessToken) {
+            throw new Error("ShopifyAuth not initialized — call initialize() first");
+        }
+        return this.accessToken;
+    }
+    /** Stop the background refresh timer (for clean shutdown). */
+    destroy() {
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Internal
+    // ---------------------------------------------------------------------------
+    async fetchToken() {
+        const url = `https://${this.config.shopDomain}/admin/oauth/access_token`;
+        const body = new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: this.config.clientId,
+            client_secret: this.config.clientSecret,
+        });
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body,
+        });
+        if (!res.ok) {
+            // Cap the echoed body: it should only ever be a short OAuth error like
+            // {"error":"invalid_client"}, but truncate defensively so an unexpected
+            // large/sensitive response is never propagated wholesale into logs.
+            const text = (await res.text()).slice(0, 200);
+            throw new Error(`Shopify token exchange failed (${res.status}): ${text}`);
+        }
+        const data = (await res.json());
+        this.accessToken = data.access_token;
+        this.expiresAt = Date.now() + data.expires_in * 1000;
+        // Hot-swap the header on the existing GraphQL client so every tool
+        // automatically picks up the new token.
+        if (this.graphqlClient) {
+            this.graphqlClient.setHeader("X-Shopify-Access-Token", this.accessToken);
+        }
+    }
+    scheduleRefresh() {
+        const msUntilRefresh = this.expiresAt - Date.now() - REFRESH_MARGIN_MS;
+        const delay = Math.max(msUntilRefresh, 0);
+        this.refreshTimer = setTimeout(async () => {
+            try {
+                await this.fetchToken();
+                this.scheduleRefresh();
+            }
+            catch (err) {
+                console.error("Failed to refresh Shopify access token:", err);
+                // Retry in 60 s rather than dying.
+                this.refreshTimer = setTimeout(() => this.scheduleRefresh(), 60000);
+            }
+        }, delay);
+        // Allow the Node process to exit even if the timer is pending.
+        if (this.refreshTimer && typeof this.refreshTimer === "object" && "unref" in this.refreshTimer) {
+            this.refreshTimer.unref();
+        }
+    }
+}

package/dist/lib/toolUtils.js

@@ -0,0 +1,36 @@
+// ── Utility functions ─────────────────────────────────────────────────
+/**
+ * Throw a formatted error if Shopify userErrors array is non-empty.
+ */
+export function checkUserErrors(errors, operation) {
+    if (errors.length > 0) {
+        throw new Error(`Failed to ${operation}: ${errors
+            .map((e) => `${e.field}: ${e.message}`)
+            .join(", ")}`);
+    }
+}
+/**
+ * Catch handler that doesn't re-wrap errors already thrown by checkUserErrors.
+ * Fixes the double-wrapping bug where "Failed to X: Failed to X: actual message"
+ * was produced by every mutation tool.
+ */
+export function handleToolError(operation, error) {
+    // If the error already has our "Failed to" prefix, re-throw as-is
+    if (error instanceof Error && error.message.startsWith("Failed to ")) {
+        throw error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to ${operation}: ${message}`);
+}
+/**
+ * Extract nodes from a Shopify connection's edges array.
+ */
+export function edgesToNodes(connection) {
+    return connection.edges.map((edge) => edge.node);
+}
+/**
+ * Extract shopMoney from a Shopify MoneyBag (e.g. totalPriceSet.shopMoney).
+ */
+export function shopMoney(moneyBag) {
+    return moneyBag?.shopMoney ?? null;
+}

package/dist/tools/completeDraftOrder.js

@@ -0,0 +1,76 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+const CompleteDraftOrderInputSchema = z.object({
+    draftOrderId: z.string().describe("The draft order GID, e.g. gid://shopify/DraftOrder/123"),
+    paymentGatewayId: z.string().optional().describe("Payment gateway GID (optional)"),
+});
+let shopifyClient;
+const completeDraftOrder = {
+    name: "complete-draft-order",
+    description: "Complete a draft order, converting it into a real order. Optionally specify a payment gateway.",
+    schema: CompleteDraftOrderInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        mutation draftOrderComplete($id: ID!, $paymentGatewayId: ID) {
+          draftOrderComplete(id: $id, paymentGatewayId: $paymentGatewayId) {
+            draftOrder {
+              id
+              status
+              order {
+                id
+                name
+                displayFinancialStatus
+                displayFulfillmentStatus
+                totalPriceSet {
+                  shopMoney {
+                    amount
+                    currencyCode
+                  }
+                }
+              }
+            }
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const variables = {
+                id: input.draftOrderId,
+            };
+            if (input.paymentGatewayId) {
+                variables.paymentGatewayId = input.paymentGatewayId;
+            }
+            const data = (await shopifyClient.request(query, variables));
+            checkUserErrors(data.draftOrderComplete.userErrors, "complete draft order");
+            const draft = data.draftOrderComplete.draftOrder;
+            return {
+                draftOrder: {
+                    id: draft.id,
+                    status: draft.status,
+                    order: draft.order
+                        ? {
+                            id: draft.order.id,
+                            name: draft.order.name,
+                            financialStatus: draft.order.displayFinancialStatus,
+                            fulfillmentStatus: draft.order.displayFulfillmentStatus,
+                            totalPrice: draft.order.totalPriceSet?.shopMoney,
+                        }
+                        : null,
+                },
+            };
+        }
+        catch (error) {
+            handleToolError("complete draft order", error);
+        }
+    },
+};
+export { completeDraftOrder };

package/dist/tools/createCustomer.js

@@ -0,0 +1,142 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError, edgesToNodes } from "../lib/toolUtils.js";
+// Input schema for creating a customer
+const CreateCustomerInputSchema = z.object({
+    firstName: z.string().optional(),
+    lastName: z.string().optional(),
+    email: z.string().email().optional(),
+    phone: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    note: z.string().optional(),
+    taxExempt: z.boolean().optional(),
+    metafields: z
+        .array(z.object({
+        namespace: z.string(),
+        key: z.string(),
+        value: z.string(),
+        type: z.string().optional()
+    }))
+        .optional(),
+    addresses: z
+        .array(z.object({
+        address1: z.string().optional(),
+        address2: z.string().optional(),
+        city: z.string().optional(),
+        provinceCode: z.string().optional(),
+        zip: z.string().optional(),
+        countryCode: z.string().optional(),
+        phone: z.string().optional()
+    }))
+        .optional()
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const createCustomer = {
+    name: "create-customer",
+    description: "Create a new customer",
+    schema: CreateCustomerInputSchema,
+    // Add initialize method to set up the GraphQL client
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        mutation customerCreate($input: CustomerInput!) {
+          customerCreate(input: $input) {
+            customer {
+              id
+              firstName
+              lastName
+              defaultEmailAddress {
+                emailAddress
+              }
+              defaultPhoneNumber {
+                phoneNumber
+              }
+              tags
+              note
+              taxExempt
+              createdAt
+              updatedAt
+              defaultAddress {
+                address1
+                address2
+                city
+                provinceCode
+                zip
+                country
+                phone
+              }
+              addressesV2(first: 10) {
+                edges {
+                  node {
+                    address1
+                    address2
+                    city
+                    provinceCode
+                    zip
+                    country
+                    phone
+                  }
+                }
+              }
+              metafields(first: 10) {
+                edges {
+                  node {
+                    id
+                    namespace
+                    key
+                    value
+                  }
+                }
+              }
+            }
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const variables = {
+                input: {
+                    ...input
+                }
+            };
+            const data = (await shopifyClient.request(query, variables));
+            checkUserErrors(data.customerCreate.userErrors, "create customer");
+            // Format and return the created customer
+            const customer = data.customerCreate.customer;
+            // Format metafields if they exist
+            const metafields = customer.metafields?.edges.map((edge) => edge.node) || [];
+            const addresses = customer.addressesV2
+                ? edgesToNodes(customer.addressesV2)
+                : [];
+            return {
+                customer: {
+                    id: customer.id,
+                    firstName: customer.firstName,
+                    lastName: customer.lastName,
+                    email: customer.defaultEmailAddress?.emailAddress || null,
+                    phone: customer.defaultPhoneNumber?.phoneNumber || null,
+                    tags: customer.tags,
+                    note: customer.note,
+                    taxExempt: customer.taxExempt,
+                    createdAt: customer.createdAt,
+                    updatedAt: customer.updatedAt,
+                    defaultAddress: customer.defaultAddress,
+                    addresses,
+                    metafields
+                }
+            };
+        }
+        catch (error) {
+            handleToolError("create customer", error);
+        }
+    }
+};
+export { createCustomer };

package/dist/tools/createDraftOrder.js

@@ -0,0 +1,160 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+import { shippingAddressSchema } from "../lib/formatters.js";
+const CreateDraftOrderInputSchema = z.object({
+    lineItems: z
+        .array(z.object({
+        variantId: z.string().optional().describe("Product variant GID. Required for existing products, omit for custom line items."),
+        title: z.string().optional().describe("Title for custom line items (ignored when variantId is set)"),
+        quantity: z.number().describe("Quantity of the line item"),
+        originalUnitPriceWithCurrency: z
+            .object({
+            amount: z.string().describe("Price amount as string"),
+            currencyCode: z.string().describe("Currency code, e.g. 'USD'"),
+        })
+            .optional()
+            .describe("Custom price for custom line items"),
+        sku: z.string().optional().describe("SKU for custom line items"),
+        taxable: z.boolean().optional().describe("Whether custom line item is taxable"),
+        requiresShipping: z.boolean().optional().describe("Whether custom line item requires shipping"),
+    }))
+        .min(1)
+        .describe("Line items (max 499). Use variantId for existing products or title+price for custom items."),
+    customerId: z.string().optional().describe("Customer GID to associate with the draft order"),
+    email: z.string().optional().describe("Customer email"),
+    phone: z.string().optional().describe("Customer phone"),
+    note: z.string().optional().describe("Note for the draft order"),
+    tags: z.array(z.string()).optional().describe("Tags for the draft order"),
+    shippingAddress: shippingAddressSchema.optional(),
+    billingAddress: shippingAddressSchema.optional(),
+    useCustomerDefaultAddress: z.boolean().optional().describe("Use customer's default address"),
+    taxExempt: z.boolean().optional().describe("Whether the draft order is tax exempt"),
+    poNumber: z.string().optional().describe("Purchase order number"),
+    appliedDiscount: z
+        .object({
+        title: z.string().optional().describe("Discount title"),
+        description: z.string().optional(),
+        value: z.number().describe("Discount value"),
+        valueType: z.enum(["FIXED_AMOUNT", "PERCENTAGE"]).describe("Whether value is fixed or percentage"),
+    })
+        .optional()
+        .describe("Order-level discount"),
+});
+let shopifyClient;
+const createDraftOrder = {
+    name: "create-draft-order",
+    description: "Create a draft order for phone/chat sales, invoicing, or wholesale. Supports custom line items, discounts, and customer association.",
+    schema: CreateDraftOrderInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        mutation draftOrderCreate($input: DraftOrderInput!) {
+          draftOrderCreate(input: $input) {
+            draftOrder {
+              id
+              name
+              status
+              totalPriceSet {
+                shopMoney {
+                  amount
+                  currencyCode
+                }
+              }
+              subtotalPriceSet {
+                shopMoney {
+                  amount
+                  currencyCode
+                }
+              }
+              customer {
+                id
+                firstName
+                lastName
+              }
+              lineItems(first: 20) {
+                edges {
+                  node {
+                    id
+                    title
+                    quantity
+                    originalTotalSet {
+                      shopMoney {
+                        amount
+                        currencyCode
+                      }
+                    }
+                  }
+                }
+              }
+              tags
+              note2
+              createdAt
+            }
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const draftInput = {
+                lineItems: input.lineItems,
+            };
+            if (input.customerId) {
+                draftInput.purchasingEntity = { customerId: input.customerId };
+            }
+            if (input.email)
+                draftInput.email = input.email;
+            if (input.phone)
+                draftInput.phone = input.phone;
+            if (input.note)
+                draftInput.note = input.note;
+            if (input.tags)
+                draftInput.tags = input.tags;
+            if (input.shippingAddress)
+                draftInput.shippingAddress = input.shippingAddress;
+            if (input.billingAddress)
+                draftInput.billingAddress = input.billingAddress;
+            if (input.useCustomerDefaultAddress !== undefined)
+                draftInput.useCustomerDefaultAddress = input.useCustomerDefaultAddress;
+            if (input.taxExempt !== undefined)
+                draftInput.taxExempt = input.taxExempt;
+            if (input.poNumber)
+                draftInput.poNumber = input.poNumber;
+            if (input.appliedDiscount)
+                draftInput.appliedDiscount = input.appliedDiscount;
+            const data = (await shopifyClient.request(query, { input: draftInput }));
+            checkUserErrors(data.draftOrderCreate.userErrors, "create draft order");
+            const draft = data.draftOrderCreate.draftOrder;
+            return {
+                draftOrder: {
+                    id: draft.id,
+                    name: draft.name,
+                    status: draft.status,
+                    totalPrice: draft.totalPriceSet?.shopMoney,
+                    subtotalPrice: draft.subtotalPriceSet?.shopMoney,
+                    customer: draft.customer,
+                    lineItems: draft.lineItems.edges.map((e) => ({
+                        id: e.node.id,
+                        title: e.node.title,
+                        quantity: e.node.quantity,
+                        originalTotal: e.node.originalTotalSet?.shopMoney,
+                    })),
+                    tags: draft.tags,
+                    note: draft.note2,
+                    createdAt: draft.createdAt,
+                },
+            };
+        }
+        catch (error) {
+            handleToolError("create draft order", error);
+        }
+    },
+};
+export { createDraftOrder };

package/dist/tools/createFulfillment.js

@@ -0,0 +1,100 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+const CreateFulfillmentInputSchema = z.object({
+    lineItemsByFulfillmentOrder: z
+        .array(z.object({
+        fulfillmentOrderId: z.string().describe("The fulfillment order GID"),
+        fulfillmentOrderLineItems: z
+            .array(z.object({
+            id: z.string().describe("The fulfillment order line item GID"),
+            quantity: z.number().describe("Quantity to fulfill"),
+        }))
+            .optional()
+            .describe("Specific line items to fulfill. If omitted, all line items are fulfilled."),
+    }))
+        .min(1)
+        .describe("Fulfillment orders and their line items to fulfill"),
+    trackingInfo: z
+        .object({
+        number: z.string().optional().describe("Tracking number"),
+        url: z.string().optional().describe("Tracking URL"),
+        company: z.string().optional().describe("Tracking company name (use exact Shopify-known names)"),
+    })
+        .optional()
+        .describe("Tracking information for the shipment"),
+    notifyCustomer: z.boolean().default(false).describe("Whether to send shipping notification to customer"),
+});
+let shopifyClient;
+const createFulfillment = {
+    name: "create-fulfillment",
+    description: "Create a fulfillment (mark items as shipped) with optional tracking info and customer notification.",
+    schema: CreateFulfillmentInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        mutation fulfillmentCreate($fulfillment: FulfillmentInput!) {
+          fulfillmentCreate(fulfillment: $fulfillment) {
+            fulfillment {
+              id
+              status
+              createdAt
+              trackingInfo {
+                number
+                url
+                company
+              }
+              fulfillmentLineItems(first: 20) {
+                edges {
+                  node {
+                    id
+                    quantity
+                    lineItem {
+                      title
+                    }
+                  }
+                }
+              }
+            }
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      `;
+            const fulfillment = {
+                lineItemsByFulfillmentOrder: input.lineItemsByFulfillmentOrder,
+                notifyCustomer: input.notifyCustomer,
+            };
+            if (input.trackingInfo) {
+                fulfillment.trackingInfo = input.trackingInfo;
+            }
+            const data = (await shopifyClient.request(query, { fulfillment }));
+            checkUserErrors(data.fulfillmentCreate.userErrors, "create fulfillment");
+            const f = data.fulfillmentCreate.fulfillment;
+            return {
+                fulfillment: {
+                    id: f.id,
+                    status: f.status,
+                    createdAt: f.createdAt,
+                    trackingInfo: f.trackingInfo,
+                    lineItems: f.fulfillmentLineItems.edges.map((e) => ({
+                        id: e.node.id,
+                        quantity: e.node.quantity,
+                        title: e.node.lineItem.title,
+                    })),
+                },
+            };
+        }
+        catch (error) {
+            handleToolError("create fulfillment", error);
+        }
+    },
+};
+export { createFulfillment };