Local stdio MCP server: searches products for group trips in the Ctrip lists "Избранные/Общие" according to requirements and recommends TopN based on the useful score, sales, price, etc., returning a unified Markdown table (with links to the web/mobile versions).
Implemented purely using Python's standard library, no third-party dependencies, runs on Python 3.10+.
Tool | Purpose |
| By keyword + multiple filters, returns TopN products with good sales and reviews |
| Searches the list and returns Markdown table |
| Gets currently available filters and their values, for mapping |
| Gets Ctrip departure city ID by city name/pinyin (only when needed) |
Related MCP server: 12306 Train Ticket Search MCP Server
When you need to map the user request to specific filter values, first call get_filter_options:
{ "keyword": "川西" }Return each option group and its possible values from fastFilters, the Agent can choose based on that and pass it to search_tours/recommend_tours.
get_departure_cities is only used if the user mentions a departure city and you need the ID; otherwise the default depart_city_id is used.
Just install uv first:
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iexThen install via the git link:
uv tool install git+https://github.com/KatouMegumii/vac-product-recommend-mcpOr you can directly run the installation script in the repository:
./scripts/install.sh
# Windows: powershell -File scripts/install.ps1uv will automatically download Python and dependencies on first run; the target machine does not need Python preinstalled.
For installed users, update in the way you installed:
# 用 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 pullIf the client config uses uvx --from git+..., first clear the cache and then restart the MCP client:
uv cache cleanAfter updating, you need to restart/re-connect MCP for new tools and instructions to take effect.
If the installation/update is done by the Agent, you must:
Strictly check this readme's "Important: have the Agent strictly keep the output format" and "Specific: every inquiry is fully independent" limitations for changes;
Sync the latest limitations into the Agent's personalization / memory / Rules / system prompt;
After restarting/reconnecting MCP, confirm the tool list has been updated.
With Claude Desktop as 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": ""
}
}
}
}config_examples/ contains example config configurations for Claude Desktop / Cursor / Cline.
Environment variables:
Variable | Required | Description |
| no | Full cookie string copied from the browser, can also work without (may trigger risk control) |
| no | Can be left empty; if empty uses built-in default |
| no | Risk control signature, not required by current API |
| no | Rotation token, not required by current API |
Parameter | Description |
| Destination/theme, e.g. "Turkey", "广西" |
| The department departure city ID; only query via |
| travel method, multi-select array: |
| The brand, e.g. |
| Star level, e.g. |
| Group size: |
| Transportation: |
| Service guarantees, multiple AND (comma separated or array): |
| Applicable crowd, multiple OR (comma separated or array): |
| The breakdown: promotions, such as |
| The number of days, supports |
| departure date (only the departure day), format |
| The supplier name or ID, multiple, name fuzzy match |
| Only pass |
| Minimum review, default 0 no filtering; irrelevant to the number of people |
| budget upper bound |
| number of recommendations |
| candidate pool limit, auto page to collect enough matches |
Open the Ctrip H5 group tour list in the browser (or use DevTools to switch to mobile simulation).
F12 → NNetwork → find graphql?queryName=productSearchInfo.
Right-click → Copy → Copy as cURL.
Grab the entire string after -b in ... and put it into CTRIP_COOKIE (as is, do not URL-encode).
Help me find a 3-5 day self-owned mini-group or group tour in Guangxi, parent-child friendly, recommend 3.
The Agent will first query the departure city ID (if needed), then call the recommendation tool, and finally return the Markdown table as-is.
Add the following restriction in the Agent's Personalization / Memory / System Prompt / Rules (which is the most stable layer; if the Agent executes it itself, self-constrain as required):
当调用 vac-product-recommend 的 recommend_tours（又称mcp__recommend_tours） / 或 search_tours（又称mcp__search_tours） 后，
必须把工具返回的 Markdown（包含筛选项和表格） 原样作为最终回复输出。
禁止改写、禁止总结、禁止转成列表、禁止删除或合并列。Also add the restriction "every inquiry is completely independent":
每次调用 recommend_tours / search_tours 时，只根据当前这一轮用户的原话设置参数。
不要复用上一轮对话中的 keyword、travel_way、departure_date、days、team_size、budget 等参数。
如果用户新一轮没有提到某个筛选条件，就不要传该参数（使用默认值或留空）。Also, do not mix the number of people with the type of product:
用户提到人数（如 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查询携程出发城市ID。当用户提到某出发城市（如上海、北京、合肥）时，先调用本工具按中文名/拼音模糊查询城市ID，再把ID传给 search_tours 或 recommend_tours 的 depart_city_id。
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 最多返回多少条城市，默认20 | |
| keyword | Yes | 出发城市中文名/拼音/英文名，支持模糊匹配，例如：合肥、hefei |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It mentions fuzzy matching by Chinese/pinyin/English and a limit parameter, but does not describe the output format, behavior on no matches, or whether results are sorted. Basic behavior is disclosed, but some gaps remain, so a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the main purpose front-loaded ('查询携程出发城市ID'), followed by a concise workflow explanation. No redundant words; every phrase adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two parameters, no output schema), the description adequately covers purpose, when to use, and how the result feeds into other tools. It doesn't detail the response structure, but for a lookup tool this is acceptable. Slightly more could be said about the return format, hence a 4.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters (keyword and limit) with full descriptions, including examples. The description adds no new parameter-level detail beyond what the schema already provides, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries Ctrip departure city IDs, using the specific verb '查询' and resource '出发城市ID'. It also explains the workflow of looking up the ID before passing it to search_tours or recommend_tours, which distinguishes it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context: 'when user mentions a departure city, call this tool first' (当用户提到某出发城市...先调用本工具). It also explains how the ID is used downstream, but does not explicitly mention exclusions or alternatives like get_filter_options. Clear context, no exclusions, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询携程综合列表当前可用的筛选器及可选值（fastFilters）。当需要把用户需求映射成具体筛选参数/枚举时，先调用本工具获取可选值，再调用 search_tours 或 recommend_tours。
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | 目的地/主题关键词，例如：川西、土耳其 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It implies a read-only query by using '查询' (query) but does not describe the return format, pagination, or any potential side effects. It mentions returning 'fastFilters' but lacks detail on structure or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose in the first sentence and usage guidance in the second. No fluff, every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description sufficiently explains the tool's role and usage context. However, it could mention what the output looks like or any prerequisites (e.g., authentication), but given the simplicity, the description is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the keyword parameter with a description (destination/theme keyword with examples). The tool description adds no additional meaning about the parameter, so it does not go beyond the schema. Baseline of 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries available filters and their optional values ('fastFilters') from the Ctrip integrated list. This is a specific verb-resource combination that distinguishes it from sibling tools like search_tours and recommend_tours, which are for searching tours, and get_departure_cities, which is for departure cities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use this tool: when mapping user requirements to filter parameters/enums, call this tool first, then pass the obtained values to search_tours or recommend_tours. This provides clear context and a workflow, effectively distinguishing it from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
在携程跟团游「精选/综合」列表里搜索并按需求推荐产品。当用户要『找/推荐/搜索/比较』携程的跟团游、拼小团、私家团、邮轮、自由行、定制游等旅游产品时，直接调用本工具（无需用户指定工具名）。根据点评分、销量、点评量、供应商等维度排序，返回 TopN 产品信息、链接和推荐理由。返回的是 Markdown 表格；最终回复用户时请直接使用该表格，不要改写格式。
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | 游玩天数，支持单值/区间/多选：7、7天、6-8、6,7,8。若用户同时给了出发日和返程日，必须精确计算：天数 = 返程日 - 出发日 + 1，并传该单值，例如 9月25日出发、10月5日返程 → days=11，不要传 10-12 | |
| brand | No | 品牌，可多选（逗号分隔），支持：携程自营/自营 | |
| level | No | 产品钻级，可多选（逗号分隔），支持：5钻/5、4钻/4、3钻/3、2钻及以下 | |
| promo | No | 优惠活动，可多选（逗号分隔），支持：机票用户价、拼满返现、717嗨玩节 | |
| top_n | No | 返回前几名推荐，默认3，可改成5/10等 | |
| vendor | No | 供应商名称或ID，可多选（逗号分隔），名称支持模糊匹配，例如：随程国旅假期,2256920 | |
| keyword | Yes | 目的地/主题关键词，例如：土耳其、日本、云南 | |
| rank_by | No | 排序规则：composite=综合分(默认) sales=销量 rating=好评 comment_count=点评量 price_asc=价格升序 price_desc=价格降序 | composite |
| vehicle | No | 交通方式，可多选（逗号分隔），支持：不含往返交通 / 不含大交通 / 当地参团 | |
| min_sold | No | 最低销量，默认0（不过滤） | |
| max_pages | No | 最多抓取页数，默认2页（约30个候选） | |
| min_score | No | 最低点评分，仅当用户要求『评分/好评优先』时才设置；默认0表示不过滤。人数请用 team_size，不要用本参数 | |
| must_tags | No | 硬性标签过滤，逗号分隔，产品标题/标签必须全部包含，例如：0购物,含领队 | |
| page_size | No | 每页抓取数量，默认15 | |
| team_size | No | 团队规模，可多选（逗号分隔）。用户提到人数时必须设置本参数：1-9人→最多9人，10-20人→10-20人，21人及以上→21人及以上。例如：4人→最多9人 | |
| budget_max | No | 单人预算上限（人民币），用于过滤 | |
| travel_way | No | 产品类型/旅行方式筛选，支持多选，传数组，例如：['拼小团','跟团游']。仅当用户明确说『私家团/独立成团/私人团』时才传私家团；用户只说『X人』不代表私家团，不要据此设置本参数 | |
| requirement | No | 用户额外要求，例如：0购物、含领队、直飞、预算2万以内。命中的标签会加分，预算请用 budget_max 传数字。 | |
| suit_person | No | 适用人群，可多选（逗号分隔），支持：亲子友好、老友会严选 | |
| service_tags | No | 服务保障，逗号分隔，支持：0购物、一价全包、0购物0自费、成团保障、含接送机/站 | |
| depart_city_id | No | 出发城市ID，2=上海，1=北京，默认2 | 2 |
| departure_date | No | 出发日期（仅出发日，不是返程日）。格式 YYYY-MM-DD。只有用户明确说『出发日期在某段时间内』才用 YYYY-MM-DD~YYYY-MM-DD。若用户同时给了出发日和返程日，只用出发日，例如：9月25日出发、10月5日返程 → departure_date=2026-09-25 | |
| candidate_limit | No | 候选池上限，会自动分页（例：50 会拆成 25×2）。不传则用 page_size × max_pages。 | |
| include_traffic | No | 是否含往返大交通。仅当用户明确要『含往返交通』时传 是；用户说『不含往返交通/不含大交通/当地参团』时请改用 vehicle 参数，不要传本参数 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It thoroughly discloses behavior: it returns a Markdown table, sorts by multiple dimensions, and respects numerous parameter constraints (e.g., '仅当用户明确说' clauses). This high level of detail ensures the agent understands side effects and conditional logic, exceeding typical transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-organized paragraph that front-loads the purpose and usage, then details the output. Despite the large parameter count, the description is concise and avoids redundancy—every sentence adds necessary context. The format is clean and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 24 parameters and many conditional rules, the description is remarkably complete. It covers the core behavior, output format, sorting logic, and provides explicit guidance on how to interpret user intents for each parameter. No major aspects are missing, and the lack of an output schema is mitigated by the clear statement that the result is a Markdown table.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 24 parameters have rich, descriptive explanations that go beyond type information. Examples include team_size mapping from user counts, departure_date format and conditionality, and explicit instructions like 'min_socre' only when the user requests rating priority. This exceeds the 100% schema coverage baseline by providing actionable context for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to search and recommend tour products on Ctrip based on user requirements, with sorting and TopN output. It explicitly lists the action verbs (找/推荐/搜索/比较) and specifies the product types covered, making its function unambiguous and distinct from sibling tools like search_tours.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: it says to call this tool directly whenever the user asks to find, recommend, search, or compare these tour products, without needing the user to name the tool. It also explains sorting dimensions and output format, covering the primary usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
在携程跟团游「精选/综合」列表里搜索并返回结构化产品列表。当用户要『列出/搜索/看看』携程的跟团游、拼小团、私家团、邮轮等产品，或需要按销量/好评/价格/产品类型自定义筛选时，直接调用本工具（无需用户指定工具名）。支持 travel_way 产品类型筛选、sort 排序、limit 自动分页。返回的是 Markdown 表格；最终回复用户时请直接使用该表格，不要改写格式。
| Name | Required | Description | Default |
|---|---|---|---|
| tab | No | 126=精选/综合，64=上海出发参团，512=当地参团 | 126 |
| days | No | 游玩天数，支持单值/区间/多选：7、7天、6-8、6,7,8。若用户同时给了出发日和返程日，必须精确计算：天数 = 返程日 - 出发日 + 1，并传该单值，例如 9月25日出发、10月5日返程 → days=11，不要传 10-12 | |
| page | No | 页码，默认1 | |
| sort | No | 8=推荐 2=销量 4=好评 5=低价 6=高价 | |
| brand | No | 品牌，可多选（逗号分隔），支持：携程自营/自营 | |
| level | No | 产品钻级，可多选（逗号分隔），支持：5钻/5、4钻/4、3钻/3、2钻及以下 | |
| limit | No | 最多返回多少条，会自动分页（例：50 会拆成 25×2）。不传则按 page/page_size 单页返回。 | |
| promo | No | 优惠活动，可多选（逗号分隔），支持：机票用户价、拼满返现、717嗨玩节 | |
| vendor | No | 供应商名称或ID，可多选（逗号分隔），名称支持模糊匹配，例如：随程国旅假期,2256920 | |
| keyword | Yes | 目的地/主题关键词 | |
| vehicle | No | 交通方式，可多选（逗号分隔），支持：不含往返交通 / 不含大交通 / 当地参团 | |
| page_size | No | 每页数量，默认15 | |
| team_size | No | 团队规模，可多选（逗号分隔）。用户提到人数时必须设置本参数：1-9人→最多9人，10-20人→10-20人，21人及以上→21人及以上。例如：4人→最多9人 | |
| travel_way | No | 产品类型/旅行方式筛选，支持多选，传数组，例如：['拼小团','跟团游']。仅当用户明确说『私家团/独立成团/私人团』时才传私家团；用户只说『X人』不代表私家团，不要据此设置本参数 | |
| suit_person | No | 适用人群，可多选（逗号分隔），支持：亲子友好、老友会严选 | |
| service_tags | No | 服务保障，逗号分隔，支持：0购物、一价全包、0购物0自费、成团保障、含接送机/站 | |
| depart_city_id | No | 出发城市ID，默认2 | 2 |
| departure_date | No | 出发日期（仅出发日，不是返程日）。格式 YYYY-MM-DD。只有用户明确说『出发日期在某段时间内』才用 YYYY-MM-DD~YYYY-MM-DD。若用户同时给了出发日和返程日，只用出发日，例如：9月25日出发、10月5日返程 → departure_date=2026-09-25 | |
| include_traffic | No | 是否含往返大交通。仅当用户明确要『含往返交通』时传 是；用户说『不含往返交通/不含大交通/当地参团』时请改用 vehicle 参数，不要传本参数 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
描述明确说明返回Markdown表格，且要求最终回复直接使用该表格，不要改写格式，这是有用的行为提示。还提到limit自动分页、travel_way筛选仅当用户明确说私家团等才使用，以及days参数的计算逻辑。无注解，因此描述承载了行为披露责任，较充分。
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
描述紧凑，一段话概述用途和关键参数，无冗余。每句都提供价值：使用场景、自动分页、Markdown表格、筛选能力。
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
19个参数但仅1个必需，schema描述全覆盖。描述给出了关键计算规则和筛选触发条件，输出格式已说明（Markdown表格）。尽管无输出schema，但描述已足够让agent正确调用，整体完整。
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
schema描述覆盖100%参数，描述在schema基础上添加了关键语义：days参数精确计算规则（返程-出发+1）、travel_way的私家团触发条件、include_traffic与vehicle的互斥指导、departure_date仅出发日。这些额外信息确实超过schema本身，因schema描述已有不少，但描述增加了决策逻辑，所以给4。
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
描述明确说明该工具在携程跟团游列表中搜索并返回结构化产品列表，并列出用法（列出/搜索/看看）和可筛选维度（销量、好评等）。它通过与recommend_tours的对比来区分，明确‘直接调用本工具（无需用户指定工具名）’，但与兄弟工具区分不够明确——虽然未明确提及兄弟工具名称，但上下文应足够。
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
明确指明何时使用（列出/搜索/看看携程产品时）以及无需用户指定工具名。虽未明确说何时不使用，但提到‘直接调用’并对筛选、排序、分页有用法指引。缺少对recommend_tours等兄弟工具的明确排除，但已有上下文可推断。
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_departure_citiesget_filter_optionsrecommend_tourssearch_toursScored across 4 tools
recommend_tours and search_tours overlap heavily: both search the same Ctrip tour list and both are meant for searching/recommending, with only a subtle difference in intent. The two get_* helpers are clearly distinct, so the ambiguity is contained.
All tool names follow a consistent verb_noun pattern: recommend_tours, search_tours, get_filter_options, get_departure_cities. The naming is predictable and easy to map to tool purpose.
Four tools is a well-scoped set for a travel recommendation MCP. Each tool has a clear role in the search/recommendation workflow, and nothing feels extraneous or missing at the count level.
The set covers the main workflows: searching, recommending, resolving filter options, and mapping departure cities. A minor gap is lack of a dedicated product-detail or itinerary tool, but recommendations include links and enough product information to work around this.
Search vetted local guides and travel routes across China, with deep links to chat and booking.
Search tours, attraction tickets, and holiday packages across 24 countries.
Search & compare prices for tours, activities and tickets across multiple providers.
Search and compare outdoor experiences. Public keyless API; booking and payment happen on Viator.
