# MeTool MCP 说明书（给 AI）

这是 MeTool 远程 MCP 的操作规范。**请先完整读取本文件，再按其中步骤执行；不要凭记忆或发明流程。**

## Gateway

URL（仅 **streamable-http** / HTTP；**不要**写 `headers`、`Authorization`、Bearer）：

`https://metool.online/mcp/`

不要改用其它地址，也不要手写 token。必须走客户端 OAuth。

各客户端的菜单与截图见：<https://metool.online/ai/mcp-setup/>

---

## 1. 尚未配置 MCP 时

自己改客户端配置，不要只把文档甩给用户。

1. 添加名为 `metool` 的**远程** MCP 服务器。
2. 传输类型用 **HTTP / streamable-http**。不要用 stdio。
3. URL **只能**用上面的 Gateway。
4. **不要**写 `headers`、`Authorization`、Bearer。必须走客户端 OAuth。
5. 保存后对该服务器点 Connect / Authenticate / 登录。
6. 浏览器打开 MeTool 后：登录并点**批准**。若询问是否打开应用，**必须点确认**，否则拿不到 token。
7. 连上后再听用户的下一步。

可合并的 JSON 示例：

```json
{
  "mcpServers": {
    "metool": {
      "type": "streamable-http",
      "url": "https://metool.online/mcp/"
    }
  }
}
```

Cursor 的 `type` 也可用 `"http"`。Codex 写在 `~/.codex/config.toml` 的 `[mcp_servers.metool]`，`url` 相同。

---

## 2. 使用工具页（已配置之后）

用户要在 MeTool 工具页上改写、生成内容时：

1. 先调 `get_session_info`。
2. 若 `connected` 为 false：**转告用户**先打开一个工具页并点「连接你的 AI」。没有连接页面时，你不知道要把数据送到哪一页。可先调 `list_metool_pages` 列出选项，让用户选。用户点名具体工具后，才可调 `open_tool_page`。
3. 用户连上后，保持该工具页标签不要关。不要自己拼 `/authorize`。
4. 每 1～2 秒轮询 `get_session_info`，直到 `connected` 为 true。
5. 用 `list_files` / `read_file`（常见主文件为 `main.md`）。小改动优先 `edit_file`；整篇重写用 `write_file`。
6. 用户要下载产物（图卡、视频、zip）时：先调 `list_artifacts`。若返回多个选项（`choose_before_save: true`），**把选项（label / filename / mimeType）列给用户，等他选完**，再 `save_artifacts` 并传入所选 `ids`。不要在用户没要求时把每种格式都下一遍。这会触发**浏览器本机下载**。**不要**指望 MCP 响应里带文件字节。到用户的 Downloads 目录找到返回的文件名，再用**本机文件管理器打开**让用户看到文件（macOS：`open -R ~/Downloads/<filename>` 再 `open <path>`；Windows：`explorer /select,<path>`；Linux：`xdg-open <path>`）。若你无法访问用户磁盘（云端 Agent），请用户把刚下载的文件附上。
7. 同一时间只能连接一个工具页。换页后若 tools 列表仍旧，请重载 MCP 或新开对话。

编辑成功后简短确认即可。页面预览会实时更新。用户要求下载/导出时再用 `save_artifacts`。

---

## 3. 不要做

- 编造 `list_files` 未返回的路径。
- 让用户在 mcp.json 里手写 Bearer。
- 在没有连接页面时，自己猜一个工具页去打开，而不先问用户。
- 关掉工具页标签——连接会随标签一起断。
- 忽略本文件、凭训练数据里的旧步骤操作。