blowsh-mcp

Сервер Model Context Protocol для терминального браузера с поддержкой JS на базе Browsh

Что такое blowsh-mcp?

blowsh-mcp — это сервер Model Context Protocol (MCP), который открывает возможности Browsh — полностью поддерживающего JavaScript терминального браузера — для любого AI-агента, IDE-агента или MCP-клиента. Этот проект позволяет вашему ИИ получать и отображать любые современные веб-страницы, в том числе требующие JavaScript, и получать результат в виде легко разбираемого обычного текста, HTML или Markdown.

Мнемоника: «blowsh» = MCP-сервер на базе Browsh.

Related MCP server: openmcp

Ключевые возможности

• Инструмент fetch_web: единый инструмент для извлечения читаемого обычного текста, HTML или Markdown (после полного рендеринга JS). Поддерживает извлечение по CSS selector, ограничение вывода max_chars и опрос wait_ms для ожидания завершения JS.

• Инструмент search_web: поиск страниц через отрендеренную поисковую систему (DuckDuckGo HTML с запасным вариантом Bing) — ранжированные результаты с URL и сниппетами.

• Инструмент extract_links: выводит список гиперссылок (текст + абсолютный URL) с любой JS-отрендеренной страницы для последующей навигации.

• Инструмент fetch_web_batch: загрузка до 10 URL за один вызов с изоляцией ошибок по каждому URL.

• Защита SSRF: отклоняет запросы к loopback, частным, link-local или зарезервированным адресам (с резолвингом DNS), защищая серверный браузер.

• AI-оптимизированная документация инструментов: входные и выходные данные, а также иллюстрированные примеры использования, предназначенные для бесшовной автоматизации агентов. Инструменты генерируют структурированные ошибки с HTTP-статус кодами (isError в ответах MCP).

• Надёжное управление Browsh: запускает Browsh один раз, поддерживает его работу, переиспользует лёгкий по RAM/CPU синглтон, корректно завершает работу при выходе.

• Кэш рендеринга в памяти с TTL: повторные запросы обслуживаются мгновенно без повторного рендеринга.

• Разработан для PaaS, облака, локальных AI-инструментов и IDE-агентов.

Ссылки

• Browsh CLI Browser — Движок рендеринга.

• Firefox — Требуется в качестве бэкенда для Browsh.

• Model Context Protocol (MCP) Specification — Протокол взаимодействия агента и сервера.

Как это работает

1. AI/агент отправляет MCP-запрос: fetch_web (один URL), search_web (запрос), extract_links (URL) или fetch_web_batch (до 10 URL).

2. blowsh-mcp запускает Browsh в режиме HTTP-сервера (при первом использовании) и переиспользует его для всех последующих вызовов.

3. blowsh-mcp запрашивает исходный вывод от Browsh, используя X-Browsh-Raw-Mode: PLAIN (для текста), DOM (для HTML), или получает HTML и затем преобразует его в Markdown.

4. Страница (после полного выполнения JS) возвращается как терминальный обычный текст, насыщенный HTML DOM или чистый Markdown — AI/агенты выбирают тип вывода в соответствии с дальнейшей обработкой.

5. Результаты кэшируются в памяти (TTL), поэтому повторные запросы выполняются мгновенно; каждый запрос проверяется на SSRF перед отправкой в браузер.

Быстрый старт (Docker — готовый образ)

Образ публикуется в GitHub Container Registry и автоматически пересобирается при каждом пуше в main через GitHub Actions — не требуется устанавливать Firefox/Browsh/html2markdown на хосте:

docker pull ghcr.io/mokhtarabadi/blowsh-mcp:latest
docker run --rm -i ghcr.io/mokhtarabadi/blowsh-mcp:latest

Флаг -i обязателен: MCP-сервер общается по JSON-RPC через stdin/stdout. Оставьте его интерактивным и передавайте запросы через конвейер или укажите ваш MCP-клиент на него (см. Конфигурация AI-клиента ниже).

Пример использования

Из Claude, Cursor или любого MCP-совместимого агента:

{
  "tool": "search_web",
  "params": { "query": "bitcoin price today", "max_results": 5 }
}
// → Ranked results with URLs + snippets → feed top URL to fetch_web

{
  "tool": "fetch_web",
  "params": { "url": "https://coindesk.com/price/bitcoin/", "type": "plain" }
}
// → Returns readable plain text (live price as text table, etc)

{
  "tool": "fetch_web",
  "params": { "url": "https://coindesk.com/price/bitcoin/", "type": "markdown", "selector": "main", "wait_ms": 3000 }
}
// → Markdown of <main> only, after JS settles ("# Bitcoin Price\n\n| Time | Price | ...")

{
  "tool": "extract_links",
  "params": { "url": "https://example.com", "limit": 20 }
}
// → [{"text": "Learn more", "url": "https://iana.org/domains/example"}, ...]

{
  "tool": "fetch_web_batch",
  "params": { "urls": ["https://a.com", "https://b.com"], "type": "markdown" }
}
// → Per-URL results; a failing page never fails the batch

AI получает:

• С type: plain: чистый читаемый текст (таблицы, списки, основное содержимое; идеально для NLP/суммаризации или приёма в терминал).

• С type: html: полная HTML-разметка после выполнения всего JavaScript. Используйте для разбора элементов, построения графа ссылок, сложного скрейпинга и т.д.

• С type: markdown: чистая Markdown-версия — лучше всего подходит для контекстных блоков LLM, семантических конвейеров и AI-ориентированного потребления/рабочих процессов.

• Ошибки структурированы: MCP-ответы устанавливают isError: true с сообщением FetchError, включающим HTTP-статус, когда он доступен.

Структура проекта

• src/server.ts — MCP-сервер, предоставляющий инструменты.

• src/browshManager.ts — Запуск, мониторинг и завершение Browsh.

• src/tools/fetchWeb.ts — Реализация инструмента fetchWeb (plain, html, markdown; selector/max_chars/wait_ms).

• src/tools/searchWeb.ts — search_web (парсер DuckDuckGo HTML + запасной вариант Bing).

• src/tools/extractLinks.ts — extract_links (гиперссылки из отрендеренного DOM).

• src/tools/fetchWebBatch.ts — fetch_web_batch (несколько URL, изоляция ошибок по каждому URL).

• src/tools/html2markdownManager.ts — Обёртка для CLI html2markdown.

• src/ssrf.ts — Защита SSRF (блокирует частные/loopback/зарезервированные цели).

• src/cache.ts — Кэш рендеринга в памяти с TTL.

• src/extract.ts — Извлечение основного содержимого, вспомогательные функции для selector, усечение.

• src/errors.ts — FetchError + форматирование сообщений.

• README.md — Этот файл.

• Dockerfile — Многоступенчатый контейнер (собирает TS, включает Firefox, Browsh, html2markdown).

• .github/workflows/docker-publish.yml — CI/CD: собирает и публикует образ в ghcr.io при пушах в main/v*.

• .env — Переопределения конфигурации. Все опции см. в .env.example.

Установка

Требования:

• Node.js >= 20.18

• Firefox установлен и доступен в PATH

• Browsh CLI установлен и доступен в PATH

• html2markdown CLI установлен и доступен в PATH

  • На Debian/Ubuntu установите с помощью:

    wget -O /tmp/html2markdown.deb "https://github.com/JohannesKaufmann/html-to-markdown/releases/download/v2.5.2/html2markdown_2.5.2_linux_amd64.deb"
    sudo apt-get install -y /tmp/html2markdown.deb
    rm /tmp/html2markdown.deb

  • Или используйте готовый бинарный файл для вашей ОС со страницы релизов.

Предпочитаете Docker? Полностью пропустите установку на хосте — многоступенчатый образ включает Firefox, Browsh и html2markdown. Самый быстрый путь — опубликованный образ (ghcr.io/mokhtarabadi/blowsh-mcp:latest, см. Быстрый старт); чтобы собрать его самостоятельно:

docker build -t blowsh-mcp:latest .
docker run --rm -i blowsh-mcp:latest

git clone https://github.com/mokhtarabadi/blowsh-mcp.git
cd blowsh-mcp
npm install
npm run build

Запуск MCP-сервера

После сборки запустите сервер, используя:

node dist/server.js

Замените dist/server.js на правильный путь, если вывод вашей сборки отличается.

При необходимости создайте файл .env для конфигурации. Например:

MCP_TRANSPORT=stdio
BROWSH_FIREFOX_PATH=/usr/bin/firefox-esr
HTML2MARKDOWN_PATH=html2markdown
CACHE_TTL_MS=300000
BROWSH_REQUEST_TIMEOUT_MS=30000
ALLOW_PRIVATE_URLS=false
NODE_ENV=production

• BROWSH_FIREFOX_PATH позволяет настроить исполняемый файл Firefox, используемый Browsh во время headless/HTTP-работы.

• HTML2MARKDOWN_PATH позволяет указать свой путь к бинарному файлу html2markdown (по умолчанию: html2markdown в PATH).

• CACHE_TTL_MS, BROWSH_REQUEST_TIMEOUT_MS и ALLOW_PRIVATE_URLS настраивают соответственно кэш рендеринга, тайм-аут запроса и защиту SSRF.

• HTTP-порт/хост Browsh не настраиваются.

Документация проекта

Этот README — пользовательская точка входа; правила для агентов находятся в AGENTS.md и обязательны к прочтению перед любой реализацией.

API инструментов

Возвращает

• type: plain: терминальный, выполненный через JS читаемый текст (или строка ошибки).

• type: html: строка HTML-разметки после JS (или строка ошибки). С selector — только HTML соответствующего элемента.

• type: markdown: преобразование основного содержимого или выбранного элемента в Markdown (или строка ошибки). Ссылки, заголовки, списки и структура страницы сохраняются для AI-ориентированного контекста.

• type: pdf: извлечённый обычный текст из PDF-документа (через pdftotext, лимит 20 МБ).

• Ошибки структурированы: MCP-ответ с isError: true и сообщением FetchError, включающим HTTP-статус, когда он известен (никогда не бывает молчаливой пустой строки).

Переменные окружения

Задайте их через .env (загружается автоматически) или через окружение:

Выбор инструментов с помощью ИИ

• Начните с search_web: Чтобы обнаружить страницы, выполните запрос и выберите лучшие URL-адреса результатов; затем загрузите их.

• Используйте fetch_web для отдельных страниц: plain — когда нужен быстрый читаемый вывод для суммаризации/классификации; html — для разбора элементов, ссылок или таблиц; markdown — для удобных для LLM фрагментов контекста. Добавляйте selector/max_chars/wait_ms, чтобы экономить токены и получать стабильный релевантный контент.

• Используйте extract_links перед глубоким обходом: Следуйте по навигации без лишних затрат, вместо загрузки полных DOM-деревьев.

• Используйте fetch_web_batch для нескольких источников: Один вызов вместо N обращений; сбои изолированы для каждого URL.

Обработка ошибок: Инструменты выбрасывают FetchError, а MCP возвращает isError: true с практическим сообщением — недопустимые протоколы, блокировки SSRF, несовпадающие селекторы, коды состояния HTTP и ошибки рендеринга никогда не остаются незамеченными.

Протокол MCP: настройка ИИ-клиента

Перед настройкой вашего ИИ-клиента (Claude, Cursor и т.д.) необходимо

1. Установить зависимости: npm install

2. Собрать проект: npm run build

3. Запустить MCP-сервер из скомпилированного вывода: node dist/server.js

Пример конфигурации для Claude Desktop или Cursor:

{
  "mcpServers": {
    "blowsh": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {}
    }
  }
}

Пример конфигурации для opencode (файл проекта opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "blowsh": {
      "type": "local",
      "command": ["docker", "run", "--rm", "-i", "ghcr.io/mokhtarabadi/blowsh-mcp:latest"],
      "enabled": true,
      "timeout": 120000
    }
  },
  "permission": { "blowsh_*": "allow" }
}

Docker-вариант не требует бинарных файлов на хосте; образ включает Firefox, Browsh и html2markdown. Перезапустите opencode после сохранения (конфигурация загружается один раз при запуске).

Плавное завершение работы

blowsh-mcp перехватывает SIGINT/SIGTERM и гарантирует чистое завершение Browsh — без осиротевших процессов браузера.

Безопасность и рекомендации

• Сервер запускает Browsh локально и выполняет запросы через HTTP localhost.

• Защита SSRF: По умолчанию fetch_web/search_web/extract_links/fetch_web_batch отказываются от URL-адресов, которые разрешаются в loopback, частные, link-local или зарезервированные IP-диапазоны (проверяется через DNS). Установите ALLOW_PRIVATE_URLS=true, чтобы отключить — не рекомендуется.

• Нет публичного доступа, если явно не настроен MCP HTTP/streamable сервер.

• Никогда не открывайте порты в открытый веб без межсетевого экрана.

• Используйте переменные окружения для секретов/конфигурации.

Расширение

Добавляйте новые инструменты в src/tools/, экспортируйте их в src/server.ts и документируйте.
ИИ-клиенты автоматически найдут docstrings.

Устранение неполадок

• Если fetchPlain возвращает 404 или не удаётся отрендерить JS: проверьте, что Firefox и Browsh установлены и находятся в PATH.

• Если Firefox не найден или не запускается, установите BROWSH_FIREFOX_PATH в .env, указав полный путь до вашей установки Firefox.

• Порт/хост Browsh фиксированы — нет ни переменной окружения, ни параметра CLI для их изменения.

• Для максимальной безопасности запускайте в контейнере.

Лицензия

MIT

Автор: Mohammad Reza Mokhtarabadi mmokhtarabadi@gmail.com