headlessstage

headlessstage

ヘッドレスブラウザーのページを通じてブラウザーを自動化するツールです。CLI と stdio MCP サーバーを 1 つのバイナリで提供します。URL に移動し、クリック、ホバー、フォーム要素への入力や選択、名前付きスクリーンショットの撮影、ページ内での JavaScript の評価を行えます。

ブラウザー自体は、注入可能なエグゼキューターインターフェース（src/types.ts の BrowserExecutor）の背後で動作します。このパッケージにはブラウザーはバンドルされておらず、ダウンロードもされません。エグゼキューターが設定されていない場合、ブラウザー関連のコマンドは「Browser unavailable」という明確なエラーで失敗します。デプロイ環境では、Puppeteer 互換のエグゼキューターを注入して実際のブラウザーを操作します。ブラウザーのセキュリティを弱める起動オプション（--no-sandbox、--disable-web-security、--allow-insecure-localhost）は、呼び出しで allowDangerous: true を明示的に指定しない限り拒否されます。

インストール

npx -y @reneturcios/headlessstage mcp

CLI

headlessstage mcp                     # stdio MCP server
headlessstage navigate <url>
headlessstage screenshot <name> [selector]
headlessstage click <selector>
headlessstage fill <selector> <value>
headlessstage evaluate <script>
headlessstage --version

終了コード：0 は成功、1 はブラウザーエラー、2 は使用方法のエラーです。

MCP ツール

ツール	目的
puppeteer_navigate	ブラウザーで任意の URL に移動します
puppeteer_screenshot	ページ全体または特定の要素のスクリーンショットを撮影します
puppeteer_click	ページ上の要素をクリックします
puppeteer_hover	ページ上の要素にホバーします
puppeteer_fill	入力フィールドに入力します
puppeteer_select	SELECT タグの要素を選択します
puppeteer_evaluate	ブラウザーのコンソールで JavaScript を実行します

MCP クライアントの設定：

{
  "mcpServers": {
    "headlessstage": {
      "command": "npx",
      "args": ["-y", "@reneturcios/headlessstage", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/headlessstage          # MCP server
docker run --rm ghcr.io/cloudcorprecords/headlessstage --version

開発

npm install
npm run build
npm test

MIT ライセンス。