vac-product-recommend-mcp

ローカル stdio 形式の MCP Server：ニーズに応じて携程のパッケージツアー「厳選/総合」リストで商品を検索し、レビュー評価・販売数・価格などの観点で TopN を推薦し、統一形式の Markdown テーブル（Web版 / モバイル版リンク含む）を返します。

純 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 の再起動 / 再接続が必要です。新しいツールと instructions が有効になります。

インストール / 更新時に 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