🚇 Metro MCP

미국 대중교통 시스템(DC 메트로 및 NYC 지하철)용 Model Context Protocol 서버

여러 미국 대중교통 시스템을 지원하는 통합 원격 Model Context Protocol(MCP) 서버입니다. 현재 워싱턴 DC 메트로(WMATA)와 뉴욕시 지하철(MTA)을 지원합니다. Claude Desktop, Cursor, Codex 및 Streamable HTTP MCP 서버를 지원하는 모든 클라이언트와 원활하게 통합되도록 설계되었습니다.

빠른 링크: 빠른 시작 • 할 수 있는 일 • Transit Board • 배포 • 클라이언트 통합

할 수 있는 일

Claude Desktop 또는 MCP 호환 클라이언트에서 DC 메트로 또는 NYC 지하철에 대해 자연어로 질문하세요:

🚆 실시간 대중교통 정보

워싱턴 DC:

• "Dupont Circle에서 다음 Red Line 열차는 언제 오나요?"

• "이용 가능한 버스 노선은 무엇인가요?"

• "Dupont Circle 근처 버스 정류장 찾기"

• "지금 30N 버스는 모두 어디에 있나요?"

• "정류장 1001195에서 다음 버스는 언제 오나요?"

• "메트로 시스템에서 현재 운행 중인 모든 열차 보기"

• "지금 Blue Line에 지연이 있나요?"

• "Union Station의 모든 엘리베이터가 작동 중인가요?"

뉴욕시:

• "Times Square에서 다음 1번 열차는 언제 오나요?"

• "A/C 라인에 지연이 있나요?"

• "Grand Central에 도착하는 열차는 무엇인가요?"

• "A 열차는 무엇이고 어디로 가나요?"

• "Times Square에서 걸어서 갈 수 있는 인근 역은 어디인가요?"

• "Times Square 플랫폼 사이를 걷는 데 얼마나 걸리나요?"

🗺️ 역 정보 및 내비게이션

워싱턴 DC:

• "Smithsonian 메트로 역은 어디에 있나요?"

• "Green Line의 모든 역 보기"

뉴욕시:

• "Union Square 역은 어디에 있나요?"

• "NYC 지하철의 496개 모든 역 보기"

• "Times Square와 연결되는 역은 어디인가요?"

• "급행과 완행 열차의 차이점 설명"

♿ 접근성

워싱턴 DC (엘리베이터 고장):

• "여기에서 National Airport 사이에 엘리베이터 고장이 있나요?"

• "지금 엘리베이터가 작동하는 DC 메트로 역은 어디인가요?"

🔔 서비스 모니터링

두 도시:

• "지금 NYC에 대중교통 지연이 있나요?"

• "DC 메트로 Orange Line이 정상적으로 운행되나요?"

• "DC 메트로와 NYC 지하철의 서비스 품질 비교"

📊 시스템 정보

워싱턴 DC:

• 좌표가 포함된 모든 메트로 역의 전체 목록

• 6개 메트로 라인(Red, Blue, Orange, Silver, Green, Yellow)에 대한 정보

뉴욕시:

• 전체 범위: 좌표가 포함된 NYC 지하철의 496개 모든 역

• 환승 정보: 연결된 역 간 도보 시간 (환승이 있는 87개 역)

• 노선 설명: 29개 모든 노선의 상세 서비스 패턴 (급행 vs 완행, 운행 시간)

• 플랫폼 명확성: 방향별 플랫폼 설명 (예: "127N" = Times Square 북행)

Related MCP server: marta-mcp

빠른 시작

공용 서버 사용

가장 빠른 시작 방법은 호스팅된 인스턴스를 사용하는 것입니다:

1. MCP 클라이언트 열기

2. 이 URL 추가: https://metro-mcp.anuragd.me/mcp

3. "연결" 클릭 후 GitHub로 인증

4. DC 메트로 또는 NYC 지하철에 대해 질문 시작

직접 배포

자체 인스턴스를 실행하고 싶으신가요? 아래 배포 섹션을 참조하세요.

배포

사전 요구 사항

• WMATA API 키 (필수)

• Cloudflare 계정 (무료 티어로 충분)

• 패키지 관리를 위한 Bun

• Wrangler 및 Workerd Vitest 풀용 Node.js; Bun은 유일한 패키지 관리자 및 lockfile 소유자로 유지

• GitHub OAuth 앱 (인증용)

환경 설정

bun.lock에 기록된 것만 정확히 설치하세요:

bun install --frozen-lockfile

로컬 개발을 위해 콜백이 정확히 http://localhost:8787/callback인 전용 GitHub OAuth 앱을 만드세요. 그런 다음 표준 .dev.vars.example 템플릿을 복사하고 모든 replace-with-... 자리 표시자를 교체한 후 Wrangler를 시작하세요:

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

템플릿의 http://localhost:8787 오리진, localhost 호스트/오리진 허용 목록, 콜백 및 ENVIRONMENT=development 값을 함께 유지하세요. Wrangler의 기본 로컬 모드에서 구성된 OAUTH_KV 바인딩은 .wrangler 아래의 로컬 비프로덕션 스토리지를 사용합니다. 배포된 프로덕션 또는 프리뷰 네임스페이스를 읽거나 쓰지 않습니다. 일반적인 로컬 개발에는 --remote를 추가하지 마세요.

각 배포 환경에 대해 하나의 OAuth Provider 네임스페이스를 만들고 해당 ID를 해당 OAUTH_KV 바인딩에 넣으세요:

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

프로덕션과 프리뷰는 또한 별개의 GitHub OAuth 앱을 사용해야 합니다. 각 콜백을 ${MCP_PUBLIC_ORIGIN}/callback으로 구성하세요. 프리뷰에 프로덕션 앱이나 OAuth KV를 재사용하지 마세요. 각 환경은 다음을 설정합니다:

• 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는 서명된 MRTR 상태에만 사용되는 안정적인 환경별 32바이트 이상 키입니다. 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

프리뷰에 대해 동일한 네 개의 비밀 이름을 독립적으로 설정하세요. 명명된 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

Claude Code에서 표준 Streamable HTTP 엔드포인트를 사용하세요:

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는 권한 부여 전에 표준 /mcp로 다시 작성되는 URL 별칭입니다.

• 레거시 HTTP+SSE는 제거되었습니다. /sse 또는 /mcp에 대한 GET 및 DELETE, 세션 메시지 URL 및 /sse/는 405를 반환합니다.

• OAuth 대상 및 검색은 항상 https://metro-mcp.anuragd.me/mcp를 사용합니다. /sse는 OAuth 리소스가 아닙니다.

OAuth 엔드포인트

Workers OAuth Provider는 PKCE와 함께 OAuth 2.1을 구현합니다:

• 검색: /.well-known/oauth-authorization-server

• 등록: CIMD 우선, /register는 임시 Dynamic Client Registration 대체

• 권한 부여: /authorize (GitHub OAuth 통합)

• 토큰: /token (PKCE 검증을 통한 인증 코드 교환)

• 콜백: /callback (GitHub OAuth 콜백)

클라이언트는 명시적인 transit:read 동의 화면을 받습니다. 권한은 표준 /mcp 리소스에 바인딩됩니다. 액세스 토큰은 최대 60분, 새로 고침 토큰은 최대 30일 동안 유효하며 사용 시 회전합니다. Bearer 토큰은 Authorization 헤더에서만 허용됩니다. DCR 대체는 2027-06-30에 종료됩니다.

버전 5.0은 대상이 없는 토큰, /sse에 바인딩된 토큰 및 이전 DCR 저장소에 등록된 클라이언트에 대해 재인증을 요구합니다. /mcp에 바인딩된 기존 호환 레거시 JWT는 포함된 만료 시간과 2026-11-30T00:00:00Z 중 더 이른 시점에 작동이 중지됩니다.

지원 도시

서버는 현재 다음 대중교통 시스템을 지원합니다:

사용 가능한 MCP 도구

서버는 MCP 프로토콜을 통해 다음 도구를 노출합니다:

총 13개 MCP 도구 (11개 핵심 + 2개 새로운 NYC 전용 도구)

MCP 앱: Transit Board

위의 13개 도구는 모두 하나의 자체 포함 Transit Board MCP 앱을 참조합니다. Apps 지원 호스트는 각 결과를 전용 도착, 서비스, 역/네트워크, 노선 또는 차량 보기로 렌더링할 수 있습니다. Apps를 지원하지 않는 호스트는 동일한 content 텍스트 대체 및 structuredContent 계약을 받습니다. 이 개선은 도구를 추가하거나 대중교통 호출을 변경하지 않습니다.

컴파일된 앱은 public/apps/transit-board.html에 커밋되어 있습니다. 이 공용 자산에는 애플리케이션 코드만 포함됩니다. 대중교통 결과, ID, 토큰, 비밀 또는 구성 값이 포함되지 않습니다. 샌드박스된 보기는 직접 브라우저 네트워크 요청을 하지 않으며, 브라우저 저장소를 사용하지 않으며, 브라우저 권한을 요청하지 않습니다. 새로 고침은 유일한 서버 상호 작용이며 호스트를 통해 원래 인수와 함께 원래 허용 목록 도구로 전달됩니다.

결정적 로컬 Apps 수용 테스트 스위트를 빌드하고 실행하세요:

bun run build:apps
bun run test:apps

정확한 호스트 경계, 13개 보기 매핑, Chromium 범위 및 Apps 렌더링과 대체 클라이언트 수용의 차이에 대해서는 docs/mcp-apps-verification.md를 참조하세요. 이 릴리스에서 Codex는 대체 클라이언트로 MCP 검색 및 일반 도구 결과를 검증합니다. Codex의 인라인 Apps 렌더링은 주장되지 않습니다.

기술 세부 사항

MCP 프로토콜

• 버전: MCP 2026-07-28, 일반 MCP 2025 무상태(stateless) 호환성 포함

• 전송: 각 요청마다 새로운 SDK v2 서버를 통한 무상태 Streamable HTTP. JSON 및 요청 범위 SSE 응답이 지원되며, 프로토콜 세션, 재개 가능성, 서버 푸시는 광고되지 않습니다.

• 인증: Cloudflare Workers OAuth Provider가 검색(discovery), CIMD/DCR 검증, PKCE, RFC 9207 발급자 식별자, RFC 8707 리소스 바인딩, RFC 9728 보호 리소스 메타데이터, 갱신 토큰 순환, 폐기, Provider 토큰 저장을 담당합니다.

• 도구 결과 형태: 모든 도구는 하위 호환성을 위해 기존 content[0].text(직렬화된 JSON)와 함께 structuredContent(outputSchema와 일치하는 타입 객체)를 출력합니다.

• 도구 어노테이션: 모든 도구는 클라이언트가 안전한 작업 표시를 렌더링할 수 있도록 readOnlyHint, idempotentHint, openWorldHint를 선언합니다.

• 노출되는 기능:

  • tools — 13개의 대중교통 조회 도구(DC + NYC)

  • resources — 세 개의 transit:// URI 템플릿(역, 노선, 사고)

  • prompts — 세 개의 사전 정의 템플릿(서비스 브리핑, 통근 플래너, 접근성 확인)

  • MRTR 입력 — 최신 클라이언트는 모호한 역에 대해 input_required를 수신하고, MCP 2025 클라이언트는 정확한 역 ID가 포함된 결정적 재시도 안내를 수신합니다.

  • 진행 알림: 클라이언트가 params._meta.progressToken을 통해 옵트인할 때 get_all_stations에 대해 전송됩니다.

대중교통 API

WMATA(DC 메트로):

서버는 공식 WMATA REST API와 연동합니다. 자세한 내용은 WMATA 개발자 문서를 참조하세요:

• 역 도착 예측: 실시간 열차 도착 정보

• 역 정보: 역 이름, 코드, 위치

• 사고: 서비스 중단 및 안내

• 엘리베이터/에스컬레이터 고장: 접근성 정보

MTA(NYC 지하철):

서버는 MTA의 GTFS-Realtime 피드를 사용합니다. 공개 API 엔드포인트(API 키 불필요):

• 실시간 피드: 30초 업데이트 간격의 Protocol Buffers 형식

• 8개의 개별 피드: 모든 지하철 노선(1-7, A/C/E, B/D/F/M 등) 포함

• NYCT 확장: 열차 ID, 선로 배정, 방향 정보

• 서비스 알림: GTFS-Realtime 알림 엔티티에 포함

호스팅

• 플랫폼: Cloudflare Workers

• 정적 자산: public/은 Cloudflare Workers Static Assets을 통해 배포되며 env.ASSETS로 바인딩됩니다. Worker는 API/OAuth/MCP 라우트를 먼저 처리한 후 랜딩 페이지, 문서, 이미지, 아이콘 요청을 자산 바인딩에 위임합니다.

• 저장소:

  • 환경별 Cloudflare KV OAUTH_KV — OAuth Provider 권한 부여, 토큰, 등록 정보

  • 활성 프로토콜 세션 저장소 없음. 기존 MetroMcpAgent 내보내기와 원래 v1 마이그레이션은 롤백 전용으로만 비활성 상태로 유지됩니다.

• 런타임: 글로벌 엣지 배포가 적용된 V8 격리(isolate)

소스 구조

코드베이스는 다중 도시 대중교통 지원을 위해 관심사가 명확히 분리된 구조로 구성되어 있습니다:

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 등)를 쉽게 추가할 수 있습니다.

• 도시 라우팅: 단일 서버가 MCP 도구 호출의 city 매개변수를 통해 모든 도시를 처리합니다.

• 정규화된 응답: 모든 대중교통 클라이언트는 표준화된 TransitStation, TransitPrediction, TransitIncident 타입을 반환합니다.

• 확장성: 새 도시를 추가하려면 추상 클라이언트 클래스를 구현하기만 하면 됩니다.

검증 및 롤백

bun run test로 전체 로컬 테스트 스위트를 실행하세요. 인증된 적합성 러너(conformance runner)는 프로세스 환경에 운영자가 확보한 단기 유효 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를, Transit Board 브라우저 경계는 docs/mcp-apps-verification.md를 참조하세요.

롤백은 이전 Worker 버전과 이전 바인딩을 복원합니다. 안정화 기간 동안 원래 MetroMcpAgent Durable Object 네임스페이스를 삭제하거나 삭제 마이그레이션을 추가하지 마십시오. 프로토콜 세션 상태는 폐기 가능하지만, 클래스와 원래 v1 마이그레이션을 유지하면 롤백이 가능해집니다.

Transit Board를 롤백하면 Apps 메타데이터/리소스, 브라우저 소스 및 빌드 종속성이 제거되지만 대중교통 제공자, OAuth, 라우팅, 바인딩, 버전은 변경되지 않습니다.

기여

기여는 언제나 환영합니다! 다음과 같은 방법으로 참여할 수 있습니다:

• GitHub Issues를 통해 버그를 신고하거나 기능을 요청하세요.

• 개선 사항이 포함된 풀 리퀘스트를 제출하세요.

• MCP 구현에 대한 피드백을 공유하세요.

라이선스

MIT 라이선스 — 자세한 내용은 LICENSE 파일을 참조하세요.

워싱턴 DC 메트로 커뮤니티를 위해 ❤️로 제작되었습니다.