# 万相台 AI 助手：MCP 接入说明

此文档供客户和 AI 客户端读取。端点提供客户授权范围内的广告查询，以及经预览确认的计划预算和启停操作。

## 连接要求

- URL：`https://api.miandanni.com/api/wanxiang/mcp`
- 传输：Streamable HTTP。
- 兼容协议版本：`2025-11-25`、`2025-06-18`。由客户端在初始化时协商，不代表支持所有协议版本。
- 鉴权：请求头 `Authorization: Bearer <客户自己的奇门云密钥>`。
- 适用客户端：能够连接远程 Streamable HTTP 并设置自定义 Authorization 请求头的 MCP 客户端。不能填写请求头、仅支持 OAuth 登录的客户端不能直接使用本配置。
- 连接由客户端本机程序或其服务端发起；不支持第三方网页的浏览器跨域直连。
- 前置条件：客户账户正常、万相台 API 套餐有效，目标店铺属于该账户且授权有效。
- 网页工作台权益和其他平台套餐不授予本服务使用资格；淘宝平台订购、商品资格及实际接口权限仍须有效。

客户可打开 https://api.miandanni.com/docs/wanxiang/mcp 生成配置。页面只在浏览器内生成文字，不持久化、不上传密钥，也不自动查询账户。点击复制后配置会进入系统剪贴板；页面“清空”只清空本页内容，不清除已经复制或粘贴到客户端的配置。

通用配置示例（必须用客户自己的密钥替换占位内容；不同客户端字段可能不同）：

```json
{
  "mcpServers": {
    "wanxiang": {
      "type": "http",
      "url": "https://api.miandanni.com/api/wanxiang/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CUSTOMER_API_KEY"
      }
    }
  }
}
```

把密钥保存在客户信任的客户端私密配置或环境变量中，不放在 URL、聊天提示词、公开文档、日志或截图里。客户密钥不是淘宝 AppSecret，也不是店铺 shopKey。本文不包含有效凭据。

客户端开发者注意：使用 HTTP POST 发送单个 JSON-RPC 消息，`Content-Type: application/json`，`Accept` 同时包含 `application/json` 和 `text/event-stream`。初始化后携带协商的 `MCP-Protocol-Version` 请求头。本站用 JSON 返回请求结果，接收通知时返回无正文的 HTTP 202；不分配 MCP 会话、不提供 GET 事件流或旧版 SSE 专用地址，GET/DELETE 返回 405。不要把浏览器地址栏打开端点的结果当成连接测试。

## 首次连接

1. 由客户端连接 MCP，获取服务器提供的工具列表和 JSON Schema。
2. 调用 `wanxiang_list_shops`，让客户选择明确的店铺，不猜 shopKey。
3. 查询真实计划前确认推广场景；不能把不同场景的同名计划混为一个。
4. 先返回一页结果，注明分页情况。需要继续时按工具参数翻页。
5. 调用方法前读取其说明；工具名称、参数和可用能力以本次连接的 `tools/list` 为准。

## 工具及用途

| 工具 | 用途 |
| --- | --- |
| `wanxiang_list_shops` | 当前客户授权店铺列表。 |
| `wanxiang_list_methods` | 查看读写目录及 MCP 开放标记；支持分类、搜索和分页。 |
| `wanxiang_describe_method` | 读取完整方法名、参数说明、示例和文档链接。 |
| `wanxiang_read` | 仅调用目录标记为查询的方法；不能传写入方法。 |
| `wanxiang_list_campaigns` | 分页查询所选店铺与场景的计划。 |
| `wanxiang_preview_campaign_change` | 为预算或启停操作生成具体变更预览；不改变广告。 |
| `wanxiang_execute_campaign_change` | 客户确认后提交预览中的变更；按工具返回要求填写确认参数。 |
| `wanxiang_get_change` | 查询变更记录及执行状态，结果不明时用于核验。 |

本版仅声明以上范围。通用查询不开放任意写入；创建、删除及其他修改能力不要因为原始接口目录中存在就推断已经通过 MCP 开放。库存、退款、经营利润及其他广告平台不在本版范围。

## 参数约定

以下为本版工具参数摘要；以连接时的 JSON Schema 和工具返回为准，不在参数里放 Authorization、密钥或其他客户身份。

| 工具 | 参数 |
| --- | --- |
| `wanxiang_list_shops` | 空对象 `{}`。返回店铺名称、`shopKey` 和授权状态；列出不等于该店铺当前授权有效。 |
| `wanxiang_list_methods` | 可选 `operation`：`read` 或 `write`；`search`；`offset` 默认 0；`pageSize` 默认 30，范围 1–100。 |
| `wanxiang_describe_method` | 必填 `method`，使用目录列出的完整方法名。 |
| `wanxiang_read` | 必填 `shopKey`、`method`、`params`。`params` 为业务参数对象，含该方法要求的 `top_service_context`；先读取方法说明，不在外层增加字段。 |
| `wanxiang_list_campaigns` | 必填 `shopKey`、`bizCode`；可选 `offset` 默认 0，`pageSize` 默认 20，范围 1–100。 |
| `wanxiang_preview_campaign_change` | 必填 `shopKey`、`bizCode`、`campaignId`、`change`。`change=budget` 时只加 `dailyBudgetYuan`；`change=status` 时只加 `status`。一次预览只变更一类设置。 |
| `wanxiang_execute_campaign_change` | 必填 `previewId`、`confirmation`，均采用原预览返回内容，不传新预算或其他修改参数。 |
| `wanxiang_get_change` | 必填原操作的 `previewId`；只读核验，不提交写入。 |

专用计划工具的 `bizCode`：`onebpSite` 为货品全站推广，`onebpSearch` 为关键词推广，`onebpDisplay` 为人群推广。通用查询的场景要求以具体方法为准。

`campaignId` 使用真实计划编号的字符串形式，并须为可精确表示的正整数。`dailyBudgetYuan` 为整数人民币元／日，本站参数范围为 1–10,000,000，具体计划还须满足淘宝业务限制；只支持 `dmc_type=normal` 的普通日预算，不支持不限预算等其他类型。`status` 只能为 `start`（开启）或 `pause`（暂停）。

预览有效期为 5 分钟，并绑定创建它的账户和密钥；更换或重置密钥后，不要尝试用新密钥继续执行旧预览。执行后保留 `previewId`，用于查询结果。返回的 `state`、`canExecute`、`operationConfirmed`、`mustNotRetryWrite` 和核验说明应一起读取；当前值符合目标，不足以单独证明本次写入成功。

## 读数规则

- 每次明确客户、店铺、推广场景、对象、日期、分页和归因口径。
- 方法参数以工具说明及官方业务参数为准。保留店铺、计划和商品编号的字符串精度；核对金额单位。
- 报表结果可能含业务失败，不能仅凭 HTTP 200 当成成功。工具 `isError` 或业务错误应向客户说明，不能改成空列表。
- 缺失数据保留未知；零花费、字段缺失、日期未覆盖是不同状态。
- 今日分时与历史日报、不同归因窗口、直接与总成交不能随意合并或比较。
- 广告归因成交不等于全店净销售或利润；不同推广场景的成交不能直接相加成真实销售额。
- 本服务按请求查询，不承诺持续后台自动采集或自动优化。不得为了作答无节制地翻页或循环请求。

## 写入顺序

1. 查询目标计划，确认店铺、场景、编号、名称及当前设置。
2. 调用 `wanxiang_preview_campaign_change`，按实际工具 Schema 填写预算或状态变更。
3. 向客户完整展示预览中的店铺、计划、旧值、新值、有效期及确认要求。生成预览不代表客户已确认。
4. 得到客户对这次具体操作的明确确认，再调用 `wanxiang_execute_campaign_change`。不能自行把连接授权当成任意广告修改授权。
5. 预览过期、计划设置已变化或校验失败时重新预览，不篡改原预览值。
6. 读取执行结果。超时、中断或结果不明时调用 `wanxiang_get_change` 并查询实际计划；不要自动重新执行，不通过新预览绕过结果未知状态。

结果未知或仍在执行的记录会阻止该计划创建新的变更预览，需要保留原 `previewId` 并人工核对。只读核验发现当前值等于目标值，并不证明本次操作成功，也不会据此自动解除未知状态。不要更换密钥、账户或调用通用接口绕过该限制。

连接 MCP、列店铺、查询数据和生成预览不会启动广告。预算或启停操作经确认执行后可能影响真实投放。

## 示例问法

- 列出我有权限的店铺，先不改任何计划。
- 查询这家店货品全站推广的计划，先看一页并说明分页。
- 查看指定日期的广告花费与成交，说明归因口径和缺失数据。
- 为这个计划准备日预算调整预览，展示新旧值，等待我确认。
- 检查刚才的调整状态，先核验，不要重复写入。

## 常见问题

| 现象 | 处理 |
| --- | --- |
| 无工具或无法连接 | 核对完整 URL、HTTP 类型和客户端自定义请求头能力，刷新工具列表。 |
| 401 或密钥无效 | 重新复制客户密钥，核对 Bearer 空格；重置后更换所有旧连接。 |
| 套餐未开通或到期 | 检查万相台 API 权益；其他权益不能替代。 |
| 店铺不可访问 | 重新列店铺，核对归属和有效期；必要时重新授权。 |
| 429 | 降低并发，按返回提示稍后查询。 |
| 淘宝业务错误 | 保留错误码和请求编号，检查场景、参数、授权及应用订购。 |
| 写入结果不明 | 查变更记录及计划当前值，不盲目再次提交。 |

完整业务方法参考：https://api.miandanni.com/docs/wanxiang
