host
6bcdeb8da1
根因（2026-10-30 活体实证）：#181 的 .browser-remote.sock 假设
宿主能连容器内 socket，但生产 Docker 任务走 runsc/gVisor，
其 gofer 挂载下容器内建的 socket 只在容器内可见，宿主目录
里只有普通文件（browser-live.png 一直能透传）。后果：server
代理对真实任务一律 503，会话根本没活过。
修法：传输层改四个普通文件（worktree 内，原子写 + 追加日志）：
- .browser-remote-state.json：MCP 每轮重写，mtime 即存活信号，
server 判 30 秒无心跳为会话死亡（503）；
- .browser-remote-frame.jpg：最新 screencast 帧（base64 文本）；
- .browser-remote-input.jsonl：server 追加，MCP 按偏移量消费
完整行，执行时再判 holder，半行等下一轮；
- .browser-remote-control.json：{holder, seq}，MCP 首轮即应用，
接管可先于浏览器启动。
- holder 竞态：control 写下后 state 文件约 50ms 才刷新，server
的 input/stream 改判 effective_holder（控制文件 mtime 新者胜），
否则接管后立刻点会误 409。
- 线程契约与控制权模型不变；MCP 主循环仍是唯一触页线程。
- 播种刷新（#181）让老租户自动拿到新版脚本。
测试：socket 测试改文件桥测试（桥轮询/偏移量/半行/陈旧态/
effective_holder + server 代理全链），全量 1357 项通过（skipped 4）。
451 lines
16 KiB
Python
451 lines
16 KiB
Python
"""Stdio MCP server exposing headless Chromium to codex.
|
|
|
|
Protocol: JSON-RPC 2.0 over stdio, one JSON object per line.
|
|
Logs go to stderr only -- anything on stdout would corrupt the
|
|
JSON-RPC stream.
|
|
|
|
This file is deliberately thin: all browser logic lives in
|
|
``playwright_browser.py``. It can run two ways:
|
|
- inside the repo: ``python3 -m cloud.playwright_mcp`` (imports
|
|
``cloud.playwright_browser``);
|
|
- copied flat into a tenant codex-home next to
|
|
``playwright_browser.py`` (imports plain ``playwright_browser``
|
|
from its own directory).
|
|
The ``ensure_codex_home_playwright`` helper does the copying;
|
|
proxy vars and PLAYWRIGHT_BROWSERS_PATH arrive via the MCP env
|
|
block in config.toml, never via tool arguments.
|
|
|
|
One Browser instance lives for the whole MCP process: navigate
|
|
once, then snapshot/click/fill/screenshot against the same page.
|
|
"""
|
|
|
|
import json
|
|
import os
|
|
import sys
|
|
|
|
try:
|
|
from cloud.playwright_browser import Browser, BrowserError
|
|
except ImportError: # flat copy in a tenant codex-home
|
|
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
|
from playwright_browser import Browser, BrowserError # noqa: E402
|
|
|
|
SERVER_NAME = "playwright"
|
|
SERVER_VERSION = "0.1.0"
|
|
|
|
_TOOLS = [
|
|
{
|
|
"name": "browser_navigate",
|
|
"description": (
|
|
"Open a URL in headless Chromium and return its final "
|
|
"URL and title. Use for pages that need JavaScript to "
|
|
"render, which web_fetch cannot see. Network goes "
|
|
"through the egress proxy, so domains outside the "
|
|
"Tinyproxy whitelist fail with a proxy 403 -- report "
|
|
"that plainly, do not bypass it."
|
|
),
|
|
"inputSchema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"url": {"type": "string",
|
|
"description": "http(s) URL, or file:// URL "
|
|
"for a page already in the worktree"},
|
|
},
|
|
"required": ["url"],
|
|
},
|
|
},
|
|
{
|
|
"name": "browser_snapshot",
|
|
"description": (
|
|
"Return the current page's title, URL and body text "
|
|
"(truncated at 8000 characters with a flag). Call "
|
|
"after navigate, and after click/fill, to see what "
|
|
"actually rendered."
|
|
),
|
|
"inputSchema": {"type": "object", "properties": {}},
|
|
},
|
|
{
|
|
"name": "browser_click",
|
|
"description": (
|
|
"Click an element by CSS selector or Playwright "
|
|
"selector (e.g. 'button.submit', 'text=Next'). "
|
|
"Then snapshot to see the result."
|
|
),
|
|
"inputSchema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"selector": {"type": "string"},
|
|
},
|
|
"required": ["selector"],
|
|
},
|
|
},
|
|
{
|
|
"name": "browser_fill",
|
|
"description": (
|
|
"Fill an input/textarea by CSS selector with text. "
|
|
"Then snapshot or click to submit."
|
|
),
|
|
"inputSchema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"selector": {"type": "string"},
|
|
"text": {"type": "string"},
|
|
},
|
|
"required": ["selector", "text"],
|
|
},
|
|
},
|
|
{
|
|
"name": "browser_evaluate",
|
|
"description": (
|
|
"Run a JavaScript expression in the page and return "
|
|
"its string value (truncated at 4000 characters). "
|
|
"Same sandbox privilege as the shell tool; prefer "
|
|
"snapshot/click/fill for ordinary reads and actions."
|
|
),
|
|
"inputSchema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"expression": {"type": "string"},
|
|
},
|
|
"required": ["expression"],
|
|
},
|
|
},
|
|
{
|
|
"name": "browser_click_at",
|
|
"description": (
|
|
"Click at viewport coordinates (CSS pixels, origin "
|
|
"top-left of the 1280x800 viewport). This is the tool "
|
|
"a live viewer drives: the user clicks on a screenshot "
|
|
"and the coordinates arrive here. Then snapshot to see "
|
|
"the result."
|
|
),
|
|
"inputSchema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"x": {"type": "number"},
|
|
"y": {"type": "number"},
|
|
},
|
|
"required": ["x", "y"],
|
|
},
|
|
},
|
|
{
|
|
"name": "browser_live_shot",
|
|
"description": (
|
|
"Screenshot to the FIXED live-view file "
|
|
"browser-live.png plus a browser-live.json status "
|
|
"sidecar (url, title, timestamp), so a watcher can "
|
|
"poll one stable path. Call after every navigate / "
|
|
"click / fill while a live view is wanted. Returns "
|
|
"path, bytes, url, title and timestamp."
|
|
),
|
|
"inputSchema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"output_filename": {"type": "string",
|
|
"description": "Plain basename "
|
|
"to save as. Default: "
|
|
"browser-live.png"},
|
|
},
|
|
},
|
|
},
|
|
{
|
|
"name": "browser_snapshot_refs",
|
|
"description": (
|
|
"Accessibility-style snapshot: interactive elements "
|
|
"with stable refs (e.g. e3) plus tag, role and name. "
|
|
"Use browser_click_ref to click one; refs are valid "
|
|
"until the next snapshot_refs call."
|
|
),
|
|
"inputSchema": {"type": "object", "properties": {}},
|
|
},
|
|
{
|
|
"name": "browser_click_ref",
|
|
"description": (
|
|
"Click an element by its ref from browser_snapshot_refs. "
|
|
"More robust than a CSS selector across re-renders."
|
|
),
|
|
"inputSchema": {
|
|
"type": "object",
|
|
"properties": {"ref": {"type": "string"}},
|
|
"required": ["ref"],
|
|
},
|
|
},
|
|
{
|
|
"name": "browser_mouse_move",
|
|
"description": "Move the mouse to viewport coordinates (1280x800).",
|
|
"inputSchema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"x": {"type": "number"},
|
|
"y": {"type": "number"},
|
|
},
|
|
"required": ["x", "y"],
|
|
},
|
|
},
|
|
{
|
|
"name": "browser_key_press",
|
|
"description": "Press a key (Playwright key name, e.g. Enter, Tab).",
|
|
"inputSchema": {
|
|
"type": "object",
|
|
"properties": {"key": {"type": "string"}},
|
|
"required": ["key"],
|
|
},
|
|
},
|
|
{
|
|
"name": "browser_type_text",
|
|
"description": "Type text at the current focus.",
|
|
"inputSchema": {
|
|
"type": "object",
|
|
"properties": {"text": {"type": "string"}},
|
|
"required": ["text"],
|
|
},
|
|
},
|
|
{
|
|
"name": "browser_screenshot",
|
|
"description": (
|
|
"Save a PNG screenshot of the current page into the "
|
|
"working directory and return its absolute path and "
|
|
"byte size. Verify the returned path with shell/PIL "
|
|
"before reporting success."
|
|
),
|
|
"inputSchema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"output_filename": {"type": "string",
|
|
"description": "Plain basename "
|
|
"to save as, e.g. 'shot.png'. "
|
|
"Default: shot-<epoch>.png"},
|
|
},
|
|
},
|
|
},
|
|
{
|
|
"name": "browser_close",
|
|
"description": "Close the browser page. Safe to call twice.",
|
|
"inputSchema": {"type": "object", "properties": {}},
|
|
},
|
|
]
|
|
|
|
|
|
def _err(code, message):
|
|
return {"code": code, "message": message}
|
|
|
|
|
|
_BROWSER = None
|
|
_BRIDGE = None
|
|
|
|
|
|
def _get_browser(browser=None):
|
|
global _BROWSER
|
|
if browser is not None:
|
|
return browser
|
|
if _BROWSER is None:
|
|
_BROWSER = Browser()
|
|
return _BROWSER
|
|
|
|
|
|
def _get_bridge(browser=None):
|
|
"""File-bridge remote control, lazily created. Keyed by browser
|
|
identity so tests passing different fake browsers don't share
|
|
one holder flag."""
|
|
global _BRIDGE
|
|
target = _get_browser(browser)
|
|
if _BRIDGE is not None and _BRIDGE.browser is target:
|
|
return _BRIDGE
|
|
try:
|
|
from playwright_remote import RemoteBridge
|
|
except ImportError:
|
|
try:
|
|
from cloud.playwright_remote import RemoteBridge
|
|
except ImportError:
|
|
return None
|
|
_BRIDGE = RemoteBridge(target, getattr(target, "cwd", None))
|
|
return _BRIDGE
|
|
|
|
|
|
def handle_request(request, browser=None):
|
|
"""Handle one JSON-RPC request dict. Returns a response dict or
|
|
None for notifications (no id). Tests pass a fake browser."""
|
|
if not isinstance(request, dict):
|
|
return {"jsonrpc": "2.0", "id": None,
|
|
"error": _err(-32700, "request is not an object")}
|
|
method = request.get("method")
|
|
req_id = request.get("id")
|
|
is_notification = "id" not in request
|
|
|
|
if method == "initialize":
|
|
if is_notification:
|
|
return None
|
|
return {"jsonrpc": "2.0", "id": req_id,
|
|
"result": {
|
|
"protocolVersion": request.get("params", {}).get(
|
|
"protocolVersion", "2024-11-05"),
|
|
"capabilities": {"tools": {}},
|
|
"serverInfo": {"name": SERVER_NAME,
|
|
"version": SERVER_VERSION}}}
|
|
if method in ("notifications/initialized", "notifications/cancelled"):
|
|
return None
|
|
if method == "ping":
|
|
if is_notification:
|
|
return None
|
|
return {"jsonrpc": "2.0", "id": req_id, "result": {}}
|
|
if method == "tools/list":
|
|
if is_notification:
|
|
return None
|
|
return {"jsonrpc": "2.0", "id": req_id,
|
|
"result": {"tools": _TOOLS}}
|
|
if method == "tools/call":
|
|
if is_notification:
|
|
return None
|
|
params = request.get("params") or {}
|
|
name = params.get("name")
|
|
args = params.get("arguments") or {}
|
|
target = _get_browser(browser)
|
|
remote = _get_bridge(browser)
|
|
if remote is not None and remote.get_holder() == "user":
|
|
return {"jsonrpc": "2.0", "id": req_id,
|
|
"result": {"content": [{"type": "text",
|
|
"text": "error: user holds "
|
|
"browser control; wait for "
|
|
"release"}],
|
|
"isError": True}}
|
|
try:
|
|
if name == "browser_navigate":
|
|
result = target.navigate(args.get("url"))
|
|
elif name == "browser_snapshot":
|
|
result = target.snapshot()
|
|
elif name == "browser_click":
|
|
result = target.click(args.get("selector"))
|
|
elif name == "browser_fill":
|
|
result = target.fill(args.get("selector"),
|
|
args.get("text"))
|
|
elif name == "browser_click_at":
|
|
result = target.click_at(args.get("x"), args.get("y"))
|
|
elif name == "browser_mouse_move":
|
|
result = target.mouse_move(args.get("x"), args.get("y"))
|
|
elif name == "browser_key_press":
|
|
result = target.key_press(args.get("key"))
|
|
elif name == "browser_type_text":
|
|
result = target.type_text(args.get("text"))
|
|
elif name == "browser_snapshot_refs":
|
|
result = target.snapshot_refs()
|
|
elif name == "browser_click_ref":
|
|
result = target.click_ref(args.get("ref"))
|
|
elif name == "browser_live_shot":
|
|
result = target.live_shot(
|
|
args.get("output_filename"))
|
|
elif name == "browser_evaluate":
|
|
result = target.evaluate(args.get("expression"))
|
|
elif name == "browser_screenshot":
|
|
result = target.screenshot(
|
|
args.get("output_filename"))
|
|
elif name == "browser_close":
|
|
result = target.close()
|
|
else:
|
|
return {"jsonrpc": "2.0", "id": req_id,
|
|
"error": _err(-32602, "unknown tool: %r" % name)}
|
|
except Exception as exc: # noqa: BLE001 - tool errors are data
|
|
return {"jsonrpc": "2.0", "id": req_id,
|
|
"result": {"content": [{"type": "text",
|
|
"text": "error: %s" % exc}],
|
|
"isError": True}}
|
|
return {"jsonrpc": "2.0", "id": req_id,
|
|
"result": {"content": [{"type": "text",
|
|
"text": json.dumps(
|
|
result, ensure_ascii=False)}],
|
|
"isError": False}}
|
|
if is_notification:
|
|
return None
|
|
return {"jsonrpc": "2.0", "id": req_id,
|
|
"error": _err(-32601, "method not found: %r" % method)}
|
|
|
|
|
|
def _drain_remote(browser):
|
|
"""Main-thread only: poll the file bridge (control, inputs,
|
|
frame, state). Called on every loop iteration so remote input
|
|
lands even while no JSON-RPC request is in flight."""
|
|
bridge = _get_bridge(browser)
|
|
if bridge is None:
|
|
return
|
|
try:
|
|
bridge.poll(browser)
|
|
except Exception as exc: # noqa: BLE001 - bridge best-effort
|
|
print("playwright_mcp: bridge poll error: %s" % exc,
|
|
file=sys.stderr)
|
|
|
|
|
|
def main():
|
|
import select
|
|
browser = _get_browser()
|
|
# Frame sink must be set before any navigate so pump_screencast
|
|
# has frames for the bridge to publish. No bridge (missing
|
|
# module) means no sink either, so frames are dropped instead
|
|
# of accumulating unboundedly in a queue nobody drains.
|
|
if _get_bridge(browser) is not None:
|
|
browser.set_frame_sink(_frame_queue())
|
|
buffer = ""
|
|
while True:
|
|
_drain_remote(browser)
|
|
try:
|
|
readable, _, _ = select.select([sys.stdin], [], [], 0.05)
|
|
except Exception: # noqa: BLE001 - stdin gone
|
|
break
|
|
if not readable:
|
|
continue
|
|
chunk = sys.stdin.readline()
|
|
if not chunk:
|
|
break
|
|
line = chunk.strip()
|
|
if not line:
|
|
continue
|
|
try:
|
|
request = json.loads(line)
|
|
except json.JSONDecodeError as exc:
|
|
sys.stdout.write(json.dumps(
|
|
{"jsonrpc": "2.0", "id": None,
|
|
"error": _err(-32700, "parse error: %s" % exc)}) + "\n")
|
|
sys.stdout.flush()
|
|
continue
|
|
try:
|
|
response = handle_request(request, browser)
|
|
except Exception as exc: # noqa: BLE001 - server must not die
|
|
print("playwright_mcp: handler error: %s" % exc,
|
|
file=sys.stderr)
|
|
if "id" in request:
|
|
response = {"jsonrpc": "2.0", "id": request["id"],
|
|
"error": _err(-32603, "internal error")}
|
|
else:
|
|
response = None
|
|
if response is not None:
|
|
sys.stdout.write(json.dumps(response) + "\n")
|
|
sys.stdout.flush()
|
|
|
|
|
|
def _frame_queue():
|
|
try:
|
|
from playwright_remote import SimpleQueue
|
|
except ImportError:
|
|
try:
|
|
from cloud.playwright_remote import SimpleQueue
|
|
except ImportError:
|
|
import collections
|
|
import threading
|
|
|
|
class SimpleQueue: # noqa: D101 - last-resort fallback
|
|
def __init__(self):
|
|
self._deque = collections.deque()
|
|
self._lock = threading.Lock()
|
|
|
|
def put(self, item):
|
|
with self._lock:
|
|
self._deque.append(item)
|
|
|
|
def get_nowait(self):
|
|
with self._lock:
|
|
if not self._deque:
|
|
raise IndexError("queue empty")
|
|
return self._deque.popleft()
|
|
return SimpleQueue()
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|