Clover MCP (模型上下文协议) 服务器

一个最小化的 MCP 服务器，用于使用 OAuth 认证与 Clover API 交互。

概述

此 MCP 服务器允许生成式 AI 模型和其他客户端使用模型上下文协议访问您的 Clover 商户数据。 通过此集成，模型可以：

• 检索商户信息
• 列出库存商品
• 列出订单
• 访问单个商品和订单

快速开始

与 Claude AI 一起使用 (推荐)

1. 将以下内容添加到您的 Claude MCP 设置中（通常在 ~/.config/anthropic/claude.mcp.json 中）：

{
  "mcpServers": {
    "clover": {
      "command": "npx",
      "args": ["-y", "@ibraheem4/clover-mcp"],
      "env": {
        "CLOVER_CLIENT_ID": "your-clover-client-id",
        "CLOVER_CLIENT_SECRET": "your-clover-client-secret",
        "CLOVER_BASE_URL": "https://apisandbox.dev.clover.com"
      },
      "disabled": false,
      "autoApprove": ["initiate_oauth_flow", "get_merchant_info", "list_inventory", "list_orders"]
    }
  }
}

2. 与 Claude 一起使用：

/mcp use clover

3. 在与 Claude 的对话中启动 OAuth 流程：

你能帮我连接到我的 Clover 帐户吗？

通过命令行使用

您可以直接运行 MCP 服务器：

# 一条命令安装并运行
npx @ibraheem4/clover-mcp

# 使用凭据
CLOVER_CLIENT_ID=your-client-id CLOVER_CLIENT_SECRET=your-client-secret npx @ibraheem4/clover-mcp

Clover OAuth 设置

在使用此 MCP 服务器之前，您需要设置一个 Clover 应用程序：

1. 在 developer.clover.com 创建一个 Clover 开发者帐户
2. 在 Clover 开发者仪表板中注册一个新应用程序
3. 使用以下信息配置您的应用程序：
   • 站点 URL：http://localhost:4000/oauth-callback
   • 默认 OAuth 响应：Code
4. 记下您的客户端 ID 和客户端密钥
5. 将这些凭据添加到您的环境或 .env 文件中

MCP 工具

以下工具可通过 MCP 协议使用：

• get_oauth_status: 检查 OAuth 凭据是否可用
• initiate_oauth_flow: 启动 OAuth 流程以获取访问令牌
• get_merchant_info: 获取有关商户的信息
• list_inventory: 列出库存商品，带有可选过滤器
• list_orders: 列出订单，带有可选过滤器

与 Claude 的示例用法

以下是一些在连接后可以与 Claude 一起使用的示例提示：

1. 连接到 Clover:

   我想连接到我的 Clover 帐户。
   

2. 获取商户信息:

   你有什么关于我的 Clover 商户帐户的信息？
   

3. 列出库存商品:

   显示我的库存中的前 10 个商品。
   

4. 列出订单:

   你能列出我最近的订单吗？
   

开发

本地安装

1. 克隆此存储库
2. 安装依赖项：

   npm install
   

3. 设置您的 OAuth 凭据：

   cp .env.example .env
   # 使用您的 Clover OAuth 凭据编辑 .env
   

4. 构建 TypeScript 代码：

   npm run build
   

5. 启动 MCP 服务器：

   ./run.sh
   

发布更新

要将新版本发布到 npm：

# 更新 package.json 中的版本
npm version patch  # 或 minor, 或 major

# 构建并发布
npm run build
npm publish

故障排除

如果您遇到 OAuth 问题：

1. 验证您的 Clover 应用程序是否已正确注册
2. 检查您的应用程序设置中的站点 URL 是否设置为 http://localhost:4000/oauth-callback
3. 确保您的客户端 ID 和客户端密钥正确
4. 确保开发者仪表板中的“默认 OAuth 响应”设置为“Code”
5. 尝试使用 initiate_oauth_flow 再次启动 OAuth 流程

许可证

MIT