easy-ui-mcp

ローカルUIテストのためのDocker化されたMCP（Model Context Protocol）サーバーです。Playwrightベースのブラウザ自動化ツールをHTTP/SSE経由で公開し、AIエージェント（Claude Codeなど）がWeb UIのフローをステップバイステップで操作し、スクリーンショット付きのJSON + HTMLレポートを受け取れるようにします。サーバー側のLLMは不要で、テストスクリプトを書く必要もありません。

クイックスタート

docker compose up -d --build
curl http://localhost:8765/health
# {"status":"ok"}

Claude Codeを接続します：

claude mcp add --transport http easy-ui-mcp http://localhost:8765/mcp

次にClaude Codeにページへ移動してスクリーンショットを撮るよう依頼します。以下のツールが呼び出され、結果が報告されます。

別のリポジトリから使っていますか？ MCPの登録はプロジェクト単位です。そのリポジトリのルートでも claude mcp add を実行してください（上記のコンテナは一度起動すればよく、複数のリポジトリで共有できます）。必要な手順の詳細は AGENTS.md → Using easy-ui-mcp From Another Repo を参照してください。

Related MCP server: Playwright MCP Server

ネットワーク

コンテナは docker-compose.yml 内で network_mode: host で実行されます（ブリッジネットワーク上の公開ポートではありません）。これは必須であり、任意ではありません。このコンテナ内でPlaywrightが操作するブラウザは、あなたのホストマシン上の localhost:<port> に到達する必要があります。そこには、テスト対象のアプリの開発サーバー（テスト対象のリポジトリ）が実際に稼働しています。デフォルトのブリッジネットワークでは、コンテナに独立したネットワーク名前空間が与えられ、ホストへの経路がまったくありません。http://localhost:8766 のようなターゲットURLはハングするか ERR_CONNECTION_REFUSED で失敗し、http://<host-LAN-IP>:8766 は、ターゲットサーバーがリッスンしていてホストのシェルから curl で到達可能な場合でも、単にタイムアウトします。

このコンテナを network_mode: host が利用できない環境（macOS/Windows上のDocker Desktopなど、ホストネットワーキングのサポートが制限されているか存在しない環境）にフォーク/再デプロイする場合は、ui_navigate を呼び出す際に localhost の代わりに host.docker.internal をターゲットホスト名として使用し、docker-compose.yml に network_mode: host のフォールバックとして extra_hosts: ["host.docker.internal:host-gateway"] を追加してください。

ツール

ui_start_session、ui_end_session、ui_step、ui_navigate、ui_click、ui_fill、ui_assert、ui_check、ui_wait_for、ui_get_page_state、ui_take_screenshot — さらに、MCP以外の呼び出し元向けにRESTラッパー POST /api/run-test もあります。

ステップにラベルを付ける

ui_step(label) は、その後に続くすべてを、次の ui_step まで平易な言葉の見出しの下にグループ化します。このラベルは、レポートにおける呼び出し元が作成した唯一の意図表明です。サーバーは個々のアクションに対して「Opened …」「Clicked …」「Filled …」などの決定的なテンプレートを使用します。コンテナ内でLLMは実行されないため、ラベルがないセッションでも、1つの暗黙のグループの下に読みやすいアクションの説明がレンダリングされます。

ui_start_session  target: "Account Access toggle smoke"
ui_step           label:  "Open the Settings page"
ui_navigate       ...
ui_wait_for       ...
ui_step           label:  "Turn Manual Invoice access on"
ui_click          ...
ui_assert         ...
ui_end_session

ui_step の呼び出しがないセッションも、単一の暗黙のグループの下で正しくレンダリングされます。

検証と待機 — 正しい方を選ぶ

ハードアクションが1つでも失敗するとセッションは failed とマークされるため、どのように検証するかによって、レポートが真実を伝えるかどうかが決まります。

何かを待つためにリトライループで ui_assert を呼び出さないでください。最初の偽の結果は、アプリが正常でも実行を恒久的に失敗させます。それが ui_wait_for の役割です。

ui_check と ui_wait_for の両方で、条件が実行できない場合（ページが開いていない、または式が例外を投げる）は常にハード失敗です。それはハーネスのエラーであり、観察事項ではありません。

自動失敗スクリーンショットはセッションごとに予算が設定されています（FAILURE_SCREENSHOT_BUDGET、デフォルト3）。同一のスクリーンショット内容はHTMLレポートに1回だけ埋め込まれます。

レポートに表示される内容

判定ボックス（ステータス、ターゲット、ステップ/アクション/失敗数、所要時間）、次にラベル付きステップとしての実行内容（ステップごとの結果と経過時間）、次にブラウザの問題、最後に生のアクションログが開閉式ディスクロージャーの下に折りたたまれて表示されます。

コンソールエラー、未捕捉のページエラー、ネットワークレベルのリクエスト失敗は自動的にキャプチャされ、Browser problems の下に一覧表示されます。コンソールが例外を投げているのにフローが成功するのは、確認する価値のある偽のグリーンです。404や500などのHTTPエラーレスポンスはPlaywrightの requestfailed イベントをトリガーせず、自動的には一覧表示されません。キャプチャされた問題は情報提供のみであり、判定を変更することはありません。セッションごとに最大50件が保持され、それを超えるとレポートは残りが破棄されたと記載します。

アーキテクチャと完全なMCP接続ガイドについては AGENTS.md を、REST APIリファレンスについては HARNESS.md を参照してください。デプロイ/ロールバック手順は RUNBOOK.md にあります。

スコープ（v1）

Webのみ（Chromium）、ローカルのみ、モバイルサポートはまだありません。完全な製品意図については PRD.md を、アーキテクチャの決定については PROJECT_SPEC.md を参照してください。