Browser Recorder MCP

自用项目 / AI 生成警告

本项目主要用于个人学习、实验和自用，代码与文档主要由 AI 生成和修改，可能包含错误、遗漏或未经验证的假设。不保证其他平台的兼容性、稳定性或安全性。使用前请自行审查代码并验证运行结果。

基于 Chrome DevTools MCP 的浏览器操作与录制服务。外部 agent 通过带 token 认证的 HTTP 入口连接：浏览器工具交给 chrome-devtools-mcp，本项目只补充标签页音视频录制。Chrome 的启动、重连、临时 profile 和关闭均由 DevTools 管理；初始化、列工具和健康检查不会启动 Chrome。

容器自带 Node 24.21.0；源码运行要求 Node 24+。项目直接使用原生资源管理接口，不再支持 Node 22 及更早版本。

两个容器镜像均包含 Noto CJK 字体，用于中文、日文和韩文页面的显示、截图及录制。直接在 WSL/Linux 中运行源码时，也需安装 CJK 字体，例如 sudo apt-get install fonts-noto-cjk。

Windows 用户：推荐 WSL

建议在 WSL 2 的 Linux 环境中运行服务，使用 WSLg 提供 Chrome 所需的图形环境。在 WSL 内准备 Linux 版 Node 24+、Chrome/Chromium 和 FFmpeg（含 ffprobe），将源码放在 Linux 文件系统中，然后在项目根目录执行：

npm ci
# 使用 Chromium 或非默认安装位置时，设置 CHROME_PATH 为 Linux 可执行文件路径。
npm start

首次启动自动生成 token，保存在项目根目录 .env。服务启动后，在另一个 WSL 终端中读取其中的 MCP_TOKEN 值并设置同名 shell 变量，用于健康检查和客户端配置：

curl -H "Authorization: Bearer $MCP_TOKEN" http://127.0.0.1:3000/health

本项目不再提供 Windows PowerShell 包装脚本。已有 wslc 环境仍可使用保留的镜像、D3D12 GPU 配置和手动命令，见 wslc 部署说明。下方原生 Linux NVIDIA 容器使用另一套 GPU 配置，不应直接视作 WSL 部署步骤。

Related MCP server: chrome-mcp

连接客户端

外部 agent 使用支持 Streamable HTTP 的 MCP 配置，示例如下（字段格式以客户端要求为准）：

{
  "mcpServers": {
    "browser-recorder": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": { "Authorization": "Bearer REPLACE_WITH_YOUR_MCP_TOKEN" }
    }
  }
}

其他机器上的 agent 将 127.0.0.1 替换为服务的可达地址；WSL 的远程访问还需按实际网络环境配置。也可使用下文的 hostc 隧道。外部 agent 不需要安装 Node、Chrome、FFmpeg 或启动 MCP 进程。服务要求 Authorization: Bearer <MCP_TOKEN>；将示例中的占位符替换为服务端配置的 token。Mcp-Session-Id 仅用于协议会话路由。

原生 Linux + NVIDIA

在装有 NVIDIA 专有驱动和 NVIDIA Container Toolkit 的 Linux 主机上：

./environments/linux-nvidia/build.sh
GPU=0 PORT=3000 ./environments/linux-nvidia/run.sh

与 wslc 的 GPU 接入方式不同（CDI 设备直通而非 WSL 的 D3D12），工具代码和录制扩展完全共用。 详见 原生 Linux NVIDIA 部署说明。

GHCR 镜像与自动发布

镜像工作流 先使用 Node 24.21.0 运行 npm test，通过后分别构建 linux-nvidia 和 wslc 两个 linux/amd64 镜像，发布到 ghcr.io/matachuan-258v/browser-recorder-mcp。PR 只测试和构建，不发布。普通 GitHub runner 不提供 NVIDIA/WSL GPU，工作流不运行 GPU 端到端测试。

两个环境使用各自的标签，不设置通用 latest。版本标签不更新 main 对应的环境标签；需要固定部署版本时使用版本标签或镜像 digest。每次发布的完整镜像名和 digest 会显示在 Actions 运行摘要中。

原生 Linux NVIDIA 用户可以直接拉取预构建镜像，再通过现有启动脚本运行：

docker pull ghcr.io/matachuan-258v/browser-recorder-mcp:linux-nvidia
IMAGE=ghcr.io/matachuan-258v/browser-recorder-mcp:linux-nvidia GPU=0 PORT=3000 ./environments/linux-nvidia/run.sh

wslc 用户将手动部署命令中的镜像名替换为 ghcr.io/matachuan-258v/browser-recorder-mcp:wslc，见部署说明。

工作流使用 GitHub 自动提供的 GITHUB_TOKEN，只在镜像构建任务授予 packages: write，无需额外配置 PAT 或仓库 secret。CI 为 wslc 覆盖基础镜像、apt 和 npm 的镜像源，使用官方源；本地构建的默认镜像源仍按 Dockerfile 配置。镜像带有源码仓库和提交的 OCI 标签，以关联 GitHub Package 与仓库。

GHCR 新建 Package 默认私有；需要匿名拉取时，仓库 owner 在该 Package 的 Settings 中将可见性设为 Public。私有镜像需先登录 GHCR，使用有 read:packages 权限的 PAT classic。发布权限与可见性规则参见 GitHub Container registry 文档。

Docker Compose

compose.yaml 面向原生 Linux NVIDIA 主机，使用 GHCR 的 linux-nvidia 镜像。需要 Docker Compose 2.30+、Docker 的 CDI 支持，以及已配置 NVIDIA CDI 设备的 NVIDIA Container Toolkit；GPU 前提同原生 Linux 部署说明。wslc 的镜像和手动命令继续保留在其部署目录中。

在项目根目录执行（私有 GHCR Package 需先登录）：

docker compose pull
docker compose up -d --wait
docker compose logs -f browser-recorder

默认仅将端口映射到宿主机 127.0.0.1:3000；客户端 URL 为 http://127.0.0.1:3000/mcp。录像和自动生成的 token 保存在宿主机 artifacts/recordings/，重建容器或执行 docker compose down 后仍保留。首次启动后读取该目录 .env 中的 MCP_TOKEN 配置客户端；容器写出的文件权限为 0600，需要宿主机相应读取权限。健康检查从显式环境变量或 /data/.env 读取 token，并访问受认证保护的 /health，不会启动 Chrome。

参数可以通过 shell 环境变量或项目根目录 .env 设置；根目录 .env 用于 Compose 配置，自动生成的服务 token 写入挂载目录下的 .env。

例如选择 GPU、修改端口和启用 hostc：

GPU=1 MCP_PORT=3001 MCP_HOSTC=1 docker compose up -d --wait

更新镜像、停止或删除容器：

docker compose pull
docker compose up -d --wait
docker compose stop
docker compose down

服务退出时按 unless-stopped 策略重启；正常停止最多等待 3 分钟，让执行中的工具和录制完成清理。使用 docker compose -p <项目名> 和不同的端口、数据目录可运行多个独立实例。

需要从本地源码构建时叠加 compose.build.yaml：

docker compose -f compose.yaml -f compose.build.yaml up -d --build --wait

本地构建默认镜像名为 game-browser-mcp:linux-nvidia，可用 IMAGE 和 BASE_IMAGE 覆盖镜像名与基础镜像。之后管理该实例时使用相同的两个 -f 参数。

Token 与 hostc.dev

直接启动即可：服务自动加载 .env，优先使用非空环境变量 MCP_TOKEN，其次使用文件中的值。两者均未配置或为空时，生成 32 字节随机 token，以 64 字符十六进制文本写入 .env，后续启动自动复用。已有的其他配置和注释会保留；新写入文件在 POSIX 系统上的权限为 0600。文件无法保存时拒绝启动，显式配置但格式不合法的 token 也会报错。

• 本机运行：默认保存在项目根目录 .env，与启动命令所在目录无关。

• 容器运行：保存在 /data/.env，即宿主机挂载的录像目录下；默认是 artifacts/recordings/.env。重建容器时保留该目录即可复用 token。

• 可通过 MCP_ENV_FILE 指定其他路径。环境变量优先于 .env 中的配置；显式传入的 token 不会自动写入文件。

启动日志会提示新生成 token 的保存路径，不输出 token 内容。请从文件读取 MCP_TOKEN 值用于客户端的 Authorization 请求头；.env 已被 Git 和镜像构建排除。也可以自行指定 token：

export MCP_TOKEN="$(openssl rand -hex 32)"

启用隧道（未配置 token 时也会自动生成并保存）：

# 原生 Linux 容器
MCP_HOSTC=1 ./environments/linux-nvidia/run.sh
# 或本机 Node 服务
MCP_HOSTC=1 npm start

wslc 容器在手动 wslc run 命令中添加 -e MCP_HOSTC=1，详见其部署说明。

从 docker logs -f browser-recorder-mcp、wslc logs -f browser-recorder-mcp 或本机服务输出读取 hostc 实际打印的 HTTPS 地址，在其末尾加 /mcp 作为客户端 URL；仍须配置上述 Authorization 请求头。/health 同样要求 token。公网连接使用 HTTPS，token 不要放进 URL。

服务在 HTTP 监听成功后运行 npx --yes hostc@latest，需要能访问 npm 和 hostc。容器内已包含 Node/npm，宿主机无需安装 hostc。按 hostc 官方说明，不把 hostc 固定为项目依赖；短暂断网由 hostc 自动重连，离线过久可能更换地址，应以日志为准。停止服务会关闭隧道；hostc 进程意外退出则关闭 MCP 服务并以非零状态退出。重新启动隧道会生成新地址。

服务与会话

• /health 和 /mcp 的所有请求均须携带 Bearer token；缺失或错误返回 HTTP 401，token 不接受 URL 查询参数。

• GET /health：返回服务状态、是否有活动会话、Chrome 是否已启动；不占用会话，不启动 Chrome。

• /mcp：Streamable HTTP MCP 接口，支持 SDK 的 POST、GET/SSE、DELETE 会话流程。不是旧式 /sse 接口。

• 同时只允许一个活动会话；第二个初始化请求返回 HTTP 409，避免两个 agent 同时操作。

• 客户端通过 DELETE /mcp 结束会话后，服务先等待工具和录制保存，再由 DevTools 关闭该会话的 Chrome 并释放占用。

• 客户端直接断网不会立刻释放会话。默认无请求 30 分钟后回收；执行中的工具和录制不会被空闲回收中断。/health 请求不延长会话。

• 容器正常停止时会等待当前工具和录像清理。容器保持运行时，新客户端可以建立新的独立会话。

传输使用仓库锁定的 MCP TypeScript SDK 1.30.0，采用 initialize + session 的 Streamable HTTP 流程（2025-11-25 协议）。客户端需支持这一流程；没有实现仅支持 2026-07-28 无会话协议的新传输形态。

架构与工具

flowchart LR
  A[Agent] --> H[HTTP MCP：token 认证 / 会话 / 工具队列]
  H --> R[recording_*：标签页音视频录制]
  H --> D[Chrome DevTools MCP：工具与生命周期]
  D --> C[Chrome：独立临时 profile]
  R --> C

依赖锁定为 chrome-devtools-mcp@1.10.1。通过 SDK 内存传输连接官方 MCP 服务，按工具名转发请求；没有额外 HTTP 端口或第二个浏览器。官方 BrowserManager 是 Chrome 的唯一管理者，录制模块借用其浏览器对象，不调用 Chrome 的 launch、close 或 disconnect。此集成使用上游包内的 BrowserManager API，升级依赖时需重新验证兼容性。

全量开放上游公开工具分类，不设置工具白名单。 当前为 58 个 DevTools 工具，加上 3 个本地录制工具。工具名称、参数定义、图片、结构化结果及工具错误按上游协议传递；完整列表以 tools/list 为准。已开启公开的扩展、PWA、第三方工具、WebMCP、内存调试、坐标点击和 screencast 能力，不使用 slim 模式；隐藏的上游内部开发接口不属于此支持范围。

上游工具参数参见 DevTools 工具文档。部分能力依赖 Chrome 版本和页面支持，开放工具不代表所有页面均可使用。容器中的 Chrome 153 满足 WebMCP 的版本要求，并传入 --enable-features=WebMCP。网络工具和脚本可以读取页面数据；持有 MCP token 的客户端获得这些完整能力，token 不区分只读与写入权限。

旧的 browser_open/status/screenshot/click 已移除。客户端改用上游 list_pages、navigate_page、take_screenshot、click_at 等工具；click 使用快照元素 UID，click_at 使用截图坐标。浏览器初始尺寸为 1280×720、设备缩放为 1，可通过上游工具调整。

两种录制与冲突处理

先通过 list_pages 获取页面 ID，再传入 recording_start。音视频录制固定绑定该页面，不依赖当前选中标签页或 URL，两个同网址标签页也能区分。音视频录制限 HTTP(S) 页面和默认浏览器上下文；DevTools 创建的 isolatedContext 页面可使用官方纯视频录制。

录制规则适用于同一 MCP 会话：

• 所有客户端工具调用串行执行，两种录制互斥；同时只能录制一个页面。两种录制都会阻止空闲会话回收。

• 录制期间可以继续截图、点击、输入、查看信息和选择其他页面。对其他页面的导航等操作仍可使用。

• 对正在录制的页面，拒绝显式导航、关闭、调整尺寸、环境模拟、脚本执行，以及会重载页面的性能/Lighthouse 操作。页面提供的可执行第三方/WebMCP 工具也需先停止录制。

• 录制期间拒绝更改扩展和安装/启动/卸载 PWA。本项目使用的录制扩展由 recording_* 管理，不能通过扩展工具直接卸载、重载或触发；其他扩展在未录制时可正常管理。

• 点击或页面自身脚本仍可能触发导航，检测到后会安排停止录制。页面被外部关闭/崩溃或浏览器断开时，音视频录制标记为错误并保留已上传的原始分片和错误记录；无法保证崩溃时最后一段媒体完整。

• 官方录制的页面丢失时尝试完成录制并清理状态；无法清理则关闭该 DevTools 会话，需要结束当前 MCP 会话后重新初始化。Chrome 正常断开后的重启由 DevTools 负责；重连后需重新调用 list_pages，不能继续使用旧页面 ID。

• 客户端取消已经开始的操作时，队列仍等待该操作完成，防止后续录制与尚未结束的浏览器操作重叠。转发调用超过 120 秒时关闭 DevTools 会话，再次使用需建立新的 MCP 会话。

recording_status 查询本地录制状态，并通过 screencast 字段显示是否有官方录制占用。音视频默认帧率上限 30 fps、码率 6 Mbps。输出为 <id>.webm、<id>.json 和 <id>.raw.webm。

所有路径均属于服务端。上游工具显式读写文件的默认允许根目录为 GAME_DATA_DIR（容器为 /data），可将上传素材或待安装的扩展放在该目录。官方录制未指定路径时使用上游临时目录；建议指定数据目录中的路径以便保存。HTTP MCP 不提供录像文件下载接口。DevTools 的使用统计与 CrUX 上传在本项目中关闭。

配置

工具代码位于 src/，录制扩展位于 extension/，容器的 GPU/显示配置位于 environments/（wslc 为 wslc/，原生 Linux NVIDIA 为 linux-nvidia/）。WSL 内直接运行无需容器配置。独立运行工具需要 Node 24+、Chrome、FFmpeg，以及适当的显示环境。启动命令 npm start 默认运行 HTTP 服务。

Chrome 使用独立临时 profile，由 DevTools 启动和关闭，不接管日常浏览器。通用工具不硬编码 GPU 后端；wslc 镜像设置 D3D12 和 Weston，linux-nvidia 镜像使用 NVIDIA 原生 EGL 和 Weston。原始录制分片通过独立的容器内回环服务上传，不对外开放该内部端口。

端到端测试

测试逻辑位于 test/e2e.mjs，通过 HTTP 连接 MCP 服务，使用真实 DevTools 工具检查以下流程：

1. 确认服务尚未启动 Chrome，再打开模拟游戏页面。

2. 获取 PNG 截图并执行鼠标点击。

3. 启动录制，继续点击，并确认录制中不能切换网址。

4. 停止录制，检查视频时长、1280×720 分辨率及音视频流。

5. 检查重复停止、再次录制和到时自动保存。

6. 使用官方 screencast_* 录制纯视频，确认两种录制互斥。

fixtures/click-game.html 是测试素材：包含移动目标、开始按钮、点击计分、中文字体样例，以及周期性闪白和提示音。它不是实际游戏，仅在 GAME_TEST_FIXTURES=1 时由服务提供访问，正常运行无需开启。

原生 Linux NVIDIA 环境先构建镜像，然后在项目根目录执行：

GPU=0 ./environments/linux-nvidia/test.sh

默认产物保存在 artifacts/linux-nvidia-test/，可通过 DATA_DIR 指定其他目录。wslc 环境使用手动测试命令。两种容器测试均由各自的 smoke.sh 启动 HTTP 服务、启用测试页面，再运行 test/e2e.mjs；测试结束后关闭服务并删除测试容器，挂载目录中的录像、截图、媒体信息和日志会保留。

也可以对已启用测试页面的独立 HTTP 服务运行 E2E_SERVER_URL 指向该服务的 npm run test:e2e，同时设置与服务相同的 MCP_TOKEN。该测试会操作浏览器并录制，应使用没有活动会话、尚未启动 Chrome 的测试服务。它验证基础操作与媒体流，不测量复杂游戏性能或精确音画同步误差。

许可证

本项目采用 MIT License，按“现状”提供，不作任何担保。第三方依赖、Chrome/Chromium 及容器中各组件仍遵循各自的许可证。