# AVAS Food MCP — client-agnostic food ordering

A standard Python MCP server for AVAS Food: browse menus, build and quote carts, complete bank-transfer ordering with explicit confirmation, track deliveries, and analyze delivery spending.

The server uses **standard MCP over stdio** and has no Hermes runtime dependency. It works with Claude Code, OpenAI Codex CLI, Cursor, Gemini CLI, OpenCode, VS Code/Copilot, Windsurf, Hermes Agent, and other MCP-compatible clients.

## Quick start

```bash
git clone https://github.com/Rayyan011/avasfood-mcp.git
cd avasfood-mcp
./scripts/setup.sh
```

Then choose a client configuration from [`docs/CLIENTS.md`](docs/CLIENTS.md). Configuration templates live in [`configs/`](configs/).

## Remotion demo

The repository includes a 36-second, 1080p Remotion product demo under [`demo/`](demo/).

```bash
cd demo
npm install
npm run render
```

The rendered MP4 is written to `demo/out/avasfood-mcp-demo.mp4`.

## Tools

Existing tools:

- `get_client_metadata`
- `list_restaurants`
- `get_restaurant`
- `search_menu_items`
- `account_status`, `start_phone_login`, `verify_phone_login`
- `list_delivery_addresses`

Ordering tools:

- `get_menu` — authenticated merchant menu with zone, coordinates, and address context
- `add_to_cart`, `update_cart_item`, `remove_cart_item`, `view_cart`, `clear_cart` — local-only, single-merchant canonical `CartRow` storage
- `quote_cart` — calls `CalculationSalesOrder` and parses totals, payment modes, and bank details
- `stage_receipt` — validates/copies a PNG or JPEG locally; **does not upload**
- `upload_receipt` — uploads 500,000-character base64 chunks only after the exact confirmation phrase
- `prepare_order` — freezes the current cart/quote into an immutable, redacted preview and one-time token
- `submit_order` — requires that exact token, validates, then calls `SaveSalesOrder` once
- `track_deliveries` — live active-order, rider, and delivery state
- `delivery_spending_report` — private spending totals by fees, restaurant, and inferred food type

## Portable agent guidance

- `AGENTS.md` — vendor-neutral behavior and safety rules
- `CLAUDE.md` — Claude Code entry point
- `GEMINI.md` — Gemini CLI entry point
- MCP prompts: `food_assistant` and `delivery_budget_analyst`
- Optional skills under `skills/` for clients with compatible skill loaders

Hermes users may additionally install the optional skill packages:

```bash
mkdir -p ~/.hermes/skills/avasfood
cp -R skills/avas-food-assistant ~/.hermes/skills/avasfood/
cp -R skills/food-delivery-budgeting ~/.hermes/skills/avasfood/
```

The tools do not require those skills; they improve conversational orchestration only.

## Safety model

- Local state is stored under `~/.avasfood-mcp` with private directory/file permissions.
- Carts accept only one merchant at a time.
- Bank transfer is payment mode `4`; a receipt GUID is required before preparation.
- Receipt upload requires exactly: `I CONFIRM UPLOAD OF THIS BANK TRANSFER RECEIPT`.
- Preparing does not submit. Submission requires the exact generated token and an unchanged cart.
- `SaveSalesOrder` is never automatically retried. Before the call, the order is marked in-flight; transport failures are persisted as **ambiguous** and users must inspect order history.
- Tool results redact addresses/names and expose only the last four phone digits. Secrets are not stored in this repository.
- Spending history is written privately to `~/.avasfood-mcp/spending-history.json` only after a successful MCP-submitted order. It does not claim to include older AVAS orders.

## Typical flow

1. Link the account (`start_phone_login`, `verify_phone_login`) if needed.
2. Select an address/zone and call `get_menu`.
3. Build and inspect the local cart.
4. Call `quote_cart`.
5. If using bank transfer (`4`), call `stage_receipt`, inspect the staged metadata, then separately call `upload_receipt` with the exact phrase.
6. Call `prepare_order` and carefully inspect its preview.
7. Separately call `submit_order` with the returned token.

## Run

```bash
cd /Users/rayyu/personal/avasfood-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m avasfood_mcp.server
```

Optional environment variables:

- `AVAS_ACCESS_TOKEN` — approved backend token, if required
- `AVAS_API_BASE` — owner-approved API override
- `AVAS_ENVIRONMENT` — defaults to `LIVE`
- `AVAS_STATE_DIR` — local private state override

## Tests

Tests mock `_post`; they do not call AVAS production calculation or write endpoints.

```bash
.venv/bin/python -m unittest discover -s tests -p 'test_*.py' -v
```

## Example stdio configuration

```json
{
  "mcpServers": {
    "avasfood": {
      "command": "/absolute/path/avasfood-mcp/.venv/bin/python",
      "args": ["-m", "avasfood_mcp.server"]
    }
  }
}
```

See [`docs/CLIENTS.md`](docs/CLIENTS.md) for client-specific locations and commands.