haden-browser

haden-browser 是一个快速、以 AI 为先的网页浏览器，以本地 Model Context Protocol 服务器的形式提供。它根据 AI 当前的目标，为其提供最小可用的页面表示，而不是在每次交互时都发送截图和原始页面源码。

基准测试：AI 浏览器上下文减少 33%

主要结果： Haden 在核心浏览会话中使用了 7,822 个参考 token——比 Playwright MCP 少 32.7%，比 Chrome DevTools MCP 完整模式少 32.5%。在测试的返回语义操作引用和图片 alt 覆盖的浏览器 MCP 中，Haden 的 token 占用最低。

† Chrome Slim 是绝对的 token 最小值，但它是一个低层 JavaScript 控制基线：模型必须编写页面脚本，且测试路径未返回语义操作引用或图片 alt 文本。因此它以透明方式显示，但不被视为语义浏览器的等价物。

核心上下文包括一次完整的工具模式加载，以及文章阅读、表单提交和计算样式检查的序列化 MCP 工具调用和结果。计数使用 o200k_base tokenizer。图片像素、用户/系统提示词以及模型推理或散文被排除在外，因此实际计费用量取决于 MCP 主机和模型。

参见完整基准测试报告、每次运行的原始数据和复现说明。

Related MCP server: browsegrab

为什么它与众不同

• 基于目标的视图 — 研究时使用紧凑的语义文本，结构时使用净化后的 DOM，视觉工作时使用有界的计算样式。

• 图片保持惰性 — 图片以其 alt 文本或 [image img1] 表示。仅当 AI 显式调用 haden_image 时才返回像素数据。

• 低往返控制 — 每次交互都返回新的快照，因此大多数点击/输入流程每步只需一次工具调用。

• 稳定的操作引用 — 可见控件变为 e1、e2 等，这比让模型自行发明 CSS 选择器更便宜、更可靠。

• 默认快速 — 普通浏览期间会阻止图片、媒体和字体请求。视觉视图仍可使用 CSS。

• 更安全的本地执行 — 非 HTTP 协议、包含凭据的 URL 和私有网络目标会被阻止，除非用户明确选择允许。

flowchart LR
    AI[AI / MCP host] -->|stdio tools| MCP[haden-browser]
    MCP --> PW[Playwright Chromium]
    PW --> PAGE[Web page]
    PAGE -->|semantic text / DOM / computed CSS| MCP
    MCP -.->|only haden_image imgN| PIXELS[Image bytes]
    PIXELS -.-> AI

视图

text 是默认视图，除非任务确实需要结构或呈现细节，否则应优先使用。

MCP 工具

文本输出示例：

# Example Domain
URL: https://example.com/
View: text
Interactive elements: 1
Images: 1 (use haden_image with an img ref only when visual inspection is needed)

# Example Domain
This domain is for use in illustrative examples.
[e1] link "More information" -> https://iana.org/domains/example
[image img1: "Example diagram"]

引用仅限于最新快照。在页面发生重大变化后，请重新读取后再复用旧的 e 或 img 引用。

要求

• Node.js 20 或更高版本

• 通过 Playwright 安装 Chromium

从此仓库安装

git clone https://github.com/Haden-Min/haden-browser.git
cd haden-browser
npm ci
npm run setup-browser
npm run build

然后配置 MCP 主机以启动构建后的 stdio 服务器。在实际配置中使用绝对路径：

{
  "mcpServers": {
    "haden-browser": {
      "command": "node",
      "args": ["/absolute/path/to/haden-browser/dist/index.js"]
    }
  }
}

在开发期间，主机可以启动 npx tsx /absolute/path/to/haden-browser/src/index.ts 代替。

包发布到 npm 后，预期的配置是：

{
  "mcpServers": {
    "haden-browser": {
      "command": "npx",
      "args": ["-y", "haden-browser"]
    }
  }
}

在该机器上首次调用浏览器之前，运行一次 npx playwright install chromium。

配置

布尔变量接受 true/false、1/0、yes/no 和 on/off。

本地开发页面

私有主机默认被阻止以降低 SSRF 风险。要浏览 localhost 上的应用程序，仅针对该 MCP 进程选择允许：

{
  "mcpServers": {
    "haden-browser-local": {
      "command": "node",
      "args": ["/absolute/path/to/haden-browser/dist/index.js"],
      "env": { "HADEN_ALLOW_PRIVATE_HOSTS": "true" }
    }
  }
}

开发

npm install
npm run setup-browser
npm run check
npm run build

测试套件涵盖网络策略、文本整形、真实 Chromium 提取、基于引用的交互、惰性图片检索以及内存中的 MCP 客户端/服务器连接。

当前限制

• 每个 stdio MCP 连接维护一个活动浏览器上下文。

• 图片引用目前覆盖可见的 HTML <img> 元素，不包括 CSS 背景图片、画布、视频帧或 iframe 内容。

• 视觉视图报告计算属性；它不会转储每个样式表规则。

• 下载、文件上传、浏览器扩展、持久化配置文件和 CAPTCHA 解决不在 MVP 范围内。

• 私有主机过滤降低了 SSRF 暴露，但在敌意多租户环境中不能替代操作系统/容器级别的网络隔离。

参见 CONTRIBUTING.md 了解开发指南，SECURITY.md 了解漏洞报告。

许可证

MIT