@klaudworks/shopify-mcp 1.1.0

package/dist/tools/getLocations.js

@@ -0,0 +1,85 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { edgesToNodes, handleToolError } from "../lib/toolUtils.js";
+const GetLocationsInputSchema = z.object({
+    includeInactive: z
+        .boolean()
+        .default(false)
+        .optional()
+        .describe("Whether to include deactivated locations (default false)"),
+    first: z
+        .number()
+        .min(1)
+        .max(100)
+        .default(50)
+        .optional()
+        .describe("Number of locations to return (default 50, max 100)"),
+});
+let shopifyClient;
+const getLocations = {
+    name: "get-locations",
+    description: "Get all inventory/fulfillment locations with addresses, capabilities, and active status",
+    schema: GetLocationsInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        query GetLocations($first: Int!, $includeInactive: Boolean!) {
+          locations(first: $first, includeInactive: $includeInactive) {
+            edges {
+              node {
+                id
+                name
+                isActive
+                isFulfillmentService
+                fulfillsOnlineOrders
+                shipsInventory
+                hasActiveInventory
+                hasUnfulfilledOrders
+                address {
+                  address1
+                  address2
+                  city
+                  province
+                  provinceCode
+                  country
+                  countryCode
+                  zip
+                  phone
+                  latitude
+                  longitude
+                }
+                fulfillmentService {
+                  serviceName
+                  handle
+                }
+                localPickupSettingsV2 {
+                  instructions
+                  pickupTime
+                }
+              }
+            }
+          }
+        }
+      `;
+            const variables = {
+                first: input.first ?? 50,
+                includeInactive: input.includeInactive ?? false,
+            };
+            const data = await shopifyClient.request(query, variables);
+            const locations = edgesToNodes(data.locations);
+            return {
+                locationsCount: locations.length,
+                locations,
+            };
+        }
+        catch (error) {
+            handleToolError("fetch locations", error);
+        }
+    },
+};
+export { getLocations };

package/dist/tools/getMarkets.js

@@ -0,0 +1,91 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { edgesToNodes, handleToolError } from "../lib/toolUtils.js";
+const GetMarketsInputSchema = z.object({
+    first: z
+        .number()
+        .min(1)
+        .max(50)
+        .default(25)
+        .optional()
+        .describe("Number of markets to return (default 25, max 50)"),
+});
+let shopifyClient;
+const getMarkets = {
+    name: "get-markets",
+    description: "Get all markets with their regions, currencies, status, and web presence configuration",
+    schema: GetMarketsInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        query GetMarkets($first: Int!) {
+          markets(first: $first) {
+            edges {
+              node {
+                id
+                name
+                handle
+                status
+                type
+                currencySettings {
+                  baseCurrency {
+                    currencyCode
+                    currencyName
+                  }
+                  localCurrencies
+                }
+                webPresences(first: 10) {
+                  edges {
+                    node {
+                      id
+                      subfolderSuffix
+                      defaultLocale {
+                        locale
+                        name
+                        primary
+                        published
+                      }
+                      alternateLocales {
+                        locale
+                        name
+                        published
+                      }
+                      domain {
+                        id
+                        host
+                        url
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      `;
+            const variables = {
+                first: input.first ?? 25,
+            };
+            const data = await shopifyClient.request(query, variables);
+            const markets = edgesToNodes(data.markets).map((market) => ({
+                ...market,
+                webPresences: market.webPresences
+                    ? edgesToNodes(market.webPresences)
+                    : [],
+            }));
+            return {
+                marketsCount: markets.length,
+                markets,
+            };
+        }
+        catch (error) {
+            handleToolError("fetch markets", error);
+        }
+    },
+};
+export { getMarkets };

package/dist/tools/getMetafieldDefinitions.js

@@ -0,0 +1,112 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { edgesToNodes, handleToolError } from "../lib/toolUtils.js";
+/** Map common underscore aliases to their correct Shopify API enum values */
+const OWNER_TYPE_NORMALIZE = {
+    PRODUCT_VARIANT: "PRODUCTVARIANT",
+    DRAFT_ORDER: "DRAFTORDER",
+    CART_TRANSFORM: "CARTTRANSFORM",
+};
+const GetMetafieldDefinitionsInputSchema = z.object({
+    ownerType: z
+        .enum([
+        "API_PERMISSION",
+        "ARTICLE",
+        "BLOG",
+        "CART_TRANSFORM",
+        "CARTTRANSFORM",
+        "COLLECTION",
+        "COMPANY",
+        "COMPANY_LOCATION",
+        "CUSTOMER",
+        "DELIVERY_CUSTOMIZATION",
+        "DISCOUNT",
+        "DRAFT_ORDER",
+        "DRAFTORDER",
+        "FULFILLMENT_CONSTRAINT_RULE",
+        "GIFT_CARD_TRANSACTION",
+        "LOCATION",
+        "MARKET",
+        "MEDIA_IMAGE",
+        "ORDER",
+        "ORDER_ROUTING_LOCATION_RULE",
+        "PAGE",
+        "PAYMENT_CUSTOMIZATION",
+        "PRODUCT",
+        "PRODUCT_VARIANT",
+        "PRODUCTVARIANT",
+        "SELLING_PLAN",
+        "SHOP",
+        "VALIDATION",
+    ])
+        .describe("The resource type to get metafield definitions for (e.g. PRODUCT, ORDER, CUSTOMER). " +
+        "Note: Some Shopify types use concatenated names without underscores " +
+        "(PRODUCTVARIANT not PRODUCT_VARIANT, DRAFTORDER not DRAFT_ORDER, CARTTRANSFORM not CART_TRANSFORM). " +
+        "Underscore aliases are accepted and normalized automatically."),
+    first: z
+        .number()
+        .min(1)
+        .max(100)
+        .default(50)
+        .optional()
+        .describe("Number of definitions to return (default 50, max 100)"),
+});
+let shopifyClient;
+const getMetafieldDefinitions = {
+    name: "get-metafield-definitions",
+    description: "Discover custom metafield definitions for any resource type (PRODUCT, ORDER, CUSTOMER, etc.). Returns namespace, key, name, type, and validations.",
+    schema: GetMetafieldDefinitionsInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        query GetMetafieldDefinitions(
+          $ownerType: MetafieldOwnerType!
+          $first: Int!
+        ) {
+          metafieldDefinitions(ownerType: $ownerType, first: $first) {
+            edges {
+              node {
+                id
+                namespace
+                key
+                name
+                description
+                ownerType
+                pinnedPosition
+                type {
+                  name
+                  category
+                }
+                validations {
+                  name
+                  type
+                  value
+                }
+              }
+            }
+          }
+        }
+      `;
+            const variables = {
+                ownerType: OWNER_TYPE_NORMALIZE[input.ownerType] ?? input.ownerType,
+                first: input.first ?? 50,
+            };
+            const data = await shopifyClient.request(query, variables);
+            const definitions = edgesToNodes(data.metafieldDefinitions);
+            return {
+                ownerType: input.ownerType,
+                definitionsCount: definitions.length,
+                definitions,
+            };
+        }
+        catch (error) {
+            handleToolError("fetch metafield definitions", error);
+        }
+    },
+};
+export { getMetafieldDefinitions };

package/dist/tools/getMetafields.js

@@ -0,0 +1,68 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { handleToolError } from "../lib/toolUtils.js";
+const GetMetafieldsInputSchema = z.object({
+    ownerId: z.string().describe("GID of the resource (product, order, customer, variant, collection, etc.)"),
+    namespace: z.string().optional().describe("Filter metafields by namespace"),
+    first: z.number().default(25).describe("Number of metafields to return (max 50)"),
+    after: z.string().optional().describe("Cursor for pagination"),
+});
+let shopifyClient;
+const getMetafields = {
+    name: "get-metafields",
+    description: "Get metafields for any Shopify resource (products, orders, customers, variants, collections, etc.). Uses the node query with HasMetafields interface.",
+    schema: GetMetafieldsInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        query GetMetafields($ownerId: ID!, $first: Int!, $namespace: String, $after: String) {
+          node(id: $ownerId) {
+            ... on HasMetafields {
+              metafields(first: $first, namespace: $namespace, after: $after) {
+                edges {
+                  node {
+                    id
+                    namespace
+                    key
+                    value
+                    type
+                    updatedAt
+                  }
+                }
+                pageInfo {
+                  hasNextPage
+                  endCursor
+                }
+              }
+            }
+          }
+        }
+      `;
+            const data = (await shopifyClient.request(query, {
+                ownerId: input.ownerId,
+                first: input.first,
+                ...(input.namespace && { namespace: input.namespace }),
+                ...(input.after && { after: input.after }),
+            }));
+            if (!data.node) {
+                throw new Error(`Resource with ID ${input.ownerId} not found`);
+            }
+            if (!data.node.metafields) {
+                throw new Error(`Resource ${input.ownerId} does not support metafields`);
+            }
+            return {
+                metafields: data.node.metafields.edges.map((e) => e.node),
+                pageInfo: data.node.metafields.pageInfo,
+            };
+        }
+        catch (error) {
+            handleToolError("fetch metafields", error);
+        }
+    },
+};
+export { getMetafields };

package/dist/tools/getOrderById.js

@@ -0,0 +1,212 @@
+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 getOrderById
+const GetOrderByIdInputSchema = z.object({
+    orderId: z.string().min(1)
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const getOrderById = {
+    name: "get-order-by-id",
+    description: "Get a specific order by ID",
+    schema: GetOrderByIdInputSchema,
+    // Add initialize method to set up the GraphQL client
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const { orderId } = input;
+            // Smart lookup: detect format and resolve to GID
+            let resolvedId;
+            const trimmed = orderId.trim();
+            if (trimmed.startsWith("gid://")) {
+                // Already a full GID
+                resolvedId = trimmed;
+            }
+            else if (/^#?\d{1,9}$/.test(trimmed)) {
+                // Short number or #number — treat as order name, query by name
+                const orderName = trimmed.startsWith("#") ? trimmed : `#${trimmed}`;
+                const nameQuery = gql `
+          #graphql
+
+          query FindOrderByName($query: String!) {
+            orders(first: 1, query: $query) {
+              edges {
+                node {
+                  id
+                }
+              }
+            }
+          }
+        `;
+                const nameData = (await shopifyClient.request(nameQuery, {
+                    query: `name:${orderName}`,
+                }));
+                if (nameData.orders.edges.length === 0) {
+                    throw new Error(`Order with name ${orderName} not found`);
+                }
+                resolvedId = nameData.orders.edges[0].node.id;
+            }
+            else if (/^\d+$/.test(trimmed)) {
+                // Long numeric ID — convert to GID
+                resolvedId = `gid://shopify/Order/${trimmed}`;
+            }
+            else {
+                // Unknown format — try as-is
+                resolvedId = trimmed;
+            }
+            const query = gql `
+        #graphql
+
+        query GetOrderById($id: ID!) {
+          order(id: $id) {
+            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
+              }
+              defaultPhoneNumber {
+                phoneNumber
+              }
+            }
+            shippingAddress {
+              address1
+              address2
+              city
+              provinceCode
+              zip
+              country
+              phone
+            }
+            lineItems(first: 20) {
+              edges {
+                node {
+                  id
+                  title
+                  quantity
+                  originalTotalSet {
+                    shopMoney {
+                      amount
+                      currencyCode
+                    }
+                  }
+                  variant {
+                    id
+                    title
+                    sku
+                  }
+                }
+              }
+            }
+            tags
+            note
+            billingAddress {
+              address1
+              address2
+              city
+              provinceCode
+              zip
+              country
+              company
+              phone
+              firstName
+              lastName
+            }
+            cancelReason
+            cancelledAt
+            updatedAt
+            returnStatus
+            processedAt
+            poNumber
+            discountCodes
+            currentTotalPriceSet {
+              shopMoney {
+                amount
+                currencyCode
+              }
+            }
+            metafields(first: 20) {
+              edges {
+                node {
+                  id
+                  namespace
+                  key
+                  value
+                  type
+                }
+              }
+            }
+          }
+        }
+      `;
+            const variables = {
+                id: resolvedId
+            };
+            const data = (await shopifyClient.request(query, variables));
+            if (!data.order) {
+                throw new Error(`Order with ID ${orderId} not found`);
+            }
+            // Extract and format order data
+            const order = data.order;
+            const base = formatOrderSummary(order);
+            const formattedOrder = {
+                ...base,
+                customer: order.customer
+                    ? {
+                        ...base.customer,
+                        phone: order.customer.defaultPhoneNumber?.phoneNumber || null,
+                    }
+                    : null,
+                billingAddress: order.billingAddress,
+                cancelReason: order.cancelReason,
+                cancelledAt: order.cancelledAt,
+                updatedAt: order.updatedAt,
+                returnStatus: order.returnStatus,
+                processedAt: order.processedAt,
+                poNumber: order.poNumber,
+                discountCodes: order.discountCodes,
+                currentTotalPrice: order.currentTotalPriceSet?.shopMoney,
+                metafields: edgesToNodes(order.metafields),
+            };
+            return { order: formattedOrder };
+        }
+        catch (error) {
+            handleToolError("fetch order", error);
+        }
+    }
+};
+export { getOrderById };

package/dist/tools/getOrderRefundDetails.js

@@ -0,0 +1,131 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { edgesToNodes, handleToolError } from "../lib/toolUtils.js";
+const GetOrderRefundDetailsInputSchema = z.object({
+    orderId: z
+        .string()
+        .min(1)
+        .describe("The order ID (e.g. gid://shopify/Order/123 or just 123)"),
+});
+let shopifyClient;
+const getOrderRefundDetails = {
+    name: "get-order-refund-details",
+    description: "Get detailed refund info for an order including refunded items, amounts, restock status, and associated transactions",
+    schema: GetOrderRefundDetailsInputSchema,
+    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 GetOrderRefundDetails($id: ID!) {
+          order(id: $id) {
+            id
+            name
+            refunds(first: 25) {
+              id
+              note
+              createdAt
+              updatedAt
+              totalRefundedSet {
+                shopMoney {
+                  amount
+                  currencyCode
+                }
+                presentmentMoney {
+                  amount
+                  currencyCode
+                }
+              }
+              refundLineItems(first: 50) {
+                edges {
+                  node {
+                    quantity
+                    restockType
+                    restocked
+                    priceSet {
+                      shopMoney {
+                        amount
+                        currencyCode
+                      }
+                    }
+                    subtotalSet {
+                      shopMoney {
+                        amount
+                        currencyCode
+                      }
+                    }
+                    totalTaxSet {
+                      shopMoney {
+                        amount
+                        currencyCode
+                      }
+                    }
+                    lineItem {
+                      id
+                      title
+                      sku
+                    }
+                    location {
+                      id
+                      name
+                    }
+                  }
+                }
+              }
+              transactions(first: 10) {
+                edges {
+                  node {
+                    id
+                    kind
+                    status
+                    gateway
+                    amountSet {
+                      shopMoney {
+                        amount
+                        currencyCode
+                      }
+                    }
+                    processedAt
+                  }
+                }
+              }
+              duties {
+                amountSet {
+                  shopMoney {
+                    amount
+                    currencyCode
+                  }
+                }
+              }
+            }
+          }
+        }
+      `;
+            const data = await shopifyClient.request(query, { id: orderId });
+            if (!data.order) {
+                throw new Error(`Order not found: ${orderId}`);
+            }
+            const refunds = data.order.refunds.map((refund) => ({
+                ...refund,
+                refundLineItems: edgesToNodes(refund.refundLineItems),
+                transactions: edgesToNodes(refund.transactions),
+            }));
+            return {
+                orderId: data.order.id,
+                orderName: data.order.name,
+                refundsCount: refunds.length,
+                refunds,
+            };
+        }
+        catch (error) {
+            handleToolError("fetch order refund details", error);
+        }
+    },
+};
+export { getOrderRefundDetails };