Sushimaster

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

Related MCP server: OrderFood MCP

Features

• 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/:

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

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

Configuration (environment variables)

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