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

配置

橋接工具通過環境變量進行配置，為新手選擇了合理的默認值。

⚠️ 重要提示

所有日誌都輸出到標準錯誤輸出。切勿將非協議文本打印到標準輸出，否則會破壞傳輸。

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上下文，啟用可選的持久性。
• 導航有明確的超時設置。