OnceHub MCP Server

OnceHub MCP 服务

OnceHub MCP 服务为 AI models 和 agents 提供了一种标准化方式，使它们能够直接与您的 OnceHub 日程安排 API 交互。AI Agent 无需向用户发送预订链接并让他们手动安排，而是可以通过 MCP 工具，以自然语言流程查询可用时间并代表用户安排会议。 该解决方案使用标准化的模型上下文协议（MCP）远程服务，使外部 AI Agent 能够在 AI 驱动的工作流中访问 OnceHub 日程安排 API。

兼容： VS Code Copilot、OpenAI，以及任何兼容 MCP 的 AI 客户端。

目录

• 功能
• 快速开始
• 架构
• 工具
• 客户端配置
• 安装
• 测试
• 生产部署
• 参与贡献
• 许可证

功能

• 🔌 MCP 协议支持 - 适用于任何兼容 MCP 的 AI 客户端
• 📅 时段查询 - 从 OnceHub 预订日历获取可用时段
• 🗓️ 会议安排 - 根据访客信息自动安排会议
• 🔐 安全认证 - 通过标头使用基于 API 密钥的认证
• 🧪 经过充分测试 - 代码覆盖率达 92%，并配有全面的单元测试
• 🐳 支持 Docker - 容器化，便于部署
• 📝 适用于 AI 的提示词 - 内置面向 AI 助手的工作流指引

快速开始

在您的 AI 客户端中开始使用 OnceHub MCP 服务：

1. 获取 API 密钥

从认证文档获取您的 OnceHub API 密钥。

2. 配置客户端

在您的工作区中创建 .vscode/mcp.json：

{
  "servers": {
    "oncehub": {
      "url": "https://mcp.oncehub.com/sse",
      "type": "http",
      "headers": {
        "authorization": "Bearer YOUR_ONCEHUB_API_KEY"
      }
    }
  }
}

将 YOUR_ONCEHUB_API_KEY 替换为您的实际 API 密钥。

3. 开始使用

向您的 AI 助手提出以下请求：

• “显示日历 BKC-XXXXXXXXXX 的可用时段”
• “安排明天下午 2 点与 John Doe 开会”

⚠️ 运行自己的 MCP 服务？ 请参阅安装与本地运行中的设置说明。

✅ 生产服务： 我们托管的 MCP 服务地址为 https://mcp.oncehub.com/sse。

架构

项目结构

mcp-server/
├── main.py              # MCP server with tool definitions
├── models.py            # Pydantic data schemas for BookingForm and Location
├── pyproject.toml       # Project dependencies and configuration
├── Dockerfile           # Docker image configuration
├── .dockerignore        # Files to exclude from Docker build
└── README.md            # This file

工具

1. get_booking_time_slots

从预订日历中查询可用时段。

参数：

• calendar_id (str，必填)：预订日历 ID（例如，'BKC-XXXXXXXXXX'）
• start_time (str，可选)：按此 ISO 8601 格式的日期时间筛选时段（例如，'2026-02-15T09:00:00Z'）
• end_time (str，可选)：筛选截至此 ISO 8601 格式日期时间的时段（例如，'2026-02-28T17:00:00Z'）
• timeout (int，默认值：30)：请求超时时间，单位为秒

响应示例：

{
  "success": true,
  "status_code": 200,
  "calendar_id": "BKC-XXXXXXXXXX",
  "total_slots": 5,
  "data": [
    {"start_time": "2026-02-10T10:00:00Z", "end_time": "2026-02-10T11:00:00Z"},
    {"start_time": "2026-02-10T14:00:00Z", "end_time": "2026-02-10T15:00:00Z"}
  ]
}

2. schedule_meeting

在指定时段安排会议。务必先调用 get_booking_time_slots，以确保该时段可用。

参数：

• calendar_id（str，必填）：预订日历的 ID（例如：'BKC-XXXXXXXXXX'）
• start_time（str，必填）：可用时段的确切开始时间，采用 ISO 8601 格式
• guest_time_zone（str，必填）：访客的时区，采用 IANA 格式（例如：'America/New_York'、'Europe/London'）
• guest_name（str，必填）：访客的全名
• guest_email（str，必填）：用于接收确认信息的访客电子邮件地址
• guest_phone（str，可选）：访客的电话号码，采用 E.164 格式（例如：'+15551234567'）
• location_type（str，可选）：会议方式——'virtual'、'virtual_static'、'physical' 或 'guest_phone'
• location_value（str，可选）：根据类型填写的地点详情：
  • virtual：提供商名称（例如：'zoom'、'google_meet'、'microsoft_teams'）
  • virtual_static：使用 null
  • physical：地址 ID（例如：'ADD-XXXXXXXXXX'）
  • guest_phone：电话号码，采用 E.164 格式
• custom_fields（dict，可选）：自定义表单字段，采用键值对格式（例如：{"company": "Acme", "interests": ["Demo"]}）
• timeout（int，默认值：30）：请求超时时间，单位为秒

响应示例：

{
  "success": true,
  "status_code": 200,
  "booking_id": "BKG-123456789",
  "confirmation": {
    "guest_name": "John Doe",
    "guest_email": "[email protected]",
    "scheduled_time": "2026-02-10T10:00:00Z",
    "timezone": "America/New_York"
  }
}

前提条件

• Python 3.13 或更高版本
• uv 包管理器（推荐）
• OnceHub API 密钥——请参阅身份验证文档以获取 API 密钥
• OnceHub API 端点 URL（通常为 https://api.oncehub.com）

环境变量

创建 .env 文件或设置以下环境变量：

# Required: Your OnceHub API endpoint
ONCEHUB_API_URL=https://api.oncehub.com

# Note: API key is passed via Authorization header from MCP clients
# Do NOT commit API keys to version control

客户端配置

此 MCP 服务兼容 VS Code Copilot、Claude Desktop、OpenAI 及其他兼容 MCP 的客户端。

VS Code / GitHub Copilot

第 1 步：创建配置目录

Windows（PowerShell）：

New-Item -Path ".vscode" -ItemType Directory -Force
New-Item -Path ".vscode\mcp.json" -ItemType File -Force

macOS/Linux：

mkdir -p .vscode
touch .vscode/mcp.json

第 2 步：配置服务

编辑 .vscode/mcp.json：

{
  "servers": {
    "oncehub": {
      "url": "http://0.0.0.0:8000/sse",
      "type": "http",
      "headers": {
        "authorization": "Bearer YOUR_ONCEHUB_API_KEY"
      }
    }
  }
}

配置选项：

• url：MCP 服务端点（如果可自托管，请改为你的服务 URL）
• authorization：添加 Bearer 前缀的 OnceHub API 密钥
• 服务名称（oncehub）：可自定义为任意标识符

第 3 步：重新加载 VS Code

保存配置后，重新加载 VS Code 以激活与 MCP 服务的连接。

Claude Desktop

编辑 Claude Desktop 配置文件：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "oncehub": {
      "url": "http://0.0.0.0:8000/sse",
      "headers": {
        "authorization": "Bearer YOUR_ONCEHUB_API_KEY"
      }
    }
  }
}

保存后重启 Claude Desktop。

其他 MCP 客户端

对于其他兼容 MCP 的客户端，请配置它们连接到：

• 端点： http://0.0.0.0:8000/sse
• 协议： 使用服务器发送事件（SSE）的 HTTP
• 身份验证： 在 Authorization 标头中使用 Bearer 令牌

**安全提示：**切勿将 API 密钥提交到版本控制系统。生产部署时，请使用环境变量或安全的密钥管理方式。

使用 uv 在本地安装和运行

1. 安装 uv（如果尚未安装）

Windows（PowerShell）：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

2. 克隆仓库

git clone https://github.com/scheduleonce/mcp-server.git
cd mcp-server

3. 设置环境变量

Windows（PowerShell）：

$env:ONCEHUB_API_URL="https://api.oncehub.com"

macOS/Linux：

export ONCEHUB_API_URL="https://api.oncehub.com"

或者创建 .env 文件：

echo "ONCEHUB_API_URL=https://api.oncehub.com" > .env

**注意：**API 密钥通过 MCP 客户端的 Authorization 标头传递（而非作为环境变量）。

4. 使用 uv 运行服务

选项 1：直接执行

uv run main.py

选项 2：使用脚本入口点

uv run mcp-server

服务将在 http://0.0.0.0:8000 上启动

5. 验证服务是否正在运行

健康检查：

curl http://localhost:8000/health

连接到 SSE 端点：

curl http://localhost:8000/sse

使用 Docker 运行

构建 Docker 镜像

docker build -t mcp-server .

运行容器

docker run -p 8000:8000 mcp-server

使用环境变量

docker run -p 8000:8000 \
  -e ONCEHUB_API_URL="https://api.oncehub.com" \
  mcp-server

使用 Docker Compose（推荐）

创建 docker-compose.yml：

version: '3.8'
services:
  mcp-server:
    build: .
    ports:
      - "8000:8000"
    environment:
      - ONCEHUB_API_URL=https://api.oncehub.com
    restart: unless-stopped

然后运行：

docker-compose up -d

数据架构

Location

表示会议地点详情。

字段：

• type（str）：地点类型（"physical"、"virtual"、"phone"）
• value（str）：地点详情（地址、URL、电话号码）

日志记录

服务器会全面记录发送至 OnceHub 的 HTTP 请求：

• 发出的请求（→）
• 响应状态码（←）
• 请求/响应正文

日志会附带时间戳和日志级别输出到控制台。

API 端点

• GET /health - 健康检查端点
• GET /healthy - 备用健康检查端点
• GET /sse - 用于 MCP 协议通信的服务器发送事件端点
• GET /tools - 返回已注册的 MCP 工具及其说明、必需参数和输入字段详情

开发

手动安装依赖项

uv pip install fastmcp pydantic httpx

安装测试依赖项

uv pip install -e ".[test]"

使用不同的日志级别运行

编辑 main.py 并更改 log_level 参数：

asyncio.run(mcp.run_sse_async(host="0.0.0.0", port=8000, log_level="debug"))

可用的日志级别："debug"、"info"、"warning"、"error"、"critical"

测试

该项目为所有工具和函数提供了全面的单元测试。

安装测试依赖项

# Install test dependencies
uv pip install pytest pytest-asyncio pytest-cov pytest-mock

运行测试

运行所有测试：

uv run pytest

运行测试并生成覆盖率报告：

uv run pytest --cov=. --cov-report=html --cov-report=term

运行指定测试文件：

uv run pytest test_tools.py

运行指定测试类：

uv run pytest test_tools.py::TestGetBookingTimeSlots

运行指定测试：

uv run pytest test_tools.py::TestGetBookingTimeSlots::test_get_time_slots_success

以详细模式运行：

uv run pytest -v

运行并在首次失败时停止：

uv run pytest -x

测试覆盖率

运行测试并生成覆盖率报告后，打开 HTML 报告：

# Windows
start htmlcov/index.html

# macOS
open htmlcov/index.html

# Linux
xdg-open htmlcov/index.html

测试结构

• test_tools.py - 所有工具函数的单元测试
  • TestGetApiKeyFromContext - API 密钥提取测试
  • TestGetBookingTimeSlots - 时间段检索测试
  • TestScheduleMeeting - 会议安排测试

所有测试均使用模拟，避免实际 API 调用，从而确保测试执行快速可靠。

生产环境部署

安全最佳实践

1. API 密钥管理

   • 切勿将 API 密钥提交到版本控制系统
   • 使用环境变量或密钥管理系统
   • 定期轮换 API 密钥

2. 网络安全

   • 在生产环境中使用 HTTPS（添加 nginx 等反向代理）
   • 实施速率限制以防止滥用
   • 使用防火墙规则限制访问

3. 监控

   • 监控 /health 端点以确保服务可用
   • 设置日志聚合（例如 ELK 堆栈、CloudWatch）
   • 跟踪 API 响应时间和错误率

部署选项

Docker 部署

# Build and tag the image
docker build -t oncehub-mcp-server:1.0.0 .

# Run with restart policy
docker run -d \
  --name oncehub-mcp \
  --restart unless-stopped \
  -p 8000:8000 \
  -e ONCEHUB_API_URL="https://api.oncehub.com" \
  oncehub-mcp-server:1.0.0

云端部署

• AWS：使用 ECS、Fargate 或 EC2，并搭配 Application Load Balancer
• Azure：部署到 Azure Container Instances 或 App Service
• GCP：使用 Cloud Run 或 Google Kubernetes Engine

性能注意事项

• 默认超时时间为 30 秒，可根据需求调整
• 服务器使用 asyncio 并发处理请求
• 对于高流量场景，可考虑水平扩展
• 如果添加数据库/缓存，请使用连接池

健康监控

# Simple health check script
curl -f http://localhost:8000/health || exit 1

# Docker healthcheck (add to Dockerfile)
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

故障排除

错误："API key is required"

调用工具时，请确保传入 api_key 参数。

/health 上出现错误："404 Not Found"

请确保服务器正在运行，且可通过端口 8000 访问。

/sse 上出现错误："405 Method Not Allowed"

SSE 端点需要 GET 请求，而不是 POST。请使用合适的 MCP 客户端库，或通过 curl 发送 GET 请求。

未显示 OnceHub 请求日志

请检查 main.py 中的日志配置是否正确，并确认服务器以 log_level="info" 或 "debug" 运行。

许可证

本项目采用 MIT 开源许可证。完整条款请参阅 MIT。

支持

• 文档：OnceHub API 文档
• 问题反馈：GitHub Issues
• MCP 协议：Model Context Protocol

致谢

• 使用 FastMCP 构建
• 兼容 Model Context Protocol
• 由 OnceHub API 提供支持

---

由 Oncehub 团队制作