Rush Gift

약속 장소로 이동 중인 사용자를 위해 지금 살 수 있는 선물과 픽업 동선을 추천하는 PlayMCP 제출용 MCP 서버 프로젝트입니다.

Concept

"오다 주웠다처럼 자연스럽게 건넬 수 있도록, AI가 선물 후보와 픽업 경로를 한 번에 짜주는 MCP"

사용자는 출발지, 목적지, 도착 제한 시간, 예산, 관계, 상황을 자연어로 말합니다. AI는 이 MCP의 도구를 호출해 선물 후보, 픽업 매장, 경유 추가 시간, 실패 리스크, 짧은 메시지를 함께 제안합니다.

Why MCP

일반 AI 답변은 "좋아 보이는 선물"을 말할 수 있지만, 지금 상황에서 실제로 들를 수 있는지 판단하지 못합니다. 이 MCP는 추천을 다음 데이터와 계산으로 검증합니다.

• 선물 후보 데이터
• 픽업 가능 매장 데이터
• 출발지-매장-목적지 경유 시간
• 약속 시간까지 남은 여유
• 관계/상황/예산별 실패 리스크

Current Strategy

카카오 선물하기 MCP/API가 없더라도 동작하도록 fixture provider로 시작합니다. 나중에 카카오 연동이 가능해지면 provider 구현만 교체합니다.

MCP Tools
  -> RushGiftService
    -> GiftProvider
    -> PickupStoreProvider
    -> PlaceProvider
    -> RouteProvider

초기 provider:

• FixtureGiftProvider: 샘플 선물 데이터
• FixturePickupStoreProvider: 샘플 픽업 매장 데이터
• MockRouteProvider: 좌표 기반 경유 시간 추정

교체 대상 provider:

• KakaoGiftProvider
• KakaoLocalProvider
• KakaoMobilityRouteProvider
• WebSearchGiftProvider

Tools

• plan_rush_gift: 상황을 받아 추천, 픽업, 경유 시간, 메시지를 한 번에 반환
• recommend_gifts: 관계/상황/예산 기준으로 선물 후보 추천
• find_pickup_options: 선물 후보별 픽업 매장과 경유 가능성 계산
• draft_gift_message: 관계와 상황에 맞는 짧은 카드 메시지 생성

PlayMCP

Submission endpoint:

https://rush-gift-mcp.vercel.app/mcp

Health check:

https://rush-gift-mcp.vercel.app/health

PlayMCP gateway:

https://playmcp.kakao.com/mcp

The submission endpoint is this server. The PlayMCP gateway is Kakao's proxy for approved MCP servers in a user's toolbox and requires a PlayMCP access token.

Demo Prompt

지금 강남역에서 판교역으로 여자친구 생일 약속 가는 중이야.
35분 안에 도착해야 하고 예산은 3만원이야.
가는 길에 픽업 가능한 선물 추천해줘.

30분으로 요청하면 현재 샘플 경로 기준으로는 픽업이 어렵다는 fallback을 반환합니다. 이 케이스는 "무조건 추천"이 아니라 불가능한 상황을 솔직하게 말하는 데모로 사용합니다.

Quick Start

Local MCP Inspector:

uv sync
uv run mcp dev main.py

MCP Inspector가 열리면 다음 도구를 호출할 수 있습니다.

• plan_rush_gift: 선물 추천, 픽업 매장, 경유 가능성, 메시지를 한 번에 반환
• recommend_gifts: 관계/상황/예산 기준으로 선물 후보 추천
• find_pickup_options: 선물 후보별 픽업 매장과 경유 가능성 계산
• draft_gift_message: 관계와 상황에 맞는 짧은 카드 메시지 생성

stdio 서버로 직접 실행할 때:

uv run python main.py

HTTP MCP endpoint로 실행할 때:

MCP_TRANSPORT=streamable-http FASTMCP_HOST=127.0.0.1 PORT=8000 uv run python main.py

Local URLs:

• MCP endpoint: http://127.0.0.1:8000/mcp
• Health check: http://127.0.0.1:8000/health

Docker:

docker build -t rush-gift-mcp .
docker run --rm -p 8000:8000 rush-gift-mcp

Vercel:

npx vercel

After deployment, use:

https://<production-domain>/mcp

If PlayMCP cannot load tools from the Vercel URL, deploy the same code to a container/always-on host with the Dockerfile.

테스트:

uv run pytest

Documentation

• PlayMCP Submission Plan
• Architecture
• Implementation Roadmap
• Demo Scenarios
• Deployment

Development Status

Implemented:

• fixture-backed gift, place, store, and route providers
• transparent scoring for gift fit and pickup feasibility
• four MCP tools in main.py
• unit tests for recommendation, fallback, budget filtering, pickup options, and MCP tool registration

Next:

• deploy the Dockerized HTTP MCP server
• replace fixture providers with Kakao/web providers when available