Metadata-Version: 2.4
Name: mcp-homestay-finder
Version: 1.0.2
Summary: 特色民宿搜索MCP Server - 景区民宿、古镇客栈、乡村精品民宿，结构化搜索+AI语义推荐
Author: mako2026
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: cryptography>=42.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.9.2
Description-Content-Type: text/markdown

# 🏡 特色民宿搜索

特色民宿搜索与智能推荐MCP服务，连接大语言模型与全国民宿数据，为AI助手、旅行智能体及Cursor/Windsurf等IDE提供景区民宿、古镇客栈、乡村精品民宿等非标住宿的搜索与推荐能力。

## ✨ 核心特性

▸ 结构化搜索：按目的地、关键词、景点、价格等多维度搜索民宿，返回名称、价格、地址、预订链接
▸ AI语义推荐：用自然语言描述需求，AI理解意图并推荐最匹配的特色民宿，包含风格、设施、景观等维度详情
▸ 零配置接入：无需额外申请Key，配置即接入

## 🛠 工具

### search_homestay

搜索特色民宿：按条件搜索，返回民宿列表（名称、价格、地址、预订链接）。

**参数：**

▸ `dest_name`（string，✅必填）：目的地，如"大理""莫干山""三亚"
▸ `key_words`（string，选填）：关键词，如"海景""亲子""山景""温泉"
▸ `poi_name`（string，选填）：附近景点，如"洱海""灵隐寺"
▸ `check_in_date`（string，选填）：入住日期，YYYY-MM-DD格式
▸ `check_out_date`（string，选填）：退房日期，YYYY-MM-DD格式
▸ `max_price`（int，选填）：最高价格（人民币），0表示不限
▸ `sort`（string，选填）：排序方式，distance_asc/rate_desc/price_asc/price_desc

---

### recommend_homestay

智能民宿推荐：用自然语言描述需求，AI推荐最匹配的特色民宿。

**参数：**

▸ `query`（string，✅必填）：自然语言需求描述

## 📝 使用示例

▸ "大理海景民宿500以内" → search_homestay搜索
▸ "莫干山带院子能烧烤的亲子民宿，要有山景" → recommend_homestay推荐
▸ "杭州西湖附近民宿" → search_homestay按景点搜
▸ "丽江古城纳西风格小院，适合两个人安静住几天" → recommend_homestay推荐

## 📦 安装

```
pip install mcp-homestay-finder
```

## ⚙️ 配置

API密钥为选填，不配置也可直接使用服务：

```
export HOMESTAY_API_KEY="your_api_key_here"
export HOMESTAY_SIGN_SECRET="your_sign_secret_here"
```

## 🚀 MCP客户端配置

```json
{
  "mcpServers": {
    "homestay-finder": {
      "command": "uvx",
      "args": ["mcp-homestay-finder"],
      "env": {
        "HOMESTAY_API_KEY": "",
        "HOMESTAY_SIGN_SECRET": ""
      }
    }
  }
}
```

💡 HOMESTAY_API_KEY和HOMESTAY_SIGN_SECRET留空即可使用内置密钥。

## 📄 许可证

MIT License
