# Mtop DevTools MCP Server

让 AI 能够与浏览器实时交互的 MCP 服务器。

## 功能

- 📊 **browser_get_requests**: 获取历史请求记录
- 📊 **browser_get_events**: 获取 RUM/aplus 埋点事件
- 📝 **browser_get_logs**: 获取控制台日志
- 🎭 **browser_set_mock**: 动态设置 Mock 数据
- 🌐 **browser_list**: 统一列出普通浏览器和托管浏览器，返回默认目标、类型及连接状态
- 🚀 **browser_launch / browser_close**: 启动或关闭独立 Profile 的托管 Chrome
- 🌐 **browser_page_snapshot**: 首次获取页面结构和可交互元素
- ⚡ **browser_page_act**: 执行页面动作、等待异步稳定并返回通知、可交互控件和焦点等高置信度信号

## 浏览器交互工作流

首次进入页面时调用 `browser_page_snapshot` 建立结构基线。后续点击、输入、悬停、滚动、按键和上传优先调用 `browser_page_act` 完成动作与异步同步；同页结果读取 `effects.notifications`、`effects.interactives` 和 `effects.focus`，导航结果读取新 URL 和就绪状态。仅在导航后、`fullSnapshotRecommended: true` 或需要视觉判断时重新 snapshot 或截图。

长列表重新感知时优先使用 `browser_page_snapshot(mode: "viewport")`；已知弹层或区域时使用 `rootSelector`；仅需要控件时使用 `mode: "interactive"`，避免整页 AX Tree 占用上下文。页面缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。

`browser_page_click/type/hover/scroll/press/upload` 保留为低级兼容接口，不需要在每次动作后固定追加 wait、snapshot 或 screenshot。

## 安装

**方式一：使用 npx（推荐，保持最新）**

```bash
# 直接运行配置向导，会自动生成 npx 配置
npx @mtop-devtools/mcp-server --configure
```

**方式二：全局安装（启动更快）**

```bash
# 全局安装
npm install -g @mtop-devtools/mcp-server

# 运行配置向导
mtop-mcp-configure
```

配置向导会自动完成所有设置，支持 **VSCode Copilot**、**Claude Code**、**Cursor**。完成后重启 MCP 客户端即可使用。

## 使用

打开任意淘宝/飞猪页面，在 AI 客户端中发送：

```
获取最近 5 个请求
帮我分析购物车相关的接口
把购物车总价改成 150 元测试一下
```

## 本地开发

```bash
cd mcp-server
npm install
npm run build
npm link
```

运行配置向导，选择使用自定义 Extension ID：

```bash
mtop-mcp-configure
# 选择 "使用自定义 Chrome 插件 ID？" -> Yes
# 输入你的开发版 Extension ID
```

> 💡 在 `chrome://extensions/` 查看你的 Extension ID

发布新版本：

```bash
npm version patch
npm run build
npm publish --access public
```

## 卸载

```bash
# 全局安装的版本
mtop-mcp-uninstall

# 或使用 npx
npx @mtop-devtools/mcp-server --uninstall
```

## 故障排查

**配置失败**：检查目录权限和路径是否存在

```bash
# macOS
mkdir -p ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts
```

**"Native host has exited"**：删除配置后重新运行

```bash
rm ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.alibaba.mtop_devtools.mcp.*
```

**Extension ID 不匹配**：使用 `mtop-mcp-configure` 重新配置

**查看日志**：

- MCP Server: AI 客户端的输出面板
- Chrome Extension: `chrome://extensions/` → Mtop DevTools → background page

## License

ISC