기차표 조회 MCP 서버（FastMCP）

FastMCP로 구현된 기차표/고속철도 차편 조회 서비스로, 원격 MCP 도구로서 모든 Agent(예: deepagents, LangGraph, Claude 등)에서 호출할 수 있습니다.

기능

하나의 도구 함수: query_train_tickets(from_station, to_station, date)

• 두 역 사이의 특정 날짜에 대한 차편, 시간, 소요 시간, 예약 가능 상태, 잔여 티켓 상황을 조회합니다.

• 데이터 소스: 12306 공개 조회 인터페이스(실제 데이터); 인터페이스가 리스크 관리에 의해 차단될 경우 자동으로 시뮬레이션 데이터로 전환하고 출처를 명확히 표시하여 언제든지 링크를 시연할 수 있습니다.

Related MCP server: THSRC MCP Server

로컬 실행

pip install -r requirements.txt
python server.py        # 启动 streamable-http 服务，默认 http://127.0.0.1:8000

MCP 클라이언트 구성(로컬 연동 디버깅):

{
  "mcpServers": {
    "train": {
      "url": "http://127.0.0.1:8000/mcp/",
      "transport": "streamable_http"
    }
  }
}

모델스코프 MCP 광장에 배포(중요 단계)

1. 이 저장소를 GitHub에 푸시합니다.

2. modelscope.cn/mcp를 열어 로그인 → **「MCP 생성」**을 클릭합니다.

3. 생성 유형은 **「GitHub 빠른 생성」**을 선택하고, 호스팅 유형은 **「호스팅 가능 배포」**를 선택합니다.

4. 영문/중문 이름, 소스 주소(GitHub 저장소 URL)를 입력하고 플랫폼 안내에 따라 구성을 완료합니다.

5. 제출 후 플랫폼에서 접근 주소를 생성합니다: https://mcp.api-inference.modelscope.net/<你的ID>/sse 또는 /mcp (장기 유효 설정 가능)

6. 해당 주소를 Agent 프로젝트의 MCP 구성에 다시 입력하면 됩니다.

참고: 플랫폼은 호스팅 프로젝트에 시작 방식 요구사항이 있습니다(일반적으로 Python + HTTP 서비스 시작 필요). 배포가 실패할 경우 플랫폼 안내에 따라 진입점을 조정하세요(예: run 스크립트 또는 환경 변수 제공).

데이터 소스 설명

• 12306은 공식 오픈 API가 없으며, 본 프로젝트는 공개 조회 인터페이스(kyfw.12306.cn/otn/leftTicket)를 사용합니다. 로그인 없이 조회 가능하며, 개인 학습 연구 용도로만 사용됩니다.

• 인터페이스는 리스크 관리(간헐적 302)가 있으며, 코드는 세션 쿠키 + 시뮬레이션 데이터로 대비되어 있습니다.

• 더 안정적인 데이터가 필요하면 _fetch_12306을 타사 데이터 소스로 직접 교체할 수 있습니다(플러그인 가능).

디렉토리

• server.py — FastMCP 서비스 메인 프로그램

• test_client.py — 로컬 연동 디버깅 스크립트(도구 함수 직접 호출 + MCP 프로토콜 테스트)

• requirements.txt — 의존성