serpapi-mcp

一个封装型技能，通过 mcporter CLI 调用 SerpAPI 的 MCP 服务器（Model Context Protocol）。

该技能提供的功能

• 通过 MCP（HTTP）从 OpenClaw 执行 SerpAPI 搜索。
• 将完整的 SerpAPI JSON 输出至 stdout（这是主要契约）。
• 可选地将每次查询及其响应持久化到 Airtable：
  • 原始 JSON（完整 SerpAPI 有效载荷）
  • 结构化“摘要”（前 10 条自然搜索结果、PAA/相关问题、视频、图片、数量统计、标志位）

/serp 命令用法

本技能提供 /serp 命令。

语法：

• /serp
• /serp [engine] [num] [mode]

默认参数：

• engine=google_light
• num=5
• mode=compact

说明：

• 如需 SERP 高级功能（例如 People also ask（PAA）、视频聚合区、知识图谱等），建议使用：
  • engine=google
  • mode=complete

示例：

• /serp site:cnmv.es "educación financiera"
• /serp "AAPL stock" google 3 compact
• /serp "mortgage pay off vs invest" google 10 complete

工作原理

主脚本（向 stdout 输出 JSON）：

• skills/serpapi-mcp/scripts/serp.sh "" [engine] [num] [mode]

调用的 MCP 工具端点：

• https://mcp.serpapi.com/$SERPAPI_API_KEY/mcp.search

可选 Airtable 日志记录器：

• skills/serpapi-mcp/scripts/airtable_log.mjs

依赖要求

1) MCP 客户端（mcporter）

本技能需要主机上已安装 mcporter。

安装方法：

• npm install -g mcporter

验证安装：

• mcporter --help

2) SerpAPI 密钥 + 故障转移支持

可配置单个密钥或故障转移密钥池：

• 单密钥模式：
  • SERPAPI_API_KEY
• 故障转移池（逗号分隔，按顺序尝试）：
  • SERPAPI_API_KEYS

推荐配置位置（以下任一方式均被支持）：

• 技能作用域内：
  • skills.entries.serpapi-mcp.env.SERPAPI_API_KEY
  • skills.entries.serpapi-mcp.env.SERPAPI_API_KEYS
• 全局作用域：
  • env.vars.SERPAPI_API_KEY
  • env.vars.SERPAPI_API_KEYS

故障转移行为：

• 当发生常见错误（如配额超限、认证失败、速率限制等，例如 HTTP 状态码 429/401/403，或返回 “quota exceeded”、“rate limit” 等提示）时，脚本将自动重试下一个密钥。
• 对于其他错误（如请求格式错误），脚本将立即终止并返回对应错误信息。

可选：将搜索与结果存储至 Airtable

启用 / 禁用日志记录

启用日志记录：

• SERP_LOG_AIRTABLE=1（或 true）

可在 Gateway 环境变量中全局设置（始终启用），也可在执行脚本时按次指定。

Airtable 配置（Gateway 环境变量）

请设置以下环境变量（切勿将密钥等敏感信息存入代码仓库或 workspace）：

• AIRTABLE_TOKEN（Airtable 个人访问令牌）
• AIRTABLE_BASE_ID
• AIRTABLE_TABLE（表名 或 表 ID）

写入行为与兼容性

• Airtable 不会 自动创建字段。
• 日志记录器具备 Schema 感知能力：
  • 通过 Airtable Metadata API 读取目标表 Schema。
  • 仅写入您表中已存在的字段（按字段名精确匹配）。
  • 尽可能将值强制转换为对应 Airtable 字段类型（复选框 / 数字 / 文本 / 单选 / 日期等）。

Airtable 表结构（推荐）

字段名称必须完全一致。

核心字段：

• Query → 单行文本
• Engine → 单行文本
• Num → 数字（整数）
• Mode → 单行文本
• CreatedAt → 日期/时间

来源追踪字段：

• SerpApiSearchId → 单行文本
• SerpApiJsonEndpoint → URL
• GoogleUrl → URL

原始有效载荷字段：

• ResultJson → 长文本
• ResultJsonTruncatedFlag → 复选框
  • （向后兼容：若您偏好该命名，日志记录器也支持 ResultJsonTruncated 字段）

结构化摘要字段：

• SummaryJson → 长文本
• SummaryJsonTruncated → 复选框
• OrganicTop10Json → 长文本
• RelatedQuestionsTop10Json → 长文本
• ShortVideosTop10Json → 长文本
• VideosTop10Json → 长文本
• ImagesTop10Json → 长文本

标志位与计数字段：

• HasAiOverview → 复选框
• HasAnswerBox → 复选框
• HasKnowledgeGraph → 复选框
• OrganicCount → 数字（整数）
• RelatedQuestionsCount → 数字（整数）
• ShortVideosCount → 数字（整数）
• VideosCount → 数字（整数）
• ImagesCount → 数字（整数）

Airtable 尺寸限制

Airtable 对单个单元格有大小限制。当日志记录器检测到超出限制时，将对 JSON 字符串进行截断：

• AIRTABLE_MAX_JSON_CHARS（默认值：90000）
• AIRTABLE_MAX_SUMMARY_CHARS（默认值：90000）

输出

返回 SerpAPI JSON。具体字段取决于所选引擎及 Google 实际返回内容，可能包含如下键：

• organic_results
• short_videos / videos_results
• images_results
• related_questions
• knowledge_graph
• answer_box / ai_overview
• 广告区块（top_ads、bottom_ads 等）