rzd-api 1.0.0__py3-none-any.whl

mcp_server/server.py

@@ -0,0 +1,204 @@
+"""
+MCP Server for RZD (Russian Railways) API.
+
+Exposes rzd_api as MCP tools so any MCP-compatible client (Claude, etc.)
+can search train routes, carriages, and station codes.
+
+Transport is configured via environment variables:
+  MCP_TRANSPORT  — stdio (default) | sse | streamable-http
+  MCP_HOST       — bind host for HTTP transports (default: 0.0.0.0)
+  MCP_PORT       — bind port for HTTP transports (default: 8000)
+"""
+
+import os
+import sys
+
+from rzd_api import Api
+
+mcp = None
+
+_api: Api | None = None
+
+
+def get_api() -> Api:
+    global _api
+    if _api is None:
+        _api = Api()
+    return _api
+
+
+def train_routes(
+    code0: str,
+    code1: str,
+    dt0: str,
+    dir: int = 0,
+    tfl: int = 3,
+    check_seats: int = 1,
+    md: int = 0,
+) -> str:
+    """Get one-way train routes with available seats and prices.
+
+    Args:
+        code0: Origin station code (e.g. '2004000' for Saint Petersburg).
+        code1: Destination station code (e.g. '2000000' for Moscow).
+        dt0: Departure date in format dd.mm.yyyy.
+        dir: Direction — 0 one-way (default).
+        tfl: Train type: 1 = trains only, 2 = electric trains only, 3 = both (default).
+        check_seats: 1 = only trains with seats (default), 0 = all trains.
+        md: 0 = direct routes only (default), 1 = with transfers.
+
+    Returns:
+        JSON array of train objects with seats and pricing info.
+    """
+    params = {
+        'code0': code0,
+        'code1': code1,
+        'dt0': dt0,
+        'dir': dir,
+        'tfl': tfl,
+        'checkSeats': check_seats,
+        'md': md,
+    }
+    return get_api().train_routes(params)
+
+
+def train_routes_return(
+    code0: str,
+    code1: str,
+    dt0: str,
+    dt1: str,
+    tfl: int = 3,
+    check_seats: int = 1,
+) -> str:
+    """Get round-trip train routes (forward + back legs).
+
+    Args:
+        code0: Origin station code (e.g. '2004000' for Saint Petersburg).
+        code1: Destination station code (e.g. '2000000' for Moscow).
+        dt0: Departure date in format dd.mm.yyyy.
+        dt1: Return date in format dd.mm.yyyy.
+        tfl: Train type: 1 = trains only, 2 = electric trains only, 3 = both (default).
+        check_seats: 1 = only trains with seats (default), 0 = all trains.
+
+    Returns:
+        JSON object with 'forward' and 'back' arrays of train objects.
+    """
+    params = {
+        'code0': code0,
+        'code1': code1,
+        'dt0': dt0,
+        'dt1': dt1,
+        'dir': 1,
+        'tfl': tfl,
+        'checkSeats': check_seats,
+    }
+    return get_api().train_routes_return(params)
+
+
+def train_carriages(
+    code0: str,
+    code1: str,
+    dt0: str,
+    time0: str,
+    tnum0: str,
+    dir: int = 0,
+) -> str:
+    """Get detailed carriage and seat information for a specific train.
+
+    Args:
+        code0: Origin station code.
+        code1: Destination station code.
+        dt0: Departure date in format dd.mm.yyyy.
+        time0: Departure time in format HH:MM.
+        tnum0: Train number (e.g. '054Г').
+        dir: Direction — 0 one-way (default).
+
+    Returns:
+        JSON object with 'cars', 'functionBlocks', 'schemes', and 'companies'.
+    """
+    params = {
+        'code0': code0,
+        'code1': code1,
+        'dt0': dt0,
+        'time0': time0,
+        'tnum0': tnum0,
+        'dir': dir,
+    }
+    return get_api().train_carriages(params)
+
+
+def train_station_list(
+    train_number: str,
+    dep_date: str,
+) -> str:
+    """Get all stations on a train's route with arrival/departure times and distances.
+
+    Args:
+        train_number: Train number (e.g. '054Г').
+        dep_date: Departure date in format dd.mm.yyyy.
+
+    Returns:
+        JSON object with 'train' info and 'routes' array of station objects.
+    """
+    params = {
+        'trainNumber': train_number,
+        'depDate': dep_date,
+    }
+    return get_api().train_station_list(params)
+
+
+def station_code(
+    station_name_part: str,
+    compact_mode: str = 'y',
+) -> str:
+    """Search for station codes by partial station name (in Russian).
+
+    Args:
+        station_name_part: Part of the station name (min 2 characters, e.g. 'ЧЕБ').
+        compact_mode: Response format, default 'y'.
+
+    Returns:
+        JSON array of objects with 'station' name and 'code' fields.
+    """
+    params = {
+        'stationNamePart': station_name_part,
+        'compactMode': compact_mode,
+    }
+    return get_api().station_code(params)
+
+
+def create_mcp_app():
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError as exc:
+        raise RuntimeError(
+            "MCP support is not installed. Install it with: pip install 'rzd-api[mcp]'"
+        ) from exc
+
+    app = FastMCP("RZD API")
+    app.tool()(train_routes)
+    app.tool()(train_routes_return)
+    app.tool()(train_carriages)
+    app.tool()(train_station_list)
+    app.tool()(station_code)
+    return app
+
+
+def main() -> None:
+    try:
+        app = create_mcp_app()
+    except RuntimeError as exc:
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(1) from exc
+
+    transport = os.getenv('MCP_TRANSPORT', 'stdio')
+    if transport in ('sse', 'streamable-http'):
+        host = os.getenv('MCP_HOST', '0.0.0.0')
+        port = int(os.getenv('MCP_PORT', '8000'))
+        app.run(transport=transport, host=host, port=port)
+    else:
+        app.run(transport='stdio')
+
+
+if __name__ == '__main__':
+    main()

rzd_api/__init__.py

@@ -0,0 +1,6 @@
+from .api import Api
+from .client import RzdClient
+from .config import Config
+from .query import Query, RzdException
+
+__all__ = ['Api', 'RzdClient', 'Config', 'Query', 'RzdException']

rzd_api/api.py

@@ -0,0 +1,95 @@
+import json
+
+from .config import Config
+from .query import Query
+
+
+class Api:
+    ROUTES_LAYER = 5827
+    CARRIAGES_LAYER = 5764
+    STATIONS_STRUCTURE_ID = 704
+
+    def __init__(self, config: Config = None):
+        if config is None:
+            config = Config()
+
+        self.lang = config.language
+        self.path = f'https://pass.rzd.ru/timetable/public/{self.lang}'
+        self.suggestion_path = 'https://pass.rzd.ru/suggester'
+        self.station_list_path = 'https://pass.rzd.ru/ticket/services/route/basicRoute'
+        self.query = Query(config)
+
+    def train_routes_data(self, params: dict) -> list[dict]:
+        """Получает маршруты в одну точку как Python-объект."""
+        layer = {'layer_id': self.ROUTES_LAYER}
+        routes = self.query.get(self.path, {**layer, **params})
+        return routes['tp'][0]['list']
+
+    def train_routes(self, params: dict) -> str:
+        """Получает маршруты в одну точку (one-way routes)."""
+        return json.dumps(self.train_routes_data(params), ensure_ascii=False)
+
+    def train_routes_return_data(self, params: dict) -> dict[str, list[dict]]:
+        """Получает маршруты туда-обратно как Python-объект."""
+        layer = {'layer_id': self.ROUTES_LAYER}
+        routes = self.query.get(self.path, {**layer, **params})
+        return {
+            'forward': routes['tp'][0]['list'],
+            'back': routes['tp'][1]['list'],
+        }
+
+    def train_routes_return(self, params: dict) -> str:
+        """Получает маршруты туда-обратно (round-trip routes)."""
+        return json.dumps(self.train_routes_return_data(params), ensure_ascii=False)
+
+    def train_carriages_data(self, params: dict) -> dict:
+        """Получение списка вагонов как Python-объект."""
+        layer = {'layer_id': self.CARRIAGES_LAYER}
+        carriages = self.query.get(self.path, {**layer, **params})
+        lst = carriages.get('lst', [{}])
+        return {
+            'cars': lst[0].get('cars') if lst else None,
+            'functionBlocks': lst[0].get('functionBlocks') if lst else None,
+            'schemes': carriages.get('schemes'),
+            'companies': carriages.get('insuranceCompany'),
+        }
+
+    def train_carriages(self, params: dict) -> str:
+        """Получение списка вагонов (carriages/cars for a specific train)."""
+        return json.dumps(self.train_carriages_data(params), ensure_ascii=False)
+
+    def train_station_list_data(self, params: dict) -> dict:
+        """Получение списка станций маршрута как Python-объект."""
+        layer = {'STRUCTURE_ID': self.STATIONS_STRUCTURE_ID}
+        stations = self.query.get(self.station_list_path, {**layer, **params})
+        return {
+            'train': stations['data']['trainInfo'],
+            'routes': stations['data']['routes'],
+        }
+
+    def train_station_list(self, params: dict) -> str:
+        """Получение списка станций маршрута (all stations on a train's route)."""
+        return json.dumps(self.train_station_list_data(params), ensure_ascii=False)
+
+    def station_code_data(self, params: dict) -> list[dict]:
+        """Получение кодов станций по части названия как Python-объект."""
+        query_params = {'lang': self.lang, **params}
+        routes = self.query.get(self.suggestion_path, query_params, method='GET')
+
+        stations = []
+        station_name_part = params.get('stationNamePart', '').upper()
+
+        if routes:
+            for station in routes:
+                name = station.get('n', '')
+                if station_name_part in name.upper():
+                    stations.append({
+                        'station': name,
+                        'code': station.get('c'),
+                    })
+
+        return stations
+
+    def station_code(self, params: dict) -> str:
+        """Получение кодов станций по части названия (search stations by partial name)."""
+        return json.dumps(self.station_code_data(params), ensure_ascii=False)

rzd_api/client.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Any
+
+from .api import Api
+from .config import Config
+from .query import RzdException
+
+
+class RzdClient:
+    """High-level client for using the package as a Python library."""
+
+    TRANSPORT_TYPES = {
+        'trains': 1,
+        'suburban': 2,
+        'all': 3,
+    }
+
+    def __init__(self, config: Config | None = None, api: Api | None = None):
+        self.api = api or Api(config)
+
+    def search_tickets(
+        self,
+        from_station: str | int,
+        to_station: str | int,
+        departure_date: str | date | datetime,
+        return_date: str | date | datetime | None = None,
+        *,
+        only_with_seats: bool = True,
+        include_transfers: bool = False,
+        transport_type: str = 'all',
+    ) -> list[dict[str, Any]] | dict[str, list[dict[str, Any]]]:
+        """Search tickets by station names or station codes."""
+        params = {
+            'code0': self.resolve_station_code(from_station),
+            'code1': self.resolve_station_code(to_station),
+            'dt0': self._format_date(departure_date),
+            'dir': 1 if return_date is not None else 0,
+            'tfl': self._transport_type_code(transport_type),
+            'checkSeats': 1 if only_with_seats else 0,
+            'md': 1 if include_transfers else 0,
+        }
+
+        if return_date is not None:
+            params['dt1'] = self._format_date(return_date)
+            return self.api.train_routes_return_data(params)
+
+        return self.api.train_routes_data(params)
+
+    def get_carriages(
+        self,
+        from_station: str | int,
+        to_station: str | int,
+        departure_date: str | date | datetime,
+        departure_time: str,
+        train_number: str,
+    ) -> dict[str, Any]:
+        """Fetch carriage information for a train."""
+        params = {
+            'code0': self.resolve_station_code(from_station),
+            'code1': self.resolve_station_code(to_station),
+            'dt0': self._format_date(departure_date),
+            'time0': departure_time,
+            'tnum0': train_number,
+            'dir': 0,
+        }
+        return self.api.train_carriages_data(params)
+
+    def get_route_stations(
+        self,
+        train_number: str,
+        departure_date: str | date | datetime,
+    ) -> dict[str, Any]:
+        """Fetch all stations for a train route."""
+        return self.api.train_station_list_data({
+            'trainNumber': train_number,
+            'depDate': self._format_date(departure_date),
+        })
+
+    def find_stations(self, query: str, *, compact_mode: str = 'y') -> list[dict[str, str]]:
+        """Find stations by a partial name."""
+        return self.api.station_code_data({
+            'stationNamePart': query,
+            'compactMode': compact_mode,
+        })
+
+    def resolve_station_code(self, station: str | int) -> str:
+        """Resolve either a station code or a station name to a code."""
+        value = str(station).strip()
+        if not value:
+            raise ValueError('Station name or code must not be empty.')
+
+        if value.isdigit():
+            return value
+
+        matches = self.find_stations(value)
+        if not matches:
+            raise RzdException(f'Station not found: {value}')
+
+        upper_value = value.upper()
+        exact_match = next((item for item in matches if item['station'].upper() == upper_value), None)
+        if exact_match:
+            return exact_match['code']
+
+        return matches[0]['code']
+
+    def _format_date(self, value: str | date | datetime) -> str:
+        if isinstance(value, datetime):
+            return value.strftime('%d.%m.%Y')
+        if isinstance(value, date):
+            return value.strftime('%d.%m.%Y')
+        return value
+
+    def _transport_type_code(self, transport_type: str) -> int:
+        try:
+            return self.TRANSPORT_TYPES[transport_type]
+        except KeyError as exc:
+            allowed = ', '.join(sorted(self.TRANSPORT_TYPES))
+            raise ValueError(
+                f'Unsupported transport_type: {transport_type}. Use one of: {allowed}.'
+            ) from exc

rzd_api/config.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Config:
+    language: str = 'ru'
+    timeout: float = 5.0
+    debug: bool = False
+    proxy: Optional[str] = None
+    user_agent: Optional[str] = None
+    referer: Optional[str] = None

rzd_api/query.py

@@ -0,0 +1,86 @@
+import logging
+import time
+import requests
+import urllib3
+
+from .config import Config
+
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+logger = logging.getLogger(__name__)
+
+
+class RzdException(Exception):
+    pass
+
+
+class Query:
+    def __init__(self, config: Config):
+        self.config = config
+        self.session = requests.Session()
+        self.session.verify = False
+
+        if config.debug:
+            logging.basicConfig(level=logging.DEBUG)
+            from http.client import HTTPConnection
+            HTTPConnection.debuglevel = 1
+
+        headers = {'Accept': 'application/json'}
+        if config.user_agent:
+            headers['User-Agent'] = config.user_agent
+        if config.referer:
+            headers['Referer'] = config.referer
+        self.session.headers.update(headers)
+
+        if config.proxy:
+            self.session.proxies = {
+                'http': config.proxy,
+                'https': config.proxy,
+            }
+
+    def get(self, path: str, params: dict, method: str = 'POST') -> dict | list:
+        return self._run(path, params, method)
+
+    def _run(self, path: str, params: dict, method: str) -> dict | list:
+        rid = None
+        content = None
+
+        for attempt in range(10):
+            request_params = dict(params)
+            if rid is not None:
+                request_params['rid'] = rid
+
+            logger.debug('[attempt %d] %s %s params=%s', attempt + 1, method, path, request_params)
+
+            if method == 'GET':
+                response = self.session.get(path, params=request_params, timeout=self.config.timeout)
+            else:
+                response = self.session.post(path, data=request_params, timeout=self.config.timeout)
+
+            response.raise_for_status()
+            content = response.json()
+
+            result = content.get('result', 'OK') if isinstance(content, dict) else 'OK'
+            logger.debug('[attempt %d] result=%s', attempt + 1, result)
+
+            if result in ('RID', 'REQUEST_ID'):
+                rid = self._get_rid(content)
+                time.sleep(1)
+            elif result == 'OK':
+                try:
+                    msg = content['tp'][0]['msgList'][0]['message']
+                    raise RzdException(msg)
+                except (KeyError, IndexError, TypeError):
+                    pass
+                return content
+            else:
+                msg = content.get('message', 'Failed to get request data!') if isinstance(content, dict) else 'Failed to get request data!'
+                raise RzdException(msg)
+
+        return content
+
+    def _get_rid(self, content: dict) -> str:
+        for key in ('rid', 'RID'):
+            if key in content:
+                return str(content[key])
+        raise RzdException('Rid not found!')

rzd_api-1.0.0.dist-info/METADATA

@@ -0,0 +1,391 @@
+Metadata-Version: 2.4
+Name: rzd-api
+Version: 1.0.0
+Summary: Python client for RZD (Russian Railways) pass.rzd.ru API
+Author: drgod
+License: MIT
+Project-URL: Homepage, https://github.com/drGOD/rzd-api
+Project-URL: Repository, https://github.com/drGOD/rzd-api
+Project-URL: Issues, https://github.com/drGOD/rzd-api/issues
+Keywords: rzd,railway,trains,tickets,api,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: urllib3>=2.0.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: rzd-api[mcp]; extra == "dev"
+
+# RZD API — Python
+
+Python-клиент для API сайта [pass.rzd.ru](https://pass.rzd.ru) (РЖД).  
+Включает MCP-сервер для интеграции с Claude и другими MCP-совместимыми клиентами.
+
+## Возможности
+
+- Маршруты в одну сторону
+- Маршруты туда-обратно
+- Список вагонов (схема, цены, свободные места)
+- Список станций по маршруту следования поезда
+- Поиск кода станции по части названия
+
+---
+
+## Установка
+
+**Из PyPI после публикации:**
+```sh
+pip install rzd-api
+```
+
+**Как библиотека без MCP-зависимостей:**
+```sh
+pip install rzd-api
+```
+
+**С поддержкой MCP-сервера:**
+```sh
+pip install "rzd-api[mcp]"
+```
+
+**Напрямую из GitHub:**
+```sh
+pip install "git+https://github.com/drGOD/rzd-api.git"
+```
+
+**Напрямую из GitHub c MCP-сервером:**
+```sh
+pip install "rzd-api[mcp] @ git+https://github.com/drGOD/rzd-api.git"
+```
+
+**Из исходников:**
+```sh
+pip install .
+```
+
+**Из исходников c MCP-сервером:**
+```sh
+pip install ".[mcp]"
+```
+
+**Для разработки (с тестами):**
+```sh
+pip install -e ".[dev]"
+# или
+make install
+```
+
+**Проверка импорта после установки:**
+```sh
+python -c "from rzd_api import RzdClient; print(RzdClient.__name__)"
+```
+
+**Проверка MCP-команды после установки extra:**
+```sh
+rzd-mcp-server
+```
+
+---
+
+## Быстрый старт
+
+### Как библиотека
+
+```python
+from datetime import date
+from rzd_api import RzdClient
+
+client = RzdClient()
+
+# Можно передавать названия станций, клиент сам найдёт их коды
+tickets = client.search_tickets(
+    from_station='Санкт-Петербург',
+    to_station='Москва',
+    departure_date=date(2026, 4, 1),
+)
+
+for train in tickets[:3]:
+    print(train['number'], train['route0'], train['route1'], train['time0'], train['time1'])
+
+# Туда-обратно
+round_trip = client.search_tickets(
+    from_station='Санкт-Петербург',
+    to_station='Москва',
+    departure_date='01.04.2026',
+    return_date='05.04.2026',
+)
+
+# Поиск станций и получение кода
+stations = client.find_stations('Чеб')
+code = client.resolve_station_code('Москва')
+
+# Детали по вагонам
+cars = client.get_carriages(
+    from_station='Санкт-Петербург',
+    to_station='Москва',
+    departure_date='01.04.2026',
+    departure_time='22:30',
+    train_number='054А',
+)
+```
+
+### Низкоуровневый API
+
+```python
+from datetime import datetime, timedelta
+from rzd_api import Api, Config
+
+config = Config(
+    language='ru',       # язык ответа: 'ru' или 'en'
+    timeout=10.0,        # таймаут запроса в секундах
+    user_agent='Mozilla/5.0 ...',
+    referer='https://ticket.rzd.ru/',
+    # proxy='https://user:pass@host:port',
+    # debug=True,        # включить HTTP-лог
+)
+
+api = Api(config)   # config необязателен
+
+tomorrow = (datetime.now() + timedelta(days=1)).strftime('%d.%m.%Y')
+
+# Маршруты Санкт-Петербург → Москва
+routes = api.train_routes({
+    'dir':        0,          # 0 — в одну сторону
+    'tfl':        3,          # 3 — поезда и электрички, 1 — только поезда, 2 — только электрички
+    'checkSeats': 1,          # 1 — только с билетами, 0 — все поезда
+    'code0':      '2004000',  # код станции отправления
+    'code1':      '2000000',  # код станции прибытия
+    'dt0':        tomorrow,   # дата отправления dd.mm.yyyy
+    'md':         0,          # 0 — без пересадок, 1 — с пересадками
+})
+print(routes)   # JSON-строка
+```
+
+---
+
+## API
+
+### `RzdClient(config=None, api=None)`
+
+Высокоуровневый интерфейс для использования пакета как библиотеки.  
+Методы возвращают обычные Python-объекты (`list` / `dict`) и принимают станции как коды или названия.
+
+| Метод | Описание |
+|---|---|
+| `search_tickets(from_station, to_station, departure_date, return_date=None, *, only_with_seats=True, include_transfers=False, transport_type='all')` | Удобный поиск билетов |
+| `find_stations(query, compact_mode='y')` | Поиск станций по части названия |
+| `resolve_station_code(station)` | Получить код станции по названию или вернуть переданный код |
+| `get_carriages(from_station, to_station, departure_date, departure_time, train_number)` | Вагоны и свободные места |
+| `get_route_stations(train_number, departure_date)` | Список станций маршрута |
+
+#### `search_tickets`
+
+| Параметр | Описание |
+|---|---|
+| `from_station` / `to_station` | Код станции (`2004000`) или название (`Санкт-Петербург`) |
+| `departure_date` / `return_date` | `str`, `datetime.date` или `datetime.datetime` |
+| `only_with_seats` | `True` — только поезда с билетами |
+| `include_transfers` | `True` — искать варианты с пересадками |
+| `transport_type` | `'trains'`, `'suburban'`, `'all'` |
+
+### `Api(config=None)`
+
+Низкоуровневый совместимый интерфейс. Методы ниже сохраняют текущее поведение и возвращают **JSON-строку**.  
+Если нужен Python-объект без `json.loads`, можно использовать парные методы с суффиксом `_data`.
+
+| Метод | Описание |
+|---|---|
+| `train_routes(params)` | Маршруты в одну сторону |
+| `train_routes_data(params)` | Маршруты в одну сторону как `list[dict]` |
+| `train_routes_return(params)` | Маршруты туда-обратно |
+| `train_routes_return_data(params)` | Маршруты туда-обратно как `dict` |
+| `train_carriages(params)` | Вагоны и свободные места |
+| `train_carriages_data(params)` | Вагоны и свободные места как `dict` |
+| `train_station_list(params)` | Все станции на маршруте поезда |
+| `train_station_list_data(params)` | Все станции на маршруте как `dict` |
+| `station_code(params)` | Поиск кода станции по части названия |
+| `station_code_data(params)` | Поиск кода станции как `list[dict]` |
+
+#### `train_routes` / `train_routes_return`
+
+| Параметр | Описание |
+|---|---|
+| `code0` | Код станции отправления |
+| `code1` | Код станции прибытия |
+| `dt0` | Дата отправления `dd.mm.yyyy` |
+| `dt1` | Дата возврата `dd.mm.yyyy` (только для `train_routes_return`) |
+| `dir` | `0` — в одну сторону, `1` — туда-обратно |
+| `tfl` | `1` — поезда, `2` — электрички, `3` — всё |
+| `checkSeats` | `1` — только с билетами, `0` — все |
+| `md` | `0` — без пересадок, `1` — с пересадками |
+
+#### `train_carriages`
+
+| Параметр | Описание |
+|---|---|
+| `code0` / `code1` | Коды станций |
+| `dt0` | Дата отправления `dd.mm.yyyy` |
+| `time0` | Время отправления `HH:MM` |
+| `tnum0` | Номер поезда (например `054Г`) |
+
+#### `train_station_list`
+
+| Параметр | Описание |
+|---|---|
+| `trainNumber` | Номер поезда (например `054Г`) |
+| `depDate` | Дата отправления `dd.mm.yyyy` |
+
+#### `station_code`
+
+| Параметр | Описание |
+|---|---|
+| `stationNamePart` | Часть названия станции (мин. 2 символа, например `ЧЕБ`) |
+| `compactMode` | Формат ответа, по умолчанию `y` |
+
+### `Config`
+
+| Поле | По умолчанию | Описание |
+|---|---|---|
+| `language` | `'ru'` | Язык ответа (`'ru'`, `'en'`) |
+| `timeout` | `5.0` | Таймаут запроса (сек) |
+| `debug` | `False` | HTTP-лог в stderr (уровень DEBUG) |
+| `proxy` | `None` | URL прокси |
+| `user_agent` | `None` | User-Agent |
+| `referer` | `None` | Referer |
+
+---
+
+## MCP-сервер
+
+MCP-сервер позволяет использовать API РЖД напрямую из Claude Desktop или любого MCP-клиента.
+
+Для локального запуска нужен extra `mcp`:
+```sh
+pip install "rzd-api[mcp]"
+```
+
+### Инструменты
+
+| Инструмент | Описание |
+|---|---|
+| `train_routes` | Поиск поездов в одну сторону |
+| `train_routes_return` | Поиск поездов туда-обратно |
+| `train_carriages` | Информация о вагонах |
+| `train_station_list` | Станции на маршруте |
+| `station_code` | Поиск кода станции |
+
+### Запуск локально (stdio)
+
+```sh
+rzd-mcp-server
+# или
+make run
+```
+
+**Настройка в Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "rzd": {
+      "command": "rzd-mcp-server"
+    }
+  }
+}
+```
+
+### Запуск через Docker (HTTP)
+
+```sh
+docker compose up -d
+# или
+make docker-up
+```
+
+Сервер запустится на `http://localhost:8000` (транспорт `streamable-http`).
+
+**Настройка в Claude Desktop** для удалённого сервера:
+
+```json
+{
+  "mcpServers": {
+    "rzd": {
+      "type": "streamable-http",
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+### Переменные окружения MCP-сервера
+
+| Переменная | По умолчанию | Описание |
+|---|---|---|
+| `MCP_TRANSPORT` | `stdio` | Транспорт: `stdio`, `sse`, `streamable-http` |
+| `MCP_HOST` | `0.0.0.0` | Хост для HTTP-транспортов |
+| `MCP_PORT` | `8000` | Порт для HTTP-транспортов |
+
+---
+
+## Docker
+
+```sh
+# Сборка образа
+docker build -t rzd-api .
+
+# Запуск
+docker run -p 8000:8000 rzd-api
+
+# С кастомным портом
+docker run -p 9000:9000 -e MCP_PORT=9000 rzd-api
+```
+
+---
+
+## Тесты
+
+```sh
+pytest tests/ -v
+# или
+make test
+```
+
+Тесты интеграционные — работают с живым API pass.rzd.ru.
+
+---
+
+## Как работает протокол RZD
+
+1. Первый запрос возвращает статус `RID` / `REQUEST_ID` + cookie
+2. Повторный запрос с тем же `rid` и cookie возвращает статус `OK` с данными
+3. Библиотека управляет сессией и повторными запросами автоматически (до 10 попыток, интервал 1 сек)
+
+## Популярные коды станций
+
+| Станция | Код |
+|---|---|
+| Санкт-Петербург Главный | `2004000` |
+| Москва (Ленинградский вокзал) | `2000000` |
+| Москва (Казанский вокзал) | `2000001` |
+| Новосибирск Главный | `2060600` |
+| Екатеринбург Пасс. | `2030000` |
+
+Для поиска кода любой станции используйте метод `station_code`.
+
+## Лицензия
+
+MIT

rzd_api-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+mcp_server/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_server/server.py,sha256=njffuItSxAkVx8o1a9iy_V7HA71XMZAjdE2MRX8Rpo4,5369
+rzd_api/__init__.py,sha256=PiuGytV_vaPG9HDB5EuF3b-EQLd3cnDHIBORF6_yxJI,184
+rzd_api/api.py,sha256=oZTxs8PpucROzcQP38ONrfUsgDCI2BhXIFk2M8sD9Jc,4233
+rzd_api/client.py,sha256=TsrfuybBbCyCiAYl_tFKJpwDpJdkTsX4126jB7g5v5A,4155
+rzd_api/config.py,sha256=4hKeH2W3QlK2gp4fqtZJNKBBgjYc4-p2NHT12ZsjkXE,266
+rzd_api/query.py,sha256=UcwooXQRbNp7qyKrKtsXCHS0A9ppKZs9lMYbjpHmwpk,2795
+rzd_api-1.0.0.dist-info/METADATA,sha256=iTre5wdUUZ2dYQTm820zDulpPSX_DY1bYRbs4M-SgJc,13339
+rzd_api-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+rzd_api-1.0.0.dist-info/entry_points.txt,sha256=XnLatRdzqeiez4AHnpDyVc5SbxV3iAql7AsS-lbzWD8,58
+rzd_api-1.0.0.dist-info/top_level.txt,sha256=NsYXt3dQpIaUpdga9uXm3JZUXkBtZWsXIzIB3Jm8K_k,19
+rzd_api-1.0.0.dist-info/RECORD,,

rzd_api-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rzd_api-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rzd-mcp-server = mcp_server.server:main

rzd_api-1.0.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+mcp_server
+rzd_api