Yeosugaja(여수가자) Travel MCP

A read-only MCP server that exposes verified Yeosu travel itineraries, curated POIs, and transport schedules — sourced from the daily R2 bundle cache the app already produces. Built to be registered on Kakao PlayMCP and consumed by MCP clients (Claude, ChatGPT dev mode, OpenClaw, …).

It is a thin, stateless Cloudflare Worker: on each tool call it loads {region}/latest.json from R2 (60s in-isolate memo) and answers from it. It never touches the API or the database, so periodic bundle regeneration cannot affect it — worst case is a few minutes of staleness.

Architecture

API batch  ──►  R2  {region}/latest.json  ──►  this Worker (MCP)  ──►  MCP client
generate_daily_bundle    (atomic, gzipped)      read-only, stateless     (PlayMCP)

Tools (7)

tool	purpose
list_itineraries	list verified itineraries, filter by mbti/transport/duration/party/season
get_itinerary	full time-ordered timeline of one itinerary
recommend_itinerary	top matches for an MBTI, ranked by confidence
search_pois	search POIs by text/tag/grade/indoor/signature
get_poi	full detail for one POI
get_transport	ferry / airport / train / bus schedules
get_region_info	weather, event banner, dining rules, bundle freshness

All tools are readOnlyHint: true, non-destructive, idempotent, closed-world.

사용 예시 프롬프트 (Example prompts)

이 MCP를 연결한 에이전트(Claude·ChatGPT·OpenClaw 등)에 자연어로 말하면 아래처럼 도구가 불린다.

단일 도구

• "INFP한테 맞는 여수 하루 코스 추천해줘" → recommend_itinerary(mbti=INFP)
• "여수 당일치기 일정 목록 보여줘, 도보로 다니는 걸로" → list_itineraries(duration_type=1day, transport=walk)
• "그 코스(it1) 시간표 자세히 풀어줘" → get_itinerary(id=it1)
• "여수에서 실내 문화 명소 찾아줘" → search_pois(tag=culture, indoor_outdoor=indoor)
• "오동도 정보 알려줘" → search_pois(query=오동도) → get_poi(id=…)
• "여수 들어가는 배편 시간표 알려줘" → get_transport(mode=ferry)
• "지금 여수 날씨랑 진행 중인 이벤트 있어?" → get_region_info()

여러 도구 조합 (이 MCP 안에서)

• "ENFP 커플 여름 여수 코스 추천하고, 1등 코스 시간표까지 보여줘" → recommend_itinerary(mbti=ENFP, party_type=couple, season=summer) → get_itinerary(id=…)
• "비 오는 날 가기 좋은 여수 실내 코스랑 그 안 장소들 상세 정리해줘" → get_region_info() → search_pois(indoor_outdoor=indoor) → get_poi(...)
• "차 없이 뚜벅이로 갈 수 있는 시그니처 명소 위주 하루 코스 짜줘" → list_itineraries(transport=walk) + search_pois(signature_only=true) → get_itinerary(...)

PlayMCP(카카오 도구함)와 함께 — 클라이언트 계층 합성

이 MCP + 카카오 서버(맵/톡캘린더/카톡 나에게 보내기)를 같은 도구함에 함께 연결한 경우.

• "INTJ 여수 코스 추천받아서 톡캘린더에 이번 주 토요일 일정으로 넣어줘" → recommend_itinerary(mbti=INTJ) → (카카오) 톡캘린더 등록
• "추천 코스를 카톡으로 나한테 보내줘" → get_itinerary(...) → (카카오) 나에게 보내기
• "첫 장소를 카카오맵으로 길찾기 열어줘" → get_poi(...) → (카카오) 지도 길찾기

팁: MBTI·계절·이동수단·동행(solo/couple/family/group)을 함께 말하면 더 정확히 매칭된다.

PlayMCP compliance (dev guide 2026-06-12)

Requirement	This server
Streamable HTTP only	✅ stateless Streamable HTTP at POST /mcp
Remote, public URL	✅ Cloudflare Worker
Stateless (no session)	✅ single request/response, no session id
MCP version 2025-03-26 … 2025-11-25	✅ protocolVersion: 2025-03-26
3–10 tools (≤20)	✅ 7
name/description/inputSchema/annotations present	✅
all 5 annotation hints set	✅
English description incl. service name (EN/KO)	✅ "…from Yeosugaja(여수가자)"
no "kakao" in server/tool names	✅
OAuth only if personal data	✅ none needed (public, read-only)
minimal, cleaned (markdown) results	✅
p99 ≤ 3s, avg ≤ 100ms	✅ R2 + memo cache
MCP Inspector pre-check	see below

Develop

cd apps/yeosugaja-mcp
npm install
npm run typecheck
npm run dev            # local Worker at http://localhost:8787/mcp

Local smoke test (JSON-RPC over Streamable HTTP):

curl -s http://localhost:8787/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

curl -s http://localhost:8787/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"recommend_itinerary","arguments":{"mbti":"INFP"}}}'

MCP Inspector (required before PlayMCP submission)

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP   URL: http://localhost:8787/mcp (or the deployed URL)

Verify initialize, tools/list, and each tools/call succeed.

Deploy

npx wrangler login
npm run deploy         # → https://yeosugaja-mcp.<subdomain>.workers.dev/mcp

Optional, recommended:

• R2 binding — uncomment the r2_buckets block in wrangler.jsonc and set the real bucket name (same as the API's R2_BUCKET_NAME) for edge-local reads. Without it, the Worker falls back to the public BUNDLE_PUBLIC_BASE URL.
• Custom domain — uncomment routes for a stable registration URL.

Register on PlayMCP

1. PlayMCP → 개발자 콘솔 → 새로운 MCP 서버 등록.
2. Server URL: the deployed …/mcp endpoint.
3. No OAuth (read-only public data) — leave auth unset.
4. Submit for review.

Notes / limits

• Read-only over the cache. Only verified itineraries and the yeosu region are in the bundle. Live per-user generation would require calling the API engine and is intentionally out of scope here.
• Schema contract. If the bundle's field names change, update src/bundle.ts and src/tools.ts; handlers already guard missing fields defensively.
• Kakao features (map, calendar, KakaoTalk share) are composed at the client layer: the user connects this MCP and the relevant PlayMCP tool together and the agent chains them. This server does not call Kakao services directly.