ALLMarvelous/my-heb-proxy
GitHub: ALLMarvelous/my-heb-proxy
一个基于 TypeScript 的轻量级代理服务器，将 H-E-B 超市移动应用的生产级 API 封装为 HTTP 接口和 MCP 工具，供 AI 助手实时查询商品、优惠券和门店信息。
Stars: 0 | Forks: 0
# My H-E-B API 代理与 MCP 服务器
一个轻量级的 TypeScript 封装、HTTP 代理和用于 My H-E-B 移动应用 API 的 Model Context Protocol (MCP) 服务器。使用 Bun 和 Elysia.js 构建。
我对 My H-E-B 应用的生产级 GraphQL 和 REST API 进行了逆向工程，以提取它们的 schema 查询、headers 和 API keys。本项目将这些 endpoint 封装为一个简洁、现代的 HTTP 代理，并将其作为标准的 MCP 工具暴露给 LLM 使用。
有关原始 GraphQL 查询、REST endpoint、headers 和参数的详细说明，请参阅 [API 规范](API.md)。
### 预期用途
本项目旨在弥合大型语言模型 (LLM) 与实时杂货数据之间的差距。通过连接您的 AI 助手（通过 MCP 或 HTTP 代理），您可以：
- **寻找最优惠的交易：** 让您的模型扫描每周广告，或搜索符合您购物需求的活跃优惠券。
- **构建智能购物清单：** 让模型推荐食材、整理有条理的杂货清单，并与实际的商店商品和价格进行交叉比对。
- **定位附近商店：** 以编程方式验证商店位置、设施和营业时间。
## 功能特性
- **商店定位器：** 根据地址或邮政编码搜索 H-E-B 商店详情、距离和营业时间。
- **数字优惠券：** 根据类别、打印状态或搜索关键词搜索和筛选 H-E-B 数字优惠券。
- **商品目录：** 根据商店编号和购物场景（路边提货、送货、店内）查询商品目录，以获取价格、SKU 数据和图片。
- **每周广告：** 获取每周广告布局、促销轮播图以及直接的出版物翻页书链接。
- **通用 GraphQL 透传：** 将原始查询转发到 H-E-B 的边缘 API 网关，同时自动注入正确的拦截器 headers。
- **Model Context Protocol (MCP) 集成：** 将 API 作为本地工具直接插入您的 AI 编程助手或桌面客户端。
## 工作原理
H-E-B 的 API 网关会拒绝没有特定移动应用客户端 headers 的请求。本服务器会自动注入：
1. **API Key (`apiKey`)：** Android 应用客户端使用的已提取的生产级 key。
2. **User-Agent：** 格式化为模拟标准的移动设备（例如 `MyHEB/2.80.1.1 (Android 14; Google Pixel 8)`）。
3. **Request UUID (`X-CLNT-REQ-UUID`)：** 为每个请求自动生成一个新的随机 UUID。
## 技术栈
- **Runtime：** [Bun](https://bun.sh) (快速的 JS/TS runtime)
- **HTTP 服务器：** [Elysia.js](https://elysiajs.com) (快速且类型友好的 Web 框架)
- **文档：** Swagger UI (在 `/swagger` 自动生成)
- **协议：** Model Context Protocol (MCP) TypeScript SDK
## 快速开始
### 前置条件
请确保您已安装 [Bun](https://bun.sh)。
### 安装
克隆仓库并安装依赖：
```
git clone https://github.com/ALLMarvelous/my-heb-proxy.git
cd my-heb-proxy
bun install
```
### 运行 HTTP 代理
要以开发模式运行服务器（支持热重载）：
```
bun run dev
```
服务器将启动于 `http://localhost:3000`。您可以在浏览器中打开 [http://localhost:3000/swagger](http://localhost:3000/swagger) 查看交互式 API 文档。
## API Endpoint
| 方法 | Endpoint | 描述 |
| :------- | :--------------------- | :------------------------------------------------ |
| **GET** | `/api/stores` | 查找地址或邮政编码附近的商店 |
| **POST** | `/api/coupons` | 搜索并筛选数字优惠券 |
| **POST** | `/api/products` | 搜索商品目录以获取价格/图片 |
| **GET** | `/api/weekly-ad` | 获取每周广告组件布局 |
| **GET** | `/api/weekly-ad/flyer` | 重定向到静态的每周广告翻页书 PDF |
| **POST** | `/api/graphql` | 原始 GraphQL 代理（自动注入所需 headers） |
## MCP 服务器集成
本项目是一个完全兼容的 Model Context Protocol 服务器。要在您的 AI 工作流中使用这些工具：
### Claude Desktop
将此内容添加到您的 `claude_desktop_config.json` 中：
```
{
"mcpServers": {
"my-heb-mcp": {
"command": "bun",
"args": ["run", "/absolute/path/to/my-heb-proxy/src/mcp-server.ts"]
}
}
}
```
### Cursor / Windsurf
在您的编辑器设置中添加一个新的 MCP 服务器：
- **名称：** `my-heb-mcp`
- **类型：** `command`
- **命令：** `bun run /absolute/path/to/my-heb-proxy/src/mcp-server.ts`
### 可用的 MCP 工具
- `search_stores` (参数：`address`、`radiusMiles`、`includeNextAvailableTimeslot`、`includeEcommInactive`)
- `search_coupons` (参数：`text`、`offset`、`limit`、`categories`、`couponTypes`、`sortOrder`)
- `search_products` (参数：`query`、`storeId`、`shoppingContext`)
- `get_weekly_ad` (参数：`storeId`、`shoppingContext`)
- `get_weekly_ad_flyer_url` (参数：`storeId`)
标签：API代理, GraphQL, LLM集成, MCP, TypeScript, 云资产清单, 安全插件, 自动化攻击, 购物应用, 逆向工程