vac-product-recommend-mcp

A local stdio-based MCP Server: searches products in Ctrip's group tour "Featured/Comprehensive" lists based on requirements, recommends TopN by review score, sales volume, price, and other dimensions, and returns a unified Markdown table (with web/mobile links).

Implemented in pure Python standard library, no third-party dependencies required, runs on Python 3.10+.

Provided Tools

Related MCP server: 12306 Train Ticket Search MCP Server

Filter Enum Queries

When you need to map user requirements to specific filter values, call get_filter_options first:

{ "keyword": "川西" }

It returns all available filter groups and enum values in fastFilters; the Agent can choose from these and pass them to search_tours / recommend_tours.

get_departure_cities is only used when the user mentions a departure city and an ID is needed; otherwise use the default depart_city_id.

Installation (uv recommended, no manual Python install needed)

Just install uv first:

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

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

Then install via git link:

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

You can also run the installation script in the repository directly:

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

uv will automatically download Python and dependencies on first run; the target machine does not need Python pre-installed.

Updating

Already-installed users update according to their installation method:

# 用 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

If the client config uses uvx --from git+..., clear the cache first, then restart the MCP client:

uv cache clean

After updating, you must restart / reconnect MCP for the new tools and instructions to take effect.

During installation / update, if performed by an Agent, you must:

1. Strictly check whether the restrictions in this README, such as "Important: Have the Agent strictly maintain output format" and "Each consultation is fully independent", have changed;

2. Sync the latest restrictions into the Agent's personalization / memory / Rules / system prompt;

3. Restart / reconnect MCP, then confirm the tool list has been updated.

Client Configuration

Using Claude Desktop as an example, edit 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": ""
      }
    }
  }
}

The config_examples/ directory provides example configs for Claude Desktop / Cursor / Cline.

Environment variables:

Main Parameters

recommend_tours / search_tours

How to Get the Cookie

1. Open the Ctrip H5 group tour list in a browser (or switch to mobile emulation in DevTools).

2. F12 → Network → find graphql?queryName=productSearchInfo.

3. Right-click → Copy → Copy as cURL.

4. Copy the entire string after -b '...' into CTRIP_COOKIE (as-is, do not URL-encode).

Example

Help me find 3-5 day self-operated small group or group tours in Guangxi, family-friendly, recommend 3.

The Agent will first look up the departure city ID (if needed), then call the recommendation tool, and finally return the Markdown table as-is.

Important: Have the Agent strictly maintain output format

Add the following restriction to the Agent's personalization / memory / system prompt / Rules (this is the most reliable layer; if the Agent executes on its own, please self-constrain as required):

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

Also, add the "Each consultation is fully independent" restriction:

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

Additionally, do not confuse group size with product type:

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

Directory Structure

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