Browser MCP Demo

远程浏览器+MCP工具网关（多站点MVP）

该项目提供了一个最小的HITL（人在环）远程浏览器会话和一个用于受限搜索/提取的MCP工具网关。它目前支持XHS，并包括Yelp和TripAdvisor的真正搜索适配器。

需求

• Node.js>=18
• 剧作家Chromium(npx playwright install chromium)

安装

npm install
npx playwright install chromium

复制环境模板并根据需要进行调整：

cp .env.example .env

跑

npm run dev

这将开始：

• HTTP服务器已打开 http://HOST:PORT
• stdio上的MCP服务器（与MCP客户端连接）

Docker（单用户+无VNC）

此路径适用于单个用户（或 MAX_SESSIONS=1).它在Xvfb中运行浏览器，并通过noVNC流式传输桌面。

构建：

docker build -t browser-mcp-demo .

运行：

docker run --rm \
  -p 3000:3000 -p 7900:7900 \
  -e HOST=0.0.0.0 \
  -e HEADLESS=false \
  -e MAX_SESSIONS=1 \
  -e VIEW_MODE=novnc \
  -e PUBLIC_BASE_URL=http://YOUR_SERVER_IP:3000 \
  -e NOVNC_URL_TEMPLATE="http://YOUR_SERVER_IP:7900/vnc.html?autoconnect=1&resize=scale&path=websockify" \
  -e PROFILES_DIR=/data/profiles \
  -e AUDIT_LOG_PATH=/data/logs/audit.log \
  -e DELETE_PROFILE=false \
  -v "$PWD/profiles:/data/profiles" \
  -v "$PWD/logs:/data/logs" \
  browser-mcp-demo

笔记：

• VIEW_MODE=novnc 使 /session/view/:id 嵌入实时浏览器流。
• 更新 PUBLIC_BASE_URL 和 NOVNC_URL_TEMPLATE 使用您的公共主机或域名。

HITL登录流程

1. 调用MCP工具 create_session -> { sessionId, viewUrl }
2. 打开 viewUrl 在您的浏览器中。

- 默认模式：打开本地Chromium窗口进行登录。 - noVNC模式(VIEW_MODE=novnc)：远程浏览器流嵌入在页面中。

1. 登录该窗口（QR/OTP/2FA由用户处理）。
2. 呼叫 wait_for_login 直到状态为 READY （网站知道何时 site 提供）。

MCP工具（stdio）

工具：

• create_session
• wait_for_login （可选 site)
• platform_search （通过网站了解 site 参数）
• xhs_open_and_extract （通过网站了解 site 参数）
• destroy_session

示例（伪）：

const session = await client.callTool("create_session", {});
await client.callTool("wait_for_login", { sessionId: session.sessionId, timeoutSec: 120 });
const results = await client.callTool("platform_search", {
  sessionId: session.sessionId,
  query: "camping",
  maxNotes: 10,
  scrollTimes: 0,
  site: "xhs" // xhs | yelp | tripadvisor
});
const detail = await client.callTool("xhs_open_and_extract", {
  sessionId: session.sessionId,
  url: results.notes[0]?.url,
  site: "xhs"
});

安全边界

• 工具仅返回经过净化的结构化JSON。
• 没有Cookie、localStorage、sessionStorage、storageState或userDataDir暴露。
• 没有截图工具。
• 审计日志已写入 logs/audit.log 与编辑。

代理HTTP端点

• POST /agent/run → 开始运行并执行，直到需要登录或完成登录
• POST /agent/continue → 用户登录后继续运行
• GET /agent/run/:id → 获取当前运行状态

请求正文示例：

{
  "query": "camping",
  "maxNotes": 10,
  "scrollTimes": 0,
  "detailCount": 3,
  "detailParallel": 4,
  "site": "xhs"
}

配置

关键环境变量：

• HOST, PORT, PUBLIC_BASE_URL
• UI_DIST_DIR （从同一服务器提供内置UI）
• VIEW_MODE (info | novnc)
• NOVNC_URL_TEMPLATE （支持 {sessionId} 占位符）
• OPENAI_API_KEY, OPENAI_MODEL
• AGENT_RUN_TTL_MINUTES
• MAX_SESSIONS, SESSION_TTL_MINUTES
• PROFILES_DIR, DELETE_PROFILE
• HEADLESS
• XHS_BASE_URL
• AUDIT_LOG_PATH

备注

• XHS、Yelp和TripAdvisor都支持当前适配器层中的搜索。实现了XHS细节提取；Yelp/TripAdvisor的细节提取仍然存在问题。
• 每个站点的DOM选择器可能会发生变化。更新 src/browser/xhs.ts 或 src/sites/*.ts 如果提取中断。
• 此MVP不实现大规模爬行或反机器人绕过。