bonbama-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.
Files changed (31) hide show
  1. bonbama_mcp-0.1.0/.dockerignore +9 -0
  2. bonbama_mcp-0.1.0/.github/workflows/publish.yml +20 -0
  3. bonbama_mcp-0.1.0/.github/workflows/registry.yml +95 -0
  4. bonbama_mcp-0.1.0/.github/workflows/smoke.yml +21 -0
  5. bonbama_mcp-0.1.0/.gitignore +8 -0
  6. bonbama_mcp-0.1.0/DEPLOY.md +123 -0
  7. bonbama_mcp-0.1.0/Dockerfile +18 -0
  8. bonbama_mcp-0.1.0/LICENSE +79 -0
  9. bonbama_mcp-0.1.0/PKG-INFO +85 -0
  10. bonbama_mcp-0.1.0/README-fa.md +59 -0
  11. bonbama_mcp-0.1.0/README.md +72 -0
  12. bonbama_mcp-0.1.0/pyproject.toml +23 -0
  13. bonbama_mcp-0.1.0/server.json +1 -0
  14. bonbama_mcp-0.1.0/src/bonbama_mcp/__init__.py +2 -0
  15. bonbama_mcp-0.1.0/src/bonbama_mcp/bonbama.py +476 -0
  16. bonbama_mcp-0.1.0/src/bonbama_mcp/http.py +143 -0
  17. bonbama_mcp-0.1.0/src/bonbama_mcp/server.py +317 -0
  18. bonbama_mcp-0.1.0/tests/__init__.py +0 -0
  19. bonbama_mcp-0.1.0/tests/fixtures/articles-index.html +106 -0
  20. bonbama_mcp-0.1.0/tests/fixtures/business-takchh.html +47 -0
  21. bonbama_mcp-0.1.0/tests/fixtures/business-testino.html +1 -0
  22. bonbama_mcp-0.1.0/tests/fixtures/category-zban.html +254 -0
  23. bonbama_mcp-0.1.0/tests/fixtures/home-categories.html +968 -0
  24. bonbama_mcp-0.1.0/tests/fixtures/search-campaigns.html +549 -0
  25. bonbama_mcp-0.1.0/tests/fixtures/search-companies.html +94 -0
  26. bonbama_mcp-0.1.0/tests/fixtures/sitemap-articles.xml +51 -0
  27. bonbama_mcp-0.1.0/tests/fixtures/sitemap-categories.xml +151 -0
  28. bonbama_mcp-0.1.0/tests/fixtures/sitemap-companies.xml +51 -0
  29. bonbama_mcp-0.1.0/tests/smoke_live.py +17 -0
  30. bonbama_mcp-0.1.0/tests/test_bonbama.py +210 -0
  31. bonbama_mcp-0.1.0/tests/test_live.py +75 -0
@@ -0,0 +1,9 @@
1
+ .git
2
+ .github
3
+ tests
4
+ .venv
5
+ __pycache__
6
+ .pytest_cache
7
+ Dockerfile
8
+ .dockerignore
9
+ DEPLOY.md
@@ -0,0 +1,20 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+
7
+ jobs:
8
+ publish:
9
+ runs-on: ubuntu-latest
10
+ permissions:
11
+ id-token: write # required for PyPI trusted publishing (OIDC)
12
+ contents: read
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+ - uses: actions/setup-python@v5
16
+ with:
17
+ python-version: "3.12"
18
+ - run: pip install build
19
+ - run: python -m build
20
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,95 @@
1
+ name: Publish to MCP Registry
2
+
3
+ # Official MCP Registry (registry.modelcontextprotocol.io) via GitHub OIDC.
4
+ # No secret, no interactive login: the runner's OIDC token proves ownership
5
+ # of the io.github.mohammad-abbasi-sh/* namespace.
6
+ # Refs: https://github.com/modelcontextprotocol/registry
7
+
8
+ on:
9
+ push:
10
+ tags: ["v*"]
11
+ workflow_dispatch:
12
+
13
+ jobs:
14
+ publish:
15
+ runs-on: ubuntu-latest
16
+ permissions:
17
+ id-token: write # required for OIDC -> MCP Registry
18
+ contents: read
19
+ steps:
20
+ - uses: actions/checkout@v4
21
+
22
+ - name: Sync server.json version to tag
23
+ # Only sync when running on a version tag (v*). On workflow_dispatch
24
+ # (ref = refs/heads/main) keep the version committed in server.json.
25
+ run: |
26
+ VER=""
27
+ if [[ "$GITHUB_REF" == refs/tags/* ]]; then
28
+ TAG="${GITHUB_REF#refs/tags/}"
29
+ VER="${TAG#v}"
30
+ fi
31
+ if [ -n "$VER" ]; then
32
+ python3 - "$VER" << 'EOF'
33
+ import json, sys
34
+ ver = sys.argv[1]
35
+ d = json.load(open('server.json'))
36
+ d['version'] = ver
37
+ for pkg in d.get('packages', []):
38
+ pkg['version'] = ver
39
+ json.dump(d, open('server.json', 'w'), indent=2, ensure_ascii=False)
40
+ print('server.json version ->', ver)
41
+ EOF
42
+ else
43
+ echo "No version tag ($GITHUB_REF); keeping server.json version as-is"
44
+ fi
45
+
46
+ - name: Wait for PyPI
47
+ # The registry validates that the PyPI package + version exists,
48
+ # but the PyPI publish workflow runs in parallel with this one.
49
+ # Poll until the version appears instead of racing it: a 400 here
50
+ # used to fail silently under continue-on-error and left 40/43
51
+ # servers unlisted in the registry (2026-11-11).
52
+ run: |
53
+ python3 - << 'EOF'
54
+ import json, sys, time, urllib.request, urllib.error
55
+ d = json.load(open('server.json'))
56
+ pkg = d['packages'][0]
57
+ name = pkg.get('identifier') or pkg.get('name')
58
+ ver = pkg['version']
59
+ if not name:
60
+ print('ERROR: no package identifier/name in server.json')
61
+ sys.exit(1)
62
+ url = f'https://pypi.org/pypi/{name}/json'
63
+ for attempt in range(1, 21):
64
+ try:
65
+ with urllib.request.urlopen(url, timeout=30) as r:
66
+ data = json.load(r)
67
+ if ver in data.get('releases', {}):
68
+ print(f'PyPI {name}=={ver} is live (attempt {attempt})')
69
+ sys.exit(0)
70
+ except urllib.error.HTTPError as e:
71
+ print(f'attempt {attempt}: PyPI returned {e.code}')
72
+ except Exception as e:
73
+ print(f'attempt {attempt}: {e}')
74
+ print(f'attempt {attempt}: {name}=={ver} not on PyPI yet, waiting 30s...')
75
+ time.sleep(30)
76
+ print(f'ERROR: {name}=={ver} did not appear on PyPI after 10 minutes')
77
+ sys.exit(1)
78
+ EOF
79
+
80
+ - name: Install mcp-publisher
81
+ run: |
82
+ curl -sL "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.7/mcp-publisher_linux_amd64.tar.gz" -o /tmp/mcp-publisher.tar.gz
83
+ tar -xzf /tmp/mcp-publisher.tar.gz -C /tmp
84
+ sudo mv /tmp/mcp-publisher /usr/local/bin/mcp-publisher
85
+ mcp-publisher --version
86
+
87
+ - name: Validate server.json
88
+ run: mcp-publisher validate server.json
89
+
90
+ - name: Publish to MCP Registry (OIDC)
91
+ # Failures must fail the run visibly: a silent publish failure
92
+ # once left 40/43 servers unlisted in the registry (2026-11-11).
93
+ run: |
94
+ mcp-publisher login github-oidc
95
+ mcp-publisher publish server.json
@@ -0,0 +1,21 @@
1
+ name: Daily live smoke
2
+
3
+ # One fixed probe per day: catches fingerprint rot / bot-wall changes
4
+ # before users hit them. Fails visibly on 403/timeout.
5
+ on:
6
+ schedule:
7
+ - cron: "0 6 * * *"
8
+ workflow_dispatch:
9
+
10
+ jobs:
11
+ smoke:
12
+ runs-on: ubuntu-latest
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+ - uses: actions/setup-python@v5
16
+ with:
17
+ python-version: "3.12"
18
+ - name: Install
19
+ run: pip install -e .
20
+ - name: Smoke probe
21
+ run: python tests/smoke_live.py
@@ -0,0 +1,8 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ venv/
5
+ .pytest_cache/
6
+ *.egg-info/
7
+ dist/
8
+ build/
@@ -0,0 +1,123 @@
1
+ # DEPLOY.md — hosting bonbama-mcp (for Bonbama's dev team / Bazaar MCP Hub)
2
+
3
+ Bazaar's MCP Hub connects to a **hosted** MCP URL. This server speaks MCP
4
+ streamable HTTP at `/mcp`, so it can be deployed at e.g.
5
+ `https://api.bonbama.ir/mcp` and submitted to Bazaar with that URL.
6
+
7
+ - **MCP endpoint:** `POST /mcp` (MCP streamable HTTP, JSON-RPC over SSE)
8
+ - **Liveness probe:** `GET /health` → `{"status": "ok", "server": "bonbama-mcp", ...}`
9
+ (plain liveness — it does NOT call bonbama.ir; use it for load-balancer /
10
+ Docker health checks. The live bonbama.ir probe is the `bb_health` tool.)
11
+ - **State:** none. Stateless HTTP (`stateless_http=True`) — no sessions, no
12
+ database, no disk writes. Any number of replicas behind any reverse proxy.
13
+ - **Auth:** none on the endpoint itself for v1 — the data is public,
14
+ read-only bonbama.ir content. Bazaar connects with its own token on
15
+ Bazaar's side; if Bonbama later wants an API key on this endpoint, add it
16
+ in the reverse proxy (see below), not in this code.
17
+ - **Resources:** tiny — one uvicorn worker, ~100MB RAM. It only fetches
18
+ bonbama.ir pages on demand (a few hundred KB per tool call, 30s timeout).
19
+
20
+ ## Option A — Docker (recommended)
21
+
22
+ ```bash
23
+ docker build -t bonbama-mcp .
24
+ docker run -d --name bonbama-mcp -p 8000:8000 --restart unless-stopped bonbama-mcp
25
+ curl http://localhost:8000/health # {"status": "ok", ...}
26
+ ```
27
+
28
+ The image runs `uvicorn bonbama_mcp.server:app --host 0.0.0.0 --port 8000`
29
+ as a non-root user, with a Docker `HEALTHCHECK` on `/health`.
30
+
31
+ ## Option B — bare metal / systemd
32
+
33
+ ```bash
34
+ python3.12 -m venv /opt/bonbama-mcp/.venv
35
+ /opt/bonbama-mcp/.venv/bin/pip install bonbama-mcp # from PyPI, or pip install .
36
+ ```
37
+
38
+ `/etc/systemd/system/bonbama-mcp.service`:
39
+
40
+ ```ini
41
+ [Unit]
42
+ Description=bonbama-mcp (MCP streamable HTTP for bonbama.ir)
43
+ After=network.target
44
+
45
+ [Service]
46
+ Type=simple
47
+ User=www-data
48
+ WorkingDirectory=/opt/bonbama-mcp
49
+ Environment=BONBAMA_MCP_HOST=127.0.0.1
50
+ Environment=BONBAMA_MCP_PORT=8000
51
+ ExecStart=/opt/bonbama-mcp/.venv/bin/bonbama-mcp --transport streamable-http
52
+ Restart=on-failure
53
+ RestartSec=5
54
+
55
+ [Install]
56
+ WantedBy=multi-user.target
57
+ ```
58
+
59
+ ```bash
60
+ systemctl daemon-reload && systemctl enable --now bonbama-mcp
61
+ ```
62
+
63
+ ## Environment variables
64
+
65
+ | Variable | Default | Meaning |
66
+ |----------|---------|---------|
67
+ | `BONBAMA_MCP_HOST` | `127.0.0.1` | Bind host for streamable HTTP |
68
+ | `BONBAMA_MCP_PORT` | `8000` | Bind port for streamable HTTP |
69
+
70
+ CLI flags override env vars: `bonbama-mcp --transport streamable-http --host 0.0.0.0 --port 8000`.
71
+ Plain `bonbama-mcp` with no flags runs stdio (local uvx use) — same tools.
72
+
73
+ ## Reverse proxy (nginx + TLS)
74
+
75
+ ```nginx
76
+ server {
77
+ listen 443 ssl;
78
+ server_name api.bonbama.ir;
79
+ # ssl_certificate / ssl_certificate_key here
80
+
81
+ location /mcp {
82
+ proxy_pass http://127.0.0.1:8000;
83
+ proxy_http_version 1.1;
84
+ proxy_set_header Host $host;
85
+ proxy_set_header X-Real-IP $remote_addr;
86
+ proxy_read_timeout 120s; # MCP uses long-lived SSE responses
87
+ proxy_buffering off; # do not buffer the event stream
88
+ }
89
+ location /health {
90
+ proxy_pass http://127.0.0.1:8000;
91
+ }
92
+ }
93
+ ```
94
+
95
+ Notes:
96
+ - **Do not buffer SSE** (`proxy_buffering off`) and allow long reads — MCP
97
+ streamable HTTP holds the response open while the tool runs.
98
+ - Optional API key (if Bonbama wants one later): enforce it in nginx
99
+ (`auth_request` or a simple `if ($http_authorization != "Bearer …")`),
100
+ not in this server.
101
+ - Optional rate limiting: a few requests/second per IP is plenty — each
102
+ tool call is 1–5 fetches of bonbama.ir pages.
103
+
104
+ ## Verify after deploy
105
+
106
+ ```bash
107
+ curl https://api.bonbama.ir/health
108
+ # {"status":"ok","server":"bonbama-mcp","transport":"streamable-http","mcp_path":"/mcp"}
109
+
110
+ curl -X POST https://api.bonbama.ir/mcp \
111
+ -H "Content-Type: application/json" \
112
+ -H "Accept: application/json, text/event-stream" \
113
+ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0.1"}}}'
114
+ # 200 + SSE "event: message" with serverInfo.name = "bonbama-mcp"
115
+ ```
116
+
117
+ Then submit `https://api.bonbama.ir/mcp` in Bazaar's form
118
+ ("آدرس سرور MCP").
119
+
120
+ ## Updating
121
+
122
+ New version = rebuild the image (or `pip install --upgrade bonbama-mcp`)
123
+ and restart. No migrations, no state to preserve.
@@ -0,0 +1,18 @@
1
+ FROM python:3.12-slim
2
+
3
+ WORKDIR /app
4
+
5
+ COPY pyproject.toml README.md LICENSE ./
6
+ COPY src ./src
7
+ RUN pip install --no-cache-dir . \
8
+ && useradd -m app \
9
+ && chown -R app:app /app
10
+
11
+ USER app
12
+
13
+ EXPOSE 8000
14
+
15
+ HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
16
+ CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')"
17
+
18
+ CMD ["uvicorn", "bonbama_mcp.server:app", "--host", "0.0.0.0", "--port", "8000"]
@@ -0,0 +1,79 @@
1
+ Required Notice: Copyright (c) 2026 Mohammad Abbasi (https://github.com/mohammad-abbasi-sh)
2
+
3
+ Free for personal and non-commercial use under the terms below. Commercial use needs a separate license: contact Mohammad Abbasi at https://www.linkedin.com/in/mohammad-abbasi-sh or https://github.com/mohammad-abbasi-sh.
4
+
5
+ Versions released before this license change were published under the MIT license and stay under it.
6
+
7
+ # PolyForm Noncommercial License 1.0.0
8
+
9
+ <https://polyformproject.org/licenses/noncommercial/1.0.0>
10
+
11
+ ## Acceptance
12
+
13
+ In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
14
+
15
+ ## Copyright License
16
+
17
+ The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
18
+
19
+ ## Distribution License
20
+
21
+ The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
22
+
23
+ ## Notices
24
+
25
+ You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
26
+
27
+ > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
28
+
29
+ ## Changes and New Works License
30
+
31
+ The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
32
+
33
+ ## Patent License
34
+
35
+ The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
36
+
37
+ ## Noncommercial Purposes
38
+
39
+ Any noncommercial purpose is a permitted purpose.
40
+
41
+ ## Personal Uses
42
+
43
+ Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
44
+
45
+ ## Noncommercial Organizations
46
+
47
+ Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
48
+
49
+ ## Fair Use
50
+
51
+ You may have "fair use" rights for the software under the law. These terms do not limit them.
52
+
53
+ ## No Other Rights
54
+
55
+ These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
56
+
57
+ ## Patent Defense
58
+
59
+ If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
60
+
61
+ ## Violations
62
+
63
+ The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
64
+
65
+ ## No Liability
66
+
67
+ ***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
68
+
69
+ ## Definitions
70
+
71
+ The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
72
+
73
+ **You** refers to the individual or entity agreeing to these terms.
74
+
75
+ **Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
76
+
77
+ **Your licenses** are all the licenses granted to you for the software under these terms.
78
+
79
+ **Use** means anything you do with the software requiring one of your licenses.
@@ -0,0 +1,85 @@
1
+ Metadata-Version: 2.5
2
+ Name: bonbama-mcp
3
+ Version: 0.1.0
4
+ Summary: Unofficial read-only MCP server for bonbama.ir — Gorgan discounts, businesses and codes
5
+ Author: Mohammad Abbasi
6
+ License: PolyForm-Noncommercial-1.0.0
7
+ License-File: LICENSE
8
+ Requires-Python: >=3.10
9
+ Requires-Dist: httpx>=0.27
10
+ Requires-Dist: mcp<2
11
+ Requires-Dist: uvicorn>=0.30
12
+ Description-Content-Type: text/markdown
13
+
14
+ # bonbama-mcp 🇮🇷
15
+
16
+ mcp-name: io.github.mohammad-abbasi-sh/bonbama-mcp
17
+
18
+ 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.
19
+
20
+ > Not affiliated with Bonbama. Built for the Bazaar MCP Hub submission — see [DEPLOY.md](DEPLOY.md) for hosting.
21
+
22
+ ## For AI agents
23
+
24
+ **Local (stdio)** — add to your MCP client config:
25
+
26
+ ```json
27
+ {
28
+ "mcpServers": {
29
+ "bonbama": {
30
+ "command": "uvx",
31
+ "args": ["bonbama-mcp"]
32
+ }
33
+ }
34
+ }
35
+ ```
36
+
37
+ Or run locally: `python -m bonbama_mcp.server` (needs `mcp<2`, `httpx`, `uvicorn`).
38
+
39
+ **Hosted (streamable HTTP)** — for clients that connect to a remote MCP server:
40
+
41
+ ```
42
+ https://api.bonbama.ir/mcp
43
+ ```
44
+
45
+ MCP endpoint is `/mcp` (streamable HTTP, stateless — no session affinity needed); liveness probe at `/health`. Hosting guide: [DEPLOY.md](DEPLOY.md).
46
+
47
+ ## Tools
48
+
49
+ | Tool | Description |
50
+ |------|-------------|
51
+ | `bb_search_businesses` | Search businesses by keyword and/or category slug — `query`, `category`, `limit` |
52
+ | `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 |
53
+ | `bb_list_categories` | All business categories with Persian names + business/campaign counts |
54
+ | `bb_search_discounts` | Search ACTIVE discount campaigns site-wide — `query` (empty = popular campaigns) |
55
+ | `bb_search_articles` | Search the Bonbama magazine (guides, best-of-Gorgan lists) — `query` |
56
+ | `bb_health` | Check whether bonbama.ir is reachable right now |
57
+
58
+ Example output (`bb_get_business` / `takchh`, trimmed):
59
+
60
+ ```json
61
+ {"name": "طاقچه | خرید کتاب الکترونیکی و صوتی و اشتراک بی‌نهایت",
62
+ "city": "تهران", "campaign_count": 5,
63
+ "campaigns": [{"title": "۵۰٪ تخفیف اولین خرید طاقچه — فقط از طریق بن‌باما",
64
+ "discount": "50%", "valid_through": "2027-01-20"}],
65
+ "codes": [{"code": "OFF50", "note": "۵۰٪ تخفیف اولین خرید"}]}
66
+ ```
67
+
68
+ Notes:
69
+ - 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.
70
+ - 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.
71
+ - 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.
72
+
73
+ ## Development
74
+
75
+ ```bash
76
+ python -m venv .venv && .venv/bin/pip install -e . pytest
77
+ .venv/bin/python -m pytest tests/ -q # 29 offline + 7 live tests
78
+ .venv/bin/python -m pytest tests/test_bonbama.py -q # offline only
79
+ ```
80
+
81
+ ## License
82
+
83
+ [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.
84
+
85
+ Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)
@@ -0,0 +1,59 @@
1
+ # bonbama-mcp 🇮🇷
2
+
3
+ سرور MCP **فقط‌خواندنی** و غیررسمی برای [بن‌باما](https://bonbama.ir) — پلتفرم تخفیف گرگان: کسب‌وکارها، کدها و کمپین‌های تخفیف، دسته‌بندی کسب‌وکارها و مقالات مجله. همهٔ داده‌ها **به‌صورت زنده** از صفحات عمومی بن‌باما خوانده می‌شوند — هیچ چیزی هاردکد نشده است.
4
+
5
+ > وابسته به بن‌باما نیست. ساخته‌شده برای ثبت در هاب MCP بازار — راهنمای میزبانی: [DEPLOY.md](DEPLOY.md)
6
+
7
+ ## برای ایجنت‌های هوش مصنوعی
8
+
9
+ **محلی (stdio)** — به کانفیگ MCP Client اضافه کنید:
10
+
11
+ ```json
12
+ {
13
+ "mcpServers": {
14
+ "bonbama": {
15
+ "command": "uvx",
16
+ "args": ["bonbama-mcp"]
17
+ }
18
+ }
19
+ }
20
+ ```
21
+
22
+ یا اجرای محلی: `python -m bonbama_mcp.server` (نیازمند `mcp<2`، `httpx`، `uvicorn`).
23
+
24
+ **میزبانی‌شده (streamable HTTP)** — برای کلاینت‌هایی که به سرور راه‌دور وصل می‌شوند:
25
+
26
+ ```
27
+ https://api.bonbama.ir/mcp
28
+ ```
29
+
30
+ اندپوینت MCP روی `/mcp` است (streamable HTTP، بدون state — نیازی به چسبندگی نشست نیست)؛ بررسی سلامت روی `/health`. راهنمای میزبانی: [DEPLOY.md](DEPLOY.md).
31
+
32
+ ## ابزارها
33
+
34
+ | ابزار | توضیح |
35
+ |------|-------|
36
+ | `bb_search_businesses` | جستجوی کسب‌وکارها با کلیدواژه و/یا دسته — `query`، `category`، `limit` |
37
+ | `bb_get_business` | جزئیات کامل یک کسب‌وکار — `slug` (مثل `testino`، `takchh`): توضیح، شهر، آدرس، امتیاز، دسته، کمپین‌های فعال با تخفیف و انقضا، و کدهای تخفیف منتشرشده در صفحه |
38
+ | `bb_list_categories` | همهٔ دسته‌های کسب‌وکار با نام فارسی و تعداد کسب‌وکار/کمپین |
39
+ | `bb_search_discounts` | جستجوی کمپین‌های تخفیف فعال در کل سایت — `query` (خالی = کمپین‌های محبوب) |
40
+ | `bb_search_articles` | جستجوی مجلهٔ بن‌باما (راهنماها، بهترین‌های گرگان) — `query` |
41
+ | `bb_health` | بررسی در دسترس بودن bonbama.ir در همین لحظه |
42
+
43
+ نکته‌ها:
44
+ - کمپین‌ها، کدها، قیمت‌ها و تاریخ‌های انقضا در هر فراخوانی زنده از صفحه خوانده می‌شوند و تغییر می‌کنند؛ همیشه `fetched_at` را گزارش کنید و به کاربر بگویید قبل از خرید در صفحهٔ کسب‌وکار بررسی کند.
45
+ - کدهای صریح (مثل `OFF50`) از متن خود صفحهٔ کسب‌وکار می‌آیند. بعضی کمپین‌ها نیاز دارند کاربر در بن‌باما دکمهٔ «دریافت کد» را بزند (رایگان، نیازمند حساب رایگان) تا کد/QR شخصی‌اش ساخته شود — آن کدها شخصی‌اند و اینجا هرگز برگردانده نمی‌شوند.
46
+ - منابع داده: سایت‌مپ‌ها + صفحات عمومی جستجو، کسب‌وکار، دسته و مقالهٔ بن‌باما — بدون کلید، بدون لاگین، فقط‌خواندنی. این سرور هیچ چیزی روی بن‌باما نمی‌نویسد.
47
+
48
+ ## توسعه
49
+
50
+ ```bash
51
+ python -m venv .venv && .venv/bin/pip install -e . # + pytest
52
+ .venv/bin/python -m pytest tests/ -q # ۲۹ تست آفلاین + ۷ تست زنده
53
+ ```
54
+
55
+ ## لایسنس
56
+
57
+ [PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/) — رایگان برای استفادهٔ شخصی و غیرتجاری؛ استفادهٔ تجاری نیازمند لایسنس جداگانه است.
58
+
59
+ ساختهٔ [محمد عباسی](https://github.com/mohammad-abbasi-sh) — [آلمانی‌باما](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)
@@ -0,0 +1,72 @@
1
+ # bonbama-mcp 🇮🇷
2
+
3
+ mcp-name: io.github.mohammad-abbasi-sh/bonbama-mcp
4
+
5
+ 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.
6
+
7
+ > Not affiliated with Bonbama. Built for the Bazaar MCP Hub submission — see [DEPLOY.md](DEPLOY.md) for hosting.
8
+
9
+ ## For AI agents
10
+
11
+ **Local (stdio)** — add to your MCP client config:
12
+
13
+ ```json
14
+ {
15
+ "mcpServers": {
16
+ "bonbama": {
17
+ "command": "uvx",
18
+ "args": ["bonbama-mcp"]
19
+ }
20
+ }
21
+ }
22
+ ```
23
+
24
+ Or run locally: `python -m bonbama_mcp.server` (needs `mcp<2`, `httpx`, `uvicorn`).
25
+
26
+ **Hosted (streamable HTTP)** — for clients that connect to a remote MCP server:
27
+
28
+ ```
29
+ https://api.bonbama.ir/mcp
30
+ ```
31
+
32
+ MCP endpoint is `/mcp` (streamable HTTP, stateless — no session affinity needed); liveness probe at `/health`. Hosting guide: [DEPLOY.md](DEPLOY.md).
33
+
34
+ ## Tools
35
+
36
+ | Tool | Description |
37
+ |------|-------------|
38
+ | `bb_search_businesses` | Search businesses by keyword and/or category slug — `query`, `category`, `limit` |
39
+ | `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 |
40
+ | `bb_list_categories` | All business categories with Persian names + business/campaign counts |
41
+ | `bb_search_discounts` | Search ACTIVE discount campaigns site-wide — `query` (empty = popular campaigns) |
42
+ | `bb_search_articles` | Search the Bonbama magazine (guides, best-of-Gorgan lists) — `query` |
43
+ | `bb_health` | Check whether bonbama.ir is reachable right now |
44
+
45
+ Example output (`bb_get_business` / `takchh`, trimmed):
46
+
47
+ ```json
48
+ {"name": "طاقچه | خرید کتاب الکترونیکی و صوتی و اشتراک بی‌نهایت",
49
+ "city": "تهران", "campaign_count": 5,
50
+ "campaigns": [{"title": "۵۰٪ تخفیف اولین خرید طاقچه — فقط از طریق بن‌باما",
51
+ "discount": "50%", "valid_through": "2027-01-20"}],
52
+ "codes": [{"code": "OFF50", "note": "۵۰٪ تخفیف اولین خرید"}]}
53
+ ```
54
+
55
+ Notes:
56
+ - 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.
57
+ - 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.
58
+ - 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.
59
+
60
+ ## Development
61
+
62
+ ```bash
63
+ python -m venv .venv && .venv/bin/pip install -e . pytest
64
+ .venv/bin/python -m pytest tests/ -q # 29 offline + 7 live tests
65
+ .venv/bin/python -m pytest tests/test_bonbama.py -q # offline only
66
+ ```
67
+
68
+ ## License
69
+
70
+ [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.
71
+
72
+ Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)
@@ -0,0 +1,23 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "bonbama-mcp"
7
+ version = "0.1.0"
8
+ description = "Unofficial read-only MCP server for bonbama.ir — Gorgan discounts, businesses and codes"
9
+ readme = "README.md"
10
+ license = { text = "PolyForm-Noncommercial-1.0.0" }
11
+ requires-python = ">=3.10"
12
+ dependencies = [
13
+ "mcp<2",
14
+ "httpx>=0.27",
15
+ "uvicorn>=0.30",
16
+ ]
17
+ authors = [{ name = "Mohammad Abbasi" }]
18
+
19
+ [project.scripts]
20
+ bonbama-mcp = "bonbama_mcp.server:main"
21
+
22
+ [tool.hatch.build.targets.wheel]
23
+ packages = ["src/bonbama_mcp"]
@@ -0,0 +1 @@
1
+ {"$schema":"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json","description":"Unofficial read-only MCP server for bonbama.ir — Gorgan discounts, businesses and codes.","name":"io.github.mohammad-abbasi-sh/bonbama-mcp","packages":[{"identifier":"bonbama-mcp","registryBaseUrl":"https://pypi.org","registryType":"pypi","transport":{"type":"stdio"},"version":"0.1.0"}],"repository":{"source":"github","url":"https://github.com/mohammad-abbasi-sh/bonbama-mcp"},"title":"Bonbama Discounts","version":"0.1.0","websiteUrl":"https://github.com/mohammad-abbasi-sh/bonbama-mcp"}
@@ -0,0 +1,2 @@
1
+ """bonbama_mcp — unofficial read-only MCP server for bonbama.ir discounts."""
2
+ __version__ = "0.1.0"