Metadata-Version: 2.4
Name: mcp-hotel-recommend
Version: 0.1.3
Summary: 酒店搜索与智能推荐 MCP Server — 场景路由+退改解读, 1次调用=搜索+详情+解读, 极省Token
Author: Hotel Recommend Team
License-Expression: MIT
License-File: LICENSE
Keywords: booking,hotel,mcp,recommend,search,travel,差旅,推荐,退改,酒店
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Other/Nonlisted Topic
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.9.2
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🏨 mcp-hotel-recommend

**酒店搜索与智能推荐 MCP Server** — 场景路由 + 退改解读，1 次调用 = 搜索 + 详情 + 解读，极省 Token。

## 🆚 核心差异化 vs RollingGo

| | RollingGo | mcp-hotel-recommend |
|---|---|---|
| **工具数** | 3 个独立工具 (searchHotels/getHotelDetail/getHotelSearchTags) | **1 个统一工具** hotel_search_and_recommend |
| **调用次数** | AI Agent 需调 3 次：搜索→详情→标签 | **1 次调用**完成全部流程 |
| **场景识别** | 无，用户需自己判断筛选条件 | **自动检测**：商务/亲子/度假/背包/通用 |
| **退改政策** | 原始 JSON 返回，Agent 需自己解读 | **人类可读解读**：`05月31日后取消扣¥553` |
| **Token 消耗** | 高（3 次调用 + 原始数据） | **极省 Token**（精简 emoji 格式） |
| **API 透明** | 直接透传 | 智能路由 + 格式化 + 解读 |

## 🛠 工具

| 工具 | 功能 | 典型场景 |
|------|------|---------|
| `hotel_search_and_recommend` | 场景路由搜索 → Top3 详情 → 退改解读 → 极简输出 | "出差上海住哪好" "带娃去三亚住哪" "杭州经济酒店" |

## 📦 安装

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

## ⚙️ 配置

需要 AigoHotel API 密钥：

```bash
export HOTEL_API_KEY="your_api_key_here"
```

## 🚀 使用

### 命令行

```bash
# STDIO 模式 (默认)
mcp-hotel-recommend

# 或
python -m mcp_hotel_recommend
```

### MCP 客户端配置

在 Claude Desktop / Cherry Studio / ChatBox 等 MCP 客户端中添加：

```json
{
  "mcpServers": {
    "hotel-recommend": {
      "command": "mcp-hotel-recommend",
      "env": {
        "HOTEL_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### 开发测试

```bash
# 安装 FastMCP CLI
pip install "mcp[cli]"

# 交互式测试
mcp dev src/mcp_hotel_recommend/server.py

# 检查工具列表
mcp inspect src/mcp_hotel_recommend/server.py
```

## 💡 使用示例

### 商务出差

```python
hotel_search_and_recommend(
    destination="上海",
    scene="商务",
    check_in="2026-06-15",
    check_out="2026-06-17",
    query="出差上海住哪好"
)
```

输出：
```
💼商务推荐 · 上海 · 2026-06-15

1️⃣ 上海花园饭店 ⭐5 💰¥924/晚
   📍 茂名南路58号 | 距目标1131m
   🏷️ 商务酒店 免费WiFi 健身房
   🔄 退改：05月30日后取消扣¥922
   🔗 https://rollinggo.cn/...
```

### 亲子出游（场景自动检测）

```python
hotel_search_and_recommend(
    destination="三亚",
    query="带娃去三亚住哪好"
)
# 自动检测为"亲子"场景
```

### 通用搜索

```python
hotel_search_and_recommend(destination="杭州")
```

## 🎯 场景路由

| 场景 | 关键词 | 标签策略 |
|------|--------|---------|
| 💼 商务 | 出差/商务/办公/会议/商旅 | 必选：商务酒店；优选：免费WiFi/24小时前台 |
| 👨‍👩‍👧 亲子 | 亲子/家庭/带娃/遛娃 | 必选：亲子酒店；优选：儿童乐园/儿童泳池 |
| 🌴 度假 | 度假/情侣/蜜月/温泉 | 优选：度假酒店/SPA/户外泳池 |
| 🎒 背包 | 穷游/学生/青旅/便宜 | 优选：性价比酒店；排除：仅限成人入住 |
| 🏨 通用 | 无匹配关键词 | 无标签过滤 |

## 🔄 退改政策解读

自动将原始 JSON 退改政策解读为人类可读文字：

| 原始数据 | 解读结果 |
|---------|---------|
| `{amount: 0}` | `05月30日前免费取消` |
| `{amount: 553}` | `05月31日后取消扣¥553` |
| `{amount: 922, fromDate >= 入住日}` | `入住当日取消扣¥922` |
| 无退改数据 | `暂无退改信息` |

## 📄 许可证

MIT License

---

# 🏨 mcp-hotel-recommend (English)

**Hotel Search & Smart Recommendation MCP Server** — Scene routing + cancellation policy interpretation, 1 call = search + detail + interpretation, extreme token saving.

## Key Differentiator vs RollingGo

| | RollingGo | mcp-hotel-recommend |
|---|---|---|
| **Tools** | 3 separate tools | **1 unified tool** |
| **Calls** | 3 calls: search→detail→tags | **1 call** for everything |
| **Scene Detection** | None | **Auto-detect**: business/family/vacation/backpack/general |
| **Cancellation** | Raw JSON | **Human-readable** interpretation |
| **Token Usage** | High (3 calls + raw data) | **Minimal** (emoji-formatted) |

## Install

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

## Configure

```bash
export HOTEL_API_KEY="your_api_key"
```

## MCP Client Config

```json
{
  "mcpServers": {
    "hotel-recommend": {
      "command": "mcp-hotel-recommend",
      "env": {
        "HOTEL_API_KEY": "your_api_key"
      }
    }
  }
}
```

## License

MIT
