# costco-mcp-demo

Public copy of the **Costco Saturday Run** app and MCP from [internalsphere/group-21-gtmko-2026](https://github.com/internalsphere/group-21-gtmko-2026). Phone UI, website catalog, staged warehouse data, tests, and streamable HTTP MCP all live here.

This repo is meant for a **public Vercel deploy**.

| Surface | URL | What it is |
| --- | --- | --- |
| Phone | [`/`](https://costco-mcp-demo.vercel.app/) | Chrome phone shell. Kirk in the dock. |
| Website | [`/web`](https://costco-mcp-demo.vercel.app/web) | Warehouse catalog (departments, search, product pages, cart). |
| MCP | [`/api/mcp`](https://costco-mcp-demo.vercel.app/api/mcp) | Streamable HTTP MCP. Catalog / cart / member tools. |
| Connect | [`/connect.html`](https://costco-mcp-demo.vercel.app/connect.html) | Static MCP credentials page (also optional on GitHub Pages). |

Labeled demo. Catalog, membership, warehouse hours, and product photos are staged — not live Costco APIs.

## Demo MCP credentials

Always bound to **Jordan Lee / Executive Member**.

| | |
| --- | --- |
| Username | `jordan` |
| Password | `spacexai123` |
| Bearer | `Authorization: Bearer spacexai123` |
| Basic | `Authorization: Basic` base64(`jordan:spacexai123`) |
| Connect URL | `https://costco-mcp-demo.vercel.app/api/mcp` |

## Run locally

```bash
git clone https://github.com/cursor-demo-lab/costco-mcp-demo.git
cd costco-mcp-demo
npm install
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) for the phone, or [http://localhost:3000/web](http://localhost:3000/web) for the website.

Optional live Grok (text / Imagine / Voice):

```bash
cp .env.example .env.local
# set XAI_API_KEY=...
```

The app boots without a key. Voice says it is not connected; Imagine falls back to baked plates or the labeled demo plate.

```bash
npm test
npm run build
npm start
```

## Deploy on Vercel

1. In Vercel, **Add New Project** → import [`cursor-demo-lab/costco-mcp-demo`](https://github.com/cursor-demo-lab/costco-mcp-demo).
2. Framework preset: **Next.js**. Root directory: repo root. `vercel.json` already names the Next.js framework and leaves git deploys **enabled**.
3. Leave **Deployment Protection off** (public). Do not attach Internalsphere Passport / Okta.
4. Environment variables (Production + Preview):
   - `XAI_API_KEY` — optional, for live Grok
   - `MCP_DEMO_PASSWORD` — optional; defaults to `spacexai123`
   - `MCP_DEMO_USERNAME` — optional; defaults to `jordan`
   - `MCP_TOKEN_SECRET` — optional HMAC mint only
5. Deploy. Production is `https://costco-mcp-demo.vercel.app`. MCP is `https://costco-mcp-demo.vercel.app/api/mcp`.

Encrypted `secrets/**/*.sops.json` files may remain from the private source. They are not used on this public project. Set the Vercel env vars above instead of running `scripts/secrets.py`.

Cursor / Grok Bot:

```json
{
  "mcpServers": {
    "costco-saturday-run": {
      "url": "https://costco-mcp-demo.vercel.app/api/mcp",
      "headers": {
        "Authorization": "Bearer spacexai123"
      }
    }
  }
}
```

Local: `http://127.0.0.1:3000/api/mcp` with the same Bearer (or Basic `jordan:spacexai123`).

Full steps: [docs/mcp.md](./docs/mcp.md). Presenter debug on the phone/website (`?debug=1`) also copies the pair.

### Optional GitHub Pages connect page

[`docs/connect.html`](./docs/connect.html) is a static credentials card. Enable GitHub Pages on the `docs/` folder if you want that page without the Next.js app. The same file is served from the Vercel app at `/connect.html`.

## Kirk (member-app assistant)

**Kirk** is the consumer persona (`Talk to Kirk` / `Try Kirk` / `Ask Kirk`). Conversational choices stay in [`lib/prompts.ts`](./lib/prompts.ts). **Grok** is the engine only — never consumer chrome.

Costco DNA: membership above the fold, warehouse walk order, close with **Buy online** or **Save list for the store**. No live checkout, no 15-minute delivery hero.

## Layout

- `app/` — Next.js App Router; `/` phone, `/web` website; API routes for status / chat / Imagine / Voice / product photos / MCP
- `components/` — Chrome phone shell and website
- `lib/` — staged catalog, Grok client, Costco DNA prompts, MCP transport (`lib/mcp/`)
- `data/` — catalog zones (including furniture), recipes, preferences, baked plate ids
- `docs/mcp.md` — Grok Bot / Cursor connect
- `public/web-products/` — staged catalog photos
- `public/plates/` — baked dinner-plate photos for Imagine
- `gtmko-costco-pitch/` — presenter pitch deck
- `e2e/` + `lib/**/*.test.ts` — contract and unit tests

## Internalsphere leftovers

This tree was mirrored from a private Internalsphere app. Platform files (`QUICKSTART.md` notes, `app-manifest.yml`, encrypted sops, `.cursor/skills/*` for ranger) are inactive here. GitHub Actions in this repo run `npm test` + `npm run build` only — they do not call Internalsphere deploy workflows.