@klaudworks/shopify-mcp 1.1.0

package/dist/tools/getProducts.js

@@ -0,0 +1,155 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { handleToolError } from "../lib/toolUtils.js";
+// Input schema for getProducts
+const GetProductsInputSchema = z.object({
+    searchTitle: z.string().optional().describe("Search by title (convenience filter, wraps in title:*...*). Use 'query' for advanced filtering."),
+    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", "INVENTORY_TOTAL", "PRODUCT_TYPE",
+        "PUBLISHED_AT", "RELEVANCE", "TITLE", "UPDATED_AT", "VENDOR"
+    ]).optional().describe("Sort key for products"),
+    reverse: z.boolean().optional().describe("Reverse the sort order"),
+    query: z.string().optional().describe("Raw query string for advanced filtering (e.g. 'status:active vendor:Nike tag:sale')")
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const getProducts = {
+    name: "get-products",
+    description: "Get all products or search by title",
+    schema: GetProductsInputSchema,
+    // Add initialize method to set up the GraphQL client
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const { searchTitle, limit, after, before, sortKey, reverse, query: rawQuery } = input;
+            // Build query string from convenience filters and raw query
+            const queryParts = [];
+            if (searchTitle) {
+                queryParts.push(`title:*${searchTitle}*`);
+            }
+            if (rawQuery) {
+                queryParts.push(rawQuery);
+            }
+            const queryFilter = queryParts.join(" ") || undefined;
+            const query = gql `
+        #graphql
+
+        query GetProducts($first: Int!, $query: String, $after: String, $before: String, $sortKey: ProductSortKeys, $reverse: Boolean) {
+          products(first: $first, query: $query, after: $after, before: $before, sortKey: $sortKey, reverse: $reverse) {
+            edges {
+              node {
+                id
+                title
+                description
+                handle
+                status
+                createdAt
+                updatedAt
+                totalInventory
+                priceRangeV2 {
+                  minVariantPrice {
+                    amount
+                    currencyCode
+                  }
+                  maxVariantPrice {
+                    amount
+                    currencyCode
+                  }
+                }
+                media(first: 1) {
+                  edges {
+                    node {
+                      ... on MediaImage {
+                        id
+                        image {
+                          url
+                          altText
+                        }
+                      }
+                    }
+                  }
+                }
+                variants(first: 5) {
+                  edges {
+                    node {
+                      id
+                      title
+                      price
+                      inventoryQuantity
+                      sku
+                    }
+                  }
+                }
+              }
+            }
+            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 product data
+            const products = data.products.edges.map((edge) => {
+                const product = edge.node;
+                // 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
+                }));
+                // Get first image if it exists
+                const firstMedia = product.media.edges.find((e) => e.node.image);
+                const imageUrl = firstMedia?.node.image?.url || null;
+                return {
+                    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
+                        }
+                    },
+                    imageUrl,
+                    variants
+                };
+            });
+            return {
+                products,
+                pageInfo: data.products.pageInfo
+            };
+        }
+        catch (error) {
+            handleToolError("fetch products", error);
+        }
+    }
+};
+export { getProducts };

package/dist/tools/getShopInfo.js

@@ -0,0 +1,74 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { handleToolError } from "../lib/toolUtils.js";
+const GetShopInfoInputSchema = z.object({});
+let shopifyClient;
+const getShopInfo = {
+    name: "get-shop-info",
+    description: "Get shop configuration including name, plan, currencies, features, payment settings, tax config, and contact info",
+    schema: GetShopInfoInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (_input) => {
+        try {
+            const query = gql `
+        #graphql
+
+        query GetShopInfo {
+          shop {
+            id
+            name
+            email
+            contactEmail
+            myshopifyDomain
+            primaryDomain {
+              url
+              host
+            }
+            plan {
+              publicDisplayName
+              partnerDevelopment
+              shopifyPlus
+            }
+            currencyCode
+            enabledPresentmentCurrencies
+            ianaTimezone
+            timezoneAbbreviation
+            taxShipping
+            taxesIncluded
+            setupRequired
+            features {
+              giftCards
+              reports
+              storefront
+              harmonizedSystemCode
+              avalaraAvatax
+              sellsSubscriptions
+            }
+            paymentSettings {
+              supportedDigitalWallets
+            }
+            shopAddress {
+              address1
+              address2
+              city
+              province
+              provinceCode
+              country
+              countryCodeV2
+              zip
+              phone
+            }
+          }
+        }
+      `;
+            const data = await shopifyClient.request(query);
+            return { shop: data.shop };
+        }
+        catch (error) {
+            handleToolError("fetch shop info", error);
+        }
+    },
+};
+export { getShopInfo };

package/dist/tools/manageCustomerAddress.js

@@ -0,0 +1,149 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+import { shippingAddressSchema } from "../lib/formatters.js";
+const ManageCustomerAddressInputSchema = z.object({
+    customerId: z.string().describe("Customer GID, e.g. gid://shopify/Customer/123"),
+    action: z.enum(["create", "update", "delete"]).describe("Action to perform"),
+    addressId: z.string().optional().describe("Address GID (required for update and delete)"),
+    address: shippingAddressSchema.optional().describe("Address fields (required for create and update)"),
+    setAsDefault: z.boolean().optional().describe("Set this address as the customer's default"),
+});
+let shopifyClient;
+const manageCustomerAddress = {
+    name: "manage-customer-address",
+    description: "Create, update, or delete a customer's mailing address. Can optionally set as default.",
+    schema: ManageCustomerAddressInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            if (input.action === "create") {
+                if (!input.address) {
+                    throw new Error("Address fields are required for create action");
+                }
+                const query = gql `
+          #graphql
+
+          mutation customerAddressCreate(
+            $customerId: ID!
+            $address: MailingAddressInput!
+            $setAsDefault: Boolean
+          ) {
+            customerAddressCreate(
+              customerId: $customerId
+              address: $address
+              setAsDefault: $setAsDefault
+            ) {
+              address {
+                id
+                address1
+                address2
+                city
+                company
+                countryCodeV2
+                firstName
+                lastName
+                phone
+                provinceCode
+                zip
+              }
+              userErrors {
+                field
+                message
+              }
+            }
+          }
+        `;
+                const data = (await shopifyClient.request(query, {
+                    customerId: input.customerId,
+                    address: input.address,
+                    setAsDefault: input.setAsDefault,
+                }));
+                checkUserErrors(data.customerAddressCreate.userErrors, "create address");
+                return { address: data.customerAddressCreate.address };
+            }
+            else if (input.action === "update") {
+                if (!input.addressId) {
+                    throw new Error("addressId is required for update action");
+                }
+                if (!input.address) {
+                    throw new Error("Address fields are required for update action");
+                }
+                const query = gql `
+          #graphql
+
+          mutation customerAddressUpdate(
+            $customerId: ID!
+            $addressId: ID!
+            $address: MailingAddressInput!
+            $setAsDefault: Boolean
+          ) {
+            customerAddressUpdate(
+              customerId: $customerId
+              addressId: $addressId
+              address: $address
+              setAsDefault: $setAsDefault
+            ) {
+              address {
+                id
+                address1
+                address2
+                city
+                company
+                countryCodeV2
+                firstName
+                lastName
+                phone
+                provinceCode
+                zip
+              }
+              userErrors {
+                field
+                message
+              }
+            }
+          }
+        `;
+                const data = (await shopifyClient.request(query, {
+                    customerId: input.customerId,
+                    addressId: input.addressId,
+                    address: input.address,
+                    setAsDefault: input.setAsDefault,
+                }));
+                checkUserErrors(data.customerAddressUpdate.userErrors, "update address");
+                return { address: data.customerAddressUpdate.address };
+            }
+            else {
+                // delete
+                if (!input.addressId) {
+                    throw new Error("addressId is required for delete action");
+                }
+                const query = gql `
+          #graphql
+
+          mutation customerAddressDelete($customerId: ID!, $addressId: ID!) {
+            customerAddressDelete(customerId: $customerId, addressId: $addressId) {
+              deletedAddressId
+              userErrors {
+                field
+                message
+              }
+            }
+          }
+        `;
+                const data = (await shopifyClient.request(query, {
+                    customerId: input.customerId,
+                    addressId: input.addressId,
+                }));
+                checkUserErrors(data.customerAddressDelete.userErrors, "delete address");
+                return { deletedAddressId: data.customerAddressDelete.deletedAddressId };
+            }
+        }
+        catch (error) {
+            handleToolError(`${input.action} customer address`, error);
+        }
+    },
+};
+export { manageCustomerAddress };

package/dist/tools/manageProductOptions.js

@@ -0,0 +1,293 @@
+import { gql } from "graphql-request";
+import { z } from "zod";
+import { checkUserErrors, handleToolError } from "../lib/toolUtils.js";
+// Input schema for manageProductOptions
+const ManageProductOptionsInputSchema = z.object({
+    productId: z.string().min(1).describe("Shopify product GID"),
+    action: z.enum(["create", "update", "delete"]),
+    variantStrategy: z
+        .enum(["LEAVE_AS_IS", "CREATE"])
+        .optional()
+        .describe("Strategy for variant creation when adding options. LEAVE_AS_IS (default) keeps existing variants, CREATE generates new variant combinations."),
+    // For create
+    options: z
+        .array(z.object({
+        name: z.string().describe("Option name, e.g. 'Size' or 'Color'"),
+        position: z.number().optional().describe("Position of the option (1-based)"),
+        values: z
+            .array(z.string())
+            .optional()
+            .describe("Option values, e.g. ['Small', 'Medium', 'Large']"),
+    }))
+        .optional()
+        .describe("Options to create (action=create)"),
+    // For update
+    optionId: z.string().optional().describe("Option GID to update (action=update)"),
+    name: z.string().optional().describe("New name for the option (action=update)"),
+    position: z.number().optional().describe("New position (action=update)"),
+    valuesToAdd: z
+        .array(z.string())
+        .optional()
+        .describe("Values to add (action=update)"),
+    valuesToDelete: z
+        .array(z.string())
+        .optional()
+        .describe("Value GIDs to delete (action=update)"),
+    // For delete
+    optionIds: z
+        .array(z.string())
+        .optional()
+        .describe("Option GIDs to delete (action=delete)"),
+});
+// Will be initialized in index.ts
+let shopifyClient;
+const manageProductOptions = {
+    name: "manage-product-options",
+    description: "Create, update, or delete product options (e.g. Size, Color). Use action='create' to add options, 'update' to rename or add/remove values, 'delete' to remove options.",
+    schema: ManageProductOptionsInputSchema,
+    initialize(client) {
+        shopifyClient = client;
+    },
+    execute: async (input) => {
+        try {
+            const { productId, action } = input;
+            if (action === "create") {
+                if (!input.options?.length) {
+                    throw new Error("options array is required for action=create");
+                }
+                const query = gql `
+          #graphql
+
+          mutation productOptionsCreate(
+            $productId: ID!
+            $options: [OptionCreateInput!]!
+            $variantStrategy: ProductOptionCreateVariantStrategy
+          ) {
+            productOptionsCreate(
+              productId: $productId
+              options: $options
+              variantStrategy: $variantStrategy
+            ) {
+              product {
+                ...ProductOptionsFields
+              }
+              userErrors {
+                field
+                message
+                code
+              }
+            }
+          }
+
+          fragment ProductOptionsFields on Product {
+            id
+            title
+            options {
+              id
+              name
+              position
+              optionValues {
+                id
+                name
+                hasVariants
+              }
+            }
+            variants(first: 20) {
+              edges {
+                node {
+                  id
+                  title
+                  price
+                  selectedOptions {
+                    name
+                    value
+                  }
+                }
+              }
+            }
+          }
+        `;
+                const options = input.options.map((o) => ({
+                    name: o.name,
+                    ...(o.position !== undefined && { position: o.position }),
+                    ...(o.values && {
+                        values: o.values.map((v) => ({ name: v })),
+                    }),
+                }));
+                const data = (await shopifyClient.request(query, {
+                    productId,
+                    options,
+                    variantStrategy: input.variantStrategy || "LEAVE_AS_IS",
+                }));
+                checkUserErrors(data.productOptionsCreate.userErrors, "create options");
+                return formatProductResponse(data.productOptionsCreate.product);
+            }
+            if (action === "update") {
+                if (!input.optionId) {
+                    throw new Error("optionId is required for action=update");
+                }
+                const query = gql `
+          #graphql
+
+          mutation productOptionUpdate(
+            $productId: ID!
+            $option: OptionUpdateInput!
+            $optionValuesToAdd: [OptionValueCreateInput!]
+            $optionValuesToDelete: [ID!]
+          ) {
+            productOptionUpdate(
+              productId: $productId
+              option: $option
+              optionValuesToAdd: $optionValuesToAdd
+              optionValuesToDelete: $optionValuesToDelete
+            ) {
+              product {
+                ...ProductOptionsFields
+              }
+              userErrors {
+                field
+                message
+                code
+              }
+            }
+          }
+
+          fragment ProductOptionsFields on Product {
+            id
+            title
+            options {
+              id
+              name
+              position
+              optionValues {
+                id
+                name
+                hasVariants
+              }
+            }
+            variants(first: 20) {
+              edges {
+                node {
+                  id
+                  title
+                  price
+                  selectedOptions {
+                    name
+                    value
+                  }
+                }
+              }
+            }
+          }
+        `;
+                const option = { id: input.optionId };
+                if (input.name)
+                    option.name = input.name;
+                if (input.position !== undefined)
+                    option.position = input.position;
+                const variables = { productId, option };
+                if (input.valuesToAdd?.length) {
+                    variables.optionValuesToAdd = input.valuesToAdd.map((v) => ({
+                        name: v,
+                    }));
+                }
+                if (input.valuesToDelete?.length) {
+                    variables.optionValuesToDelete = input.valuesToDelete;
+                }
+                const data = (await shopifyClient.request(query, variables));
+                checkUserErrors(data.productOptionUpdate.userErrors, "update option");
+                return formatProductResponse(data.productOptionUpdate.product);
+            }
+            if (action === "delete") {
+                if (!input.optionIds?.length) {
+                    throw new Error("optionIds array is required for action=delete");
+                }
+                const query = gql `
+          #graphql
+
+          mutation productOptionsDelete(
+            $productId: ID!
+            $options: [ID!]!
+          ) {
+            productOptionsDelete(
+              productId: $productId
+              options: $options
+            ) {
+              product {
+                ...ProductOptionsFields
+              }
+              userErrors {
+                field
+                message
+                code
+              }
+            }
+          }
+
+          fragment ProductOptionsFields on Product {
+            id
+            title
+            options {
+              id
+              name
+              position
+              optionValues {
+                id
+                name
+                hasVariants
+              }
+            }
+            variants(first: 20) {
+              edges {
+                node {
+                  id
+                  title
+                  price
+                  selectedOptions {
+                    name
+                    value
+                  }
+                }
+              }
+            }
+          }
+        `;
+                const data = (await shopifyClient.request(query, {
+                    productId,
+                    options: input.optionIds,
+                }));
+                checkUserErrors(data.productOptionsDelete.userErrors, "delete options");
+                return formatProductResponse(data.productOptionsDelete.product);
+            }
+            throw new Error(`Unknown action: ${action}`);
+        }
+        catch (error) {
+            handleToolError("manage product options", error);
+        }
+    },
+};
+function formatProductResponse(product) {
+    return {
+        product: {
+            id: product.id,
+            title: product.title,
+            options: product.options.map((o) => ({
+                id: o.id,
+                name: o.name,
+                position: o.position,
+                values: o.optionValues.map((v) => ({
+                    id: v.id,
+                    name: v.name,
+                    hasVariants: v.hasVariants,
+                })),
+            })),
+            variants: product.variants.edges.map((e) => ({
+                id: e.node.id,
+                title: e.node.title,
+                price: e.node.price,
+                options: e.node.selectedOptions,
+            })),
+        },
+    };
+}
+export { manageProductOptions };