Skip to main content
Glama
io.github.mohammad-abbasi-sh/bonbama-mcp

io.github.mohammad-abbasi-sh/bonbama-mcp

README.md
# 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

A4.1/5.0

Scored across 6 tools

Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues