# MCP

`acdev mcp` 是一个 stdio 上的 [MCP](https://modelcontextprotocol.io) 服务器, 把[调试工具](https://docs.dopame.ai/zh/guide/tools.md)和更多能力交给 AI agent: 它能自己启动一个 `acdev dev` 开发会话, 看屏幕、点按钮、读控制台、截图, 用来开发和验证你的应用.

这些事 agent 用普通的[调试命令](https://docs.dopame.ai/zh/guide/tools.md)也都能做, 不用任何配置; [acdev skill](https://docs.dopame.ai/zh/guide/agents.md) 会教它怎么用. 你的 agent 用工具比用 shell 顺手时再接 MCP.

## 接入

Claude Code:

```sh
claude mcp add acdev -- acdev mcp
```

别的客户端: 命令是 `acdev mcp`, 没有参数 (想钉住某个会话时加 `--session <pid>`).

## 工具

| 工具 | 作用 |
| --- | --- |
| `doctor` | 像 [`acdev doctor`](https://docs.dopame.ai/zh/guide/doctor.md) 一样检查这台机器能不能跑 `acdev dev`; `start` 失败时先调它 |
| `doctor_fix` | 像 `acdev doctor --fix` 一样: 检查, 修 acdev 不用问就能修的, 再检查一遍. 要下载、安装或结束进程的修复它只点名: 由用户在终端里跑 `acdev doctor --fix` (会问), 或同意跑 `acdev doctor --fix --yes`. 它的 `dir` 必须在工作目录里 |
| `sessions` | 列出正在跑的 `acdev dev`, 可以钉住一个 |
| `start` / `stop` / `logs` | 自己起一个 `acdev dev` 开发会话 (默认是工作目录的工程)、停掉它、读它的输出. 已经有一个 `acdev dev` 跑的正好是这些 (同样的工程、`desktop`、`app` 和 `headless`) 时, `start` 就用那个会话, 并说明这一点 (`attached to acdev dev <pid>, which already runs …`); `stop` 和 `logs` 碰不到别处启动的会话. 有一个 `acdev dev` 以别的方式跑着这些工程时, `start` 报错并点出它 (`… which is not what start asked for`): 用 `sessions {use: <pid>}` 钉住它, 或者先停掉它. `start {force: true}` 照样再起一个 |
| `webs` | 页面列表, 以及在等回答的摄像头或麦克风提示 |
| `permissions` / `answer` / `revoke` | 列出等待回答的摄像头和麦克风提示以及已做的决定、允许或拒绝一个等待中的提示、收回一个决定, 见 [摄像头和麦克风](https://docs.dopame.ai/zh/guide/tools.md#摄像头和麦克风) |
| `snapshot` | 屏幕的文字形式: 窗口和焦点窗口的元素, 每个带 ref |
| `act` / `run` | 按 ref 做一个动作 / 依次做多个, 返回发生的变化 |
| `open` | 打开一个应用并等它的窗口出来 |
| `query` | 用 CSS 选择器找元素, 隐藏的也能找到; 给出的 ref 可以交给 `act` |
| `wait_for` | 等某段文字出现 (或消失) |
| `screenshot` | 一个窗口或整个屏幕的截图; 桌面的面板 (Dock、菜单栏) 只在整个屏幕的截图里有 |
| `eval` | 在页面里执行 JS |
| `console` / `network` | 页面的日志和请求 |
| `emulate` | 切换深浅色 |
| `choose_folder` / `choose_files` / `choose_save_file` | 事先回答页面下一次弹出的文件选择器 |
| `route` / `unroute` | 伪造页面请求的回应, 或让请求失败 |
| `pointer` | 把指针移到屏幕上的一个点, 是一次真的移动 (悬停、屏幕边缘) |
| `clipboard` | 读写剪贴板 |
| `input` | 给页面发原始的鼠标和键盘事件, 用页面坐标; `wait` (`ms`) 在中间按住一个键或按钮 |
| `clock` | 接管页面的时间: 装上假时钟、暂停它、让它往前走 |
| `dialog` | 事先回答页面的下一个 `alert` / `confirm` / `prompt`, 并列出页面弹过的对话框 |
| `resize` | 调整窗口的大小, 使它的页面是给定的尺寸 |

选会话的规则: 钉住的; 否则 `start` 起的; 否则按工作目录挑.

声明了的能力不用回答; 只有摄像头、麦克风和空闲检测 (`idleDetection`) 会问用户. 页面第一次要用其中一样时才问用户, 页面等着回答. `webs` 把这样的提示列成一行: `recorder waits for approval of microphone: the answer tool allows or denies it`. `answer` 接受 `allow` (true 或 false). 允许时, 必须给出 `permissions` 列出的 `app` 和 `capability`, 这样调用本身就写明了授予的是什么; 拒绝时, 给 `prompt` id 或者 `app` 加 `capability` 都行, 只有一个提示在等时两样都不用给. 它代替的是用户自己的回答, 所以这个工具标为需要确认的操作: 只允许用户要求过或同意过的.

只跑一个应用的会话里, 关掉唯一的窗口 (对 `w1` 用 `act` 做 `close`) 会结束这个会话, 这是有意这样设计的. 这次调用成功, 它的回答会说明这一点: `closed w1; acdev runtime exited with it, so acdev dev 4242 ended`. 下一次调用失败, 并说会话已经停了 (`start` 起的会话是 `the acdev dev started here (pid 4242) stopped; last output: …`, 在别处启动的会话是 `acdev dev 4242 stopped; no acdev dev is running (…)`). 要继续就再跑一次 `start`. 别的动作做到一半运行时没了, 就会失败, 报 `acdev runtime closed the connection`; 步骤里关掉了那个窗口的 `run` 也是这样, 因为它那些步骤的回答丢了, 所以要用 `act` 来关.

`input`、`clock`、`dialog` 和 `resize` 替 agent 做的, 就是测试里 `app.mouse` / `app.keyboard`、`app.clock`、`app.answerDialog` 和 `app.resize` 做的事; 见 [时间、对话框和页面准备](https://docs.dopame.ai/zh/guide/testing.md#时间对话框和页面准备). `clock` 接受 `action` (`install`、`pause_at`、`fast_forward`、`run_for`、`resume`、`set_fixed_time`、`set_system_time`、`state`), 加一个 `time` (ISO 字符串, 或 1970 年以来的毫秒数) 或一个 `duration` (毫秒数、`"mm:ss"` 或 `"hh:mm:ss"`). 不带 `accept` 或 `text` 的 `dialog` 只列出对话框.

页面的文件夹、文件或保存选择器可以在页面打开它之前回答: 用一个 `path` (相对路径按工作目录解析) 或 `cancel: true` 调 `choose_folder`, 再做打开选择器的那个 `act`. 每个回答给同一种选择器的下一次. 用 `start {headless: true}` 起的会话里没有选择器对话框, 所以没有事先回答的选择器会失败, 页面看到的是被取消了. `choose_files` 接受 `paths`, `choose_save_file` 接受一个 `path`.

```json
{ "name": "choose_folder", "arguments": { "path": "fixtures/project" } }
{ "name": "act", "arguments": { "ref": "w1.4", "action": "click" } }
```

在没有显示器的机器上, 用 `headless: true` 调 `start`; `screenshot` 和 `snapshot` 照样能用. 用 `eval` 跑 `getComputedStyle` 或 `getBoundingClientRect` 检查样式和布局, 见 [样式和布局](https://docs.dopame.ai/zh/guide/tools.md#样式和布局).

`clipboard` 在有窗口的会话里碰的是**你的系统剪贴板**, 所以要 agent 明确给 `system: true`, 并标为需要确认的操作. headless 会话有自己的剪贴板.

服务器的 stdin 关闭或收到信号时, 会停掉 `start` 起的那个开发会话.
