Fayeblade MCP

🚀 Venice Browser MCP Bridge

このプロジェクトは、stdin/stdout を介してJSON-RPCに似たプロトコルを使用する小型で実用的なブラウザブリッジです。Playwrightを利用して、ブラウザの自動化を行います。

🚀 クイックスタート

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

✨ 主な機能

• 2種類のトランスポートフレーマーをサポート: line (デフォルト) と content-length。
• Playwrightを使用したブラウザの自動化。
• シングルな永続的なコンテキストを使用したブラウザ操作 (オプションでクッキー/セッション状態を保持)。
• asyncio.StreamWriter の問題を回避するための安全なライター実装。

📦 インストール

仮想環境の作成

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

依存関係のインストール

pip install -r requirements.txt
playwright install chromium

💻 使用例

基本的な使用法

make run-line
make test-line

高度な使用法

Content-Length 区切りを使用する場合:

make run-cl    # ターミナルA
make test-cl   # ターミナルB

📚 ドキュメント

リポジトリの構成

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

設定

ブリッジは環境変数を介して設定されます。初心者向けに適切なデフォルト値が選択されています。

⚠️ 重要提示

すべてのログは stderr に出力されます。stdoutにプロトコル以外のテキストを出力しないでください。そうしないと、トランスポートが破損します。

RPCメソッド

• browser.navigate — { "url": "https://example.com" }
  単一のページを開き、ナビゲートし、{ ok, status, final_url, title } を返します。
• ping — { "echo": "value" }
  クイックチェックのために { "echo": "value" } を返します。
• mcp.shutdown — パラメータなし。
  ブラウザを正常に閉じ、メインループを終了します。

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 で再インストールするか、zipファイルを再抽出してください。

2) json.decoder.JSONDecodeError: Extra data

原因: stdoutにJSON以外の行を出力した (例: 他のツールからの印刷や警告)。
解決策: すべての診断情報を stderr に出力するようにしてください。Pythonでは print("dbg", file=sys.stderr, flush=True) を使用します。

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

原因: ホストがJSON行を期待したが、空または不正なデータを受け取った。通常は子プロセスがJSONの前にバナーをstdoutに出力したため。
解決策: 上記と同じで、stdoutを純粋なプロトコルに保ちます。また、フレーミングモードが一致していることを確認してください (ホストとブリッジ)。

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

原因: ブラウザをインストールし忘れた。
解決策: playwright install chromium (または BROWSER を変更した場合は firefox / webkit)。

5) ヘッドレスモードは動作するが、クッキーの永続化 / “ログイン済み” 状態が必要な場合

• MCP_STORAGE_STATE=state.json (デフォルトですでに設定されています) を設定します。
• HEADLESS=false で一度ログインしてから閉じます。その後のセッションではその状態が再利用されます。

6) 企業のプロキシ、奇妙なTTY、またはPTYの問題

ホストがPTYまたはパイプではないstdoutを使用する場合、行バッファリングがうまくいかないことがあります。パイプでブリッジを起動し、クリーンに通信するサンプルホストを使用することをお勧めします。

🔧 技術詳細

• 両方のフレーマーは含まれるホストで検証されています。
• stdoutにログを出力せず、メッセージごとにアトミックなフラッシュを行います。
• シングルなPlaywrightコンテキストが呼び出し間で再利用され、オプションで永続化が有効になっています。
• ナビゲーションに明示的なタイムアウトが設定されています。

📄 ライセンス

このプロジェクトのライセンスについては、LICENSE ファイルを参照してください。