mcp-costco

Instructions

Implementation Reference

• src/index.ts:713-784 (handler)

  The handleAddToCart function implements the add_to_cart tool logic. It checks if the user is logged in, validates that either url or item_number is provided, navigates to the product page, adjusts quantity if needed, clicks the Add to Cart button, and returns confirmation with cart details.

  async function handleAddToCart(
    url?: string,
    itemNumber?: string,
    quantity = 1
  ) {
    if (!isLoggedIn()) {
      return err("Not logged in. Use the `login` tool first.");
    }
    if (!url && !itemNumber) {
      return err("Provide either url or item_number");
    }
  
    return withPage(async (page: Page) => {
      const productUrl = url ?? `https://www.costco.com/p.${itemNumber}.product.html`;
  
      await page.goto(productUrl, {
        waitUntil: "domcontentloaded",
        timeout: 30000,
      });
      await page.waitForTimeout(2000);
  
      // Adjust quantity if > 1
      if (quantity > 1) {
        try {
          const qtyInput = await page.$(
            '[automation-id="product-detail-quantity-input"], input[id*="qty"], input[name*="qty"], input[class*="qty"]'
          );
          if (qtyInput) {
            await qtyInput.fill(String(quantity));
          }
        } catch {
          // Ignore quantity adjustment errors
        }
      }
  
      // Click Add to Cart
      const addBtn = await page.waitForSelector(
        '[automation-id="add-to-cart-btn"], button[id*="add-to-cart"], button[class*="add-to-cart"], [class*="addToCart"]',
        { timeout: 10000 }
      );
  
      const btnText = await addBtn.textContent();
      if (
        btnText?.toLowerCase().includes("out of stock") ||
        btnText?.toLowerCase().includes("unavailable") ||
        btnText?.toLowerCase().includes("sold out")
      ) {
        return err("Item is out of stock or unavailable");
      }
  
      await addBtn.click();
      await page.waitForTimeout(3000);
  
      // Confirm added — look for cart confirmation modal or count change
      const confirmation = await page.$(
        '[automation-id="cart-count"], .cart-count, [class*="cartCount"]'
      );
      const count = confirmation ? await confirmation.textContent() : null;
  
      // Extract item number from URL
      const itemMatch = page.url().match(/\.(\d+)\.product/);
      const resolvedItemNumber = itemMatch ? itemMatch[1] : (itemNumber ?? "unknown");
  
      return ok(
        `Successfully added to cart.\n` +
        `Quantity: ${quantity}\n` +
        `Item #: ${resolvedItemNumber}\n` +
        `Cart count: ${count?.trim() ?? "updated"}\n` +
        `Product URL: ${productUrl}`
      );
    });
  }

• src/index.ts:109-122 (schema)

  Schema definition for the add_to_cart tool in the ListToolsRequestSchema handler. Defines input parameters: url (product URL), item_number (Costco item number), and quantity (default: 1).

    name: "add_to_cart",
    description: "Add a Costco product to the cart",
    inputSchema: {
      type: "object",
      properties: {
        url: { type: "string", description: "Costco product URL" },
        item_number: { type: "string", description: "Costco item number" },
        quantity: {
          type: "number",
          description: "Quantity to add (default: 1)",
        },
      },
    },
  },

• src/index.ts:312-317 (registration)

  Registration of the add_to_cart tool in the CallToolRequestSchema handler switch statement. Routes tool calls to the handleAddToCart function with url, item_number, and quantity parameters.

  case "add_to_cart":
    return await handleAddToCart(
      a.url as string | undefined,
      a.item_number as string | undefined,
      (a.quantity as number | undefined) ?? 1
    );