Barbercontrol MCP

BarberControl MCP服务器

FastMCP服务器，使语音助手能够与BarberControl预约系统进行交互。

概述

此MCP服务器公开了4个工具，允许外部语音代理：

• 查询可用理发师
• 查看具体日期的可用性
• 查看多日可用性窗口
• 预约并通知理发师

语音助手集成流程

Client calls → Voice Agent (external) → MCP Server → Supabase Database
                                          ↓
                                    Push notification to barber

MCP工具

1. get_barbers()

列出系统中的所有理发师及其联系信息。

退货： 理发师名单，包括身份证、姓名、电子邮件和电话

2. check_barber_availability(barber_id, date)

查看特定日期特定理发师的可用性。

参数：

• barber_id （string）：理发师的UUID
• date （字符串）：YYYY-MM-DD格式的日期

退货： 有预订次数的可用时段（每个时段最多2个）

3. get_available_slots(barber_id, start_date, end_date)

获取一个日期范围内的可用插槽（最多30天）。

参数：

• barber_id （string）：理发师的UUID
• start_date （字符串）：YYYY-MM-DD格式的开始日期
• end_date （字符串）：YYYY-MM-DD格式的结束日期

退货： 按日期组织的可用插槽，剩余容量

4. book_appointment(barber_id, client_name, client_phone, date, time_slot, client_email?, notes?)

为客户预约。

参数：

• barber_id （string）：理发师的UUID
• client_name （string）：客户端的全名
• client_phone （string）：电话号码
• date （字符串）：YYYY-MM-DD格式的日期
• time_slot （string）：时间段（例如，“上午9:00”）
• client_email （字符串，可选）：电子邮件地址
• notes （字符串，可选）：预约备注

退货： 确认预约详情

地方发展

1.安装依赖项

cd mcp_server
pip install -r requirements.txt

2.配置环境

创建 .env 文件在 mcp_server/ 目录：

cp .env.example .env

编辑 .env 使用您的Supabase凭据：

• NEXT_PUBLIC_SUPABASE_URL：来自Supabase仪表板→ 设置→ API
• SUPABASE_SERVICE_ROLE_KEY：来自Supabase仪表板→ 设置→ API → service_role密钥

⚠️ 重要提示： 服务角色密钥绕过行级安全。保守秘密！

3.本地运行

# Development mode
python barbercontrol.py

# Or using FastMCP CLI
fastmcp dev barbercontrol.py

4.使用MCP检查员进行测试

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run inspector
mcp-inspector python barbercontrol.py

访问http://localhost:6274以交互方式测试工具。

部署到FastMCP云

选项1：通过GitHub部署

1. 创建GitHub存储库

   cd mcp_server
   git init
   git add .
   git commit -m "Initial commit"
   git branch -M main
   git remote add origin https://github.com/yourusername/barbercontrol-mcp.git
   git push -u origin main

1. 在FastMCP云上部署

- 访问https://fastmcp.com - 使用GitHub登录 - 点击“部署MCP服务器” - 选择您的存储库 - 添加环境变量： - NEXT_PUBLIC_SUPABASE_URL - SUPABASE_SERVICE_ROLE_KEY - 点击“部署”

1. 获取您的MCP端点

- 复制生成的MCP服务器URL - 在语音助手配置中使用此功能

选项2：通过CLI部署

1. 安装FastMCP命令行界面

   pip install fastmcp

1. 登录FastMCP

   fastmcp login

1. 部署

   fastmcp deploy

1. 设置环境变量

   fastmcp env set NEXT_PUBLIC_SUPABASE_URL "https://your-project.supabase.co"
   fastmcp env set SUPABASE_SERVICE_ROLE_KEY "your-service-role-key"

连接语音助手

部署后，配置您的语音助手以使用MCP服务器：

适用于克劳德桌面

增添 claude_desktop_config.json:

{
  "mcpServers": {
    "barbercontrol": {
      "url": "https://your-fastmcp-url.fastmcp.com"
    }
  }
}

用于自定义语音代理

在您的语音代理中使用MCP客户端SDK：

from mcp import Client

client = Client("https://your-fastmcp-url.fastmcp.com")

# Check availability
result = await client.call_tool("check_barber_availability", {
    "barber_id": "e0c8c546-b205-4fbf-bf89-e0dce022fdb0",
    "date": "2025-01-20"
})

# Book appointment
result = await client.call_tool("book_appointment", {
    "barber_id": "e0c8c546-b205-4fbf-bf89-e0dce022fdb0",
    "client_name": "John Doe",
    "client_phone": "555-1234",
    "date": "2025-01-20",
    "time_slot": "10:00 AM"
})

数据库模式

MCP服务器与这些Supabase表交互：

• 理发师：理发师信息（身份证、姓名、电子邮件、电话）
• 可用性_地块：具有可用性状态的时隙（2个客户端限制）
• 预约：已预约并提供客户详细信息
• 推送订阅：为理发师推送通知订阅

2客户每小时限额

数据库使用触发器强制每个时隙最多2个约会：

• check_max_appointments_trigger：如果已有2位客户预订，则阻止预订
• auto_update_availability_trigger：满时自动标记插槽不可用

安全

• 使用Supabase服务角色键访问数据库
• 所有数据库操作都遵守现有的RLS策略
• 响应中从不暴露环境变量
• 推送通知通过Supabase安全发送

故障排除

“缺少必需的环境变量”

• 确保 .env 文件存在正确的变量
• 在FastMCP Cloud上，验证仪表板中是否设置了环境变量

“未找到可用性”

• 检查理发师是否在BarberControl应用程序中创建了可用性插槽
• 验证 is_available 设置为 true 对于时间段
• 确认日期格式为YYYY-MM-DD

“时段已满”

• 每小时最多执行2个客户端
• 检查该时段的现有预约
• 向客户建议其他时间段

推送通知不起作用

• 验证理发师是否已订阅应用程序中的推送通知
• 检查 push_subscriptions 桌子上有理发师的条目
• 发送通知需要额外的网络推送设置（可选）

监控

FastMCP云仪表板

• 查看日志https://fastmcp.com/dashboard
• 监控工具使用情况和错误
• 检查响应时间

Supabase仪表板

• 在数据库中查看约会→ 表格→ 预约
• 检查availability_slots表中的可用性插槽
• 监控推送订阅

支持

对于问题或疑问：

• FastMCP文档：https://docs.fastmcp.com
• Supabase文档：https://supabase.com/docs
• GitHub问题：\[您的存储库URL\]

许可证

\[您的许可证在这里\]