haden-browser — это быстрый веб-браузер, ориентированный на ИИ, предоставляемый как локальный сервер Model Context Protocol. Он даёт ИИ наименьшее полезное представление страницы для текущей цели вместо отправки скриншотов и исходного кода страницы на каждом ходу.
Основной результат: Haden использовал 7 822 референсных токена для основной сессии просмотра — на 32,7% меньше, чем Playwright MCP, и на 32,5% меньше, чем Chrome DevTools MCP в полном режиме. Среди протестированных браузерных MCP, которые возвращали семантические ссылки на действия и покрытие alt-текста изображений, Haden показал наименьший объём токенов.
Медиана пяти запусков | Haden | Playwright MCP | Chrome Slim† | Chrome Full |
Токены основного контекста | 7,822 | 11,627 | 4,638 | 11,596 |
Токены схемы инструментов | 727 | 3,999 | 221 | 4,974 |
Токены сценария работы со статьёй | 2,732 | 4,640 | 2,497 | 4,388 |
Первая полезная статья | 1,044 ms | 2,714 ms | 3,005 ms | 3,133 ms |
Передача данных статьи от источника | 16.7 KB / 1 request | 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 — это абсолютный минимум токенов, но он представляет собой низкоуровневый базовый уровень управления через JavaScript: модель должна сама писать скрипты страницы, а протестированный путь не возвращал семантических ссылок на действия или alt-текста изображений. Поэтому он показан прозрачно, но не рассматривается как эквивалент семантического браузера.
Основной контекст включает одну полную загрузку схемы инструментов, а также сериализованные вызовы MCP-инструментов и результаты для чтения статьи, отправки формы и проверки вычисленных стилей. Подсчёт выполняется с помощью токенизатора o200k_base. Пиксели изображений, пользовательские/системные промпты и рассуждения или текст модели исключены, поэтому фактическое тарифицируемое использование зависит от MCP-хоста и модели.
См. полный отчёт о бенчмарке, исходные данные по каждому запуску и инструкции по воспроизведению.
Related MCP server: Charlotte
Целевые представления — используйте компактный семантический текст для исследований, очищенный DOM для структуры или ограниченные вычисленные стили для визуальной работы.
Изображения остаются ленивыми — изображение представлено своим alt-текстом или [image img1]. Пиксельные данные возвращаются только когда ИИ явно вызывает 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 или новее
Chromium, установленный через Playwright
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-фоновые изображения, canvas, кадры видео или содержимое 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 pages as clean Markdown and JSON for AI agents, in fewer tokens, with an Evidence Record.
Agent-native search engine with live web research optimized for AI agents.
