使用说明

主控程序

全球酒店供应链管理系统

全球酒店预订MCP客户

这是一个基于FastMCP框架的酒店预订服务客户端，提供酒店搜索、详细信息查询和价格查询功能。

📋 目录

特性
环境要求
安装
快速开始
API方法
详细示例
错误处理
常见问题

🚀 特性

✅ 按地址（纬度/经度）搜索酒店
✅ 按酒店名称搜索酒店
✅ 查询酒店详细信息
✅ 查询实时酒店价格和可用房间类型
✅ 多语言支持（中文/英文）
✅ 异步编程实现高性能
✅ 综合录井

📦 环境要求

Python 3.8+
有效的API密钥和密钥

🔧 安装

1.安装依赖项

pip install -r requirements.txt

2.获取API证书

您可以通过以下两种方式获取API证书： 平台联系 或 自助注册.详情如下：

2.1核心证书

x_api_key：唯一的API访问密钥（用于身份验证）
x_secret_key：密钥（用于请求签名，请保密）

2.2自助注册（推荐）

访问官方网站: https://mcp.fusionconnectgroup.com
注册：通过电子邮件在官方网站上完成注册。
邮件验证：注册成功后收到验证邮件，点击验证链接。
获取凭据：系统将发送 x_api_key 和 x_secret_key 发送到您的注册电子邮件。

2.3账户类型和请求配额

帐户类型	请求配额
个人账户	100个请求
企业帐户	1000个请求

2.4额外配额申请

如果您需要更多请求配额，请通过以下方式联系我们：

电子邮件：yangsheng.ma@fangcang.com

3.🎯 快速开始

基础示例

import asyncio
from client import DhubMCPClient

async def main():
    # Initialize client
    client = DhubMCPClient()
    
    # Connect to server
    async with client.connect():
        # Search hotels
        result = await client.search_hotels_by_hotel_name(
            x_api_key="your_api_key",
            x_secret_key="your_secret_key",
            keyword="Tokyo",
            check_in_date="2025-12-01",
            check_out_date="2025-12-03",
            language="zh-CN",
            page_size=10
        )
        print(result)

# Run
asyncio.run(main())

4.📖 API方法

1.按地址搜索酒店 `search_hotels_by_address`

使用纬度和经度坐标搜索附近的酒店。

参数：

参数	类型	必填	说明
x_api_key	str	是	api密钥
x_secret_key	str	是	密钥
lng_google	浮点数	是	谷歌经度（6位小数）
lat_google	float	是	谷歌纬度（6位小数）
check_in_date	str	是	入住日期（格式：yyyy-MM-dd）
check_out_date	str	是	退房日期（格式：yyyy-MM-dd）
language	str	否	语言类型，默认：en-US，可选：zh-CN
price_min	浮动	否	最低价格
price_max	浮动	否	最高价格
star_ratings	列表[str]	否	星级列表，例如[“3”、“4”、“5”]
distance	int	No	距离范围（单位：公里），默认值：5
page_size	int	否	每页结果数，默认值：20，最大值：50

例子：

result = await client.search_hotels_by_address(
    x_api_key="your_api_key",
    x_secret_key="your_secret_key",
    lng_google=139.691706,  # Tokyo Station
    lat_google=35.689487,
    check_in_date="2025-12-01",
    check_out_date="2025-12-03",
    language="zh-CN",
    distance=5,
    page_size=20
)

2.按名称搜索酒店 `search_hotels_by_hotel_name`

使用酒店名称中的关键字搜索酒店。

参数：

参数	类型	必填	说明
x_api_key	str	是	api密钥
x_secret_key	str	是	密钥
关键字	str	是	酒店名称关键字
check_in_date	str	是	入住日期（格式：yyyy-MM-dd）
check_out_date	str	是	退房日期（格式：yyyy-MM-dd）
language	str	否	语言类型，默认：en-US，可选：zh-CN
price_min	浮动	否	最低价格
price_max	浮动	否	最高价格
star_ratings	列表[str]	否	星级列表
distance	int	No	距离范围（单位：公里），默认值：5
page_size	int	否	每页结果数，默认值：20，最大值：50

例子：

result = await client.search_hotels_by_hotel_name(
    x_api_key="your_api_key",
    x_secret_key="your_secret_key",
    keyword="Hilton",
    check_in_date="2025-12-01",
    check_out_date="2025-12-03",
    language="zh-CN",
    price_min=500.0,
    price_max=2000.0,
    star_ratings=["4", "5"],
    page_size=10
)

3.查询酒店详细信息 `get_hotel_details`

使用酒店ID获取酒店的详细信息。

参数：

参数	类型	必填	说明
x_api_key	str	是	api密钥
x_secret_key	str	是	密钥
hotel_id	int	是	酒店id
language	str	否	语言类型，默认：en-US，可选：zh-CN
need_facility	bool	否	是否包含设施信息，默认值：True

例子：

result = await client.get_hotel_details(
    x_api_key="your_api_key",
    x_secret_key="your_secret_key",
    hotel_id=1364848,
    language="zh-CN",
    need_facility=True
)

4.查看酒店价格 `check_hotel_price`

查询特定酒店的实时价格和可用房间类型。

参数：

参数	类型	必填	说明
x_api_key	str	是	api密钥
x_secret_key	str	是	密钥
hotel_id	int	是	酒店id
check_in_date	str	是	入住日期（格式：yyyy-MM-dd）
check_out_date	str	是	退房日期（格式：yyyy-MM-dd）
num_of_adults	int	No	默认成人人数：2
num_of_children	int	No	子项数量，默认值：0
国籍	str	否	国籍代码（ISO 2位数），默认值：CN
language	str	否	语言类型，默认：en-US，可选：zh-CN

例子：

result = await client.check_hotel_price(
    x_api_key="your_api_key",
    x_secret_key="your_secret_key",
    hotel_id=1364848,
    check_in_date="2025-12-01",
    check_out_date="2025-12-03",
    num_of_adults=2,
    num_of_children=1,
    nationality="CN",
    language="zh-CN"
)

5.💡 详细示例

完成工作流程

import asyncio
from client import DhubMCPClient
from loguru import logger
import os

async def hotel_search_workflow():
    """Complete hotel search workflow"""
    
    # Get credentials from environment variables (recommended)
    api_key = os.getenv("DHUB_API_KEY")
    secret_key = os.getenv("DHUB_SECRET_KEY")
    
    # Or use credentials directly (not recommended for production)
    # x_api_key = "your_api_key"
    # x_secret_key = "your_secret_key"
    
    # Initialize client
    client = DhubMCPClient()
    
    async with client.connect():
        # Step 1: Search for hotels
        logger.info("Step 1: Search for hotels in Tokyo")
        search_result = await client.search_hotels_by_hotel_name(
            x_api_key=api_key,
            x_secret_key=secret_key,
            keyword="Tokyo",
            check_in_date="2025-12-01",
            check_out_date="2025-12-03",
            language="zh-CN",
            page_size=5
        )
        print(f"Search Results: {search_result}\n")
        
        # Step 2: Assume hotel ID is obtained from search results
        hotel_id = 1364848  # Extract from search results in actual use
        
        # Step 3: Query hotel details
        logger.info(f"Step 2: Query details for hotel {hotel_id}")
        details = await client.get_hotel_details(
            x_api_key=api_key,
            x_secret_key=secret_key,
            hotel_id=hotel_id,
            language="zh-CN",
            need_facility=True
        )
        print(f"Hotel Details: {details}\n")
        
        # Step 4: Query price
        logger.info(f"Step 3: Check price for hotel {hotel_id}")
        price = await client.check_hotel_price(
            x_api_key=api_key,
            x_secret_key=secret_key,
            hotel_id=hotel_id,
            check_in_date="2025-12-01",
            check_out_date="2025-12-03",
            num_of_adults=2,
            num_of_children=0,
            nationality="CN",
            language="zh-CN"
        )
        print(f"Price Information: {price}\n")

if __name__ == "__main__":
    asyncio.run(hotel_search_workflow())

使用环境变量管理凭据

创建一个 .env 文件：

X_API_KEY=your_api_key_here
X_SECRET_KEY=your_secret_key_here

在代码中使用：

from dotenv import load_dotenv
import os

# Load environment variables
load_dotenv()

api_key = os.getenv("X_API_KEY")
secret_key = os.getenv("X_SECRET_KEY")

6.🖥️ 光标IDE配置

要在Cursor IDE中使用此MCP服务，请将以下配置添加到您的 mcp.json 文件：

配置文件位置：

窗户： C:\Users\<username>\.cursor\mcp.json
macOS： ~/.cursor/mcp.json
Linux： ~/.cursor/mcp.json

配置内容：

{
  "mcpServers": {
    "global_hotel_mcp": {
      "name": "Global Hotel MCP",
      "type": "http",
      "url": "https://mcp.fusionconnectgroup.com/mcp",
      "env": {
        "x_api_key": "your_api_key_here",
        "x_secret_key": "your_secret_key_here"
      }
    }
  }
}

配置参数：

参数	说明
`name`	在游标中显示名称
`type`	连接类型、用途 `http`
`url`	MCP服务端点URL
`env.x_api_key`	您的API密钥
`env.x_secret_key`	您的密钥

步骤：

打开或创建 mcp.json 文件在上面的位置
复制配置内容并替换为实际的API凭据
保存文件
重新启动游标IDE
MCP工具将在Cursor的AI助手中提供

验证：

配置后，您可以通过询问Cursor的AI助手进行验证：

“搜索东京的酒店”
“查找酒店ID 1364848的酒店详细信息”

7.🛡️ 错误处理

建议使用try-except块来处理潜在错误：

async with client.connect():
    try:
        result = await client.search_hotels_by_hotel_name(
            x_api_key=api_key,
            x_secret_key=secret_key,
            keyword="Tokyo",
            check_in_date="2025-12-01",
            check_out_date="2025-12-03",
            language="zh-CN"
        )
        print(result)
    except Exception as e:
        logger.error(f"Search failed: {e}")
        # Handle error

常见错误类型：

认证失败：检查API密钥和密钥是否正确
连接超时：检查网络连接
无效参数：验证日期格式、酒店ID和其他参数

8.❓ 常见问题

Q1：如何获得API证书？

联系平台申请API密钥和密钥。

Q2：支持哪些语言？

目前支持：

en-US：英语
zh-CN：中文

Q3：日期格式是什么？

入住/退房日期格式： yyyy-MM-dd （例如。， 2025-12-01)
必须是未来的日期
退房日期必须晚于入住日期

Q4：如何更改服务器地址？

要连接到其他服务器，请执行以下操作：

client = DhubMCPClient(base_url="https://your-custom-url.com/mcp")

Q5：如何修复Windows命令提示符中的乱码字符？

这是一个编码问题，不会影响功能。你可以：

使用PowerShell而不是CMD
设置环境变量：
```
set PYTHONIOENCODING=utf-8
chcp 65001
```

Q6：如何测试连接是否正常？

运行客户端文件：

python client.py

这将执行内置测试示例。

9. 🔗 相关链接

服务器地址: https://mcp.fusionconnectgroup.com/mcp
官方网站: https://mcp.fusionconnectgroup.com

📄 许可证

按照项目许可证使用。

🤝 技术支持

如有任何疑问，请联系技术支持团队。

版本: 1.0.0
最后更新: 2025-11-28

使用说明

主控程序

全球酒店预订MCP客户

📋 目录

🚀 特性

📦 环境要求

🔧 安装

1.安装依赖项

2.获取API证书

2.1核心证书

2.2自助注册（推荐）

2.3账户类型和请求配额

2.4额外配额申请

3.🎯 快速开始

基础示例

4.📖 API方法

1.按地址搜索酒店 search_hotels_by_address

2.按名称搜索酒店 search_hotels_by_hotel_name

3.查询酒店详细信息 get_hotel_details

4.查看酒店价格 check_hotel_price

5.💡 详细示例

完成工作流程

使用环境变量管理凭据

6.🖥️ 光标IDE配置

7.🛡️ 错误处理

8.❓ 常见问题

Q1：如何获得API证书？

Q2：支持哪些语言？

Q3：日期格式是什么？

Q4：如何更改服务器地址？

Q5：如何修复Windows命令提示符中的乱码字符？

Q6：如何测试连接是否正常？

9. 🔗 相关链接

📄 许可证

🤝 技术支持

相关 MCP

实时网络搜索服务

图像生成服务

滴滴出行MCP服务

GraphQL API交互服务

DNS分析MCP服务器

LLM增强工具包

1.按地址搜索酒店 `search_hotels_by_address`

2.按名称搜索酒店 `search_hotels_by_hotel_name`

3.查询酒店详细信息 `get_hotel_details`

4.查看酒店价格 `check_hotel_price`