Metadata-Version: 2.4
Name: mcp-hotel-recommend
Version: 0.3.0
Summary: 酒店搜索与智能推荐 MCP Server — 场景路由+智能补全+退改解读+推荐理由, 1次调用=搜索+详情+解读, 极省Token
Author: Hotel Recommend Team
License-Expression: MIT
Keywords: mcp,hotel,search,recommend,booking,travel
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]>=1.9.2
Requires-Dist: httpx>=0.27.0

# 🏨 酒店搜索与智能推荐

酒店搜索与智能推荐MCP服务，连接大语言模型与全球酒店数据，为AI助手、旅行智能体及Cursor/Windsurf等IDE提供智能酒店推荐能力。**1次调用完成需求理解→参数补全→搜索→详情→退改解读→推荐理由全流程**，无需多次调用多个工具，极省Token。

## ✨ 核心特性

### vs 官方RollingGo MCP

| 维度 | 官方RollingGo | 本服务 |
|------|-------------|-------|
| **定位** | 搜索工具（API透传） | 推荐引擎（理解+补全+排序+解读） |
| **输入** | 用户必须提供完整结构化参数 | 5个字也能理解（"带娃去三亚"） |
| **调用次数** | 4次（getTags+搜索+3次详情） | **1次** |
| **需求理解** | 无，AI自己猜参数 | ✅ 场景自动识别+参数智能补全 |
| **空结果** | 返回空 | ✅ 4轮自动降级 |
| **输出** | 原始JSON | ✅ 人类可读推荐+推荐理由+退改解读 |
| **API Key** | 用户自己申请 | ✅ 零配置 |

### 智能补全示例

| 用户说 | 自动补全 |
|--------|---------|
| "带娃去三亚" | 亲子场景 + 儿童乐园/泳池/家庭房标签 + 3.5-5星 + 2晚 + 海边标签 |
| "出差上海" | 商务场景 + WiFi/前台/健身房标签 + 3.5-5星 + 1晚 |
| "便宜点的" | 背包场景 + 性价比标签 + 0-3.5星 + 限价300 |
| "三亚海边住几天" | 度假场景 + 海滩/泳池标签 + 2晚 + placeType=景点 |
| "15人团建" | 7-8间房 + 2成人/间 + 商务标签 |

## 🛠 工具

### hotel_search_and_recommend

酒店搜索与智能推荐：1次调用完成场景路由→参数补全→搜索→详情→退改解读→推荐理由。

**必填参数：**

| 参数 | 类型 | 说明 |
|---|---|---|
| destination | string | 目的地城市/区域/地标，如"上海"、"三亚海棠湾" |

**可选参数（AI不传也会自动补全）：**

| 参数 | 类型 | 说明 |
|---|---|---|
| query | string | 用户原始查询，用于场景检测和参数补全 |
| scene | string | 场景：商务/亲子/度假/背包/通用，默认自动检测 |
| check_in | string | 入住日期 YYYY-MM-DD，默认明天 |
| check_out | string | 退房日期 YYYY-MM-DD，默认根据场景推断 |
| star_rating | string | 星级：'4'=4星+，'3,4'=3-4星，或'豪华型'等中文 |
| max_price | int | 每晚价格上限（元） |
| max_distance | int | 距目标距离上限（米） |
| preferred_brand | string | 偏好品牌，逗号分隔 |
| required_tag | string | 必须标签（硬约束） |
| preferred_tag | string | 偏好标签（软约束） |
| excluded_tag | string | 排除标签 |
| min_room_size | int | 最小房间面积（㎡） |
| guests | int | 入住人数 |
| child_count | int | 儿童数量 |
| child_ages | string | 儿童年龄，逗号分隔 |
| room_count | int | 房间数 |
| country_code | string | 国家代码（海外搜索） |
| size | int | 返回数量，默认8 |

**场景自动检测：**

| 场景 | 关键词 | 自动补全 |
|---|---|---|
| 💼 商务 | 出差/商务/会议/商旅 | 必选商务酒店；一线=WiFi/前台/健身房，二三线=停车场/早餐 |
| 👨‍👩‍👧 亲子 | 带娃/亲子/家庭/孩子 | 必选亲子酒店；海岛=儿童乐园+泳池+海滩，内陆=泳池+早餐 |
| 🌴 度假 | 度假/情侣/蜜月/温泉 | 海岛=户外泳池+SPA+海滩，内陆=温泉+SPA |
| 🎒 背包 | 穷游/便宜/经济/学生 | 性价比标签+限价+低星级 |
| 🏨 通用 | 无匹配 | 无标签过滤 |

**支持多场景叠加**："带娃去三亚便宜点" = 亲子+背包，同时应用两套标签。

**输出示例：**

```
👨‍👩👧亲子推荐 · 三亚 · 2026-06-15 (2晚)

1️⃣ 三亚亚特兰蒂斯酒店 ⭐5 💰¥2,380/晚
   📍 海棠湾海棠北路 | 距目标800m
   🏷️ 亲子酒店 儿童乐园 儿童泳池
   💡 有儿童乐园和儿童泳池，近海滩
   🔄 退改：入住前3天前免费取消
   🔗 https://rollinggo.cn/...

2️⃣ 三亚天域度假酒店 ⭐4 💰¥680/晚
   📍 亚龙湾 | 距目标1.2km
   🏷️ 亲子酒店 儿童乐园 提供家庭房
   💡 有儿童乐园，有家庭房，近海滩
   🔄 退改：入住当日18点前免费取消
   🔗 https://rollinggo.cn/...

3️⃣ 三亚湾红树林度假酒店 ⭐4 💰¥520/晚
   📍 三亚湾路 | 距目标2.1km
   🏷️ 度假酒店 户外泳池 中式早餐
   💡 有户外泳池，4星品质
   🔄 退改：入住前1天后取消扣¥520
   🔗 https://rollinggo.cn/...

👥 2成人1儿童 · 1间
```

## 📦 安装

```
pip install mcp-hotel-recommend
```

## ⚙️ 配置

**无需API Key**，开箱即用。服务通过云端代理访问全球酒店数据（200万+酒店），Key已在代理端管理。

如需使用自有Key（独立追踪分佣收益）：
```
export HOTEL_API_KEY="your_api_key_here"
```

## 🚀 MCP客户端配置

```json
{
  "mcpServers": {
    "hotel-recommend": {
      "command": "uvx",
      "args": ["mcp-hotel-recommend"],
      "env": {
        "HOTEL_API_KEY": ""
      }
    }
  }
}
```

💡 HOTEL_API_KEY留空即可使用，填入自有Key可独立追踪分佣。

## 📝 使用示例

- "带娃去三亚" → 自动检测亲子场景 + 补全海边标签 + 2晚
- "出差上海住陆家嘴" → 商务场景 + placeType=区县 + WiFi/健身房
- "杭州有什么便宜的酒店" → 背包场景 + 限价300 + 低星级
- "和女朋友去大阪" → 度假场景 + countryCode=JP + 2晚
- "公司团建15人北京" → 商务场景 + 8间房 + 会议室标签
- "帮我搜搜上海的酒店" → 通用场景，无额外标签

## 🔄 降级策略

当搜索条件过严导致0结果时，自动4轮降级：

1. 去掉requiredTags（必选标签→偏好标签）
2. 去掉距离限制
3. 去掉星级限制
4. 只保留地点+日期，展示城市热门酒店

每次降级都会在输出中提示用户。

## 📄 许可证

MIT License
