基于 Rube MCP 与 Composio 的 Magnetic 自动化实战指南（awesome-claude-skills）

导读

本文围绕 awesome-claude-skills 仓库中 magnetic-automation 技能文档，系统讲解如何通过 Rube MCP（Composio）驱动 Magnetic 工具包，实现账号连接、工具发现、参数化执行与批量操作的完整自动化闭环。读完本文，你将掌握 RUBE_SEARCH_TOOLS、RUBE_MANAGE_CONNECTIONS、RUBE_MULTI_EXECUTE_TOOL 等核心 MCP 调用的标准用法、正确的工具发现顺序，以及避免踩坑的关键约束，可直接在 Claude 工作流中复刻这条「先搜索、再连接、后执行」的三步式实战模式。

技能文档定位：一条贯穿所有 Composio 技能的通用模板

本仓库的 composio-skills/ 目录收录了面向 78 个 SaaS 应用预构建的工作流技能，README.md 明确说明这些技能全部基于 Rube MCP（Composio） 构建，每个技能都包含工具调用序列、参数指引、已知陷阱与快速参考表，且工具 slug 均来自 Composio API 的真实返回。magnetic-automation 正是其中针对 Magnetic 工具包的实例，与 composio-automation、composio-search-automation 等技能共享同一套文档骨架与调用协议——因此本文总结的流程、参数约定与规避策略，对仓库内其他任何 *-automation 技能同样适用，区别仅在于 toolkit 名称与 use_case 描述。

该技能的 requires 字段声明了硬性依赖：mcp: [rube]，即只有挂载了 Rube MCP 服务器，技能中涉及的 RUBE_* 工具才会存在，这是整个自动化链路的前提。

前置条件：先满足这三项，再谈自动化

开始执行任何 Magnetic 工作流之前，文档要求确认三个前置条件：

1. Rube MCP 已连接：环境中必须存在 RUBE_SEARCH_TOOLS 工具可用，它是整个技能体系的入口。
2. Magnetic 连接处于 ACTIVE 状态：通过 RUBE_MANAGE_CONNECTIONS 并指定 toolkit 为 magnetic 建立的活动连接，是调用具体工具前必须满足的授权前提。
3. 每次执行前先调用 RUBE_SEARCH_TOOLS：这是本技能最重要的行为准则——工具 schema 随时可能变化，不能凭记忆或历史记录硬编码任何工具 slug 与参数。

环境设置：接入 Rube MCP 的四个步骤

Rube MCP 的接入方式非常轻量，无需任何 API Key：

在客户端配置中添加 https://rube.app/mcp 作为 MCP 服务器端点，添加后即可直接使用，无需额外密钥。

随后按文档给出的顺序完成连接初始化：

1. 验证 Rube MCP 已就绪：确认 RUBE_SEARCH_TOOLS 能正常响应；
2. 调用 RUBE_MANAGE_CONNECTIONS，toolkits 参数传入 magnetic；
3. 若返回的连接状态不是 ACTIVE，按返回的授权链接完成 Magnetic 账号的 OAuth 设置；
4. 在运行任何工作流之前，再次确认连接状态显示为 ACTIVE。

从仓库内其他技能文档（如 composio-automation）可以看出，这套「验证 MCP → 建立 toolkit 连接 → 处理授权链接 → 确认 ACTIVE」的流程是全部 78 个技能共享的标准初始化协议，RUBE_MANAGE_CONNECTIONS 承担了连接生命周期管理（创建、检查、续期）的职责。

工具发现：永远先于执行的 RUBE_SEARCH_TOOLS

技能文档反复强调「Always discover available tools before executing workflows」（执行工作流之前，务必先发现可用工具）。推荐的做法是用通用查询做首次探测：

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

该调用会返回四类关键信息，作为后续所有步骤的输入：

• 可用工具 slug（tool slugs）：执行阶段的 tool_slug 必须取自这里，而不是硬编码；
• 输入 schema（input schemas）：每个工具参数的确切字段名与类型；
• 推荐执行计划（recommended execution plans）：针对当前 use_case 的建议调用顺序；
• 已知陷阱（known pitfalls）：该工具集常见的错误用法提示。

注意此处 session: {generate_id: true} 表示这是一个新工作流的起点，需要系统生成全新的会话 ID；而工作流内部后续调用则复用该 ID（见下文）。

核心工作流模式：搜索 → 连接 → 执行 三步闭环

Step 1：发现可用工具

针对具体任务发起定向搜索，复用已生成的会话 ID：

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

与初始探测不同，这里把 use_case 换成你的具体业务描述（例如创建线索、同步联系人、更新记录等），让 Rube 返回与该任务最匹配的工具及其精确参数 schema。session 使用 id 形式，保持工作流上下文连续。

Step 2：检查连接状态

在执行任何工具前，确认授权连接仍然有效：

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

这一步成本极低但价值很高：一旦连接过期或未激活，后续工具调用必然失败；提前检查可以避免在批量执行中途才发现授权失效。

Step 3：执行工具

使用搜索阶段返回的 slug 与 schema 发起执行：

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

三个字段的约束各有讲究：

• tool_slug 必须来自 RUBE_SEARCH_TOOLS 的返回结果，杜绝硬编码；
• arguments 必须严格遵循搜索结果中的 schema——字段名、类型、必填项一个都不能偏差；
• memory 必须始终携带，即使当前没有需要传递的状态，也要显式传入空对象 {}。

RUBE_MULTI_EXECUTE_TOOL 支持在 tools 数组中一次提交多个工具调用，因此多步骤业务（如「先查客户 → 再更新记录」）可以在单次请求内按序执行，这正是批量化、自动化 Magnetic 运营任务的执行入口。

已知陷阱：六条必须遵守的纪律

文档用专门章节总结了实践中最高频的六类错误，逐条对照可显著提升首次成功率：

陷阱	正确做法
工具 schema 变化	每次执行前都调用 RUBE_SEARCH_TOOLS，绝不硬编码工具 slug 或参数
连接状态未确认	执行工具前先通过 RUBE_MANAGE_CONNECTIONS 确认状态为 ACTIVE
参数不符合 schema	严格使用搜索结果返回的精确字段名与类型
遗漏 memory 参数	每次 RUBE_MULTI_EXECUTE_TOOL 调用都必须携带 memory，即便为空 {}
会话 ID 使用不当	同一工作流内复用会话 ID；新工作流生成新 ID
忽略分页	检查响应中的分页 token，持续拉取直至数据完整

最后一条尤其容易被忽略：列表类接口往往分页返回，若不跟踪分页 token，会得到「看似成功实则缺失数据」的结果。

快速参考表：五种操作的入口速查

Operation	Approach
Find tools	RUBE_SEARCH_TOOLS with Magnetic-specific use case
Connect	RUBE_MANAGE_CONNECTIONS with toolkit magnetic
Execute	RUBE_MULTI_EXECUTE_TOOL with discovered tool slugs
Bulk ops	RUBE_REMOTE_WORKBENCH with run_composio_tool()
Full schema	RUBE_GET_TOOL_SCHEMAS for tools with schemaRef

其中两点值得展开：

• 批量操作走 RUBE_REMOTE_WORKBENCH，在远端工作台中通过 run_composio_tool() 调用工具，适合大规模、长耗时的数据处理场景，与 RUBE_MULTI_EXECUTE_TOOL 的本地执行形成互补；
• 完整 schema：当搜索返回的工具带有 schemaRef 引用标识时，用 RUBE_GET_TOOL_SCHEMAS 拉取该工具的完整字段定义，适合需要对参数做精细化定制（如嵌套对象、枚举取值）的场景。

仓库上下文：模板复用与扩展方式

从仓库结构看，composio-skills/ 下每个 *-automation/ 目录仅含一个 SKILL.md，构成「一应用一技能」的扁平组织。magnetic-automation 的技能头部 description 字段写明了它的能力边界——「Automate Magnetic tasks via Rube MCP (Composio). Always search tools first for current schemas」，这与 README 所述「每个技能都使用 Composio API 返回的真实工具 slug」相互印证。

对于想扩展新工具集的读者，最可靠的方式不是照抄本模板，而是遵循其内核方法论：先用 RUBE_SEARCH_TOOLS 以目标 use_case 探测真实可用的工具与 schema，再据此生成技能文档与执行计划——schema 永远以运行时返回为准，这正是本技能（以及整个 78 技能集合）能在工具频繁演化的 SaaS 生态中保持可用的根本原因。