seo-api

通过 https://api.seranking.com/mcp 使用实时的 SE Ranking MCP。工具架构会实时探测；此技能从不依赖冻结的 API 接口快照。

SE Ranking API 集成架构师

帮助开发者基于 SE Ranking SEO Data API 和 Project API 构建真正可用的集成。交付内容可以是代码示例（可直接粘贴使用的 cURL / Python / TypeScript / MCP 工具调用序列）、实时配置 Project API 状态（创建项目、添加关键词、配置审计、设置 AIRT 提示词），也可以两者兼有。此技能了解完整的 195 个工具接口、每次调用的积分与速率限制成本，以及所有主流 MCP 客户端的标准配置方法。

前提条件

• 已连接 SE Ranking MCP，地址为 https://api.seranking.com/mcp。单个 API 密钥通过统一网关对 DATA_* 和 PROJECT_* 工具进行身份验证。如果 /mcp 中没有显示 se-ranking，此技能会输出安装命令并停止——请参阅 references/auth-and-keys.md。
• （可选）WebFetch，用于在请求需要 JSON Schema 以外的文字说明时，获取 seranking.com/api/data/* 和 seranking.com/api/project/* 上的详细指南。
• 用户需提供：用通俗语言描述的集成目标（例如“为客户 X 构建排名跟踪器”“每周将这 50 个域名的所有反向链接拉取到 BigQuery”“为新项目配置审计和 AIRT 提示词”）。只有在目标不明确时，此技能才会询问用户。

流程

1. 预检。

   • 确认 SE Ranking MCP 可访问。如果不可访问，输出：

     claude mcp add --transport http se-ranking https://api.seranking.com/mcp
     

     然后停止。有关 OAuth 与 X-Api-Key 标头的权衡，以及无头 / CI 使用模式，请参阅 references/auth-and-keys.md。
   • 调用 DATA_getSubscription（0 积分）。记录 units_left、套餐状态和到期时间——units_left 是预测成本时使用的数值，会在第 5 步的成本预测中列出。也可以调用 DATA_getCreditBalance，查看 { limit, used } 数据——但两者并非同义接口：它们报告的剩余积分数不同，无法相互核对（相差约 860 万很正常），因此应以 getSubscription.units_left 为准。

2. 明确目标。 仅当目标不明确时，提出 1–3 个问题。用户已明确说明时则跳过。可参考以下追问：

   • “这是一次性运行、定期任务（每天 / 每周），还是要长期集成到你的产品中？”
   • “目标国家 / 语言 / 设备是什么——还是面向全球？”
   • “我们要操作的是你在 SE Ranking 中已有的项目，还是仅仅研究域名？”

3. 确定 API 接口范围。 将目标映射到以下一项或两项：

   • Data API——针对任意域名获取研究类数据，无需预先设置账户。按积分计费。请参阅 references/api-surface-map.md §“Data API surfaces”。
   • Project API——操作用户自己的 SE Ranking 项目（排名跟踪、审计、AIRT、反向链接分组、营销计划、子账户）。按订阅限额计费，不按积分计费。需要 Business 或 Enterprise 套餐。请参阅 references/api-surface-map.md §“Project API surfaces”。
   • 许多实际集成会同时涉及两者——例如，排名跟踪器的设置会使用 PROJECT_createProject + PROJECT_addKeywords + PROJECT_runPositionCheck，然后通过 DATA_getDomainKeywords 获取同一域名的数据并生成报告。

4. 映射到工具 / 端点。 对集成中的每个步骤，列出：

   • MCP 工具：`DATA_getDomainKeywords` 或 `PROJECT_addKeywords`。
   • 底层 REST 端点 + HTTP 方法（例如，GET /v1/domain/keywords）。
   • 积分消耗量（Data API）或占用的限额（Project API）。从 references/rate-limits-and-credits.md 和 seranking.com/api/data/* 中的各端点页面获取消耗量——MCP 工具的 description 字段包含输入架构和使用说明，但不包含积分消耗量。
   • 如果工具需要用户未提供的 ID（项目 ID、搜索引擎 ID、地理区域名称、语言代码），则在它之前插入相应的 *list* 或 *available* 调用。参见 references/api-surface-map.md 中的“ID resolution”一节。

5. 预测成本。 汇总所有 Data API 调用的积分消耗量。对于 Project API 调用，说明对套餐限额的影响（例如，“这会占用套餐中的 1 个 Site + 50 个 Keywords + 约 500 个 Audit Pages”）。与以下内容进行比较：

   • 第 1 步中的 units_left——如果积分不足，说明这一点并停止，同时提供升级链接。
   • 如果涉及 Project API 工具，则检查套餐限额——PROJECT_getUserProfile 会返回当前用量；如果集成会导致超出限额，请标明。

6. 选择执行模式。 明确征求用户确认：

   • 代码模式——生成可直接粘贴使用的 cURL、Python（requests）、TypeScript（fetch）和 MCP 工具调用版本。由开发者运行。只读研究、用户希望自行维护的定期任务，以及任何用户希望部署在 Claude 会话之外的内容，默认使用此模式。
   • 实时模式——通过 MCP 逐步执行集成。每次变更调用都需确认。对于一次性的 Project API 设置（新建项目、添加关键词、配置审核、设置 AIRT 提示词组等），如果用户希望在本次对话结束时完成状态变更，则默认使用此模式。
   • 混合模式——实时完成一次性设置，并为定期任务生成代码（例如，“我已为你创建项目并添加了 50 个关键词；这是用于提取排名并写入 BigQuery 的每日运行 Python 脚本”）。

7. 执行或生成。

   • 代码模式——编写 code/curl.sh、code/python.py、code/typescript.ts、code/mcp-calls.md。每个文件都必须是完整、可运行的示例，不能只是片段。加入对 429（速率限制）和 403（积分不足）的错误处理。参见 references/integration-patterns.md 中的标准模式代码片段。
   • 实时模式——对于每次变更调用（PROJECT_create*、PROJECT_add*、PROJECT_delete*、PROJECT_update*、DATA_createStandardAudit、DATA_createAdvancedAudit 等），打印一行确认信息：

     About to call PROJECT_createProject(domain="acme.com", name="ACME Inc — Rank Tracker", country="us").
     Consumes: 1 "Site" from your subscription. Proceed? [y/N]
     

     等待用户明确回复 y / yes。若收到其他回复，则切换到代码模式，生成等效代码，而不是执行调用。只读调用（DATA_get*、DATA_list*、PROJECT_get*、PROJECT_list*）无需确认即可执行。将每次调用记录到 evidence/03-execution-log.md，包括时间戳、参数和响应状态。

8. 编写 RECIPE.md。 无论采用哪种模式，都必须编写。该交付文档供开发者了解已构建的内容或如何构建。请参阅下方的输出格式。

输出格式

文件夹 seo-api-{slug}-{YYYYMMDD}/，其中 {slug} 是对目标的 kebab-case 摘要（例如，acme-rank-tracker、bulk-backlinks-bigquery）。

seo-api-{slug}-{YYYYMMDD}/
├── RECIPE.md                       (primary deliverable — what was built or how to build it)
├── code/
│   ├── curl.sh                     (cURL one-liners + multi-step bash)
│   ├── python.py                   (idiomatic requests-based script)
│   ├── typescript.ts               (fetch + zod-validated responses)
│   └── mcp-calls.md                (MCP-tool-call sequence — same workflow, agent-native)
└── evidence/
    ├── 01-preflight.md             (credit balance, subscription status, MCP connectivity check)
    ├── 02-cost-forecast.md         (per-call cost breakdown, plan-limit deltas, total)
    ├── 03-ids-resolved.md          (Project API / search-engine IDs, geo codes resolved upfront — omit if none needed)
    └── 04-execution-log.md         (every MCP call executed, with args + status — omit in pure code mode where nothing ran)

顶层内容：RECIPE.md + code/。evidence/ 文件夹保留推理过程；审计人员会重点查看 02-cost-forecast.md 和执行日志。03 和 04 为可选内容——如果运行期间无需查询 ID，也没有执行任何调用（纯代码模式建议），则仅提供 01 + 02。

RECIPE.md 的结构如下：

# {Integration Title}: {target}

> Run dated {YYYY-MM-DD} · Mode: {code | live | hybrid} · Total cost: {n} credits + {plan-limits consumed}

## Goal

{1–2 sentences. What was asked, what's being shipped.}

## API surface map

| Step | MCP tool | REST endpoint | Verb | Cost |
|------|----------|---------------|------|------|
| 1    | `DATA_getCreditBalance` | `/v1/account/subscription` | GET | 0 credits |
| 2    | `PROJECT_listProjects` | `/v1/account/projects` | GET | 0 (plan limit: read) |
| 3    | `PROJECT_createProject` | `/v1/projects` | POST | 1 Site from plan |
| ...  | ... | ... | ... | ... |

## Auth & setup

{cURL header / Python session / TypeScript fetch wrapper showing exactly how to authenticate. Reference `references/auth-and-keys.md` for OAuth vs. header tradeoffs.}

## Cost forecast

- Credit cost (Data API): {n} credits ({explanation per call})
- Plan-limit consumption (Project API): {Sites: n, Keywords: n, Audit Pages: n, AIRT Prompts: n}
- Your balance at run time: {units_left} credits, {plan limits available}
- {OK / WARNING: this integration would push X over plan limit}

## Recipe

### Option A — cURL

(complete bash script in `code/curl.sh`)

### Option B — Python

(complete script in `code/python.py`)

### Option C — TypeScript

(complete script in `code/typescript.ts`)

### Option D — MCP tool calls

(agent-native sequence in `code/mcp-calls.md` — for when this integration lives inside another Claude/Cursor/Codex workflow)

## Rate limit & retry strategy

- Data API: 10 RPS, Project API: 5 RPS. Pace sequentially for batched workflows; small-batch parallelism (≤3 concurrent) is safe.
- 429 handling: exponential backoff with jitter (1s → 2s → 4s → 8s, ±20% jitter). 5xx: same. Treat 403 "Insufficient funds" as terminal — no retry.

## What's running now (live mode only)

{Bullet list of MCP calls that were executed, with their outcomes. Pulled from `evidence/04-execution-log.md`.}

## What you still need to do

{Concrete next steps for the developer. E.g., "Run `python.py` daily via cron at 06:00 UTC", "Open the project at https://online.seranking.com/...", "Add a webhook for rank changes via Settings → Notifications".}

## Linked docs

- {Direct links to the relevant pages on `seranking.com/api/data/*` and `seranking.com/api/project/*`.}

## When to escalate to another skill

- `seo-content-brief` — once your integration is pulling keyword data, this skill turns it into editor briefs.
- `seo-technical-audit` — if the integration involves website audits, this skill interprets the audit output.
- `seo-drift baseline` — if the integration's job is to track a domain over time, snapshot it first.

提示

• 一个 API 密钥即可完成所有身份验证。 API_TOKEN（无头模式下使用 X-Api-Key 标头）同时适用于 DATA_* 和 PROJECT_*。旧版的 Data 和 Project 分开使用不同密钥的方式已废弃——出于向后兼容考虑，同时传递两个密钥作为标头仍然有效，但现在只需使用 X-Api-Key。请参阅 references/auth-and-keys.md。
• 速率限制按 API 密钥计算，而非按 IP 计算。 所有使用同一密钥的线程、工作进程和服务共用同一个 10 RPS（Data）或 5 RPS（Project）额度。对于生产环境中的扇出请求，请通过 API Dashboard 创建多个密钥。
• 失败的请求不收费。 4xx 和 5xx 响应不会消耗额度。无需为常规错误重试过度设计成本保护机制。
• Project API 限制不等于额度。 它们会消耗订阅中的 “Sites”、“Keywords”、“Audit Pages”、“AIRT Prompts” 配额。对于任何会修改数据的调用，都应提前说明对套餐限制的影响——这些限制比额度更难处理，因为用户必须升级套餐才能解除，而不仅仅是购买额度包。
• 修改数据前先确认。 PROJECT_create*、PROJECT_add*、PROJECT_delete*、PROJECT_update*、DATA_create*Audit、DATA_deleteAudit 都会永久修改账户状态。调用前务必打印一行摘要（工具、参数、将消耗的内容），并等待用户输入 y/yes。
• 使用正确的 ID 解析工具。 大多数“我想操作项目 X / 关键词 Y”的请求都需要先查询 ID。完整列表请参阅 references/api-surface-map.md §“ID 解析”。常见情况：
  • 项目 ID → PROJECT_listProjects（子账户设置可使用 PROJECT_listOwnedProjects / PROJECT_listSharedProjects）。
  • 用于排名跟踪的搜索引擎 → 直接向 PROJECT_addSearchEngine 传递 country_code（ISO 3166-1 alpha-2）。只有在使用区域性搜索引擎时（加泰罗尼亚、塞浦路斯土族区）才回退到 PROJECT_getAvailableSearchEngines。
  • SERP 位置 → DATA_getSerpLocations。
  • 语言 → PROJECT_getGoogleLanguages。
  • 本地排名跟踪的地区 → PROJECT_getAvailableRegions（使用原样的 name 字段；缩写会被拒绝）。
• 导出时，请轮询状态端点。 异步端点（/backlinks/export、/keywords/export）会返回任务 ID；后续轮询 *ExportStatus 会计入速率限制，但不消耗额度。先以 5 秒为轮询间隔；如果任务较大，则使用指数退避。
• 通过 WebFetching 文档前，先查看 MCP 工具说明。 每个 MCP 工具都会通过协议公开完整的输入架构、默认值和使用说明——例如，DATA_getDomainCompetitors 会说明自身约 60KB 的响应上限。工具说明不会包含的一项信息是额度成本；有关额度成本，请查阅 references/rate-limits-and-credits.md 和公开的各端点页面。
• 大型列表端点可能导致 MCP 传输溢出。 对热门域名调用 DATA_getDomainCompetitors，以及对大型域名调用 DATA_getDomainKeywords / DATA_getAllBacklinks 时，响应可能超过 MCP 客户端的内联令牌限制；此时结果会自动保存到文件。可以在保存的文件上使用 jq 切片来取回数据，或直接调用 REST 端点（原始 REST 没有大小限制）。请参阅 references/api-surface-map.md。
• 对于“展示 MCP 的 Swagger / OpenAPI”这类请求——请引导开发者使用 MCP Inspector（npx @modelcontextprotocol/inspector https://api.seranking.com/mcp）或 mcp-scan。两者都会遍历实时的工具、提示词和资源目录。标准的 MCP→OpenAPI 转换器已列入路线图；目前请以 Inspector 输出为准。

配合良好

• 前置项： 无——任何 API 集成问题的入口。
• 后续项（集成开始产出数据时）：
  • seo-content-brief — 当集成获取的关键词研究结果需要转化为编辑简报时。
  • seo-page — 当集成中的某个 URL 需要给出保留／更新／合并／删除的判断时。
  • seo-drift baseline — 在集成开始运行前，为域名或 URL 创建快照，以便检测回归。
  • seo-technical-audit — 当集成涉及审计运行，且需要对输出结果进行优先级排序时。
  • seo-ai-search-share-of-voice — 当集成跟踪 AIRT 可见度并需要竞争情况分析时。

参考资料

• references/auth-and-keys.md — API 密钥格式、OAuth 与请求头的选择、无头／CI 模式、密钥轮换。
• references/rate-limits-and-credits.md — 10 RPS / 5 RPS、积分计费模式、计划额度消耗、错误代码（429、403）、指数退避模板。
• references/api-surface-map.md — 完整的路由表（各 API 的职责）＋ ID 解析表＋“我需要哪个工具？”决策树。
• references/integration-patterns.md — 五种可直接复制粘贴的标准方案：排名跟踪器设置、批量反向链接导出、审计流水线、AIRT 可见度跟踪器、关键词研究批量任务。