Sushimaster

<p align="center"> <img src="assets/banner.png" alt="Sushimaster banner" width="80%"> </p>

MCP tool for AI agents (Claude Code, Claude Desktop, Codex) that finds deals in food delivery apps. Ask your agent "find a pizza under 50 PLN with free delivery" and it will search Wolt and Glovo, compare prices, ratings, delivery estimates and promotions, and return a ready recommendation with a link.

The problem it solves

<p align="center"> <picture> <source media="(max-width: 640px)" srcset="assets/problem-solution-mobile.svg"> <img src="assets/problem-solution.svg" alt="Sushimaster searches delivery apps, compares offers and returns the best deal" width="100%"> </picture> </p>

<p align="center"> <strong>No account. No API keys. No manual configuration.</strong><br> Just share this repository link with your agent and ask it to install Sushimaster. The agent will clone the repo, set everything up and connect the MCP server on its own. That's it. </p>

<p align="center"> <strong>Built to grow.</strong><br> The architecture is provider-agnostic. Adding new apps such as Uber Eats or Deliveroo means implementing one class that subclasses <code>BaseProvider</code>. </p>

---

Features

MCP tool	Description
list_providers	List available food delivery apps
resolve_location	Resolve an address / lat,lon to coordinates
search_venues	Find restaurants (rating 0–10, ETA, free-delivery flags, promotions)
search_items	Find dishes with prices in cents; filter by price, rating, free delivery
get_venue_menu	Fetch a full restaurant menu (discounted items included)

• No login, no API keys — data comes from the public Wolt and Glovo endpoints.
• Prices are normalized to cents (int), ratings to a 0–10 scale.
• Every result is tagged with fetched_at and a per-provider report (responded?, latency, warnings) so the agent can attribute the data honestly.
• Results are cached (TTL) with single-flight protection.

Requirements

• Python 3.10+
• uv (for installation and running)

Installation

cd sushimaster
uv sync --extra dev      # create .venv and install dependencies (+ dev tools)

This installs two console commands into .venv/bin/:

Command	Purpose
sushimaster	CLI for quick testing (resolve / venues / items / menu)
sushimaster-mcp	MCP server (stdio transport)

To call them as plain sushimaster … / sushimaster-mcp, either activate the virtualenv (source .venv/bin/activate) or add .venv/bin to your PATH. Alternatively, use uv run sushimaster … from the project directory.

Usage

CLI (quick testing without MCP)

sushimaster resolve "Warszawa, Marszałkowska 98"
sushimaster venues "pizza" "52.2297,21.0122" --apps wolt,glovo --free-delivery
sushimaster items "pizza margherita" "Warszawa" --max-price 5000 --min-rating 8
sushimaster menu glovo "dodo-pizza-waw" "52.2297,21.0122"

MCP server (stdio)

sushimaster-mcp

Claude Code configuration (claude mcp add):

claude mcp add sushimaster -- /path/to/sushimaster/.venv/bin/sushimaster-mcp

Or in ~/.claude.json:

{
  "mcpServers": {
    "sushimaster": {
      "command": "/path/to/sushimaster/.venv/bin/sushimaster-mcp",
      "args": []
    }
  }
}

Once connected, try: "Find a pizza under 50 PLN with free delivery in Warsaw."

Instructions for agents

This section is written for AI agents (Claude Code, Codex, Claude Desktop) that need to install and use Sushimaster. Follow the steps in order.

0. Prerequisites

• Python 3.10+ — check with python3 --version
• uv — check with uv --version
• git — check with git --version

1. Clone and install

git clone <repository-url> sushimaster
cd sushimaster
uv sync --extra dev        # creates .venv/ and installs the package

This produces two executables in .venv/bin/: sushimaster (CLI) and sushimaster-mcp (MCP server). Remember the absolute path to sushimaster-mcp — you will need it in step 2. Get it with:

echo "$(pwd)/.venv/bin/sushimaster-mcp"

2. Register the MCP server

Pick the section matching your agent.

Claude Code (project-scoped, recommended):

claude mcp add sushimaster -- /absolute/path/to/sushimaster/.venv/bin/sushimaster-mcp

Then restart Claude Code and verify with /mcp — the sushimaster server should be listed as connected with 5 tools.

Claude Code (alternative — .mcp.json in the project root, committed to the repo):

{
  "mcpServers": {
    "sushimaster": {
      "command": "/absolute/path/to/sushimaster/.venv/bin/sushimaster-mcp",
      "args": []
    }
  }
}

Codex:

codex mcp add sushimaster -- /absolute/path/to/sushimaster/.venv/bin/sushimaster-mcp

Claude Desktop — add the same mcpServers entry to claude_desktop_config.json (Claude → Settings → Developer → Edit config), then restart Claude Desktop.

Do not use uv run or python -m as the command — the installed script is self-contained and avoids spawning an extra process.

3. Verify the installation

From the shell:

/absolute/path/to/sushimaster/.venv/bin/sushimaster resolve "Warszawa"

Expected: JSON with lat, lon, label and country_code: "PL".

From the agent, ask: "list your available tools" or call list_providers. Expected: [{"name": "wolt", "display_name": "Wolt"}, {"name": "glovo", "display_name": "Glovo"}].

Then run an end-to-end query:

"Find a pizza margherita under 40 PLN in Warsaw and list the results with prices."

4. Tool reference for agents

Tool	Purpose	Key parameters
list_providers	Available apps	—
resolve_location	Address / lat,lon → coordinates	address
search_venues	Restaurants	query, address, apps, free_delivery, min_rating, limit
search_items	Dishes	query, address, max_price_cents, min_rating, free_delivery, sort, limit
get_venue_menu	Restaurant menu	provider, venue_id, address

Conventions the agent should follow when answering users:

• Prices are in cents — divide by 100 for PLN (e.g. 3699 → 36.99 zł).
• Ratings are 0–10.
• Always mention the source app (Wolt/Glovo) and the delivery flag (free_delivery) for each recommendation.
• venue_id from search results can be passed straight to get_venue_menu.
• Read the warnings array — it may explain partial data (e.g. Wolt menu previews) or failed providers.

5. Run the tests

cd sushimaster
uv run pytest             # offline tests on frozen API fixtures
uv run pytest -m live     # optional: live tests against real APIs

6. Troubleshooting

Symptom	Fix
sushimaster-mcp: command not found	Run uv sync --extra dev again; check the path from step 1
MCP server listed as failed	Restart the agent; verify the absolute path has no symlinks/quotes
No module named 'yaml' / unrelated plugin errors	PYTHONPATH from another toolchain (e.g. ROS) leaks in — run PYTHONPATH= uv run pytest
Tools return empty providers	SUSHIMASTER_PROVIDERS env var may be filtering them — unset it or list the apps explicitly
No results for a city	The app may not cover that city (Glovo is limited to larger cities in Poland) — try resolve_location first

Configuration (environment variables)

Variable	Default	Description
SUSHIMASTER_CACHE_TTL	600	Result cache TTL in seconds
SUSHIMASTER_PROVIDERS	empty (all)	Active providers, comma-separated, e.g. wolt,glovo
SUSHIMASTER_REQUEST_INTERVAL	0.35	Minimum interval between API requests (seconds)
SUSHIMASTER_TIMEOUT	15	HTTP request timeout (seconds)

Project structure

src/sushimaster/
├── server.py            # MCP server (FastMCP) + tool definitions
├── service.py           # orchestration: caching, filtering, dedup, reports
├── geo.py               # address → coordinates (multi-provider resolution)
├── models.py            # shared, normalized schema (Venue, MenuItem, …)
├── cache.py             # TTL cache with single-flight
└── providers/
    ├── base.py          # BaseProvider — the contract for new providers
    ├── wolt.py          # Wolt adapter
    └── glovo.py         # Glovo adapter

Adding a new provider

1. Create src/sushimaster/providers/<name>.py subclassing BaseProvider.
2. Set name / display_name and implement the three abstract methods:
   • search_venues(query, location, *, limit) -> list[Venue]
   • search_items(query, location, *, limit) -> list[MenuItem]
   • get_venue_menu(venue_id, location) -> MenuFetchResult
3. Optionally implement geocode() and check_availability().
4. Register the class with the @register decorator and add the module import in providers/__init__.py (importing the module runs the decorator).
5. Done — caching, filtering, dedup and the MCP tools pick it up automatically.

Every provider gets, for free: HTTP with retry/backoff and error mapping (429 → RateLimitError), an enforced minimum interval between requests, price parsing (_to_cents handles "36,99 zł", 3699, 36.99) and rating normalization (_normalize_rating maps "98%" → 9.8). The full contract is documented in the providers/base.py docstring.

Known limitations

• Full Wolt menus require a web session; the adapter returns dish previews from the restaurant list and always reports this as a warning. Glovo provides complete menus.
• Wolt delivery fees are calculated dynamically at the basket level — the adapter exposes approximation flags (delivery_price_highlight, Wolt+). Glovo returns the real fee and the isFreeDeliveryFee flag directly.
• Personal promotions (discount codes, Wolt+/Prime prices) require an authenticated session and are not visible to this tool.
• Glovo coverage in Poland is limited to larger cities.

Privacy & data handling

• The tool only reads public data (venues, menus, prices) from provider APIs.
• It performs no authentication and stores no user data on disk.
• The in-memory result cache holds only public search results and expires automatically (TTL).
• No telemetry, no tracking, no third-party services — geocoding is done through the providers' own endpoints.

Tests

uv run pytest             # offline tests on frozen API responses (fixtures)
uv run pytest -m live     # live tests against the real APIs (1s request interval)

Offline tests use fixtures from tests/fixtures/ — real API responses captured during development, so parser regressions are caught without the network. To regenerate fixtures, capture fresh API responses and replace the files.

Note: in environments with PYTHONPATH set (e.g. ROS), run pytest with PYTHONPATH= to avoid loading unrelated plugins.

Disclaimer

Sushimaster is an unofficial project. It is not affiliated with, endorsed by, or sponsored by Wolt or Glovo. The provider endpoints are public but undocumented and may change or require authentication at any time; use the tool at your own risk and respect each platform's terms of service and rate limits (the built-in request pacing is there to help with that).