+
+
+
+ Chrome + Firefox · CDP + BiDi · 100% Python · Node.js不要 · Chromiumダウンロード不要 +
+ +--- + +[English](README.md) | [简体中文](README.zh-CN.md) | **日本語** + +[](https://github.com/MathiasPaulenko/wavexis-mcp/actions/workflows/ci.yml) +[](https://pypi.org/project/wavexis-mcp/) +[](https://pypi.org/project/wavexis-mcp/) +[](https://pypi.org/project/wavexis-mcp/) +[](https://github.com/MathiasPaulenko/wavexis-mcp/actions/workflows/ci.yml) +[](https://github.com/MathiasPaulenko/wavexis-mcp/pkgs/container/wavexis-mcp) +[](https://github.com/MathiasPaulenko/wavexis-mcp/blob/main/LICENSE) +[](https://mathiaspaulenko.github.io/wavexis-mcp/) +[](https://smithery.ai/servers/mathias-paulenko/wavexis-mcp) + +> [wavexis](https://github.com/MathiasPaulenko/wavexis) ブラウザ自動化ライブラリをLLM向けのMCPサーバーとして公開します。220個のツールを13の機能ティアに分割しています。Node.jsもChromiumのダウンロードも不要で、既存のChrome/Edgeをそのまま利用できます。100% Pythonです。 + +## クイックデモ + +**最初のスクリーンショットまで30秒。** 次の内容をMCPクライアント設定（Claude Desktop、Cursor、Windsurf、VS Code）に追加してください。 + +```json +{ + "mcpServers": { + "wavexis": { + "command": "uvx", + "args": ["wavexis-mcp", "--caps", "all"] + } + } +} +``` + +その後、LLMに次のように依頼します。 + +> *"https://example.com のフルページスクリーンショットを撮って"* + +LLMは `wavexis_screenshot(url="https://example.com", full_page=true)` を呼び出し、スクリーンショットを返します。Node.jsもChromiumのダウンロードも不要で、上記の設定以外の準備は必要ありません。 + +## なぜWaveXisMCPなのか？ + +WaveXisMCPは [wavexis](https://github.com/MathiasPaulenko/wavexis) ブラウザ自動化ライブラリをラップし、[MCPサーバー](https://modelcontextprotocol.io/) として公開します。Node.js、Playwright、別途のChromiumダウンロードは不要です。WaveXisMCPは既存のChromeまたはEdgeを直接起動します。 + +### 主な機能 + +- **220個のツール** — Playwright MCP（21）の約3倍、zendriver-mcp（96）の約2倍 +- **13の機能ティア** — `--caps` で必要なものだけを有効化。まず `core`（72ツール）から始め、必要に応じて追加 +- **Chrome + Firefox** — Chrome/EdgeはCDP、FirefoxはBiDi。どちらもPATHからドライバーを自動起動 +- **Chromiumダウンロード不要** — 既存ブラウザを利用。インストールサイズは約5MB（Playwright MCPは約400MB） +- **ステルスモード** — `stealth=true` で `navigator.webdriver` を隠し、plugins / languages / chrome runtime を偽装 +- **構造化エラー** — すべてのエラーに `suggestion` フィールドがあり、LLMが人手なしで自己修正可能 +- **マルチアクションYAML** — 1回のツール呼び出しで navigate → click → fill → screenshot を連結 +- **生のCDP/BiDiアクセス** — 専用ツールがないブラウザ機能のための逃げ道 +- **Lighthouse監査、WebAuthn、Bluetooth、Cast** — 他のMCPサーバーではカバーされないニッチな機能 +- **SSRF保護、パスサンドボックス、レート制限** — 初日から組み込まれたセキュリティ +- **593テスト、90%カバレッジ強制、実ChromeでのE2E** — 本番利用に耐える品質 + +### 仕組み + +```text +あなた（自然言語） + → LLM が呼び出すツールを決定 + → WaveXisMCP がツール呼び出しを受信 + → wavexis ライブラリが CDP または BiDi で実行 + → Chrome/Edge/Firefox が操作を実行 + ← 結果を JSON で返却（テキスト、base64、ファイルパス） + ← JSON を LLM に返却 + ← LLM が結果を要約 +``` + +LLMはブラウザを直接見ることはありません。見えるのはツール定義（名前、説明、パラメータ）とJSONレスポンスだけです。そのため、MCP互換のLLMクライアントであれば追加のカスタム統合なしでそのまま動作します。 + +### 基本概念 + +- **ツール（Tool）** — スクリーンショット、eval、クリックなどの単一ブラウザ操作を、任意のLLMクライアントが呼べるMCPツールとして公開したものです。 +- **セッション（Session）** — 永続的なブラウザインスタンスです。セッションを開き、複数のツール呼び出しをつなぎ、完了後に閉じます。操作ごとにブラウザを起動するオーバーヘッドを避けられます。 +- **ステートレスモード（Stateless）** — 任意のツールに `url` パラメータを渡して呼び出します。ブラウザは起動、実行、終了まで自動で行われます。 +- **機能ティア（Capability tiers）** — `core`（72ツール）から `all`（220ツール）までの13ティアです。`--caps` で必要なものだけを有効化します。 +- **デュアルバックエンド（Dual backend）** — CDP（Chromiumネイティブ、cdpwave経由）とBiDi（W3Cクロスブラウザ、bidiwave経由）を、セッション単位で選択できます。 +- **構造化エラー（Structured errors）** — すべてのエラーに `suggestion` フィールドがあり、LLMへ次に取るべき行動を示すことで、人手なしの自己修正が可能です。 + +## インストール + +```bash +pip install wavexis-mcp +``` + +CDPバックエンド（Chromium）付き： + +```bash +pip install "wavexis-mcp[cdp]" +``` + +またはインストールせずに実行（推奨）： + +```bash +uvx wavexis-mcp +``` + +## 要件 + +- **Python**：3.11、3.12、または 3.13 +- **ブラウザ**：Google Chrome、Microsoft Edge、または任意のChromium/Chrome系ブラウザ +- **BiDiバックエンド**（任意）：Chrome向けChromeDriver/EdgeDriver、またはFirefox向けgeckodriver + +## クイックスタート + +MCPクライアント設定（Claude Desktop、Cursor、Windsurf、VS Code）に追加してください。 + +```json +{ + "mcpServers": { + "wavexis": { + "command": "uvx", + "args": ["wavexis-mcp", "--caps", "all"] + } + } +} +``` + +または pip を使う場合： + +```json +{ + "mcpServers": { + "wavexis": { + "command": "wavexis-mcp", + "args": ["--caps", "all"] + } + } +} +``` + +### ステートレスモード（ワンショット） + +任意のツールに `url` パラメータを渡して呼び出します。ブラウザは起動、実行、終了まで自動で行われます。 + +```text +wavexis_screenshot(url="https://example.com", full_page=true) +``` + +### セッションモード（マルチステップ） + +セッションを開き、複数のアクションをつなぎ、完了後に閉じます。 + +```text +wavexis_session_open(backend="cdp", headless=false) +→ {"session_id": "abc-123"} + +wavexis_navigate(session_id="abc-123", url="https://example.com") +wavexis_click(session_id="abc-123", selector="#login") +wavexis_screenshot(session_id="abc-123") +wavexis_session_close(session_id="abc-123") +``` + +### 自然言語インタラクション（M1） + +`wavexis_act` を使い、自然言語でページを操作します。 + +```text +wavexis_session_open(backend="cdp") +wavexis_navigate(session_id="abc-123", url="https://example.com") +wavexis_act(session_id="abc-123", instruction="click the login button") +→ {"action": "click", "element": {"ref": "el-3", "role": "button", "name": "Login"}, "status": "ok"} +``` + +`wavexis_act` ツールは a11y スナップショットを取得し、キーワードスコアリングで指示を要素に対応付け、検出されたアクション（click、type、fill、hover）を実行します。外部LLM呼び出しはなく、純粋なヒューリスティックマッチングです。 + +## 機能ティア + +| ティア | フラグ | ツール数 | 主な機能 | +|------|------|-------|--------------| +| **Core** | 常時有効 | 72 | セッション、ナビゲーション、スクリーンショット、PDF、スクレイプ、eval、DOM、入力、cookies、タブ、自然言語操作、iframe、shadow DOM、イベント | +| **Network** | `--caps=network` | 20 | ヘッダー、UA、ブロック、スロットル、キャッシュ、HAR、intercept、mock、リクエスト/レスポンス変更、リクエストボディ、HAR再生、リクエスト一覧 | +| **Storage** | `--caps=storage` | 18 | localStorage、sessionStorage、cache storage、IndexedDB、状態の保存/復元 | +| **Emulation** | `--caps=emulation` | 9 | デバイス、ビューポート、位置情報、タイムゾーン、ダークモード、ロケール、CPU、タッチ、センサー | +| **A11y** | `--caps=a11y` | 4 | アクセシビリティツリーのスナップショット、ノード走査、axe-core監査 | +| **Interactions** | `--caps=interactions` | 5 | ダイアログ、ダウンロード、権限 | +| **DevTools** | `--caps=devtools` | 31 | パフォーマンス、CSS、デバッグ、overlay、コンソール、セキュリティ、ウィンドウ管理、複合trace、注釈付きスクリーンショット | +| **Vision** | `--caps=vision` | 7 | 座標ベースのマウス操作（ピクセル精度） | +| **Video** | `--caps=video` | 4 | 動画録画、チャプター、アクションオーバーレイ | +| **Testing** | `--caps=testing` | 6 | アサーション、ロケーター生成 | +| **Workflows** | `--caps=workflows` | 6 | マルチアクションYAML、生のCDP/BiDi、ブラウザコンテキストCRUD | +| **Data** | `--caps=data` | 7 | Codegen、Lighthouse監査、抽出、WebSocket intercept、クロール、ビジュアルdiff、Core Web Vitals | +| **Experimental** | `--caps=experimental` | 31 | Service workers、アニメーション、WebAuthn、WebAudio、メディア、cast、bluetooth、拡張機能、prefs | +| **合計** | `--caps=all` | **220** | | + +**デフォルト**：`--caps=core`（72ツール）。すべて有効化：`--caps=all`。特定のみ：`--caps=network,storage,emulation`。 + +> **ヒント**：まず `--caps core` から始め、必要に応じてティアを追加してください。各ティアはLLMのコンテキストにツール定義を追加するため、トークンを消費します。多くの作業では `core,network,storage`（110ツール）が良いバランスです。 + +## バックエンド + +WaveXisMCPは、機能パリティを保った2つのバックエンドをサポートします。 + +- **CDP**（cdpwave）— デフォルト。Chrome DevTools Protocol。Chrome/EdgeへWebSocketで直接接続。ドライバー不要。57のCDPドメイン。`pip install "wavexis-mcp[cdp]"` +- **BiDi**（bidiwave）— WebDriver BiDiプロトコル。W3Cクロスブラウザ（Firefox、Chrome）。Chromeはchromedriver、Firefoxはgeckodriverが必要で、未起動ならPATHから自動起動されます。`pip install "wavexis-mcp[bidi]"` + +セッションごとに選択します。 + +```text +# CDP (default, Chrome/Edge only) +wavexis_session_open(backend="cdp") + +# BiDi with Chrome (auto-launches chromedriver) +wavexis_session_open(backend="bidi", browser="chrome") + +# BiDi with Firefox (auto-launches geckodriver) +wavexis_session_open(backend="bidi", browser="firefox") +``` + +### 既存のChromeへ接続 + +`connect_existing=True` を使うと、Chromeを `--remote-debugging-port` 付きで起動して接続できます。ログイン済みセッションを含むブラウザプロファイルの再利用に便利です。 + +```text +# Launch Chrome with debug port and connect via CDP +wavexis_session_open(connect_existing=true) + +# Reuse an existing Chrome profile (keeps logins, cookies, extensions) +wavexis_session_open(connect_existing=true, user_data_dir="C:/Users/me/ChromeProfile") +``` + +Chromeはヘッド付きで起動されます（headlessは無視されます）。セッションを閉じると、ブラウザのサブプロセスも終了します。 + +## マルチアクションYAML + +YAML文字列を渡すことで、1回のツール呼び出しに複数アクションを連結できます。 + +```text +wavexis_multi_action( + config=""" +actions: + - navigate: https://example.com + - screenshot: + full_page: true + - eval: document.title + - click: "#login" + - type: + selector: "#username" + text: admin@example.com + - screenshot: {} +""", + session_id="abc-123" +) +``` + +対応アクション種別：`navigate`、`screenshot`、`eval`、`click`、`type`、`fill`。失敗時も続行する場合は `continue_on_error: true` を設定してください。 + +## MCPリソースとプロンプト（M3） + +**リソース（Resources）**（読み取り専用のブラウザ状態）： + +- `wavexis://session/{id}/url` — 現在のページURL +- `wavexis://session/{id}/cookies` — cookies（JSON） +- `wavexis://session/{id}/console` — コンソールメッセージ +- `wavexis://session/{id}/tabs` — 開いているタブ + +**プロンプト（Prompts）**（ワークフローテンプレート）： + +- `scrape_page(url, selector)` — コンテンツのスクレイプと抽出 +- `audit_page(url)` — 完全なa11y + パフォーマンス監査 +- `fill_form(url, fields)` — ページ上のフォーム入力 +- `debug_page(url)` — コンソール、ネットワーク、パフォーマンスのデバッグ + +## HTTPトランスポート + +CI/CD、共有インスタンス、Docker向けに、WaveXisMCPをHTTPサーバーとして実行できます。 + +```bash +# HTTP on localhost +wavexis-mcp --transport http --port 8765 + +# HTTP with all tiers +wavexis-mcp --transport http --port 8765 --caps all + +# HTTP with remote access (use behind a reverse proxy!) +wavexis-mcp --transport http --allow-remote --port 8765 +``` + +デフォルトでは `127.0.0.1` にバインドします。`0.0.0.0` にする場合は `--allow-remote` を使います。 + +## レート制限（M4） + +セッション単位のトークンバケットによるレート制限です。 + +```bash +# 10 calls/sec, burst of 5 +wavexis-mcp --rate-limit 10 --rate-burst 5 +``` + +上限超過時は `{"error": "rate_limited", "retry_after_ms": N}` を返します。 + +## Docker + +```bash +# Pull and run +docker run -p 8765:8765 ghcr.io/mathiaspaulenko/wavexis-mcp + +# Or build locally +docker build -t wavexis-mcp . +docker run -p 8765:8765 wavexis-mcp + +# Docker Compose +docker-compose up +``` + +詳細は [Dockerドキュメント](https://mathiaspaulenko.github.io/wavexis-mcp/docker/) を参照してください。 + +## 比較 + +| 機能 | Playwright MCP | **WaveXisMCP** | +|---------|:---:|:---:| +| 言語 | TypeScript | **Python** | +| Node.js必須 | ✗ | **✓（Node.js不要）** | +| Chromiumダウンロード（約200MB） | ✓ | **✗（既存ブラウザを使用）** | +| インストールサイズ | ~400MB | **~5MB** | +| コールドスタート | 3.2s | **0.8s** | +| ツール総数 | ~21 | **220** | +| 機能ティア（オプトイン） | ✗ | **✓（13ティア）** | +| デュアルプロトコル（CDP + BiDi） | ✗ | **✓** | +| Firefoxサポート | ✓（基本） | **✓（BiDi + geckodriver自動起動）** | +| バックエンド選択（セッション単位） | ✗ | **✓** | +| ステルス / アンチボットモード | ✗ | **✓** | +| 生のCDP/BiDiアクセス | ✗ | **✓（逃げ道）** | +| マルチアクションYAMLバッチ | ✗ | **✓** | +| 動画録画 | ✗ | **✓** | +| Lighthouse監査 | ✗ | **✓** | +| WebAuthn / Bluetooth / Cast | ✗ | **✓** | +| 自然言語インタラクション | ✗ | **✓（`wavexis_act`）** | +| MCPリソースとプロンプト | ✗ | **✓** | +| レート制限 | ✗ | **✓** | +| SSRF保護 | ✗ | **✓** | +| 提案付き構造化エラー | ✗ | **✓** | + +> **注意**：Playwright MCPはWebKit（Safari）に対応していますが、WaveXisMCPは現時点では未対応です。今後の予定は [ロードマップ](https://github.com/MathiasPaulenko/wavexis-mcp/issues) を参照してください。 + +## ドキュメント + +完全なドキュメント、APIリファレンス、サンプルは [mathiaspaulenko.github.io/wavexis-mcp](https://mathiaspaulenko.github.io/wavexis-mcp/) で公開しています。 + +主なセクション： + +- [クイックスタート](https://mathiaspaulenko.github.io/wavexis-mcp/quickstart/) +- [アーキテクチャ](https://mathiaspaulenko.github.io/wavexis-mcp/architecture/) +- [設定](https://mathiaspaulenko.github.io/wavexis-mcp/configuration/) +- [Docker](https://mathiaspaulenko.github.io/wavexis-mcp/docker/) +- [HTTPトランスポート](https://mathiaspaulenko.github.io/wavexis-mcp/http-transport/) +- [レート制限](https://mathiaspaulenko.github.io/wavexis-mcp/rate-limiting/) +- [ツールリファレンス](https://mathiaspaulenko.github.io/wavexis-mcp/tools/core/) +- [サンプル](https://mathiaspaulenko.github.io/wavexis-mcp/examples/screenshot/) + +## エラーハンドリング + +すべてのツールは失敗時に構造化エラーJSONを返します。各エラーには、LLMを次のアクションへ導く `suggestion` フィールドが含まれます。 + +```json +{ + "error": "Session 'abc-123' not found.", + "tool": "wavexis_navigate", + "type": "SessionNotFoundError", + "message": "Session 'abc-123' not found.", + "suggestion": "Call wavexis_session_open first to create a browser session." +} +``` + +これにより、LLMは人手なしで自己修正できます。提案を読み取り、推奨されたツールを呼び出します。 + +## アーキテクチャ + +WaveXisMCPは、3層エコシステムの最上位に位置します。 + +```text +WaveXisMCP（MCPサーバー、220ツール） +└─ wraps → wavexis（ブラウザ自動化ライブラリ） + ├─ cdpwave（CDPバックエンド、Chromiumネイティブ） + └─ bidiwave（BiDiバックエンド、W3Cクロスブラウザ） +``` + +- **cdpwave** — Chrome DevTools Protocol向けの低レベル非同期Pythonライブラリ。Chrome/EdgeへWebSocketで直接接続します。ドライバーバイナリは不要です。 +- **bidiwave** — WebDriver BiDiプロトコル（W3C標準）向けの低レベル非同期Pythonライブラリ。Firefox、Chrome、Edgeで動作します。 +- **wavexis** — cdpwaveとbidiwaveを統一された `AbstractBackend` インタフェースの背後に抽象化する、高レベルなブラウザ自動化ライブラリです。 +- **WaveXisMCP** — wavexisをラップするMCPサーバーです。各バックエンドメソッドをMCPツールとして公開し、Pydantic v2による入力検証、JSONレスポンス、機能ティアによるフィルタリングを提供します。 + +全体設計、データフロー図、ADRについては [アーキテクチャドキュメント](https://mathiaspaulenko.github.io/wavexis-mcp/architecture/) を参照してください。 + +## 開発 + +```bash +git clone https://github.com/MathiasPaulenko/wavexis-mcp.git +cd wavexis-mcp +pip install -e ".[dev]" + +# 品質チェックを実行 +ruff check wavexis_mcp tests +ruff format --check +mypy wavexis_mcp +python -m bandit -r wavexis_mcp + +# テストを実行 +pytest tests/unit -v +``` + +## コントリビューション + +コントリビューションを歓迎します。開発ワークフロー、コーディング規約、プルリクエストの手順については [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。セキュリティ問題については [SECURITY.md](SECURITY.md) を参照してください。 + +## 謝辞 + +WaveXisMCPは [wavexis](https://github.com/MathiasPaulenko/wavexis) ブラウザ自動化ライブラリと [Model Context Protocol](https://modelcontextprotocol.io/) の上に構築されています。本プロジェクトを支えてくれるツールと標準を提供してくださった、オープンソースのPythonおよびMCPコミュニティに感謝します。 + +## ライセンス + +MIT diff --git a/README.md b/README.md index 5a5d77f..178fdd7 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ --- +**English** | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) + [](https://github.com/MathiasPaulenko/wavexis-mcp/actions/workflows/ci.yml) [](https://pypi.org/project/wavexis-mcp/) [](https://pypi.org/project/wavexis-mcp/) diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..a58f8a5 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,424 @@ + + +
+
+
+ Chrome + Firefox · CDP + BiDi · 100% Python · 无需 Node.js · 无需下载 Chromium +
+ +--- + +[English](README.md) | **简体中文** | [日本語](README.ja.md) + +[](https://github.com/MathiasPaulenko/wavexis-mcp/actions/workflows/ci.yml) +[](https://pypi.org/project/wavexis-mcp/) +[](https://pypi.org/project/wavexis-mcp/) +[](https://pypi.org/project/wavexis-mcp/) +[](https://github.com/MathiasPaulenko/wavexis-mcp/actions/workflows/ci.yml) +[](https://github.com/MathiasPaulenko/wavexis-mcp/pkgs/container/wavexis-mcp) +[](https://github.com/MathiasPaulenko/wavexis-mcp/blob/main/LICENSE) +[](https://mathiaspaulenko.github.io/wavexis-mcp/) +[](https://smithery.ai/servers/mathias-paulenko/wavexis-mcp) + +> 将 [wavexis](https://github.com/MathiasPaulenko/wavexis) 浏览器自动化库以 MCP 服务器形式提供给 LLM。共 220 个工具，分属 13 个功能层级。无需 Node.js，无需下载 Chromium — 直接使用本机已安装的 Chrome/Edge。100% Python。 + +## 快速演示 + +**30 秒完成第一次截图。** 将以下内容添加到你的 MCP 客户端配置（Claude Desktop、Cursor、Windsurf、VS Code）： + +```json +{ + "mcpServers": { + "wavexis": { + "command": "uvx", + "args": ["wavexis-mcp", "--caps", "all"] + } + } +} +``` + +然后对你的 LLM 说： + +> *"请对 https://example.com 截取整页截图"* + +LLM 会调用 `wavexis_screenshot(url="https://example.com", full_page=true)` 并返回截图。无需 Node.js，无需下载 Chromium，除上述配置外无需其他设置。 + +## 为什么选择 WaveXisMCP？ + +WaveXisMCP 封装了 [wavexis](https://github.com/MathiasPaulenko/wavexis) 浏览器自动化库，并以 [MCP 服务器](https://modelcontextprotocol.io/) 的形式对外暴露。你不需要 Node.js、Playwright，也不需要单独下载 Chromium — WaveXisMCP 会直接启动本机已安装的 Chrome 或 Edge。 + +### 主要特性 + +- **220 个工具** — 比 Playwright MCP（21）多 3 倍，比 zendriver-mcp（96）多 2 倍 +- **13 个功能层级** — 通过 `--caps` 按需启用。从 `core`（72 个工具）开始，再按需要追加层级 +- **Chrome + Firefox** — Chrome/Edge 使用 CDP，Firefox 使用 BiDi。两者都会从 PATH 自动启动对应驱动 +- **无需下载 Chromium** — 使用本机浏览器。安装体积约 5MB，而 Playwright MCP 约 400MB +- **隐身模式** — `stealth=true` 可隐藏 `navigator.webdriver`，并伪造 plugins、languages 与 chrome runtime +- **结构化错误** — 每个错误都包含 `suggestion` 字段，便于 LLM 在无人干预下自我纠正 +- **多动作 YAML** — 在一次工具调用中串联 navigate → click → fill → screenshot +- **直接 CDP/BiDi 访问（逃生舱）** — 覆盖尚未提供专用工具的浏览器功能 +- **Lighthouse 审计、WebAuthn、Bluetooth、Cast** — 其他 MCP 服务器通常不具备的小众能力 +- **SSRF 防护、路径沙盒、速率限制** — 从第一天起就内置安全机制 +- **593 项测试、强制 90% 覆盖率、真实 Chrome 的 E2E** — 可直接用于生产环境 + +### 工作原理 + +```text +你（自然语言） + → LLM 决定调用哪个工具 + → WaveXisMCP 接收工具调用 + → wavexis 库通过 CDP 或 BiDi 执行 + → Chrome/Edge/Firefox 执行操作 + ← 以 JSON 返回结果（文本、base64、文件路径） + ← JSON 回传给 LLM + ← LLM 为你总结结果 +``` + +LLM 不会直接看到浏览器。它只能看到工具定义（名称、描述、参数）以及 JSON 响应。因此，任何兼容 MCP 的 LLM 客户端都能开箱即用，无需定制集成。 + +### 核心概念 + +- **工具（Tool）** — 单个浏览器操作（截图、eval、点击等），以 MCP 工具形式暴露，供任意 LLM 客户端调用。 +- **会话（Session）** — 持久化的浏览器实例。打开会话后可连续发起多次工具调用，完成后再关闭，避免每次操作都重新启动浏览器。 +- **无状态模式（Stateless）** — 调用任意工具时传入 `url` 参数。浏览器会自动启动、执行并关闭。 +- **功能层级（Capability tiers）** — 从 `core`（72 个工具）到 `all`（220 个工具）共 13 个层级。通过 `--caps` 按需启用。 +- **双后端（Dual backend）** — CDP（基于 Chromium，经由 cdpwave）与 BiDi（W3C 跨浏览器，经由 bidiwave），可按会话选择。 +- **结构化错误（Structured errors）** — 每个错误都包含 `suggestion` 字段，告诉 LLM 下一步该做什么，从而实现无人干预的自我纠正。 + +## 安装 + +```bash +pip install wavexis-mcp +``` + +启用 CDP 后端（Chromium）： + +```bash +pip install "wavexis-mcp[cdp]" +``` + +或不安装直接运行（推荐）： + +```bash +uvx wavexis-mcp +``` + +## 环境要求 + +- **Python**：3.11、3.12 或 3.13 +- **浏览器**：Google Chrome、Microsoft Edge，或任意基于 Chromium/Chrome 的浏览器 +- **BiDi 后端**（可选）：Chrome 需 ChromeDriver/EdgeDriver，Firefox 需 geckodriver + +## 快速开始 + +添加到你的 MCP 客户端配置（Claude Desktop、Cursor、Windsurf、VS Code）： + +```json +{ + "mcpServers": { + "wavexis": { + "command": "uvx", + "args": ["wavexis-mcp", "--caps", "all"] + } + } +} +``` + +或使用 pip： + +```json +{ + "mcpServers": { + "wavexis": { + "command": "wavexis-mcp", + "args": ["--caps", "all"] + } + } +} +``` + +### 无状态模式（一次性） + +调用任意工具时传入 `url` 参数 — 浏览器会自动启动、执行并关闭： + +```text +wavexis_screenshot(url="https://example.com", full_page=true) +``` + +### 会话模式（多步骤） + +打开会话，串联多个动作，完成后关闭： + +```text +wavexis_session_open(backend="cdp", headless=false) +→ {"session_id": "abc-123"} + +wavexis_navigate(session_id="abc-123", url="https://example.com") +wavexis_click(session_id="abc-123", selector="#login") +wavexis_screenshot(session_id="abc-123") +wavexis_session_close(session_id="abc-123") +``` + +### 自然语言交互（M1） + +使用 `wavexis_act`，通过自然语言与页面交互： + +```text +wavexis_session_open(backend="cdp") +wavexis_navigate(session_id="abc-123", url="https://example.com") +wavexis_act(session_id="abc-123", instruction="click the login button") +→ {"action": "click", "element": {"ref": "el-3", "role": "button", "name": "Login"}, "status": "ok"} +``` + +`wavexis_act` 工具会获取 a11y 快照，通过关键词打分将指令匹配到元素，并执行检测到的动作（click、type、fill、hover）。不调用外部 LLM — 纯启发式匹配。 + +## 功能层级 + +| 层级 | 标志 | 工具数 | 主要功能 | +|------|------|-------|--------------| +| **Core** | 始终启用 | 72 | 会话、导航、截图、PDF、爬取、eval、DOM、输入、cookies、标签页、自然语言交互、iframe、shadow DOM、事件 | +| **Network** | `--caps=network` | 20 | 请求头、UA、拦截、限速、缓存、HAR、intercept、mock、修改请求/响应、请求体、重放 HAR、请求列表 | +| **Storage** | `--caps=storage` | 18 | localStorage、sessionStorage、cache storage、IndexedDB、状态保存/恢复 | +| **Emulation** | `--caps=emulation` | 9 | 设备、视口、地理位置、时区、深色模式、语言区域、CPU、触摸、传感器 | +| **A11y** | `--caps=a11y` | 4 | 无障碍树快照、节点遍历、axe-core 审计 | +| **Interactions** | `--caps=interactions` | 5 | 对话框、下载、权限 | +| **DevTools** | `--caps=devtools` | 31 | 性能、CSS、调试、overlay、控制台、安全、窗口管理、组合 trace、带标注截图 | +| **Vision** | `--caps=vision` | 7 | 基于坐标的鼠标操作（像素级精确） | +| **Video** | `--caps=video` | 4 | 视频录制、章节、动作叠加层 | +| **Testing** | `--caps=testing` | 6 | 断言、定位器生成 | +| **Workflows** | `--caps=workflows` | 6 | 多动作 YAML、直接 CDP/BiDi、浏览器上下文 CRUD | +| **Data** | `--caps=data` | 7 | Codegen、Lighthouse 审计、抽取、WebSocket 拦截、爬取、视觉对比、Core Web Vitals | +| **Experimental** | `--caps=experimental` | 31 | Service workers、动画、WebAuthn、WebAudio、媒体、cast、bluetooth、扩展、偏好设置 | +| **合计** | `--caps=all` | **220** | | + +**默认**：`--caps=core`（72 个工具）。启用全部：`--caps=all`。启用指定层级：`--caps=network,storage,emulation`。 + +> **提示**：建议从 `--caps core` 开始，再按需追加层级。每个层级都会把工具定义加入 LLM 的上下文，从而消耗 token。对大多数任务而言，`core,network,storage`（110 个工具）是较好的平衡点。 + +## 后端 + +WaveXisMCP 支持两种后端，并保持完整功能对等： + +- **CDP**（cdpwave）— 默认后端，Chrome DevTools Protocol。通过 WebSocket 直连 Chrome/Edge。无需驱动。覆盖 57 个 CDP 域。`pip install "wavexis-mcp[cdp]"` +- **BiDi**（bidiwave）— WebDriver BiDi 协议，W3C 跨浏览器（Firefox、Chrome）。Chrome 需要 chromedriver，Firefox 需要 geckodriver；若尚未运行，两者都会从 PATH 自动启动。`pip install "wavexis-mcp[bidi]"` + +按会话选择： + +```text +# CDP (default, Chrome/Edge only) +wavexis_session_open(backend="cdp") + +# BiDi with Chrome (auto-launches chromedriver) +wavexis_session_open(backend="bidi", browser="chrome") + +# BiDi with Firefox (auto-launches geckodriver) +wavexis_session_open(backend="bidi", browser="firefox") +``` + +### 连接到已有 Chrome + +使用 `connect_existing=True`，以 `--remote-debugging-port` 启动 Chrome 并连接到它。适合复用已登录的浏览器配置文件： + +```text +# Launch Chrome with debug port and connect via CDP +wavexis_session_open(connect_existing=true) + +# Reuse an existing Chrome profile (keeps logins, cookies, extensions) +wavexis_session_open(connect_existing=true, user_data_dir="C:/Users/me/ChromeProfile") +``` + +Chrome 会以有头模式启动（headless 会被忽略）。会话关闭时，浏览器子进程也会一并终止。 + +## 多动作 YAML + +通过传入 YAML 字符串，在一次工具调用中串联多个动作： + +```text +wavexis_multi_action( + config=""" +actions: + - navigate: https://example.com + - screenshot: + full_page: true + - eval: document.title + - click: "#login" + - type: + selector: "#username" + text: admin@example.com + - screenshot: {} +""", + session_id="abc-123" +) +``` + +支持的动作类型：`navigate`、`screenshot`、`eval`、`click`、`type`、`fill`。设置 `continue_on_error: true` 可在失败后继续执行。 + +## MCP 资源与提示词（M3） + +**资源（Resources）**（只读浏览器状态）： + +- `wavexis://session/{id}/url` — 当前页面 URL +- `wavexis://session/{id}/cookies` — cookies（JSON） +- `wavexis://session/{id}/console` — 控制台消息 +- `wavexis://session/{id}/tabs` — 已打开的标签页 + +**提示词（Prompts）**（工作流模板）： + +- `scrape_page(url, selector)` — 爬取并提取内容 +- `audit_page(url)` — 完整的 a11y + 性能审计 +- `fill_form(url, fields)` — 填写页面表单 +- `debug_page(url)` — 调试控制台、网络与性能 + +## HTTP 传输 + +将 WaveXisMCP 作为 HTTP 服务器运行，适用于 CI/CD、共享实例或 Docker： + +```bash +# HTTP on localhost +wavexis-mcp --transport http --port 8765 + +# HTTP with all tiers +wavexis-mcp --transport http --port 8765 --caps all + +# HTTP with remote access (use behind a reverse proxy!) +wavexis-mcp --transport http --allow-remote --port 8765 +``` + +默认绑定到 `127.0.0.1`。使用 `--allow-remote` 可绑定到 `0.0.0.0`。 + +## 速率限制（M4） + +按会话的令牌桶速率限制： + +```bash +# 10 calls/sec, burst of 5 +wavexis-mcp --rate-limit 10 --rate-burst 5 +``` + +超限时返回 `{"error": "rate_limited", "retry_after_ms": N}`。 + +## Docker + +```bash +# Pull and run +docker run -p 8765:8765 ghcr.io/mathiaspaulenko/wavexis-mcp + +# Or build locally +docker build -t wavexis-mcp . +docker run -p 8765:8765 wavexis-mcp + +# Docker Compose +docker-compose up +``` + +详见 [Docker 文档](https://mathiaspaulenko.github.io/wavexis-mcp/docker/)。 + +## 对比 + +| 功能 | Playwright MCP | **WaveXisMCP** | +|---------|:---:|:---:| +| 语言 | TypeScript | **Python** | +| 是否需要 Node.js | ✗ | **✓（无需 Node.js）** | +| 是否下载 Chromium（约 200MB） | ✓ | **✗（使用本机浏览器）** | +| 安装体积 | ~400MB | **~5MB** | +| 冷启动 | 3.2s | **0.8s** | +| 工具总数 | ~21 | **220** | +| 功能层级（按需启用） | ✗ | **✓（13 个层级）** | +| 双协议（CDP + BiDi） | ✗ | **✓** | +| Firefox 支持 | ✓（基础） | **✓（BiDi + geckodriver 自动启动）** | +| 后端选择（按会话） | ✗ | **✓** | +| 隐身 / 反爬模式 | ✗ | **✓** | +| 直接 CDP/BiDi 访问 | ✗ | **✓（逃生舱）** | +| 多动作 YAML 批处理 | ✗ | **✓** | +| 视频录制 | ✗ | **✓** | +| Lighthouse 审计 | ✗ | **✓** | +| WebAuthn / Bluetooth / Cast | ✗ | **✓** | +| 自然语言交互 | ✗ | **✓（`wavexis_act`）** | +| MCP 资源与提示词 | ✗ | **✓** | +| 速率限制 | ✗ | **✓** | +| SSRF 防护 | ✗ | **✓** | +| 带建议的结构化错误 | ✗ | **✓** | + +> **说明**：Playwright MCP 支持 WebKit（Safari）— WaveXisMCP 目前尚不支持。计划功能请参见 [路线图](https://github.com/MathiasPaulenko/wavexis-mcp/issues)。 + +## 文档 + +完整文档、API 参考与示例托管于 [mathiaspaulenko.github.io/wavexis-mcp](https://mathiaspaulenko.github.io/wavexis-mcp/)。 + +主要章节： + +- [快速开始](https://mathiaspaulenko.github.io/wavexis-mcp/quickstart/) +- [架构](https://mathiaspaulenko.github.io/wavexis-mcp/architecture/) +- [配置](https://mathiaspaulenko.github.io/wavexis-mcp/configuration/) +- [Docker](https://mathiaspaulenko.github.io/wavexis-mcp/docker/) +- [HTTP 传输](https://mathiaspaulenko.github.io/wavexis-mcp/http-transport/) +- [速率限制](https://mathiaspaulenko.github.io/wavexis-mcp/rate-limiting/) +- [工具参考](https://mathiaspaulenko.github.io/wavexis-mcp/tools/core/) +- [示例](https://mathiaspaulenko.github.io/wavexis-mcp/examples/screenshot/) + +## 错误处理 + +所有工具在失败时都会返回结构化错误 JSON。每个错误都包含 `suggestion` 字段，用于引导 LLM 执行下一步动作： + +```json +{ + "error": "Session 'abc-123' not found.", + "tool": "wavexis_navigate", + "type": "SessionNotFoundError", + "message": "Session 'abc-123' not found.", + "suggestion": "Call wavexis_session_open first to create a browser session." +} +``` + +这使得 LLM 可以在无人干预下自我纠正 — 它会阅读建议并调用推荐的工具。 + +## 架构 + +WaveXisMCP 位于三层生态的最上层： + +```text +WaveXisMCP（MCP 服务器，220 个工具） +└─ wraps → wavexis（浏览器自动化库） + ├─ cdpwave（CDP 后端，Chromium 原生） + └─ bidiwave（BiDi 后端，W3C 跨浏览器） +``` + +- **cdpwave** — 面向 Chrome DevTools Protocol 的底层异步 Python 库。通过 WebSocket 直连 Chrome/Edge。无需驱动二进制。 +- **bidiwave** — 面向 WebDriver BiDi 协议（W3C 标准）的底层异步 Python 库。可配合 Firefox、Chrome 与 Edge 使用。 +- **wavexis** — 高层浏览器自动化库，通过统一的 `AbstractBackend` 接口抽象 cdpwave 与 bidiwave。 +- **WaveXisMCP** — 封装 wavexis 的 MCP 服务器。将每个后端方法暴露为 MCP 工具，并提供 Pydantic v2 输入校验、JSON 响应以及功能层级过滤。 + +完整系统设计、数据流图与 ADR 请参见 [架构文档](https://mathiaspaulenko.github.io/wavexis-mcp/architecture/)。 + +## 开发 + +```bash +git clone https://github.com/MathiasPaulenko/wavexis-mcp.git +cd wavexis-mcp +pip install -e ".[dev]" + +# 运行质量检查 +ruff check wavexis_mcp tests +ruff format --check +mypy wavexis_mcp +python -m bandit -r wavexis_mcp + +# 运行测试 +pytest tests/unit -v +``` + +## 贡献 + +欢迎贡献。开发流程、编码规范与拉取请求流程请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。安全问题请参见 [SECURITY.md](SECURITY.md)。 + +## 致谢 + +WaveXisMCP 基于 [wavexis](https://github.com/MathiasPaulenko/wavexis) 浏览器自动化库与 [Model Context Protocol](https://modelcontextprotocol.io/) 构建。感谢开源 Python 与 MCP 社区提供的工具与标准，使本项目成为可能。 + +## 许可证 + +MIT