square-automation

通过 Rube MCP 自动化 Square

通过 Rube MCP 调用 Composio 的 Square 工具包，自动处理 Square 付款、订单管理和开票。

工具包文档：composio.dev/toolkits/square

前提条件

• 必须已连接 Rube MCP（可用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Square 连接，并使用工具包 square
• 始终先调用 RUBE_SEARCH_TOOLS，获取当前工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。无需 API 密钥——添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 有响应，以验证 Rube MCP 可用
2. 使用工具包 square 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请根据返回的授权链接完成 Square OAuth
4. 确认连接状态显示为 ACTIVE 后，再运行任何工作流

核心工作流

1. 列出并监控付款

适用场景：用户想查看付款历史或查询付款状态

工具调用顺序：

1. SQUARE_LIST_PAYMENTS - 获取付款记录，可使用可选筛选条件 [必需]
2. SQUARE_CANCEL_PAYMENT - 如有需要，取消待处理的付款 [可选]

关键参数：

• begin_time / end_time：用于筛选日期范围的 RFC 3339 时间戳
• sort_order：使用 'ASC' 或 'DESC' 按时间顺序排列
• cursor：上一条响应中的分页游标
• location_id：按特定地点筛选付款

注意事项：

• 时间戳必须采用 RFC 3339 格式（例如，'2024-01-01T00:00:00Z'）
• 大量结果需要分页；持续使用 cursor，直到没有游标为止
• 只能取消待处理的付款；已完成的付款需要退款
• SQUARE_CANCEL_PAYMENT 需要列表结果中的确切 payment_id

2. 搜索和管理订单

适用场景：用户想按条件查找订单或更新订单详情

工具调用顺序：

1. SQUARE_LIST_LOCATIONS - 获取用于筛选的地点 ID [前置条件]
2. SQUARE_SEARCH_ORDERS - 使用筛选条件搜索订单 [必需]
3. SQUARE_RETRIEVE_ORDER - 获取特定订单的完整详情 [可选]
4. SQUARE_UPDATE_ORDER - 修改订单状态或详情 [可选]

关键参数：

• location_ids：要搜索的地点 ID 数组（搜索时必需）
• query：包含日期范围、状态和履约类型的搜索筛选对象
• order_id：用于检索或更新操作的特定订单 ID
• cursor：搜索结果的分页游标

注意事项：

• SEARCH_ORDERS 需要 location_ids；请先通过 LIST_LOCATIONS 获取 ID
• 订单状态包括：OPEN、COMPLETED、CANCELED、DRAFT
• UPDATE_ORDER 需要当前的 version 字段，以防止冲突
• 搜索结果采用分页方式；持续使用 cursor，直到没有游标为止

3. 管理地点

适用场景：用户想查看营业地点或获取地点详情

工具调用顺序：

1. SQUARE_LIST_LOCATIONS - 列出所有营业地点 [必需]

关键参数：

• 没有必需参数；返回所有可访问的地点
• 响应包含 id、name、address、status、timezone

注意事项：

• 大多数其他 Square 操作（订单、付款）都需要地点 ID
• 首次获取地点 ID 后，请始终缓存，以避免重复调用
• 结果中可能仍会显示非活跃地点；请检查 status 字段

4. 发票管理

适用场景：用户想要列出、查看或取消发票

工具调用顺序：

1. SQUARE_LIST_LOCATIONS - 获取用于筛选的位置 ID【前置条件】
2. SQUARE_LIST_INVOICES - 列出某个位置的发票【必需】
3. SQUARE_GET_INVOICE - 获取发票详细信息【可选】
4. SQUARE_CANCEL_INVOICE - 取消已安排或未付款的发票【可选】

关键参数：

• location_id：列出发票时必需
• invoice_id：执行获取或取消操作时必需
• cursor：列表结果的分页游标
• limit：每页结果数量

注意事项：

• LIST_INVOICES 需要 location_id；请先通过 LIST_LOCATIONS 获取
• 只有状态为 SCHEDULED、UNPAID 或 PARTIALLY_PAID 的发票才能取消
• CANCEL_INVOICE 需要发票的 version，以防止竞态条件
• 已取消的发票无法撤销取消

常见模式

ID 解析

位置名称 -> 位置 ID：

1. Call SQUARE_LIST_LOCATIONS
2. Find location by name in response
3. Extract id field (e.g., 'L1234ABCD')

订单查询：

1. Call SQUARE_SEARCH_ORDERS with location_ids and query filters
2. Extract order_id from results
3. Use order_id for RETRIEVE_ORDER or UPDATE_ORDER

分页

• 检查响应中是否包含 cursor 字段
• 在下一次请求的 cursor 参数中传入游标值
• 持续请求，直到 cursor 不存在或为空
• 使用 limit 控制每页大小

日期范围筛选

• 使用 RFC 3339 格式：2024-01-01T00:00:00Z
• 对于付款：使用 begin_time 和 end_time 参数
• 对于订单：使用带有 date_time_filter 的查询筛选条件
• 所有时间戳均为 UTC

已知注意事项

ID 格式：

• 位置 ID 是字母数字字符串（例如，'L1234ABCD'）
• 付款 ID 和订单 ID 是较长的字母数字字符串
• 执行其他操作前，务必先将位置名称解析为 ID

版本控制：

• UPDATE_ORDER 和 CANCEL_INVOICE 需要当前的 version 字段
• 先获取资源，以取得其当前版本
• 版本不匹配时会返回 409 Conflict 错误

速率限制：

• Square API 对各个端点设有速率限制
• 批量操作时应实施退避机制
• 处理大型数据集时，分页请求之间应稍作延迟

响应解析：

• 响应中的数据可能嵌套在 data 键下
• 金额以货币的最小单位表示（USD 使用美分）
• 应采用防御式解析，并为可选字段提供回退处理

快速参考

任务	工具标识	关键参数
列出付款	SQUARE_LIST_PAYMENTS	begin_time, end_time, location_id, cursor
取消付款	SQUARE_CANCEL_PAYMENT	payment_id
搜索订单	SQUARE_SEARCH_ORDERS	location_ids, query, cursor
获取订单	SQUARE_RETRIEVE_ORDER	order_id
更新订单	SQUARE_UPDATE_ORDER	order_id, version
列出位置	SQUARE_LIST_LOCATIONS	（无）
列出发票	SQUARE_LIST_INVOICES	location_id, cursor
获取发票	SQUARE_GET_INVOICE	invoice_id
取消发票	SQUARE_CANCEL_INVOICE	invoice_id, version

---

由 Composio 提供支持