# WOWAPA MCP 接入说明

服务地址：https://app.wowapa.com/api/mcp
传输：Streamable HTTP。业务报表只读，数据查询在服务器执行；可按账号保存个人关注词和审核进度，无需下载服务端源码。
网页帮助：https://app.wowapa.com/agent-setup

## 第一步：检查是否已经连接

查看当前 Agent 的工具目录。工具名称可能带 wowapa 或 wowapa_web 前缀。
如果已有此服务的 apa_capabilities，先调用它。成功返回 remote-readonly 和 streamable-http 即可继续使用，不重复安装或授权。
本机 APA 的 stdio 工具是另一个连接，不能用本地数据库查询代替远程连接验收。

## 第二步：仅在没有连接时添加客户端

### Codex

先确认已安装 Codex，并可在该客户端修改 MCP 设置。
如果已配置相同 URL，沿用已有服务名称，不新增重复连接。
首次配置使用：

```text
codex mcp add wowapa --url https://app.wowapa.com/api/mcp
codex mcp login wowapa
```

在浏览器由用户登录 WOWAPA，核对账号、站点及有效期，点击同意只读授权。
授权与刷新令牌由客户端的凭据存储管理。不要让用户把密码或令牌发到聊天。
默认登录支持动态客户端注册 DCR、S256 PKCE；本服务不支持 CIMD。
只有客户端明确提示不支持注册方式时，且 codex mcp login --help 存在此参数，才使用：

```text
codex mcp login wowapa --oauth-client-registration dcr
```

也可将以下不含密钥的配置合并进自己的 Codex config.toml；不要覆盖其他 MCP：

```toml
[mcp_servers.wowapa]
url = "https://app.wowapa.com/api/mcp"
startup_timeout_sec = 30
tool_timeout_sec = 60
```

新连接未出现在当前工具目录时，刷新客户端 MCP 连接或开启新会话。子 Agent 使用宿主客户端已配置、已授权的连接；独立机器或另一个客户端仍须各自配置授权。

### VS Code

在支持 MCP 的 VS Code 中使用网页的“在 VS Code 中添加”，或将下列配置合并到 .vscode/mcp.json：

```json
{"servers":{"wowapa":{"type":"http","url":"https://app.wowapa.com/api/mcp"}}}
```

使用客户端登录入口，浏览器中由用户确认授权。此 JSON 是 VS Code 格式，不是所有 Agent 的通用配置。

### 其他客户端

在客户端设置中添加远程 MCP，选择 Streamable HTTP，填写服务地址，使用客户端提供的 OAuth 登录入口。
OAuth 客户端需要支持 DCR 和 S256 PKCE。不要猜测它的配置文件格式，也不要安装 stdio 服务端替代远程服务。
当前聊天没有修改客户端设置或打开授权的能力时，明确告诉用户需要在 MCP 设置中添加地址并授权；普通网页请求不是宿主 Agent 工具连接。

### 不支持 OAuth 的客户端

让用户在网站“Agent 授权”页创建只读个人密钥，选择站点和期限。
仅通过该客户端安全凭据设置填写 Authorization: Bearer 令牌；不要把令牌写进共享配置、脚本、命令、日志或聊天。
不提供安全凭据入口的客户端，请由用户选择支持安全凭据管理的客户端。
网页登录会话令牌不能作为 MCP 令牌使用。

## 第三步：连接后按顺序验证

1. 读取 tools/list，以服务器当前声明为准。
2. 调用 apa_capabilities({})，确认只读、OAuth 支持及限制。旧 productionOAuth=false 表示独立生产安全评估未完成，不表示 OAuth 不可用。
3. 调用 apa_list_stations({})。
4. 从返回站点选一个 station，调用 apa_list_imports({"station":"所选代码","granularity":"all"})。station 为必填；默认只列周报，明确 all 才同时列日周。
5. 从返回的完整报告选择真实 report_date 或 report_week，再查询，不按当天日期猜数据。

查询示例参数模板（替换站点、日期和关键词；不能原样使用占位符）：

```json
{"station":"所选代码","source":"day","reportDate":"真实已导入日期","queries":["待查询关键词"],"matchMode":"exact","limit":10}
```

每页默认/最多 50 条，每批最多 10 个查询词。翻页使用返回的 nextOffset，并回传第一页 snapshotId 到 expectedSnapshot。一般日分析窗口最多30天，日报候选最多7天，回看最多30天；品牌排名跨度最多20,000，日周分析品牌要指定明确窗口。
管理员可以随时调整远程 MCP 开放的功能。以 apa_capabilities.tools 和最新 tools/list 为准；关闭功能会停止该功能的排队／在途查询，旧工具目录也不能绕过。收到“功能未开放／管理员已调整”时刷新工具列表，选择仍开放的工具或联系管理员，不重复安装或申请授权。重新开放功能后原有效授权仍可用，账号被限制或授权被撤销另行处理。
日/周排名分别处理，数值越小越靠前；排名不是搜索量，未收录不是零搜索量，缺少报告不要擅自改成别的日期。

## 当前工具与管理员权限

当前接入28项工具，实际可用项以当前账号的 tools/list 和 apa_capabilities.tools 为准。
新账号与新接入的合格功能默认开放，保留之前明确收回的权限；全站关闭优先于个人授权。功能调整无需重新安装或授权，客户端目录缓存时刷新目录/连接。

| 功能 | 工具 |
| --- | --- |
| 启动、数据概况与报告检查 | apa_capabilities、apa_status、apa_list_stations、apa_list_imports、apa_check_reports、apa_check_daily_reports |
| 查询、趋势与涨幅 | apa_combined_search、apa_search_keywords、apa_keyword_trend、apa_rank_movers、apa_consecutive_growth、apa_daily_keyword_candidates、apa_daily_best_rank_lifts |
| 品牌与品类分析 | apa_brand_groups、apa_brand_group_detail、apa_brand_group_detail_batch、apa_brand_breakouts、apa_product_opportunities、apa_brand_cross_site |
| 审核校验 | apa_audit_brand_review、apa_audit_keyword_selection |
| 增量审核 | apa_review_start、apa_review_page、apa_review_submit、apa_review_evidence、apa_review_result |
| 个人关注词 | apa_watchlist、apa_set_watch |

审核建议流程：start固定真实报告窗口与用户规则 → 按候选id用submit保存本批结论 → page继续 → 有歧义的id用evidence补查 → result读取结果。
review_start的source支持daily_candidates、rank_movers、daily_best_rank_lifts。源工具被全站或个人关闭时，对应审核任务也不能继续；审核不能绕过源功能权限。
只保存当前账号的辅助记录，不修改业务报告。每页50条；每账号最多100个审核任务，单任务最多保存10000条候选；超过时明确拒绝，不跳过候选或伪称完整。个人关注词最多1000条，和网页个人关注词共用；本地EXE/MCP关注词独立。

品牌单项详情也返回rows、metadata、snapshotId；组内翻页按next_keyword_offset和expectedSnapshot继续。apa_search_keywords仍按输入词返回数组，增加snapshotId及报告状态；推荐日周同时查询使用apa_combined_search。批量品牌详情最多10个key，审核提交/校验最多200条，补证据最多20个id。日窗口30天、候选7天、回看30天，周窗口24周；品牌组和详情须明确起止报告，短期爆发须明确目标报告。历史最佳提升沿用本地最多366天连续历史核查，缺报告不补零。

不提供报表导入/预览、删除、数据库备份或电脑文件导出；不接受任何export参数。新增站点和修改全站品牌词库仍在网页管理员端操作。
能力兼容字段readOnly表示业务报表只读，businessReadOnly明确该边界；个人状态保存由personalStateWrites及每个工具annotations说明。

## 遇到问题时，只处理对应原因

| 状态/现象 | 下一步 |
| --- | --- |
| 未授权请求 401，带 WWW-Authenticate | 正常 OAuth 发现流程；由客户端登录。已授权仍401则检查过期、撤销或账号/MCP停用，不无限重试 |
| 403 | 检查账号、授权站点和 MCP 使用权限；需要时联系管理员，不通过重复安装绕过 |
| 浏览器打开 MCP 返回401/405 | 不是连接失败证明；本服务接受 Streamable HTTP POST，不提供旧 SSE GET 流 |
| 406 / 415 | 客户端须发送 JSON，并声明 Accept: application/json, text/event-stream；使用标准 MCP 客户端 |
| 429 | 等待后重试，不循环创建客户端或授权 |
| OAuth 回调失败 | 在发起登录的同一客户端/电脑完成回调；不要把本机回调网址发到另一台设备 |
| 工具未出现 | 刷新连接或新开会话；客户端限制须在该客户端设置中解决 |
| 工具返回 isError | 连接已完成；核对 tools/list 参数、报告日期、权限和快照 |
| 无法读取网页帮助 | 尝试本 Markdown 地址；若网络也失败，使用上方固定端点与已验证步骤，不下载服务器源码 |

网页“检查连接入口”只探测服务和公共 OAuth 元数据，不创建客户端、授权或读取账号数据。服务入口在线不等于你的 Agent 已经授权成功；最终以实际三项工具调用为准。

Codex 方式参考官方说明：https://developers.openai.com/codex/mcp/