Swiggy Deal Finder

Swiggy Deal Finder is an MCP connector that finds the cheapest nearby option for a dish on your own Swiggy account, ranked by final post-coupon payable amount.

It is designed for discovery only:

• no order placement
• read + controlled cart mutation for pricing probes
• automatic cart cleanup after each pricing probe

---

What this project does

Given a dish and a selected saved delivery address, the connector:

1. Finds open restaurants within 7 km.
2. Matches menu items for the requested dish.
3. Prices top candidates by probing Swiggy cart + coupon application.
4. Returns ranked options by:
   • lowest final payable amount (to_pay)
   • highest rating as tie-breaker

The MCP server exposes these tools:

• get_locations()
• list_dish_variants(dish, address_id, category?)
• find_deals(dish, address_id, top_n=5, portion="regular", category?)

---

Architecture overview

Core modules (src/swiggy_deal_finder):

• server.py
  MCP entrypoint (FastMCP), tool definitions, lifespan-managed persistent Swiggy client.
• live_client.py
  Real Swiggy adapter over mcp-remote (spawned via npx), wraps MCP tool calls.
• service.py
  Orchestration pipeline (DealFinder) for candidate discovery → pricing → ranking.
• candidates.py
  Restaurant/menu discovery, dish-token matching, distance/open filters, portion filtering.
• pricing.py
  Cart safety guard + coupon probe cycle. Handles empty-cart precondition and cart flush.
• ranking.py
  Final ordering logic (final_to_pay asc, rating desc).
• swiggy_client.py
  Protocol and pure parsers for Swiggy responses.
• models.py
  Pydantic domain models.
• main.py
  Minimal FastAPI app (/health) for service health checks.

---

Safety invariants

The project enforces a few critical rules:

• Never places an order.
• Refuses pricing if the cart is already non-empty.
• Never flushes a cart it did not create.
• Always flushes probe cart items after pricing completes (or on failure path after entry).
• Uses fresh cart reads for truth after coupon application.

---

Prerequisites

• Python >= 3.14 (as defined in pyproject.toml)
• uv for environment management
• Node.js / npx (used to spawn mcp-remote)
• A Swiggy account with saved delivery addresses

---

Setup

1. Install dependencies:

   uv sync --dev
   

2. Create environment file:

   cp .env.example .env
   

3. Fill required values in .env:

   • Swiggy MCP/OAuth values (as available in your environment)
   • Vertex/Gemini values for model access
   • APP_SECRET_KEY (required)

4. Validate connectivity:

   uv run python scripts/check_env.py
   

---

Running locally

1) FastAPI health app

uv run uvicorn swiggy_deal_finder.main:app --reload

Health endpoint:

• GET /health → {"status":"ok"}

2) MCP server (for Claude Desktop / MCP clients)

uv run python -m swiggy_deal_finder.server

This starts the MCP connector and keeps one persistent authenticated Swiggy session for tool calls.

---

Typical MCP usage flow

1. Call get_locations() and choose an address_id.
2. If dish is generic (e.g. dosa, pizza, biryani), call list_dish_variants(...) first.
3. Call find_deals(...) with the selected specific dish.
4. Present ranked results to the user.

Notes:

• category should be a broad cuisine/category term when dish search is too specific.
• portion="regular" excludes mini/half-style servings unless user explicitly asks.

---

Scripts

Repository scripts:

• scripts/check_env.py
  Validates env load + Swiggy MCP reachability + Vertex/Gemini reachability.
• scripts/smoke_live.py
  Read-only live smoke test against Swiggy MCP bridge.
• scripts/demo.py
  Runs the full deal-finder engine from CLI.
• scripts/check_server.py
  End-to-end MCP server check by spawning connector and invoking tools.

See also: DEMO.md for local Claude Desktop demo wiring details.

---

Development commands

Lint:

uv run ruff check .

Tests:

uv run pytest

---

Testing scope

Tests in tests/ cover:

• parser and config behavior
• candidate filtering and matching
• pricing/cart guard behavior
• ranking logic
• server tool behavior
• live-client adapter contract assumptions

---

Troubleshooting

• uv: command not found
  Install uv from https://docs.astral.sh/uv/installation/ and ensure it is in your PATH.

• No results for a specific dish phrase
  Retry with a broader category (e.g. dosa, biryani, roll) and then match exact dish via menu scan.

• Cart-not-empty response from find_deals
  Clear your cart in Swiggy app before pricing; this is a deliberate safety check.

• No saved addresses
  Add delivery addresses in your Swiggy app first.