@klaudworks/shopify-mcp 1.1.0

package/dist/tools/getCustomerById.js

@@ -0,0 +1,122 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { handleToolError, edgesToNodes } from "../lib/toolUtils.js";
+// Input schema for getting a customer by ID
+const GetCustomerByIdInputSchema = z.object({
+    id: z.string().regex(/^\d+$/, "Customer ID must be numeric")
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const getCustomerById = {
+    name: "get-customer-by-id",
+    description: "Get a single customer by ID",
+    schema: GetCustomerByIdInputSchema,
+    // 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
+
+        query GetCustomerById($id: ID!) {
+          customer(id: $id) {
+            id
+            firstName
+            lastName
+            defaultEmailAddress {
+              emailAddress
+            }
+            defaultPhoneNumber {
+              phoneNumber
+            }
+            createdAt
+            updatedAt
+            tags
+            note
+            taxExempt
+            defaultAddress {
+              address1
+              address2
+              city
+              provinceCode
+              zip
+              country
+              phone
+            }
+            addressesV2(first: 10) {
+              edges {
+                node {
+                  address1
+                  address2
+                  city
+                  provinceCode
+                  zip
+                  country
+                  phone
+                }
+              }
+            }
+            amountSpent {
+              amount
+              currencyCode
+            }
+            numberOfOrders
+            metafields(first: 10) {
+              edges {
+                node {
+                  id
+                  namespace
+                  key
+                  value
+                }
+              }
+            }
+          }
+        }
+      `;
+            const variables = {
+                id: customerGid
+            };
+            const data = (await shopifyClient.request(query, variables));
+            if (!data.customer) {
+                throw new Error(`Customer with ID ${id} not found`);
+            }
+            const customer = data.customer;
+            // Format metafields if they exist
+            const metafields = customer.metafields
+                ? edgesToNodes(customer.metafields)
+                : [];
+            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,
+                    createdAt: customer.createdAt,
+                    updatedAt: customer.updatedAt,
+                    tags: customer.tags,
+                    note: customer.note,
+                    taxExempt: customer.taxExempt,
+                    defaultAddress: customer.defaultAddress,
+                    addresses,
+                    amountSpent: customer.amountSpent,
+                    numberOfOrders: customer.numberOfOrders,
+                    metafields
+                }
+            };
+        }
+        catch (error) {
+            handleToolError("fetch customer", error);
+        }
+    }
+};
+export { getCustomerById };

package/dist/tools/getCustomerOrders.js

@@ -0,0 +1,131 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { handleToolError, edgesToNodes } from "../lib/toolUtils.js";
+import { formatOrderSummary } from "../lib/formatters.js";
+// Input schema for getting customer orders
+const GetCustomerOrdersInputSchema = z.object({
+    customerId: z.string().regex(/^\d+$/, "Customer ID must be numeric"),
+    limit: z.number().default(10),
+    after: z.string().optional().describe("Cursor for forward pagination"),
+    before: z.string().optional().describe("Cursor for backward pagination"),
+    sortKey: z.enum([
+        "CREATED_AT", "ORDER_NUMBER", "TOTAL_PRICE", "FINANCIAL_STATUS",
+        "FULFILLMENT_STATUS", "UPDATED_AT", "CUSTOMER_NAME", "PROCESSED_AT",
+        "ID", "RELEVANCE"
+    ]).optional().describe("Sort key for orders"),
+    reverse: z.boolean().optional().describe("Reverse the sort order")
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const getCustomerOrders = {
+    name: "get-customer-orders",
+    description: "Get orders for a specific customer",
+    schema: GetCustomerOrdersInputSchema,
+    // Add initialize method to set up the GraphQL client
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const { customerId, limit, after, before, sortKey, reverse } = input;
+            // Query to get orders for a specific customer
+            const query = gql `
+        #graphql
+
+        query GetCustomerOrders($query: String!, $first: Int!, $after: String, $before: String, $sortKey: OrderSortKeys, $reverse: Boolean) {
+          orders(query: $query, first: $first, after: $after, before: $before, sortKey: $sortKey, reverse: $reverse) {
+            edges {
+              node {
+                id
+                name
+                createdAt
+                displayFinancialStatus
+                displayFulfillmentStatus
+                totalPriceSet {
+                  shopMoney {
+                    amount
+                    currencyCode
+                  }
+                }
+                subtotalPriceSet {
+                  shopMoney {
+                    amount
+                    currencyCode
+                  }
+                }
+                totalShippingPriceSet {
+                  shopMoney {
+                    amount
+                    currencyCode
+                  }
+                }
+                totalTaxSet {
+                  shopMoney {
+                    amount
+                    currencyCode
+                  }
+                }
+                customer {
+                  id
+                  firstName
+                  lastName
+                  defaultEmailAddress {
+                    emailAddress
+                  }
+                }
+                lineItems(first: 5) {
+                  edges {
+                    node {
+                      id
+                      title
+                      quantity
+                      originalTotalSet {
+                        shopMoney {
+                          amount
+                          currencyCode
+                        }
+                      }
+                      variant {
+                        id
+                        title
+                        sku
+                      }
+                    }
+                  }
+                }
+                tags
+                note
+              }
+            }
+            pageInfo {
+              hasNextPage
+              hasPreviousPage
+              startCursor
+              endCursor
+            }
+          }
+        }
+      `;
+            // We use the query parameter to filter orders by customer ID
+            const variables = {
+                query: `customer_id:${customerId}`,
+                first: limit,
+                ...(after && { after }),
+                ...(before && { before }),
+                ...(sortKey && { sortKey }),
+                ...(reverse !== undefined && { reverse })
+            };
+            const data = (await shopifyClient.request(query, variables));
+            // Extract and format order data
+            const orders = edgesToNodes(data.orders).map(formatOrderSummary);
+            return {
+                orders,
+                pageInfo: data.orders.pageInfo
+            };
+        }
+        catch (error) {
+            handleToolError("fetch customer orders", error);
+        }
+    }
+};
+export { getCustomerOrders };

package/dist/tools/getCustomers.js

@@ -0,0 +1,125 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { handleToolError, edgesToNodes } from "../lib/toolUtils.js";
+// Input schema for getCustomers
+const GetCustomersInputSchema = z.object({
+    searchQuery: z.string().optional().describe("Freetext search or Shopify query syntax (e.g. 'country:US tag:vip orders_count:>5')"),
+    limit: z.number().default(10),
+    after: z.string().optional().describe("Cursor for forward pagination"),
+    before: z.string().optional().describe("Cursor for backward pagination"),
+    sortKey: z.enum([
+        "CREATED_AT", "ID", "LAST_UPDATE", "LOCATION", "NAME",
+        "ORDERS_COUNT", "RELEVANCE", "TOTAL_SPENT", "UPDATED_AT"
+    ]).optional().describe("Sort key for customers"),
+    reverse: z.boolean().optional().describe("Reverse the sort order")
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const getCustomers = {
+    name: "get-customers",
+    description: "Get customers or search by name/email",
+    schema: GetCustomersInputSchema,
+    // Add initialize method to set up the GraphQL client
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const { searchQuery, limit, after, before, sortKey, reverse } = input;
+            const query = gql `
+        #graphql
+
+        query GetCustomers($first: Int!, $query: String, $after: String, $before: String, $sortKey: CustomerSortKeys, $reverse: Boolean) {
+          customers(first: $first, query: $query, after: $after, before: $before, sortKey: $sortKey, reverse: $reverse) {
+            edges {
+              node {
+                id
+                firstName
+                lastName
+                defaultEmailAddress {
+                  emailAddress
+                }
+                defaultPhoneNumber {
+                  phoneNumber
+                }
+                createdAt
+                updatedAt
+                tags
+                defaultAddress {
+                  address1
+                  address2
+                  city
+                  provinceCode
+                  zip
+                  country
+                  phone
+                }
+                addressesV2(first: 10) {
+                  edges {
+                    node {
+                      address1
+                      address2
+                      city
+                      provinceCode
+                      zip
+                      country
+                      phone
+                    }
+                  }
+                }
+                amountSpent {
+                  amount
+                  currencyCode
+                }
+                numberOfOrders
+              }
+            }
+            pageInfo {
+              hasNextPage
+              hasPreviousPage
+              startCursor
+              endCursor
+            }
+          }
+        }
+      `;
+            const variables = {
+                first: limit,
+                query: searchQuery,
+                ...(after && { after }),
+                ...(before && { before }),
+                ...(sortKey && { sortKey }),
+                ...(reverse !== undefined && { reverse })
+            };
+            const data = (await shopifyClient.request(query, variables));
+            // Extract and format customer data
+            const customers = data.customers.edges.map((edge) => {
+                const customer = edge.node;
+                return {
+                    id: customer.id,
+                    firstName: customer.firstName,
+                    lastName: customer.lastName,
+                    email: customer.defaultEmailAddress?.emailAddress || null,
+                    phone: customer.defaultPhoneNumber?.phoneNumber || null,
+                    createdAt: customer.createdAt,
+                    updatedAt: customer.updatedAt,
+                    tags: customer.tags,
+                    defaultAddress: customer.defaultAddress,
+                    addresses: customer.addressesV2
+                        ? edgesToNodes(customer.addressesV2)
+                        : [],
+                    amountSpent: customer.amountSpent,
+                    numberOfOrders: customer.numberOfOrders
+                };
+            });
+            return {
+                customers,
+                pageInfo: data.customers.pageInfo
+            };
+        }
+        catch (error) {
+            handleToolError("fetch customers", error);
+        }
+    }
+};
+export { getCustomers };

package/dist/tools/getFulfillmentOrders.js

@@ -0,0 +1,106 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { edgesToNodes, handleToolError } from "../lib/toolUtils.js";
+const GetFulfillmentOrdersInputSchema = z.object({
+    orderId: z
+        .string()
+        .min(1)
+        .describe("The order ID (e.g. gid://shopify/Order/123 or just 123)"),
+});
+let shopifyClient;
+const getFulfillmentOrders = {
+    name: "get-fulfillment-orders",
+    description: "Get fulfillment orders for an order including status, assigned location, delivery method, holds, and line items",
+    schema: GetFulfillmentOrdersInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const orderId = input.orderId.startsWith("gid://")
+                ? input.orderId
+                : `gid://shopify/Order/${input.orderId}`;
+            const query = gql `
+        #graphql
+
+        query GetFulfillmentOrders($id: ID!) {
+          order(id: $id) {
+            id
+            name
+            fulfillmentOrders(first: 25) {
+              edges {
+                node {
+                  id
+                  status
+                  requestStatus
+                  createdAt
+                  updatedAt
+                  fulfillAt
+                  fulfillBy
+                  assignedLocation {
+                    name
+                    address1
+                    address2
+                    city
+                    province
+                    countryCode
+                    zip
+                    phone
+                  }
+                  deliveryMethod {
+                    methodType
+                    minDeliveryDateTime
+                    maxDeliveryDateTime
+                    presentedName
+                    serviceCode
+                  }
+                  fulfillmentHolds {
+                    id
+                    reason
+                    reasonNotes
+                    displayReason
+                    heldByRequestingApp
+                  }
+                  lineItems(first: 50) {
+                    edges {
+                      node {
+                        id
+                        totalQuantity
+                        remainingQuantity
+                        productTitle
+                        variantTitle
+                        sku
+                      }
+                    }
+                  }
+                  supportedActions {
+                    action
+                    externalUrl
+                  }
+                }
+              }
+            }
+          }
+        }
+      `;
+            const data = await shopifyClient.request(query, { id: orderId });
+            if (!data.order) {
+                throw new Error(`Order not found: ${orderId}`);
+            }
+            const fulfillmentOrders = edgesToNodes(data.order.fulfillmentOrders).map((fo) => ({
+                ...fo,
+                lineItems: edgesToNodes(fo.lineItems),
+            }));
+            return {
+                orderId: data.order.id,
+                orderName: data.order.name,
+                fulfillmentOrdersCount: fulfillmentOrders.length,
+                fulfillmentOrders,
+            };
+        }
+        catch (error) {
+            handleToolError("fetch fulfillment orders", error);
+        }
+    },
+};
+export { getFulfillmentOrders };

package/dist/tools/getInventoryItems.js

@@ -0,0 +1,86 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { edgesToNodes, handleToolError } from "../lib/toolUtils.js";
+const GetInventoryItemsInputSchema = z.object({
+    productId: z
+        .string()
+        .min(1)
+        .describe("The product ID (e.g. gid://shopify/Product/123 or just 123)"),
+});
+let shopifyClient;
+const getInventoryItems = {
+    name: "get-inventory-items",
+    description: "Get inventory item details for all variants of a product including SKU, cost, tracked status, country of origin, and HS codes",
+    schema: GetInventoryItemsInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const productId = input.productId.startsWith("gid://")
+                ? input.productId
+                : `gid://shopify/Product/${input.productId}`;
+            const query = gql `
+        #graphql
+
+        query GetInventoryItems($id: ID!) {
+          product(id: $id) {
+            id
+            title
+            variants(first: 100) {
+              edges {
+                node {
+                  id
+                  title
+                  sku
+                  inventoryItem {
+                    id
+                    sku
+                    tracked
+                    requiresShipping
+                    unitCost {
+                      amount
+                      currencyCode
+                    }
+                    countryCodeOfOrigin
+                    provinceCodeOfOrigin
+                    harmonizedSystemCode
+                    measurement {
+                      weight {
+                        unit
+                        value
+                      }
+                    }
+                    locationsCount {
+                      count
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      `;
+            const data = await shopifyClient.request(query, { id: productId });
+            if (!data.product) {
+                throw new Error(`Product not found: ${productId}`);
+            }
+            const variants = edgesToNodes(data.product.variants).map((variant) => ({
+                variantId: variant.id,
+                variantTitle: variant.title,
+                variantSku: variant.sku,
+                inventoryItem: variant.inventoryItem,
+            }));
+            return {
+                productId: data.product.id,
+                productTitle: data.product.title,
+                variantsCount: variants.length,
+                variants,
+            };
+        }
+        catch (error) {
+            handleToolError("fetch inventory items", error);
+        }
+    },
+};
+export { getInventoryItems };

package/dist/tools/getInventoryLevels.js

@@ -0,0 +1,82 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { edgesToNodes, handleToolError } from "../lib/toolUtils.js";
+const GetInventoryLevelsInputSchema = z.object({
+    inventoryItemId: z
+        .string()
+        .min(1)
+        .describe("The inventory item ID (e.g. gid://shopify/InventoryItem/123 or just 123). Get this from getInventoryItems or product variant data."),
+});
+let shopifyClient;
+const getInventoryLevels = {
+    name: "get-inventory-levels",
+    description: "Get inventory quantities per location for an inventory item (available, on_hand, committed, reserved, incoming, damaged, etc.)",
+    schema: GetInventoryLevelsInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const inventoryItemId = input.inventoryItemId.startsWith("gid://")
+                ? input.inventoryItemId
+                : `gid://shopify/InventoryItem/${input.inventoryItemId}`;
+            const query = gql `
+        #graphql
+
+        query GetInventoryLevels($id: ID!) {
+          inventoryItem(id: $id) {
+            id
+            sku
+            tracked
+            inventoryLevels(first: 50) {
+              edges {
+                node {
+                  id
+                  location {
+                    id
+                    name
+                    isActive
+                  }
+                  quantities(
+                    names: [
+                      "available"
+                      "on_hand"
+                      "committed"
+                      "reserved"
+                      "incoming"
+                      "damaged"
+                      "quality_control"
+                      "safety_stock"
+                    ]
+                  ) {
+                    name
+                    quantity
+                  }
+                  updatedAt
+                }
+              }
+            }
+          }
+        }
+      `;
+            const data = await shopifyClient.request(query, {
+                id: inventoryItemId,
+            });
+            if (!data.inventoryItem) {
+                throw new Error(`Inventory item not found: ${inventoryItemId}`);
+            }
+            const levels = edgesToNodes(data.inventoryItem.inventoryLevels);
+            return {
+                inventoryItemId: data.inventoryItem.id,
+                sku: data.inventoryItem.sku,
+                tracked: data.inventoryItem.tracked,
+                levelsCount: levels.length,
+                levels,
+            };
+        }
+        catch (error) {
+            handleToolError("fetch inventory levels", error);
+        }
+    },
+};
+export { getInventoryLevels };