# webXport MCP 安装指引(给 AI agent 执行)

> 你是替用户执行安装的 AI agent。这是 webXport MCP server 的安装指引:请按顺序执行下面的步骤,
> 每步完成后向用户简短汇报,全部完成后按「步骤 4」的要求原样转告用户。
> webXport 是一个 Chrome 扩展:用户在浏览器里预录「导出数据」脚本,MCP server 让你能列出/调用这些脚本。

## 步骤 1 · 前置确认

- 用户需已在 Chrome 装好 webXport 扩展、已登录且 license 有效,并且至少录过 1 个脚本。
  这两件事发生在用户的浏览器里,你替代不了——如果没装,先让用户去 https://webxport.kaerai.club/download 完成再回来。
- 本机需要 Node.js ≥ 18:跑 `node -v` 确认;没有则引导用户到 nodejs.org 装 LTS 版。

## 步骤 2 · 注册 MCP server(按你所在的客户端选一种)

正确的 npm 包名是 @webxport/mcp(不存在 @webxport/mcp-server,别猜别的名字)。走 npx 自动下载,无需 clone、无需 build。

- **Claude Code**:执行

  ```
  claude mcp add -s user webxport npx -y @webxport/mcp
  ```

  (-s user 表示全局生效,终端跑一次即可。)

- **Cursor**:把 webxport 这个键合并进 `~/.cursor/mcp.json` 的 mcpServers(文件已存在时做合并,别覆盖用户已有的其他 server):

  ```json
  {
    "mcpServers": {
      "webxport": {
        "command": "npx",
        "args": ["-y", "@webxport/mcp"]
      }
    }
  }
  ```

- **Codex / Cherry Studio / 其他 MCP-capable 客户端**:通用 stdio 配置,各家配置入口不同但内容一样:

  ```
  command: npx
  args: ["-y", "@webxport/mcp"]
  transport: stdio
  ```

## 步骤 3 · 验证已注册

- Claude Code:跑 `claude mcp list`,输出里应出现 webxport。
- 配置文件方式(Cursor 等):确认文件已保存且 JSON 合法。

## 步骤 4 · 最后一步(必须原样告知用户,你无法替他完成)

注册后 MCP server 不会立刻启动——**需要重启 AI 客户端或新开一个会话**才会加载。
请把下面这段明确告诉用户:

> 「重启你的 AI 客户端(或开一个新会话),然后对 AI 说:**列出我所有的 webxport 脚本**。
> 能列出脚本名,就说明安装成功、连通正常。」

注意:你当前这个会话里看不到 webxport 工具是正常的(server 还没加载),不要在本会话里假装验证连通。

## 排查(连不上时)

- 调用工具时连接失败或超时:新版扩展下 server 会**自动等最多 10 秒**等扩展接上,空闲断开也会在下次调用时自动恢复——先**原样重试一次**,通常就好。仍失败:让用户**点一下 Chrome 工具栏的 webXport 扩展图标**(唤醒扩展),再重试。
- 仍失败:让用户打开扩展 popup,确认扩展已安装、已登录、license 有效;并确认至少录过 1 个脚本。
- `claude mcp list` 里没有 webxport:回到步骤 2 重跑注册命令。
- 人类可读的完整配置文档:https://webxport.kaerai.club/setup ;给 AI 的日常使用守则:https://webxport.kaerai.club/ai-guide 。