CUHKSZ Booking MCP 服务器

一个基于模型上下文协议 (MCP) 的香港中文大学（深圳）场馆预订系统接口服务。

📋 目录

• 项目描述
• 可用工具
• 安装与部署
• 测试说明
• 项目架构
• 实现方式与核心逻辑
• 故障排除
• 许可证与免责声明

✨ 项目描述

一个基于模型上下文协议 (MCP) 的香港中文大学（深圳）场馆预订系统接口服务，该服务使语言模型能够查询场地信息、检查可用时段并执行在线预订。

🛠️ 可用工具

本服务提供了一套结构化的工具，用于查询和预订场地。推荐的调用流程是：

1. 使用 booking_get_field_info 获取目标场地类型的总体信息，包括其下的具体场所列表及其 ID。
2. 使用 booking_get_all_available_slots 查看指定时间范围内所有场地的详细可用时间段。
3. 使用 booking_get_available_places 查询在特定时间段内，哪些具体场所是可用的。
4. 使用 booking_book 预订一个确切的可用场所。

---

1. booking_get_field_info

查询指定场地类型在某一天内的基本信息，包括所有具体场所的列表和当天的预订情况。

• 参数说明:

  • field (Literal["badminton"]): 必须。要查询的场地类型。
    • 约束: 目前仅支持 "badminton"。必须使用英文名称。
  • start_time (string): 必须。查询范围的开始时间。
    • 格式: YYYY-MM-DD HH:MM。
  • end_time (string): 必须。查询范围的结束时间。
    • 格式: YYYY-MM-DD HH:MM。

• 返回示例:

  场地信息:
  场地名称: badminton
  场地ID: 1097
  
  可用场所:
    - 羽毛球场1 (ID: 1100)
    - 羽毛球场2 (ID: 1101)
    ...
  
  当前预订 (3 个):
    - Booker: 张三, Start Time: ..., End Time: ..., Reason: ..., PlaceID: 1100
    ...
  

---

2. booking_get_all_available_slots

查询指定时间范围内，每个场地所有可用的具体时间段。这会返回一个详细的时间段列表，显示每个场地在指定日期范围内的所有可用时间段。

• 参数说明:

  • field (Literal["badminton"]): 必须。要查询的场地类型。
    • 约束: 目前仅支持 "badminton"。必须使用英文名称。
  • start_time (string): 必须。查询的开始时间。
    • 格式: YYYY-MM-DD HH:MM。
  • end_time (string): 必须。查询的结束时间。
    • 格式: YYYY-MM-DD HH:MM。

• 返回示例:

  查询时间段 2025-01-01 08:00 到 2025-01-01 22:00 内的所有可用时间段:
  
  场地: 羽毛球场1 (ID: 1100)
    - 2025-01-01 08:00 到 2025-01-01 09:00
    - 2025-01-01 10:00 到 2025-01-01 12:00
    - 2025-01-01 14:00 到 2025-01-01 16:00
  
  场地: 羽毛球场2 (ID: 1101)
    - 2025-01-01 09:00 到 2025-01-01 11:00
    - 2025-01-01 13:00 到 2025-01-01 15:00
  

---

3. booking_get_available_places

根据 booking_get_field_info 的结果，查询在您指定的时间段内，哪些具体的场所是空闲的。

• 参数说明:

  • field (Literal["badminton"]): 必须。要查询的场地类型。
    • 约束: 目前仅支持 "badminton"。必须使用英文名称。
  • query_start_time (string) & query_end_time (string): 必须。用于获取当天预订信息的查询范围，通常是场地开放的一整天（如 08:00 到 22:00）。
    • 格式: YYYY-MM-DD HH:MM。
  • check_start_time (string) & check_end_time (string): 必须。您希望预订的具体时间段。
    • 格式: YYYY-MM-DD HH:MM。

• 返回示例:

  时间段 2025-01-01 17:00 到 2025-01-01 18:00 的可用场地:
  
    - 羽毛球场2 (ID: 1101)
    - 羽毛球场4 (ID: 1103)
  
  共 2 个场地可用
  

---

4. booking_book

执行预订操作。您需要提供从其他工具中获取的 ID。预订系统会自动进行以下验证：

重要验证规则:

1. 时间范围限制: 只能预订今明两天的时间段
2. 预订时间限制: 场馆每天的有效预订时间为 08:00 至 22:00
3. 时长限制: 单次预订时长不能超过1小时
4. 频率限制: 每周最多预订1次
5. 预订前必须先查询可用场地

• 参数说明:

  • field_id (string): 必须。要预订的场地类型的 ID，从 booking_get_field_info 获取 (例如，羽毛球场地的 ID 是 "1097")。
  • place_id (string): 必须。要预订的具体场所的 ID，从 booking_get_available_places 的返回结果中选取。
  • start_time (string) & end_time (string): 必须。预订的起止时间。
    • 格式: YYYY-MM-DD HH:MM。
    • 限制: 只能预订今明两天，且必须在08:00-22:00之间。
  • telephone (string): 必须。您的联系电话。
  • reason (string): 必须。预订原因或主题 (例如 "🏸" 或 "Badminton Practice")。
  • details (string): 必须。预订的详细说明。

• 返回示例:

  预订成功！
  
  场地ID: 1097
  场所ID: 1101
  时间: 2025-01-01 10:00 到 2025-01-01 11:00
  联系电话: 1234567890
  预订原因: 🏸
  详细说明: 和朋友一起练习羽毛球
  
  请按时到场并遵守场馆规定。
  

🚀 安装与部署

本服务支持 Docker 部署和本地运行两种方式。

1. 使用 Docker (推荐)

此方法最简单，推荐用于生产和日常使用。

a. 环境准备

• 安装 Docker 和 Docker Compose。
• 克隆项目:

  git clone https://github.com/BetterAndBetterII/awesome-cuhksz-mcp.git
  cd BOOKING-MCP
  

b. 配置凭证

在项目根目录 (BOOKING-MCP/) 创建一个 .env 文件，并填入您的凭证。

# .env 文件内容
BOOKING_USERNAME=你的学号
BOOKING_PASSWORD=你的密码

⚠️ 安全提醒: 请勿将 .env 文件提交到版本控制系统。

c. 构建和启动服务

# 构建并以守护进程模式启动容器
docker-compose up --build -d

# 查看实时日志
docker-compose logs -f booking-mcp

# 停止服务
docker-compose down

服务启动后，将在 http://localhost:3001 上提供 MCP 接口。

2. 本地运行 (用于开发)

a. 环境准备

克隆项目并进入目录：

git clone https://github.com/BetterAndBetterII/awesome-cuhksz-mcp.git
cd BOOKING-MCP

创建并激活 Python 虚拟环境：

python3 -m venv .venv
source .venv/bin/activate

安装项目依赖（以可编辑模式）：

pip install -e .

b. 配置凭证

您可以通过以下两种方式提供凭证（命令行参数优先）：

1. （推荐）创建 .env 文件: 在项目根目录 (BOOKING-MCP/) 下创建一个 .env 文件。

   # .env 文件内容
   BOOKING_USERNAME=你的学号
   BOOKING_PASSWORD=你的密码
   

2. 命令行参数: 在启动命令中直接提供。

c. 启动服务

• 如果您配置了 .env 文件：

  # 使用模块名启动 (默认使用 stdio 传输)
  python -m mcp_server_booking
  # 或
  mcp-server-booking
  

• 如果您希望使用命令行参数 (默认使用 stdio 传输)：

  python -m mcp_server_booking --username 你的学号 --password 你的密码
  

注意: stdio 模式用于直接的进程间通信，不会监听网络端口。如果需要通过网络（如 http://localhost:3001）访问服务，或运行 test/test.py 脚本，必须在启动时指定 sse 传输模式：

python -m mcp_server_booking --transport sse

• 如果您希望使用命令行参数提供凭证并使用 SSE 传输：

  python -m mcp_server_booking --transport sse --username 你的学号 --password 你的密码
  

当使用 sse 模式启动后，服务将在 http://localhost:3001 上提供 MCP 接口。

📄 项目架构

核心模块说明

• **`