io.github.mohammad-abbasi-sh/bonbama-mcp
# bonbama-mcp 🇮🇷
mcp-name: io.github.mohammad-abbasi-sh/bonbama-mcp
Unofficial **read-only** MCP server for [bonbama.ir](https://bonbama.ir) — Gorgan's discount platform: local businesses, discount codes and campaigns, business categories, and magazine articles. All data is read **live** from bonbama.ir public pages at call time — nothing is hardcoded.
> Not affiliated with Bonbama. Built for the Bazaar MCP Hub submission — see [DEPLOY.md](DEPLOY.md) for hosting.
## For AI agents
**Local (stdio)** — add to your MCP client config:
```json
{
"mcpServers": {
"bonbama": {
"command": "uvx",
"args": ["bonbama-mcp"]
}
}
}
```
Or run locally: `python -m bonbama_mcp.server` (needs `mcp<2`, `httpx`, `uvicorn`).
**Hosted (streamable HTTP)** — for clients that connect to a remote MCP server:
```
https://api.bonbama.ir/mcp
```
MCP endpoint is `/mcp` (streamable HTTP, stateless — no session affinity needed); liveness probe at `/health`. Hosting guide: [DEPLOY.md](DEPLOY.md).
## Tools
| Tool | Description |
|------|-------------|
| `bb_search_businesses` | Search businesses by keyword and/or category slug — `query`, `category`, `limit` |
| `bb_get_business` | Full details for one business — `slug` (e.g. `testino`, `takchh`): description, city, address, rating, category, ACTIVE campaigns with discount + expiry, and any literal discount codes published on the page |
| `bb_list_categories` | All business categories with Persian names + business/campaign counts |
| `bb_search_discounts` | Search ACTIVE discount campaigns site-wide — `query` (empty = popular campaigns) |
| `bb_search_articles` | Search the Bonbama magazine (guides, best-of-Gorgan lists) — `query` |
| `bb_health` | Check whether bonbama.ir is reachable right now |
Example output (`bb_get_business` / `takchh`, trimmed):
```json
{"name": "طاقچه | خرید کتاب الکترونیکی و صوتی و اشتراک بینهایت",
"city": "تهران", "campaign_count": 5,
"campaigns": [{"title": "۵۰٪ تخفیف اولین خرید طاقچه — فقط از طریق بنباما",
"discount": "50%", "valid_through": "2027-01-20"}],
"codes": [{"code": "OFF50", "note": "۵۰٪ تخفیف اولین خرید"}]}
```
Notes:
- Campaigns, codes, prices and expiries are read live from the page on every call — they change; always report `fetched_at` and tell the user to verify on the business page before buying.
- Literal codes (e.g. `OFF50`) come from the business page's own text. Some campaigns instead need the user to press «دریافت کد» on bonbama.ir (free, needs a free account) to generate their personal code/QR — those codes are per-user and are never returned here.
- Data sources: bonbama.ir sitemaps + public search, business, category and article pages — no key, no login, read-only. This server never writes anything to bonbama.ir.
## Development
```bash
python -m venv .venv && .venv/bin/pip install -e . pytest
.venv/bin/python -m pytest tests/ -q # 29 offline + 7 live tests
.venv/bin/python -m pytest tests/test_bonbama.py -q # offline only
```
## Cite this project
If you use bonbama-mcp, build on it, or write about it, please credit the source:
> Abbasi, Mohammad. *bonbama-mcp*. v0.1.0, 2026. https://github.com/mohammad-abbasi-sh/bonbama-mcp
A ready-to-copy citation is also available from GitHub's **Cite this repository** button (see `CITATION.cff`). Commercial use needs a separate license (see below).
## License
[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/) — free for personal and non-commercial use; commercial use needs a separate license.
Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)
TDQS
Scored across 6 tools
Each tool targets a distinct entity and action: business search vs. single-business detail vs. category listing vs. discount search vs. article search vs. health probe. The inclusion of the category-listing tool explicitly feeding the search tool's category parameter further separates the roles. No two tools could be reasonably confused for one another.
A consistent bb_ prefix plus verb_noun pattern (search_businesses, get_business, list_categories, search_discounts, search_articles) is applied throughout. The only deviation is bb_health, a bare noun rather than a verb_noun form, but it is still predictable and readable.
Six tools is a tight, well-scoped surface for a site-search server covering two content types (businesses, discounts) plus articles and categories. Every tool earns its place, with no redundant or filler operations.
The lifecycle is largely covered: discover categories, search businesses, fetch business detail (including its campaigns), search discounts, search articles, and verify reachability. Minor gaps exist — there is no direct single-campaign or single-article fetch, and no explicit city filter — but campaign and article data surface through the search and detail responses, so agents can work around it.