tapsifood-mcp 0.1.0__tar.gz

tapsifood_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest -q

tapsifood_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish
+
+# Tag a release (git tag v0.1.0 && git push --tags) after bumping the version in
+# pyproject.toml and server.json.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing
+      contents: write  # GitHub Release
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: Check versions match the tag
+        run: |
+          TAG=${GITHUB_REF_NAME#v}
+          grep -q "^version = \"$TAG\"" pyproject.toml
+          test "$(jq -r .version server.json)" = "$TAG"
+          test "$(jq -r '.packages[0].version' server.json)" = "$TAG"
+      - run: uv sync --locked && uv run pytest -q
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --title "$GITHUB_REF_NAME"
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  mcp-registry:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # MCP Registry login via GitHub OIDC
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - name: Wait for PyPI to serve the new version
+        run: |
+          for i in $(seq 1 30); do
+            curl -sf "https://pypi.org/pypi/tapsifood-mcp/${GITHUB_REF_NAME#v}/json" >/dev/null && exit 0
+            sleep 10
+          done
+          exit 1
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.1/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - run: ./mcp-publisher login github-oidc
+      - run: ./mcp-publisher publish

tapsifood_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.pytest_cache/
+.ruff_cache/

tapsifood_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sepehr Radmard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tapsifood_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: tapsifood-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for Tapsi Food: search dishes and restaurants, read menus and reviews, find flash deals.
+Project-URL: Homepage, https://github.com/sepehr071/tapsifood-mcp
+Project-URL: Issues, https://github.com/sepehr071/tapsifood-mcp/issues
+Author-email: Sepehr Radmard <sepehrr80@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: food-delivery,iran,mcp,model-context-protocol,tapsi,tapsifood
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: curl-cffi>=0.16.3
+Requires-Dist: httpx-curl-cffi>=0.1.5
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.2
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.sepehr071/tapsifood-mcp -->
+
+# tapsifood-mcp: Tapsi Food MCP server for AI agents
+
+**Let your AI agent shop around on Tapsi Food (تپسی‌فود).**
+An unofficial, read-only MCP server for Tapsi's food and grocery delivery in Iran: search dishes and restaurants near an
+address, read live menus and reviews, check delivery fees and minimum orders, and catch the Tap Time flash deals.
+
+## For AI agents
+
+- **What:** unofficial MCP server for Tapsi Food (tapsi.food) in Iran. Queries in Persian match best; prices in Toman.
+- **Install:** `uvx tapsifood-mcp` or `claude mcp add tapsifood -- uvx tapsifood-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none. Tapsi Food hangs connections from non-Iranian IPs: run it from Iran without a VPN, or set `TAPSIFOOD_MCP_PROXY` to an HTTP proxy that exits in Iran.
+- **Access:** read-only. No login, basket, orders or payment, so no confirmation is needed before calling any tool.
+- **Tools:** 11, all `tf_*`. Most need `lat` and `long` (not `tf_reviews`, `tf_find_location`, `tf_list_cities`).
+  Typical sequence: `tf_find_location` -> `tf_search_dishes` -> `tf_vendor_info` (-> `tf_menu`, `tf_reviews`).
+- **Coverage:** Tehran, Mashhad, Shiraz. Elsewhere the API answers 404 or `OutOfCoverage`.
+- **Output:** compact JSON. Prices in Toman, ratings 0-5. Null and empty fields are omitted (a missing `rating` = not rated); menu descriptions
+  are cut to 100 characters and review comments to 250 (`full_text: true` for the whole text, which lifts the size cap).
+  Replies stay under about 15 KB at the maximum `limit` (`tf_menu` 25, `tf_reviews` 20, `tf_search_dishes` 40).
+
+## Quick start
+
+```bash
+claude mcp add tapsifood -- uvx tapsifood-mcp
+# behind a proxy that exits in Iran:
+claude mcp add tapsifood -e TAPSIFOOD_MCP_PROXY=http://127.0.0.1:8080 -- uvx tapsifood-mcp
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `tf_find_location` | Turn a place name or address into latitude/longitude. |
+| `tf_reverse_geocode` | Describe coordinates as an address with province and city. |
+| `tf_list_cities` | List the cities Tapsi Food shows, with a center point and whether it delivers there. |
+| `tf_search_dishes` | Search dishes by name near a point; sort by relevance, cheapest, biggest discount, rating or distance. |
+| `tf_search_vendors` | Search restaurants and stores by name or cuisine near a point. |
+| `tf_restaurants` | List restaurants or grocery stores with rating, delivery fee, minimum order, ETA; filter by cuisine, discount, courier. |
+| `tf_deals` | List the Tap Time flash deals (limited-stock discounted dishes). |
+| `tf_discounted_vendors` | List the vendors in the Food Shots discount campaign. |
+| `tf_menu` | Read a vendor's live menu with price, discount and stock. |
+| `tf_vendor_info` | Get a vendor's delivery fee to a point, minimum order, packaging, ETA, status, hours, address and rating spread. |
+| `tf_reviews` | Read customer reviews of a vendor with per-dish ratings. |
+
+## Notes
+
+- Prices in the search index can lag the menu: confirm with `tf_menu`. Menu and profile minimums sometimes differ; `tf_vendor_info` returns both (`min_order`, `min_order_profile`).
+- Dish and vendor search list only restaurants open now (the site does the same), so at night `total` can be 0; `tf_restaurants` and
+  `tf_discounted_vendors` also list closed vendors, flagged `open: false`. `tf_search_dishes` `top_rated` / `cheapest` / `biggest_discount`
+  sort the first 100 matches, not the whole result set.
+- `eta_max` is the site's "up to N minutes" (its dialog shows roughly 20 to N); the API sends no lower bound. `tf_vendor_info.open_now`
+  follows the menu status (the live state the site shows); the profile's own status is just the vendor's on/off switch and is not returned.
+- `tf_reviews`: `total` counts every review including rating-only ones; only reviews with a comment are listed, so a page can hold fewer
+  than `limit` (keep paging while `has_more`). The site's tab badge shows just the first page's count. Writer names are left out on purpose.
+- Coupons are not exposed by the site's anonymous API.
+- Page 1 of the browse tools also carries filter and banner widgets, so it lists fewer vendors than `page_size`.
+- API map this server is built on: [`tapsifood/`](https://github.com/sepehr071/api-mcp) (endpoints, samples, quirks).
+
+## Development
+
+```bash
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run python -m pytest -q          # offline unit tests
+uv run python -m pytest -m live -q  # real API; needs an Iranian IP
+uv build
+```
+
+Unofficial: not affiliated with Tapsi. MIT licensed.

tapsifood_mcp-0.1.0/README.md

@@ -0,0 +1,70 @@
+<!-- mcp-name: io.github.sepehr071/tapsifood-mcp -->
+
+# tapsifood-mcp: Tapsi Food MCP server for AI agents
+
+**Let your AI agent shop around on Tapsi Food (تپسی‌فود).**
+An unofficial, read-only MCP server for Tapsi's food and grocery delivery in Iran: search dishes and restaurants near an
+address, read live menus and reviews, check delivery fees and minimum orders, and catch the Tap Time flash deals.
+
+## For AI agents
+
+- **What:** unofficial MCP server for Tapsi Food (tapsi.food) in Iran. Queries in Persian match best; prices in Toman.
+- **Install:** `uvx tapsifood-mcp` or `claude mcp add tapsifood -- uvx tapsifood-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none. Tapsi Food hangs connections from non-Iranian IPs: run it from Iran without a VPN, or set `TAPSIFOOD_MCP_PROXY` to an HTTP proxy that exits in Iran.
+- **Access:** read-only. No login, basket, orders or payment, so no confirmation is needed before calling any tool.
+- **Tools:** 11, all `tf_*`. Most need `lat` and `long` (not `tf_reviews`, `tf_find_location`, `tf_list_cities`).
+  Typical sequence: `tf_find_location` -> `tf_search_dishes` -> `tf_vendor_info` (-> `tf_menu`, `tf_reviews`).
+- **Coverage:** Tehran, Mashhad, Shiraz. Elsewhere the API answers 404 or `OutOfCoverage`.
+- **Output:** compact JSON. Prices in Toman, ratings 0-5. Null and empty fields are omitted (a missing `rating` = not rated); menu descriptions
+  are cut to 100 characters and review comments to 250 (`full_text: true` for the whole text, which lifts the size cap).
+  Replies stay under about 15 KB at the maximum `limit` (`tf_menu` 25, `tf_reviews` 20, `tf_search_dishes` 40).
+
+## Quick start
+
+```bash
+claude mcp add tapsifood -- uvx tapsifood-mcp
+# behind a proxy that exits in Iran:
+claude mcp add tapsifood -e TAPSIFOOD_MCP_PROXY=http://127.0.0.1:8080 -- uvx tapsifood-mcp
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `tf_find_location` | Turn a place name or address into latitude/longitude. |
+| `tf_reverse_geocode` | Describe coordinates as an address with province and city. |
+| `tf_list_cities` | List the cities Tapsi Food shows, with a center point and whether it delivers there. |
+| `tf_search_dishes` | Search dishes by name near a point; sort by relevance, cheapest, biggest discount, rating or distance. |
+| `tf_search_vendors` | Search restaurants and stores by name or cuisine near a point. |
+| `tf_restaurants` | List restaurants or grocery stores with rating, delivery fee, minimum order, ETA; filter by cuisine, discount, courier. |
+| `tf_deals` | List the Tap Time flash deals (limited-stock discounted dishes). |
+| `tf_discounted_vendors` | List the vendors in the Food Shots discount campaign. |
+| `tf_menu` | Read a vendor's live menu with price, discount and stock. |
+| `tf_vendor_info` | Get a vendor's delivery fee to a point, minimum order, packaging, ETA, status, hours, address and rating spread. |
+| `tf_reviews` | Read customer reviews of a vendor with per-dish ratings. |
+
+## Notes
+
+- Prices in the search index can lag the menu: confirm with `tf_menu`. Menu and profile minimums sometimes differ; `tf_vendor_info` returns both (`min_order`, `min_order_profile`).
+- Dish and vendor search list only restaurants open now (the site does the same), so at night `total` can be 0; `tf_restaurants` and
+  `tf_discounted_vendors` also list closed vendors, flagged `open: false`. `tf_search_dishes` `top_rated` / `cheapest` / `biggest_discount`
+  sort the first 100 matches, not the whole result set.
+- `eta_max` is the site's "up to N minutes" (its dialog shows roughly 20 to N); the API sends no lower bound. `tf_vendor_info.open_now`
+  follows the menu status (the live state the site shows); the profile's own status is just the vendor's on/off switch and is not returned.
+- `tf_reviews`: `total` counts every review including rating-only ones; only reviews with a comment are listed, so a page can hold fewer
+  than `limit` (keep paging while `has_more`). The site's tab badge shows just the first page's count. Writer names are left out on purpose.
+- Coupons are not exposed by the site's anonymous API.
+- Page 1 of the browse tools also carries filter and banner widgets, so it lists fewer vendors than `page_size`.
+- API map this server is built on: [`tapsifood/`](https://github.com/sepehr071/api-mcp) (endpoints, samples, quirks).
+
+## Development
+
+```bash
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run python -m pytest -q          # offline unit tests
+uv run python -m pytest -m live -q  # real API; needs an Iranian IP
+uv build
+```
+
+Unofficial: not affiliated with Tapsi. MIT licensed.

tapsifood_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "tapsifood-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for Tapsi Food: search dishes and restaurants, read menus and reviews, find flash deals."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Sepehr Radmard", email = "sepehrr80@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["mcp", "model-context-protocol", "tapsi", "tapsifood", "iran", "food-delivery"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp>=2.2,<3",
+    "httpx>=0.27",
+    "httpx-curl-cffi>=0.1.5",
+    "curl-cffi>=0.16.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/sepehr071/tapsifood-mcp"
+Issues = "https://github.com/sepehr071/tapsifood-mcp/issues"
+
+[project.scripts]
+tapsifood-mcp = "tapsifood_mcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not live'"
+markers = ["live: calls the real Tapsi Food API (run with -m live)"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["E501"]  # long Field(description=...) strings read better on one line

tapsifood_mcp-0.1.0/server.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.sepehr071/tapsifood-mcp",
+  "title": "Tapsi Food",
+  "description": "Unofficial read-only Tapsi Food: search dishes and restaurants, menus, reviews, flash deals.",
+  "repository": {
+    "url": "https://github.com/sepehr071/tapsifood-mcp",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/sepehr071/tapsifood-mcp",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "tapsifood-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "TAPSIFOOD_MCP_PROXY",
+          "description": "Optional HTTP proxy URL. Tapsi Food does not answer non-Iranian exit IPs (connections hang); system proxy settings are ignored. Also accepts a comma-separated list: one is used until it gets blocked or fails to connect, then the next.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

tapsifood_mcp-0.1.0/src/tapsifood_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Unofficial MCP server for Tapsi Food."""
+
+from importlib.metadata import version
+
+__version__ = version("tapsifood-mcp")

tapsifood_mcp-0.1.0/src/tapsifood_mcp/discover.py

@@ -0,0 +1,297 @@
+"""Search and browse tools: dishes, vendors, restaurant and grocery lists, flash deals, discounted vendors."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import Field
+
+from .http import fetch
+from .location import Lat, Long
+from .registry import tool
+
+Query = Annotated[str, Field(min_length=2, description="Dish or restaurant word, e.g. 'پیتزا'.")]
+Page = Annotated[int, Field(ge=1, le=50, description="Page number, from 1.")]
+
+FEED = "/v1/api/search-discovery/page-content/"
+SEARCH = "/v1/api/search-discovery/Search/"
+DELIVERY = {"tapsi": "OfoodDelivery", "vendor": "OwnDelivery"}
+
+
+def _stars(v: float | None) -> float | None:
+    return round(v, 1) if v else None
+
+
+def _dish(d: dict[str, Any]) -> dict[str, Any]:
+    p, v = d["productInfo"], d.get("vendorInfo") or {}
+    return {
+        "id": p["id"],
+        "product_id": str(p["headerId"]) if p.get("headerId") is not None else None,
+        "name": p["name"].strip(),
+        "price": p["price"],
+        "discount_pct": p.get("discountRatio") or 0,
+        "final_price": p["priceAfterDiscount"],
+        "rating": _stars(p.get("rate")),
+        "vendor_code": v.get("vendorCode"),
+        "vendor": (v.get("title") or "").strip(),
+        "vendor_rating": _stars(v.get("rate")),
+        "delivery_fee": v.get("deliveryPrice"),
+        "eta_max": v.get("eta"),
+        "open": v.get("vendorStatus"),
+    }
+
+
+def _vendor(code: str, title: str | None, v: dict[str, Any]) -> dict[str, Any]:
+    """One vendor card; search rows and feed rows name the same facts differently."""
+    badges = [b["name"] for b in v.get("badges") or [] if b.get("name")]
+    return {
+        "code": code,
+        "title": (title or "").strip(),
+        "rating": _stars(v.get("rate")),
+        "ratings_count": v.get("ratesCount"),
+        "open": v["isOpen"] if "isOpen" in v else v.get("vendorStatus") == "Open",
+        "delivery_fee": v.get("deliveryPrice"),
+        "delivery_by": "vendor" if v.get("deliveryType") == "OwnDelivery" else "tapsi",
+        "min_order": int(v["minimumBasket"]) if v.get("minimumBasket") else None,
+        "eta_max": v.get("eta"),
+        "discount_pct": int(v["discount"]) if v.get("discount") else None,
+        "badges": badges,
+    }
+
+
+@tool("Search dishes")
+async def tf_search_dishes(
+    query: Query,
+    lat: Lat,
+    long: Long,
+    sort: Annotated[
+        Literal["relevance", "cheapest", "biggest_discount", "top_rated", "nearest"],
+        Field(
+            description="Order of the results; cheapest / biggest_discount / top_rated sort the first 100 matches "
+            "(top_rated = dish rating, then restaurant rating; unrated last). nearest is Tapsi's own order."
+        ),
+    ] = "relevance",
+    discounted_only: Annotated[bool, Field(description="Only dishes with a discount.")] = False,
+    page: Page = 1,
+    limit: Annotated[int, Field(ge=1, le=40, description="Max dishes (40 keeps the reply under 15 KB).")] = 10,
+) -> dict[str, Any]:
+    """Search dishes by name near a delivery point, with price, discount and restaurant.
+
+    Use for "find X near me" or "cheapest / discounted X". Prices are the search index's and can lag
+    the menu: confirm with tf_menu before recommending. Then call tf_vendor_info for fee and minimum order.
+    Tapsi's search lists only restaurants open now: at night total can be 0 (the site shows the same);
+    tf_restaurants / tf_discounted_vendors also list closed vendors.
+    """
+    pooled = sort in ("cheapest", "biggest_discount", "top_rated")  # the API ignores ratingdesc for dishes
+    filters = ["HasDiscount"] if discounted_only else []
+    if sort == "nearest":
+        filters.append("distance")
+    body = await fetch(
+        SEARCH + "product-search",
+        {
+            "latitude": lat,
+            "longitude": long,
+            "query": query,
+            "pageNumber": 1 if pooled else page,
+            "pageSize": 100 if pooled else limit,
+            "filtersAndSorts": filters or None,
+        },
+    )
+    dishes = [_dish(d) for d in body.get("data") or []]
+    if sort == "cheapest":
+        dishes.sort(key=lambda d: d["final_price"])
+    elif sort == "biggest_discount":
+        dishes.sort(key=lambda d: -d["discount_pct"])
+    elif sort == "top_rated":
+        dishes.sort(key=lambda d: (-(d["rating"] or 0), -(d["vendor_rating"] or 0)))
+    if pooled:  # the pool is page 1 of 100 hits; slice the requested page out of it
+        dishes = dishes[(page - 1) * limit :]
+    return {"total": body["meta"]["totalItems"], "dishes": dishes[:limit]}
+
+
+@tool("Search vendors")
+async def tf_search_vendors(
+    query: Query,
+    lat: Lat,
+    long: Long,
+    page: Page = 1,
+    limit: Annotated[int, Field(ge=1, le=50, description="Max vendors.")] = 10,
+) -> dict[str, Any]:
+    """Search restaurants and stores by name or cuisine near a delivery point.
+
+    Use to find a vendor code by name. No dish prices: use tf_menu or tf_search_dishes.
+    Tapsi's search lists only restaurants open now (total 0 at night, as on the site); tf_restaurants also lists closed ones.
+    """
+    body = await fetch(
+        SEARCH + "vendor-search",
+        {"latitude": lat, "longitude": long, "query": query, "pageNumber": page, "pageSize": limit},
+    )
+    return {
+        "total": body["meta"]["totalItems"],
+        "vendors": [_vendor(r["vendorCode"], (i := r["vendorInfo"])["title"], i) for r in body.get("data") or []],
+    }
+
+
+async def _feed(slug: str, lat: float, long: float, filters: list[str], page: int, size: int) -> dict[str, Any]:
+    """One page of a CMS feed. Page 1 also carries filter and banner widgets, so it holds fewer rows."""
+    body = await fetch(
+        FEED + slug,
+        {
+            "latitude": lat,
+            "longitude": long,
+            "bypassCache": "false",
+            "pageNumber": page,
+            "pageSize": size,
+            "filtersAndSorts": filters or None,
+        },
+    )
+    rows, chips = [], []
+    for c in body.get("content") or []:
+        if c["type"] in (1, 2) and c.get("defaultFeedContent"):
+            rows.append(c)
+        elif (c.get("component") or {}).get("type") == 1039:  # category chips, only on page 1
+            chips = [
+                {"title": i["payload"]["title"], "filter": i["filterValue"]}
+                for i in c["component"]["items"]
+                if i.get("filterValue")
+            ]
+    meta = body["meta"]
+    total = rows[0].get("feedMeta", {}).get("totalItems") if rows else 0
+    return {
+        "rows": [r["defaultFeedContent"] for r in rows],
+        "chips": chips,
+        "total": total if total is not None else meta["totalItems"],
+        "has_more": meta["pageNumber"] * meta["pageSize"] < meta["totalItems"],
+    }
+
+
+def _filters(sort: str | None, discounted_only: bool, delivery: str, new_only: bool, category: str | None) -> list[str]:
+    out = [category] if category else []
+    out += [sort] if sort else []
+    out += ["HasDiscount"] if discounted_only else []
+    out += [DELIVERY[delivery]] if delivery in DELIVERY else []
+    out += ["NewVendor"] if new_only else []
+    return out
+
+
+@tool("List restaurants")
+async def tf_restaurants(
+    lat: Lat,
+    long: Long,
+    kind: Annotated[
+        Literal["restaurants", "groceries"], Field(description="restaurants, or grocery stores (خواربار).")
+    ] = "restaurants",
+    category: Annotated[
+        str | None,
+        Field(description="Cuisine chip filter from the 'categories' of a page-1 result, e.g. '1-82' (kebab)."),
+    ] = None,
+    sort: Annotated[
+        Literal["default", "top_rated", "popular", "nearest"], Field(description="Order of the results.")
+    ] = "default",
+    discounted_only: Annotated[bool, Field(description="Only vendors with a discount.")] = False,
+    delivery: Annotated[
+        Literal["any", "tapsi", "vendor"], Field(description="Courier: Tapsi's own, or the vendor's.")
+    ] = "any",
+    new_only: Annotated[bool, Field(description="Only new vendors.")] = False,
+    page: Page = 1,
+    page_size: Annotated[
+        int,
+        Field(
+            ge=5, le=50, description="Feed items per page; page 1 spends some on widgets, so it lists fewer vendors."
+        ),
+    ] = 20,
+) -> dict[str, Any]:
+    """List restaurants (or grocery stores) delivering to a point, with rating, delivery fee, minimum order and ETA.
+
+    Use to browse or rank vendors. Page 1 also returns 'categories' (cuisine filters for the category param).
+    No dish prices: use tf_menu. Returns 404 outside the served cities (tf_list_cities).
+    """
+    sort_key = {"top_rated": "ratingdesc", "popular": "mostpopular", "nearest": "distance"}.get(sort)
+    slug = "business-line-15" if kind == "restaurants" else "business-line-7"
+    f = await _feed(slug, lat, long, _filters(sort_key, discounted_only, delivery, new_only, category), page, page_size)
+    return {
+        "total": f["total"],
+        "has_more": f["has_more"],
+        "categories": f["chips"],
+        "vendors": [_vendor(r["vendorCode"], r["title"], r) for r in f["rows"]],
+    }
+
+
+@tool("Flash deals")
+async def tf_deals(
+    lat: Lat,
+    long: Long,
+    sort: Annotated[
+        Literal["default", "most_discounted", "most_purchased", "cheapest", "top_rated"],
+        Field(description="Order of the deals."),
+    ] = "most_discounted",
+    category: Annotated[str | None, Field(description="Cuisine chip filter from 'categories', e.g. '1-82'.")] = None,
+    page: Page = 1,
+    page_size: Annotated[
+        int,
+        Field(ge=5, le=50, description="Feed items per page; page 1 spends some on widgets, so it lists fewer deals."),
+    ] = 20,
+) -> dict[str, Any]:
+    """List the Tap Time flash deals (تپ تایم): discounted dishes with a limited stock, near a point.
+
+    Use for "today's best deals". Not the same as Snappfood's FoodParty. Check stock_left, it runs out.
+    Then tf_menu / tf_vendor_info for the restaurant.
+    """
+    sort_key = {
+        "most_discounted": "mostdiscounted",
+        "most_purchased": "mostpurchased",
+        "cheapest": "cheapest",
+        "top_rated": "ratingdesc",
+    }.get(sort)
+    f = await _feed("تپ-تایم", lat, long, _filters(sort_key, False, "any", False, category), page, page_size)
+    return {
+        "total": f["total"],
+        "has_more": f["has_more"],
+        "categories": f["chips"],
+        "deals": [
+            {
+                "id": r["productVariationId"],
+                "product_id": r.get("headerId"),
+                "name": r["productName"].strip(),
+                "price": r["price"],
+                "discount_pct": int(r.get("discountRatio") or 0),
+                "final_price": r["priceAfterDiscount"],
+                "stock_left": r.get("discountStock"),
+                "rating": _stars(r.get("productRate")),
+                "vendor_code": r["vendorCode"],
+                "vendor": (r.get("vendorName") or "").strip(),
+                "delivery_fee": r.get("deliveryPrice"),
+                "open": r.get("vendorStatus") == "Open",
+            }
+            for r in f["rows"]
+        ],
+    }
+
+
+@tool("Discounted vendors")
+async def tf_discounted_vendors(
+    lat: Lat,
+    long: Long,
+    sort: Annotated[
+        Literal["default", "top_rated", "popular", "nearest"], Field(description="Order of the results.")
+    ] = "default",
+    page: Page = 1,
+    page_size: Annotated[
+        int,
+        Field(
+            ge=5, le=50, description="Feed items per page; page 1 spends some on widgets, so it lists fewer vendors."
+        ),
+    ] = 20,
+) -> dict[str, Any]:
+    """List the vendors in Tapsi Food's 'Food Shots' (فودشات) discount campaign near a point.
+
+    Use for "which restaurants have the biggest discount". discount_pct is the vendor-wide percentage.
+    The campaign is curated, so not every discounted vendor is in it (tf_restaurants with discounted_only is wider).
+    """
+    sort_key = {"top_rated": "ratingdesc", "popular": "mostpopular", "nearest": "distance"}.get(sort)
+    f = await _feed("فودشات", lat, long, _filters(sort_key, False, "any", False, None), page, page_size)
+    return {
+        "total": f["total"],
+        "has_more": f["has_more"],
+        "vendors": [_vendor(r["vendorCode"], r["title"], r) for r in f["rows"]],
+    }