Appointment MCP Server

预约MCP服务器

一个全面的模型上下文协议（MCP）服务器，用于管理约会、员工和业务运营，使用Node.js和TypeScript构建。

特性

核心任命管理

• 使用标题、日期、时间和可选描述创建新约会
• 列出所有具有筛选和排序选项的约会
• 按ID获取具体预约详情
• 按ID删除约会
• 更新预约状态和详细信息
• 日期和时间格式的输入验证

员工管理

• 获取全面的员工信息，包括服务和工作时间
• 查看特定日期的员工可用性
• 获取员工个人的详细信息
• 查看员工休假时间表
• 员工服务任务和专业化

可用性和预订

• 获取特定服务和日期的可用时段
• 实时可用性检查与预订能力
• 基于服务持续时间和缓冲时间的时隙生成
• 与现有约会的冲突检测

客户管理

• 创建和管理客户档案
• 按姓名、电子邮件或电话搜索客户
• 更新客户信息
• 查看客户预约历史记录
• 客户评价和评级

业务运营

• API密钥认证支持多企业
• 营业时间管理
• 服务目录管理
• 业务详细信息和配置

技术特性

• 使用PostgreSQL数据库的持久存储
• 多租户架构
• 全面的错误处理和验证
• TypeScript首次开发
• MCP协议合规性

先决条件

• Node.js 16或更高版本
• npm或yarn包管理器
• PostgreSQL数据库（本地或云端）

安装

1. 安装依赖项：

npm install

1. 构建项目：

npm run build

用法

配置

此服务器旨在通过MCP客户端设置进行配置。环境变量通过MCP配置传递，而不是使用.env文件。

所需的环境变量：

• DATABASE_URL：您的PostgreSQL连接字符串
• BUSINESS_ID：默认业务ID（每次工具调用都可以覆盖）

备注：业务ID作为参数动态传递给每个工具调用，允许服务器在没有硬编码配置的情况下处理多个业务。

运行服务器

npm start

或用于开发：

npm run dev

MCP配置

要将此服务器与Claude Desktop或其他MCP客户端一起使用，请将以下配置添加到MCP设置中：

{
  "mcpServers": {
    "appointment-mcp": {
      "command": "node",
      "args": [
        "/path/to/appointment_mcp/build/index.js"
      ],
      "env": {
         "DATABASE_URL": "postgresql://username:password@localhost:5432/database",
         "BUSINESS_ID": "your-default-business-id"
       }
    }
  }
}

或者使用npx（推荐用于已发布的软件包）：

{
  "mcpServers": {
    "appointment-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "appointment-mcp-server@latest"
      ],
      "env": {
         "DATABASE_URL": "postgresql://username:password@localhost:5432/database",
         "BUSINESS_ID": "your-default-business-id"
       }
    }
  }
}

地方发展

对于本地开发，您可以直接运行服务器：

npm start

或者用于自动重建的开发：

npm run dev

注意：在本地运行进行开发时，您需要手动设置环境变量或使用.env文件。

可用工具

预约管理

1.创建_应用程序

为特定业务创建新的预约。

参数：

• business_id （string，可选）：企业的ID
• title （string，必填）：任命的标题
• date （字符串，必填）：YYYY-MM-DD格式的日期
• time （字符串，必填）：HH:MM格式的时间
• description （字符串，可选）：可选描述
• customer_id （字符串，可选）：客户ID
• service_id （字符串，可选）：服务ID
• staff_id （字符串，可选）：员工ID

2.列表_职位

列出特定业务的所有预约。

参数：

• business_id （string，可选）：企业的ID
• status （字符串，可选）：按状态筛选（已确认、待处理、已完成、已取消）
• date （字符串，可选）：按日期筛选（YYYY-MM-DD）

3.获取appointment

获取企业特定预约的详细信息。

参数：

• business_id （string，可选）：企业的ID
• id （string，必填）：约会的ID

4.取消预约

删除特定业务的预约。

参数：

• business_id （string，可选）：企业的ID
• id （string，必填）：要删除的约会的ID

员工管理

5.get_staff_availability

获取特定日期的员工可用性。

参数：

• business_id （string，可选）：企业的ID
• date （字符串，必填）：检查可用性的日期（YYYY-MM-DD格式）

退货： 工作人员的工作时间、可用性状态和休假信息。

6.get_all_staff_info

获取所有员工的详细信息。

参数：

• business_id （string，可选）：企业的ID

退货： 全面的员工信息，包括提供的服务、工作时间和预约次数。

7.get_staff_member

获取特定员工的详细信息。

参数：

• business_id （string，可选）：企业的ID
• staff_id （string，必填）：工作人员ID

退货： 详细的员工信息，包括服务、工作时间和预约历史。

8.获取关闭时间

在特定日期范围内让员工休假。

参数：

• business_id （string，可选）：企业的ID
• start_date （字符串，可选）：休假开始日期（YYYY-MM-DD格式）
• end_date （字符串，可选）：休假结束日期（YYYY-MM-DD格式）

可用性和预订

9.获取可用时间地块

获取某一日期特定服务的可用时段。

参数：

• business_id （string，可选）：企业的ID
• service_id （string，必填）：服务ID
• date （字符串，必填）：检查可用性的日期（YYYY-MM-DD格式）

退货： 提供员工信息和预订能力的可用时段。

客户管理

10.创建客户

创建新的客户资料。

参数：

• business_id （string，可选）：企业的ID
• first_name （string，必填）：客户的名字
• last_name （string，必填）：客户姓氏
• email （string，必填）：客户的电子邮件地址
• phone_number （字符串，可选）：客户的电话号码

11.获取客户

按ID获取客户详细信息。

参数：

• business_id （string，可选）：企业的ID
• customer_id （string，必填）：客户ID

12.搜索_客户

按姓名、电子邮件或电话搜索客户。

参数：

• business_id （string，可选）：企业的ID
• query （字符串，必填）：搜索查询

13.更新_客户

更新客户信息。

参数：

• business_id （string，可选）：企业的ID
• customer_id （string，必填）：客户ID
• first_name （字符串，可选）：更新了名字
• last_name （字符串，可选）：已更新姓氏
• email （字符串，可选）：已更新电子邮件
• phone_number （字符串，可选）：更新的电话号码

14.获取客户预约

获取特定客户的所有预约。

参数：

• business_id （string，可选）：企业的ID
• customer_id （string，必填）：客户ID

15.获取客户信息

获取客户提交的评论。

参数：

• business_id （string，可选）：企业的ID
• customer_id （string，必填）：客户ID

16.创建视图

为约会创建新的审核。

参数：

• business_id （string，可选）：企业的ID
• appointment_id （字符串，必填）：约会ID
• rating （数字，必填）：评级（1-5）
• comment （字符串，可选）：查看评论

业务运营

17.获取业务详情

通过业务ID获取特定业务的详细信息。

参数：

• business_id （string，必填）：用于检索详细信息的业务ID

18.获取业务_小时

获取营业时间。

参数：

• business_id （string，可选）：企业的ID

服务管理

19.获取服务

获取企业提供的所有服务。

参数：

• business_id （string，可选）：企业的ID

20.获取服务

获取特定服务的详细信息。

参数：

• business_id （string，可选）：企业的ID
• service_id （string，必填）：服务ID

数据库模式

服务器使用一个全面的PostgreSQL模式，其中包括：

• 企业：业务信息和配置
• 员工：工作人员简介和详细信息
• 客户：客户资料和联系信息
• 服务：有定价和期限的服务选项
• 预约：预约和日程安排
• 员工_工作_小时：工作人员可用时间表
• 员工_休假：员工休假和假期跟踪
• 员工服务：工作人员服务任务
• 评价：客户评价和评级

看 database_schema.sql 以获取完整的模式定义。

发展

项目结构

appointment_mcp/
├── src/
│   ├── index.ts          # Main server implementation and tool definitions
│   └── database.ts       # Database operations and queries
├── build/                # Compiled JavaScript output
├── database_schema.sql   # Complete database schema
├── customer_inquiry_prompt.md    # Customer service prompts
├── customer_inquiry_resources.md # Customer service resources
├── mcp-config-example.json       # Example MCP configuration
├── test-availability-tools.js    # Test script for new tools
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

建筑

npm run build

测试

运行测试脚本以验证新的可用性工具：

node test-availability-tools.js

重要提示

• 此服务器使用STDIO传输，因此避免使用 console.log() 因为它会破坏JSON-RPC消息
• 使用 console.error() 改为日志记录
• 所有数据都持久存储在PostgreSQL数据库中
• 日期格式必须为YYYY-MM-DD
• 时间格式必须为HH:MM（24小时格式）
• 必须通过MCP客户端设置配置环境变量
• 业务ID的范围可确保多租户安全

版本历史记录

v1.4.0（当前）

• ✨ 新增了5个可用性和员工管理工具
• ✨ 通过服务和工作时间增强员工信息检索
• ✨ 增加了预订可用性的时间段生成
• ✨ 通过评论和评级改进客户管理
• ✨ 增强的业务运营和服务管理
• 🔧 更新为使用直接PostgreSQL查询以获得更好的性能
• 📚 全面的文档和示例

v1.3.x

• 核心预约管理功能
• 基本客户和业务运营
• 多租户支持

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

支持

对于问题和疑问：

• GitHub问题：https://github.com/arimunandar/appointment-mcp-server/issues
• NPM包：https://www.npmjs.com/package/appointment-mcp-server