Ziara酒店API MCP服务器
一个MCP(模型上下文协议)服务器,提供工具以与Ziara酒店API进行交互,用于酒店搜索、预订管理和信息检索。
用……建造 FastMCP 2.0 - 生产MCP(多芯片封装)应用程序的标准框架。
特点/特性
- 酒店搜索按城市、日期和房间需求搜索可用酒店
- 房间信息获取特定酒店的详细房间选项
- 政策详情获取预订政策和取消条款
- 酒店详情获取全面的酒店信息
- 预订管理列出并查看酒店预订信息
- 自动认证自动登录和令牌刷新
安装
- 导航至服务器目录:```bash
cd ziara-hotel-mcp
2. **安装依赖项:**```bash
pip install -r requirements.txt
- 配置凭据:```bash
cp .env.example .env
编辑 `.env` 并添加您的Ziara API凭据:```env
ZIARA_EMAIL=your-email@example.com
ZIARA_PASSWORD=your-password
ZIARA_DEVICE_ID=your-device-id
与Cline的配置
要使用此MCP服务器与Cline配合,请将其添加到您的MCP设置中:
Windows
编辑: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
macOS/Linux
编辑: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
添加以下配置:```json
{
"mcpServers": {
"ziara-hotel": {
"command": "python",
"args": [
"c:/ai/ZiaraBot/ziara-hotel-mcp/server.py"
]
}
}
}
**注:** 调整路径以匹配您的实际安装目录。
## 可用工具
### 1. 搜索酒店
根据标准搜索可用酒店。
**参数:**
- `city_id` (整数,必填):城市ID(例如,麦地那为4359,麦加为12839)
- `start` (字符串,必填):入住日期(MM/DD/YYYY 格式)
- `end` (字符串,必填):退房日期(MM/DD/YYYY 格式)
- `nationality` (字符串,必填):客人国籍(例如,“巴基斯坦”)
- `residency` (字符串,必填):访客居住地代码(例如,“PK”)
- `currency` (字符串,必填):货币代码(例如,“PKR”,“USD”)
- `rooms` (数组,必需):房间需求的数组
- `adults` (整数):成人数量
- `childCount` (整数):子女数量
- `child_ages` (数组):儿童年龄(可选)
**示例:**```json
{
"city_id": 12839,
"start": "01/15/2025",
"end": "01/20/2025",
"nationality": "Pakistan",
"residency": "PK",
"currency": "PKR",
"rooms": [
{
"adults": 2,
"childCount": 0,
"child_ages": []
}
]
}
2. 获取酒店房间
查询特定酒店的可用房间。
参数:
hotel_index(字符串,必填):搜索结果中的酒店索引session_id(字符串,必填):搜索结果中的会话ID
3. 获取酒店政策
获取特定房间套餐的预订政策。
参数:
hotel_index(字符串,必填):酒店索引标识符package_id(字符串,必填):套餐/房间IDsession_id(字符串,必填):来自搜索的会话ID
4. 获取酒店详情
获取特定酒店的详细信息。
参数:
slug(字符串,必填):酒店的唯一标识符(slug)
5. 列出酒店预订列表
列出酒店预订记录,并可选择应用过滤条件。
参数(全部可选):
from_date(字符串): 开始日期过滤器 (YYYY-MM-DD)to_date(字符串):结束日期过滤器 (YYYY-MM-DD)search(字符串):搜索过滤器(状态、包ID或预订类型)per_page(整数):每页结果数量page(整数):页码
6. 获取预订详情
获取特定酒店预订的详细信息。
参数:
booking_id(整数,必填):预订ID
使用示例
示例1:搜索麦加的酒店```
Search for hotels in Makkah (city_id: 12839) from January 15-20, 2025 for 2 adults in PKR currency
### 示例2:查看预订历史```
List all hotel bookings with status "pending"
示例3:获取预订详情```
Get details for booking ID 7
## 运行服务器
服务器可以通过多种方式运行:
### 开发(本地)```bash
# Using FastMCP CLI
fastmcp run server.py
# Or directly with Python
python server.py
生产(HTTP)
服务器默认使用stdio传输方式,但您可以将其配置为HTTP:```python
In server.py, modify the run command:
if name == "main":
mcp.run(transport="http", host="0.0.0.0", port=8000)
### 使用FastMCP开发命令
对于带自动重载功能的开发:```bash
fastmcp dev server.py
API 端点使用情况
- 认证:
https://b2b.ziara.co/api/auth/login - 酒店运营:
https://new-api.ziara.co/api/v1.6/hotels/* - 预订管理:
https://b2b.ziara.co/api/hotel-bookings/*
它是如何运作的
这台服务器使用 FastMCP 2.0它提供了一个高级、Python化的接口来构建MCP服务器。每个工具都被定义为一个简单的Python函数,其中 @mcp.tool() 装饰器:```python
@mcp.tool()
def search_hotels(
city_id: int,
start: str,
end: str,
nationality: str,
residency: str,
currency: str,
rooms: List[Dict[str, Any]]
) -> Dict[str, Any]:
"""
Search for available hotels based on city, dates, and room requirements.
Args:
city_id: City ID (e.g., 4359 for Madina, 12839 for Makkah)
start: Check-in date in MM/DD/YYYY format
...
"""
Implementation
return result
FastMCP 自动地:
- 根据类型提示生成JSON模式
- 从文档字符串中提取工具描述
- 处理序列化/反序列化
- 管理MCP协议通信
## 错误处理
服务器包括:
- 令牌过期时自动刷新
- 认证失败(401响应)的重试逻辑
- 用于调试的详细错误信息
- API故障的异常处理
## 安全注意事项
- 存储凭据于 `.env` 文件(永远不要提交到版本控制系统)
- 添加 `.env` to `.gitignore`
- 令牌每23小时自动刷新一次
- 所有API请求均使用Bearer令牌进行身份验证
## 故障排除
### 常见问题
1. **认证错误**
- 验证凭据在 `.env` 文件
- 确保所有三个变量(EMAIL、PASSWORD、DEVICE_ID)都已设置
- 检查凭据是否有效
1. **导入错误**
- 跑 `pip install -r requirements.txt`
- 确保您使用的是 Python 3.10 或更高版本
- 验证FastMCP版本是否为2.0.0或更高版本: `pip show fastmcp`
1. **连接错误**
- 检查网络连接
- 验证API端点是否可访问
- 检查防火墙设置
1. **未找到工具**
- 配置更改后重启Cline/Claude桌面
- 验证MCP设置路径是否正确
- 检查配置中的server.py路径
### 测试服务器
在将服务器添加到Cline之前,您可以在本地进行测试:```bash
# Test that the server starts without errors
python server.py
# Or use FastMCP's built-in testing
fastmcp dev server.py
发展
代码结构
服务器采用简洁、模块化的结构:
- 认证:
get_auth_token()和make_api_request()处理所有API认证 - 工具每个
@mcp.tool()装饰函数表示一个API操作 - 类型安全完整的类型提示,以更好地支持集成开发环境(IDE)和错误捕获
- 文档为自动生成的模式提供全面的文档字符串
添加新工具
要添加一个新工具,只需定义一个具有以下(特性/参数等,根据上下文补充完整)的函数即可 @mcp.tool() 装饰器:```python
@mcp.tool()
def new_operation(param1: str, param2: int) -> Dict[str, Any]:
"""
Description of what this tool does.
Args:
param1: Description of param1
param2: Description of param2
Returns:
Description of return value
"""
Implementation
return result
FastMCP 将自动注册它并使其对客户端可用。
## 建筑学```
┌─────────────────┐
│ MCP Client │
│ (Cline/Claude) │
└────────┬────────┘
│ MCP Protocol
│
┌────────▼────────┐
│ FastMCP 2.0 │
│ Server │
├─────────────────┤
│ @mcp.tool() │
│ decorators │
└────────┬────────┘
│ HTTP/S
│
┌────────▼────────┐
│ Ziara Hotel │
│ API │
└─────────────────┘
许可证
此MCP服务器按原样提供,用于与Ziara酒店API配合使用。
支持
- Ziara API支持如需API相关问题,请联系Ziara
更新日志
2.0版本(当前)
- 已迁移到FastMCP 2.0 API
- 使用装饰器简化工具定义
- 从类型提示自动生成模式
- 改进了错误处理
- 代码复杂度降低了约60%
