haden-browser 是一个快速、以 AI 为先的网页浏览器，以本地 Model Context Protocol 服务器的形式提供。它根据 AI 当前的目标，为其提供最小可用的页面表示，而不是在每次交互时都发送截图和原始页面源码。
主要结果： Haden 在核心浏览会话中使用了 7,822 个参考 token——比 Playwright MCP 少 32.7%，比 Chrome DevTools MCP 完整模式少 32.5%。在测试的返回语义操作引用和图片 alt 覆盖的浏览器 MCP 中，Haden 的 token 占用最低。
五次运行中位数 | Haden | Playwright MCP | Chrome Slim† | Chrome Full |
核心上下文 token | 7,822 | 11,627 | 4,638 | 11,596 |
工具模式 token | 727 | 3,999 | 221 | 4,974 |
文章工作流 token | 2,732 | 4,640 | 2,497 | 4,388 |
首个可用文章 | 1,044 ms | 2,714 ms | 3,005 ms | 3,133 ms |
文章源传输 | 16.7 KB / 1 次请求 | 95.0 KB / 10 | 95.0 KB / 10 | 95.0 KB / 10 |
语义操作引用 | 15 | 172 | 0 | 143 |
图片 alt 覆盖 | 8/8 | 8/8 | 0/8 | 8/8 |
† Chrome Slim 是绝对的 token 最小值，但它是一个低层 JavaScript 控制基线：模型必须编写页面脚本，且测试路径未返回语义操作引用或图片 alt 文本。因此它以透明方式显示，但不被视为语义浏览器的等价物。
核心上下文包括一次完整的工具模式加载，以及文章阅读、表单提交和计算样式检查的序列化 MCP 工具调用和结果。计数使用 o200k_base tokenizer。图片像素、用户/系统提示词以及模型推理或散文被排除在外，因此实际计费用量取决于 MCP 主机和模型。
Related MCP server: Charlotte
基于目标的视图 — 研究时使用紧凑的语义文本，结构时使用净化后的 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视图 | 最适合 | 返回的数据 |
| 搜索、阅读、表单流程 | 标题、可见文本、带 |
| HTML 结构和属性 | 净化后的 HTML；脚本和内嵌内容已移除； |
| 布局和 CSS 推理 | 带盒子的可见有意义元素以及一组有界的计算 CSS 属性 |
text 是默认视图，除非任务确实需要结构或呈现细节，否则应优先使用。
工具 | 用途 |
| 打开一个 HTTP(S) URL 并返回其第一个快照 |
| 读取当前页面，可选地在 CSS 选择器内读取 |
| 点击、填写、选择、按键、滚动、浏览历史、刷新或等待；然后返回更新后的快照 |
| 返回最新快照中一个 |
| 报告活动页面而不启动 Chromium |
文本输出示例：
# 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。
环境变量 | 默认值 | 含义 |
|
| 无可见窗口运行 Chromium |
|
| 普通浏览期间阻止图片、媒体和字体 |
|
| 允许 localhost 和私有网络目标 |
|
| 导航和图片获取超时 |
|
| 点击、填写和定位器超时 |
|
| 默认快照字符数限制 |
|
|
|
布尔变量接受 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
Return the actual pixels for one img ref from the latest snapshot. Use only after alt text/placeholders are insufficient for the goal.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering safety. The description adds context about the data source ('latest snapshot') and output nature ('actual pixels'), but doesn't detail return format or potential edge cases, which is acceptable given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the primary action and followed by a usage condition. Every word is purposeful, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one param, no nested objects) and rich annotations (readOnly, openWorld, destructive), the description sufficiently covers what the tool does and when to use it. The absence of an output schema reduces the need to document return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With one parameter (ref) and schema description coverage of 0%, the description does not explicitly explain the parameter format. However, the schema pattern (^img\d+$) and the phrase 'one img ref' provide some meaning. The description adds minimal semantic value beyond what the schema already implies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Return the actual pixels for one img ref from the latest snapshot.' This distinguishes it from sibling tools like haden_read or haden_open by focusing on image pixel retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use the tool: 'Use only after alt text/placeholders are insufficient for the goal.' This implies alternatives (alt text/placeholders) and sets a clear condition, though it does not name specific sibling tools or list when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform one browser action and immediately return the updated snapshot, avoiding an extra read call. click/fill/select need a current e ref; press can target a ref or the page.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | ||
| ref | No | ||
| mode | No | text | |
| value | No | ||
| action | Yes | ||
| amount | No | ||
| waitMs | No | ||
| maxChars | No | ||
| direction | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the immediate return of the updated snapshot, adding value beyond the destructiveHint annotation. Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, well-structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains core behavior and return, but lacks detail on parameter usage and edge cases, which is somewhat expected given the 9 parameters and 3 enums.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only partially explains parameters (action, ref), leaving many (key, value, amount, waitMs, maxChars) undocumented. Schema enums help but description does not compensate sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it performs a browser action and returns an updated snapshot, distinguishing it from read-only siblings like read and status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to use (to avoid extra read calls) and which actions require a current ref, but does not explicitly contrast with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open an HTTP(S) URL and return an AI-optimized snapshot. text is fastest; dom returns sanitized HTML; visual adds computed layout/CSS.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| mode | No | text | |
| maxChars | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so the safety profile is clear. The description adds valuable behavioral details: returning an AI-optimized snapshot and specifying sanitized HTML for dom mode. It does not contradict annotations and offers meaningful context beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core action and then efficiently outlines mode differences. Every clause adds value; there is no fluff or redundancy. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no output schema, and moderate complexity, the description covers purpose and mode meanings but omits maxChars explanation and does not clarify what 'snapshot' encompasses beyond the modes. It is adequate but leaves room for improvement, especially since schema coverage is zero.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 0% of parameters, so the description must compensate. It effectively explains the mode parameter (text/dom/visual semantics), but fails to describe maxChars, leaving its purpose and constraints solely to the schema. Url is self-evident from its format but still lacks narrative. Given the low coverage, this is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the primary action (open an HTTP(S) URL) and the result (AI-optimized snapshot), making the purpose clear. It doesn't explicitly compare with sibling tools, but the resource and verb are specific enough to differentiate from likely 'read' or 'interact' functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on choosing output modes (text, dom, visual) with performance/reliability trade-offs, but lacks explicit direction on when to use this tool versus sibling tools like haden_read or haden_interact. The description implies usage for fetching web pages but does not state alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the current page again, optionally limited to a CSS selector. Returns stable e refs for actions and img refs for optional image retrieval.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | text | |
| maxChars | No | ||
| selector | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by disclosing that refs are stable and that image retrieval is optional. It does not contradict annotations, and the additional behavioral context (stable refs) goes beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence followed by a clarifying clause. It front-loads the core purpose and adds only high-value return info. No fluff, every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 3 parameters lacking schema descriptions, the description is incomplete. It covers the selector's purpose but ignores mode and maxChars, which are essential for understanding output types and limits. The refs info helps but does not bridge the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains 'selector' via 'optionally limited to a CSS selector', but gives no meaning for 'mode' (text/dom/visual) or 'maxChars'. This is a significant gap for effective tool invocation, as agents cannot infer the purpose of these parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the current page, optionally limited by a CSS selector, and mentions it returns stable refs for actions and images. This specific verb+resource+scope distinguishes it from siblings like haden_interact or haden_open.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it ('Read the current page again') and mentions optional selector, which suggests targeted reading. However, it does not explicitly state when NOT to use it or compare with alternatives like haden_image for visual capture, though the context is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report whether the browser is running and which page is active.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the annotations (readOnlyHint=true, destructiveHint=false) and adds a small behavioral detail: it reports the active page, not just a running flag. However, it does not disclose what happens if the browser is not running, what 'active page' means in practice, or whether the tool returns a simple boolean, a URL, or both. With annotations already signaling safety, the description adds only modest context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word earns its place: it names the action, the target resource, and the exact two pieces of information reported.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only status tool with no output schema, the description is sufficiently complete. It clearly states what the tool reports, and no additional input or prerequisite detail is needed. The absence of an output schema is compensated by specifying that the tool reports both browser-running state and active page.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema contains no properties, so the description does not need to explain parameter meaning. The baseline for a parameterless tool is 4, and the description correctly focuses on behavior rather than inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Report') and a clear resource ('whether the browser is running and which page is active'), making the tool's purpose immediately obvious. It is also clearly differentiated from sibling tools like haden_open, haden_read, haden_interact, and haden_image, which describe actions rather than state inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance about when to use this tool versus alternatives, nor any when-not-to-use conditions. The context is implied by the name and siblings, but the description does not state that this should be used before acting on the browser or how it relates to the other browser tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0haden_imagehaden_interacthaden_openhaden_readhaden_statusScored across 5 tools
Each tool has a unique, non-overlapping purpose: open, read, interact, image, and status. No ambiguity between them.
All tools follow the consistent 'haden_' prefix with clear action verbs (open, read, interact, image, status). The pattern is uniform.
Five tools provide a well-scoped set for browser automation—covering navigation, reading, interaction, visual capture, and state checking—without excess or deficiency.
The set covers core browser operations, but lacks explicit navigation controls (e.g., back, forward, refresh) and waiting mechanisms. These can be worked around via interact/open, but are minor gaps.
Web data extraction and browser workflows for AI assistants.
Reliable web access for AI agents: smart HTTP, rotating proxies, and full-browser rendering.
Web infrastructure for AI agents: scrape, crawl and search the web, run browsers and agents.
Agent-native search engine with live web research optimized for AI agents.
