# My H-E-B API Proxy & MCP Server

A lightweight TypeScript wrapper, HTTP proxy, and Model Context Protocol (MCP) server for the My H-E-B mobile app API. Built with Bun and Elysia.js.

I reverse-engineered the My H-E-B app's production GraphQL and REST APIs to extract their schema queries, headers, and API keys. This project wraps those endpoints into a clean, modern HTTP proxy and exposes them as standard MCP tools for LLMs.

For a detailed breakdown of the raw GraphQL queries, REST endpoints, headers, and parameters, see the [API Specification](API.md).

> [!WARNING]  
> This is an **unofficial** project built for educational and personal research purposes. It is not affiliated with, maintained by, or endorsed by H-E-B.

### Intended Use

This project is designed to bridge the gap between large language models (LLMs) and real-time grocery data. By connecting your AI assistant (via MCP or the HTTP proxy), you can:

- **Find the best deals:** Ask your model to scan weekly ads or search for active coupons matching your shopping needs.
- **Build smart shopping lists:** Let the model suggest ingredients, compile organized grocery lists, and cross-reference them with actual store items and pricing.
- **Locate nearby stores:** Programmatically verify store locations, amenities, and operating hours.

---

## Features

- **Store Locator:** Search H-E-B store details, distance, and operating hours by address or zip code.
- **Digital Coupons:** Search and filter H-E-B digital coupons by categories, print statuses, or search keywords.
- **Product Catalog:** Query the product catalog by store number and shopping context (curbside pickup, delivery, in-store) to fetch prices, SKU data, and images.
- **Weekly Ads:** Retrieve the weekly ad layout, promotional carousels, and direct publications flipbook links.
- **Generic GraphQL Pass-through:** Forward raw queries to H-E-B's edge API gateway while automatically injecting the correct interceptor headers.
- **Model Context Protocol (MCP) Integration:** Plug the API straight into your AI coding assistants or desktop clients as local tools.

---

## How It Works

H-E-B's API gateway rejects requests without specific mobile app client headers. This server automatically injects:

1. **API Key (`apiKey`):** The extracted production key used by the Android app client.
2. **User-Agent:** Formatted to mimic a standard mobile device (e.g. `MyHEB/2.80.1.1 (Android 14; Google Pixel 8)`).
3. **Request UUID (`X-CLNT-REQ-UUID`):** Automatically generates a fresh random UUID for every request.

---

## Tech Stack

- **Runtime:** [Bun](https://bun.sh) (fast JS/TS runtime)
- **HTTP Server:** [Elysia.js](https://elysiajs.com) (fast, type-friendly web framework)
- **Documentation:** Swagger UI (auto-generated at `/swagger`)
- **Protocol:** Model Context Protocol (MCP) TypeScript SDK

---

## Getting Started

### Prerequisites

Make sure you have [Bun](https://bun.sh) installed.

### Installation

Clone the repository and install dependencies:

```bash
git clone https://github.com/ALLMarvelous/my-heb-proxy.git
cd my-heb-proxy
bun install
```

### Running the HTTP Proxy

To run the server in development mode (with hot reloading):

```bash
bun run dev
```

The server will start at `http://localhost:3000`. You can open the interactive API docs in your browser at [http://localhost:3000/swagger](http://localhost:3000/swagger)

---

## API Endpoints

| Method   | Endpoint               | Description                                       |
| :------- | :--------------------- | :------------------------------------------------ |
| **GET**  | `/api/stores`          | Find stores near an address or zip code           |
| **POST** | `/api/coupons`         | Search and filter digital coupons                 |
| **POST** | `/api/products`        | Search the product catalog for pricing/images     |
| **GET**  | `/api/weekly-ad`       | Retrieve weekly ad component layouts              |
| **GET**  | `/api/weekly-ad/flyer` | Redirects to the static weekly ad flipbook PDF    |
| **POST** | `/api/graphql`         | Raw GraphQL proxy (auto-injects required headers) |

---

## MCP Server Integration

This project is a fully-compliant Model Context Protocol server. To use these tools in your AI workflow:

### Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "my-heb-mcp": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/my-heb-proxy/src/mcp-server.ts"]
    }
  }
}
```

### Cursor / Windsurf

Add a new MCP server in your editor settings:

- **Name:** `my-heb-mcp`
- **Type:** `command`
- **Command:** `bun run /absolute/path/to/my-heb-proxy/src/mcp-server.ts`

### Available MCP Tools

- `search_stores` (arguments: `address`, `radiusMiles`, `includeNextAvailableTimeslot`, `includeEcommInactive`)
- `search_coupons` (arguments: `text`, `offset`, `limit`, `categories`, `couponTypes`, `sortOrder`)
- `search_products` (arguments: `query`, `storeId`, `shoppingContext`)
- `get_weekly_ad` (arguments: `storeId`, `shoppingContext`)
- `get_weekly_ad_flyer_url` (arguments: `storeId`)