transit-mcp-server

MCP-сервер для API общественного транспорта 511.org SF Bay Open Data. Предоставляет LLM живые данные о транспорте в заливе Сан-Франциско — операторы, маршруты, остановки, отправления в реальном времени, позиции транспортных средств и предупреждения о сбоях — для BART, Muni, AC Transit, Caltrain, VTA и всех остальных операторов, отчитывающихся в 511.

6 инструментов, все только для чтения.

Требования

• Node.js 18+

• Бесплатный токен 511 API с https://511.org/open-data/token

Related MCP server: Bay Wheels MCP Server

Установка

npm install
npm run build

Настройка

{
  "mcpServers": {
    "transit": {
      "command": "node",
      "args": ["/absolute/path/to/transit-mcp-server/dist/index.js"],
      "env": { "TRANSIT_511_API_KEY": "your-token-here" }
    }
  }
}

Основное ограничение — квота

511 разрешает 60 запросов в час на ключ, общих для всех конечных точек. Этого достаточно мало, чтобы определять, как следует использовать эти инструменты:

• Определите коды операторов и коды остановок один раз, затем переиспользуйте их. Они не меняются.

• Предпочитайте transit_list_service_alerts без operator_id — один вызов покрывает все агентства.

• Никогда не опрашивайте transit_next_departures в цикле. Десять проверок за поездку на работу — это шестая часть часового бюджета.

transit_list_operators сообщает, сколько бюджета осталось, читая заголовок RateLimit-Remaining, который 511 возвращает в каждом ответе. Превышение квоты возвращает 429; запросите увеличение по адресу transitdata@511.org.

Развёртывание (для коннекторов Claude mobile / claude.ai)

Та же схема, что и для любого размещённого MCP-сервера: сгенерируйте секрет пути с помощью openssl rand -hex 32, задайте TRANSIT_511_API_KEY и MCP_PATH_SECRET в панели платформы, и включённые Dockerfile и railway.json будут работать как есть на Railway, Render или Fly. Сервер отказывается запускаться на публичном интерфейсе без секрета. /healthz — это неаутентифицированный зонд готовности.

Затем на claude.ai в браузере: Customize → Connectors → Add custom connector, URL https://your-app.up.railway.app/mcp/<secret>.

Инструменты

Сеть — transit_list_operators, transit_list_lines, transit_find_stops

Реальное время — transit_next_departures, transit_list_vehicles

Предупреждения — transit_list_service_alerts

Каждый инструмент принимает response_format: "markdown" | "json". Markdown — по умолчанию и оптимизирован для чтения LLM; JSON — полная структурированная полезная нагрузка. structuredContent всегда заполняется независимо от формата.

Примеры

«Когда следующий N Judah?» → transit_find_stops с operator_id="SF", query="judah" для получения кода остановки, затем transit_next_departures с этим кодом и line="N".

«BART работает нормально?» → transit_list_service_alerts с operator_id="BA".

«Что-то не так с моей поездкой на работу?» → transit_list_service_alerts без оператора — один вызов охватывает все агентства залива.

«Где сейчас поезда?» → transit_list_vehicles с operator_id="BA".

Заметки по дизайну

Только для чтения по построению. 511 не публикует конечных точек записи, и каждый инструмент несёт readOnlyHint: true. Тест проверяет это.

Один operator_id, сопоставляемый для каждой конечной точки. 511 называет этот параметр operator_id на своих статических конечных точках и agency на своих конечных точках реального времени, для одного и того же значения. Каждый инструмент здесь принимает operator_id, и клиент сопоставляет его. Это разделение — проблема 511, а не вызывающего.

Две конечные точки реального времени имеют действительно разные обёртки. StopMonitoring не имеет корневой обёртки Siri; VehicleMonitoring имеет. Опубликованная спецификация показывает одну для обеих — спецификация неверна, и разбор документированной формы вернул бы ничего для отправлений. Обе разбираются так, как их фактически выдаёт живой API, с тестом, фиксирующим каждую.

Прибытия несут обратный отсчёт, а не отправления. ExpectedDepartureTime равен null практически в каждой реальной строке, поэтому привязка обратного отсчёта к нему показала бы остановку без обслуживания. ExpectedArrivalTime — надёжное поле.

Перед разбором удаляется UTF-8 BOM. 511 добавляет префикс U+FEFF к телам JSON, из-за чего наивный JSON.parse выбрасывает исключение на совершенно корректной полезной нагрузке. Сбои аутентификации — это обычный текст без BOM, поэтому удаление происходит после проверки статуса.

Значения, которые выглядят как числа и логические значения, часто таковыми не являются. Координаты и азимуты приходят как строки JSON, VehicleAtStop — это строка "false", а "" используется повсюду, где подразумевается null. Слепое приведение превратило бы отсутствующую позицию в правдоподобные 0,0 у побережья Африки, поэтому пустые строки трактуются как отсутствующие, а не как ноль.

Страж эпохи — это не временная метка. Поездка, которая запланирована, но не имеет назначенного транспортного средства, сообщает RecordedAtTime как 1970-01-01T00:00:00Z. Это отображается как «транспортное средство ещё не назначено», а не «записано 56 лет назад».

Перечисления GTFS-Realtime декодируются. JSON-рендеринг предупреждений 511 выдаёт "effect": 3, тогда как XML-рендеринг говорит SignificantDelays. И причина, и эффект сопоставляются обратно со словами.

Внутренние псевдо-агентства 511 отфильтровываются. 5E, 5F, 5O и 5S — это 511 Emergency, Flap Sign, Operations и Staff — они появляются в списке операторов, не неся данных об обслуживании.

Всё по тихоокеанскому времени. Временные метки приходят как UTC и отображаются в America/Los_Angeles, поэтому переход на летнее время обрабатывается здесь один раз, а не моделью дважды в год. Обратите внимание, что собственное поле TimeZone от 511 сообщает America/Vancouver для каждого агентства залива — известная вышестоящая ошибка данных, намеренно игнорируемая.

Усечение всегда указывается. 511 не использует пагинацию; он возвращает целые коллекции, и у крупного агентства тысячи остановок. Инструменты принимают клиентский limit, и каждый усечённый результат сообщает, сколько было скрыто, потому что молча сокращённый список читается как «это всё».

Предостережения

• Часовая квота — 60 запросов на все конечные точки. Это связывающее ограничение для любого рабочего процесса.

• Коды операторов легко угадать неправильно: VTA — это SC (не VT), Capitol Corridor — AM (не CC), Tri Delta — 3D. transit_list_operators выводит эти ловушки в своём выводе.

• Коды остановок принадлежат одному оператору и не взаимозаменяемы между агентствами.

• transit_find_stops фильтрует на этом сервере, поэтому узкий запрос не экономит квоту — полный список остановок извлекается в любом случае.

• Прогнозы реального времени простираются примерно на 90 минут вперёд, и 511 опускает конечную остановку маршрута, доступную только для прибытия, из потока отправлений.

• tripupdates и vehiclepositions доступны только в protobuf без опции JSON, поэтому они намеренно не предоставляются — их поддержка означала бы принятие зависимости от protobuf для данных, которые конечные точки SIRI уже покрывают.

Структура проекта

src/
├── index.ts               # entry point, transport selection
├── constants.ts           # enums, limits, operator-code traps
├── types.ts               # interfaces for every 511 entity
├── services/
│   └── transit-client.ts  # fetch wrapper, auth, BOM stripping, quota tracking, errors
├── schemas/
│   ├── inputs.ts          # Zod input schemas
│   └── outputs.ts         # structuredContent schemas
├── formatters/
│   ├── response.ts        # limiting, truncation, Pacific-time rendering
│   └── entities.ts        # per-entity markdown rendering
└── tools/
    ├── network.ts         # operators, lines, stops
    ├── departures.ts      # real-time arrivals and vehicles
    └── alerts.ts          # service alerts

Тесты

npm run build
npm test            # 42 checks: handshake, BOM, envelopes, quirks, errors (mocked API)
npm run test:http   # 17 checks: config validation, path-secret gating, method handling, origins

Оба набора запускаются против локального макета, который намеренно воспроизводит реальные причуды 511 — BOM, отсутствующую обёртку Siri, строковые логические значения и координаты, страж эпохи и текстовые тела ошибок — потому что именно на этом спотыкается наивный клиент.