OpenAPI 与 MCP 接入指南

监测数据不只属于监测工具。这篇讲怎么用 OpenAPI（REST）和 MCP（Model Context Protocol）把数据接进你自己的系统。两边共用同一套底层接口，数字一致。

鉴权

两个通道都用 API Key，在应用内「设置 → API 密钥」创建。

• 格式：Authorization: Bearer pk_live_xxxxxxxx
• 权限范围：read（读数据）/ write（读 + 触发抓取）
• 明文只显示一次，创建后立刻复制保存；库里只存哈希，丢了只能重新建

限流

• 每 Key：120 次 / 分钟，5000 次 / 天
• 响应头带 X-RateLimit-Limit / Remaining / Reset
• 超限返回 429，带 Retry-After

OpenAPI 端点清单

基础路径 /api/v1，返回统一为 { data, meta } 结构，错误为 { error: { code, message } }。

健康检查（无需鉴权）

curl https://你的域名/api/v1/health

账号与项目

# 当前 Key 信息 + 项目列表
curl -H "Authorization: Bearer pk_live_xxx" \
  https://你的域名/api/v1/me

# 项目列表（含问句数、引擎状态、最近抓取）
curl -H "Authorization: Bearer pk_live_xxx" \
  https://你的域名/api/v1/projects

# 单个项目详情（含品牌列表与引擎配置）
curl -H "Authorization: Bearer pk_live_xxx" \
  https://你的域名/api/v1/projects/1

项目数据（/api/v1/projects/:id/...）

| 端点 | 说明 | 关键参数 | |---|---|---| | overview | 总览：可见性 / 位次 / 情感趋势 | ?range=30（7/14/30/90/180/365） | | prompts | 问句列表与各自指标 | ?gap=1 只看缺口问句；?limit=200 | | prompts/:pid | 单个问句详情（含回答样本） | — | | sources | 信源分析 | ?level=url 按 URL 拆（默认按域名） | | competitors | 竞品对标 | 同 range | | perception | 品牌认知属性拆解 | 同 range | | runs | 抓取运行记录（最近 20 条） | — | | runs (POST) | 触发一次抓取 | 需 write 权限；body: { "engineKeys": [...] } |

示例：拉最近 30 天、按缺口排序的问句

curl -H "Authorization: Bearer pk_live_xxx" \
  "https://你的域名/api/v1/projects/1/prompts?range=30&gap=1&limit=50"

示例：用 write Key 触发抓取

curl -X POST -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"engineKeys":["deepseek","qwen"]}' \
  https://你的域名/api/v1/projects/1/runs

字段约定

• 所有比率类字段为 0-1 的小数（如可见性 0.34），百分比由前端换算
• 时间统一 ISO 8601（UTC）
• meta.requestId 每次请求唯一，排查问题时带上它

MCP 接入

MCP（Model Context Protocol）让你在 Claude Desktop、Cursor 等支持 MCP 的客户端里，直接用自然语言查询监测数据。

连接信息：

• 传输方式：HTTP（JSON-RPC）
• 端点：https://你的域名/api/mcp（与 OpenAPI 同源）
• 鉴权：同一个 pk_live_xxx Key

可用工具：

| 工具 | 作用 | |---|---| | list_projects | 列出项目 | | get_visibility_overview | 总览指标 | | list_prompts | 问句列表（可带缺口过滤） | | get_prompt_detail | 问句详情 | | list_sources | 信源列表 | | compare_competitors | 竞品对比 | | get_brand_perception | 品牌认知属性 | | list_runs | 抓取记录 | | trigger_run | 触发抓取（需 write） |

配置示例（以 Claude Desktop 的 claude_desktop_config.json 为例）：

{
  "mcpServers": {
    "geo-ai": {
      "type": "http",
      "url": "https://你的域名/api/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_xxx"
      }
    }
  }
}

配好后可以直接问：「我们上个月在『降噪耳机推荐』这类问题下的可见性趋势如何？」「最近被抓取的信源里，竞品占了哪些？」

典型用法

1. 接进自己的 BI 定时任务拉 overview + prompts，写进数据仓库，和内部销售数据做关联分析——回答「AI 可见性和成交的关系」。

2. 周报自动化 每周一拉上周数据 → 渲染成模板 → 推送飞书 / 企微 / 邮件。用只读 Key。

3. Agent 工作流 把 MCP 接进你的内容 Agent：发现缺口问句 → 自动检索对应信源 → 生成内容 brief → 两周后调 overview 复测。

4. 异常告警 定时对比 overview 的可见性环比，跌幅超阈值时告警——比人盯周报快一周。

最佳实践

• 只读优先：日常同步用 read Key，write Key 单独保管，降低误触发挥发的风险
• 尊重限流：批量同步用指数退避重试；一天一次的全量同步远低于配额
• 缓存 meta.requestId：排查时双方对照
• 轮换 Key：每季度重建一次，旧 Key 即时吊销

排错

| 返回 | 含义 | 处理 | |---|---|---| | 401 missing_token | 没带 Authorization 头 | 补头 | | 401 invalid_token | Key 错或已吊销 | 检查 / 重建 | | 403 insufficient_scope | 权限不够 | 用 write Key 调 POST | | 404 not_found | 项目 / 问句不存在或不属于你 | 核对 ID 归属 | | 409 already_running | 该项目正在抓取 | 稍后重试 | | 429 | 触发限流 | 看 Retry-After，退避重试 |