🚇 Metro MCP

Сервер Model Context Protocol для транспортных систем США (метро DC и метро Нью-Йорка)

Единый удалённый сервер Model Context Protocol (MCP), поддерживающий несколько транспортных систем США. В настоящее время поддерживаются метро Вашингтона (WMATA) и метро Нью-Йорка (MTA). Создан для бесшовной интеграции с MCP-совместимыми клиентами, такими как Claude Desktop, Cursor, Codex, и любым клиентом, поддерживающим Streamable HTTP MCP-серверы.

Быстрые ссылки: Быстрый старт • Что вы можете делать • Transit Board • Развёртывание • Интеграция с клиентами

Что вы можете делать

Задавайте вопросы на естественном языке о метро DC или метро Нью-Йорка в Claude Desktop или любом MCP-совместимом клиенте:

🚆 Информация о транспорте в реальном времени

Вашингтон, округ Колумбия:

• «Когда следующий поезд Красной линии на станции Dupont Circle?»

• «Какие автобусные маршруты доступны?»

• «Найди автобусные остановки рядом с Dupont Circle»

• «Где сейчас все автобусы 30N?»

• «Когда следующий автобус на остановке 1001195?»

• «Покажи все поезда, которые сейчас работают в системе метро»

• «Есть ли задержки на Синей линии прямо сейчас?»

• «Все ли лифты работают на станции Union Station?»

Нью-Йорк:

• «Когда следующий поезд 1 на Таймс-сквер?»

• «Есть ли задержки на линии A/C?»

• «Какие поезда прибывают на Grand Central?»

• «Что такое поезд A и куда он идёт?»

• «До каких ближайших станций я могу дойти пешком от Таймс-сквер?»

• «Сколько времени занимает переход между платформами Таймс-сквер?»

🗺️ Информация о станциях и навигация

Вашингтон, округ Колумбия:

• «Где находится станция метро Smithsonian?»

• «Покажи все станции на Зелёной линии»

Нью-Йорк:

• «Где находится станция Union Square?»

• «Покажи все 496 станций метро Нью-Йорка»

• «Какие станции соединяются с Таймс-сквер?»

• «Объясни разницу между экспресс- и локальными поездами»

♿ Доступность

Вашингтон, округ Колумбия (отключения лифтов):

• «Есть ли отключения лифтов между здесь и National Airport?»

• «На каких станциях метро DC сейчас работают лифты?»

🔔 Мониторинг обслуживания

Оба города:

• «Есть ли задержки транспорта прямо сейчас в Нью-Йорке?»

• «Работает ли Оранжевая линия метро DC нормально?»

• «Сравни качество обслуживания между метро DC и метро Нью-Йорка»

📊 Информация о системе

Вашингтон, округ Колумбия:

• Полный список всех станций метро с координатами

• Информация обо всех шести линиях метро (Red, Blue, Orange, Silver, Green, Yellow)

Нью-Йорк:

• Полное покрытие: Все 496 станций метро Нью-Йорка с координатами

• Информация о переходах: Время перехода между связанными станциями (87 станций с переходами)

• Описания маршрутов: Детальные схемы обслуживания для всех 29 маршрутов (экспресс против локальных, часы работы)

• Ясность платформ: Объясняет направленные платформы (например, «127N» = северное направление на Таймс-сквер)

Related MCP server: marta-mcp

Быстрый старт

Использование публичного сервера

Самый быстрый способ начать — использовать размещённый экземпляр:

1. Откройте ваш MCP-клиент

2. Добавьте этот URL: https://metro-mcp.anuragd.me/mcp

3. Нажмите «Подключиться» и авторизуйтесь через GitHub

4. Начните задавать вопросы о метро DC или метро Нью-Йорка

Разверните свой собственный

Хотите запустить собственный экземпляр? Смотрите раздел Развёртывание ниже.

Развёртывание

Предварительные требования

• Ключ API WMATA (обязательно)

• Аккаунт Cloudflare (бесплатный тариф работает)

• Bun для управления пакетами

• Node.js для Wrangler и пула Workerd Vitest; Bun остаётся единственным менеджером пакетов и владельцем lockfile

• GitHub OAuth App (для аутентификации)

Настройка окружения

Установите ровно то, что записано в bun.lock:

bun install --frozen-lockfile

Для локальной разработки создайте отдельный GitHub OAuth App, чей callback должен быть точно http://localhost:8787/callback. Затем скопируйте канонический шаблон .dev.vars.example, замените каждый заполнитель replace-with-... и запустите Wrangler:

cp .dev.vars.example .dev.vars
bun run dev

Держите вместе origin http://localhost:8787 из шаблона, списки разрешённых хостов/origin localhost, callback и значения ENVIRONMENT=development. В режиме локального запуска Wrangler по умолчанию настроенная привязка OAUTH_KV использует локальное непроизводственное хранилище в .wrangler; она не читает и не записывает развёрнутое производственное или preview-пространство имён. Не добавляйте --remote для обычной локальной разработки.

Создайте одно пространство имён OAuth Provider для каждого развёрнутого окружения и поместите его ID в соответствующую привязку OAUTH_KV:

bunx wrangler kv namespace create OAUTH_KV
bunx wrangler kv namespace create OAUTH_KV_preview

Производственная среда и preview также должны использовать отдельные GitHub OAuth-приложения. Настройте каждый callback как ${MCP_PUBLIC_ORIGIN}/callback; никогда не используйте производственное приложение или OAuth KV для preview. Каждое окружение задаёт:

• MCP_PUBLIC_ORIGIN, MCP_ALLOWED_HOSTNAMES и MCP_ALLOWED_ORIGIN_HOSTNAMES

• OAUTH_REDIRECT_URI и публичный GitHub GITHUB_CLIENT_ID окружения

• ENVIRONMENT (production, preview или development)

• OAUTH_KV, указывающий на выделенное пространство имён окружения

Устанавливайте производственные секреты в интерактивном режиме. MCP_REQUEST_STATE_KEY — это стабильный, специфичный для окружения ключ длиной не менее 32 байт, используемый только для подписанного состояния MRTR. JWT_SECRET остаётся временно для моста с устаревшей аудиторией /mcp.

bunx wrangler secret put MCP_REQUEST_STATE_KEY
bunx wrangler secret put GITHUB_CLIENT_SECRET
bunx wrangler secret put WMATA_API_KEY
bunx wrangler secret put JWT_SECRET

Установите те же четыре имени секретов независимо для preview; именованные окружения Wrangler не наследуют производственные секреты:

bunx wrangler secret put MCP_REQUEST_STATE_KEY --env preview
bunx wrangler secret put GITHUB_CLIENT_SECRET --env preview
bunx wrangler secret put WMATA_API_KEY --env preview
bunx wrangler secret put JWT_SECRET --env preview

Wrangler должен включать как nodejs_compat, так и global_fetch_strictly_public. Проверьте обе формы перед любым одобренным развёртыванием:

bunx wrangler deploy --dry-run --outdir /tmp/metro-mcp-production
bunx wrangler deploy --dry-run --env preview --outdir /tmp/metro-mcp-preview

Интеграция с MCP-клиентами

Claude

Используйте каноническую конечную точку Streamable HTTP в Claude Code:

claude mcp add --transport http metro-mcp https://metro-mcp.anuragd.me/mcp

Затем откройте /mcp, выберите metro-mcp и завершите вход через GitHub и согласие. Пользователи Claude.ai/Desktop могут добавить тот же URL как удалённый пользовательский коннектор, если это разрешено их тарифным планом и политикой рабочего пространства.

Codex

codex mcp add metro-mcp --url https://metro-mcp.anuragd.me/mcp
codex mcp login metro-mcp --scopes transit:read

Проверенный в репозитории mcp-config.json показывает эквивалентную общую конфигурацию удалённого HTTP. Токены доступа и обновления остаются в хранилище учётных данных клиента; не вставляйте их в конфигурацию проекта.

Совместимость транспорта

• Запросы MCP 2026-07-28 не сохраняют состояние и не требуют initialize.

• Обычные инструменты, ресурсы и подсказки остаются доступными для клиентов MCP 2025 без состояния.

• POST /sse и OPTIONS /sse — это псевдонимы URL, переписываемые на канонический /mcp перед авторизацией.

• Устаревший HTTP+SSE удалён. GET и DELETE на /sse или /mcp, URL сообщений сеанса и /sse/ возвращают 405.

• Аудитория OAuth и обнаружение всегда используют https://metro-mcp.anuragd.me/mcp; /sse никогда не является ресурсом OAuth.

Конечные точки OAuth

Провайдер OAuth Workers реализует OAuth 2.1 с PKCE:

• Обнаружение: /.well-known/oauth-authorization-server

• Регистрация: сначала CIMD, с /register как временным запасным вариантом Dynamic Client Registration

• Авторизация: /authorize (интеграция GitHub OAuth)

• Токен: /token (обмен кода авторизации с проверкой PKCE)

• Callback: /callback (обратный вызов GitHub OAuth)

Клиенты получают явный экран согласия transit:read. Гранты привязаны к каноническому ресурсу /mcp; токены доступа действуют не более 60 минут, токены обновления — не более 30 дней и ротируются при использовании, а токены-носители принимаются только в заголовке Authorization. Запасной вариант DCR прекращает действие 2027-06-30.

Версия 5.0 требует повторной авторизации для токенов без аудитории, токенов, привязанных к /sse, и клиентов, зарегистрированных в старом хранилище DCR. Существующие совместимые устаревшие JWT, привязанные к /mcp, перестают работать в более ранний из сроков: встроенный срок действия или 2026-11-30T00:00:00Z.

Поддерживаемые города

Сервер в настоящее время поддерживает следующие транспортные системы:

Доступные MCP-инструменты

Сервер предоставляет следующие инструменты через протокол MCP:

Всего: 13 MCP-инструментов (11 основных + 2 новых инструмента для NYC)

MCP Apps: Transit Board

Все 13 инструментов выше ссылаются на один автономный MCP App Transit Board. Хост, поддерживающий Apps, может отображать каждый результат в виде отдельного представления прибытия, обслуживания, станции/сети, маршрута или транспортного средства. Хосты без поддержки Apps получают тот же текстовый запасной вариант content и контракт structuredContent; улучшение не добавляет инструментов и не изменяет транзитные вызовы.

Скомпилированное приложение зафиксировано в public/apps/transit-board.html. Этот публичный ресурс содержит только код приложения: никакие результаты транзита, идентификационные данные, токены, секреты или значения конфигурации в него не встроены. Песочница не выполняет прямых сетевых запросов из браузера, не использует браузерное хранилище и не запрашивает разрешений браузера. Обновление — единственное взаимодействие с сервером, и оно идёт через хост к исходному разрешённому инструменту с его исходными аргументами.

Соберите и запустите детерминированный локальный набор приёмочных тестов Apps с помощью:

bun run build:apps
bun run test:apps

Смотрите docs/mcp-apps-verification.md для точной границы хоста, всех тринадцати сопоставлений представлений, покрытия Chromium и различия между рендерингом Apps и приёмкой запасного клиента. В этом выпуске Codex проверяет обнаружение MCP и обычные результаты инструментов как запасной клиент; встроенный рендеринг Apps в Codex не заявляется.

Технические детали

Протокол MCP

• Версия: MCP 2026-07-28, с обычной совместимостью со stateless-режимом MCP 2025

• Транспорт: Stateless Streamable HTTP через новый сервер SDK v2 для каждого запроса. Поддерживаются JSON и ответы SSE в рамках запроса; сессии протокола, возобновляемость и серверный push не рекламируются.

• Аутентификация: Cloudflare Workers OAuth Provider отвечает за обнаружение, проверку CIMD/DCR, PKCE, идентификаторы издателя RFC 9207, привязку ресурсов RFC 8707, метаданные защищённого ресурса RFC 9728, ротацию refresh-токенов, отзыв и хранение токенов провайдера.

• Форма результата инструментов: Каждый инструмент выдаёт structuredContent (типизированный объект, соответствующий outputSchema) наряду с устаревшим content[0].text (сериализованный JSON) для обратной совместимости.

• Аннотации инструментов: Каждый инструмент объявляет readOnlyHint, idempotentHint, openWorldHint, чтобы клиенты могли отображать безопасные действия.

• Предоставляемые возможности:

  • tools — 13 инструментов запросов транзита (DC + NYC)

  • resources — три URI-шаблона transit:// (станции, маршруты, инциденты)

  • prompts — три готовых шаблона (service-briefing, commute-planner, accessibility-check)

  • Ввод MRTR — современные клиенты получают input_required для неоднозначных станций; клиенты MCP 2025 получают детерминированные рекомендации по повторной попытке с точными идентификаторами станций

  • Уведомления о ходе выполнения: отправляются для get_all_stations, когда клиент соглашается через params._meta.progressToken

Транзитные API

WMATA (метро DC):

Сервер взаимодействует с официальными REST API WMATA. Подробности см. в документации разработчика WMATA:

• Прогнозы по станциям: информация о прибытии поездов в реальном времени

• Информация о станциях: названия, коды и местоположения станций

• Инциденты: сбои в обслуживании и уведомления

• Отключения лифтов и эскалаторов: информация о доступности

MTA (метро Нью-Йорка):

Сервер использует GTFS-Realtime каналы MTA. Публичные конечные точки API (без ключа API):

• Каналы реального времени: формат Protocol Buffers с интервалом обновления 30 секунд

• 8 отдельных каналов: охватывают все линии метро (1-7, A/C/E, B/D/F/M и т. д.)

• Расширения NYCT: идентификаторы поездов, назначения путей и информация о направлении

• Уведомления об обслуживании: встроены в сущности предупреждений GTFS-Realtime

Хостинг

• Платформа: Cloudflare Workers

• Статические ресурсы: public/ разворачивается через Cloudflare Workers Static Assets и привязывается как env.ASSETS; Worker сначала обрабатывает маршруты API/OAuth/MCP, затем делегирует запросы целевой страницы, документации, изображений и иконок привязке ресурсов.

• Хранилище:

  • Специфическое для окружения Cloudflare KV OAUTH_KV — гранты, токены и регистрации OAuth Provider

  • Нет активного хранения сессий протокола. Старый экспорт MetroMcpAgent и исходная миграция v1 остаются неактивными исключительно для отката.

• Среда выполнения: V8-изоляты с глобальным развёртыванием на периферии

Структура исходного кода

Кодовая база организована для поддержки транзита в нескольких городах с чётким разделением ответственности:

src/
├── index.ts              # Outer route normalization and Provider composition
├── public-handler.ts     # /info, OAuth UI, and static assets
├── route-normalizer.ts   # Exact /mcp admission and /sse URL alias
├── oauth/                # Provider configuration, GitHub consent, legacy bridge
├── mcp/                  # Stateless server factory, tools, resources, and prompts
├── mcp-agent.ts          # Inactive 4.x rollback class only
└── transit/              # WMATA and MTA clients with request cancellation

Ключевые архитектурные решения:

• Абстракция транзита: общий интерфейс TransitAPIClient упрощает добавление новых городов (BART, MBTA и т. д.)

• Маршрутизация по городам: один сервер обрабатывает все города через параметр city в вызовах инструментов MCP

• Нормализованные ответы: все транзитные клиенты возвращают стандартизированные типы TransitStation, TransitPrediction и TransitIncident

• Расширяемость: добавление нового города требует только реализации абстрактного класса клиента

Проверка и откат

Запустите полный локальный набор тестов с помощью bun run test. Аутентифицированный конформанс-раннер требует операторский кратковременный токен доступа Provider в переменных окружения процесса; он никогда не хранит токен и не передаёт его в аргументах командной строки:

export MCP_CONFORMANCE_TARGET_URL=https://metro-mcp-preview.anuragd.me/mcp
export MCP_CONFORMANCE_ALLOW_REMOTE=1
read -rsp 'Short-lived MCP token: ' MCP_CONFORMANCE_TOKEN && export MCP_CONFORMANCE_TOKEN
./scripts/run-conformance.sh
unset MCP_CONFORMANCE_TOKEN

См. docs/mcp-2026-verification.md для записи о приёмке основного протокола и docs/mcp-apps-verification.md для границы браузера Transit Board.

Откат восстанавливает предыдущую версию Worker и её предыдущие привязки. Не удаляйте исходное пространство имён Durable Object MetroMcpAgent и не добавляйте миграцию удаления в течение окна стабилизации; состояние сессии протокола является одноразовым, но сохранение класса и исходной миграции v1 обеспечивает возможность отката.

Откат Transit Board удаляет метаданные/ресурс Apps, исходный код браузера и зависимости сборки, оставляя транзитных провайдеров, OAuth, маршрутизацию, привязки и версию без изменений.

Участие

Вклад приветствуется! Не стесняйтесь:

• Сообщать об ошибках или запрашивать функции через GitHub Issues

• Отправлять pull request с улучшениями

• Делиться отзывами о реализации MCP

Лицензия

Лицензия MIT — подробности см. в файле LICENSE.

Сделано с ❤️ для сообщества метро Вашингтона, округ Колумбия