flytoday-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 (85) hide show
  1. flytoday_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +42 -0
  2. flytoday_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
  3. flytoday_mcp-0.1.0/.github/banner.png +0 -0
  4. flytoday_mcp-0.1.0/.github/dependabot.yml +10 -0
  5. flytoday_mcp-0.1.0/.github/workflows/ci.yml +22 -0
  6. flytoday_mcp-0.1.0/.github/workflows/publish.yml +51 -0
  7. flytoday_mcp-0.1.0/.gitignore +6 -0
  8. flytoday_mcp-0.1.0/LICENSE +21 -0
  9. flytoday_mcp-0.1.0/PKG-INFO +348 -0
  10. flytoday_mcp-0.1.0/README.md +322 -0
  11. flytoday_mcp-0.1.0/pyproject.toml +54 -0
  12. flytoday_mcp-0.1.0/server.json +32 -0
  13. flytoday_mcp-0.1.0/src/flytoday_mcp/__init__.py +5 -0
  14. flytoday_mcp-0.1.0/src/flytoday_mcp/buses.py +134 -0
  15. flytoday_mcp-0.1.0/src/flytoday_mcp/extras.py +496 -0
  16. flytoday_mcp-0.1.0/src/flytoday_mcp/flights.py +401 -0
  17. flytoday_mcp-0.1.0/src/flytoday_mcp/hotels.py +718 -0
  18. flytoday_mcp-0.1.0/src/flytoday_mcp/http.py +172 -0
  19. flytoday_mcp-0.1.0/src/flytoday_mcp/registry.py +16 -0
  20. flytoday_mcp-0.1.0/src/flytoday_mcp/server.py +61 -0
  21. flytoday_mcp-0.1.0/src/flytoday_mcp/trains.py +207 -0
  22. flytoday_mcp-0.1.0/tests/conftest.py +87 -0
  23. flytoday_mcp-0.1.0/tests/fixtures/buses_calendar.json +52 -0
  24. flytoday_mcp-0.1.0/tests/fixtures/buses_cities.json +66 -0
  25. flytoday_mcp-0.1.0/tests/fixtures/buses_popular.json +90 -0
  26. flytoday_mcp-0.1.0/tests/fixtures/buses_search.json +451 -0
  27. flytoday_mcp-0.1.0/tests/fixtures/extras_activity_content.json +460 -0
  28. flytoday_mcp-0.1.0/tests/fixtures/extras_activity_details.json +583 -0
  29. flytoday_mcp-0.1.0/tests/fixtures/extras_activity_locations.json +844 -0
  30. flytoday_mcp-0.1.0/tests/fixtures/extras_activity_prices.json +413 -0
  31. flytoday_mcp-0.1.0/tests/fixtures/extras_activity_regions.json +86 -0
  32. flytoday_mcp-0.1.0/tests/fixtures/extras_cip_airports.json +49 -0
  33. flytoday_mcp-0.1.0/tests/fixtures/extras_cip_search.json +530 -0
  34. flytoday_mcp-0.1.0/tests/fixtures/extras_esim_geo.json +324 -0
  35. flytoday_mcp-0.1.0/tests/fixtures/extras_esim_search.json +329 -0
  36. flytoday_mcp-0.1.0/tests/fixtures/extras_visa_detail.json +292 -0
  37. flytoday_mcp-0.1.0/tests/fixtures/extras_visa_search.json +300 -0
  38. flytoday_mcp-0.1.0/tests/fixtures/flights_baggages_dom.json +1 -0
  39. flytoday_mcp-0.1.0/tests/fixtures/flights_baggages_intl.json +1 -0
  40. flytoday_mcp-0.1.0/tests/fixtures/flights_calendar.json +1 -0
  41. flytoday_mcp-0.1.0/tests/fixtures/flights_farerules_dom.json +1 -0
  42. flytoday_mcp-0.1.0/tests/fixtures/flights_farerules_intl.json +1 -0
  43. flytoday_mcp-0.1.0/tests/fixtures/flights_locations.json +1 -0
  44. flytoday_mcp-0.1.0/tests/fixtures/flights_popular_dom.json +1 -0
  45. flytoday_mcp-0.1.0/tests/fixtures/flights_popular_intl.json +1 -0
  46. flytoday_mcp-0.1.0/tests/fixtures/flights_restriction.json +1 -0
  47. flytoday_mcp-0.1.0/tests/fixtures/flights_rt_back.json +1 -0
  48. flytoday_mcp-0.1.0/tests/fixtures/flights_rt_out.json +1 -0
  49. flytoday_mcp-0.1.0/tests/fixtures/flights_search.json +1 -0
  50. flytoday_mcp-0.1.0/tests/fixtures/flights_search_party.json +1 -0
  51. flytoday_mcp-0.1.0/tests/fixtures/hotels_info.json +1 -0
  52. flytoday_mcp-0.1.0/tests/fixtures/hotels_info_foreign.json +1 -0
  53. flytoday_mcp-0.1.0/tests/fixtures/hotels_one.json +1 -0
  54. flytoday_mcp-0.1.0/tests/fixtures/hotels_place.json +1 -0
  55. flytoday_mcp-0.1.0/tests/fixtures/hotels_place_intl.json +1 -0
  56. flytoday_mcp-0.1.0/tests/fixtures/hotels_popular.json +1 -0
  57. flytoday_mcp-0.1.0/tests/fixtures/hotels_portfolio.json +1 -0
  58. flytoday_mcp-0.1.0/tests/fixtures/hotels_portfolio_foreign.json +41 -0
  59. flytoday_mcp-0.1.0/tests/fixtures/hotels_reviews.json +1 -0
  60. flytoday_mcp-0.1.0/tests/fixtures/hotels_roominfo.json +1 -0
  61. flytoday_mcp-0.1.0/tests/fixtures/hotels_search.json +1 -0
  62. flytoday_mcp-0.1.0/tests/fixtures/hotels_smart.json +1 -0
  63. flytoday_mcp-0.1.0/tests/fixtures/hotels_stay_calendar.json +1 -0
  64. flytoday_mcp-0.1.0/tests/fixtures/hotels_stay_info.json +1 -0
  65. flytoday_mcp-0.1.0/tests/fixtures/hotels_stay_popular.json +1 -0
  66. flytoday_mcp-0.1.0/tests/fixtures/hotels_stay_reviews.json +1 -0
  67. flytoday_mcp-0.1.0/tests/fixtures/hotels_stays.json +1 -0
  68. flytoday_mcp-0.1.0/tests/fixtures/trains_fare_lookup.json +1005 -0
  69. flytoday_mcp-0.1.0/tests/fixtures/trains_popular.json +54 -0
  70. flytoday_mcp-0.1.0/tests/fixtures/trains_search.json +340 -0
  71. flytoday_mcp-0.1.0/tests/fixtures/trains_stations.json +36 -0
  72. flytoday_mcp-0.1.0/tests/fixtures/trains_stops.json +40 -0
  73. flytoday_mcp-0.1.0/tests/fixtures/trains_wagon.json +61 -0
  74. flytoday_mcp-0.1.0/tests/test_buses.py +76 -0
  75. flytoday_mcp-0.1.0/tests/test_extras.py +246 -0
  76. flytoday_mcp-0.1.0/tests/test_flights.py +243 -0
  77. flytoday_mcp-0.1.0/tests/test_hotels.py +327 -0
  78. flytoday_mcp-0.1.0/tests/test_http.py +63 -0
  79. flytoday_mcp-0.1.0/tests/test_live_buses.py +24 -0
  80. flytoday_mcp-0.1.0/tests/test_live_extras.py +31 -0
  81. flytoday_mcp-0.1.0/tests/test_live_flights.py +30 -0
  82. flytoday_mcp-0.1.0/tests/test_live_hotels.py +63 -0
  83. flytoday_mcp-0.1.0/tests/test_live_trains.py +33 -0
  84. flytoday_mcp-0.1.0/tests/test_trains.py +110 -0
  85. flytoday_mcp-0.1.0/uv.lock +1124 -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. ft_search_flights
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 flytoday.ir for the same route, date and passengers
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
+ - FLYTODAY_MCP_PROXY set
38
+ - type: input
39
+ id: version
40
+ attributes:
41
+ label: flytoday-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/flytoday-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/flytoday-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,348 @@
1
+ Metadata-Version: 2.5
2
+ Name: flytoday-mcp
3
+ Version: 0.1.0
4
+ Summary: Unofficial read-only MCP server for Flytoday: cheapest domestic and international flights, hotels, stays, trains and buses in Iran, with fare rules and exact prices.
5
+ Project-URL: Homepage, https://github.com/sepehr071/flytoday-mcp
6
+ Project-URL: Source, https://github.com/sepehr071/flytoday-mcp
7
+ Project-URL: Changelog, https://github.com/sepehr071/flytoday-mcp/releases
8
+ Project-URL: Issues, https://github.com/sepehr071/flytoday-mcp/issues
9
+ Author-email: Sepehr <sepehr@nextofx.com>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: bus,flights,flytoday,hotel,iran,mcp,model-context-protocol,train,travel
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/flytoday-mcp -->
28
+
29
+ <div align="center">
30
+
31
+ <img src="https://raw.githubusercontent.com/sepehr071/flytoday-mcp/main/.github/banner.png" alt="flytoday-mcp: let your AI agent find the cheapest flight, train or hotel in Iran" width="100%">
32
+
33
+ # ✈️ flytoday-mcp
34
+
35
+ **Let your AI agent plan trips with Flytoday.**<br>
36
+ Find the cheapest domestic or international flight, train or bus on a date or over a month, read fare rules and baggage,<br>
37
+ compare hotels and villas with exact prices, and price CIP lounges, eSIMs and visas, all from Claude, Cursor or Copilot.
38
+
39
+ [![PyPI](https://img.shields.io/pypi/v/flytoday-mcp?color=2563eb)](https://pypi.org/project/flytoday-mcp/)
40
+ [![Python](https://img.shields.io/pypi/pyversions/flytoday-mcp)](https://pypi.org/project/flytoday-mcp/)
41
+ [![CI](https://github.com/sepehr071/flytoday-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sepehr071/flytoday-mcp/actions/workflows/ci.yml)
42
+ [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.sepehr071%2Fflytoday--mcp-7c3aed)](https://registry.modelcontextprotocol.io/?q=flytoday-mcp)
43
+ [![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/flytoday-mcp/blob/main/LICENSE)
44
+
45
+ [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=flytoday&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJmbHl0b2RheS1tY3AiXX0=)
46
+ [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_flytoday--mcp-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=flytoday&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22flytoday-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
+ Flytoday (flytoday.ir, فلای تودی) sells domestic and international flights, hotels, villas, trains, buses, CIP
57
+ lounges, eSIMs and visas. Comparing "which day, plane or train or bus, which hotel" still means many page loads.
58
+ An agent with `flytoday-mcp` does it in one go:
59
+
60
+ > **You:** Cheapest way from Tehran to Mashhad around 20 October?
61
+ >
62
+ > **Agent:** *calls* `ft_flight_calendar(origin="THR", destination="MHD", date="2026-10-21", window="week")`,
63
+ > `ft_train_calendar(origin="1", destination="191")`
64
+ >
65
+ > | Mode | Cheapest day | Price (Toman) |
66
+ > |---|---|---|
67
+ > | Flight | 2026-10-20, airline IRZ | 11,056,700 |
68
+ > | Train | 2026-10-20 (and most days that week) | **760,000** |
69
+ >
70
+ > The train is far cheaper; want me to list that day's trains with `ft_search_trains`?
71
+
72
+ <sub>Real tool output from 2026-10-07; prices and seats change all the time. Prices are in Toman.</sub>
73
+
74
+ ## What it can do
75
+
76
+ - ✈️ **Flights**: domestic and international, one-way or round trip, party prices, airline, direct, charter/system and time filters
77
+ - 📅 **Cheapest day** for flights (+-15 days), trains (~16 days) and buses (~6 weeks)
78
+ - 📜 **Fare details**: refund and change rules, baggage, international entry notes
79
+ - 🏨 **Hotels** in Iran and abroad: priced search, room and meal offers with cancellation terms, guest reviews
80
+ - 🏡 **Villas and apartments** in Iran: price per night and total, per-date calendar with blocked days
81
+ - 🚆🚌 **Trains and buses**: classes, seats left, stops, amenities, VIP and sleeper buses
82
+ - 🛂 **Extras**: CIP lounges at IKA and MHD, eSIM data plans per country, visa prices and documents, tours and tickets
83
+ - 🔒 **Read-only by design**: no login, no seat hold, no booking, no payment
84
+
85
+ ## Quick start
86
+
87
+ You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
88
+
89
+ <details open>
90
+ <summary><b>Claude Code</b></summary>
91
+
92
+ ```bash
93
+ claude mcp add flytoday -- uvx flytoday-mcp
94
+ ```
95
+
96
+ If Flytoday does not answer from your network, add a proxy:
97
+
98
+ ```bash
99
+ claude mcp add flytoday -e FLYTODAY_MCP_PROXY=http://127.0.0.1:8080 -- uvx flytoday-mcp
100
+ ```
101
+ </details>
102
+
103
+ <details>
104
+ <summary><b>Claude Desktop</b></summary>
105
+
106
+ Settings → Developer → Edit Config, then add:
107
+
108
+ ```json
109
+ {
110
+ "mcpServers": {
111
+ "flytoday": { "command": "uvx", "args": ["flytoday-mcp"] }
112
+ }
113
+ }
114
+ ```
115
+
116
+ Need a proxy? Add `"env": { "FLYTODAY_MCP_PROXY": "http://127.0.0.1:8080" }` next to `args`.
117
+ </details>
118
+
119
+ <details>
120
+ <summary><b>Cursor</b></summary>
121
+
122
+ Click **Install in Cursor** above, or add the Claude Desktop block to `~/.cursor/mcp.json`.
123
+ </details>
124
+
125
+ <details>
126
+ <summary><b>VS Code (Copilot agent mode)</b></summary>
127
+
128
+ Click **Install in VS Code** above, or add to `.vscode/mcp.json`:
129
+
130
+ ```json
131
+ {
132
+ "servers": {
133
+ "flytoday": { "type": "stdio", "command": "uvx", "args": ["flytoday-mcp"] }
134
+ }
135
+ }
136
+ ```
137
+ </details>
138
+
139
+ <details>
140
+ <summary><b>Anything else</b></summary>
141
+
142
+ It's a standard stdio MCP server: run `uvx flytoday-mcp`, or `pip install flytoday-mcp` and run `flytoday-mcp`.
143
+ </details>
144
+
145
+ Then just ask:
146
+
147
+ - "Cheapest day to fly Tehran to Istanbul next month, and the refund rules of that fare?"
148
+ - "Hotels in Mashhad for 2 nights from the 21st, cheapest first, with free cancellation."
149
+ - "A villa in Ramsar for 4 people next weekend under 5 million Toman a night."
150
+ - <span dir="rtl">ارزان&zwnj;ترین اتوبوس VIP تهران به اصفهان دوشنبه بعد؟</span>
151
+
152
+ ## How it works
153
+
154
+ ```text
155
+ AI agent (Claude, Cursor, Copilot, ...)
156
+ │
157
+ │ MCP over stdio
158
+ ▼
159
+ flytoday-mcp (runs on your machine)
160
+ │
161
+ │ HTTPS (optional proxy)
162
+ ▼
163
+ www.flytoday.ir/api/gateway ──▶ api.flytoday.ir, placesearch.flytoday.ir
164
+ ```
165
+
166
+ `flytoday-mcp` runs locally and calls the same public gateway the flytoday.ir website uses. There's no hosted
167
+ server in between, no API key, and nothing about you is sent anywhere else.
168
+
169
+ ## Tools
170
+
171
+ Each vertical has its own ids, taken from its find tool: IATA codes for flights (`THR`, `MHD`, `IST`), hotel
172
+ `city_id` / `region_code`, stay `region_code`, train station codes (Tehran `1`, Mashhad `191`), 4-digit bus city
173
+ ids (Tehran `0001`, Isfahan `0002`).
174
+
175
+ <details open>
176
+ <summary><b>✈️ Flights</b> (4)</summary>
177
+
178
+ | Tool | What it does |
179
+ |---|---|
180
+ | `ft_find_airport` | Finds IATA codes for Iranian and international cities and airports, or lists the popular ones |
181
+ | `ft_search_flights` | Searches one-way or round-trip flights with filters, sorting and paging, in Toman, with fare_source_code and search_id |
182
+ | `ft_flight_calendar` | Shows the cheapest fare per departure day around a date and marks the cheapest day |
183
+ | `ft_flight_details` | Gives the refund and change rules, baggage and international entry notes of one fare |
184
+ </details>
185
+
186
+ <details open>
187
+ <summary><b>🏨 Hotels and stays</b> (6)</summary>
188
+
189
+ | Tool | What it does |
190
+ |---|---|
191
+ | `ft_find_hotel_place` | Find city, region and hotel ids for hotels, and region codes for villa stays; popular places when empty |
192
+ | `ft_search_hotels` | Priced hotels of a city or region for dates: whole-stay and per-night Toman, stars, score, refundable, meal |
193
+ | `ft_hotel` | One hotel: room and meal offers with price, rooms left and cancellation terms, room details, basics |
194
+ | `ft_hotel_reviews` | Guest reviews of a hotel with score, text, pros and cons |
195
+ | `ft_search_stays` | Villas and apartments in Iran for dates, cheapest first, Toman per night and total |
196
+ | `ft_stay` | One villa or apartment: details, price calendar with blocked days, reviews |
197
+ </details>
198
+
199
+ <details open>
200
+ <summary><b>🚆 Trains</b> (4)</summary>
201
+
202
+ | Tool | What it does |
203
+ |---|---|
204
+ | `ft_find_station` | Train station codes by city name, or the popular stations |
205
+ | `ft_search_trains` | Trains between two stations on a date: company, class, times, seats left, price per adult |
206
+ | `ft_train_calendar` | Cheapest train price per day for the next ~16 days, sold-out days flagged |
207
+ | `ft_train_stops` | Stops and times of one train, plus class amenities and meals |
208
+ </details>
209
+
210
+ <details open>
211
+ <summary><b>🚌 Buses</b> (3)</summary>
212
+
213
+ | Tool | What it does |
214
+ |---|---|
215
+ | `ft_find_bus_city` | Bus city ids by name, or the popular cities |
216
+ | `ft_bus_calendar` | Cheapest bus seat price per day for the next weeks (the site's price strip) |
217
+ | `ft_search_buses` | Buses between two cities on a date: company, terminals, type, seats left, price per seat |
218
+ </details>
219
+
220
+ <details open>
221
+ <summary><b>🛂 CIP, eSIM, visa, activities</b> (5)</summary>
222
+
223
+ | Tool | What it does |
224
+ |---|---|
225
+ | `ft_cip` | CIP / VIP airport lounge prices and add-ons at IKA and MHD for a date and passengers, per passport nationality |
226
+ | `ft_esim_plans` | eSIM data plans for a country (GB, days, price in Toman), cheapest first |
227
+ | `ft_visa` | Visa country list with from-prices, or one country's prices, documents and processing time |
228
+ | `ft_activities` | Tours, tickets and activities in a destination with from-prices for a date range |
229
+ | `ft_activity` | One activity: description, options, prices and cheapest days |
230
+ </details>
231
+
232
+ All 22 tools are annotated `readOnlyHint: true` and return compact structured JSON, so they don't flood the agent's context.
233
+
234
+ ## Good to know
235
+
236
+ - **Prices are in Toman** in every tool, in fields named `*_toman` (the API sends Rial; values are divided by 10).
237
+ Flight `price_toman` is per adult and `total_toman` the whole party; hotel `price_toman` is the whole stay (with
238
+ `per_night_toman`); stays give `price_per_night_toman` and `total_toman`; trains per adult; buses per seat.
239
+ Visa and some activity prices are in a foreign currency (`price_currency`).
240
+ - **Dates** in and out are Gregorian `YYYY-MM-DD`; past dates are rejected. Times are local to the place.
241
+ - **Searches are rate limited per IP** by Flytoday: about 15 flight/train/bus searches, and hotel search asks for a
242
+ captcha after about 12 searches in 10 minutes (blocked for an hour or more). Use the calendars and paging
243
+ (`search_id`) instead of searching again; the tools never loop searches.
244
+ - **Ids expire**: `search_id` and `fare_source_code` are valid for about 15 minutes.
245
+ - **Sales windows**: trains open about 16 days ahead. An empty result often just means "not on sale yet".
246
+ - When the rail companies' link is down, Flytoday answers HTTP 599; `ft_search_trains` retries three times, then says so.
247
+
248
+ ## FAQ
249
+
250
+ <details>
251
+ <summary><b>Do I need a proxy?</b></summary>
252
+
253
+ Usually not: the website's gateway answers from Iran and from abroad. If your network cannot reach
254
+ www.flytoday.ir, or your IP is rate limited, set `FLYTODAY_MCP_PROXY` to an HTTP proxy. System proxy variables
255
+ (`HTTPS_PROXY`, ...) are ignored on purpose.
256
+ </details>
257
+
258
+ <details>
259
+ <summary><b>Can it book a ticket for me?</b></summary>
260
+
261
+ No, and that's deliberate. It has no login and never holds a seat, reserves, orders or pays. The agent finds the
262
+ best option; you book on flytoday.ir.
263
+ </details>
264
+
265
+ <details>
266
+ <summary><b>I get "wants a captcha" or HTTP 429</b></summary>
267
+
268
+ Flytoday limits searches per IP. Wait (the hotel captcha block can last an hour or more) or use another network
269
+ through `FLYTODAY_MCP_PROXY`. Calendars, details, reviews and stay searches are not limited.
270
+ </details>
271
+
272
+ <details>
273
+ <summary><b>Why is there no bus seat map?</b></summary>
274
+
275
+ The site's seat map comes from the first call of its checkout flow. It is left out until it is clear that the call
276
+ holds nothing.
277
+ </details>
278
+
279
+ <details>
280
+ <summary><b>How do I debug what the agent sees?</b></summary>
281
+
282
+ ```bash
283
+ npx @modelcontextprotocol/inspector uvx flytoday-mcp
284
+ ```
285
+ </details>
286
+
287
+ ## Configuration
288
+
289
+ | Variable | Default | Meaning |
290
+ |---|---|---|
291
+ | `FLYTODAY_MCP_PROXY` | unset | HTTP proxy for every request, e.g. `http://user:pass@host:port` |
292
+
293
+ ## Safety
294
+
295
+ - Read-only: no login or OTP, no seat hold, reservation, order, payment, refund, review or bookmark.
296
+ The only POSTs are searches and price lookups the site itself makes before booking.
297
+ - At most two requests at a time, and no tool repeats a search in a loop.
298
+
299
+ ## فارسی
300
+
301
+ <div dir="rtl">
302
+
303
+ **flytoday-mcp** به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می&zwnj;دهد در فلای&zwnj;تودی ارزان&zwnj;ترین
304
+ پرواز داخلی و خارجی، قطار یا اتوبوس را برای یک روز یا یک ماه پیدا کند، قوانین استرداد و بار مجاز را ببیند
305
+ و هتل&zwnj;ها و ویلاها را با قیمت دقیق مقایسه کند؛ همچنین قیمت CIP، سیم&zwnj;کارت eSIM و ویزا را می&zwnj;گوید.
306
+
307
+ - فقط خواندنی است: وارد حساب نمی&zwnj;شود و چیزی رزرو یا پرداخت نمی&zwnj;کند.
308
+ - همه قیمت&zwnj;ها به تومان است.
309
+ - روی سیستم خود شما اجرا می&zwnj;شود و به هیچ سرور واسطی داده نمی&zwnj;فرستد.
310
+
311
+ **نصب در Claude Code:**
312
+
313
+ </div>
314
+
315
+ ```bash
316
+ claude mcp add flytoday -- uvx flytoday-mcp
317
+ ```
318
+
319
+ <div dir="rtl">
320
+
321
+ بعد بپرسید: «ارزان&zwnj;ترین راه رفتن از تهران به مشهد حدود ۲۸ مهر چیست؟»
322
+
323
+ </div>
324
+
325
+ ## Development
326
+
327
+ ```bash
328
+ git clone https://github.com/sepehr071/flytoday-mcp && cd flytoday-mcp
329
+ uv sync
330
+ uv run pytest # offline, against recorded responses
331
+ uv run pytest -m live # real API, one search per tool (set FLYTODAY_MCP_PROXY if needed)
332
+ uv run ruff check .
333
+ ```
334
+
335
+ Tools live in `src/flytoday_mcp/flights.py`, `hotels.py`, `trains.py`, `buses.py` and `extras.py`; each is a typed
336
+ async function with a docstring that tells the agent when to use it. Issues and PRs are welcome.
337
+
338
+ Releases: bump the version in `pyproject.toml` and `server.json`, then push a `v*` tag. GitHub Actions tests,
339
+ publishes to PyPI and the [MCP Registry](https://registry.modelcontextprotocol.io), and creates the GitHub Release.
340
+
341
+ ## Disclaimer
342
+
343
+ Unofficial and not affiliated with or endorsed by Flytoday. It uses the public endpoints of the flytoday.ir website,
344
+ which can change without notice. Please keep request rates reasonable.
345
+
346
+ ## License
347
+
348
+ [MIT](https://github.com/sepehr071/flytoday-mcp/blob/main/LICENSE)