使用 Rube MCP 与 Composio 自动化 IQAir AirVisual 空气质量数据操作（awesome-claude-skills 实战指南）

• AI 技能
• AI 插件
• 人工智能
• 工作流自动化

本篇技术指南聚焦于 awesome-claude-skills 仓库中composio-skills/iqair-airvisual-automation这一预置 Claude Skill，讲解如何借助 Rube MCP（Composio 提供）以"先搜索工具、再建立连接、后执行操作"的标准流程，自动化 IQAir AirVisual 的空气质量数据查询与相关操作。读完本文，你将掌握 Rube MCP 的连接配置、RUBE_SEARCH_TOOLS/RUBE_MANAGE_CONNECTIONS/RUBE_MULTI_EXECUTE_TOOL三个核心工具的调用范式，以及批量操作、全量 Schema 获取等进阶用法，可以直接在自己的 Claude 工作流中落地可复现的空气质量自动化方案。

一、Skill 定位：在哪儿、解决什么问题

composio-skills/iqair-airvisual-automation/SKILL.md是 awesome-claude-skills 仓库 README.md 中"App Automation via Composio"分类下的一个预置工作流 Skill。该分类在仓库中为 78 个 SaaS 应用提供了基于 Rube MCP（Composio）的自动化 Skill，每个 Skill 都包含工具序列、参数指引、已知陷阱（known pitfalls）与快速参考表，且全部使用从 Composio API 实际发现（discover）出的真实工具 slug。

本 Skill 的核心目标非常聚焦：让 Claude（或其他兼容 Agent）能够通过标准 MCP 协议，真实调用 IQAir AirVisual 的工具，而不是停留在"帮你写一段调用代码"的层面。它不直接定义 IQAir 的 REST 端点，而是把 IQAir AirVisual 的能力封装为 Composio 平台上的iqair_airvisualtoolkit，再经由 Rube MCP 桥接给 Agent。

# 该 Skill 的前置声明（Frontmatter） name: iqair-airvisual-automation description: "Automate Iqair Airvisual tasks via Rube MCP (Composio). Always search tools first for current schemas." requires: mcp: [rube]

从结构上看，requires: mcp: [rube]明确表示该 Skill 强依赖 Rube 这个 MCP 服务器；而同目录下的 composio-automation/SKILL.md、openweather-api-automation/SKILL.md 等 78 个 Skill 遵循完全一致的模板，说明这套"搜索 → 连接 → 执行"的模式是仓库级的最佳实践，IQAir AirVisual 只是其中的一个具体实例。

二、前置条件（Prerequisites）

在使用该 Skill 之前，需要满足三个条件：

1. Rube MCP 已连接：环境中有可用的RUBE_SEARCH_TOOLS工具，这是所有流程的第一步；
2. IQAir AirVisual 连接已建立：通过RUBE_MANAGE_CONNECTIONS建立并保持iqair_airvisualtoolkit 的 ACTIVE 连接；
3. 永远先搜索工具：任何执行动作之前必须先调用RUBE_SEARCH_TOOLS获取当前的工具 Schema——工具 slug 和参数会随平台更新而变化，不能凭记忆硬编码。

三、环境搭建：接入 Rube MCP

接入 Rube MCP 的方式非常简单，官方说明指出：

Addhttps://rube.app/mcpas an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

即：无需申请 API Key，只需要在客户端配置中把https://rube.app/mcp添加为一个 MCP 服务器端点即可生效。这与仓库中 connect/SKILL.md 描述的 Composio 连接体系一脉相承：Composio 底层负责处理 OAuth 与工具路由，Rube 作为暴露给 Agent 的 MCP 网关。

接入后按以下 4 步完成连接验证：

1. 验证 Rube MCP 可用：确认RUBE_SEARCH_TOOLS能正常响应；
2. 发起连接：调用RUBE_MANAGE_CONNECTIONS，toolkit 参数传iqair_airvisual；
3. 完成鉴权：如果连接状态不是 ACTIVE，按返回的授权链接（auth link）完成 IQAir AirVisual 的授权设置；
4. 确认状态：在运行任何工作流之前，再次确认连接状态显示为 ACTIVE。

从仓库的 README.md（App Automation via Composio 一节）可以看到，这套"Rube MCP + Composio"体系统一覆盖了 CRM、项目管理、通信、邮箱、代码与 DevOps 等 78 个应用，IQAir AirVisual 的连接流程与其他应用完全一致，因此本节步骤可以平滑复用到任意 toolkit。

四、工具发现：为什么"永远先搜索"

该 Skill 反复强调的第一步是执行RUBE_SEARCH_TOOLS：

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

调用后会返回四类关键信息：

• 可用工具 slug（tool slugs）：当前 toolkit 暴露给 Agent 的工具标识符，例如查询空气质量、获取站点/城市数据等对应的实际 slug；
• 输入 Schema（input schemas）：每个工具的入参字段名、类型与必填项；
• 推荐的执行计划（recommended execution plans）：平台针对该 use case 给出的工具组合建议；
• 已知陷阱（known pitfalls）：该工具的常见踩坑点。

之所以"永远先搜索"，是因为工具 Schema 会变化。硬编码 slug 或参数，一旦平台更新就会导致调用失败或参数错位。这也是该 Skill 在 Frontmatter 描述中特意强调 "Always search tools first for current schemas" 的原因。

五、核心工作流：三步执行模式

整个自动化流程被归纳为一个清晰的三步模式，任何 IQAir AirVisual 任务都应当按此展开。

Step 1：发现可用工具

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

与初始发现不同，这里把use_case替换为你当前的具体任务描述（例如"查询北京当前空气质量指数"），并在session中复用已有会话 ID（id而非generate_id），从而让平台基于会话上下文给出更精准的工具建议。

Step 2：检查连接状态

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

在执行任何工具前，确认该 toolkit 在当前会话下处于 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"

这是实际发生副作用（调用 IQAir AirVisual API）的一步。有三个要点：

• tool_slug必须来自 Step 1 的搜索结果，不能自行拼写；
• arguments必须严格遵循搜索结果返回的 Schema——字段名和类型都要与 Schema 完全一致；
• memory参数必须始终携带，即使没有跨步骤状态需要传递，也要显式传空对象{}。

六、进阶用法：批量操作与全量 Schema

除三步主流程外，Skill 的快速参考还给出了两个进阶入口：

• RUBE_REMOTE_WORKBENCH：当需要批量、循环地处理数据（例如遍历多个城市的空气质量数据）时，可以进入远程工作台，通过run_composio_tool()以编程方式编排多次工具调用，避免逐条手工发起RUBE_MULTI_EXECUTE_TOOL；
• RUBE_GET_TOOL_SCHEMAS：当搜索结果只返回schemaRef（Schema 引用）而非内联 Schema 时，用该工具拉取工具的完整字段定义，确保参数构造的精确性。

这两个进阶工具与三步主流程配合，可以覆盖从单次查询到批量轮询的完整自动化场景。

七、已知陷阱清单（Known Pitfalls）

该 Skill 用独立小节汇总了最容易出错的六个点，逐一对应实践中的高频故障：

1. 永远先搜索：工具 Schema 会变化。绝不在不调用RUBE_SEARCH_TOOLS的情况下硬编码工具 slug 或参数；
2. 检查连接：执行工具前必须确认RUBE_MANAGE_CONNECTIONS返回 ACTIVE 状态，否则调用会因未授权而失败；
3. Schema 合规：严格使用搜索结果中的字段名与类型，多一个字段、少一个字段或类型不符都会导致执行失败；
4. Memory 参数：RUBE_MULTI_EXECUTE_TOOL调用中必须携带memory，即使内容为空也要传{}；
5. 会话复用：同一工作流内复用同一会话 ID，新工作流再生成新的会话 ID——这既保持上下文连续性，又避免会话无限膨胀；
6. 分页处理：检查响应中是否带有分页令牌（pagination tokens），有则持续翻页拉取，直到数据完整为止，防止只拿到第一页导致结果不完整。

这六条不仅是 IQAir AirVisual 的专属注意事项，从仓库中 78 个 composio-skills 的 SKILL.md（例如 composio-automation/SKILL.md 的 Known Pitfalls 一节）可以看到，它们是完全一致的通用约束，可以作为任何 Composio toolkit 自动化的安全检查清单。

八、快速参考表（Quick Reference）

九、落地示例：一个完整的空气质量查询工作流

综合以上所有要素，一个可复现的完整工作流如下：

1. RUBE_SEARCH_TOOLS queries: [{use_case: "查询北京当前 AQI 与 PM2.5 数据", known_fields: ""}] session: {generate_id: true} → 记下返回的 tool_slug、arguments 字段定义与分页信息 2. RUBE_MANAGE_CONNECTIONS toolkits: ["iqair_airvisual"] session_id: "上一步返回的 session_id" → 确认连接状态为 ACTIVE；若否则跟随授权链接完成鉴权 3. RUBE_MULTI_EXECUTE_TOOL tools: [{ tool_slug: "步骤 1 返回的 slug", arguments: { /* 严格按 Schema 填写的城市/坐标等参数 */ } }] memory: {} session_id: "同一个 session_id" → 获取空气质量数据；若响应含分页令牌，继续翻页直到取完

这一流程把前文"搜索 → 连接 → 执行 → 处理分页"全部串起来，且每一步都有明确的验证点（Session ID 复用、ACTIVE 状态确认、Schema 合规、memory 携带），可以作为后续扩展到其他城市的模板。

十、总结

composio-skills/iqair-airvisual-automation/SKILL.md的价值在于：它把"连接 IQAir AirVisual → 发现工具 → 鉴权 → 执行"这条链路固化成了可复用的 Skill 规范，并且以"Always search tools first"为最高原则，天然免疫工具 Schema 变更带来的兼容性问题。无论你是想给 Claude 增加空气质量查询能力，还是参考这套模式自动化其他 Composio toolkit（仓库中还有 77 个同构 Skill 可对照学习），本文所述的连接配置、三步工作流、陷阱清单与快速参考表都直接可用。

• AI 技能
• AI 插件
• 人工智能
• 工作流自动化