@klaudworks/shopify-mcp 1.1.0

package/dist/tools/getOrderTransactions.js

@@ -0,0 +1,85 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { handleToolError } from "../lib/toolUtils.js";
+const GetOrderTransactionsInputSchema = z.object({
+    orderId: z
+        .string()
+        .min(1)
+        .describe("The order ID (e.g. gid://shopify/Order/123 or just 123)"),
+});
+let shopifyClient;
+const getOrderTransactions = {
+    name: "get-order-transactions",
+    description: "Get all payment transactions for an order including authorizations, captures, refunds, and voids with gateway, status, and amounts",
+    schema: GetOrderTransactionsInputSchema,
+    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 GetOrderTransactions($id: ID!) {
+          order(id: $id) {
+            id
+            name
+            transactions {
+              id
+              kind
+              status
+              gateway
+              formattedGateway
+              amountSet {
+                shopMoney {
+                  amount
+                  currencyCode
+                }
+                presentmentMoney {
+                  amount
+                  currencyCode
+                }
+              }
+              processedAt
+              createdAt
+              authorizationCode
+              authorizationExpiresAt
+              errorCode
+              test
+              parentTransaction {
+                id
+                kind
+              }
+              paymentDetails {
+                ... on CardPaymentDetails {
+                  company
+                  number
+                  name
+                }
+              }
+              receiptJson
+            }
+          }
+        }
+      `;
+            const data = await shopifyClient.request(query, { id: orderId });
+            if (!data.order) {
+                throw new Error(`Order not found: ${orderId}`);
+            }
+            const transactions = data.order.transactions;
+            return {
+                orderId: data.order.id,
+                orderName: data.order.name,
+                transactionsCount: transactions.length,
+                transactions,
+            };
+        }
+        catch (error) {
+            handleToolError("fetch order transactions", error);
+        }
+    },
+};
+export { getOrderTransactions };

package/dist/tools/getOrders.js

@@ -0,0 +1,148 @@
+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 getOrders
+const GetOrdersInputSchema = z.object({
+    status: z.enum(["any", "open", "closed", "cancelled"]).default("any"),
+    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"),
+    query: z.string().optional().describe("Raw query string for advanced filtering (e.g. 'financial_status:paid fulfillment_status:shipped')")
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const getOrders = {
+    name: "get-orders",
+    description: "Get orders with optional filtering by status",
+    schema: GetOrdersInputSchema,
+    // Add initialize method to set up the GraphQL client
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const { status, limit, after, before, sortKey, reverse, query: rawQuery } = input;
+            // Build query filters
+            const queryParts = [];
+            if (status !== "any") {
+                queryParts.push(`status:${status}`);
+            }
+            if (rawQuery) {
+                queryParts.push(rawQuery);
+            }
+            const queryFilter = queryParts.join(" ") || undefined;
+            const query = gql `
+        #graphql
+
+        query GetOrders($first: Int!, $query: String, $after: String, $before: String, $sortKey: OrderSortKeys, $reverse: Boolean) {
+          orders(first: $first, query: $query, 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
+                  }
+                }
+                shippingAddress {
+                  address1
+                  address2
+                  city
+                  provinceCode
+                  zip
+                  country
+                  phone
+                }
+                lineItems(first: 10) {
+                  edges {
+                    node {
+                      id
+                      title
+                      quantity
+                      originalTotalSet {
+                        shopMoney {
+                          amount
+                          currencyCode
+                        }
+                      }
+                      variant {
+                        id
+                        title
+                        sku
+                      }
+                    }
+                  }
+                }
+                tags
+                note
+              }
+            }
+            pageInfo {
+              hasNextPage
+              hasPreviousPage
+              startCursor
+              endCursor
+            }
+          }
+        }
+      `;
+            const variables = {
+                first: limit,
+                query: queryFilter,
+                ...(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 orders", error);
+        }
+    }
+};
+export { getOrders };

package/dist/tools/getPriceLists.js

@@ -0,0 +1,92 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { edgesToNodes, handleToolError } from "../lib/toolUtils.js";
+const GetPriceListsInputSchema = z.object({
+    first: z
+        .number()
+        .min(1)
+        .max(50)
+        .default(25)
+        .optional()
+        .describe("Number of price lists to return (default 25, max 50)"),
+});
+let shopifyClient;
+const getPriceLists = {
+    name: "get-price-lists",
+    description: "Get all price lists with their currency, fixed/relative adjustments, and associated catalog context",
+    schema: GetPriceListsInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        query GetPriceLists($first: Int!) {
+          priceLists(first: $first) {
+            edges {
+              node {
+                id
+                name
+                currency
+                fixedPricesCount
+                parent {
+                  adjustment {
+                    type
+                    value
+                  }
+                }
+                catalog {
+                  ... on MarketCatalog {
+                    id
+                    title
+                  }
+                }
+                prices(first: 10) {
+                  edges {
+                    node {
+                      variant {
+                        id
+                        title
+                        product {
+                          id
+                          title
+                        }
+                      }
+                      price {
+                        amount
+                        currencyCode
+                      }
+                      compareAtPrice {
+                        amount
+                        currencyCode
+                      }
+                      originType
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      `;
+            const variables = {
+                first: input.first ?? 25,
+            };
+            const data = await shopifyClient.request(query, variables);
+            const priceLists = edgesToNodes(data.priceLists).map((priceList) => ({
+                ...priceList,
+                prices: edgesToNodes(priceList.prices),
+            }));
+            return {
+                priceListsCount: priceLists.length,
+                priceLists,
+            };
+        }
+        catch (error) {
+            handleToolError("fetch price lists", error);
+        }
+    },
+};
+export { getPriceLists };

package/dist/tools/getProductById.js

@@ -0,0 +1,171 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { handleToolError } from "../lib/toolUtils.js";
+// Input schema for getProductById
+const GetProductByIdInputSchema = z.object({
+    productId: z.string().min(1)
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const getProductById = {
+    name: "get-product-by-id",
+    description: "Get a specific product by ID",
+    schema: GetProductByIdInputSchema,
+    // Add initialize method to set up the GraphQL client
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const { productId } = input;
+            const query = gql `
+        #graphql
+
+        query GetProductById($id: ID!) {
+          product(id: $id) {
+            id
+            title
+            description
+            handle
+            status
+            createdAt
+            updatedAt
+            totalInventory
+            priceRangeV2 {
+              minVariantPrice {
+                amount
+                currencyCode
+              }
+              maxVariantPrice {
+                amount
+                currencyCode
+              }
+            }
+            media(first: 5) {
+              edges {
+                node {
+                  ... on MediaImage {
+                    id
+                    image {
+                      url
+                      altText
+                      width
+                      height
+                    }
+                  }
+                }
+              }
+            }
+            variants(first: 20) {
+              edges {
+                node {
+                  id
+                  title
+                  price
+                  inventoryQuantity
+                  sku
+                  selectedOptions {
+                    name
+                    value
+                  }
+                }
+              }
+            }
+            collections(first: 5) {
+              edges {
+                node {
+                  id
+                  title
+                }
+              }
+            }
+            tags
+            vendor
+            productType
+            descriptionHtml
+            seo {
+              title
+              description
+            }
+            options {
+              id
+              name
+              position
+              optionValues {
+                id
+                name
+              }
+            }
+          }
+        }
+      `;
+            const variables = {
+                id: productId
+            };
+            const data = (await shopifyClient.request(query, variables));
+            if (!data.product) {
+                throw new Error(`Product with ID ${productId} not found`);
+            }
+            // Format product data
+            const product = data.product;
+            // Format variants
+            const variants = product.variants.edges.map((variantEdge) => ({
+                id: variantEdge.node.id,
+                title: variantEdge.node.title,
+                price: variantEdge.node.price,
+                inventoryQuantity: variantEdge.node.inventoryQuantity,
+                sku: variantEdge.node.sku,
+                options: variantEdge.node.selectedOptions
+            }));
+            // Format images from media
+            const images = product.media.edges
+                .filter((mediaEdge) => mediaEdge.node.image)
+                .map((mediaEdge) => ({
+                id: mediaEdge.node.id,
+                url: mediaEdge.node.image.url,
+                altText: mediaEdge.node.image.altText,
+                width: mediaEdge.node.image.width,
+                height: mediaEdge.node.image.height
+            }));
+            // Format collections
+            const collections = product.collections.edges.map((collectionEdge) => ({
+                id: collectionEdge.node.id,
+                title: collectionEdge.node.title
+            }));
+            const formattedProduct = {
+                id: product.id,
+                title: product.title,
+                description: product.description,
+                handle: product.handle,
+                status: product.status,
+                createdAt: product.createdAt,
+                updatedAt: product.updatedAt,
+                totalInventory: product.totalInventory,
+                priceRange: {
+                    minPrice: {
+                        amount: product.priceRangeV2.minVariantPrice.amount,
+                        currencyCode: product.priceRangeV2.minVariantPrice.currencyCode
+                    },
+                    maxPrice: {
+                        amount: product.priceRangeV2.maxVariantPrice.amount,
+                        currencyCode: product.priceRangeV2.maxVariantPrice.currencyCode
+                    }
+                },
+                images,
+                variants,
+                collections,
+                tags: product.tags,
+                vendor: product.vendor,
+                productType: product.productType,
+                descriptionHtml: product.descriptionHtml,
+                seo: product.seo,
+                options: product.options
+            };
+            return { product: formattedProduct };
+        }
+        catch (error) {
+            handleToolError("fetch product", error);
+        }
+    }
+};
+export { getProductById };

package/dist/tools/getProductVariantsDetailed.js

@@ -0,0 +1,139 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { edgesToNodes, handleToolError } from "../lib/toolUtils.js";
+const GetProductVariantsDetailedInputSchema = z.object({
+    productId: z
+        .string()
+        .min(1)
+        .describe("The product ID (e.g. gid://shopify/Product/123 or just 123)"),
+    first: z
+        .number()
+        .min(1)
+        .max(100)
+        .default(50)
+        .optional()
+        .describe("Number of variants to return (default 50, max 100)"),
+});
+let shopifyClient;
+const getProductVariantsDetailed = {
+    name: "get-product-variants-detailed",
+    description: "Get all variant fields for a product: pricing, inventory, barcode, weight, tax code, selected options, metafields, and image",
+    schema: GetProductVariantsDetailedInputSchema,
+    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 GetProductVariantsDetailed($id: ID!, $first: Int!) {
+          product(id: $id) {
+            id
+            title
+            variants(first: $first) {
+              edges {
+                node {
+                  id
+                  title
+                  displayName
+                  sku
+                  barcode
+                  price
+                  compareAtPrice
+                  taxable
+                  availableForSale
+                  inventoryQuantity
+                  position
+                  createdAt
+                  updatedAt
+                  selectedOptions {
+                    name
+                    value
+                  }
+                  media(first: 1) {
+                    edges {
+                      node {
+                        ... on MediaImage {
+                          image {
+                            url
+                            altText
+                          }
+                        }
+                      }
+                    }
+                  }
+                  inventoryItem {
+                    id
+                    tracked
+                    requiresShipping
+                    unitCost {
+                      amount
+                      currencyCode
+                    }
+                    measurement {
+                      weight {
+                        unit
+                        value
+                      }
+                    }
+                  }
+                  metafields(first: 25) {
+                    edges {
+                      node {
+                        namespace
+                        key
+                        value
+                        type
+                      }
+                    }
+                  }
+                }
+              }
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
+            }
+          }
+        }
+      `;
+            const data = await shopifyClient.request(query, {
+                id: productId,
+                first: input.first ?? 50,
+            });
+            if (!data.product) {
+                throw new Error(`Product not found: ${productId}`);
+            }
+            const variants = edgesToNodes(data.product.variants).map((variant) => {
+                const mediaNodes = variant.media
+                    ? edgesToNodes(variant.media)
+                    : [];
+                const firstImage = mediaNodes.find((m) => m.image);
+                const image = firstImage?.image ?? null;
+                delete variant.media;
+                return {
+                    ...variant,
+                    image,
+                    metafields: variant.metafields
+                        ? edgesToNodes(variant.metafields)
+                        : [],
+                };
+            });
+            return {
+                productId: data.product.id,
+                productTitle: data.product.title,
+                variantsCount: variants.length,
+                variants,
+                pageInfo: data.product.variants.pageInfo,
+            };
+        }
+        catch (error) {
+            handleToolError("fetch product variants", error);
+        }
+    },
+};
+export { getProductVariantsDetailed };