内容
# 浏览器 MCP 应用
一个 MCP 应用，通过 Playwright 驱动一个真正的 Chromium 浏览器，并在 MCP 主机（如 [Archestra]）内渲染一个实时的、可点击的页面视图。代理可以为您浏览，您可以在面板中接管 — 点击、输入、滚动、导航。
## 工作原理
浏览器工具（`browser_navigate`、`browser_click`、`browser_type`、`browser_press`、`browser_scroll`、`browser_back`/`forward`/`reload`、`browser_read_page`）驱动一个共享的 Playwright 页面。UI 面板轮询一个仅限应用的 `browser_screenshot` 工具（约 1 秒/次），将您的点击映射回视口像素，并转发您的按键 — 因此模型和您驱动同一个页面。
## 设置
```bash
npm install
npm run browsers # 一次性：下载 Chromium
npm run build # 将 UI 打包到 dist/mcp-app.html
```
## 运行
```bash
npm run serve # HTTP 传输在 :3001 (npm run dev = 监视模式)
npm run serve:stdio # stdio 传输
```
要从 MCP 主机（如 Archestra）使用它，请先构建，然后将主机的 MCP 配置指向 stdio 入口：
```json
{
"mcpServers": {
"browser": {
"command": "npx",
"args": ["-y", "tsx", "/绝对路径/to/browser-mcp-app/main.ts", "--stdio"]
}
}
}
```
## 配置
| 环境变量 | 默认值 | 含义 |
| --- | --- | --- |
| `HEADLESS` | 未设置 → 有头 | `1`/`true` 运行 Chromium 无头。 |
| `PORT` | `3001` | HTTP 端口。 |
| `SCREENSHOT_QUALITY` | `60` | 实时视图的 JPEG 质量。 |
## 开发
使用 **`create-mcp-app`** 代理技能构建，该技能涵盖了此处使用的 MCP 应用 SDK 模式（工具 + UI 资源注册、应用生命周期、主机上下文、轮询）。在扩展服务器时使用它 — 调用 `/create-mcp-app`。
## 注意事项
- 一个共享的浏览器页面；动作序列化，因此调用不会竞争。
- 实时视图是一个截图流 — 页面像素从不发送到模型；只有 `browser_read_page` 在请求时返回文本。
- 它是一个真正的浏览器：它可以登录和提交表单。不要指向可能会导致意外点击的站点。
[Archestra]: https://archestra.ai
[Playwright]: https://playwright.dev
