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.
- bonbama_mcp-0.1.0/.dockerignore +9 -0
- bonbama_mcp-0.1.0/.github/workflows/publish.yml +20 -0
- bonbama_mcp-0.1.0/.github/workflows/registry.yml +95 -0
- bonbama_mcp-0.1.0/.github/workflows/smoke.yml +21 -0
- bonbama_mcp-0.1.0/.gitignore +8 -0
- bonbama_mcp-0.1.0/DEPLOY.md +123 -0
- bonbama_mcp-0.1.0/Dockerfile +18 -0
- bonbama_mcp-0.1.0/LICENSE +79 -0
- bonbama_mcp-0.1.0/PKG-INFO +85 -0
- bonbama_mcp-0.1.0/README-fa.md +59 -0
- bonbama_mcp-0.1.0/README.md +72 -0
- bonbama_mcp-0.1.0/pyproject.toml +23 -0
- bonbama_mcp-0.1.0/server.json +1 -0
- bonbama_mcp-0.1.0/src/bonbama_mcp/__init__.py +2 -0
- bonbama_mcp-0.1.0/src/bonbama_mcp/bonbama.py +476 -0
- bonbama_mcp-0.1.0/src/bonbama_mcp/http.py +143 -0
- bonbama_mcp-0.1.0/src/bonbama_mcp/server.py +317 -0
- bonbama_mcp-0.1.0/tests/__init__.py +0 -0
- bonbama_mcp-0.1.0/tests/fixtures/articles-index.html +106 -0
- bonbama_mcp-0.1.0/tests/fixtures/business-takchh.html +47 -0
- bonbama_mcp-0.1.0/tests/fixtures/business-testino.html +1 -0
- bonbama_mcp-0.1.0/tests/fixtures/category-zban.html +254 -0
- bonbama_mcp-0.1.0/tests/fixtures/home-categories.html +968 -0
- bonbama_mcp-0.1.0/tests/fixtures/search-campaigns.html +549 -0
- bonbama_mcp-0.1.0/tests/fixtures/search-companies.html +94 -0
- bonbama_mcp-0.1.0/tests/fixtures/sitemap-articles.xml +51 -0
- bonbama_mcp-0.1.0/tests/fixtures/sitemap-categories.xml +151 -0
- bonbama_mcp-0.1.0/tests/fixtures/sitemap-companies.xml +51 -0
- bonbama_mcp-0.1.0/tests/smoke_live.py +17 -0
- bonbama_mcp-0.1.0/tests/test_bonbama.py +210 -0
- bonbama_mcp-0.1.0/tests/test_live.py +75 -0
|
@@ -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,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"}
|