内容
🐵 猴子看
> 猴子看到什么就模仿什么。你的代理在真实的 Chrome 浏览器中获得了眼睛和手。
MonkeySee 让 MCP 客户端（Claude Code、Codex 或任何支持 MCP 的客户端）控制一个真实的、已登录的 Chrome 浏览器配置文件。它可以打开标签页、读取页面内容、点击、输入、滚动、截图，并判断任务是否完成。
关键词是 **你的** Chrome 浏览器。不是一个全新的、无头无脑的沙盒环境，而是一个你已经登录了邮箱、仪表盘等所有内容的真实浏览器。
## 演示
https://github.com/user-attachments/assets/bb544504-8406-49e4-97fc-94e51bb56d59
## 这不是一个代理
让我们明确一下谁在思考。MonkeySee **没有代理循环，没有 LLM，没有推理**。你的终端代理已经具备了所有这些功能。MonkeySee 只是一个快速、可靠的执行者，为你的代理提供手和眼睛。
```
大脑 手和眼睛
┌─────────────┐ MCP（stdio） ┌──────────────────┐ ws://localhost:8787 ┌──────────│ Claude Code │──────────────── monkeysee-bridge │▶│ 扩展程序 │
│ / Codex │ （ dumb router） │ │ SW + DOM │
└─────────────┘ └──────────────────┘ └───────────┘
```
代理决定 **做什么**。MonkeySee 只负责 **执行** 并报告它所看到的内容。
可以同时运行多个终端吗？这可以正常工作 —— 没有守护进程，没有设置。每个会话都有自己的桥梁；第一个启动的会话成为 **领导者**，其他会话通过第二个本地端口 (`8788`) 作为 **跟随者** 中继。每个会话都跟踪自己的标签页，因此在一个终端中执行的操作会影响该终端的标签页，而在另一个终端中执行的操作会影响另一个终端的标签页。如果领导者的终端关闭，剩余的会话会自动接管并保留其标签页。
```
┌───────────────────┐ ws://localhost:8787 ┌───────────┐
会话 A ─stdio─▶ │ 桥梁（领导者） │──────────────────────▶│ 扩展程序 │──▶ Chrome
└───────────────────┘ └───────────┘
▲
│ ws://localhost:8788 （控制中继）
│
┌───────────────────┐
会话 B ─stdio─▶ │ 桥梁（跟随者） │ 代理其 RPC 请求到领导者
└───────────────────┘
```
## 你的代理可以做什么
一旦连接成功，你的代理就会获得一个工具箱- **查看：** `get_state`（将页面作为编号元素列表，可选地附带截图）、`get_forms`（仅表单 — 每个字段及其类型、标签、当前值、选项和标志；比 `get_state` 更便宜的填充任务）、`extract_text`、`screenshot`
- **对看到操作：** `click`、`type`、`select_option`、`fill_fields`（一次填充多个字段，可以立即或作为可监视的机填充）、`hover`、`focus`（所有按元素索引）
- **手动执行：** `click_at`、`scroll`、`scroll、`drag`、`press`、`type_text`
- **移动：** `open_tab`、`navigate`、`go_back`、`go_forward`、`wait_for_load`
- **管理标签页：** `list_tabs`、`switch_tab`、`close_tab`
- **调用：** `done`（使用最终 URL + 页面片段确定答案）
## 你可以用它做什么
驱动 **你的** 已登录 Chrome 浏览器的好处在于，代理可以根据终端会话中已经存在的内容和你已经登录的网站执行操作。由此衍生出几个工作流：
- **用代理已经拥有的上下文填充表单。** 将 Claude Code 或 Codex 指向注册表、职位申请、费用报告或供应商入职表单，让它从文件、前一次对话或存储库中填充字段。它使用 `get_forms` 读取表单（一个紧凑的、分组列表 — 标签、类型、当前值、选项），在单个 `fill_fields` 调用中填充它们，并在提交之前告诉你它输入了什么。默认情况下，`fill_fields` 以 **渐进** 模式运行：它滚动每个字段到视图中并像人一样输入，因此你可以观看表单自行填充（演示和录制）。传递 `mode: 'batch'` 以代替进行即时、无人值守的填充。
- **从没有 API 的仪表盘中提取数据。** 分析数据费、内部管理已经登录了。，`extract_text`，并返回结构化注释，无需爬虫凭证或无头重新登录。
- **重现并排除报告中的错误。** 将重现步骤交给它；它会点击你的暂存应用，截图每个状态，并报告流程实际中断的位置。
- **提交枯燥的工单。** 打开 Jira/Linear/GitHub，从对话中的列表创建问题，并链接它们回去，所有操作都在你已经通过身份验证的标签页中进行。
- **将工作与实时网站进行交叉检查。** 将代码 **应该** 渲染的内容与已部署的页面实际显示的内容进行比较，并使用标记集截图来指出不匹配的位置。
- **驱动你不想编写脚本的多步骤 Web 流程。** Cookie 横幅、分页表格、多页向导：代理在每个步骤后重新读取页面，而不是依赖脆弱的记录选择器。
在所有这些过程中，代理都是大脑，而 MonkeySee 是执行者。你可以掌控全局，允许列表控制任何 每次操作都会报告它所看到的内容。
## 安装
一个安装程序同时提供两个部分。Chrome 应用商店中没有可供搜索的列表。
```bash
npm install -g-bridge
```
它。最快的路径是注册 MCP 服务器打印扩展程序路径：
monkeysee-bridge init
```
该命令为每个项目（用户范围）monkeysee`，并打印捆绑的扩展。标志：`--scope project` 在 `.m` 中写入存储文件，而不是用户配置；`--client codex` 连接 Codex (`~/.code`) 而不是 Claude Code；`--print` 显示配置而不写入任何内容。参见 `monkeysee-bridge init --help`。
更喜欢自己连接？使用以下命令项目注册服务器：
```bash
claude mcp add monkeysee -s user -- npx -y monkeysee-bridge
```
... 或将以下内容放入项目的 `..json` 中（然后仅在从该文件夹运行 时应用）：
```json
{ "mcpServers": { "monkeysee": { "command": "npx", "args": ["-monkeysee- } } }
```
无论哪种方式，都需要手动执行一个步骤，因为没有安装程序可以此操作： 浏览器中教授捆绑的扩展程序。
打开 `chrome://extensions`
2. 启用 **** （右上角）
3. 点击 **加载解 并选择 `init` （或安装）打印的路径
错过了路径？没问题。桥梁每次启动时都会将路径重新打印到 stderr，因此在您的 MCP 日志中可以看到。
加载扩展程序后，确认链接是活动的：
```bash
monkeysee-bridge doctor
```
它打开 WebSocket，等待扩展程序连接，并报告 `OK` （带有扩展程序版本）、`DOWN` （扩展程序未加载或 Chrome 浏览器未运行）或 `INCOMPATIBLE` （协议版本不匹配）。如果桥梁已经在端口上运行，它会报告这一点，而不是争夺端口。
## 60 秒演示
桥梁可以从 CLI （`pnpm test`，无需浏览器）完全测试。完整的循环需要 Chrome 浏览器：
1. **构建：** `pnpm build`
2. **加载扩展程序：** `chrome:// → 开发者模式 → 加载解压 → `packages/extension/dist`。（已发布的 `monkeysee-bridge` 内部包含扩展程序，安装程序和桥梁的启动行都打印加载路径。）
3. **启动 Claude Code**。复制 `.mcp.json.example` 到 `.mcp.json` （它被 git 忽略，因此保持本地）。该条目io 启动桥梁。在几秒钟内，扩展程序的服务工作线程将连接到桥梁。在扩展程序弹出窗口中查找绿色圆点。
**给它一个任务 明确指示它使用浏览器，否则一个有能力的代理将直接从内存或自己的网络搜索中回答，而不会触及 MonkeySee。尝试： _“使用 monkeysee 浏览器工具，为我找到一篇关于威尔士的维基百科文章。”_ 它应该 `open_tab`、`get_state`、`type` 进入搜索，`press('Enter')` 或 `click`，重新读取，`extract_text`，并使用 URL 和片段 `done`。
> **`ws://localhost:8787` 连接被拒绝？** 完全正常，当没有任何东西运行时。桥梁只有在 MCP 客户端启动后才会监听。 在此处启动 Claude Code （`.mcp.json` 会启动它），或单独运行它来测试链接：`node packages/dist/index.js`。服务工作线程会以回退重试连接，因此顺序要。您将在桥梁的 stderr 中看到 `extension / `hello`。
## 开发
```bash
pnpm install
pnpm build # 构建所有软件包
pnpm dev # 监视所有软件包
pnpm typecheck
pnpm lint
pn # 桥梁端 + 多会话检查浏览器）
```
pnpm 工作区中的三个软件
| 软件包 角色 |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| `monkeysee-protocol` | 共享线路类型 + zod 模式。兼容性主干。发布到 npm。 |
| `monkeysee-bridge` | MCP 服务器（stdio）+ WebSocket 服务器。翻译工具调用为 RPC。发布到 npm，带有 `bin`。 |
| `extension` | MV3 Chrome 扩展程序：服务工作线程路由器 + 内容脚本眼睛/手。捆绑到桥梁中，解压后加载深入了解请参见 [`docs/`](./docs)： [`STRUCTURE.md`](./docs/STRUCTURE.md) （项目地图 + 设计决策）。
## 安全（最小但真实）
您正在将一个机器人指向一个登录到您生活的浏览器。请像对待它一样。
扩展程序弹出窗口有一个 **域名允许列表**。启用 **强制** 后，不允许列表的域上的变异操作（`click`、`type`、`select_option`、`click_at`、`drag`、`press`、`type_text`）返回 `blocked` 错误。查看和导航永远不会被阻止。
## 受信任的输入（chrome.debugger）
默认情况下，操作会从内容脚本中触发合成 DOM 事件。某些网站很挑剔：它们会检查 `event.isTrusted`，或者忽略搜索框中的合成 Enter 键。
在弹出窗口中切换 **“受信任的输入（chrome.debugger）”**，以通过 Chrome DevTools 协议 (`Input.dispatch*`) 调度实际输入的 `click`、`type`、`type_text`、`press`、`click_at` 和 `drag`。这些事件是受信任的，并且表现得像一个真正的人的手指。注意：
- `debugger` 是一个 **必需** 权限（Chrome 不允许它作为可选权限）。只有在您打开开关时才会 **使用** 它。
- 如果附加失败（例如，DevTools 已经在该标签页中打开），MonkeySee 静默地恢复为该操作的合成事件。
- MCP 工具表面相同。代理永远不知道或不关心运行了哪个后端。
### 关于黄色“开始调试此浏览器”横幅
Chrome 自身在任何扩展程序调用 `chrome.debugger.attach()` 时显示 **“MonkeySee 浏览器代理开始调试此浏览器”** 信息栏，当以下两条件均成立时：
1. 弹出窗口中的 **受信任的输入** 后端已启用，且
2. 实际运行了依赖调试器的操作（`click`、`type`、`type_text`、`press`、`click_at` 或 `drag`）。附加是延迟的且每个标签页独立的，在第一个此类操作时，并且横幅会一直保留，直到 MonkeySee detach 或关闭。
它 **不会** 显示在：
- 打开标签页或导航
- 观察：`get_state`、`extract_text`
- `screenshot` / `get_state({ withScreenshot: true })` （这些使用 `chromeVisibleTab`，无需调试器）
- 任何操作同时后端默认为 `content` （合成
因此：保持后端在 `content` 上，你将永远不会看到横幅。打开受信任的后端并在每个标签页上启用它，MonkeySee 在那里调度输入时，你将看到它。
## 帧 + 截图
- **同源帧** 自动索引（`all_frames: true`）。同源 iframe 中的元素在 `get_state` 中显示，`frameId != 0`，可以通过索引点击，并报告其在视口坐标中的框。目前，跨源 iframe 不在此范围内。
- **`screenshot`** 返回受控标签页的可见视口作为 PNG。
- **`get_state({ withScreenshot: true })`** 将该图像与每个视口元素上绘制的编号标记集一起添加。非常适合代理以“指向”并确认。
## 版本兼容性
桥梁和扩展程序在 WebSocket `hello` 握手（合约位于 `monkeysee-protocol` 中）中交换 `protocolVersion`。如果它们的 **主** 版本有冲突，桥梁会拒绝连接，并且永远不会向不匹配的扩展程序提供工具调用。弹出窗口显示一个“不兼容的桥梁”状态，扩展缓慢重试，直到您更新较旧的一侧。相同的握手保护 follower→leader 控制通道，因此具有不同协议的过时会话将被拒绝，而不是跨越差距提供服务。预 1.0 版本，双方都是主版本 `0`，并通过工作区同步移动，因此这仅在未来发生重大更改时才会生效。
## 许可证
MIT。参见 [`LICENSE`](./LICENSE)。
