配置¶
使用上游 PLAYWRIGHT_MCP_* 变量来实现 Playwright MCP 行为。 仅将 CLOAK_PLAYWRIGHT_MCP_* 用于 Cloak 特有的桥接行为。
旧版 CLOAKBROWSER_MCP_* 变量已不被支持。 生成的 CLI 参考 是桥接 CLI 标志及其对应环境变量的权威列表。
桥接选项¶
| 变量 | 默认值 | 说明 |
|---|---|---|
CLOAK_PLAYWRIGHT_MCP_TRANSPORT | stdio | 桥接器传输方式:stdio 或 streamable-http。 |
CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL | http | Streamable HTTP 监听器协议:http 或 https。 |
CLOAK_PLAYWRIGHT_MCP_HTTP_HOST | 127.0.0.1 | Streamable HTTP 监听器绑定的主机地址。 |
CLOAK_PLAYWRIGHT_MCP_HTTP_PORT | 3000 | Streamable HTTP 监听器绑定的端口。测试中可使用 0 分配临时端口。 |
CLOAK_PLAYWRIGHT_MCP_HTTP_ENDPOINT | /mcp | Streamable HTTP 端点路径。/healthz 和 /readyz 保留用于探针。 |
CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN | unset | 可选的 Bearer 令牌;设置后,Streamable HTTP 请求必须携带该令牌。 |
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_BACKEND | memory | 会话元数据后端。此版本仅实现 memory。 |
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_IDLE_TTL_MS | 3600000 | Streamable HTTP 会话的空闲有效期。会话过期时会释放其桥接器资源并终止上游子进程。 |
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_MAX | 32 | 单个进程中允许的最大活跃 Streamable HTTP 会话数。 |
CLOAK_PLAYWRIGHT_MCP_HTTPS_CERT | unset | Streamable HTTP 使用 HTTPS 时的 TLS 证书 PEM 文件路径。 |
CLOAK_PLAYWRIGHT_MCP_HTTPS_KEY | unset | Streamable HTTP 使用 HTTPS 时的 TLS 私钥 PEM 文件路径。 |
CLOAK_PLAYWRIGHT_MCP_HTTPS_PFX | unset | Streamable HTTP 使用 HTTPS 时的 TLS PFX/PKCS12 文件路径。 |
CLOAK_PLAYWRIGHT_MCP_HTTPS_PASSPHRASE | unset | 加密 HTTPS 私钥或 PFX 文件的密码。 |
CLOAK_PLAYWRIGHT_MCP_LOG_LEVEL | info | Streamable HTTP 运行日志级别:trace、debug、info、warn、error、fatal 或 silent。 |
PLAYWRIGHT_MCP_PROXY_SERVER | unset | 上游 Playwright MCP 使用的代理服务器。启用匹配时,用于确定 GeoIP 信息。 |
PLAYWRIGHT_MCP_PROXY_BYPASS | unset | 上游代理绕过列表,指定不应使用 PLAYWRIGHT_MCP_PROXY_SERVER 的主机。 |
CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH | false | 解析 PLAYWRIGHT_MCP_PROXY_SERVER 的 GeoIP 信息,并使 CloakBrowser 的时区和区域设置指纹参数与代理位置匹配。 |
CLOAK_PLAYWRIGHT_MCP_HUMANIZE | false | 启用 CloakBrowser 的类人鼠标、键盘和滚动行为。 |
CLOAK_PLAYWRIGHT_MCP_HUMAN_PRESET | default | CloakBrowser 类人行为预设:default 或 careful。仅在启用 humanize 时使用。 |
CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL | stable | CloakBrowser 二进制文件发布通道:stable 或仅限 Pro 的 preview。 |
CLOAKBROWSER_BINARY_PATH | unset | 自定义 CloakBrowser 可执行文件的路径。CLI 选项 --binary-path 优先。 |
CLOAKBROWSER_VERSION | unset | 未选择自定义可执行文件时传递给 CloakBrowser 缓存解析器的固定版本。有效的免费方案许可证密钥会忽略固定版本;CloakBrowser 可能复用缓存的二进制文件。 |
PLAYWRIGHT_MCP_BROWSER_ENGINE | cloak | cloak 使用 CloakBrowser 二进制文件。playwright 跳过 Cloak 专用的可执行文件替换。 |
PLAYWRIGHT_MCP_HEADLESS | true | 以无头模式运行 Chromium。 |
PLAYWRIGHT_MCP_OUTPUT_DIR | .playwright-mcp | npm 运行时的产物目录。Docker 将其设置为 /data。 |
PLAYWRIGHT_MCP_CODEGEN | typescript | 代码生成目标语言:typescript、python、java、csharp 或 none。桥接会验证该值,并将 codegen 写入生成的 Playwright MCP 配置。 |
PLAYWRIGHT_MCP_SNAPSHOT_BOXES | false | true 或 false;在快照中以 [box=x,y,width,height] 包含每个元素的边界框。桥接会验证该值,并将 snapshot.boxes 写入生成的 Playwright MCP 配置。 |
PLAYWRIGHT_MCP_TIMEOUT_SETTLE | 500 | 操作后等待触发工作稳定的上游时间(毫秒)。直接转发给 Playwright MCP。 |
PLAYWRIGHT_MCP_TIMEOUT_ACTION | 5000 | 默认操作超时时间,单位为毫秒。 |
PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION | 60000 | 默认导航超时时间,单位为毫秒。 |
PLAYWRIGHT_MCP_VIEWPORT_SIZE | upstream default | 浏览器视口大小,格式为 WIDTHxHEIGHT。 |
PLAYWRIGHT_MCP_USER_DATA_DIR | unset | 持久化 Chromium 配置文件目录。桥接器会将其解析为绝对路径,在缺失时创建它,验证其可写,并写入生成的 browser.userDataDir。 |
CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS | unset | 包含已验证上下文选项的 JSON 对象。支持的字段列在下方。 |
CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS | unset | 现有 Chrome 扩展目录的 JSON 数组或逗号分隔列表。需要 PLAYWRIGHT_MCP_USER_DATA_DIR。对于 Windows 路径或包含逗号的路径,请使用 JSON 数组。 |
CLOAK_PLAYWRIGHT_MCP_CONSOLE_FALLBACK | true | 启用控制台消息兼容性补丁。 |
CLOAK_PLAYWRIGHT_MCP_STEALTH_ARGS | true | 添加 CloakBrowser 默认的隐蔽启动参数。 |
CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS | unset | 额外的 Chromium 参数,以逗号分隔的列表或 JSON 数组提供。 |
CLOAK_PLAYWRIGHT_MCP_NO_SANDBOX | true | 添加 --no-sandbox 并禁用 Chromium 沙箱。 |
已管理 CDP¶
托管的 Chrome 开发者工具协议 (CDP) 访问是需要明确选择加入的。它公开了 由 MCP 通过具备能力的方式控制的相同 Chromium 浏览器版本 发现 URL。仅配置端口池并不会启用 CDP。
| CLI 选项 | 环境变量 | 默认 | 目的 |
|---|---|---|---|
--cdp-enabled, --no-cdp-enabled | CLOAK_PLAYWRIGHT_MCP_CDP_ENABLED | false | 设置 stdio 值和 Streamable HTTP 会话默认值。 |
--cdp-port-range <port\|start-end> | CLOAK_PLAYWRIGHT_MCP_CDP_PORT_RANGE | 未设置 | 配置进程本地外部代理端口池。每个启用的会话租用一个端口。 |
--cdp-host <host> | CLOAK_PLAYWRIGHT_MCP_CDP_HOST | 127.0.0.1 | 绑定托管的 CDP 代理。 |
--cdp-allow-remote, --no-cdp-allow-remote | CLOAK_PLAYWRIGHT_MCP_CDP_ALLOW_REMOTE | false | 允许或拒绝非回环绑定。 |
--cdp-advertised-host <host> | CLOAK_PLAYWRIGHT_MCP_CDP_ADVERTISED_HOST | 未设置 | 在发现 URL 中放置一个可外部访问的具体主机。通配符绑定需要此项。 |
--cdp-advertised-scheme <http\|https> | CLOAK_PLAYWRIGHT_MCP_CDP_ADVERTISED_SCHEME | http | 发布 http/ws 或 https/wss URL。这不会启用 TLS。 |
每个 CLI 值仅覆盖其对应的环境变量。特别是, --no-cdp-enabled 覆盖 CLOAK_PLAYWRIGHT_MCP_CDP_ENABLED=true,并且 --no-cdp-allow-remote 覆盖 CLOAK_PLAYWRIGHT_MCP_CDP_ALLOW_REMOTE=true。 启用的会话在其上游子开始之前,如果没有端口池,将被拒绝。 一个有效的假值不会创建监听器、端口租赁或能力。
对于 stdio,该进程值直接适用:
对于 Streamable HTTP,经过身份验证的平坦 cdpEnabled 布尔值 initialize 元数据覆盖该会话的进程默认设置。省略 字段继承流程值。这些示例明确选择了一个会话并 另一个出:
一个启用 CDP 的 HTTP 会话拥有一个外部端口租用。已禁用的会话没有。 消耗池。分配是进程本地的,选择未租用的最低候选项, 如果所选的外部端口已被占用,则会立即使该会话失败。 关闭会话以释放端口,或在池耗尽时配置更大的范围。
从 cloakbrowser_bridge_info 检索当前的 URL,然后传递它的 structuredContent.cdp.discoveryUrl 到像 Playwright 的 CDP 客户 chromium.connectOverCDP()。将那个 URL 视为凭证:它包含一个随机值 每代能力,并且在浏览器更换后会变得过时。托管的 CDP 是 不是 Playwright 服务器端点。chromium.connect() 和当前的 Open WebUI 不支持 PLAYWRIGHT_WS_URL 流。
--cdp-advertised-scheme https 发布 https 发现和 wss WebSocket 链接 仅此而已。该桥不为受管 CDP 提供 TLS:它的外部监听器和 Chromium 保持明文 HTTP/WebSocket。必须有运营商拥有的 TLS 终端器 在相同的广告租用端口上监听,保留广告的 Host 和 Origin 授权,并将其一对一地转发给该会话的明文监听器。
CDP 启用从 MCP 初始化期间开始 Chromium,以便所有权和外部 可以验证就绪情况。将 MCP 客户端初始化超时配置为至少 60 秒。当启用管理的 CDP 时,由用户提供的 CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS 不得包含 --remote-debugging-port, --remote-debugging-address,或 --remote-debugging-pipe(包括 = 形式)。 Playwright 自身的内部 --remote-debugging-pipe 仍然保持启用状态,同时 由网桥管理的回环 TCP 端点。
请参阅 工具, Docker, 安全,以及 架构 用于发现状态、部署, 限制和重启行为。
CloakBrowser 许可证与 GitHub 登录¶
许可证设置使用上游 CloakBrowser CLI;cloakbrowser-mcp 不会添加登录或退出命令:
login 可接受付费密钥,也可启动 GitHub 登录以获取免费层密钥。验证后的密钥存储在 ~/.cloakbrowser/license.key 中;logout 会删除该文件。info 会报告当前许可证 层级;对于 Pro 许可证,还会报告活动会话数。
也可以在 MCP 服务器环境中设置 CLOAKBROWSER_LICENSE_KEY。桥接器会将该变量转发给 上游/浏览器子进程,但不会记录它。当 CLOAKBROWSER_CACHE_DIR 指向包含 license.key 的自定义缓存时,CloakBrowser 会解析密钥,而桥接器只会从生成的浏览器 环境中转发该解析后的密钥。其他生成的环境条目不会被复制。
如果 CloakBrowser 拒绝提供的许可证密钥,或无法通过许可证服务器及缓存验证结果验证密钥,启动会因明确的 CloakBrowser 错误而失败。桥接器保留该错误,不会掩盖它或静默切换到其他浏览器或许可证级别。
许可证服务器不可用时,CloakBrowser 可以复用缓存的验证结果。这并不保证离线启动:下载二进制文件或启动浏览器仍可能失败。
CloakBrowser 发布通道¶
CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL 选择 CloakBrowser 二进制文件的发布通道,默认值为 stable。preview 请求 Pro 浏览器预览构建,仅适用于 Pro 许可证。无密钥或付费密钥下载时,显式固定的 CLOAKBROWSER_VERSION 优先。有效的免费方案许可证密钥忽略固定版本,并可能复用缓存的二进制文件。如果平台没有可用的 Preview,CloakBrowser 会回退到 Stable。
发布通道在桥接进程启动时选定。它适用于所有 Streamable HTTP 会话,且不能在 initialize 元数据中设置或覆盖。请重启桥接进程以更改它。
自定义 CloakBrowser 二进制文件¶
--binary-path <path> 为当前桥接进程选择自定义的 CloakBrowser 可执行文件。 CLOAKBROWSER_BINARY_PATH 为基于环境的部署提供相同设置;CLI 选项优先。桥接会 解析该路径,要求它是可读的普通文件,并将解析后的路径写入生成的 Playwright MCP 配置的 browser.launchOptions.executablePath。
桥接不会下载或更新自定义可执行文件。未选择自定义路径时,可使用 CLOAKBROWSER_VERSION 固定由 CloakBrowser 管理的二进制版本。
对于 Streamable HTTP,所选二进制文件属于桥接进程,并由其创建的每个 MCP 会话 使用。initialize 元数据不能选择或覆盖可执行文件路径;需要不同二进制文件的 会话应运行单独的桥接进程。
如果所选构建提供带有 getTools() 方法的 document.modelContext 或 navigator.modelContext,上游 Playwright MCP 可以在页面快照后添加 webmcp_<page-tool> 工具。它发送 tools/list_changed,桥接器转发通知和更新后的工具列表。每个动态工具的名称和模式由页面定义。
GeoIP 代理匹配¶
将 CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true 与 PLAYWRIGHT_MCP_PROXY_SERVER 一起设置,以根据代理出口位置推导 CloakBrowser 的 时区、语言和区域设置指纹标志。对于受支持的二进制文件,CloakBrowser 会选择原生 URL 内联身份验证;对于较旧的二进制文件,则保留 Playwright 代理对象作为回退。
有关配置示例、运行时 可流式传输的 HTTP 代理元数据、用例、优先级规则和限制,请参阅 GeoIP 代理匹配。
简明操作步骤请参阅通过代理进行区域 QA。
拟人化的输入行为¶
将 CLOAK_PLAYWRIGHT_MCP_HUMANIZE=true 设置为启用 CloakBrowser 的类人 鼠标、键盘和滚动层,用于页面交互。 该桥接器通过 Playwright MCP 的页面初始化钩子应用此设置,因此上游浏览器工具 的架构保持不变。
有关配置示例、 运行时可流式传输的 HTTP 元数据、用例及限制,请参阅 人性化输入行为。
Chrome 扩展¶
Chrome 扩展会在浏览器启动时加载,因此请在启动桥接器之前,或在创建 Streamable HTTP 会话之前完成配置。扩展必须是已解压的目录,并且需要 持久化配置文件:
PLAYWRIGHT_MCP_USER_DATA_DIR="$PWD/.profiles/default" \
CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS='["/absolute/path/to/my-extension"]' \
npx -y cloakbrowser-mcp@latest
对于 Streamable HTTP,请在 initialize 元数据中传入配置文件目录和扩展 目录:
{
"params": {
"_meta": {
"io.github.swimmwatch/cloakbrowser-mcp": {
"userDataDir": "/absolute/path/to/profile",
"extensionPaths": ["/absolute/path/to/my-extension"]
}
}
}
}
更改扩展文件或扩展路径后,请重启桥接器或创建新的 HTTP 会话。当路径包含 逗号、传入多个扩展,或使用带盘符的 Windows 路径时,请为 CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS 使用 JSON 数组。
简短的可复制配置示例请参阅加载 Chrome 扩展。
Playwright Extension 连接模式¶
Playwright Extension 连接模式与通过 CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS 加载未打包扩展是两种不同的机制。该模式通过 Chrome 或 Edge 配置文件中已经安装的官方 Playwright Extension 建立连接;桥接器不会安装该扩展。
使用 stdio 时,配置进程环境变量:
PLAYWRIGHT_MCP_EXTENSION=true \
PLAYWRIGHT_MCP_EXTENSION_TOKEN='<secret-from-the-extension>' \
PLAYWRIGHT_MCP_USER_DATA_DIR="$PWD/.profiles/playwright-extension" \
PLAYWRIGHT_MCP_PROFILE_DIR_NAME='Profile 1' \
npx -y cloakbrowser-mcp@latest
使用 Streamable HTTP 时,initialize 元数据中的 extensionMode 和 profileDirName 会覆盖对应的进程级设置。userDataDir 也按会话指定。令牌仍只能通过进程环境变量提供:
{
"params": {
"_meta": {
"io.github.swimmwatch/cloakbrowser-mcp": {
"extensionMode": true,
"profileDirName": "Profile 1",
"userDataDir": "/absolute/path/to/profile"
}
}
}
}
扩展模式要求非空令牌和持久化配置文件。并发的 HTTP 扩展会话必须使用不同的 userDataDir。启动上游子进程前,桥接器会拒绝以下配置:托管或外部 CDP 端点、远程浏览器端点、无头或隔离启动配置、代理和 GeoIP 选项、类人操作、上下文修改、未打包扩展的 extensionPaths,以及显式提供的 CloakBrowser 启动选项。成功连接的端到端验证需要手动进行,因为所选浏览器配置文件中必须已经安装官方 Playwright Extension。
可流式传输的 HTTP 运行时元数据¶
支持流式传输的 HTTP 客户端可以通过在 initialize 请求中添加 特定于桥接器的元数据,为每个 MCP 会话选择相应的运行时选项:
{
"params": {
"_meta": {
"io.github.swimmwatch/cloakbrowser-mcp": {
"proxyServer": "http://user:pass@proxy.example:8080",
"proxyBypass": ".internal,localhost",
"geoipProxyMatch": true,
"headless": false,
"extensionMode": false,
"profileDirName": "Profile 1",
"humanize": true,
"humanPreset": "careful",
"userDataDir": "/absolute/path/to/profile",
"contextOptions": {
"viewport": { "width": 1280, "height": 720 },
"locale": "en-US",
"timezoneId": "America/New_York"
},
"extensionPaths": ["/absolute/path/to/extension"]
}
}
}
}
proxyServer 在该 HTTP 会话中覆盖了 PLAYWRIGHT_MCP_PROXY_SERVER。 proxyBypass 仅在存在 proxyServer 时,才覆盖 PLAYWRIGHT_MCP_PROXY_BYPASS,但仅当 proxyServer 存在时 才生效。 geoipProxyMatch 可在无需重启 MCP 服务器的情况下, 启用或禁用该会话的 GeoIP 匹配功能。现有会话将保留其初始代理; 需创建新的 HTTP 会话才能切换位置。
humanize 可以为该会话启用或禁用人性化输入行为, 而不会影响其他会话。 humanPreset 可为该会话选择 default 或 careful ,但本身不会启用人性化行为。 现有 会话将保留在 initialize 期间捕获的行为。
headless 可按会话启用或禁用无头浏览器模式。在 Docker 镜像中,设置 headless 为 false 会按需启动容器私有的虚拟显示。在镜像之外,有头会话仍需要可用的显示环境。
extensionMode 和 profileDirName 会覆盖该会话的 PLAYWRIGHT_MCP_EXTENSION 和 PLAYWRIGHT_MCP_PROFILE_DIR_NAME。元数据绝不接受 PLAYWRIGHT_MCP_EXTENSION_TOKEN。
userDataDir 为该会话启用持久化 Chromium 配置文件,并覆盖 PLAYWRIGHT_MCP_USER_DATA_DIR。桥接器会将目录解析为平台原生绝对路径, 在缺失时创建它,验证其可写,并写入生成的 browser.userDataDir。 持久化配置文件会禁用该会话默认的 Streamable HTTP 隔离配置文件。桥接器会拒绝同一进程内以及同一进程 ID 命名空间中不同进程之间对同一配置文件目录的重复活动使用。锁恢复方式及其限制见持久登录配置文件。
contextOptions 会经过验证,并在 CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS 之上进行浅合并;嵌套对象会整体替换。支持的字段为 userAgent、 viewport、locale、timezoneId、colorScheme、permissions、 geolocation、extraHTTPHeaders、httpCredentials、ignoreHTTPSErrors、 offline、deviceScaleFactor、isMobile 和 hasTouch。本版本不支持任意 传递 BrowserContextOptions。
extensionPaths 必须指向现有目录,并且需要持久化的 userDataDir。 桥接器会将扩展路径解析为平台原生绝对路径,传给 CloakBrowser,并把生成的 Chromium 参数 --load-extension 和 --disable-extensions-except 写入生成的 Playwright MCP 配置。
经过身份验证的 HTTP 代理凭据可以嵌入到 proxyServer 中,例如 http://user:pass@proxy.example:8080。对具有 URL 含义的凭据 字符进行百分比编码,例如 @、 :、/、 ?、 #,以及 %。
对于受支持的 CloakBrowser 二进制文件,经过身份验证的 HTTP 代理会使用原生 URL 内联身份验证,桥接器则会移除重复的 Playwright 代理对象。较旧的二进制文件会保留 Playwright 代理对象作为兼容性回退。
有关多地点质量保证模式,请参阅 GeoIP 代理匹配。 有关交互真实性模式,请参阅 人性化输入行为。
登录状态复用和扩展配置请参阅持久化登录配置文件和加载 Chrome 扩展。
上游选项¶
该桥接器将 PLAYWRIGHT_MCP_* 的设置转发给上游的 Playwright MCP。其中包括以下上游选项:
PLAYWRIGHT_MCP_ALLOWED_ORIGINSPLAYWRIGHT_MCP_BLOCKED_ORIGINSPLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESSPLAYWRIGHT_MCP_CAPSPLAYWRIGHT_MCP_CONSOLE_LEVELPLAYWRIGHT_MCP_FILE_PATHSPLAYWRIGHT_MCP_IDLE_TIMEOUTPLAYWRIGHT_MCP_IMAGE_RESPONSESPLAYWRIGHT_MCP_PROFILE_DIR_NAMEPLAYWRIGHT_MCP_SNAPSHOT_MODEPLAYWRIGHT_MCP_STORAGE_STATEPLAYWRIGHT_MCP_WEBMCP
有关完整的上游选项列表,请参阅上游 Playwright MCP 文档。
PLAYWRIGHT_MCP_CAPS=devtools 会由上游子进程继承,并启用该能力控制的 工具,无需桥接专用的 --caps 标志。
日志记录¶
可流式传输的 HTTP 模式会将易于人类阅读的启动和请求日志写入 stdout。Stdio 模式不会输出常规操作日志,因此 MCP JSON-RPC 的 stdout 保持协议纯净。命令行界面(CLI)启动时的致命错误仍会写入 stderr。
HTTPS¶
Streamable HTTP 默认使用本地 HTTP。若要选择直接 TLS,请使用 --http-protocol https 或 CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL=https 选择“直接 TLS”模式,然后提供证书/密钥对或 PFX 文件:
cloakbrowser-mcp --transport streamable-http \
--http-protocol https \
--https-cert ./cert.pem \
--https-key ./key.pem
对于外部或非回环暴露,请使用 HTTPS 并配合 --http-auth-token,或者在可信的反向代理上终止 TLS,该代理还应强制执行身份验证和网络访问控制。
可流式传输的 HTTP 会话¶
每个 Streamable HTTP MCP 会话都有独立的桥接运行时和上游 Playwright MCP 子进程。未配置持久化配置文件时,HTTP 会话默认使用隔离的浏览器配置文件。显式持久化配置文件会被锁定,并发会话需要不同的配置文件目录。内置 memory 后端仅保存会话 ID、时间戳、过期时间和状态等元数据。浏览器状态保留在活动的上游子进程中,产物仍由 PLAYWRIGHT_MCP_OUTPUT_DIR 控制。
对于水平扩展,请在负载均衡器后运行多个服务器副本,并使用以 mcp-session-id 头为键的粘性会话。 未来的 Redis、Postgres 或 SQLite 后端可以协调元数据和锁,但当拥有该会话的进程退出后,它们无法恢复正在运行的浏览器会话。
可流式传输的 HTTP 探针¶
当桥接器运行时,若使用 --transport streamable-http,它会在与 MCP 端点相同的主机和端口上暴露固定的探针端点:
GET /healthz返回进程健康状况元数据:status、version、transport,以及uptimeMs。GET /readyz返回就绪状态元数据和会话容量:sessions.active、sessions.pending、sessions.max以及sessions.available。
当会话容量可用时,就绪状态返回 HTTP 200,而当 503,而当 active + pending >= max 时则返回 active + pending >= max。 如果配置了 --http-auth-token 或 CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN 已配置,则这两个探针都需要与 MCP 请求相同的 Authorization: Bearer ... 标头。 如果没有身份验证令牌,探针将在配置的 HTTP 绑定地址上保持开放状态。
更多实用路径¶
要在 upstream Playwright MCP 和本包之间选择,请查看对比。快速任务请使用操作示例:持久配置文件、扩展、reverse proxy、区域 QA、Claude Desktop、Codex CLI 和 CI 冒烟测试。