Clover POS协议服务器

Clover MCP服务器

Clover POS平台的综合模型上下文协议（MCP）服务器，提供18个类别的118个工具和18个交互式React应用程序，用于管理Clover商家帐户的各个方面。

概述

Clover MCP服务器使AI助手能够通过标准化的界面与Clover POS系统进行交互。它提供了对订单、库存、客户、员工、付款、报告等的完整访问，所有这些都是通过MCP工具和丰富的基于网络的UI实现的。

特性

• 118 MCP工具 涵盖18个功能类别
• 18个React应用程序 用于可视化管理和报告
• 完整的CRUD操作 适用于所有主要Clover实体
• 实时数据 通过Clover REST API v3
• 环境支持 适用于沙盒和生产环境
• TypeScript 用于类型安全和开发人员体验
• MCP资源 用于提供交互式React应用程序

安装

npm install @mcpengine/clover-server

或者从源代码安装：

git clone <repo-url>
cd servers/clover
npm install
npm run build

配置

设置以下环境变量：

# Required
export CLOVER_MERCHANT_ID="your-merchant-id"

# One of these is required
export CLOVER_API_KEY="your-api-key"
# OR
export CLOVER_ACCESS_TOKEN="your-oauth-token"

# Optional (defaults to sandbox)
export CLOVER_ENVIRONMENT="sandbox"  # or "production"

获取Clover证书

1. 商户编号：在您的Clover仪表板的“帐户和设置”下找到
2. API密钥：从Clover开发人员仪表板为您的应用程序生成
3. 访问令牌：通过Clover的OAuth流获得的OAuth令牌
4. 环境：使用 sandbox 为了测试， production 实时数据

用法

作为MCP服务器

添加到您的MCP客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "clover": {
      "command": "clover-mcp",
      "env": {
        "CLOVER_MERCHANT_ID": "your-merchant-id",
        "CLOVER_API_KEY": "your-api-key",
        "CLOVER_ENVIRONMENT": "sandbox"
      }
    }
  }
}

程序化使用

import { CloverServer } from '@mcpengine/clover-server';

const server = new CloverServer({
  merchantId: 'your-merchant-id',
  apiKey: 'your-api-key',
  environment: 'sandbox'
});

await server.run();

MCP工具（共118个）

应用工具（4）

• clover_get_app -获取特定应用程序的详细信息
• clover_get_app_metered_events -获取应用程序的计量事件
• clover_list_app_notifications -列出应用程序通知
• clover_list_apps -列出所有已安装的应用程序

现金工具（2）

• clover_get_cash_drawer -获取现金抽屉状态和详细信息
• clover_list_cash_events -列出现金抽屉事件（打开、存款等）

分类工具（8）

• clover_add_item_to_category -将项目添加到类别
• clover_create_category -创建新类别
• clover_delete_category -删除类别
• clover_get_category -获取类别详细信息
• clover_list_categories -列出所有类别
• clover_list_category_items -列出类别中的项目
• clover_remove_item_from_category -从类别中删除项目
• clover_update_category -更新类别详细信息

客户工具（9）

• clover_add_customer_address -为客户添加地址
• clover_create_customer -创建新客户
• clover_delete_customer -删除客户
• clover_get_customer -获取客户详细信息
• clover_list_customer_addresses -列出客户地址
• clover_list_customer_cards -列出客户支付卡
• clover_list_customers -列出所有客户
• clover_search_customers -按各种条件搜索客户
• clover_update_customer -更新客户信息

设备工具（6）

• clover_get_device -按ID获取设备详细信息
• clover_get_device_by_serial -按序列号获取设备
• clover_list_device_payments -列出设备处理的付款
• clover_list_devices -列出所有商家设备
• clover_open_cash_drawer -远程打开设备的现金抽屉
• clover_print_receipt -在设备上打印收据

折扣工具（5）

• clover_create_discount -创建新折扣
• clover_delete_discount -删除折扣
• clover_get_discount -获取折扣详情
• clover_list_discounts -列出所有折扣
• clover_update_discount -更新折扣设置

员工工具（10）

• clover_clock_in_employee -员工时钟
• clover_clock_out_employee -给员工打卡
• clover_create_employee -创建新员工
• clover_create_shift -创建新班次
• clover_delete_employee -删除员工
• clover_get_employee -获取员工详细信息
• clover_list_employee_roles -列出员工角色
• clover_list_employee_shifts -列出员工的班次
• clover_list_employees -列出所有员工
• clover_update_employee -更新员工信息

库存工具（11）

• clover_create_category -创建库存类别
• clover_create_item -创建新的库存项目
• clover_create_modifier -为项目创建修改器
• clover_delete_item -删除库存项目
• clover_get_item -获取商品详细信息
• clover_list_categories -列出库存类别
• clover_list_item_stocks -列出物品的库存水平
• clover_list_items -列出所有库存物品
• clover_list_modifier_groups -列出修改器组
• clover_update_item -更新项目详细信息
• clover_update_item_stock -更新物料库存水平

行项目工具（7）

• clover_add_line_item_discount -为行项目添加折扣
• clover_add_line_item_modification -向行项目添加修改
• clover_exchange_line_item -交换行项目
• clover_get_line_item -获取行项目详细信息
• clover_remove_line_item_discount -删除行项目折扣
• clover_remove_line_item_modification -删除行项目修改
• clover_update_line_item -更新行项目详细信息

商家工具（5）

• clover_get_device -获取商户设备信息
• clover_get_merchant -获取商家账户详细信息
• clover_list_devices -列出所有商家设备
• clover_list_tender_types -列出已接受的投标类型
• clover_update_merchant -更新商家设置

修改工具（10）

• clover_create_modifier -创建新修改器
• clover_create_modifier_group -创建修改器组
• clover_delete_modifier -删除修改器
• clover_delete_modifier_group -删除修改器组
• clover_get_modifier -获取修改器详细信息
• clover_get_modifier_group -获取修改器组详细信息
• clover_list_modifier_groups -列出所有修改器组
• clover_list_modifiers -列出组中的修饰符
• clover_update_modifier -更新修改器
• clover_update_modifier_group -更新修改器组

订购工具（10）

• clover_add_line_item -在订单中添加行项目
• clover_add_order_discount -为订单添加折扣
• clover_create_order -创建新订单
• clover_delete_order -删除订单
• clover_fire_order -向厨房发出命令
• clover_get_order -获取订单详细信息
• clover_list_order_payments -列出订单的付款
• clover_list_orders -列出所有订单
• clover_remove_line_item -从订单中删除行项目
• clover_update_order -更新订单详细信息

支付工具（4）

• clover_create_refund -创建付款退款
• clover_get_payment -获取付款详细信息
• clover_list_payments -列出所有付款
• clover_list_refunds -列出所有退款

退款工具（5）

• clover_create_refund -创建退款
• clover_get_refund -获取退款详细信息
• clover_list_order_refunds -列出订单退款
• clover_list_payment_refunds -列出付款退款
• clover_list_refunds -列出所有退款

报告工具（4）

• clover_employee_performance -获取员工绩效报告
• clover_revenue_by_category -按类别获取收入明细
• clover_revenue_by_item -按项目获取收入明细
• clover_sales_summary -获取整体销售摘要

换档工具（8）

• clover_clock_out -时钟超时
• clover_create_shift -创建新班次
• clover_delete_shift -删除班次
• clover_get_active_shifts -获取所有活动班次
• clover_get_shift -获取班次详细信息
• clover_list_employee_shifts -列出员工的班次
• clover_list_shifts -列出所有班次
• clover_update_shift -更新班次详细信息

税务工具（5）

• clover_create_tax_rate -创建新的税率
• clover_delete_tax_rate -删除税率
• clover_get_tax_rate -获取税率详细信息
• clover_list_tax_rates -列出所有税率
• clover_update_tax_rate -更新税率设置

提示工具（5）

• clover_add_cash_tip_to_shift -为轮班添加现金小费
• clover_get_employee_tips -为员工获取建议
• clover_get_payment_tip -获得付款提示
• clover_get_shift_tips -获取轮班的所有提示
• clover_update_payment_tip -更新付款提示

React应用程序（共18个）

所有React应用程序均可作为MCP资源访问 clover://app/<app-name>.

库存和目录管理

1. 库存仪表板 （141行）

   • 所有库存物品及其库存水平概述
   • 快速搜索和过滤
   • 低库存警报和指标

2. 库存明细 （131行）

   • 单个项目的详细视图
   • 价格、成本和利润跟踪
   • 修饰语和类别关联

3. 品类经理 （88行）

   • 创建和组织项目类别
   • 拖放类别管理
   • 项目分类

客户管理

4. 客户网格 （148行）

   • 浏览数据网格中的所有客户
   • 按姓名、电子邮件或电话搜索
   • 快速访问客户详细信息

5. 客户详细信息 （153行）

   • 完整的客户资料视图
   • 购买历史和终身价值
   • 联系方式和地址
   • 已保存的付款方式

订单管理

6. 订单仪表板 （159行）

   • 实时订单监控
   • 订单状态跟踪（待处理、已支付、已退款）
   • 快速筛选今天、周、月

7. 订单详细信息 （181行）

   • 订单明细
   • 带修饰符的行项目
   • 付款和退款历史
   • 客户信息

8. 订单网格 （150行）

   • 可搜索的订单历史记录
   • 多列排序和过滤
   • 导出功能

员工管理

9. 员工仪表板 （184行）

   • 员工名册和角色
   • 时钟输入/输出状态
   • 权限管理
   • 性能指标

10. 员工日程表 （100行）

    • 排班界面
    • 周/月日历视图
    • 冲突检测
    • 休假请求

财务与报告

11. 销售仪表板 （120行）

    • 整体销售业绩
    • 收入趋势和图表
    • 热门项目和类别
    • 付款方式明细

12. 按类别划分的收入 （105行）

    • 类别级收入分析
    • 饼图和趋势图
    • 比较期

13. 按项目划分的收入 （96行）

    • 项目级收入跟踪
    • 最佳和最差表现者
    • 利润分析

14. 付款历史记录 （102行）

    • 完整的支付交易日志
    • 按日期、金额、类型筛选
    • 退款跟踪

折扣和定价

15. 折扣经理 （120行）

    • 创建和编辑折扣
    • 百分比或固定金额
    • 自动应用规则
    • 活动/非活动状态

16. 税务经理 （108行）

    • 配置税率
    • 应用于类别或项目
    • 默认税务设置

设备和操作

17. 设备管理器 （64行）

    • 列出所有Clover设备
    • 设备状态和健康状况
    • 远程现金抽屉控制
    • 打印测试收据

18. 现金抽屉 （116行）

    • 现金抽屉事件日志
    • 开盘/收盘计数
    • 存款跟踪
    • 现金管理报告

API覆盖范围

此服务器包含以下Clover API端点：

• 订单API -完整的CRUD、行项目、折扣、付款
• 库存API -项目、类别、修饰符、库存管理
• 客户API -个人资料、地址、卡片、搜索
• 员工API -管理、角色、轮班、时间跟踪
• 支付API -交易、退款、小费
• 招商局API -设置、设备、招标类型
• 报告API -销售、收入、绩效分析
• 设备API -硬件控制、打印、现金抽屉

建筑

clover/
├── src/
│   ├── clients/
│   │   └── clover.ts           # Clover API client with auth and pagination
│   ├── tools/                  # 18 tool modules (118 tools total)
│   │   ├── apps-tools.ts
│   │   ├── cash-tools.ts
│   │   ├── categories-tools.ts
│   │   ├── customers-tools.ts
│   │   ├── devices-tools.ts
│   │   ├── discounts-tools.ts
│   │   ├── employees-tools.ts
│   │   ├── inventory-tools.ts
│   │   ├── line-items-tools.ts
│   │   ├── merchants-tools.ts
│   │   ├── modifiers-tools.ts
│   │   ├── orders-tools.ts
│   │   ├── payments-tools.ts
│   │   ├── refunds-tools.ts
│   │   ├── reports-tools.ts
│   │   ├── shifts-tools.ts
│   │   ├── taxes-tools.ts
│   │   └── tips-tools.ts
│   ├── ui/
│   │   └── react-app/          # 18 React applications
│   │       ├── cash-drawer.tsx
│   │       ├── category-manager.tsx
│   │       ├── customer-detail.tsx
│   │       ├── customer-grid.tsx
│   │       ├── device-manager.tsx
│   │       ├── discount-manager.tsx
│   │       ├── employee-dashboard.tsx
│   │       ├── employee-schedule.tsx
│   │       ├── inventory-dashboard.tsx
│   │       ├── inventory-detail.tsx
│   │       ├── order-dashboard.tsx
│   │       ├── order-detail.tsx
│   │       ├── order-grid.tsx
│   │       ├── payment-history.tsx
│   │       ├── revenue-by-category.tsx
│   │       ├── revenue-by-item.tsx
│   │       ├── sales-dashboard.tsx
│   │       └── tax-manager.tsx
│   ├── types/
│   │   └── index.ts            # TypeScript type definitions
│   ├── server.ts               # MCP server implementation
│   └── main.ts                 # CLI entry point
├── scripts/
│   └── copy-assets.js          # Build script for React apps
├── package.json
├── tsconfig.json
└── README.md

发展

构建

npm run build

编译TypeScript并将React应用资产复制到 dist/.

观看模式

npm run dev

在监视模式下运行TypeScript编译器进行开发。

类型检查

npx tsc --noEmit

验证所有TypeScript代码是否编译正确。

错误处理

服务器包括全面的错误处理：

• 身份验证错误 -清除丢失或无效凭据的消息
• API错误 -Clover API错误通过完整上下文传播
• 验证错误 -API调用前的输入验证
• 网络错误 -重试逻辑和超时处理

所有错误均以MCP错误格式返回，并附有描述性消息。

安全

• API密钥和令牌仅从环境变量中读取
• 响应中没有记录或公开凭据
• 适用于所有Clover API通信的TLS/HTTPS
• 遵循Clover的OAuth最佳实践

测试

使用Clover的沙盒环境进行测试：

export CLOVER_ENVIRONMENT="sandbox"
export CLOVER_MERCHANT_ID="<sandbox-merchant-id>"
export CLOVER_API_KEY="<sandbox-api-key>"

沙盒环境提供：

• 隔离测试数据
• 所有操作的安全测试
• 对生产数据无影响
• API的实际反应

局限性

• 需要具有API访问权限的Clover商家帐户
• 适用基于Clover API等级的费率限制
• 某些操作需要特定权限
• 当前不支持Webhook订阅

贡献

欢迎投稿！拜托：

1. 遵循现有的代码结构
2. 为新工具添加测试
3. 用新功能更新此README
4. 确保TypeScript编译时没有错误

许可证

麻省理工学院

支持

对于问题或疑问：

• GitHub问题： 报告错误
• Clover文档：https://docs.clover.com/
• MCP规范：https://modelcontextprotocol.io/

相关项目

• MCP引擎 -构建MCP服务器的框架
• Clover SDK -Clover官方开发工具
• MCP客户端 -Claude Desktop、Continue和其他

版本历史记录

1.0.0（当前）

• 初始版本
• 18个类别的118个MCP工具
• 18个React应用程序
• 完全支持TypeScript
• 沙盒和生产环境
• 全面的错误处理

内置于❤️ MCP和三叶草社区