内容
# Smile Dental MCP 服务器
牙科诊所预约管理的MCP（模型上下文协议）服务器。通过与 **n8n工作流** 连接到 **谷歌日历** 和 **Gmail** ，为AI接待员提供检查可用性和预订预约的工具。
## 架构
```
AI 助手 (MCP 客户端)
│
│ 标准输入/输出
▼
Smile Dental MCP 服务器 ──HTTP──► n8n 工作流 ──► 谷歌日历
│ + Gmail
│
└── 工具: check_availability, book_appointment
```
## 前置条件
- Python 3.12+
- pip
- 一个部署了Smile Dental工作流的n8n实例（check-availability + book-appointment webhooks）
## 安装
### 1. 安装依赖
```bash
pip install -r requirements.txt
```
### 2. 配置环境
编辑 `.env` 文件，填写您的n8n webhook URL和诊所设置：
```env
# n8n Webhook URL（如果n8n在隧道后面，请使用ngrok URL）
N8N_CHECK_AVAILABILITY_URL=https://your-ngrok-url.ngrok-free.app/webhook/check-availability
N8N_BOOK_APPOINTMENT_URL=https://your-ngrok-url.ngrok-free.app/webhook/book-appointment
# 诊所设置
CLINIC_NAME=Smile Dental Clinic
DEFAULT_TIMEZONE=America/Chicago
# n8n身份验证的API密钥（必须与n8n期望的密钥匹配）
N8N_API_KEY=smile-dental-demo-secret
# MCP服务器API密钥（客户端必须在Authorization头部发送此密钥作为Bearer令牌）
# 为生产环境生成一个强壮的随机密钥：python -c "import secrets; print(secrets.token_urlsafe(32))"
MCP_API_KEY=your-mcp-secret-key
```
## 运行
```bash
python -m app.server
```
服务器在 **SSE传输** 上启动，地址为 `http://localhost:8000`，并打印启动信息：
```
🧑⚕️ Smile Dental MCP 服务器启动...
诊所: Smile Dental Clinic
时区: America/Chicago
检查可用性 URL: https://.../webhook/check-availability
预订预约 URL: https://.../webhook/book-appointment
监听 http://0.0.0.0:8000/sse（SSE传输）...
```
## 身份验证
MCP服务器通过 `Authorization` 头部使用 **Bearer令牌身份验证**。
1. 在 `.env` 文件中设置一个强壮的API密钥：
```env
MCP_API_KEY=your-mcp-secret-key
```
使用以下命令生成一个：`python -c "import secrets; print(secrets.token_urlsafe(32))"`
2. MCP客户端在连接时必须将密钥作为Bearer令牌发送。
3. 如果 `MCP_API_KEY` 为空或未设置，则身份验证将被 **禁用**（不建议在生产环境中使用）。
## 作为MCP工具公开（SSE传输）
将此服务器添加到您的MCP客户端配置中，以便您的AI助手可以使用牙科工具。
### Cursor
在Cursor设置 → MCP服务器 → 添加：
- **名称：** `dental-mcp`
- **类型：** `sse`
- **URL：** `http://localhost:8000/sse`
- **头部（可选）：** 添加 `Authorization: Bearer your-mcp-secret-key`
### 其他MCP客户端
任何支持 **SSE传输** 的MCP客户端都可以连接。架构如下：
```json
{
"mcpServers": {
"dental-mcp": {
"type": "sse",
"url": "http://localhost:8000/sse",
"headers": {
"Authorization": "Bearer your-mcp-secret-key"
}
}
}
}
```
## 可用工具
### 1. `check_availability`
检查给定日期和首选条件下的可用预约时间段。
| 参数 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `appointmentType` | ✅ | — | 预约类型（例如，`Cleaning`，`New Patient Exam`，`Emergency`，`Follow-up Visit`，`Filling Consultation`，`Crown Consultation`，`Root Canal Consultation`） |
| `preferredDate` | ✅ | — | 日期，格式为 `YYYY-MM-DD` |
| `preferredTime` | ❌ | `Morning` | 时间偏好：`Morning`，`Afternoon`，`Evening` 或 `Any` |
| `preferredProvider` | ❌ | `""` | 首选牙医姓名（例如，`Dr. Emily Carter`）。空 = 无偏好。 |
| `patientType` | ❌ | `Existing` | `New` 或 `Existing` |
| `isEmergency` | ❌ | `false` | 是否为紧急情况 |
**返回：** 格式化后的可用时间段列表，最多5个，包含提供者信息。
### 2. `book_appointment`
为患者预订新预约。通过Gmail发送确认邮件。
| 参数 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `firstName` | ✅ | — | 患者名 |
| `lastName` | ✅ | — | 患者姓 |
| `phone` | ✅ | — | 患者电话号码 |
| `appointmentType` | ✅ | — | 预约类型（同上） |
| `appointmentDate` | ✅ | — | 日期，格式为 `YYYY-MM-DD` |
| `appointmentTime` | ✅ | — | 时间（例如，`10:30 AM`，`2:00 PM`） |
| `email` | ❌ | `""` | 患者邮箱（用于确认） |
| `dateOfBirth` | ❌ | `""` | 出生日期，格式为 `YYYY-MM-DD` |
| `patientType` | ❌ | `Existing` | `New` 或 `Existing` |
| `provider` | ❌ | `""` | 指派的提供者/牙医 |
| `hasInsurance` | ❌ | `false` | 患者是否有保险 |
| `insuranceProvider` | ❌ | `""` | 保险提供者名称 |
| `reasonForVisit` | ❌ | `""` | 访问原因 |
| `additionalNotes` | ❌ | `""` | 任何特殊请求 |
**返回：** 预约确认，包含预约ID、日期、时间和提供者。
## 示例MCP工具调用（来自AI助手）
```
用户: "我需要下周五的清洁预约。"
AI助手（调用工具）：
check_availability(
appointmentType="Cleaning",
preferredDate="2026-07-10",
preferredTime="Morning"
)
→ 显示可用时间段
用户: "预订第一个由Carter博士提供的时段。"
AI助手（调用工具）：
book_appointment(
firstName="John",
lastName="Smith",
phone="5551234567",
email="john@email.com",
appointmentType="Cleaning",
appointmentDate="2026-07-10",
appointmentTime="9:00 AM",
provider="Dr. Emily Carter",
patientType="Existing"
)
→ 确认预订 + 发送邮件
```
## 项目结构
```
dental-mcp/
├── .env # 配置（webhook URL，API密钥）
├── .gitignore # Git忽略规则
├── requirements.txt # Python依赖
├── README.md # 本文件
└── app/
├── __init__.py
├── config.py # 从.env加载的设置
├── server.py # MCP服务器入口点
├── clients/
│ ├── __init__.py
│ └── n8n_client.py # 用于n8n webhook的HTTP客户端
├── schemas/
│ ├── __init__.py
│ ├── availability.py # 可用性Pydantic模型
│ └── booking.py # 预订Pydantic模型
├── tools/
│ ├── __init__.py
│ ├── check_availability.py # check_availability工具
│ └── book_appointment.py # book_appointment工具
└── utils/
├── __init__.py
└── formatters.py # 响应格式化助手
```
