Segmetrics 自动化实战：通过 Rube MCP（Composio）在 Claude Skills 中编排 Segmetrics 工作流

本指南围绕仓库中 Segmetrics 自动化 Skill 展开，系统讲解如何借助 Rube MCP（Composio）以零硬编码、Schema 动态发现的方式自动化 Segmetrics 相关操作。读者读完将掌握「搜索工具 → 校验连接 → 执行调用」的标准三段式工作流，理解 RUBE_SEARCH_TOOLS、RUBE_MANAGE_CONNECTIONS、RUBE_MULTI_EXECUTE_TOOL 等核心 MCP 工具的正确用法，并规避工具 Schema 变更、会话复用等实战中的常见陷阱。

一、这个 Skill 是什么：Rube MCP 与 Segmetrics 的自动化桥梁

segmetrics-automation 是 awesome-claude-skills 仓库中「App Automation via Composio」系列预置 Skill 之一。据 README 说明，该仓库为 78 个 SaaS 应用提供了基于 Rube MCP（Composio） 的预构建工作流 Skill，每个 Skill 都包含工具序列、参数指引、已知陷阱与速查表，且全部使用从 Composio API 实际发现的工具 slug（tool slug）。

该 Skill 的元数据（YAML frontmatter）定义如下：

---
name: segmetrics-automation
description: "Automate Segmetrics tasks via Rube MCP (Composio). Always search tools first for current schemas."
requires:
  mcp: [rube]
---

三个字段的含义分别是：

• name：Skill 的唯一标识，即 segmetrics-automation；
• description：向 Claude 描述该 Skill 的能力边界与触发条件，注意其中"Always search tools first for current schemas"是本 Skill 最重要的行为准则——永远先搜索工具、获取当前 Schema；
• requires.mcp：声明运行前提，本 Skill 要求客户端已接入名为 rube 的 MCP 服务器。

核心设计理念：与常规"在 Skill 文档里写死工具名和参数"的做法不同，本 Skill 刻意不硬编码任何 Segmetrics 工具 slug，而是要求每次执行前先通过 RUBE_SEARCH_TOOLS 动态发现当前可用的工具及其输入 Schema。这样做的直接原因是工具 Schema 会随 Composio 平台迭代而变化，硬编码必然导致调用失败。

二、前置条件与 Setup：两分钟接入 Rube MCP

在运行任何 Segmetrics 工作流之前，需要满足以下前置条件：

1. Rube MCP 已连接：客户端中存在可用的 RUBE_SEARCH_TOOLS 工具，这是判断 MCP 连接是否成功的标志；
2. Segmetrics 连接已激活：通过 RUBE_MANAGE_CONNECTIONS 建立 segmetrics toolkit 的连接，且状态为 ACTIVE；
3. 始终先执行 RUBE_SEARCH_TOOLS：获取当前工具 Schema 是每轮工作流的第一步。

接入 Rube MCP

在客户端配置中添加 MCP 服务器时，只需填入端点 https://rube.app/mcp 即可。文档明确指出：

无需任何 API Key——只要把端点加进配置，它就能工作。

这是本 Skill 上手成本极低的关键：省去了注册、申请密钥、配置 OAuth 回调等一系列繁琐步骤。

建立 Segmetrics 连接的四步流程

1. 验证 MCP 可用：调用 RUBE_SEARCH_TOOLS，确认它能正常响应；
2. 发起连接：调用 RUBE_MANAGE_CONNECTIONS，传入 toolkit 为 segmetrics；
3. 完成授权：如果连接状态不是 ACTIVE，跟随返回的认证链接完成授权设置；
4. 确认状态：在运行任何工作流之前，确认连接状态已变为 ACTIVE。

ACTIVE 状态的确认是硬性门槛——在未激活连接的情况下执行工具，通常会直接得到认证错误，浪费一次完整的调用往返。

三、工具发现：为什么"先搜索，后执行"是铁律

工具发现（Tool Discovery）是整个自动化流程的第一环，调用形式如下：

RUBE_SEARCH_TOOLS
queries: [{use_case: "Segmetrics operations", known_fields: ""}]
session: {generate_id: true}

参数解析：

• queries.use_case：描述你的具体任务场景。首次发现时用宽泛的 "Segmetrics operations"，后续针对具体任务（如报表拉取、订阅数据查询）可以写成更精确的 "your specific Segmetrics task"；
• queries.known_fields：已知字段，首次探索可留空字符串；
• session.generate_id：置为 true 时由服务端生成新的会话 ID，适用于新工作流的起点。

一次成功的 RUBE_SEARCH_TOOLS 调用会返回四类关键信息：

1. 可用工具 slug（tool slug）：后续 RUBE_MULTI_EXECUTE_TOOL 调用中 tool_slug 字段的取值来源；
2. 输入 Schema：每个工具参数的字段名、类型与必填约束，是构造 arguments 的唯一权威依据；
3. 推荐执行计划：Composio 根据 use_case 给出的工具组合与调用顺序建议；
4. 已知陷阱（known pitfalls）：平台侧标注的常见调用错误与规避方式。

从仓库结构看，composio-automation 等兄弟 Skill 采用了完全相同的工具发现机制，这印证了"先搜索、后执行"是这套 Rube MCP 自动化体系通用的最佳实践，而非 Segmetrics 特有要求。

四、核心工作流：发现 → 校验连接 → 执行

文档给出了三段式标准工作流，每一步都有明确的调用模板，可直接复制到 Claude 会话中使用。

Step 1：发现可用工具

RUBE_SEARCH_TOOLS
queries: [{use_case: "your specific Segmetrics task"}]
session: {id: "existing_session_id"}

与首次发现不同，这一步要复用已有会话 ID（session.id），以保证整个工作流处于同一上下文；use_case 也应替换为你正在处理的具体任务描述，让返回的工具集更聚焦。

Step 2：检查连接状态

RUBE_MANAGE_CONNECTIONS
toolkits: ["segmetrics"]
session_id: "your_session_id"

传入 toolkit 数组（此处为 ["segmetrics"]）与当前会话 ID，确认返回的连接状态为 ACTIVE 后再继续。这个检查步骤成本极低，却能在执行前拦截掉绝大多数认证类错误。

Step 3：执行工具

RUBE_MULTI_EXECUTE_TOOL
tools: [{
  tool_slug: "TOOL_SLUG_FROM_SEARCH",
  arguments: {/* schema-compliant args from search results */}
}]
memory: {}
session_id: "your_session_id"

关键字段说明：

• tools 是一个数组，因此支持一次调用批量执行多个工具；每个元素包含 tool_slug 与 arguments；
• tool_slug 必须来自 Step 1 的搜索结果，严禁凭记忆硬编码；
• arguments 必须严格遵循 Step 1 返回的 Schema——字段名、类型、嵌套结构都不能自行发挥；
• memory 是必填参数，即使为空也要显式传入 {}；
• session_id 沿用当前工作流的会话 ID。

完整链路示意

从源码结构看，这三步形成了"动态发现 → 状态校验 → 按 Schema 执行"的闭环：搜索结果为执行提供工具与参数依据，连接检查为执行提供认证保障，执行则复用同一会话保持状态连续。若某个工具返回结果含分页标记，需继续拉取直至数据完整，这一点在下方陷阱部分还会展开。

五、已知陷阱清单：六条实战避坑要点

文档用专门章节总结了六条高频踩坑点，逐条拆解如下：

1. Always search first（永远先搜索）：工具 Schema 会变化，未经 RUBE_SEARCH_TOOLS 就硬编码工具 slug 或参数，是失败率最高的错误。这条被写进了 Skill 的 description 字段，属于必须内化的第一准则；
2. Check connection（检查连接）：执行工具前必须用 RUBE_MANAGE_CONNECTIONS 确认状态为 ACTIVE，否则认证错误会浪费整轮调用；
3. Schema compliance（Schema 合规）：参数必须使用搜索结果中的精确字段名与类型，注意大小写、可选与必填的差异；
4. Memory parameter（memory 参数）：RUBE_MULTI_EXECUTE_TOOL 调用中必须始终携带 memory 字段，哪怕没有状态也要传 {}，否则调用可能因缺少必填字段而被拒绝；
5. Session reuse（会话复用）：同一工作流内复用同一会话 ID，保持上下文与连接状态的连续性；开启新工作流时才生成新的会话 ID。混用会话是状态错乱的常见来源；
6. Pagination（分页处理）：检查响应中是否带有分页令牌，若有则持续翻页直到取回全部数据，避免因只读第一页而遗漏结果。

这六条本质上都在围绕同一个原则：把 Schema 与状态的权威来源交给运行时发现，而非静态文档。

六、快速参考表：五种操作一表掌握

操作	方案
查找工具	RUBE_SEARCH_TOOLS，携带 Segmetrics 专属 use case
建立连接	RUBE_MANAGE_CONNECTIONS，toolkit 为 segmetrics
执行工具	RUBE_MULTI_EXECUTE_TOOL，使用发现得到的工具 slug
批量操作	RUBE_REMOTE_WORKBENCH，配合 run_composio_tool()
获取完整 Schema	RUBE_GET_TOOL_SCHEMAS，针对带 schemaRef 的工具

这张表的实用价值在于覆盖了从单次调用到批量编排的全谱系：常规单步调用走 RUBE_MULTI_EXECUTE_TOOL；需要并行或批量执行时升级到 RUBE_REMOTE_WORKBENCH 并用 run_composio_tool() 包装；若搜索结果只给出 schemaRef 引用而未内联完整 Schema，则用 RUBE_GET_TOOL_SCHEMAS 拉取完整定义。

七、将 Skill 安装到 Claude Code 使用

本 Skill 遵循仓库统一的 Skill 结构规范（SKILL.md 携带 YAML frontmatter，见 README 的 Creating Skills 章节），可以直接安装到 Claude Code 的 Skills 目录中使用：

mkdir -p ~/.config/claude-code/skills/
cp -r composio-skills/segmetrics-automation ~/.config/claude-code/skills/

安装后可用以下命令验证元数据是否被正确识别：

head ~/.config/claude-code/skills/segmetrics-automation/SKILL.md

随后启动 Claude Code（claude），Skill 会自动加载，并在任务涉及 Segmetrics 自动化时被激活。激活后，Claude 将遵循本 Skill 中的指令：先调用 RUBE_SEARCH_TOOLS 做工具发现，再检查连接，最后按发现的 Schema 执行调用——整个过程无需人工干预。

八、总结

segmetrics-automation 不是一份"写死调用示例"的静态文档，而是一套强调运行时自发现的自动化执行规范。它的三层设计值得借鉴：

1. 发现层：RUBE_SEARCH_TOOLS 动态返回工具 slug、Schema 与执行建议，从源头消除版本漂移问题；
2. 连接层：RUBE_MANAGE_CONNECTIONS 保证每次执行前都有 ACTIVE 的 Segmetrics 连接兜底；
3. 执行层：RUBE_MULTI_EXECUTE_TOOL 以 Schema 合规的 arguments 完成调用，并以会话复用、memory 参数、分页处理保证长工作流的正确性。

这套"先搜索、后执行"的模式同样适用于仓库中其他 77 个 Composio 系列 Skill（如 composio-automation、composio-search-automation）。掌握 segmetrics-automation，就等于掌握了在 Claude Skills 生态中接入任意 Composio 支持应用的标准姿势。