fayeblade_mcp

🚀 威尼斯浏览器MCP桥

威尼斯浏览器MCP桥是一个轻量级、适用于生产环境的浏览器桥接工具，它通过标准输入/输出使用类似JSON - RPC的协议进行通信。该工具支持两种传输帧格式，使用Playwright实现真实浏览器自动化，并对常见的编程陷阱进行了优化。

✨ 主要特性

• 双传输帧格式支持：默认支持line（每行一个JSON消息）和content - length（类似HTTP的Content - Length: N帧消息）两种传输帧格式，分别适用于快速原型开发和严格的MCP主机。
• Playwright自动化：利用Playwright实现真实浏览器自动化，支持单持久上下文（可选的cookie/会话状态）。
• 避免常见陷阱：通过自定义的写入器实现，避免了asyncio.StreamWriter(sys.stdout, ...)的常见问题，如避免向标准输出日志记录、防止协议不匹配，并能按消息进行干净的刷新。

🚀 快速开始

1) 创建隔离环境（推荐）

python3 -m venv .venv && source .venv/bin/activate

2) 安装依赖

pip install -r requirements.txt
playwright install chromium

3) 运行桥接工具（默认使用行帧格式）

make run-line

在另一个终端中，运行示例主机：

make test-line

预期输出如下：

Navigate...
{"id":"nav-1","result":{"ok":true,"final_url":"https://example.com/","title":"Example Domain"}}

要使用Content - Length帧格式：

make run-cl    # 终端A
make test-cl   # 终端B

📦 安装指南

按照快速开始部分的步骤，依次创建隔离环境、安装依赖并运行桥接工具即可完成安装和启动。

💻 使用示例

基础用法

在快速开始部分已经展示了基础的使用方法，通过make run-line或make run-cl启动桥接工具，然后使用make test-line或make test-cl运行示例主机进行测试。

📚 详细文档

仓库布局

venice-browser-mcp/
├─ src/
│  ├─ venice_browser_mcp.py             # 入口点
│  ├─ venice_browser_mcp_core.py        # 环境配置
│  └─ venice_browser_mcp_v23_impl.py    # 帧格式 + 浏览器逻辑（已修补）
├─ examples/
│  ├─ line_host.py                      # 启动桥接工具（行帧格式）并发送请求
│  └─ hard_mcp_host.py                  # 启动桥接工具（Content - Length帧格式）并发送请求
├─ docs/
│  ├─ ARCHITECTURE.md
│  └─ TROUBLESHOOTING.md
├─ Makefile
├─ requirements.txt
├─ .gitignore
├─ LICENSE
└─ README.md

配置

桥接工具通过环境变量进行配置，为新手选择了合理的默认值。 | 属性 | 详情 | |------|------| | MCP_FRAMING | line或content - length | 默认line | | HEADLESS | Playwright的true或false | 默认true | | MCP_STORAGE_STATE | 用于持久会话的storage_state JSON文件路径 | 默认state.json | | NAV_TIMEOUT | 导航超时时间（毫秒） | 默认30000 | | BROWSER | 浏览器名称chromium | firefox | webkit | 默认chromium |

⚠️ 重要提示

所有日志都输出到标准错误输出。切勿将非协议文本打印到标准输出，否则会破坏传输。

RPC方法

• browser.navigate — { "url": "https://example.com" }
  打开/使用单个页面，进行导航，返回{ ok, status, final_url, title }。
• ping — { "echo": "value" }
  用于快速检查，返回{ "echo": "value" }。
• mcp.shutdown — 无参数。
  优雅地关闭浏览器并退出主循环。

你可以在venice_browser_mcp_v23_impl.py的dispatch()函数中添加更多处理程序。

Makefile目标

• make install — 安装Python依赖和Playwright浏览器
• make run-line — 以行模式运行桥接工具（前台）
• make run-cl — 以Content - Length模式运行桥接工具（前台）
• make test-line — 运行行模式的示例主机
• make test-cl — 运行Content - Length模式的示例主机
• make fmt — 基本的Python格式化（通过python -m json.tool检查和清理空白）
• make clean — 删除缓存/工件

🔧 技术细节

常见问题排查

1) 崩溃：AssertionError或'Protocol' object has no attribute '_drain_helper'

原因：asyncio.StreamWriter构造不正确（常见陷阱）。
解决方法：本仓库不使用该模式，而是使用安全的写入器。确保你运行的是这些源代码，而不是未修补的文件。使用git clean -xfd重新安装或重新解压压缩包。

2) json.decoder.JSONDecodeError: Extra data

原因：你向标准输出泄露了非JSON行（例如，打印信息、其他工具的警告）。
解决方法：确保所有诊断信息都输出到标准错误输出。在Python中：print("dbg", file=sys.stderr, flush=True)。

3) Expecting value: line 1 column 1 (char 0)

原因：主机期望一个JSON行，但得到了空值/垃圾数据，通常是因为子进程在JSON之前向标准输出打印了横幅信息。
解决方法：同上，保持标准输出仅包含协议内容。同时验证你的帧模式是否匹配（主机与桥接工具）。

4) playwright._impl._errors.Error: BrowserType.launch: Executable doesn't exist

原因：你忘记安装浏览器。
解决方法：playwright install chromium（如果你更改了BROWSER，则安装firefox / webkit）。

5) 无头模式可以工作，但你需要cookie持久化/“登录”状态

• 设置MCP_STORAGE_STATE=state.json（默认已经设置）。
• 使用HEADLESS=false登录一次，然后关闭。后续会话将重用该状态。

6) 公司代理、奇怪的TTY或PTY问题

如果主机使用PTY或非管道标准输出，行缓冲可能会出现故障。建议使用包含的示例主机，它们通过管道生成桥接工具并进行干净的通信。

📄 许可证

本项目的许可证信息请查看仓库中的LICENSE文件。

🔧 安全说明

• 本项目是一个工具桥接工具，它不会绕过Web/应用程序认证，也不包含漏洞利用逻辑。
• 如果你扩展它，请将日志记录到标准错误输出，并在调用shell或导航到用户提供的URL时对输入进行清理。
• 对于红队实验：保持其抽象性和非操作性，不要自动化有害行为。

🔧 完整性检查

• 两种帧格式都通过了包含的主机验证。
• 不进行标准输出日志记录，每条消息原子刷新。
• 跨调用重用单个Playwright上下文，启用可选的持久性。
• 导航有明确的超时设置。