otaghak-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.
- otaghak_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +42 -0
- otaghak_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
- otaghak_mcp-0.1.0/.github/banner.png +0 -0
- otaghak_mcp-0.1.0/.github/dependabot.yml +10 -0
- otaghak_mcp-0.1.0/.github/workflows/ci.yml +22 -0
- otaghak_mcp-0.1.0/.github/workflows/publish.yml +51 -0
- otaghak_mcp-0.1.0/.gitignore +6 -0
- otaghak_mcp-0.1.0/LICENSE +21 -0
- otaghak_mcp-0.1.0/PKG-INFO +326 -0
- otaghak_mcp-0.1.0/README.md +300 -0
- otaghak_mcp-0.1.0/pyproject.toml +54 -0
- otaghak_mcp-0.1.0/server.json +32 -0
- otaghak_mcp-0.1.0/src/otaghak_mcp/__init__.py +5 -0
- otaghak_mcp-0.1.0/src/otaghak_mcp/http.py +134 -0
- otaghak_mcp-0.1.0/src/otaghak_mcp/info.py +168 -0
- otaghak_mcp-0.1.0/src/otaghak_mcp/pricing.py +294 -0
- otaghak_mcp-0.1.0/src/otaghak_mcp/registry.py +16 -0
- otaghak_mcp-0.1.0/src/otaghak_mcp/room.py +323 -0
- otaghak_mcp-0.1.0/src/otaghak_mcp/search.py +534 -0
- otaghak_mcp-0.1.0/src/otaghak_mcp/server.py +60 -0
- otaghak_mcp-0.1.0/tests/conftest.py +101 -0
- otaghak_mcp-0.1.0/tests/fixtures/attributes.json +119 -0
- otaghak_mcp-0.1.0/tests/fixtures/autocomplete.json +62 -0
- otaghak_mcp-0.1.0/tests/fixtures/autocomplete_room.json +22 -0
- otaghak_mcp-0.1.0/tests/fixtures/blog.json +23 -0
- otaghak_mcp-0.1.0/tests/fixtures/calendar.json +81 -0
- otaghak_mcp-0.1.0/tests/fixtures/calendar_quote.json +81 -0
- otaghak_mcp-0.1.0/tests/fixtures/city_districts.json +47 -0
- otaghak_mcp-0.1.0/tests/fixtures/city_landing.json +20 -0
- otaghak_mcp-0.1.0/tests/fixtures/detail.json +16 -0
- otaghak_mcp-0.1.0/tests/fixtures/faq.json +38 -0
- otaghak_mcp-0.1.0/tests/fixtures/faq_city.json +41 -0
- otaghak_mcp-0.1.0/tests/fixtures/holidays.json +281 -0
- otaghak_mcp-0.1.0/tests/fixtures/home.json +130 -0
- otaghak_mcp-0.1.0/tests/fixtures/host_profile.json +24 -0
- otaghak_mcp-0.1.0/tests/fixtures/host_reviews.json +87 -0
- otaghak_mcp-0.1.0/tests/fixtures/host_rooms.json +40 -0
- otaghak_mcp-0.1.0/tests/fixtures/late_calendar.json +43 -0
- otaghak_mcp-0.1.0/tests/fixtures/late_info.json +6 -0
- otaghak_mcp-0.1.0/tests/fixtures/late_info_none.json +6 -0
- otaghak_mcp-0.1.0/tests/fixtures/page_info.json +63 -0
- otaghak_mcp-0.1.0/tests/fixtures/pdp.json +751 -0
- otaghak_mcp-0.1.0/tests/fixtures/popular.json +67 -0
- otaghak_mcp-0.1.0/tests/fixtures/quote_search.json +42 -0
- otaghak_mcp-0.1.0/tests/fixtures/rating.json +65 -0
- otaghak_mcp-0.1.0/tests/fixtures/recommendation.json +5 -0
- otaghak_mcp-0.1.0/tests/fixtures/reviews.json +108 -0
- otaghak_mcp-0.1.0/tests/fixtures/search_discounted.json +147 -0
- otaghak_mcp-0.1.0/tests/fixtures/search_filters.json +515 -0
- otaghak_mcp-0.1.0/tests/fixtures/search_rooms.json +112 -0
- otaghak_mcp-0.1.0/tests/fixtures/search_rooms_undated.json +77 -0
- otaghak_mcp-0.1.0/tests/fixtures/similar.json +180 -0
- otaghak_mcp-0.1.0/tests/fixtures/similar_search.json +147 -0
- otaghak_mcp-0.1.0/tests/fixtures/terms.json +13 -0
- otaghak_mcp-0.1.0/tests/test_info.py +101 -0
- otaghak_mcp-0.1.0/tests/test_live_info.py +14 -0
- otaghak_mcp-0.1.0/tests/test_live_pricing.py +44 -0
- otaghak_mcp-0.1.0/tests/test_live_room.py +36 -0
- otaghak_mcp-0.1.0/tests/test_live_search.py +43 -0
- otaghak_mcp-0.1.0/tests/test_pricing.py +213 -0
- otaghak_mcp-0.1.0/tests/test_room.py +207 -0
- otaghak_mcp-0.1.0/tests/test_search.py +268 -0
- otaghak_mcp-0.1.0/tests/test_server.py +13 -0
- otaghak_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. ot_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 total shown on otaghak.com for the same room, dates and guests
|
|
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
|
+
- OTAGHAK_MCP_PROXY set
|
|
38
|
+
- type: input
|
|
39
|
+
id: version
|
|
40
|
+
attributes:
|
|
41
|
+
label: otaghak-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/otaghak-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
|
|
@@ -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,326 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: otaghak-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Unofficial read-only MCP server for Otaghak: search Iranian villas and cottages, check availability, exact stay prices, reviews and hosts.
|
|
5
|
+
Project-URL: Homepage, https://github.com/sepehr071/otaghak-mcp
|
|
6
|
+
Project-URL: Source, https://github.com/sepehr071/otaghak-mcp
|
|
7
|
+
Project-URL: Changelog, https://github.com/sepehr071/otaghak-mcp/releases
|
|
8
|
+
Project-URL: Issues, https://github.com/sepehr071/otaghak-mcp/issues
|
|
9
|
+
Author-email: Sepehr <sepehr@nextofx.com>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: booking,iran,mcp,model-context-protocol,otaghak,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/otaghak-mcp -->
|
|
28
|
+
|
|
29
|
+
<div align="center">
|
|
30
|
+
|
|
31
|
+
<img src="https://raw.githubusercontent.com/sepehr071/otaghak-mcp/main/.github/banner.png" alt="otaghak-mcp: let your AI agent find the real price of a stay on Otaghak" width="100%">
|
|
32
|
+
|
|
33
|
+
# 🏡 otaghak-mcp
|
|
34
|
+
|
|
35
|
+
**Let your AI agent find a place to stay on Otaghak.**<br>
|
|
36
|
+
Search villas, cottages and apartments across Iran, check which nights are free, get the exact price<br>
|
|
37
|
+
for your dates and guests, and read reviews and host stats, all from Claude, Cursor or Copilot.
|
|
38
|
+
|
|
39
|
+
[](https://pypi.org/project/otaghak-mcp/)
|
|
40
|
+
[](https://pypi.org/project/otaghak-mcp/)
|
|
41
|
+
[](https://github.com/sepehr071/otaghak-mcp/actions/workflows/ci.yml)
|
|
42
|
+
[](https://registry.modelcontextprotocol.io/?q=otaghak-mcp)
|
|
43
|
+
[](https://github.com/sepehr071/otaghak-mcp/blob/main/LICENSE)
|
|
44
|
+
|
|
45
|
+
[](https://cursor.com/en/install-mcp?name=otaghak&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJvdGFnaGFrLW1jcCJdfQ==)
|
|
46
|
+
[](https://vscode.dev/redirect/mcp/install?name=otaghak&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22otaghak-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 Otaghak the price on a listing card is rarely what you pay: every night has its own price, weekends cost
|
|
57
|
+
more, discounts change per night, extra guests cost extra per night, and calendars only open about a month
|
|
58
|
+
ahead. Getting *the real total for my dates and my group* means clicking through calendars one room at a time.
|
|
59
|
+
An agent with `otaghak-mcp` does the clicking:
|
|
60
|
+
|
|
61
|
+
> **You:** We are 4 people, Ramsar, 20 to 23 October. How much is the "سوییسی لیلی" cottage in total?
|
|
62
|
+
>
|
|
63
|
+
> **Agent:** *calls* `ot_search_rooms(city=["ramsar"], name="لیلی")` → `ot_price_quote(room_id=2508916, check_in="2026-10-20", check_out="2026-10-23", guests=4)`
|
|
64
|
+
>
|
|
65
|
+
> | Night | Price | Before discount |
|
|
66
|
+
> |---|---:|---:|
|
|
67
|
+
> | Tue 20 Oct | 4,000,000 | 5,000,000 |
|
|
68
|
+
> | Wed 21 Oct | 4,000,000 | 5,000,000 |
|
|
69
|
+
> | Thu 22 Oct | 4,250,000 | 5,000,000 |
|
|
70
|
+
> | 1 extra guest (3 nights) | 980,000 | 1,200,000 |
|
|
71
|
+
> | **Total to pay** | **13,230,000** | |
|
|
72
|
+
>
|
|
73
|
+
> The cottage includes 3 guests and takes at most 4, so the 4th person costs 400,000 a night (discounted like the
|
|
74
|
+
> nights). All three nights are free and bookable instantly. Want me to compare it with `ot_similar_rooms`?
|
|
75
|
+
|
|
76
|
+
<sub>Real tool output from 2026-10-04; prices change all the time. Prices are in Toman.</sub>
|
|
77
|
+
|
|
78
|
+
## What it can do
|
|
79
|
+
|
|
80
|
+
- 🔎 **Search** stays in a city, province or themed collection (beach, jungle, villa with pool, ...) for your dates and group, sorted by price, rating or discount
|
|
81
|
+
- 🧮 **Exact price** for dates and guests: every night after discount, extra-guest charges, optional late checkout
|
|
82
|
+
- 📅 **Calendars**: which nights are free, nightly prices, minimum and maximum stay, weekends and holidays
|
|
83
|
+
- 🏠 **Room details**: rooms and beds, amenities, house rules, check-in times, cancellation policy, nearby shops, photos
|
|
84
|
+
- ⭐ **Quality**: rating, six category scores, percent who recommend it, reviews with host replies, host response time and acceptance rate
|
|
85
|
+
- 🏷️ **Deals**: last-second discounts and the most discounted stays
|
|
86
|
+
- 🧭 **Guides**: destination guides, FAQ, blog articles and the site's rules (cancellation, refunds)
|
|
87
|
+
- 🔒 **Read-only by design**: no login, no booking, no payment, no SMS codes
|
|
88
|
+
|
|
89
|
+
## Quick start
|
|
90
|
+
|
|
91
|
+
You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
|
|
92
|
+
|
|
93
|
+
<details open>
|
|
94
|
+
<summary><b>Claude Code</b></summary>
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
claude mcp add otaghak -- uvx otaghak-mcp
|
|
98
|
+
```
|
|
99
|
+
</details>
|
|
100
|
+
|
|
101
|
+
<details>
|
|
102
|
+
<summary><b>Claude Desktop</b></summary>
|
|
103
|
+
|
|
104
|
+
Settings → Developer → Edit Config, then add:
|
|
105
|
+
|
|
106
|
+
```json
|
|
107
|
+
{
|
|
108
|
+
"mcpServers": {
|
|
109
|
+
"otaghak": { "command": "uvx", "args": ["otaghak-mcp"] }
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
</details>
|
|
114
|
+
|
|
115
|
+
<details>
|
|
116
|
+
<summary><b>Cursor</b></summary>
|
|
117
|
+
|
|
118
|
+
Click **Install in Cursor** above, or add the Claude Desktop block to `~/.cursor/mcp.json`.
|
|
119
|
+
</details>
|
|
120
|
+
|
|
121
|
+
<details>
|
|
122
|
+
<summary><b>VS Code (Copilot agent mode)</b></summary>
|
|
123
|
+
|
|
124
|
+
Click **Install in VS Code** above, or add to `.vscode/mcp.json`:
|
|
125
|
+
|
|
126
|
+
```json
|
|
127
|
+
{
|
|
128
|
+
"servers": {
|
|
129
|
+
"otaghak": { "type": "stdio", "command": "uvx", "args": ["otaghak-mcp"] }
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
</details>
|
|
134
|
+
|
|
135
|
+
<details>
|
|
136
|
+
<summary><b>Anything else</b></summary>
|
|
137
|
+
|
|
138
|
+
It's a standard stdio MCP server: run `uvx otaghak-mcp`, or `pip install otaghak-mcp` and run `otaghak-mcp`.
|
|
139
|
+
</details>
|
|
140
|
+
|
|
141
|
+
Then just ask:
|
|
142
|
+
|
|
143
|
+
- "Cheapest villa with a pool near Ramsar for 6 people next weekend?"
|
|
144
|
+
- "Is room 2512254 free from 20 to 23 October, and what's the total for 5 guests?"
|
|
145
|
+
- "Pet-friendly cottages in Gilan with a rating of 4 or more."
|
|
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
|
+
otaghak-mcp (runs on your machine)
|
|
156
|
+
│
|
|
157
|
+
│ HTTPS (REST + OData)
|
|
158
|
+
└──────▶ core.otaghak.com, www.otaghak.com/blog
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
`otaghak-mcp` runs locally and calls the same public endpoints the otaghak.com website uses.
|
|
162
|
+
There's no hosted server in between, no API key, and nothing about you is sent anywhere else.
|
|
163
|
+
|
|
164
|
+
## Tools
|
|
165
|
+
|
|
166
|
+
Rooms are identified by numeric ids like `2512254` (the number in `otaghak.com/room/2512254/`), places by slugs
|
|
167
|
+
like `ramsar` (city), `mazandaran` (province) or `beach` (collection).
|
|
168
|
+
|
|
169
|
+
<details open>
|
|
170
|
+
<summary><b>🔎 Search</b> (5)</summary>
|
|
171
|
+
|
|
172
|
+
| Tool | What it does |
|
|
173
|
+
|---|---|
|
|
174
|
+
| `ot_find_place` | Place name → city / province slug; a room code → that room |
|
|
175
|
+
| `ot_search_rooms` | Stays in a city, province or collection for dates and guests, with filters and sorting |
|
|
176
|
+
| `ot_search_filters` | Filter codes (pool, parking, pets, beach or jungle area, ...), room types, price range, landmarks |
|
|
177
|
+
| `ot_destinations` | Popular cities and collections, and the cities of a collection |
|
|
178
|
+
| `ot_deals` | Last-second deals and the most discounted stays |
|
|
179
|
+
</details>
|
|
180
|
+
|
|
181
|
+
<details open>
|
|
182
|
+
<summary><b>🏠 Room and host</b> (4)</summary>
|
|
183
|
+
|
|
184
|
+
| Tool | What it does |
|
|
185
|
+
|---|---|
|
|
186
|
+
| `ot_room` | Details, amenities, rules, check-in/out times, cancellation policy, host, location, photos |
|
|
187
|
+
| `ot_reviews` | Rating, star histogram, category scores, percent who recommend, reviews with host replies |
|
|
188
|
+
| `ot_similar_rooms` | 4-5 alternatives, re-priced and checked for your dates and guests |
|
|
189
|
+
| `ot_host` | Host response time, response and acceptance rates, other rooms, newest reviews |
|
|
190
|
+
</details>
|
|
191
|
+
|
|
192
|
+
<details open>
|
|
193
|
+
<summary><b>📅 Dates and prices</b> (4)</summary>
|
|
194
|
+
|
|
195
|
+
| Tool | What it does |
|
|
196
|
+
|---|---|
|
|
197
|
+
| `ot_room_calendar` | Day by day: free or booked, price, min/max nights, weekend, holiday, late checkout |
|
|
198
|
+
| `ot_price_quote` | Exact amount to pay for dates and guests, extra guests and late checkout included |
|
|
199
|
+
| `ot_holidays` | Iranian public holidays in a date range, with Jalali dates |
|
|
200
|
+
| `ot_late_checkout` | Whether a room offers late checkout, hours, price, and if it's open on your departure day |
|
|
201
|
+
</details>
|
|
202
|
+
|
|
203
|
+
<details open>
|
|
204
|
+
<summary><b>🧭 Help and guides</b> (2)</summary>
|
|
205
|
+
|
|
206
|
+
| Tool | What it does |
|
|
207
|
+
|---|---|
|
|
208
|
+
| `ot_help` | Help-center FAQ, guest terms (booking, cancellation policies, refunds, wallet), host rules |
|
|
209
|
+
| `ot_travel_guide` | Destination guide, its FAQ, related search pages and blog articles |
|
|
210
|
+
</details>
|
|
211
|
+
|
|
212
|
+
All 15 tools are annotated `readOnlyHint: true` and return compact structured JSON, so they don't flood the agent's context.
|
|
213
|
+
|
|
214
|
+
## Good to know
|
|
215
|
+
|
|
216
|
+
- **Prices are in Toman**, as on the site (1 Toman = 10 Rial). `price_per_night` is after discount. Without dates, prices are the room's undated starting price, not a quote.
|
|
217
|
+
- **The amount to pay** is `ot_price_quote` → `total`: the nights after discount (the room page's payable amount), plus extra guests above the room's included guests (discounted like the nights), plus optional late checkout. Coupons and wallet credit need a login and are not included. Search results carry a `stay_total` estimate that can be a few Toman off; with dates, `sort="cheapest"` orders each page by it.
|
|
218
|
+
- **Dates** are Gregorian `YYYY-MM-DD` and `check_out` is the departure day. No past dates, at most 20 nights, and hosts' calendars open only to the end of the next Jalali month; the tools say so clearly instead of returning an empty list. A Jalali date gets an error with its Gregorian twin.
|
|
219
|
+
- **Guests:** each room includes `base_guests` in its price and takes up to `max_guests`. `ot_price_quote` checks the limit itself (the site's own search doesn't when you ask for a specific room).
|
|
220
|
+
- **Ratings are 0–5**; `null` means not rated yet. Holiday flags are only published about 7 weeks ahead.
|
|
221
|
+
- **Location** is approximate (about 100 m); the exact address and the host's phone come only after booking.
|
|
222
|
+
- **Persian queries match best** (`رامسر`, `کلبه`), English slugs work too.
|
|
223
|
+
|
|
224
|
+
## FAQ
|
|
225
|
+
|
|
226
|
+
<details>
|
|
227
|
+
<summary><b>Can it book a room for me?</b></summary>
|
|
228
|
+
|
|
229
|
+
No, and that's deliberate. It has no login and never calls booking, payment, OTP/SMS, wallet, favorites or review
|
|
230
|
+
endpoints. The agent finds the room and the exact price; you book on otaghak.com.
|
|
231
|
+
</details>
|
|
232
|
+
|
|
233
|
+
<details>
|
|
234
|
+
<summary><b>Why does a search for December return an error?</b></summary>
|
|
235
|
+
|
|
236
|
+
Hosts' calendars on Otaghak are open only to the end of the next Jalali month, and stays are limited to 20 nights.
|
|
237
|
+
Outside that window the site has no prices, so the tools tell you the last bookable day instead.
|
|
238
|
+
</details>
|
|
239
|
+
|
|
240
|
+
<details>
|
|
241
|
+
<summary><b>Do I need an Iranian IP?</b></summary>
|
|
242
|
+
|
|
243
|
+
No. It was tested from an Iranian home connection and through a Turkish exit, and both worked. Cloud servers
|
|
244
|
+
outside Iran were not tested; if Otaghak blocks one, set `OTAGHAK_MCP_PROXY`.
|
|
245
|
+
</details>
|
|
246
|
+
|
|
247
|
+
<details>
|
|
248
|
+
<summary><b>I get "did not answer in time" or "Could not reach"</b></summary>
|
|
249
|
+
|
|
250
|
+
The server retries a failed connection once (timeouts are not retried). If it keeps failing, check your connection
|
|
251
|
+
or set `OTAGHAK_MCP_PROXY`. Normal system proxy variables are ignored on purpose, because direct calls are the fastest.
|
|
252
|
+
</details>
|
|
253
|
+
|
|
254
|
+
<details>
|
|
255
|
+
<summary><b>Claude Desktop says <code>uvx</code> is not found</b></summary>
|
|
256
|
+
|
|
257
|
+
Use the full path to `uvx` (`where uvx` on Windows, `which uvx` on macOS/Linux) as `command`.
|
|
258
|
+
</details>
|
|
259
|
+
|
|
260
|
+
<details>
|
|
261
|
+
<summary><b>How do I debug what the agent sees?</b></summary>
|
|
262
|
+
|
|
263
|
+
```bash
|
|
264
|
+
npx @modelcontextprotocol/inspector uvx otaghak-mcp
|
|
265
|
+
```
|
|
266
|
+
</details>
|
|
267
|
+
|
|
268
|
+
## Configuration
|
|
269
|
+
|
|
270
|
+
| Variable | Default | Meaning |
|
|
271
|
+
|---|---|---|
|
|
272
|
+
| `OTAGHAK_MCP_PROXY` | unset | HTTP proxy for every request, e.g. `http://user:pass@host:port` |
|
|
273
|
+
|
|
274
|
+
## فارسی
|
|
275
|
+
|
|
276
|
+
<div dir="rtl">
|
|
277
|
+
|
|
278
|
+
**otaghak-mcp** به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد در اتاقک ویلا، کلبه و
|
|
279
|
+
آپارتمان جستجو کند، شب‌های خالی را ببیند، مبلغ دقیق اقامت را برای تاریخ و تعداد نفرات شما حساب کند و نظرات و
|
|
280
|
+
وضعیت میزبان را بخواند.
|
|
281
|
+
|
|
282
|
+
- فقط خواندنی است: وارد حساب نمی‌شود، رزرو و پرداخت نمی‌کند و کد پیامکی نمی‌فرستد.
|
|
283
|
+
- مبلغ نهایی را با قیمت تک‌تک شب‌ها، هزینه نفر اضافه و تأخیر در تخلیه حساب می‌کند.
|
|
284
|
+
- همه قیمت‌ها به تومان است و تاریخ‌ها میلادی (YYYY-MM-DD) هستند.
|
|
285
|
+
- روی سیستم خود شما اجرا می‌شود و به هیچ سرور واسطی داده نمی‌فرستد.
|
|
286
|
+
|
|
287
|
+
**نصب در Claude Code:**
|
|
288
|
+
|
|
289
|
+
</div>
|
|
290
|
+
|
|
291
|
+
```bash
|
|
292
|
+
claude mcp add otaghak -- uvx otaghak-mcp
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
<div dir="rtl">
|
|
296
|
+
|
|
297
|
+
بعد بپرسید: «ارزان‌ترین ویلای استخردار رامسر برای ۶ نفر از ۲۰ تا ۲۳ اکتبر چند تمام می‌شود؟»
|
|
298
|
+
|
|
299
|
+
</div>
|
|
300
|
+
|
|
301
|
+
## Development
|
|
302
|
+
|
|
303
|
+
```bash
|
|
304
|
+
git clone https://github.com/sepehr071/otaghak-mcp && cd otaghak-mcp
|
|
305
|
+
uv sync
|
|
306
|
+
uv run pytest # offline, against recorded responses
|
|
307
|
+
uv run pytest -m live # real API
|
|
308
|
+
uv run ruff check .
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
Tools live in `src/otaghak_mcp/search.py`, `room.py`, `pricing.py` and `info.py`; each is a typed async function
|
|
312
|
+
with a docstring that tells the agent when to use it. Issues and PRs are welcome, especially new tools and fixes for
|
|
313
|
+
API changes.
|
|
314
|
+
|
|
315
|
+
Releases: bump the version in `pyproject.toml` and `server.json`, then push a `v*` tag. GitHub Actions tests,
|
|
316
|
+
publishes to PyPI and the [MCP Registry](https://registry.modelcontextprotocol.io), and creates the GitHub Release.
|
|
317
|
+
|
|
318
|
+
## Disclaimer
|
|
319
|
+
|
|
320
|
+
Unofficial and not affiliated with or endorsed by Otaghak. It uses the public endpoints of the otaghak.com website,
|
|
321
|
+
which can change without notice. Otaghak offers an official booking web service to partners under contract; this is
|
|
322
|
+
not it. Please keep request rates reasonable.
|
|
323
|
+
|
|
324
|
+
## License
|
|
325
|
+
|
|
326
|
+
[MIT](https://github.com/sepehr071/otaghak-mcp/blob/main/LICENSE)
|