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

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

Then choose a client configuration from docs/CLIENTS.md. Configuration templates live in configs/.

Remotion demo

The repository includes a 36-second, 1080p Remotion product demo under demo/.

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:

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

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.

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

Example stdio configuration

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

See docs/CLIENTS.md for client-specific locations and commands.