japan-rail-mcp

japan-rail-mcp — это сервер Model Context Protocol в режиме только чтения для структурированных данных о японских железных дорогах. Версия 0.1 намеренно ориентирована в первую очередь на Синкансэн (Shinkansen-first): она предоставляет полезный каталог станций, не требующий учетных данных, и может запрашивать актуальные расписания Синкансэн, тарифы, классы мест и рейсы через ключ владельца развертывания к тарифному плану Ekispert API Standard.

Сервер никогда не бронирует билеты, не входит в учетные записи железнодорожных систем, не обходит ограничения доступа, не собирает данные с сайтов операторов и не выдает тестовые фикстуры за реальные данные.

japan-rail-mcp спроектирован так, чтобы иметь общий концептуальный интерфейс с china-rail-mcp, с долгосрочной целью создания интероперабельных схем для железнодорожных MCP-серверов в разных странах.

Это экспериментальное соглашение по интероперабельности, а не официальный железнодорожный стандарт или стандарт MCP.

Возможности

Все успешные данные содержат указание на источник. Железнодорожные временные метки — это явные значения ISO 8601 со смещением японского часа, например 2026-08-26T12:03:00+09:00. Относительные даты, такие как «завтра», должны разрешаться клиентом MCP; сервер требует YYYY-MM-DD.

Related MCP server: DB Timetable MCP Server

Инструменты MCP

Каждый инструмент аннотирован как read-only (только чтение), не разрушающий и идемпотентный. Каждый успешный результат инструмента включает как читаемый JSON-текст, так и MCP structuredContent, проверенный по выходной схеме.

Установка

Требования: Node.js 22 или новее. В CI используется Node.js 24 LTS.

git clone https://github.com/TakeruF/japan-rail-mcp.git
cd japan-rail-mcp
npm install
npm run build

Запустите stdio-сервер:

npm start

После npm-релиза клиенты могут запускать его и таким способом:

npx -y japan-rail-mcp

Актуальные данные Синкансэн

Функциональность «живого» расписания требует ключа доступа, в рамках которого соглашение об использовании Ekispert API включает точку (endpoint) поиска маршрутов плана Standard. Бесплатный план не предоставляет этой основной конечной точки.

export EKISPERT_API_KEY='your-own-key'
npm start

Ключ отправляется только на настроенную конечную точку Ekispert API. Он никогда не возвращается в результатах инструментов и не включается в ошибки провайдера. Проект не содержит общего ключа, не предоставляет сублицензии на данные провайдера и не отменяет лимиты запросов, предусмотренные вашим соглашением.

Конфигурация клиента

Claude Desktop

Для локальной копии добавьте запись такого вида и замените абсолютный путь:

{
  "mcpServers": {
    "japan-rail": {
      "command": "node",
      "args": ["/absolute/path/to/japan-rail-mcp/dist/index.js"],
      "env": {
        "EKISPERT_API_KEY": "your-own-key"
      }
    }
  }
}

Если нужен только поиск станций, опустите объект env. Предпочитайте использовать механизм управления секретами вашего клиента, а не хранить ключи в репозитории конфигурации.

Codex

Зарегистрируйте собранную stdio-команду в конфигурации MCP у Codex или используйте CLI-форму, поддерживаемую вашей установленной версией Codex:

codex mcp add japan-rail -- node /absolute/path/to/japan-rail-mcp/dist/index.js

Передавайте EKISPERT_API_KEY через переменные окружения процесса или через секретный конфигуратор Codex, когда требуются данные о поездах в реальном времени.

Примеры использования инструментов

Сначала найдите кандидатов-станций:

{
  "query": "Osaka"
}

Результат намеренно включает и станцию Осака, и станцию Син-Осака, когда это именно. Затем используйте точные ID:

{
  "fromStationId": "jp:station:tokyo",
  "toStationId": "jp:station:shin-osaka",
  "date": "2026-08-26",
  "departureAfter": "12:00",
  "serviceTypes": ["shinkansen"],
  "limit": 10,
  "offset": 0
}

Нормализованный тариф — число, безопасное при работе с валютами:

{
  "amount": 14720,
  "currency": "JPY",
  "formatted": "¥14,720",
  "kind": "total"
}

formatted предназначен только для отображения; для сравнения клиентам следует использовать amount и currency.

Источники данных

Встроенный каталог станций

Поддерживаемый проектом каталог охватывает 58 значимых-станций: действующие сети Синкансэн и небольшой набор станций, специально сделанных неоднозначными для сравнения, например станции Осака, Синдзюку и Фукуока в префектуре Тояма. В нем содержатся метаданные станций — без расписаний, тарифов или данных о наличии. Карты маршрутов операторов и страницы проезда указаны в Оцените источники.

API Ekispert

Опциональный провайдер использует документированные конечные точки API и ключ доступа владельца развертывания. Он запрашивает явную дату, явную полночь, если нижняя временная граница не задана, а также остановки, типы мест и сведения об операторе. В ответах указываются ekispert-standard, назваление конечной точки, время получения, статус в реальном времени и граница соглашения с провайдером.

Источники, не используемые для данных расписания Синкансэн

• Текущий ODPT JR East набор данных расписаний поездов прямо исключает Синкасэн.

• GTFS-JP v4 — это спецификация данных, а не общенациональный фид и не универсальная лицензия на данные.

• Публичные страницы JT и PDF-файлы с расписаниями не предоставляют проекту универсального API и лицензию на перераспределение, поэтому они не парсятся и не объединяются для бандла.

См. docs/data-sources.md — там уточненный анализ источников и основные ссылки.

Архитектура

MCP tools
  -> RailService
    -> StationCatalogProvider
       -> StaticShinkansenStationProvider
    -> RailDataProvider
       -> EkispertProvider (optional key)

core rail schemas
  + Japan extensions
  + provider-private parsing and identifiers

MCP-обработчики проверяют и описывают вызовы инструментов, но не загружают и не разбирают данные провайдера. Проверки возможностей закрываются (fail closed) до обращения к сети. search_trains представляет собой физическую поездку прямого поезда; search_journeys — маршрут, в который могут входить пересадки. Границы извлечения см. в docs/architecture.md.

Связь с china-rail-mcp

Общие имена инструментов:

• search_stations

• search_trains

• get_train_details

• get_availability

• compare_trains

Общие контактные схемы: Station, StationRef, Train, Journey, Fare, SeatClass, SeatAvailability, Source, RailError и RailProviderCapabilities. Контракт сохраняет числовые тарифы ISO 4217, явные сдвиги времени с поправкой на страну, схождение данных, канонические ID станций, важные для возможностей провайдера проверки и структурированные ошибки.

Данные, специфичные для Японии, находятся в extensions.japan, например:

• линии и названия сервисов Синсивозовиц;

• названия станции в терминологии провайдера;

• пассажирские номера поездов и операционные/провайдерские идентификаторы;

• японские обозначения мест такие как 自由席, 指定席, グリーン車 и グランクラス.

Эти границы — кандидаты на будущую независимую спецификацию rail-mcp-spec; данный репозиторий не утверждает, что такой стандарт уже существует.

Ограничения

• Установка без потребностей и доверия ключей ищет только станции.

• Поведение «живых» поездов имеет контрактные тесты на тест-фикстурах, но не испытано на реальном аккаунте в этом репозитории. Успешноя работа фикстуры — это не доказательство реального доступа к провайдеру.

• Тарифный план Ekispert Standard, лимиты, сервис, коммерческое использование, кэширование и права на расписку зависят от соглашения владельца развертывания.

• Результаты подлинного поиск ограничиваются первыми 20 ответами провайдера за запрос.

• search_trains возвращает только прямые маршруты Синкенсэн. Пересадки не участие молча строятся в прямые.

• Seat-классы и опубликованные тарифы — это не наличие мест. get_availability по-прежнему не поддерживается.

• Перебои в движении и текущие позиции поездов не втянуты.

• Встроенный каталог станций сосредоточен на Синкансэн, он не является полным национальным клубом данных.

• Важные условия поездок, тарифов и билетов следует уточнять у оператора железных дорог или в авторизованном канале бронирования.

Разработка

npm install
npm run lint
npm run typecheck
npm test
npm run build
npm run format

Тесты охватывают сопоставление станций на японском/английском, неоднозначность, парсинг фикстур Токио–Син-Осака, явные даты и границы токиского времени, сбое провайдера, неподдерживаемую викторию, структурированный вывод MCP, read-only аннотации и общий многократно используемый контракт схемы рельсовых данных.

Безопасность и только чтение

Инструментов покупки билетов, бронирования, входа, оплаты, ввода CAPTCHA, профиля или изменения данных нет. См. SECURITY.md — там рекомендации по обращению с ключами и данными.

Лицензия

Исходный код проекта доступен по лицензии MIT. Эта лицензия относится только к коду собственного репозитория; она не перелицензирует и не объединяет данные от железнодорожных операторов, ответы сервиса Ekispert, наборы данных ODPT, материалы GTFS-фидов или товарные знаки третьих сторон. Каждый источник данных остается под собственными условиями использования.