jabama-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.
- jabama_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +42 -0
- jabama_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
- jabama_mcp-0.1.0/.github/banner.png +0 -0
- jabama_mcp-0.1.0/.github/dependabot.yml +10 -0
- jabama_mcp-0.1.0/.github/workflows/ci.yml +22 -0
- jabama_mcp-0.1.0/.github/workflows/publish.yml +51 -0
- jabama_mcp-0.1.0/.gitignore +6 -0
- jabama_mcp-0.1.0/LICENSE +21 -0
- jabama_mcp-0.1.0/PKG-INFO +349 -0
- jabama_mcp-0.1.0/README.md +323 -0
- jabama_mcp-0.1.0/pyproject.toml +54 -0
- jabama_mcp-0.1.0/server.json +32 -0
- jabama_mcp-0.1.0/src/jabama_mcp/__init__.py +5 -0
- jabama_mcp-0.1.0/src/jabama_mcp/events.py +502 -0
- jabama_mcp-0.1.0/src/jabama_mcp/http.py +149 -0
- jabama_mcp-0.1.0/src/jabama_mcp/info.py +109 -0
- jabama_mcp-0.1.0/src/jabama_mcp/registry.py +16 -0
- jabama_mcp-0.1.0/src/jabama_mcp/search.py +369 -0
- jabama_mcp-0.1.0/src/jabama_mcp/server.py +64 -0
- jabama_mcp-0.1.0/src/jabama_mcp/stay.py +531 -0
- jabama_mcp-0.1.0/src/jabama_mcp/tours.py +295 -0
- jabama_mcp-0.1.0/tests/conftest.py +84 -0
- jabama_mcp-0.1.0/tests/fixtures/amenities.json +270 -0
- jabama_mcp-0.1.0/tests/fixtures/availability.json +26 -0
- jabama_mcp-0.1.0/tests/fixtures/blog.json +145 -0
- jabama_mcp-0.1.0/tests/fixtures/cancellation.json +61 -0
- jabama_mcp-0.1.0/tests/fixtures/categories.json +154 -0
- jabama_mcp-0.1.0/tests/fixtures/daytype.json +167 -0
- jabama_mcp-0.1.0/tests/fixtures/descriptive.json +53 -0
- jabama_mcp-0.1.0/tests/fixtures/detail.json +1382 -0
- jabama_mcp-0.1.0/tests/fixtures/detail_bad.json +6 -0
- jabama_mcp-0.1.0/tests/fixtures/detail_complex.json +32 -0
- jabama_mcp-0.1.0/tests/fixtures/event.json +159 -0
- jabama_mcp-0.1.0/tests/fixtures/event_bad.json +4 -0
- jabama_mcp-0.1.0/tests/fixtures/event_categories.json +142 -0
- jabama_mcp-0.1.0/tests/fixtures/event_cities.json +35 -0
- jabama_mcp-0.1.0/tests/fixtures/events.json +141 -0
- jabama_mcp-0.1.0/tests/fixtures/faq_none.json +7 -0
- jabama_mcp-0.1.0/tests/fixtures/faq_search.json +17 -0
- jabama_mcp-0.1.0/tests/fixtures/fts.json +47 -0
- jabama_mcp-0.1.0/tests/fixtures/host_listings.json +70 -0
- jabama_mcp-0.1.0/tests/fixtures/host_reviews.json +66 -0
- jabama_mcp-0.1.0/tests/fixtures/host_unknown_listings.json +11 -0
- jabama_mcp-0.1.0/tests/fixtures/host_unknown_reviews.json +14 -0
- jabama_mcp-0.1.0/tests/fixtures/organizer.json +63 -0
- jabama_mcp-0.1.0/tests/fixtures/other_rooms.json +37 -0
- jabama_mcp-0.1.0/tests/fixtures/place_reviews.json +101 -0
- jabama_mcp-0.1.0/tests/fixtures/plp_404.json +14 -0
- jabama_mcp-0.1.0/tests/fixtures/plp_codes.json +461 -0
- jabama_mcp-0.1.0/tests/fixtures/plp_instant.json +409 -0
- jabama_mcp-0.1.0/tests/fixtures/plp_retired.json +15 -0
- jabama_mcp-0.1.0/tests/fixtures/plp_search.json +443 -0
- jabama_mcp-0.1.0/tests/fixtures/quote.json +185 -0
- jabama_mcp-0.1.0/tests/fixtures/quote_complex.json +189 -0
- jabama_mcp-0.1.0/tests/fixtures/quote_past.json +15 -0
- jabama_mcp-0.1.0/tests/fixtures/seat_404.json +4 -0
- jabama_mcp-0.1.0/tests/fixtures/seat_layout.json +1250 -0
- jabama_mcp-0.1.0/tests/fixtures/seat_status.json +13 -0
- jabama_mcp-0.1.0/tests/fixtures/seatmap.json +725 -0
- jabama_mcp-0.1.0/tests/fixtures/sessions.json +19 -0
- jabama_mcp-0.1.0/tests/fixtures/sessions_timeslots.json +66 -0
- jabama_mcp-0.1.0/tests/fixtures/similar.json +241 -0
- jabama_mcp-0.1.0/tests/fixtures/support_faq.json +72 -0
- jabama_mcp-0.1.0/tests/fixtures/theater.json +214 -0
- jabama_mcp-0.1.0/tests/fixtures/theater_bad.json +4 -0
- jabama_mcp-0.1.0/tests/fixtures/theater_book.data +1 -0
- jabama_mcp-0.1.0/tests/fixtures/theater_summaries.json +42 -0
- jabama_mcp-0.1.0/tests/fixtures/theaters.json +623 -0
- jabama_mcp-0.1.0/tests/fixtures/tour.json +868 -0
- jabama_mcp-0.1.0/tests/fixtures/tour_bad.json +8 -0
- jabama_mcp-0.1.0/tests/fixtures/tour_places.json +69 -0
- jabama_mcp-0.1.0/tests/fixtures/tour_reviews.json +78 -0
- jabama_mcp-0.1.0/tests/fixtures/tours.json +364 -0
- jabama_mcp-0.1.0/tests/fixtures/variants.json +33 -0
- jabama_mcp-0.1.0/tests/test_events.py +254 -0
- jabama_mcp-0.1.0/tests/test_info.py +57 -0
- jabama_mcp-0.1.0/tests/test_live_events.py +48 -0
- jabama_mcp-0.1.0/tests/test_live_info.py +15 -0
- jabama_mcp-0.1.0/tests/test_live_search.py +40 -0
- jabama_mcp-0.1.0/tests/test_live_stay.py +50 -0
- jabama_mcp-0.1.0/tests/test_live_tours.py +22 -0
- jabama_mcp-0.1.0/tests/test_search.py +180 -0
- jabama_mcp-0.1.0/tests/test_stay.py +289 -0
- jabama_mcp-0.1.0/tests/test_tours.py +141 -0
- jabama_mcp-0.1.0/uv.lock +1112 -0
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
name: Bug report
|
|
2
|
+
description: A tool failed or returned wrong data
|
|
3
|
+
labels: [bug]
|
|
4
|
+
body:
|
|
5
|
+
- type: input
|
|
6
|
+
id: tool
|
|
7
|
+
attributes:
|
|
8
|
+
label: Tool
|
|
9
|
+
description: Which tool, e.g. jb_price_quote
|
|
10
|
+
validations:
|
|
11
|
+
required: true
|
|
12
|
+
- type: textarea
|
|
13
|
+
id: input
|
|
14
|
+
attributes:
|
|
15
|
+
label: Arguments and result
|
|
16
|
+
description: The arguments the agent sent and the error or wrong output. Remove anything personal.
|
|
17
|
+
render: json
|
|
18
|
+
validations:
|
|
19
|
+
required: true
|
|
20
|
+
- type: textarea
|
|
21
|
+
id: expected
|
|
22
|
+
attributes:
|
|
23
|
+
label: What you expected
|
|
24
|
+
description: e.g. the price shown on jabama.com for the same stay and dates
|
|
25
|
+
- type: input
|
|
26
|
+
id: client
|
|
27
|
+
attributes:
|
|
28
|
+
label: MCP client and OS
|
|
29
|
+
placeholder: Claude Desktop 1.x on Windows 11
|
|
30
|
+
- type: dropdown
|
|
31
|
+
id: network
|
|
32
|
+
attributes:
|
|
33
|
+
label: Network
|
|
34
|
+
options:
|
|
35
|
+
- Iranian IP, no VPN
|
|
36
|
+
- VPN or proxy
|
|
37
|
+
- JABAMA_MCP_PROXY set
|
|
38
|
+
- type: input
|
|
39
|
+
id: version
|
|
40
|
+
attributes:
|
|
41
|
+
label: jabama-mcp version
|
|
42
|
+
placeholder: "0.1.0"
|
|
Binary file
|
|
@@ -0,0 +1,22 @@
|
|
|
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@v7
|
|
16
|
+
- uses: astral-sh/setup-uv@v10.2.0
|
|
17
|
+
with:
|
|
18
|
+
python-version: ${{ matrix.python }}
|
|
19
|
+
- run: uv sync --locked
|
|
20
|
+
- run: uv run ruff check .
|
|
21
|
+
- run: uv run ruff format --check .
|
|
22
|
+
- run: uv run pytest -q
|
|
@@ -0,0 +1,51 @@
|
|
|
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: write # GitHub Release
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v7
|
|
18
|
+
- uses: astral-sh/setup-uv@v10.2.0
|
|
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
|
+
- run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --title "$GITHUB_REF_NAME"
|
|
29
|
+
env:
|
|
30
|
+
GH_TOKEN: ${{ github.token }}
|
|
31
|
+
|
|
32
|
+
mcp-registry:
|
|
33
|
+
needs: pypi
|
|
34
|
+
runs-on: ubuntu-latest
|
|
35
|
+
permissions:
|
|
36
|
+
id-token: write # MCP Registry login via GitHub OIDC
|
|
37
|
+
contents: read
|
|
38
|
+
steps:
|
|
39
|
+
- uses: actions/checkout@v7
|
|
40
|
+
- name: Wait for PyPI to serve the new version
|
|
41
|
+
run: |
|
|
42
|
+
for i in $(seq 1 30); do
|
|
43
|
+
curl -sf "https://pypi.org/pypi/jabama-mcp/${GITHUB_REF_NAME#v}/json" >/dev/null && exit 0
|
|
44
|
+
sleep 10
|
|
45
|
+
done
|
|
46
|
+
exit 1
|
|
47
|
+
- name: Install mcp-publisher
|
|
48
|
+
run: |
|
|
49
|
+
curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.1/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
|
|
50
|
+
- run: ./mcp-publisher login github-oidc
|
|
51
|
+
- run: ./mcp-publisher publish
|
jabama_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.
|
|
@@ -0,0 +1,349 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: jabama-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Unofficial read-only MCP server for Jabama: search villas and stays with exact prices, group tours, events and theater tickets.
|
|
5
|
+
Project-URL: Homepage, https://github.com/sepehr071/jabama-mcp
|
|
6
|
+
Project-URL: Source, https://github.com/sepehr071/jabama-mcp
|
|
7
|
+
Project-URL: Changelog, https://github.com/sepehr071/jabama-mcp/releases
|
|
8
|
+
Project-URL: Issues, https://github.com/sepehr071/jabama-mcp/issues
|
|
9
|
+
Author-email: Sepehr <sepehr@nextofx.com>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: events,iran,jabama,mcp,model-context-protocol,tours,travel,vacation-rental,villa
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Requires-Dist: httpx>=0.27
|
|
24
|
+
Requires-Dist: mcp<3,>=2.2
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
<!-- mcp-name: io.github.sepehr071/jabama-mcp -->
|
|
28
|
+
|
|
29
|
+
<div align="center">
|
|
30
|
+
|
|
31
|
+
<img src="https://raw.githubusercontent.com/sepehr071/jabama-mcp/main/.github/banner.png" alt="jabama-mcp: let your AI agent price stays, tours and events on Jabama" width="100%">
|
|
32
|
+
|
|
33
|
+
# 🏡 jabama-mcp
|
|
34
|
+
|
|
35
|
+
**Let your AI agent plan the trip on Jabama.**<br>
|
|
36
|
+
Search villas, suites and eco-lodges with the exact price for your dates and guests, read rules and reviews,<br>
|
|
37
|
+
and find group tours, events and theater seats, all from Claude, Cursor or Copilot.
|
|
38
|
+
|
|
39
|
+
[](https://pypi.org/project/jabama-mcp/)
|
|
40
|
+
[](https://pypi.org/project/jabama-mcp/)
|
|
41
|
+
[](https://github.com/sepehr071/jabama-mcp/actions/workflows/ci.yml)
|
|
42
|
+
[](https://registry.modelcontextprotocol.io/?q=jabama-mcp)
|
|
43
|
+
[](https://github.com/sepehr071/jabama-mcp/blob/main/LICENSE)
|
|
44
|
+
|
|
45
|
+
[](https://cursor.com/en/install-mcp?name=jabama&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJqYWJhbWEtbWNwIl19)
|
|
46
|
+
[](https://vscode.dev/redirect/mcp/install?name=jabama&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22jabama-mcp%22%5D%7D)
|
|
47
|
+
|
|
48
|
+
[Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
|
|
49
|
+
|
|
50
|
+
</div>
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## Why
|
|
55
|
+
|
|
56
|
+
On Jabama (jabama.com) a search card shows one price, but the real cost of a stay depends on the nights you pick
|
|
57
|
+
(weekends and holidays are priced differently), how many guests come (every guest above the base count adds a
|
|
58
|
+
nightly charge) and long-stay discounts. An agent with `jabama-mcp` reads the search, the nightly calendar and the
|
|
59
|
+
site's own price quote, so the number it gives you is the number you pay:
|
|
60
|
+
|
|
61
|
+
> **You:** A cheap eco-lodge near Ramsar for 4 people, 20 to 23 October?
|
|
62
|
+
>
|
|
63
|
+
> **Agent:** *calls* `jb_find_destination(query="رامسر")` → `jb_search_stays(keyword="city-ramsar", check_in="2026-10-20", check_out="2026-10-23", guests=4, types=["ecotourism"], sort="cheapest")` → `jb_price_quote(code=328353, check_in="2026-10-20", check_out="2026-10-23", guests=4)`
|
|
64
|
+
>
|
|
65
|
+
> | Night | Type | Night price | 2 extra guests | Total |
|
|
66
|
+
> |---|---|---:|---:|---:|
|
|
67
|
+
> | 20 Oct | weekday | 600,000 | 300,000 | 900,000 |
|
|
68
|
+
> | 21 Oct | weekend | 520,000 | 300,000 | 820,000 |
|
|
69
|
+
> | 22 Oct | weekend | 520,000 | 300,000 | 820,000 |
|
|
70
|
+
>
|
|
71
|
+
> نسا - افرا in Tonekabon: **2,540,000 Toman** for 3 nights and 4 guests (or 4 parts of 635,000). The host must
|
|
72
|
+
> accept the booking first; cancelling up to 24 Mehr costs 10% of the first night and 10% of the rest.
|
|
73
|
+
|
|
74
|
+
<sub>Real tool output from 2026-10-04; prices change all the time. Prices are in Toman.</sub>
|
|
75
|
+
|
|
76
|
+
## What it can do
|
|
77
|
+
|
|
78
|
+
- 📍 **Find a place**: Persian city, area or landmark names (a beach, a mall, an airport) to search filters
|
|
79
|
+
- 🗣️ **Understand a request**: free text like «ویلای استخردار در رامسر برای ۶ نفر» becomes filters, with Jabama's own AI parser
|
|
80
|
+
- 🔎 **Search stays** by dates and guests with type, amenities, region, rooms, price, instant booking and rating filters
|
|
81
|
+
- 🧾 **Get the exact price** for dates and guests, night by night, with discounts and the cancellation windows
|
|
82
|
+
- 📅 **See the calendar**: free nights and nightly prices for the next ~76 days, with weekends and holidays
|
|
83
|
+
- ⭐ **Check quality**: house rules, amenities (and what is missing), reviews, host reputation, similar stays
|
|
84
|
+
- 🚌 **Group tours** (jabama.tours): search, departures with free seats and per-package prices, day plans
|
|
85
|
+
- 🎭 **Events and theater** (jabama.events): what is on, sessions, seats left, free seats by row and price
|
|
86
|
+
- 🔒 **Read-only by design**: no login, no booking, no seat holds, no payment
|
|
87
|
+
|
|
88
|
+
## Quick start
|
|
89
|
+
|
|
90
|
+
You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
|
|
91
|
+
|
|
92
|
+
<details open>
|
|
93
|
+
<summary><b>Claude Code</b></summary>
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
claude mcp add jabama -- uvx jabama-mcp
|
|
97
|
+
```
|
|
98
|
+
</details>
|
|
99
|
+
|
|
100
|
+
<details>
|
|
101
|
+
<summary><b>Claude Desktop</b></summary>
|
|
102
|
+
|
|
103
|
+
Settings → Developer → Edit Config, then add:
|
|
104
|
+
|
|
105
|
+
```json
|
|
106
|
+
{
|
|
107
|
+
"mcpServers": {
|
|
108
|
+
"jabama": { "command": "uvx", "args": ["jabama-mcp"] }
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
</details>
|
|
113
|
+
|
|
114
|
+
<details>
|
|
115
|
+
<summary><b>Cursor</b></summary>
|
|
116
|
+
|
|
117
|
+
Click **Install in Cursor** above, or add the Claude Desktop block to `~/.cursor/mcp.json`.
|
|
118
|
+
</details>
|
|
119
|
+
|
|
120
|
+
<details>
|
|
121
|
+
<summary><b>VS Code (Copilot agent mode)</b></summary>
|
|
122
|
+
|
|
123
|
+
Click **Install in VS Code** above, or add to `.vscode/mcp.json`:
|
|
124
|
+
|
|
125
|
+
```json
|
|
126
|
+
{
|
|
127
|
+
"servers": {
|
|
128
|
+
"jabama": { "type": "stdio", "command": "uvx", "args": ["jabama-mcp"] }
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
</details>
|
|
133
|
+
|
|
134
|
+
<details>
|
|
135
|
+
<summary><b>Anything else</b></summary>
|
|
136
|
+
|
|
137
|
+
It's a standard stdio MCP server: run `uvx jabama-mcp`, or `pip install jabama-mcp` and run `jabama-mcp`.
|
|
138
|
+
</details>
|
|
139
|
+
|
|
140
|
+
Then just ask:
|
|
141
|
+
|
|
142
|
+
- "Cheapest villa with a pool in Ramsar for 6 people next weekend, and the exact total?"
|
|
143
|
+
- "Which nights is this cottage free in November, and which are cheapest?"
|
|
144
|
+
- "A one-day nature tour from Tehran this month, with free seats for 3."
|
|
145
|
+
- "What's on in Tehran on Friday evening under 500,000 Toman? Show the free seats."
|
|
146
|
+
- <span dir="rtl">قوانین کنسلی جاباما چیست و چقدر از پول برمی‌گردد؟</span>
|
|
147
|
+
|
|
148
|
+
## How it works
|
|
149
|
+
|
|
150
|
+
```text
|
|
151
|
+
AI agent (Claude, Cursor, Copilot, ...)
|
|
152
|
+
│
|
|
153
|
+
│ MCP over stdio
|
|
154
|
+
▼
|
|
155
|
+
jabama-mcp (runs on your machine)
|
|
156
|
+
│
|
|
157
|
+
│ HTTPS (JSON)
|
|
158
|
+
├──────▶ gw.jabama.com, www.jabama.com (stays, help, magazine)
|
|
159
|
+
├──────▶ api.jabama.tours (group tours)
|
|
160
|
+
└──────▶ api.jabama.events, jabama.events (events, theater)
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
`jabama-mcp` runs locally and calls the same public endpoints the Jabama websites use.
|
|
164
|
+
There's no hosted server in between, no API key, and nothing about you is sent anywhere else.
|
|
165
|
+
|
|
166
|
+
## Tools
|
|
167
|
+
|
|
168
|
+
Listings are identified by their numeric code (`328353`, the number in `jabama.com/stay/ecotourism-328353`);
|
|
169
|
+
tours by an 8-digit id, events and plays by the id in their page URL.
|
|
170
|
+
|
|
171
|
+
<details open>
|
|
172
|
+
<summary><b>🔎 Stay search</b> (4)</summary>
|
|
173
|
+
|
|
174
|
+
| Tool | What it does |
|
|
175
|
+
|---|---|
|
|
176
|
+
| `jb_find_destination` | Persian place name → ready search arguments (city, area, landmark, complex) |
|
|
177
|
+
| `jb_parse_request` | Free-text request → search arguments, using Jabama's AI parser |
|
|
178
|
+
| `jb_search_stays` | Search stays for dates and guests with filters, whole-stay prices, sorting |
|
|
179
|
+
| `jb_categories` | Themed lists (special pool, luxury, cheap, jungle, pet friendly, last-minute, ...) |
|
|
180
|
+
</details>
|
|
181
|
+
|
|
182
|
+
<details open>
|
|
183
|
+
<summary><b>🏡 One stay</b> (6)</summary>
|
|
184
|
+
|
|
185
|
+
| Tool | What it does |
|
|
186
|
+
|---|---|
|
|
187
|
+
| `jb_stay` | Capacity, beds, rules, amenities and missing ones, cancellation policy, host, review scores |
|
|
188
|
+
| `jb_stay_calendar` | Free nights and nightly prices with weekend and holiday flags (~76 days) |
|
|
189
|
+
| `jb_price_quote` | Exact payable amount for dates and guests, night by night; unit options for complexes |
|
|
190
|
+
| `jb_similar_stays` | Similar stays nearby (priced for your dates) and other units of the same property |
|
|
191
|
+
| `jb_reviews` | Guest reviews, newest or best/worst first, with host replies |
|
|
192
|
+
| `jb_host` | A host's listings and reviews across all of them |
|
|
193
|
+
</details>
|
|
194
|
+
|
|
195
|
+
<details open>
|
|
196
|
+
<summary><b>ℹ️ Help and guides</b> (2)</summary>
|
|
197
|
+
|
|
198
|
+
| Tool | What it does |
|
|
199
|
+
|---|---|
|
|
200
|
+
| `jb_help` | Jabama's rules: cancellation, refunds, payment, tax (help center + support answers) |
|
|
201
|
+
| `jb_travel_guide` | Jabama magazine travel guides for a destination |
|
|
202
|
+
</details>
|
|
203
|
+
|
|
204
|
+
<details open>
|
|
205
|
+
<summary><b>🎭 Events and theater</b> (6)</summary>
|
|
206
|
+
|
|
207
|
+
| Tool | What it does |
|
|
208
|
+
|---|---|
|
|
209
|
+
| `jb_search_events` | Events and experiences by city, category, date, price and rating |
|
|
210
|
+
| `jb_event` | One event: details, address, rules, sessions with seats left, reviews, organizer |
|
|
211
|
+
| `jb_event_seats` | Free seats of a seated session by section and row, with section prices |
|
|
212
|
+
| `jb_theaters` | Theater plays on sale: venue, from-price, rating, cast |
|
|
213
|
+
| `jb_theater` | One play: showtimes with live seats left; free seats of a showtime |
|
|
214
|
+
| `jb_event_filters` | Event cities and categories with counts |
|
|
215
|
+
</details>
|
|
216
|
+
|
|
217
|
+
<details open>
|
|
218
|
+
<summary><b>🚌 Group tours</b> (3)</summary>
|
|
219
|
+
|
|
220
|
+
| Tool | What it does |
|
|
221
|
+
|---|---|
|
|
222
|
+
| `jb_search_tours` | Tours by place, dates, category, tags, duration, price, difficulty, rating |
|
|
223
|
+
| `jb_tour` | One tour: departures with free seats and package prices, day plan, inclusions, cancellation, reviews |
|
|
224
|
+
| `jb_tour_places` | Place name → place id for the tour search |
|
|
225
|
+
</details>
|
|
226
|
+
|
|
227
|
+
All 21 tools are annotated `readOnlyHint: true` and return compact structured JSON, so they don't flood the agent's context.
|
|
228
|
+
|
|
229
|
+
## Good to know
|
|
230
|
+
|
|
231
|
+
- **Prices are in Toman** everywhere (1 Toman = 10 Rial). The stays API answers in Rial; the server divides by 10. Tours are Toman **per person**, events and theater Toman per ticket (or per unit, e.g. one boat, when `pricing` is `per_unit`).
|
|
232
|
+
- **Stay prices are for the whole stay** for the searched dates and guests (`total_price`); `cheapest_night` is the cheapest single night, not the average. Without dates a search prices one default night.
|
|
233
|
+
- **Count children as guests.** The quote has no child price, so `guests` is everyone who stays.
|
|
234
|
+
- **Dates are Gregorian** `YYYY-MM-DD` (1405-07-28 = 2026-10-20); times are Tehran local. Stays can be quoted for about the next 76 days.
|
|
235
|
+
- **`jb_price_quote` is the number to trust.** It is the same read-only quote the listing page shows; it creates no booking. Quotes show no tax line; Jabama's help center says 1.5% tax is added when booking.
|
|
236
|
+
- **Instant vs request:** `instant_booking: false` means the host must accept first. `instant_only` keeps only instant listings.
|
|
237
|
+
- **Tour seats:** only `jb_tour` has correct free seats; tour lists count seats once per package.
|
|
238
|
+
- **Ratings are 0–5**; `null` means not rated yet. Stay reviews carry only a Jalali month, not a date.
|
|
239
|
+
|
|
240
|
+
## FAQ
|
|
241
|
+
|
|
242
|
+
<details>
|
|
243
|
+
<summary><b>Can it book a villa or buy a ticket for me?</b></summary>
|
|
244
|
+
|
|
245
|
+
No, and that's deliberate. It has no login and never calls booking, order, payment, seat-hold or wallet endpoints.
|
|
246
|
+
`jb_price_quote` only asks for a price. The agent finds the best option; you book on the site.
|
|
247
|
+
</details>
|
|
248
|
+
|
|
249
|
+
<details>
|
|
250
|
+
<summary><b>A search with dates returns 0 results</b></summary>
|
|
251
|
+
|
|
252
|
+
Usually nothing is free for those dates with those filters, or the dates are past the ~76-day calendar. Try other
|
|
253
|
+
dates or fewer filters. Dates must be Gregorian; the server rejects Jalali-looking dates instead of searching.
|
|
254
|
+
</details>
|
|
255
|
+
|
|
256
|
+
<details>
|
|
257
|
+
<summary><b>Do I need an Iranian IP?</b></summary>
|
|
258
|
+
|
|
259
|
+
No geo block was seen: direct calls and calls through a proxy in Turkey both worked (2026-10-04). Cloud servers
|
|
260
|
+
were not tested; if Jabama blocks one, set `JABAMA_MCP_PROXY`.
|
|
261
|
+
</details>
|
|
262
|
+
|
|
263
|
+
<details>
|
|
264
|
+
<summary><b>I get "blocked the request (HTTP 403)"</b></summary>
|
|
265
|
+
|
|
266
|
+
Jabama's web firewall rejects requests that don't look like a browser; the server already sends a browser
|
|
267
|
+
User-Agent. If it still happens, wait a minute, turn off a VPN, or set `JABAMA_MCP_PROXY`. Normal system proxy
|
|
268
|
+
variables are ignored on purpose, because direct calls are the fastest.
|
|
269
|
+
</details>
|
|
270
|
+
|
|
271
|
+
<details>
|
|
272
|
+
<summary><b>The theater seat map says "not available right now"</b></summary>
|
|
273
|
+
|
|
274
|
+
The theater seat map comes live from Jabama's ticketing partner, which sometimes refuses for a while. The showtimes and
|
|
275
|
+
`seats_left` still work; try the seat map again later or for another showtime.
|
|
276
|
+
</details>
|
|
277
|
+
|
|
278
|
+
<details>
|
|
279
|
+
<summary><b>Claude Desktop says <code>uvx</code> is not found</b></summary>
|
|
280
|
+
|
|
281
|
+
Use the full path to `uvx` (`where uvx` on Windows, `which uvx` on macOS/Linux) as `command`.
|
|
282
|
+
</details>
|
|
283
|
+
|
|
284
|
+
<details>
|
|
285
|
+
<summary><b>How do I debug what the agent sees?</b></summary>
|
|
286
|
+
|
|
287
|
+
```bash
|
|
288
|
+
npx @modelcontextprotocol/inspector uvx jabama-mcp
|
|
289
|
+
```
|
|
290
|
+
</details>
|
|
291
|
+
|
|
292
|
+
## Configuration
|
|
293
|
+
|
|
294
|
+
| Variable | Default | Meaning |
|
|
295
|
+
|---|---|---|
|
|
296
|
+
| `JABAMA_MCP_PROXY` | unset | HTTP proxy for every request, e.g. `http://user:pass@host:port` |
|
|
297
|
+
|
|
298
|
+
## فارسی
|
|
299
|
+
|
|
300
|
+
<div dir="rtl">
|
|
301
|
+
|
|
302
|
+
**jabama-mcp** به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد در جاباما ویلا، سوئیت و
|
|
303
|
+
اقامتگاه بوم‌گردی پیدا کند، قیمت دقیق را برای تاریخ و تعداد نفرات شما بگیرد، قوانین و نظرات را بخواند و تورها،
|
|
304
|
+
رویدادها و صندلی‌های خالی تئاتر را هم پیدا کند.
|
|
305
|
+
|
|
306
|
+
- فقط خواندنی است: وارد حساب نمی‌شود، رزرو ثبت نمی‌کند، صندلی نگه نمی‌دارد و پرداخت نمی‌کند.
|
|
307
|
+
- قیمت هر شب، هزینه نفر اضافه، تخفیف اقامت طولانی و قوانین کنسلی را نشان می‌دهد.
|
|
308
|
+
- همه قیمت‌ها به تومان است.
|
|
309
|
+
- روی سیستم خود شما اجرا می‌شود و به هیچ سرور واسطی داده نمی‌فرستد.
|
|
310
|
+
|
|
311
|
+
**نصب در Claude Code:**
|
|
312
|
+
|
|
313
|
+
</div>
|
|
314
|
+
|
|
315
|
+
```bash
|
|
316
|
+
claude mcp add jabama -- uvx jabama-mcp
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
<div dir="rtl">
|
|
320
|
+
|
|
321
|
+
بعد بپرسید: «ارزان‌ترین ویلای استخردار رامسر برای ۶ نفر از ۲۸ مهر تا ۱ آبان، با قیمت نهایی»
|
|
322
|
+
|
|
323
|
+
</div>
|
|
324
|
+
|
|
325
|
+
## Development
|
|
326
|
+
|
|
327
|
+
```bash
|
|
328
|
+
git clone https://github.com/sepehr071/jabama-mcp && cd jabama-mcp
|
|
329
|
+
uv sync
|
|
330
|
+
uv run pytest # offline, against recorded responses
|
|
331
|
+
uv run pytest -m live # real APIs
|
|
332
|
+
uv run ruff check .
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
Tools live in `src/jabama_mcp/search.py`, `stay.py`, `info.py`, `tours.py` and `events.py`; each is a typed async
|
|
336
|
+
function with a docstring that tells the agent when to use it. Issues and PRs are welcome, especially new tools and
|
|
337
|
+
fixes for API changes.
|
|
338
|
+
|
|
339
|
+
Releases: bump the version in `pyproject.toml` and `server.json`, then push a `v*` tag. GitHub Actions tests,
|
|
340
|
+
publishes to PyPI and the [MCP Registry](https://registry.modelcontextprotocol.io), and creates the GitHub Release.
|
|
341
|
+
|
|
342
|
+
## Disclaimer
|
|
343
|
+
|
|
344
|
+
Unofficial and not affiliated with or endorsed by Jabama. It uses the public endpoints of the jabama.com,
|
|
345
|
+
jabama.tours and jabama.events websites, which can change without notice. Please keep request rates reasonable.
|
|
346
|
+
|
|
347
|
+
## License
|
|
348
|
+
|
|
349
|
+
[MIT](https://github.com/sepehr071/jabama-mcp/blob/main/LICENSE)
|