webshot-mcp

Дайте вашему агенту глаза — без предоставления браузера или вашей сети. MCP-сервер с двумя инструментами: screenshot и page_text. Он подключается к уже запущенному Chrome (через CDP) и делает снимки полных страниц или отдельных элементов. Никакой браузер не запускается и не загружается; цели в частных сетях блокируются политикой URL, устойчивой к SSRF.

Зачем это нужно

Два урока из практики циклов «визуальная проверка → исправление» с агентами кодирования:

1. Запуск браузера для каждого скриншота — медленный и ненадёжный способ. Постоянный headless Chromium (Docker-сайдкар, CI-сервис, ваш десктопный Chrome с флагом --remote-debugging-port) — это прогретый, общий и надёжный ресурс. Не хватало дисциплинированного клиента: подключение через CDP, открытие свежего контекста для каждого снимка, закрытие только того, что открыли, и никогда — завершение общего браузера. Эта дисциплина и есть данный репозиторий.

2. Инструмент для скриншотов внутри вашей сети — это SSRF-прокси с камерой. Агента можно уговорить сделать «скриншот http://169.254.169.254/…» или http://redis.internal:6379/, и он с радостью сфотографирует ваш endpoint метаданных облака. Поэтому политика URL блокирует loopback, RFC-1918, link-local, CGNAT и v6-local цели — включая доменные имена, которые резолвятся в них — если вы явно не внесёте имя хоста в белый список. Локальные серверы разработки — легитимное исключение, и вы называете их по одному.

Быстрый старт

npm install
npm test        # URL-policy test suite — no browser needed
npm run demo    # policy walkthrough + a real screenshot if a CDP Chrome is reachable

Получите Chrome с включённым CDP (любой из вариантов):

# your installed Chrome, headless
chrome --headless --remote-debugging-port=9222 --remote-debugging-address=127.0.0.1 about:blank

# or a Docker sidecar you keep running
docker run -d -p 127.0.0.1:9222:9222 chromedp/headless-shell

Подключите к Claude Code:

claude mcp add webshot \
  -e WEBSHOT_CDP_URL=http://127.0.0.1:9222 \
  -e WEBSHOT_ALLOW_HOSTS=localhost,127.0.0.1 \
  -- npx tsx src/server.ts

Затем попросите агента что-то вроде «сделай скриншот секции hero на localhost:5173 — только .hero — и скажи, что не так»: selector обрезает до одного элемента, что фокусирует внимание агента (и ваши токены) на обсуждаемой части, а не на странице высотой 4000 пикселей.

Инструменты

Замечания по дизайну

• Свежий контекст на каждый снимок, общий браузер на всё время работы. Контексты дешёвы и изолированы (cookies, кеш, viewport); браузер дорог и общий. browser.close() на CDP-соединении отключает, не убивая удалённый браузер — сервер может перезапускаться весь день, не трогая Chrome.

• DNS проверяется, rebinding документирован. Не-IP-адреса резолвятся, и каждый возвращённый адрес повторно проверяется на принадлежность к частным диапазонам. Вредоносный DNS-сервер, который на втором разрешении браузером отвечает иначе (классический rebinding), выходит за рамки инструмента для скриншотов — отмечено здесь, а не замолчано.

• deviceScaleFactor: 2 — retina-снимки, потому что агенты (и люди) ошибочно читают размытый текст на скриншотах чаще, чем можно подумать.

• Политика — fail-closed и тестируема. evaluateUrl — чистая функция со всей таблицей угроз в её тестовом файле; сервер никогда не вызывает браузер, пока политика не скажет «да».

Стек

TypeScript · @modelcontextprotocol/sdk (stdio) · playwright-core (только CDP-клиент — без встроенных браузеров) · zod · vitest.

Лицензия

MIT © Brandon Ta