Travel Briefing (트래블 브리핑)

PlayMCP에 등록하기 위한 해외여행 준비 MCP 서버. 일본을 중심으로 중국·대만·동남아 6개국까지 비자·환율·안전경보·시즌·관광지·맞춤 일정과 국가별 문화·현지 생활 팁을 제공한다.

대회: AGENTIC PLAYER 10 (본선 유저 투표: 2026-08-31 ~ 09-28)

MCP 제공 정보

지원 국가: 일본(JP), 중국(CN), 대만(TW), 베트남(VN), 태국(TH), 필리핀(PH), 싱가포르(SG), 말레이시아(MY), 인도네시아(ID).

• 출발 전 준비: 비자, 전압/플러그, 시차, 통화, 긴급번호, 대사관 연락처

• 현지 문화·생활 팁: 국가별 예절, 소지품, 교통, 결제, 음식·물, 날씨 대응 요령

• 현재 안전 상황: 외교부 여행경보 단계와 발효일

• 환율: 한국수출입은행 매매기준율

• 항공 시즌 가이드: 성수기/비수기 판정과 스카이스캐너 비교 링크

• 관광지 큐레이션: 8개 도시(도쿄·오사카·교토·후쿠오카·삿포로·오키나와·히로시마·나라) × 5개 카테고리(문화·먹거리·자연·쇼핑·온천)

• D-day 체크리스트: 위 정보를 종합한 단톡방 붙여넣기용 카드

• 맞춤 일정 추천: 일정·예산·인원·목적과 정제된 여행 후기 기반 추천

Related MCP server: Travel Agent MCP Server

아키텍처 원칙

얇은 서버: 추론은 호스트 LLM(Kakao Tools)이 담당하고, 이 서버는 결정론적 조회·계산·렌더링만 처리한다. 서버 내부에서 LLM을 돌리지 않아 운영 비용이 낮다.

데이터 변동성 3계층 관리:

MCP 도구 7개

프로젝트 구조

travel-briefing-mcp/
├── README.md                    # 이 파일
├── travel_briefing_mcp.py       # MCP 서버 본체
├── tb_config.py                 # 설정·국가 데이터 로더
├── tb_api.py                    # 외부 API·TTL 캐시
├── tb_helpers.py                # 쿼리·마크다운 렌더러
├── tb_scheduler.py              # 캐시 워밍 스케줄러
├── destinations_jp.json         # 일본 관광지 큐레이션 데이터
├── embassies.json               # 대사관 연락처 스냅샷
├── config/                      # API·TTL·어휘 설정
├── data/                        # 9개국 정적 데이터
├── test_playmcp_compliance.py   # 등록 가이드 자동 검증
├── pyproject.toml / uv.lock     # Python 의존성
├── Dockerfile                   # 배포 이미지
├── .env.example                 # 환경변수 템플릿
├── .gitignore
└── .claude/
    └── rules/
        ├── playmcp-guide.md     # PlayMCP 등록 가이드 요약
        ├── mcp-schema.md        # 외부 API 스키마와 응답 매핑
        └── curation.md          # 큐레이션 데이터 편집 규칙

시작하기

1. 환경 준비

git clone <repo-url>
cd travel-briefing-mcp
uv sync --frozen
cp .env.example .env

2. API 키 발급

다음 API 키를 .env에 설정한다. 키가 없거나 외부 API가 실패하면 가능한 범위에서 정적 정보 또는 안내 문구로 폴백한다.

• 외교부 (공공데이터포털): 입국허가요건 + 여행경보 (인증키 공유)

• 한국수출입은행: 환율

• 네이버 검색 API: 맞춤 일정의 여행 후기 검색

발급받은 키를 .env 에 채운다.

3. 로컬 실행

uv run python travel_briefing_mcp.py

http://127.0.0.1:8000/mcp에서 stateless Streamable HTTP 서버가 기동된다. stdio와 SSE 전송은 제공하지 않는다.

4. MCP Inspector 검증

배포 전 PlayMCP 가이드 준수 여부를 검증한다.

먼저 서버를 실행한 뒤 다른 터미널에서 npx @modelcontextprotocol/inspector를 실행한다. Inspector에서 Transport를 Streamable HTTP, URL을 http://127.0.0.1:8000/mcp로 지정하고 Initialize와 List Tools를 확인한다.

저장소에 포함된 자동 점검도 실행한다.

uv run python -m unittest -v test_playmcp_compliance.py

개발 규칙

프로젝트에 코드를 추가·수정할 때는 아래를 준수한다.

• 서버명·툴명에 "kakao" 를 어떤 형태로도 넣지 않는다 (등록 반려 사유)

• 툴 개수는 7개를 유지한다 (가이드 권장 3~10 범위)

• 툴 annotations 5종(title, readOnlyHint, destructiveHint, openWorldHint, idempotentHint)을 전부 지정한다

• 툴 description 은 영문으로 작성하고 "Travel Briefing(트래블 브리핑)" 을 병기한다

• 응답은 정제된 마크다운으로 반환하고, 외부 API raw JSON 을 그대로 돌려주지 않는다

• 외부 API 호출은 반드시 TTL 캐시를 통한다 (p99 3,000ms 요건)

• 서버 내부에서 LLM 을 실행하지 않는다

• 응답에 광고 유도를 넣지 않는다

세부 규칙은 .claude/rules/ 의 개별 파일을 참조한다.

배포

카카오 클라우드에 컨테이너로 배포하며, 공개 HTTPS 도메인이 필요하다.

환경변수는 .env 파일 대신 카카오 클라우드의 환경변수/시크릿 매니저로 주입한다. Docker 이미지에 .env 를 포함시키지 않는다.

배포 후 PlayMCP 개발자 콘솔에서 등록하고 심사를 받는다.

라이선스와 데이터 출처

• 외교부 여행경보/입국허가요건: 공공저작물 출처표시 (제1유형)

• 한국수출입은행 환율: 이용허락범위 제한 없음

• 관광지 큐레이션·국가별 문화 및 생활 팁: 프로젝트 자체 편찬 (외교부·각국 정부/관광청 안내 교차 검토, 수정·기여 환영)

로드맵

• v1: 일본 중심 여행 준비, 도구 6개

• v2 (현재): 중국·대만·동남아 확장과 맞춤 일정 추천, 도구 7개

• v3: 환율 30일 추이, 도시별 이벤트 정보

기여

관광지 큐레이션 수정·추가는 대상 국가의 curation/destinations_{국가코드}.json 을 편집해 PR 을 올린다. 일본 파일은 외부 JSON 갱신 주기에 따라 반영되며, 그 외 국가의 번들 큐레이션은 재배포 시 반영된다.