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.
Files changed (64) hide show
  1. otaghak_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +42 -0
  2. otaghak_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
  3. otaghak_mcp-0.1.0/.github/banner.png +0 -0
  4. otaghak_mcp-0.1.0/.github/dependabot.yml +10 -0
  5. otaghak_mcp-0.1.0/.github/workflows/ci.yml +22 -0
  6. otaghak_mcp-0.1.0/.github/workflows/publish.yml +51 -0
  7. otaghak_mcp-0.1.0/.gitignore +6 -0
  8. otaghak_mcp-0.1.0/LICENSE +21 -0
  9. otaghak_mcp-0.1.0/PKG-INFO +326 -0
  10. otaghak_mcp-0.1.0/README.md +300 -0
  11. otaghak_mcp-0.1.0/pyproject.toml +54 -0
  12. otaghak_mcp-0.1.0/server.json +32 -0
  13. otaghak_mcp-0.1.0/src/otaghak_mcp/__init__.py +5 -0
  14. otaghak_mcp-0.1.0/src/otaghak_mcp/http.py +134 -0
  15. otaghak_mcp-0.1.0/src/otaghak_mcp/info.py +168 -0
  16. otaghak_mcp-0.1.0/src/otaghak_mcp/pricing.py +294 -0
  17. otaghak_mcp-0.1.0/src/otaghak_mcp/registry.py +16 -0
  18. otaghak_mcp-0.1.0/src/otaghak_mcp/room.py +323 -0
  19. otaghak_mcp-0.1.0/src/otaghak_mcp/search.py +534 -0
  20. otaghak_mcp-0.1.0/src/otaghak_mcp/server.py +60 -0
  21. otaghak_mcp-0.1.0/tests/conftest.py +101 -0
  22. otaghak_mcp-0.1.0/tests/fixtures/attributes.json +119 -0
  23. otaghak_mcp-0.1.0/tests/fixtures/autocomplete.json +62 -0
  24. otaghak_mcp-0.1.0/tests/fixtures/autocomplete_room.json +22 -0
  25. otaghak_mcp-0.1.0/tests/fixtures/blog.json +23 -0
  26. otaghak_mcp-0.1.0/tests/fixtures/calendar.json +81 -0
  27. otaghak_mcp-0.1.0/tests/fixtures/calendar_quote.json +81 -0
  28. otaghak_mcp-0.1.0/tests/fixtures/city_districts.json +47 -0
  29. otaghak_mcp-0.1.0/tests/fixtures/city_landing.json +20 -0
  30. otaghak_mcp-0.1.0/tests/fixtures/detail.json +16 -0
  31. otaghak_mcp-0.1.0/tests/fixtures/faq.json +38 -0
  32. otaghak_mcp-0.1.0/tests/fixtures/faq_city.json +41 -0
  33. otaghak_mcp-0.1.0/tests/fixtures/holidays.json +281 -0
  34. otaghak_mcp-0.1.0/tests/fixtures/home.json +130 -0
  35. otaghak_mcp-0.1.0/tests/fixtures/host_profile.json +24 -0
  36. otaghak_mcp-0.1.0/tests/fixtures/host_reviews.json +87 -0
  37. otaghak_mcp-0.1.0/tests/fixtures/host_rooms.json +40 -0
  38. otaghak_mcp-0.1.0/tests/fixtures/late_calendar.json +43 -0
  39. otaghak_mcp-0.1.0/tests/fixtures/late_info.json +6 -0
  40. otaghak_mcp-0.1.0/tests/fixtures/late_info_none.json +6 -0
  41. otaghak_mcp-0.1.0/tests/fixtures/page_info.json +63 -0
  42. otaghak_mcp-0.1.0/tests/fixtures/pdp.json +751 -0
  43. otaghak_mcp-0.1.0/tests/fixtures/popular.json +67 -0
  44. otaghak_mcp-0.1.0/tests/fixtures/quote_search.json +42 -0
  45. otaghak_mcp-0.1.0/tests/fixtures/rating.json +65 -0
  46. otaghak_mcp-0.1.0/tests/fixtures/recommendation.json +5 -0
  47. otaghak_mcp-0.1.0/tests/fixtures/reviews.json +108 -0
  48. otaghak_mcp-0.1.0/tests/fixtures/search_discounted.json +147 -0
  49. otaghak_mcp-0.1.0/tests/fixtures/search_filters.json +515 -0
  50. otaghak_mcp-0.1.0/tests/fixtures/search_rooms.json +112 -0
  51. otaghak_mcp-0.1.0/tests/fixtures/search_rooms_undated.json +77 -0
  52. otaghak_mcp-0.1.0/tests/fixtures/similar.json +180 -0
  53. otaghak_mcp-0.1.0/tests/fixtures/similar_search.json +147 -0
  54. otaghak_mcp-0.1.0/tests/fixtures/terms.json +13 -0
  55. otaghak_mcp-0.1.0/tests/test_info.py +101 -0
  56. otaghak_mcp-0.1.0/tests/test_live_info.py +14 -0
  57. otaghak_mcp-0.1.0/tests/test_live_pricing.py +44 -0
  58. otaghak_mcp-0.1.0/tests/test_live_room.py +36 -0
  59. otaghak_mcp-0.1.0/tests/test_live_search.py +43 -0
  60. otaghak_mcp-0.1.0/tests/test_pricing.py +213 -0
  61. otaghak_mcp-0.1.0/tests/test_room.py +207 -0
  62. otaghak_mcp-0.1.0/tests/test_search.py +268 -0
  63. otaghak_mcp-0.1.0/tests/test_server.py +13 -0
  64. 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"
@@ -0,0 +1,5 @@
1
+ blank_issues_enabled: true
2
+ contact_links:
3
+ - name: Question or idea
4
+ url: https://github.com/sepehr071/otaghak-mcp/discussions
5
+ about: Ask how to use it or suggest a new tool
Binary file
@@ -0,0 +1,10 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: github-actions
4
+ directory: /
5
+ schedule:
6
+ interval: monthly
7
+ - package-ecosystem: uv
8
+ directory: /
9
+ schedule:
10
+ interval: monthly
@@ -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,6 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ dist/
5
+ .pytest_cache/
6
+ .ruff_cache/
@@ -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
+ [![PyPI](https://img.shields.io/pypi/v/otaghak-mcp?color=2563eb)](https://pypi.org/project/otaghak-mcp/)
40
+ [![Python](https://img.shields.io/pypi/pyversions/otaghak-mcp)](https://pypi.org/project/otaghak-mcp/)
41
+ [![CI](https://github.com/sepehr071/otaghak-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sepehr071/otaghak-mcp/actions/workflows/ci.yml)
42
+ [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.sepehr071%2Fotaghak--mcp-7c3aed)](https://registry.modelcontextprotocol.io/?q=otaghak-mcp)
43
+ [![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/otaghak-mcp/blob/main/LICENSE)
44
+
45
+ [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=otaghak&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJvdGFnaGFrLW1jcCJdfQ==)
46
+ [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_otaghak--mcp-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](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 و ...) اجازه می&zwnj;دهد در اتاقک ویلا، کلبه و
279
+ آپارتمان جستجو کند، شب&zwnj;های خالی را ببیند، مبلغ دقیق اقامت را برای تاریخ و تعداد نفرات شما حساب کند و نظرات و
280
+ وضعیت میزبان را بخواند.
281
+
282
+ - فقط خواندنی است: وارد حساب نمی&zwnj;شود، رزرو و پرداخت نمی&zwnj;کند و کد پیامکی نمی&zwnj;فرستد.
283
+ - مبلغ نهایی را با قیمت تک&zwnj;تک شب&zwnj;ها، هزینه نفر اضافه و تأخیر در تخلیه حساب می&zwnj;کند.
284
+ - همه قیمت&zwnj;ها به تومان است و تاریخ&zwnj;ها میلادی (YYYY-MM-DD) هستند.
285
+ - روی سیستم خود شما اجرا می&zwnj;شود و به هیچ سرور واسطی داده نمی&zwnj;فرستد.
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
+ بعد بپرسید: «ارزان&zwnj;ترین ویلای استخردار رامسر برای ۶ نفر از ۲۰ تا ۲۳ اکتبر چند تمام می&zwnj;شود؟»
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)