novada-scraper Skill + MCP

一个可扩展的 Novada Scraper MCP 项目。
当前 v1 已实现 TikTok 商品详情抓取。

功能概览

• MCP 工具：
  • set_api_key({ api_key })
  • get_tiktok_product({ url, region?, locale?, include_raw? })
• 单一标准化返回结构（便于后续分析）
• 本地持久化 API Key（默认 ~/.mcp/config.json）
• 可扩展 Adapter 架构（新增平台只需新增 adapter 并注册）

目录结构

novada-scraper/
├─ src/
│  ├─ index.ts
│  ├─ server.ts
│  ├─ tools/
│  ├─ services/
│  ├─ adapters/
│  ├─ config/
│  ├─ types/
│  └─ utils/
├─ tests/
├─ SKILL.md
├─ codex.config.example.toml
├─ package.json
└─ tsconfig.json

下载与安装(以codex为例)

1. 克隆仓库

cd  cd ~/.codex/skills
git clone https://github.com/NovadaLabs/novada-scraper-skill.git
cd novada-scraper-skill

2. 安装依赖

npm install

3. 构建项目

npm run build

在 Codex 中挂载 MCP

将下面配置加入 ~/.codex/config.toml（Windows 路径按实际修改）：

[mcp_servers.novada_scraper]
command = "node"
args = ["C:/Users/user/.codex/skills/novada-scraper/dist/index.js"]

[mcp_servers.novada_scraper.env]
SCRAPER_API = "https://scraperapi.novada.com"
SCRAPER_TIMEOUT_MS = "20000"

如何获取 API Key（官网）

可参考 Novada 官方文档：

• Scraper API 文档（：https://developer.novada.com/novada/advanced-proxy-solutions/scraper-api/tiktok-product-information-api

常见流程：

1. 登录 Novada Dashboard。
2. 在账号设置中或者联系客服获取通用 API 凭据。

Skill 使用示例（Codex 对话）

示例提问：

使用skill $novada-scraper，
爬取 tiktok 商品详情页：https://www.tiktok.com/shop/pdp/xxx/1729762527861968902

返回示例

成功示例（标准化）

{
  "platform": "tiktok",
  "entity_type": "product",
  "source_url": "https://www.tiktok.com/shop/pdp/xxx/1729762527861968902",
  "product_id": "1729762527861968902",
  "title": "Women's Solid High Waist Skinny Shorts...",
  "price": null,
  "currency": "USD",
  "sales": 31,
  "shop_name": "Elite Lane",
  "region": null,
  "scraped_at": "2026-04-21T06:18:46.316Z"
}

失败示例（Key 余额不足）

{
  "platform": "tiktok",
  "product_id": null,
  "title": null,
  "raw": {
    "code": 402,
    "msg": "Api Key error：Insufficient balance"
  }
}

常见问题

1. API_KEY_MISSING

• 未设置 key。先调用 set_api_key。

2. Api Key error: User has no permission

• key 无对应产品权限，需在 Novada 后台开通 Scraper API 权限。

3. Api Key error: Insufficient balance

• key 余额不足，充值或更换 key。

4. UPSTREAM_TIMEOUT

• 上游超时，可提高 SCRAPER_TIMEOUT_MS。

开发与测试

npm test

当前测试覆盖：

• API key 读写
• adapter 注册
• 参数校验与错误码
• 别名工具与通用工具一致性
• 上游接口成功/超时/5xx 场景

安全建议

• 不要把 API key 提交到 Git 仓库。
• 生产环境建议使用密钥管理系统，不要明文写入脚本。