cowork-qa

cowork-qa-mcp

LLM に実際の Chromium ブラウザーを提供し、指定された目標に向けて実行したすべての操作を記録して、構造化されたトレースを返す Model Context Protocol サーバーです。これにより、LLM（または別の LLM）が目標を実際に達成できたかどうかを判断できます。

Playwright を基盤にしています。5 つのツール、1 つのバイナリー、クラウドへの依存はありません。

目的

多くのブラウザーツール用 MCP サーバーはステートレスです。LLM がクリックすると HTML が返され、それを繰り返します。何が起きたかの記録も、実行後に結果を評価する方法も、目標のコンテキストもありません。

cowork-qa-mcp はこれを変えます。

• すべてのセッションは、平易な英語で記述された目標から開始します。
• すべての操作（goto、click、fill、press、eval）を、タイムスタンプ、操作後の URL、ページの aria スナップショットとともに記録します。
• セッションの終了時に、JSON トレースがディスクに保存され、単一の qa_get_trace 呼び出しで取得できるようになります。

オーケストレーションを行う LLM は、実行時のやり取りを信頼するのではなく、トレースをもとに「この実行で本当に目標を達成できたのか、それとも間違ったボタンをクリックしたのか」と推論できます。

ツール

ツール	説明
session_start	新しいタブを開き、必要に応じて開始 URL を指定して、セッション ID を返します
session_act	goto、click、fill、press、eval のいずれかを実行します。ステップを記録します。
session_observe	現在の URL とページの aria スナップショット全体を返します
session_end	タブを閉じ、トレースをディスクに保存して、ファイルパスを返します
qa_get_trace	目標、すべてのステップ、最終 URL、最終 aria スナップショットを LLM が読み取れる形式で返します

インストール

Node 20 以降が必要です。パッケージは npm で公開されているため、クローンは不要です。

# Try it once, no install
npx cowork-qa-mcp

# Or install globally
npm install -g cowork-qa-mcp

初回インストール時に、Playwright の postinstall を通じて Chromium がダウンロードされます（約 150 MB）。

MCP 対応クライアントへの接続

Claude Code

claude mcp add cowork-qa --scope user -- npx -y cowork-qa-mcp

ヘッドレスではなく、ブラウザーの画面を表示するには、次のようにします。

claude mcp add cowork-qa --scope user \
  -e COWORK_QA_HEADED=1 \
  -- npx -y cowork-qa-mcp

新しい claude セッション内で /mcp を実行して確認してください。cowork-qa ✓ connected と 5 つのツールが表示されます。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "cowork-qa": {
      "command": "npx",
      "args": ["-y", "cowork-qa-mcp"]
    }
  }
}

Cursor / Windsurf / その他の MCP クライアント

MCP の stdio トランスポートに対応するクライアントであれば、どれでも動作します。サーバー設定で npx -y cowork-qa-mcp を指定してください。

ソースから実行する場合（開発用）

git clone https://github.com/inSideos-designs/cowork-qa-mcp.git
cd cowork-qa-mcp
npm install
npm run build
node dist/server.js   # stdio server, expects an MCP client

MCP Registry

このサーバーは公式の MCP Server Registry にも io.github.inSideos-designs/cowork-qa として公開されています。レジストリから自動検出するクライアントであれば、手動で設定しなくても見つけられます。

環境変数

変数	デフォルト	用途
COWORK_QA_HEADED	未設定（ヘッドレス）	1 に設定すると、ウィンドウを表示して Chromium を起動します
COWORK_QA_DATA	<cwd>/.cowork-qa	<session-id>.json 形式のトレースを書き込むディレクトリ

使用例

オーケストレーションを行う LLM が実行する、一般的なエンドツーエンドのループは次のとおりです。

session_start({ goal: "find the cheapest 14\" MacBook Pro on apple.com",
                url: "https://www.apple.com/shop/buy-mac/macbook-pro" })
  → { session_id: "abc-123" }

session_observe({ session_id: "abc-123" })
  → URL + aria-snapshot

session_act({ session_id: "abc-123", action: "click",
              target: "button:has-text('Continue')" })

# ... more acts / observes ...

session_end({ session_id: "abc-123" })
  → { steps: 7, trace_path: "~/.cowork-qa/abc-123.json" }

qa_get_trace({ session_id: "abc-123" })
  → Goal: ...
    Steps (7 total): ...
    Final URL: ...
    Final aria-snapshot: ...

トレース形式

各トレースは JSON ファイルです。

{
  "session_id": "abc-123",
  "goal": "...",
  "steps": [
    {
      "t": 142,
      "action": "click",
      "args": { "target": "...", "value": null },
      "url_after": "...",
      "aria_after": "..."
    }
  ],
  "final": { "url": "...", "aria": "..." },
  "path": "/.../abc-123.json"
}

制限事項／既知の動作

• session_observe の呼び出しはトレースのステップ数に含まれません。含まれるのは session_act の呼び出しのみです。最終的な aria スナップショットは session_end で取得されます。
• eval は JS 式を実行しますが、値を呼び出し元に返しません。ページ上の副作用のみ確認できます。
• サーバーインスタンス内のすべてのセッションで、Chromium プロセスを 1 つ共有します。各セッションはそれぞれ独自のコンテキストを持ちます（Cookie などは分離されます）。
• セレクターはそのまま Playwright に渡されます。CSS、テキストセレクター（button:has-text("Send")）、role= セレクターがすべて使えます。

ライセンス

MIT — LICENSE を参照してください。

コントリビューション

PR を歓迎します。小規模に保ってください。このサーバーは、薄く監査しやすい状態を維持することを目指しています。