如何启用 Odysseus 内置浏览器 MCP 服务器(@playwright/mcp)
如何启用 Odysseus 内置浏览器 MCP 服务器(@playwright/mcp)
Odysseus 在启动时会自动注册几个内置 MCP 服务器,其中浏览器服务器(server id 为 builtin_browser,显示名 "Built-in: Browser")通过 npx 运行 @playwright/mcp,为 Agent 提供页面导航、截图和 vision 能力。这个服务器依赖 npm 包,因此它不像 memory、email 这类纯 Python 内置服务器那样开箱即用——需要先把 @playwright/mcp 放进本地 npx 缓存,重启后服务器才会注册。本文介绍如何完成这个启用流程,以及如何通过启动日志判断它是否注册成功。
工作原理:Odysseus 如何启动浏览器 MCP
注册逻辑位于 src/builtin_mcp.py。builtin_browser 的启动命令为:
npx -y @playwright/mcp@latest --headless --caps vision
在此之上,启动代码会自动补充几个参数(来自 src/builtin_mcp.py):
- 如果在系统里找到浏览器可执行文件(按顺序探测
google-chrome、chromium、chromium-browser,以及/opt/google/chrome/chrome、/usr/bin/google-chrome、/usr/bin/chromium、/usr/bin/chromium-browser等固定路径),会追加--executable-path <path>;找不到时不追加,交给 Playwright MCP 使用其默认浏览器。 --isolated:除非设置了ODYSSEUS_BROWSER_ISOLATED=0(或false/no)。--no-sandbox:除非设置了ODYSSEUS_BROWSER_NO_SANDBOX=0(或false/no)。
服务器通过 stdio 传输由 McpManager 作为子进程托管,与 Python 内置服务器一样,注册是异步后台任务,发生在应用启动阶段。
一个环境差异值得先确认:Docker 镜像已经安装好了所需依赖——Dockerfile 中 nodejs、npm 用于提供 npx,chromium 用于提供浏览器二进制,所以容器内一般只差 npm 包本身;原生安装(Linux/macOS/Windows)则需要宿主机自己具备 Node.js(提供 npx)和一个可用的 Chrome/Chromium。
启用步骤
1. 确认 npx 可用
Odysseus 通过 PATH 查找 npx,找不到时会回退到若干常见位置(POSIX 下包括 ~/.npm-global/bin/npx、~/.local/bin/npx、/usr/local/bin/npx、/usr/bin/npx;Windows 下包括 %APPDATA%\npm\npx.cmd、C:\Program Files\nodejs\npx.cmd 等,见 src/builtin_mcp.py)。在运行 Odysseus 的同一台机器上执行:
npx --version
Docker 安装无需此步(镜像已含 nodejs/npm);原生安装若此命令不存在,需要先安装 Node.js。
2. 预装 @playwright/mcp 包(一次性)
按 docs/setup.md 的 “Built-in MCP servers (optional setup)” 一节,执行一次:
npx -y @playwright/mcp@latest --version
该命令会安装 @playwright/mcp 及 Playwright 本体(文档标注总计约 300MB),耗时取决于网络,完成后本地 npx 缓存里就有了这个包。这条命令没有副作用性的环境修改,只是把包装进 npx 缓存,可安全重复执行。
关于“是否必须预装”存在两种表述,适用条件不同:docs/setup.md 说明 npx 类内置服务器“仅当 npm 包已在本地 npx 缓存中才启动”,未缓存时会跳过并打印一条说明性的启动日志,以免全新安装被多分钟的 npm 下载阻塞或因缺少 Playwright 系统依赖而挂起;而 src/builtin_mcp.py 的注释指出,默认路径允许 npx -y 在首次启动时自行安装 @playwright/mcp,只有设置 ODYSSEUS_BROWSER_MCP_REQUIRE_CACHE=1 才会回到“无网络启动”的旧行为。两者不冲突地看:手动预装(上面的命令)在任何版本行为下都能保证服务器可用;如果你希望保留无网络启动的严格行为,设置 ODYSSEUS_BROWSER_MCP_REQUIRE_CACHE=1,此时包未缓存会在日志中直接给出 Fix: npx -y @playwright/mcp@latest --version 的提示。
3. 重启 Odysseus
预装后重启应用,让启动注册逻辑重新运行:
- Docker 安装:
docker compose restart odysseus(或docker compose up -d重建)。 - 原生安装:停掉 uvicorn 进程后按 docs/setup.md 的方式重新启动,例如
python -m uvicorn app:app --host 127.0.0.1 --port 7000。
注意:如果环境变量里设了 ODYSSEUS_DISABLE_MCP=1(或 true/yes),所有内置 MCP 服务器(包括浏览器服务器)都不会注册,日志会显示 “Built-in MCP servers disabled via ODYSSEUS_DISABLE_MCP”。
验证注册结果
注册发生在启动阶段,结果直接体现在启动日志中(日志语句来自 src/builtin_mcp.py):
- 正常:先打印
NPX binary resolved to: <npx 路径>,随后Starting NPX server: Built-in: Browser (npx -y @playwright/mcp@latest --headless --caps vision ...),成功连接后输出Built-in NPX server registered: Built-in: Browser。 - 失败:
Built-in NPX server failed to connect: Built-in: Browser,或抛出异常时输出Built-in NPX server ... error: ...。 - 设置了
ODYSSEUS_BROWSER_MCP_REQUIRE_CACHE=1且包未缓存时,会打印一段包含 Reason / Impact / Fix 的警告,其中 Fix 即第 2 步的npx -y @playwright/mcp@latest --version命令。
Docker 安装可用 docker compose logs --tail=120 odysseus 查看上述日志;确认出现 Built-in NPX server registered: Built-in: Browser 即表示浏览器 MCP 已启用。
可选环境变量
以下环境变量来自 src/builtin_mcp.py,在需要时配置后再重启生效:
| 变量 | 作用(依据源码行为) |
|---|---|
ODYSSEUS_BROWSER_EXECUTABLE |
显式指定浏览器可执行文件路径,跳过自动探测 |
ODYSSEUS_BROWSER_ISOLATED |
置为 0/false/no 时不追加 --isolated |
ODYSSEUS_BROWSER_NO_SANDBOX |
置为 0/false/no 时不追加 --no-sandbox |
ODYSSEUS_BROWSER_MCP_CACHE |
npx 缓存目录,默认 <应用目录>/data/local/playwright-mcp-cache;Playwright 浏览器下载在其 browsers 子目录 |
ODYSSEUS_BROWSER_MCP_REQUIRE_CACHE |
置 1 时要求包已在 npx 缓存,不做启动时网络安装 |
限制与排查边界
- 浏览器服务器比 Python 内置服务器启动慢,
register_builtin_servers会让 NPX 服务器延迟 3 秒再接入(等待 Python 服务器先完成),日志里看到 “Starting NPX server” 稍晚属正常。 - 未缓存 + 无网络安装(
ODYSSEUS_BROWSER_MCP_REQUIRE_CACHE=1)时,服务器是“跳过并留痕”而不是让应用启动失败——这解释了为什么“重启后功能没出现”时应当先查日志,而不是检查应用是否起来。 - 缺少 Playwright 系统依赖时服务器可能连不上(setup 文档提到的动机之一),此时日志会给出
failed to connect,需按 docs/setup.md 的说明先补齐环境依赖再重启。 builtin_browser是内置注册的一部分,不需要在 MCP 管理界面手工添加;MCP 管理路由(添加/删除自定义 MCP 服务器)与这条内置路径互不影响。