ggcheckout-mcp

# GG Checkout MCP 服务器 > 完整的模型上下文协议服务器，通过 AI 代理管理 GG Checkout 平台 — 18 个领域中的 142 个工具。 ## 概述 GG Checkout MCP 服务器使 AI 代理（Claude Code、Cursor、Claude Desktop）能够通过自然语言管理整个 GG Checkout 平台：产品、结账、支付、会员区、漏斗、WhatsApp、账单等。 ## 先决条件 - Node.js >= 18.0.0 - 具有有效 API 密钥的 GG Checkout 账户 ## 安装 ### NPX（推荐） ```bash npx ggcheckout-mcp ``` ### 全局安装 ```bash npm install -g ggcheckout-mcp ``` ## 获取 API 密钥 1. 访问 [ggcheckout.com](https://www.ggcheckout.com/) 2. 进入 **设置** → **MCP / API 密钥** 3. 生成您的 API 密钥（格式：`ggck_live_...`） 4. **重要：** 立即复制并保存您的 API 密钥 — 它不会再次显示！ ## 配置 ### Claude Code ```json { "mcpServers": { "ggcheckout": { "command": "npx", "args": ["-y", "ggcheckout-mcp"], "env": { "GGCHECKOUT_API_KEY": "ggck_live_your_key_here" } } } } ``` ### Claude Desktop **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` 与上述格式相同。 ### Cursor / 其他客户端 ```bash export GGCHECKOUT_API_KEY="ggck_live_your_key_here" ``` ### 自定义 API URL ```bash export GGCHECKOUT_API_URL="https://your-staging.example.com" ``` --- ## 可用工具（142 个） ### 产品（16 个工具） #### `list_products` 列出所有您的产品/交付。 **示例提示：** "显示我所有产品" #### `get_product` 获取特定产品的详细信息。 **参数：** `productId`（字符串） **示例提示：** "获取产品 abc123 的详细信息" #### `create_product` 创建新的产品/交付。 **参数：** - `title`（字符串）：产品标题 - `description`（字符串）：产品描述 - `price`（数字|字符串）：价格（例如 19.90）或巴西格式（"19,90"） - `discount`（数字）：折扣百分比（使用 0 表示无折扣） - `url`（字符串）：产品交付 URL **示例提示：** - "创建一个名为 'React Course' 的产品，价格为 R$99.00，交付 URL 为 https://example.com/course" - "添加新产品：'Node.js Guide'，R$49.90，无折扣，URL 为 https://example.com/node" #### `update_product` 更新现有产品。仅提供要更改的字段。 **参数：** `productId` + `create_product` 中的任意字段（所有字段均为可选） **示例提示：** "更新产品 abc123 的价格为 R$79.90" #### `delete_product` **示例提示：** "删除产品 abc123" #### `upload_deliverable` 将交付文件上传到产品。 **参数：** `productId`、`fileUrl`、`fileName`、`fileType`（可选） **示例提示：** "将 https://files.example.com/ebook.pdf 中的电子书上传到产品 abc123" #### `list_upsells` / `create_upsell` / `delete_upsell` / `reorder_upsells` 管理产品的追加销售。 **示例提示：** - "显示产品 abc123 的追加销售" - "为产品 abc123 创建追加销售，提供产品 xyz789，价格为 R$29.90" - "重新排序产品 abc123 的追加销售" #### `list_downsells` / `create_downsell` / `delete_downsell` / `reorder_downsells` 管理产品的降价销售。 **示例提示：** "为产品 abc123 添加降价销售，标题为 50% 折扣" #### `manage_tags` 在产品上设置标签。标签有名称和十六进制颜色。 **示例提示：** "为产品 abc123 添加 'VIP' 标签，颜色为紫色，和 'Featured' 标签，颜色为绿色" --- ### 结账（6 个工具） #### `list_checkouts` **示例提示：** "显示我所有结账页面" #### `get_checkout` **示例提示：** "获取结账页面 abc123 的详细信息" > **注意：** 使用 `uid`（Firestore 文档 ID），而不是自定义 `id` slug。 #### `create_checkout` **必填：** `title`、`id`（slug）、`price`、`paymentMethods`、`checkout`（配置） **示例提示：** "为我的 React Course 创建一个结账页面，价格为 R$99.90" #### `update_checkout` 自动与当前数据合并 — 仅提供要更改的字段。 **示例提示：** "更新结账页面 abc123 的价格为 R$79.90 并取消发布" #### `delete_checkout` **示例提示：** "删除结账页面 abc123" #### `manage_checkout_tags` 标签名称和十六进制颜色（每个结账页面最多 5 个）。 **示例提示：** "为结账页面 abc123 添加 'promo' 标签，颜色为 #FF5733" --- ### 支付（7 个工具） #### `get_my_business_id` **示例提示：** "我的商户 ID 是什么？" **技巧：** 在后续提示中使用它： "获取我的商户 ID，然后显示我所有支付记录" #### `list_payments` / `get_payments_paginated` / `get_payment` **示例提示：** - "显示我商户的所有支付记录" - "获取本月前 20 条已支付的支付记录" - "搜索邮箱为 john@example.com 的支付记录" - "我有多少未结支付记录？" #### `get_payment_fulfillment` / `update_payment_fulfillment` 管理实物订单的履约。 **示例提示：** - "显示支付记录 xyz789 的履约状态" - "将支付记录 xyz789 标记为已发货，跟踪代码为 BR123456789" #### `check_payment_status` **示例提示：** "检查支付网关状态，支付记录为 xyz789" --- ### Webhooks（6 个工具） **示例提示：** - "显示我所有 Webhooks" - "为支付.paid 事件在 https://myapp.com/webhook 创建 Webhook" - "更新 Webhook abc123 以监听 payment.refunded 事件" - "删除 Webhook abc123" - "向 Webhook abc123 发送测试 payment.paid 事件" - "使用覆盖的 payment ID 测试 Webhook abc123，事件为 refunded" #### Webhook 事件负载 所有事件共享相同的顶级结构。关键字段： | 字段 | 类型 | 备注 | |---|---|---| | `event` | 字符串 | 事件类型（见下文） | | `payment.id` | 字符串 | 支付标识符 | | `payment.status` | 字符串 | `pending`、`paid`、`refunded`、`expired`、`chargeback` | | `payment.method` | 字符串 | `pix`、`pix.paid`、`card`、`card.paid` | | `payment.amount` | 数字 | 金额（单位：分）（例如 `9900` = R$99.00） | | `payment.customer.name` | 字符串 | 买家姓名 | | `payment.customer.email` | 字符串 | 买家邮箱 | | `payment.customer.document` | 字符串 | CPF | | `payment.customer.phone` | 字符串 | 电话（E.164，例如 `5511999999999`） | | `payment.createdAt` | 字符串 | ISO 8601 | | `payment.paidAt` | 字符串\|undefined | 仅在 `payment.paid`、`payment.refunded`、`payment.chargeback` 中存在 | | `payment.refundedAt` | 字符串\|undefined | 仅在 `payment.refunded` 中存在 | | `payment.expiredAt` | 字符串\|undefined | 仅在 `payment.expired` 中存在 | | `product.id` | 字符串 | 产品标识符 | | `product.title` | 字符串 | 产品名称 | **支持的事件：** ```json { "event": "payment.created", "payment": { "status": "pending", "method": "pix" }, ... } { "event": "payment.paid", "payment": { "status": "paid", "method": "pix.paid", "paidAt": "..." }, ... } { "event": "payment.refunded", "payment": { "status": "refunded", "method": "pix.paid", "paidAt": "...", "refundedAt": "..." }, ... } { "event": "payment.expired", "payment": { "status": "expired", "method": "pix", "expiredAt": "..." }, ... } { "event": "payment.chargeback", "payment": { "status": "chargeback", "method": "card.paid", "paidAt": "..." }, ... } ``` **签名验证**（当设置 `secret` 时）： ``` X-Webhook-Signature: sha256=<HMAC-SHA256(secret, raw_body)> X-GGCheckout-Event: payment.paid ``` ```ts import { createHmac } from 'crypto'; const sig = createHmac('sha256', secret).update(rawBody).digest('hex'); const isValid = sig === incomingHeader.replace('sha256=', ''); ``` --- ### 商店（9 个工具） **示例提示：** - "显示我的商店配置" - "列出商店中的所有产品" - "获取商店 xyz 中产品 abc123 的详细信息" - "显示商店中的类别" - "列出商店的客户评论及评分统计" --- ### 漏斗 / 测试（9 个工具） **示例提示：** - "列出我所有漏斗" - "显示漏斗 abc123 的详细信息" - "创建一个名为 'Lead Capture' 的新漏斗" - "复制漏斗 abc123" - "显示漏斗 abc123 中完成所有步骤的潜在客户" - "漏斗 abc123 的转化率是多少？" - "显示漏斗 abc123 中每个步骤的流失分析" --- ### 会员区（21 个工具） **示例提示：** - "列出我所有会员区" - "为产品 abc123 创建一个名为 'React Academy' 的会员区" - "在会员区 xyz 中添加一个名为 'Getting Started' 的模块" - "在会员区 abc 中创建一个名为 'Introduction' 的视频课程" - "重新排序会员区 xyz 中的模块" - "列出会员区 xyz 中的所有学生" - "将客户 john@example.com 添加到会员区 xyz" - "导入 50 名学生到会员区 xyz" - "阻止学生 abc123" --- ### 折扣 / 优惠券（6 个工具） **示例提示：** - "显示我所有折扣" - "为所有产品创建 15% 折扣优惠券，名称为 SAVE15" - "为产品 abc123 创建购买 2 件商品赠 1 件商品的折扣" - "停用折扣 abc123" - "验证优惠券 SAVE15 是否适用于订单金额为 R$100 的订单" --- ### WhatsApp（15 个工具） **示例提示：** - "列出我的 WhatsApp 会话" - "为会话 abc123 创建一个新的 WhatsApp 会话，电话号码为 5511999999999" - "列出所有消息模板" - "为 'paid' 事件创建模板：'Hi {nome}, thanks for purchasing {produto}!'" - "禁用模板 abc123" - "检查支付记录 xyz789 的 WhatsApp 交付状态" - "重新发送支付记录 xyz789 的 WhatsApp 交付" --- ### 账单（10 个工具） **示例提示：** - "我的当前账单余额是多少？" - "我的账单状态是什么？" - "显示我的发票" - "通过 PIX 支付发票 abc123" - "添加 R$100 到账单积分" - "我有存档的卡吗？" - "删除存档的卡" --- ### 运费 / MelhorEnvio（7 个工具） **示例提示：** - "计算运费到 CEP 01001-000，结账 abc123" - "检查支付记录 xyz789 的运费状态" - "生成支付记录 xyz789 的运费标签" - "获取运费订单 abc123 的打印 URL" --- ### 网关令牌（3 个工具） **示例提示：** - "列出我的支付网关令牌" - "添加 Stripe 令牌" - "删除令牌 abc123" 支持 26+ 个网关：pushinpay、mercadopago、stripe、efibank、amplopay、infinitepay、abacatepay 等。 --- ### Discord（7 个工具） **示例提示：** - "列出我的 Discord 连接" - "显示服务器 123456 中的频道" - "显示服务器 123456 中的角色" - "在服务器 123456 中创建一个私有的销售通知频道" - "更新我的 Discord 连接以使用葡萄牙语" --- ### 仪表盘（3 个工具） **示例提示：** - "显示我今天的销售统计数据" - "显示本月的收入图表" - "刷新我的仪表盘缓存" --- ### 自定义域名（5 个工具） **示例提示：** - "列出我的自定义域名" - "添加域名 checkout.mysite.com" - "验证域名 abc123 的 DNS" - "删除域名 abc123" --- ### 奖励 / 目标（3 个工具） **示例提示：** - "我的销售里程碑进度是多少？" - "重新计算我的奖励进度" - "兑换 10K 奖励手镯" --- ### 配置文件 / 身份验证（6 个工具） **示例提示：** - "显示我的配置文件" - "将我的姓名更新为 'John Doe'" - "列出我的支持邮箱" - "添加 support@mystore.com 作为支持邮箱" - "我的 KYC 状态是什么？" --- ### 推送通知（3 个工具） **示例提示：** - "列出我的注册推送设备" - "删除设备 abc123" --- ## 价格格式 价格接受两种格式： 1. **雷亚尔（推荐）：** `19.90` = R$19.90 → 存储为 `1990` 分 2. **巴西格式：** `"19,90"` 或 `"1.990,00"` 所有价格内部存储为分。 --- ## 安全最佳实践 🔒 **请勿公开分享您的 API 密钥** ✅ 始终使用环境变量 ✅ 立即撤销已泄露的密钥 ✅ 定期生成新密钥 ❌ 不要在代码中硬编码密钥 ❌ 不要将密钥提交到版本控制 --- ## 速率限制 | 限制 | 值 | |-------|-------| | 每小时 | 1,000 请求 | | 每分钟 | 30 请求 | 速率限制在执行任何操作之前强制执行 — 被阻止的请求永远不会到达数据库或业务逻辑。 当请求速率受限时，API 返回 HTTP 429，并带有 `Retry-After` 头部和结构化的 JSON 正文： **头部：``` Retry-After: 23 ``` **正文：** ```json { "error": "rate_limit_exceeded", "limit_type": "apikey_strict", "limit": 30, "window": "1m", "retry_after": 23 } ``` | `limit_type` | 限制 | 窗口 | 建议 | |---|---|---|---| | `apikey_strict` | 30 | 1m | 等待 `retry_after` 秒，然后继续 | | `apikey` | 1,000 | 1h | 迁移太大，请分批跨小时进行 | | `product_upload_strict` | 15 | 1m | 减慢文件上传速度 | | `product_upload` | 35 | 1h | 每小时最多 35 个文件上传 | 始终使用正文中的 `retry_after` 值（或 `Retry-After` 头部）而不是猜测。 ### 大批量操作和迁移 如果您需要连续创建或更新许多资源（例如导入产品、克隆结账），请遵循以下指南以避免达到限制： - **间隔请求至少 2 秒** 以保持安全低于 30 req/min 限制 - **将持续吞吐量限制在 ~900 req/hour** 以留出低于 1,000/hour 的上限空间 - **收到 429 响应时** 立即停止，读取 `Retry-After` 头部，等待该秒数，然后继续 - 不要在不等待的情况下重试 - **永远不要循环而延迟** - 紧凑的循环将在不到 30 秒内耗尽每分钟配额并触发完整的分钟阻塞 **推荐的大批量作业调度：``` for each item: call tool() if response is 429: wait Retry-After seconds retry once else: wait 2 seconds before next call ``` --- ## 本地开发 ```bash git clone https://github.com/gui-drumond/ggcheckout-mcp.git cd ggcheckout-mcp npm install ``` ### .env ```bash GGCHECKOUT_API_KEY=ggck_live_your_key_here GGCHECKOUT_API_URL=http://localhost:3000 # optional, defaults to https://ggcheckout.app ``` ### 命令 ```bash npm run dev # 开发环境热重载 npm run build # TypeScript 构建 npm start # 运行编译后的构建 npm test # 单元测试（173 个测试） npm run test (e2e) # E2E 测试（需要 .env） ``` ### MCP Inspector（交互式 UI） ```bash GGCHECKOUT_API_KEY=ggck_live_... npx @modelcontextprotocol/inspector -- npx tsx src/index.ts ``` 打开浏览器 UI 以交互方式测试任何工具。 --- ## 故障排除 ### 错误：401 未授权 - 检查您的 API 密钥是否正确 - 确保密钥以 `ggck_live_` 开头 - 验证密钥是否未在仪表盘中撤销 ### 错误：403 禁止 - 您试图访问不属于您的资源 - API 密钥的作用域仅限于创建它们的用户名 ### 错误：404 未找到 - 资源 ID 不存在 - 对于结账，请使用 `uid`（Firestore 文档 ID），而不是自定义 `id` slug ### 错误：429 请求过多 - 速率限制已超过（30 req/min 或 1,000 req/hour） - 读取 `Retry-After` 响应头部 — 它会准确告诉您需要等待多少秒 - 对于批量操作，请间隔至少 2 秒以避免一开始就达到限制 - 参见 [速率限制](#rate-limits) 部分了解批量操作指南 ### 错误：无效的价格格式 - 使用雷亚尔作为数字（`19.90`）或巴西格式作为字符串（`"19,90"`） - 不要混合格式 --- ## 支持 - 📧 邮箱：support@ggcheckout.com - 📖 文档：https://docs.ggcheckout.com - 🐛 问题：https://github.com/gui-drumond/ggcheckout-mcp/issues ## 许可 MIT © GG Checkout Team