heb-mcp

A single-user Model Context Protocol server for the unofficial H-E-B API, packaged for Docker with host-side OAuth.

Relationship to iHildy/heb-sdk-unofficial

This repo consumes the excellent iHildy/heb-sdk-unofficial project as a library — both the published heb-sdk-unofficial and heb-auth-unofficial packages, plus a vendored snapshot of the SDK build under vendor/heb-sdk-dist/. The MCP tool surface mirrors the schemas defined in upstream's SDK so behaviour stays aligned.

It is intentionally not a fork of upstream's packages/heb-mcp. The two solve different problems:

	upstream packages/heb-mcp	this repo
Tenancy	Multi-tenant via Clerk	Single user
Auth flow	Clerk-mediated OAuth dance, web interstitial	Host-side PKCE one-shot (bootstrap.ts)
Token storage	Clerk-managed	Local tokens.json (mode 0600), bind-mounted read-write into the container
Frontend	React/Vite web app (web/)	None — direct MCP over Streamable HTTP on :4321
Discovery	manifest.json for hosted-MCP listings	Not applicable
Intended deployment	Hosted, public	Personal box / sandboxed agent on a LAN

Forking would mean either carrying the Clerk + multi-tenant + web code as unused weight, or repeatedly ripping it out on every rebase. Consuming the SDK as a library lets upstream evolve its MCP server independently while this project just bumps the SDK dep.

Architecture

host (one-shot PKCE)              container (long-running)
─────────────────────             ─────────────────────────
bootstrap.ts  ──writes──▶  tokens.json (0600)
                                 │
                                 │  bind-mount rw
                                 ▼
                            /secrets/tokens.json
                                 │
                                 ▼
                            src/server.ts ── MCP over HTTP :4321

Refresh tokens are rotated inside the container and atomically written back to the bind mount (with a fallback for Docker's single-file mount rename restriction).

Quick start

# 1. One-shot PKCE login on the host (produces tokens.json in cwd)
npx tsx bootstrap.ts

# 2. (Optional) copy compose.override.example.yml → compose.override.yml
#    and edit the volume paths for your data directory
cp compose.override.example.yml compose.override.yml

# 3. Bring up the server
docker compose up -d --build

The server listens on :4321. Point your MCP client (Claude Desktop, mcporter, etc.) at it.

Files

• bootstrap.ts — host-side PKCE login, writes tokens.json
• src/server.ts — MCP HTTP transport
• src/session.ts — token refresh + persistence
• src/tools.ts — tool registrations (search, cart, orders, fulfillment, preferences)
• src/preferences.ts — local preference list (/data/preferences.json) for preference-aware tools
• Dockerfile, docker-compose.yml — container build + base compose
• compose.override.example.yml — template for bind-mount paths; copy and edit locally
• vendor/heb-sdk-dist/ — pinned snapshot of upstream SDK build

Credits

All upstream API reverse-engineering, schemas, and OAuth flow belong to iHildy and contributors to heb-sdk-unofficial. This repo is a thin deployment wrapper.

Disclaimer

Unofficial. Not affiliated with or endorsed by H-E-B. Use of the H-E-B API is subject to H-E-B's terms of service.