transit-mcp-server

511.org SF Bay Open Data 대중교통 API용 MCP 서버입니다. LLM에 실시간 베이 에어리어 대중교통 데이터(운영 기관, 노선, 정류장, 실시간 출발, 차량 위치, 서비스 알림)를 제공하며, BART, Muni, AC Transit, Caltrain, VTA 및 511에 보고하는 모든 운영 기관을 포함합니다.

6개의 도구, 모두 읽기 전용입니다.

요구 사항

• Node.js 18+

• https://511.org/open-data/token에서 무료 511 API 토큰

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회 요청을 모든 엔드포인트에 걸쳐 공유합니다. 이는 도구 사용 방식을 결정할 만큼 낮습니다.

• 운영 기관 코드와 정류장 코드는 한 번 확인한 후 재사용하세요. 변경되지 않습니다.

• operator_id 없이 transit_list_service_alerts를 사용하는 것이 좋습니다. 한 번 호출로 모든 기관을 커버합니다.

• transit_next_departures를 루프로 폴링하지 마세요. 출퇴근 시간에 10번 확인하면 시간당 예산의 6분의 1을 소모합니다.

transit_list_operators는 511이 모든 응답에 포함하는 RateLimit-Remaining 헤더에서 남은 예산을 읽어 보고합니다. 할당량을 초과하면 429가 반환됩니다. 증가를 요청하려면 transitdata@511.org에 문의하세요.

배포 (Claude 모바일 / 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는 언제인가요?" → operator_id="SF", query="judah"로 transit_find_stops를 호출하여 정류장 코드를 얻은 다음, 해당 코드와 line="N"으로 transit_next_departures를 호출합니다.

"BART가 정상적으로 운행 중인가요?" → operator_id="BA"로 transit_list_service_alerts를 호출합니다.

"출퇴근 길에 문제가 있나요?" → 운영자 없이 transit_list_service_alerts를 호출합니다. 한 번 호출로 모든 베이 에어리어 기관을 훑습니다.

"지금 열차는 어디에 있나요?" → operator_id="BA"로 transit_list_vehicles를 호출합니다.

설계 노트

구조적으로 읽기 전용입니다. 511은 쓰기 엔드포인트를 제공하지 않으며, 모든 도구는 readOnlyHint: true를 포함합니다. 테스트가 이를 확인합니다.

엔드포인트별로 매핑되는 하나의 operator_id. 511은 정적 엔드포인트에서는 이 매개변수를 operator_id라고 부르고, 실시간 엔드포인트에서는 동일한 값에 대해 agency라고 부릅니다. 여기의 모든 도구는 operator_id를 받고 클라이언트가 매핑합니다. 이 분리는 호출자의 문제가 아니라 511의 문제입니다.

두 실시간 엔드포인트는 실제로 다른 봉투를 가집니다. StopMonitoring에는 Siri 루트 래퍼가 없습니다. VehicleMonitoring에는 있습니다. 공개된 사양은 둘 다에 하나를 보여주지만, 사양이 잘못되었으며 문서화된 형태로 파싱하면 출발 정보에 대해 아무것도 반환되지 않습니다. 둘 다 실제 API가 내보내는 대로 파싱되며, 각각을 고정하는 테스트가 있습니다.

도착 정보는 카운트다운을 포함하지만 출발 정보는 아닙니다. ExpectedDepartureTime은 사실상 모든 실제 행에서 null이므로, 이를 기준으로 카운트다운을 만들면 서비스가 없는 정류장으로 표시됩니다. ExpectedArrivalTime이 신뢰할 수 있는 필드입니다.

UTF-8 BOM은 파싱 전에 제거됩니다. 511은 JSON 본문 앞에 U+FEFF를 붙이므로, 완벽하게 유효한 페이로드에서 순진한 JSON.parse가 예외를 던집니다. 인증 실패는 BOM 없는 일반 텍스트이므로, 상태 확인 후에 제거가 이루어집니다.

숫자와 불리언처럼 보이는 값은 종종 그렇지 않습니다. 좌표와 방위는 JSON 문자열로 도착하고, VehicleAtStop은 문자열 "false"이며, null이 의미되는 곳에 ""가 사용됩니다. 무작정 강제 변환하면 누락된 위치가 아프리카 연안의 유효해 보이는 0,0이 되므로, 빈 문자열은 0이 아닌 부재로 처리됩니다.

에포크 제로 센티널은 타임스탬프가 아닙니다. 예정되었지만 차량이 배정되지 않은 운행은 RecordedAtTime이 1970-01-01T00:00:00Z로 보고됩니다. "56년 전에 기록됨"이 아니라 "아직 차량이 배정되지 않음"으로 렌더링됩니다.

GTFS-Realtime 열거형이 디코딩됩니다. 511의 JSON 알림 렌더링은 XML 렌더링이 SignificantDelays라고 말하는 곳에서 "effect": 3을 내보냅니다. 원인과 효과 모두 단어로 다시 매핑됩니다.

511 내부 의사 기관은 필터링됩니다. 5E, 5F, 5O, 5S는 511 Emergency, Flap Sign, Operations, Staff입니다. 이들은 서비스 데이터 없이 운영자 목록에 나타납니다.

모든 것은 태평양 시간입니다. 타임스탬프는 UTC로 도착하고 America/Los_Angeles로 렌더링되므로, 일광 절약 시간은 모델이 매년 두 번 처리하는 대신 여기서 한 번 처리됩니다. 511 자체의 TimeZone 필드가 모든 베이 에어리어 기관에 대해 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는 JSON 옵션 없이 protobuf 전용이므로 의도적으로 노출하지 않습니다. 이를 지원하려면 SIRI 엔드포인트가 이미 커버하는 데이터에 protobuf 의존성을 추가해야 합니다.

프로젝트 구조

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 래퍼, 문자열화된 불리언과 좌표, 에포크 센티널, 일반 텍스트 오류 본문)을 의도적으로 재현하는 로컬 목(mock)에 대해 실행됩니다. 순진한 클라이언트가 정확히 그런 것들에서 실수하기 때문입니다.