Shopify MCP Server

Implementation Reference

• src/tools/getOrderById.ts:25-194 (handler)

  The execute function contains the main handler logic for fetching an order by ID. It constructs a GraphQL query, calls the Shopify API, formats the response including line items and metafields, and returns the order data.

  execute: async (input: GetOrderByIdInput) => {
    try {
      const { orderId } = input;
  
      const query = gql`
        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
              email
              phone
            }
            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
            metafields(first: 20) {
              edges {
                node {
                  id
                  namespace
                  key
                  value
                  type
                }
              }
            }
          }
        }
      `;
  
      const variables = {
        id: orderId
      };
  
      const data = (await shopifyClient.request(query, variables)) as {
        order: any;
      };
  
      if (!data.order) {
        throw new Error(`Order with ID ${orderId} not found`);
      }
  
      // Extract and format order data
      const order = data.order;
  
      // Format line items
      const lineItems = order.lineItems.edges.map((lineItemEdge: any) => {
        const lineItem = lineItemEdge.node;
        return {
          id: lineItem.id,
          title: lineItem.title,
          quantity: lineItem.quantity,
          originalTotal: lineItem.originalTotalSet.shopMoney,
          variant: lineItem.variant
            ? {
                id: lineItem.variant.id,
                title: lineItem.variant.title,
                sku: lineItem.variant.sku
              }
            : null
        };
      });
  
      // Format metafields
      const metafields = order.metafields.edges.map((metafieldEdge: any) => {
        const metafield = metafieldEdge.node;
        return {
          id: metafield.id,
          namespace: metafield.namespace,
          key: metafield.key,
          value: metafield.value,
          type: metafield.type
        };
      });
  
      const formattedOrder = {
        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.email,
              phone: order.customer.phone
            }
          : null,
        shippingAddress: order.shippingAddress,
        lineItems,
        tags: order.tags,
        note: order.note,
        metafields
      };
  
      return { order: formattedOrder };
    } catch (error) {
      console.error("Error fetching order by ID:", error);
      throw new Error(
        `Failed to fetch order: ${
          error instanceof Error ? error.message : String(error)
        }`
      );
    }
  }

• src/tools/getOrderById.ts:5-10 (schema)

  Input schema definition using Zod for validating the orderId parameter. It requires a non-empty string for the orderId.

  // Input schema for getOrderById
  const GetOrderByIdInputSchema = z.object({
    orderId: z.string().min(1)
  });
  
  type GetOrderByIdInput = z.infer<typeof GetOrderByIdInputSchema>;

• src/index.ts:137-149 (registration)

  Tool registration with the MCP server. Defines the tool name 'get-order-by-id', the input schema using Zod validation, and the handler that calls getOrderById.execute() and wraps the result in a text response.

  // Add the getOrderById tool
  server.tool(
    "get-order-by-id",
    {
      orderId: z.string().min(1)
    },
    async (args) => {
      const result = await getOrderById.execute(args);
      return {
        content: [{ type: "text", text: JSON.stringify(result) }]
      };
    }
  );

• src/tools/getOrderById.ts:15-24 (helper)

  Tool object definition containing name, description, schema reference, and initialize method for setting up the GraphQL client dependency.

  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: GraphQLClient) {
      shopifyClient = client;
    },

• src/index.ts:67-67 (helper)

  Initialization of the getOrderById tool with the Shopify GraphQL client before registering it with the MCP server.

  getOrderById.initialize(shopifyClient);