Instacart MCP Server

Instructions

Implementation Reference

• src/browser.ts:440-494 (handler)

  The core implementation of previewOrder() function that performs browser automation to check order status. It navigates to the checkout page, retrieves cart data, checks for issues (login required, payment required, address required), extracts delivery window and address, and returns whether the order can be placed.

  export async function previewOrder(): Promise<{
    canPlace: boolean;
    summary: CartSummary;
    deliveryWindow?: string;
    address?: string;
    issues?: string[];
  }> {
    const { page, context } = await initBrowser();
  
    try {
      await page.goto(`${INSTACART_BASE_URL}/store/checkout`, { waitUntil: "networkidle", timeout: DEFAULT_TIMEOUT });
      await page.waitForTimeout(2000);
  
      const cart = await viewCart();
      const issues: string[] = [];
  
      // Check for common issues
      const loginRequired = await page.$('[data-testid="login-prompt"], button:has-text("Log in to checkout")');
      if (loginRequired) {
        issues.push("Login required to place order");
      }
  
      const paymentRequired = await page.$('[data-testid="add-payment"], :text("Add payment method")');
      if (paymentRequired) {
        issues.push("Payment method required");
      }
  
      const addressRequired = await page.$('[data-testid="add-address"], :text("Add delivery address")');
      if (addressRequired) {
        issues.push("Delivery address required");
      }
  
      // Get delivery window if available
      const deliveryEl = await page.$('[data-testid="delivery-window"], [class*="DeliveryWindow"]');
      const deliveryWindow = deliveryEl ? await deliveryEl.textContent() : undefined;
  
      // Get address if available
      const addressEl = await page.$('[data-testid="delivery-address"], [class*="DeliveryAddress"]');
      const address = addressEl ? await addressEl.textContent() : undefined;
  
      const canPlace = issues.length === 0 && cart.itemCount > 0;
  
      await saveCookies(context);
  
      return {
        canPlace,
        summary: cart,
        deliveryWindow: deliveryWindow?.trim(),
        address: address?.trim(),
        issues: issues.length > 0 ? issues : undefined,
      };
    } catch (error) {
      throw new Error(`Failed to preview order: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/index.ts:134-141 (schema)

  Tool schema definition for 'instacart_preview_order' registered in the MCP server's ListTools handler. Defines the tool name, description, and empty input schema (no required parameters).

    name: "instacart_preview_order",
    description:
      "Preview order before placing. Shows cart summary, delivery window, and any issues that need to be resolved.",
    inputSchema: {
      type: "object",
      properties: {},
    },
  },

• src/index.ts:346-367 (registration)

  Tool execution handler in the CallTool switch statement. Receives the 'instacart_preview_order' request, calls the previewOrder() function from browser.ts, and formats the response with success status, preview data, and helpful note about whether the order is ready to place.

  case "instacart_preview_order": {
    const preview = await previewOrder();
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              success: true,
              ...preview,
              note: preview.canPlace
                ? "Ready to place order. Use instacart_place_order with confirm=true to complete."
                : "Cannot place order. See issues field for required actions.",
            },
            null,
            2
          ),
        },
      ],
    };
  }