ziara MCP

Ziara酒店API MCP服务器

一个MCP（模型上下文协议）服务器，提供工具以与Ziara酒店API进行交互，用于酒店搜索、预订管理和信息检索。

用……建造 FastMCP 2.0 - 生产MCP（多芯片封装）应用程序的标准框架。

特点/特性

• 酒店搜索按城市、日期和房间需求搜索可用酒店
• 房间信息获取特定酒店的详细房间选项
• 政策详情获取预订政策和取消条款
• 酒店详情获取全面的酒店信息
• 预订管理列出并查看酒店预订信息
• 自动认证自动登录和令牌刷新

安装

1. 导航至服务器目录：

cd ziara-hotel-mcp

1. 安装依赖项：

pip install -r requirements.txt

1. 配置凭据：

cp .env.example .env

编辑 .env 并添加您的Ziara API凭据：

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

添加以下配置：

{
  "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 (数组)：儿童年龄（可选）

示例：

{
  "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 （字符串，必填）：套餐/房间ID
• session_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

运行服务器

服务器可以通过多种方式运行：

开发（本地）

# Using FastMCP CLI
fastmcp run server.py

# Or directly with Python
python server.py

生产（HTTP）

服务器默认使用stdio传输方式，但您可以将其配置为HTTP：

# In server.py, modify the run command:
if __name__ == "__main__":
    mcp.run(transport="http", host="0.0.0.0", port=8000)

使用FastMCP开发命令

对于带自动重载功能的开发：

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() 装饰器：

@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之前，您可以在本地进行测试：

# 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() 装饰器：

@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配合使用。

支持

• FastMCP 文档: https://gofastmcp.com（该网址可直接翻译为“https://gofastmcp.com”，因为网址本身是英文且无特定含义，直接保留原样即可。若需说明其性质，可表述为“这是一个英文网址，指向GoFastMCP的官方网站”等。）
• MCP协议： https://modelcontextprotocol.io（该网址可翻译为“模型上下文协议官方网站”，但具体翻译可能需根据网站实际内容调整）
• Ziara API支持如需API相关问题，请联系Ziara

更新日志

2.0版本（当前）

• 已迁移到FastMCP 2.0 API
• 使用装饰器简化工具定义
• 从类型提示自动生成模式
• 改进了错误处理
• 代码复杂度降低了约60%