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?)

Related MCP server: MealOS

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.