snapp-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- snapp_mcp-0.1.0/.github/workflows/ci.yml +21 -0
- snapp_mcp-0.1.0/.github/workflows/publish.yml +48 -0
- snapp_mcp-0.1.0/.gitignore +6 -0
- snapp_mcp-0.1.0/LICENSE +21 -0
- snapp_mcp-0.1.0/PKG-INFO +177 -0
- snapp_mcp-0.1.0/README.md +157 -0
- snapp_mcp-0.1.0/pyproject.toml +48 -0
- snapp_mcp-0.1.0/server.json +32 -0
- snapp_mcp-0.1.0/src/snapp_mcp/__init__.py +5 -0
- snapp_mcp-0.1.0/src/snapp_mcp/food.py +607 -0
- snapp_mcp-0.1.0/src/snapp_mcp/http.py +132 -0
- snapp_mcp-0.1.0/src/snapp_mcp/location.py +88 -0
- snapp_mcp-0.1.0/src/snapp_mcp/market.py +418 -0
- snapp_mcp-0.1.0/src/snapp_mcp/registry.py +16 -0
- snapp_mcp-0.1.0/src/snapp_mcp/server.py +49 -0
- snapp_mcp-0.1.0/tests/conftest.py +61 -0
- snapp_mcp-0.1.0/tests/fixtures/food_cities.json +31 -0
- snapp_mcp-0.1.0/tests/fixtures/food_gem_session.json +9 -0
- snapp_mcp-0.1.0/tests/fixtures/food_gem_vendor_list.json +41 -0
- snapp_mcp-0.1.0/tests/fixtures/food_meal_for_one.json +78 -0
- snapp_mcp-0.1.0/tests/fixtures/food_menu.json +100 -0
- snapp_mcp-0.1.0/tests/fixtures/food_min_basket_rules.json +15 -0
- snapp_mcp-0.1.0/tests/fixtures/food_off_box.json +33 -0
- snapp_mcp-0.1.0/tests/fixtures/food_party.json +84 -0
- snapp_mcp-0.1.0/tests/fixtures/food_place_search.json +74 -0
- snapp_mcp-0.1.0/tests/fixtures/food_reverse_geocode.json +20 -0
- snapp_mcp-0.1.0/tests/fixtures/food_reviews.json +62 -0
- snapp_mcp-0.1.0/tests/fixtures/food_search.json +98 -0
- snapp_mcp-0.1.0/tests/fixtures/food_vendor_rewards.json +56 -0
- snapp_mcp-0.1.0/tests/fixtures/food_vendor_state.json +21 -0
- snapp_mcp-0.1.0/tests/fixtures/food_vendors_list.json +63 -0
- snapp_mcp-0.1.0/tests/fixtures/market_categories.json +43 -0
- snapp_mcp-0.1.0/tests/fixtures/market_party_deals.json +118 -0
- snapp_mcp-0.1.0/tests/fixtures/market_product.json +38 -0
- snapp_mcp-0.1.0/tests/fixtures/market_reviews.json +39 -0
- snapp_mcp-0.1.0/tests/fixtures/market_search.json +315 -0
- snapp_mcp-0.1.0/tests/fixtures/market_store_categories.json +34 -0
- snapp_mcp-0.1.0/tests/fixtures/market_store_category_products.json +61 -0
- snapp_mcp-0.1.0/tests/fixtures/market_store_coupons.json +40 -0
- snapp_mcp-0.1.0/tests/fixtures/market_store_info.json +75 -0
- snapp_mcp-0.1.0/tests/fixtures/market_store_products.json +56 -0
- snapp_mcp-0.1.0/tests/fixtures/market_stores.json +144 -0
- snapp_mcp-0.1.0/tests/test_food.py +271 -0
- snapp_mcp-0.1.0/tests/test_live_food.py +63 -0
- snapp_mcp-0.1.0/tests/test_live_market.py +59 -0
- snapp_mcp-0.1.0/tests/test_location.py +42 -0
- snapp_mcp-0.1.0/tests/test_market.py +160 -0
- snapp_mcp-0.1.0/uv.lock +1112 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
strategy:
|
|
12
|
+
matrix:
|
|
13
|
+
python: ["3.10", "3.11", "3.12", "3.13"]
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v4
|
|
16
|
+
- uses: astral-sh/setup-uv@v6
|
|
17
|
+
with:
|
|
18
|
+
python-version: ${{ matrix.python }}
|
|
19
|
+
- run: uv sync --locked
|
|
20
|
+
- run: uv run ruff check .
|
|
21
|
+
- run: uv run pytest -q
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
name: Publish
|
|
2
|
+
|
|
3
|
+
# Tag a release (git tag v0.1.0 && git push --tags) after bumping the version in
|
|
4
|
+
# pyproject.toml and server.json.
|
|
5
|
+
on:
|
|
6
|
+
push:
|
|
7
|
+
tags: ["v*"]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
pypi:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
environment: pypi
|
|
13
|
+
permissions:
|
|
14
|
+
id-token: write # PyPI trusted publishing
|
|
15
|
+
contents: read
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v4
|
|
18
|
+
- uses: astral-sh/setup-uv@v6
|
|
19
|
+
- name: Check versions match the tag
|
|
20
|
+
run: |
|
|
21
|
+
TAG=${GITHUB_REF_NAME#v}
|
|
22
|
+
grep -q "^version = \"$TAG\"" pyproject.toml
|
|
23
|
+
test "$(jq -r .version server.json)" = "$TAG"
|
|
24
|
+
test "$(jq -r '.packages[0].version' server.json)" = "$TAG"
|
|
25
|
+
- run: uv sync --locked && uv run pytest -q
|
|
26
|
+
- run: uv build
|
|
27
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
28
|
+
|
|
29
|
+
mcp-registry:
|
|
30
|
+
needs: pypi
|
|
31
|
+
runs-on: ubuntu-latest
|
|
32
|
+
permissions:
|
|
33
|
+
id-token: write # MCP Registry login via GitHub OIDC
|
|
34
|
+
contents: read
|
|
35
|
+
steps:
|
|
36
|
+
- uses: actions/checkout@v4
|
|
37
|
+
- name: Wait for PyPI to serve the new version
|
|
38
|
+
run: |
|
|
39
|
+
for i in $(seq 1 30); do
|
|
40
|
+
curl -sf "https://pypi.org/pypi/snapp-mcp/${GITHUB_REF_NAME#v}/json" >/dev/null && exit 0
|
|
41
|
+
sleep 10
|
|
42
|
+
done
|
|
43
|
+
exit 1
|
|
44
|
+
- name: Install mcp-publisher
|
|
45
|
+
run: |
|
|
46
|
+
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
|
|
47
|
+
- run: ./mcp-publisher login github-oidc
|
|
48
|
+
- run: ./mcp-publisher publish
|
snapp_mcp-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Sepehr
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
snapp_mcp-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: snapp-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Unofficial read-only MCP server for Snappfood and SnappMarket: search food and groceries, compare prices, find deals.
|
|
5
|
+
Project-URL: Homepage, https://github.com/sepehr071/snapp-mcp
|
|
6
|
+
Project-URL: Issues, https://github.com/sepehr071/snapp-mcp/issues
|
|
7
|
+
Author-email: Sepehr <sepehr@nextofx.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: food-delivery,grocery,iran,mcp,model-context-protocol,snappfood,snappmarket
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
16
|
+
Requires-Python: >=3.10
|
|
17
|
+
Requires-Dist: httpx>=0.27
|
|
18
|
+
Requires-Dist: mcp<3,>=2.2
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
|
|
21
|
+
# snapp-mcp
|
|
22
|
+
|
|
23
|
+
<!-- mcp-name: io.github.sepehr071/snapp-mcp -->
|
|
24
|
+
|
|
25
|
+
[](https://pypi.org/project/snapp-mcp/)
|
|
26
|
+
[](https://github.com/sepehr071/snapp-mcp/actions/workflows/ci.yml)
|
|
27
|
+
[](LICENSE)
|
|
28
|
+
|
|
29
|
+
An MCP server that lets AI agents use **Snappfood** (restaurant delivery) and **SnappMarket**
|
|
30
|
+
(grocery delivery) in Iran. Agents can search dishes and groceries, compare prices across
|
|
31
|
+
restaurants and stores, read menus and reviews, and find live deals.
|
|
32
|
+
|
|
33
|
+
It is **read-only**: it cannot log in, add to a basket or place an order.
|
|
34
|
+
|
|
35
|
+
> Unofficial. Not affiliated with or endorsed by Snapp. It uses the same public endpoints as
|
|
36
|
+
> the snappfood.ir and snapp.market web apps, which can change without notice.
|
|
37
|
+
|
|
38
|
+
## Example prompts
|
|
39
|
+
|
|
40
|
+
- "Cheapest pizza delivered to Vanak Square right now, including delivery fee."
|
|
41
|
+
- "Which restaurants near me in Shiraz have free delivery and a rating above 4?"
|
|
42
|
+
- "Show today's FoodParty deals with more than 40% off."
|
|
43
|
+
- "Where can I buy low-fat milk cheapest near Jordan, Tehran?"
|
|
44
|
+
- "Is restaurant 947evd's minimum order above 200,000 Toman? Any coupons?"
|
|
45
|
+
|
|
46
|
+
## Requirements
|
|
47
|
+
|
|
48
|
+
- [uv](https://docs.astral.sh/uv/getting-started/installation/) (provides `uvx`), or Python 3.10+ with pip.
|
|
49
|
+
- **An Iranian IP address.** Snappfood's firewall rejects most foreign IPs (HTTP 403). Run the server on
|
|
50
|
+
a machine in Iran with VPN off, or point `SNAPP_MCP_PROXY` at a proxy in Iran. SnappMarket is less strict.
|
|
51
|
+
|
|
52
|
+
## Install
|
|
53
|
+
|
|
54
|
+
### Claude Code
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
claude mcp add snapp -- uvx snapp-mcp
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### Claude Desktop
|
|
61
|
+
|
|
62
|
+
Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
|
|
63
|
+
|
|
64
|
+
```json
|
|
65
|
+
{
|
|
66
|
+
"mcpServers": {
|
|
67
|
+
"snapp": {
|
|
68
|
+
"command": "uvx",
|
|
69
|
+
"args": ["snapp-mcp"]
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Cursor
|
|
76
|
+
|
|
77
|
+
Add the same block to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project).
|
|
78
|
+
|
|
79
|
+
### VS Code (Copilot agent mode)
|
|
80
|
+
|
|
81
|
+
Add to `.vscode/mcp.json`:
|
|
82
|
+
|
|
83
|
+
```json
|
|
84
|
+
{
|
|
85
|
+
"servers": {
|
|
86
|
+
"snapp": {
|
|
87
|
+
"type": "stdio",
|
|
88
|
+
"command": "uvx",
|
|
89
|
+
"args": ["snapp-mcp"]
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Any other MCP client
|
|
96
|
+
|
|
97
|
+
Run `uvx snapp-mcp` (or `pip install snapp-mcp` then `snapp-mcp`) as a stdio server.
|
|
98
|
+
|
|
99
|
+
## Tools
|
|
100
|
+
|
|
101
|
+
Every food and grocery tool takes `lat` / `long`: menus, prices and delivery fees depend on the delivery point.
|
|
102
|
+
Get them with `find_location` or `list_cities` first.
|
|
103
|
+
|
|
104
|
+
### Location
|
|
105
|
+
|
|
106
|
+
| Tool | What it does |
|
|
107
|
+
|---|---|
|
|
108
|
+
| `find_location` | Place name or address to coordinates |
|
|
109
|
+
| `reverse_geocode` | Coordinates to street / neighbourhood names |
|
|
110
|
+
| `list_cities` | Served cities with center coordinates |
|
|
111
|
+
|
|
112
|
+
### Snappfood (restaurants)
|
|
113
|
+
|
|
114
|
+
| Tool | What it does |
|
|
115
|
+
|---|---|
|
|
116
|
+
| `food_search` | Search dishes by name with price, discount and restaurant (one fast call) |
|
|
117
|
+
| `food_find_cheapest` | Scan nearby menus and FoodParty for the lowest total price (food + packaging + delivery) |
|
|
118
|
+
| `food_restaurants` | List restaurants with filters (free delivery, discount, coupon) and sorting |
|
|
119
|
+
| `food_menu` | One restaurant's full menu with prices, packaging fees and availability |
|
|
120
|
+
| `food_order_costs` | Delivery fee, ETA, minimum order and coupons of one restaurant |
|
|
121
|
+
| `food_reviews` | Customer reviews of a restaurant |
|
|
122
|
+
| `food_party_deals` | FoodParty flash deals still in stock, with the deal window |
|
|
123
|
+
| `food_meal_for_one` | Single-person meals (≤ 299k Toman, free delivery) |
|
|
124
|
+
| `food_discounted_vendors` | Restaurants running discounts now, plus live "Gem" deals |
|
|
125
|
+
|
|
126
|
+
### SnappMarket (groceries)
|
|
127
|
+
|
|
128
|
+
| Tool | What it does |
|
|
129
|
+
|---|---|
|
|
130
|
+
| `market_search` | Search a product across stores, grouped by store |
|
|
131
|
+
| `market_find_cheapest` | Cheapest in-stock offers for a product, one flat list |
|
|
132
|
+
| `market_stores` | Stores delivering to a point, by delivery fee or rating |
|
|
133
|
+
| `market_store_info` | Delivery fee, minimum order, opening hours and coupons of a store |
|
|
134
|
+
| `market_store_products` | Search a store, or browse it by category |
|
|
135
|
+
| `market_categories` | Product categories and their ids |
|
|
136
|
+
| `market_product` | One product's details and price in a store |
|
|
137
|
+
| `market_party_deals` | Market party flash deals, biggest discount first |
|
|
138
|
+
| `market_reviews` | Customer comments of a store |
|
|
139
|
+
|
|
140
|
+
All tools are annotated `readOnlyHint: true`. Results are compact JSON (structured content), so they do not use up the agent's context.
|
|
141
|
+
|
|
142
|
+
## Conventions
|
|
143
|
+
|
|
144
|
+
- Prices are in **Toman** (1 Toman = 10 Rial).
|
|
145
|
+
- Ratings are normalized to **0-5**, like the apps show. `null` means not rated yet.
|
|
146
|
+
- Persian queries match best: `پیتزا`, `کباب`, `شیر`.
|
|
147
|
+
- True cost of a food order: `price - discount + packaging + delivery fee - coupon`. The basket must also reach the restaurant's minimum order.
|
|
148
|
+
|
|
149
|
+
## Configuration
|
|
150
|
+
|
|
151
|
+
| Variable | Default | Meaning |
|
|
152
|
+
|---|---|---|
|
|
153
|
+
| `SNAPP_MCP_PROXY` | unset | HTTP proxy URL for all requests, e.g. `http://user:pass@host:port`. System proxy variables are ignored on purpose, because a foreign VPN exit gets blocked. |
|
|
154
|
+
|
|
155
|
+
## Troubleshooting
|
|
156
|
+
|
|
157
|
+
- **"blocked the request (HTTP 403)"**: your IP is outside Iran. Turn off the VPN, or set `SNAPP_MCP_PROXY` to a proxy in Iran.
|
|
158
|
+
- **`uvx` not found in Claude Desktop**: use the full path to `uvx` as `command`.
|
|
159
|
+
- **Empty FoodParty / Gem results**: these deals only run in time windows. `active: false` means no window is live.
|
|
160
|
+
- Debug with the MCP Inspector: `npx @modelcontextprotocol/inspector uvx snapp-mcp`.
|
|
161
|
+
|
|
162
|
+
## Development
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
git clone https://github.com/sepehr071/snapp-mcp && cd snapp-mcp
|
|
166
|
+
uv sync
|
|
167
|
+
uv run pytest # offline tests against recorded responses
|
|
168
|
+
uv run pytest -m live # hits the real APIs (needs an Iranian IP)
|
|
169
|
+
uv run ruff check .
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Releases: bump the version in `pyproject.toml` and `server.json`, then push a `v*` tag.
|
|
173
|
+
GitHub Actions publishes to PyPI (trusted publishing) and to the [MCP Registry](https://registry.modelcontextprotocol.io).
|
|
174
|
+
|
|
175
|
+
## License
|
|
176
|
+
|
|
177
|
+
MIT
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# snapp-mcp
|
|
2
|
+
|
|
3
|
+
<!-- mcp-name: io.github.sepehr071/snapp-mcp -->
|
|
4
|
+
|
|
5
|
+
[](https://pypi.org/project/snapp-mcp/)
|
|
6
|
+
[](https://github.com/sepehr071/snapp-mcp/actions/workflows/ci.yml)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
|
|
9
|
+
An MCP server that lets AI agents use **Snappfood** (restaurant delivery) and **SnappMarket**
|
|
10
|
+
(grocery delivery) in Iran. Agents can search dishes and groceries, compare prices across
|
|
11
|
+
restaurants and stores, read menus and reviews, and find live deals.
|
|
12
|
+
|
|
13
|
+
It is **read-only**: it cannot log in, add to a basket or place an order.
|
|
14
|
+
|
|
15
|
+
> Unofficial. Not affiliated with or endorsed by Snapp. It uses the same public endpoints as
|
|
16
|
+
> the snappfood.ir and snapp.market web apps, which can change without notice.
|
|
17
|
+
|
|
18
|
+
## Example prompts
|
|
19
|
+
|
|
20
|
+
- "Cheapest pizza delivered to Vanak Square right now, including delivery fee."
|
|
21
|
+
- "Which restaurants near me in Shiraz have free delivery and a rating above 4?"
|
|
22
|
+
- "Show today's FoodParty deals with more than 40% off."
|
|
23
|
+
- "Where can I buy low-fat milk cheapest near Jordan, Tehran?"
|
|
24
|
+
- "Is restaurant 947evd's minimum order above 200,000 Toman? Any coupons?"
|
|
25
|
+
|
|
26
|
+
## Requirements
|
|
27
|
+
|
|
28
|
+
- [uv](https://docs.astral.sh/uv/getting-started/installation/) (provides `uvx`), or Python 3.10+ with pip.
|
|
29
|
+
- **An Iranian IP address.** Snappfood's firewall rejects most foreign IPs (HTTP 403). Run the server on
|
|
30
|
+
a machine in Iran with VPN off, or point `SNAPP_MCP_PROXY` at a proxy in Iran. SnappMarket is less strict.
|
|
31
|
+
|
|
32
|
+
## Install
|
|
33
|
+
|
|
34
|
+
### Claude Code
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
claude mcp add snapp -- uvx snapp-mcp
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### Claude Desktop
|
|
41
|
+
|
|
42
|
+
Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
|
|
43
|
+
|
|
44
|
+
```json
|
|
45
|
+
{
|
|
46
|
+
"mcpServers": {
|
|
47
|
+
"snapp": {
|
|
48
|
+
"command": "uvx",
|
|
49
|
+
"args": ["snapp-mcp"]
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Cursor
|
|
56
|
+
|
|
57
|
+
Add the same block to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project).
|
|
58
|
+
|
|
59
|
+
### VS Code (Copilot agent mode)
|
|
60
|
+
|
|
61
|
+
Add to `.vscode/mcp.json`:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"servers": {
|
|
66
|
+
"snapp": {
|
|
67
|
+
"type": "stdio",
|
|
68
|
+
"command": "uvx",
|
|
69
|
+
"args": ["snapp-mcp"]
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Any other MCP client
|
|
76
|
+
|
|
77
|
+
Run `uvx snapp-mcp` (or `pip install snapp-mcp` then `snapp-mcp`) as a stdio server.
|
|
78
|
+
|
|
79
|
+
## Tools
|
|
80
|
+
|
|
81
|
+
Every food and grocery tool takes `lat` / `long`: menus, prices and delivery fees depend on the delivery point.
|
|
82
|
+
Get them with `find_location` or `list_cities` first.
|
|
83
|
+
|
|
84
|
+
### Location
|
|
85
|
+
|
|
86
|
+
| Tool | What it does |
|
|
87
|
+
|---|---|
|
|
88
|
+
| `find_location` | Place name or address to coordinates |
|
|
89
|
+
| `reverse_geocode` | Coordinates to street / neighbourhood names |
|
|
90
|
+
| `list_cities` | Served cities with center coordinates |
|
|
91
|
+
|
|
92
|
+
### Snappfood (restaurants)
|
|
93
|
+
|
|
94
|
+
| Tool | What it does |
|
|
95
|
+
|---|---|
|
|
96
|
+
| `food_search` | Search dishes by name with price, discount and restaurant (one fast call) |
|
|
97
|
+
| `food_find_cheapest` | Scan nearby menus and FoodParty for the lowest total price (food + packaging + delivery) |
|
|
98
|
+
| `food_restaurants` | List restaurants with filters (free delivery, discount, coupon) and sorting |
|
|
99
|
+
| `food_menu` | One restaurant's full menu with prices, packaging fees and availability |
|
|
100
|
+
| `food_order_costs` | Delivery fee, ETA, minimum order and coupons of one restaurant |
|
|
101
|
+
| `food_reviews` | Customer reviews of a restaurant |
|
|
102
|
+
| `food_party_deals` | FoodParty flash deals still in stock, with the deal window |
|
|
103
|
+
| `food_meal_for_one` | Single-person meals (≤ 299k Toman, free delivery) |
|
|
104
|
+
| `food_discounted_vendors` | Restaurants running discounts now, plus live "Gem" deals |
|
|
105
|
+
|
|
106
|
+
### SnappMarket (groceries)
|
|
107
|
+
|
|
108
|
+
| Tool | What it does |
|
|
109
|
+
|---|---|
|
|
110
|
+
| `market_search` | Search a product across stores, grouped by store |
|
|
111
|
+
| `market_find_cheapest` | Cheapest in-stock offers for a product, one flat list |
|
|
112
|
+
| `market_stores` | Stores delivering to a point, by delivery fee or rating |
|
|
113
|
+
| `market_store_info` | Delivery fee, minimum order, opening hours and coupons of a store |
|
|
114
|
+
| `market_store_products` | Search a store, or browse it by category |
|
|
115
|
+
| `market_categories` | Product categories and their ids |
|
|
116
|
+
| `market_product` | One product's details and price in a store |
|
|
117
|
+
| `market_party_deals` | Market party flash deals, biggest discount first |
|
|
118
|
+
| `market_reviews` | Customer comments of a store |
|
|
119
|
+
|
|
120
|
+
All tools are annotated `readOnlyHint: true`. Results are compact JSON (structured content), so they do not use up the agent's context.
|
|
121
|
+
|
|
122
|
+
## Conventions
|
|
123
|
+
|
|
124
|
+
- Prices are in **Toman** (1 Toman = 10 Rial).
|
|
125
|
+
- Ratings are normalized to **0-5**, like the apps show. `null` means not rated yet.
|
|
126
|
+
- Persian queries match best: `پیتزا`, `کباب`, `شیر`.
|
|
127
|
+
- True cost of a food order: `price - discount + packaging + delivery fee - coupon`. The basket must also reach the restaurant's minimum order.
|
|
128
|
+
|
|
129
|
+
## Configuration
|
|
130
|
+
|
|
131
|
+
| Variable | Default | Meaning |
|
|
132
|
+
|---|---|---|
|
|
133
|
+
| `SNAPP_MCP_PROXY` | unset | HTTP proxy URL for all requests, e.g. `http://user:pass@host:port`. System proxy variables are ignored on purpose, because a foreign VPN exit gets blocked. |
|
|
134
|
+
|
|
135
|
+
## Troubleshooting
|
|
136
|
+
|
|
137
|
+
- **"blocked the request (HTTP 403)"**: your IP is outside Iran. Turn off the VPN, or set `SNAPP_MCP_PROXY` to a proxy in Iran.
|
|
138
|
+
- **`uvx` not found in Claude Desktop**: use the full path to `uvx` as `command`.
|
|
139
|
+
- **Empty FoodParty / Gem results**: these deals only run in time windows. `active: false` means no window is live.
|
|
140
|
+
- Debug with the MCP Inspector: `npx @modelcontextprotocol/inspector uvx snapp-mcp`.
|
|
141
|
+
|
|
142
|
+
## Development
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
git clone https://github.com/sepehr071/snapp-mcp && cd snapp-mcp
|
|
146
|
+
uv sync
|
|
147
|
+
uv run pytest # offline tests against recorded responses
|
|
148
|
+
uv run pytest -m live # hits the real APIs (needs an Iranian IP)
|
|
149
|
+
uv run ruff check .
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Releases: bump the version in `pyproject.toml` and `server.json`, then push a `v*` tag.
|
|
153
|
+
GitHub Actions publishes to PyPI (trusted publishing) and to the [MCP Registry](https://registry.modelcontextprotocol.io).
|
|
154
|
+
|
|
155
|
+
## License
|
|
156
|
+
|
|
157
|
+
MIT
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "snapp-mcp"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Unofficial read-only MCP server for Snappfood and SnappMarket: search food and groceries, compare prices, find deals."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
authors = [{ name = "Sepehr", email = "sepehr@nextofx.com" }]
|
|
9
|
+
requires-python = ">=3.10"
|
|
10
|
+
keywords = ["mcp", "model-context-protocol", "snappfood", "snappmarket", "iran", "food-delivery", "grocery"]
|
|
11
|
+
classifiers = [
|
|
12
|
+
"Development Status :: 4 - Beta",
|
|
13
|
+
"Intended Audience :: Developers",
|
|
14
|
+
"Operating System :: OS Independent",
|
|
15
|
+
"Programming Language :: Python :: 3",
|
|
16
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
17
|
+
]
|
|
18
|
+
dependencies = [
|
|
19
|
+
"mcp>=2.2,<3",
|
|
20
|
+
"httpx>=0.27",
|
|
21
|
+
]
|
|
22
|
+
|
|
23
|
+
[project.urls]
|
|
24
|
+
Homepage = "https://github.com/sepehr071/snapp-mcp"
|
|
25
|
+
Issues = "https://github.com/sepehr071/snapp-mcp/issues"
|
|
26
|
+
|
|
27
|
+
[project.scripts]
|
|
28
|
+
snapp-mcp = "snapp_mcp.server:main"
|
|
29
|
+
|
|
30
|
+
[dependency-groups]
|
|
31
|
+
dev = ["pytest>=8", "ruff>=0.6"]
|
|
32
|
+
|
|
33
|
+
[build-system]
|
|
34
|
+
requires = ["hatchling"]
|
|
35
|
+
build-backend = "hatchling.build"
|
|
36
|
+
|
|
37
|
+
[tool.pytest.ini_options]
|
|
38
|
+
testpaths = ["tests"]
|
|
39
|
+
addopts = "-m 'not live'"
|
|
40
|
+
markers = ["live: calls the real Snappfood/SnappMarket APIs (run with -m live)"]
|
|
41
|
+
|
|
42
|
+
[tool.ruff]
|
|
43
|
+
line-length = 120
|
|
44
|
+
target-version = "py310"
|
|
45
|
+
|
|
46
|
+
[tool.ruff.lint]
|
|
47
|
+
select = ["E", "F", "I", "B", "UP"]
|
|
48
|
+
ignore = ["E501"] # long Field(description=...) strings read better on one line
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
|
+
"name": "io.github.sepehr071/snapp-mcp",
|
|
4
|
+
"title": "Snappfood & SnappMarket",
|
|
5
|
+
"description": "Unofficial read-only Snappfood & SnappMarket: search food and groceries, compare prices, deals.",
|
|
6
|
+
"repository": {
|
|
7
|
+
"url": "https://github.com/sepehr071/snapp-mcp",
|
|
8
|
+
"source": "github"
|
|
9
|
+
},
|
|
10
|
+
"websiteUrl": "https://github.com/sepehr071/snapp-mcp",
|
|
11
|
+
"version": "0.1.0",
|
|
12
|
+
"packages": [
|
|
13
|
+
{
|
|
14
|
+
"registryType": "pypi",
|
|
15
|
+
"registryBaseUrl": "https://pypi.org",
|
|
16
|
+
"identifier": "snapp-mcp",
|
|
17
|
+
"version": "0.1.0",
|
|
18
|
+
"runtimeHint": "uvx",
|
|
19
|
+
"transport": {
|
|
20
|
+
"type": "stdio"
|
|
21
|
+
},
|
|
22
|
+
"environmentVariables": [
|
|
23
|
+
{
|
|
24
|
+
"name": "SNAPP_MCP_PROXY",
|
|
25
|
+
"description": "Optional HTTP proxy URL. Snappfood only accepts Iranian IP addresses; system proxy settings are ignored.",
|
|
26
|
+
"isRequired": false,
|
|
27
|
+
"isSecret": false
|
|
28
|
+
}
|
|
29
|
+
]
|
|
30
|
+
}
|
|
31
|
+
]
|
|
32
|
+
}
|