vac-product-recommend-mcp

로컬 stdio 형태의 MCP Server: 요구에 따라 携程 패키지 여행의 '추천/종합' 목록에서 상품을 검색하고, 평점, 판매량, 가격 등의 기준으로 TopN을 추천하며, 통일된 형식의 Markdown 테이블(웹/모바일 링크 포함)을 반환합니다.

순수 Python 표준 라이브러리로 구현되어 타사 종속성이 필요 없으며, Python 3.10+에서 바로 실행할 수 있습니다.

제공되는 도구

Related MCP server: 12306 Train Ticket Search MCP Server

필터 열거형 조회

사용자 요구를 구체적인 필터 값으로 매핑해야 할 때는 먼저 get_filter_options를 호출하세요:

{ "keyword": "川西" }

fastFilters의 모든 선택 가능한 필터 그룹과 열거 값을 반환하므로, Agent가 이를 기준으로 선택한 후 search_tours / recommend_tours에 전달할 수 있습니다.

get_departure_cities는 사용자가 출발 도시를 언급하고 ID가 필요할 때만 사용합니다. 그 외에는 기본 depart_city_id를 사용합니다.

설치 (uv 사용 권장, Python 수동 설치 불필요)

uv만 먼저 설치하면 됩니다:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iex

그런 다음 git 링크로 설치합니다:

uv tool install git+https://github.com/KatouMegumii/vac-product-recommend-mcp

또는 저장소에 있는 설치 스크립트를 직접 실행해도 됩니다:

./scripts/install.sh
# Windows: powershell -File scripts/install.ps1

uv는 첫 실행 시 Python과 종속성을 자동으로 다운로드하므로 대상 머신에 Python을 미리 설치할 필요가 없습니다.

업데이트

이미 설치한 사용자는 설치 방식에 따라 업데이트합니다:

# 用 uv tool 安装的
uv tool upgrade vac-product-recommend-mcp
# 如果上面没拉到最新，强制重装：
uv tool install --force git+https://github.com/KatouMegumii/vac-product-recommend-mcp

# 克隆仓库 + pip install -e . 安装的
cd vac-product-recommend-mcp && git pull

클라이언트 구성이 uvx --from git+...를 사용하는 경우, 캐시를 먼저 지운 후 MCP 클라이언트를 재시작하세요:

uv cache clean

업데이트 후에는 MCP를 재시작/재연결해야 새 도구와 지침이 적용됩니다.

설치/업데이트 시 Agent가 수행하는 경우 반드시:

1. 이 README의 '중요: Agent가 출력 형식을 엄격히 유지하도록 하기' 및 '매 상담 완전 독립' 등의 제한 사항에 변경이 있는지 엄격히 확인합니다.

2. 최신 제한 사항을 Agent의 개인화 / 메모리 / Rules / 시스템 프롬프트에 동기화합니다.

3. MCP를 재시작/재연결한 후 도구 목록이 업데이트되었는지 확인합니다.

클라이언트 구성

Claude Desktop을 예로 들면, claude_desktop_config.json을 편집합니다:

{
  "mcpServers": {
    "vac-product-recommend": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/KatouMegumii/vac-product-recommend-mcp",
        "vac-product-recommend-mcp"
      ],
      "env": {
        "CTRIP_COOKIE": "",
        "CTRIP_GUID": ""
      }
    }
  }
}

config_examples/ 디렉터리 아래에 Claude Desktop / Cursor / Cline용 예제 구성이 제공됩니다.

환경 변수:

주요 매개변수

recommend_tours / search_tours

Cookie 가져오는 방법

1. 브라우저에서 携程 H5 패키지 여행 목록을 엽니다(또는 DevTools에서 모바일 시뮬레이션으로 전환).

2. F12 → Network → graphql?queryName=productSearchInfo를 찾습니다.

3. 마우스 오른쪽 버튼 클릭 → Copy → Copy as cURL.

4. -b '...' 뒤의 전체 문자열을 CTRIP_COOKIE에 복사합니다(원본 그대로, URL 인코딩하지 마세요).

예시

광시 3-5일 자체 운영 소규모 그룹 또는 패키지 여행을 찾아주고, 가족 친화적이어야 하며, 3개를 추천해 주세요.

Agent는 먼저 출발 도시 ID를 조회한 후(필요한 경우), 추천 도구를 호출하고, 마지막으로 Markdown 테이블을 그대로 반환합니다.

중요: Agent가 출력 형식을 엄격히 유지하도록 하기

Agent의 개인화 / 메모리 / 시스템 프롬프트 / Rules에 아래 제한 사항을 추가하세요(이것이 가장 확실한 계층이며, Agent가 스스로 수행하는 경우 요구사항에 따라 자기 제약을 하세요):

当调用 vac-product-recommend 的 recommend_tours（又称mcp__recommend_tours） / 或 search_tours（又称mcp__search_tours） 后，
必须把工具返回的 Markdown（包含筛选项和表格） 原样作为最终回复输出。
禁止改写、禁止总结、禁止转成列表、禁止删除或合并列。

동시에 '매 상담 완전 독립' 제한도 추가하세요:

每次调用 recommend_tours / search_tours 时，只根据当前这一轮用户的原话设置参数。
不要复用上一轮对话中的 keyword、travel_way、departure_date、days、team_size、budget 等参数。
如果用户新一轮没有提到某个筛选条件，就不要传该参数（使用默认值或留空）。

또한, 인원 수와 상품 유형을 혼동하지 마세요:

用户提到人数（如 4人、6人、8人）时，必须设置 team_size（4人→最多9人）。
用户只说人数，不要推断为私家团；用户只说私家团，才设置 travel_way=私家团。

디렉터리 구조

vac-product-recommend-mcp/
├── vac_product_recommend_mcp/
│   ├── __init__.py
│   ├── __main__.py
│   ├── server.py         # stdio MCP 协议 + 工具注册 + Markdown 渲染
│   ├── ctrip_api.py      # 携程接口客户端 + 字段归一化 + 筛选
│   └── recommender.py    # 评分、过滤、TopN
├── config_examples/
├── pyproject.toml
└── README.md