Blueprint MCP

официальный

Автоматизация браузера через MCP для Chrome и Firefox

GitHub

Что можно делать с Blueprint MCP?

Навигация и чтение страниц в вашем реальном браузере — Попросите ассистента перейти по URL с помощью browser_navigate и извлечь доступное содержимое через browser_snapshot или browser_extract_content.
Взаимодействие с элементами страницы — Используйте browser_interact или browser_click, browser_type, browser_fill_form и browser_select_option для кликов, ввода текста, заполнения форм и выбора параметров из выпадающих списков.
Мониторинг сетевой активности — Просматривайте, фильтруйте и воспроизводите захваченные запросы с помощью browser_network_requests, включая фильтрацию по JSONPath в телах ответов.
Захват визуального состояния — Сделайте скриншот текущей страницы с помощью browser_take_screenshot или сохраните её как PDF, используя browser_pdf_save.
Управление вкладками и окнами — Выводите список, создавайте, подключайтесь к вкладкам или закрывайте их через browser_tabs, а также изменяйте размер или сворачивайте окно с помощью browser_window.
Выполнение пользовательского JavaScript и работа с диалогами — Запускайте произвольные скрипты на странице, используя browser_evaluate, и управляйте оповещениями, подтверждениями или подсказками с помощью browser_handle_dialog.

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

Blueprint MCP

Управляйте своим реальным браузером с помощью ИИ через Model Context Protocol

Что это?

MCP-сервер (Model Context Protocol), который позволяет ИИ-ассистентам управлять вашим реальным браузером (Chrome, Firefox или Opera) через браузерное расширение. В отличие от инструментов headless-автоматизации, здесь используется ваш настоящий профиль браузера со всеми активными сеансами, файлами cookie и расширениями.

Идеально для: ИИ-агентов, которым нужно взаимодействовать с сайтами, где вы уже авторизованы, или которым требуется избегать обнаружения ботов.

Зачем использовать это вместо Playwright/Puppeteer?

Blueprint MCP	Playwright/Puppeteer
✅ Реальный браузер (не headless)	❌ Headless или новый экземпляр браузера
✅ Остаётся авторизованным на всех ваших сайтах	❌ Необходима повторная аутентификация каждый сеанс
✅ Избегает обнаружения ботов (использует реальный отпечаток)	⚠️ Часто определяется как автоматизированный браузер
✅ Работает с вашими существующими расширениями браузера	❌ Нет поддержки расширений
✅ Нулевая настройка — работает «из коробки»	⚠️ Требуется установка браузера
✅ Поддержка Chrome, Firefox, Edge, Opera	✅ Поддержка Chrome, Firefox, Safari

Установка

1. Установите MCP-сервер

npm install -g @railsblueprint/blueprint-mcp

2. Установите браузерное расширение

Выберите ваш браузер:

Chrome / Edge / Opera

Chrome Web Store (работает для всех браузеров на Chromium)
Вручную: Скачайте из Releases, затем загрузите распакованное расширение по адресу chrome://extensions/ (Chrome), edge://extensions/ (Edge) или opera://extensions/ (Opera)

Firefox

Firefox Add-ons
Вручную: Скачайте из Releases, затем загрузите по адресу about:debugging#/runtime/this-firefox

3. Настройте ваш MCP-клиент

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["@railsblueprint/blueprint-mcp@latest"]
    }
  }
}

Claude Code (CLI на базе ИИ):

claude mcp add browser npx @railsblueprint/blueprint-mcp@latest

VS Code / Cursor (.vscode/settings.json):

{
  "mcp.servers": {
    "browser": {
      "command": "npx",
      "args": ["@railsblueprint/blueprint-mcp@latest"]
    }
  }
}

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

Запустите ваш MCP-клиент (Claude Desktop, Cursor и т. д.)
Нажмите на значок расширения Blueprint MCP в вашем браузере
Расширение автоматически подключается к MCP-серверу
Попросите вашего ИИ-ассистента начать просмотр!

Примеры диалогов:

You: "Go to GitHub and check my notifications"
AI: *navigates to github.com, clicks notifications, reads content*

You: "Fill out this form with my info"
AI: *reads form fields, fills them in, submits*

You: "Take a screenshot of this page"
AI: *captures screenshot and shows you*

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

┌─────────────────────────┐
│   AI Assistant          │
│   (Claude, GPT, etc)    │
└───────────┬─────────────┘
            │
            │ MCP Protocol
            ↓
┌─────────────────────────┐
│   MCP Client            │
│   (Claude Desktop, etc) │
└───────────┬─────────────┘
            │
            │ stdio/JSON-RPC
            ↓
┌─────────────────────────┐
│   blueprint-mcp         │
│   (this package)        │
└───────────┬─────────────┘
            │
            │ WebSocket (localhost:5555 or cloud relay)
            ↓
┌─────────────────────────┐
│   Browser Extension     │
└───────────┬─────────────┘
            │
            │ Browser Extension APIs
            ↓
┌─────────────────────────┐
│   Your Browser          │
│   (real profile)        │
└─────────────────────────┘

Бесплатная версия против PRO

Бесплатный уровень (по умолчанию)

✅ Локальное WebSocket-соединение (порт 5555)
✅ Один экземпляр браузера
✅ Все функции автоматизации браузера
✅ Учётная запись не требуется
❌ Ограничено одной машиной

Уровень PRO

✅ Облачный ретранслятор — подключайтесь откуда угодно
✅ Несколько браузеров — управляйте несколькими экземплярами браузера
✅ Совместный доступ — несколько ИИ-клиентов могут использовать один браузер
✅ Автопереподключение — поддерживает соединение при смене сети
✅ Приоритетная поддержка

Перейти на PRO

Доступные инструменты

MCP-сервер предоставляет ИИ-ассистентам следующие инструменты:

Управление соединением

enable — Активировать автоматизацию браузера (необходимый первый шаг)
disable — Деактивировать автоматизацию браузера
status — Проверить статус соединения
auth — Войти в учётную запись PRO (для функций облачного ретранслятора)

Управление вкладками

browser_tabs — Список, создание, прикрепление или закрытие вкладок браузера

Контент и инспекция

browser_snapshot — Получить доступное содержимое страницы (рекомендуется для чтения страниц)
browser_take_screenshot — Сделать визуальный снимок экрана
browser_console_messages — Получить логи консоли браузера
browser_network_requests — Мощный инструмент мониторинга сети и воспроизведения с несколькими действиями:
- Режим списка (по умолчанию): Облегчённый обзор с фильтрацией и пагинацией (по умолчанию: 20 запросов)
  - Фильтры: urlPattern (подстрока), method (GET/POST), status (200/404), resourceType (xhr/fetch/script)
  - Пагинация: limit (по умолчанию: 20), offset (по умолчанию: 0)
  - Пример: action='list', urlPattern='api/users', method='GET', limit=10
- Режим деталей: Полные данные запроса/ответа для конкретного запроса, включая заголовки и тела
- Фильтрация JSONPath: Запрос больших JSON-ответов с использованием синтаксиса JSONPath (например, $.data.items[0])
- Режим воспроизведения: Повторное выполнение захваченных запросов с оригинальными заголовками и аутентификацией
- Режим очистки: Очистка захваченной истории для освобождения памяти
- Пример: action='details', requestId='12345.67', jsonPath='$.data.users[0]'
browser_extract_content — Извлечь содержимое страницы как markdown

Взаимодействие

browser_interact — Выполнить несколько действий последовательно (клик, ввод, наведение, ожидание и т. д.)
browser_click — Кликнуть по элементам
browser_type — Ввести текст в поля ввода
browser_hover — Навести курсор на элементы
browser_select_option — Выбрать опции из выпадающих списков
browser_fill_form — Заполнить несколько полей формы одновременно
browser_press_key — Нажать клавиши клавиатуры
browser_drag — Перетащить элементы

Продвинутые

browser_evaluate — Выполнить JavaScript в контексте страницы
browser_handle_dialog — Обработать диалоги alert/confirm/prompt
browser_file_upload — Загрузить файлы через поля ввода файлов
browser_window — Изменить размер, свернуть, развернуть окно браузера
browser_pdf_save — Сохранить текущую страницу как PDF
browser_performance_metrics — Получить метрики производительности
browser_verify_text_visible — Проверить наличие текста (для тестирования)
browser_verify_element_visible — Проверить существование элемента (для тестирования)

Управление расширениями

browser_list_extensions — Список установленных расширений браузера
browser_reload_extensions — Перезагрузить распакованные расширения (полезно при разработке)

Разработка

Предварительные требования

Node.js 18+
Поддерживаемый браузер (Chrome, Firefox, Edge или Opera)
npm или yarn

Настройка

# Clone the repository
git clone https://github.com/railsblueprint/blueprint-mcp.git
cd blueprint-mcp

# Install server dependencies
cd server
npm install
cd ..

# Install Chrome extension dependencies
cd extensions/chrome
npm install
cd ../..

Запуск в режиме разработки

Терминал 1: Запуск MCP-сервера в режиме отладки

cd server
node cli.js --debug

Терминал 2: Сборка расширения Chrome

cd extensions/chrome
npm run build
# or for watch mode:
npm run dev

Примечание: Расширение Firefox не требует шага сборки — оно использует ванильный JavaScript и может быть загружено напрямую из extensions/firefox/

Загрузка расширения в ваш браузер:

Для браузеров на Chromium (Chrome, Edge, Opera):

Откройте chrome://extensions/ (Chrome), edge://extensions/ (Edge) или opera://extensions/ (Opera)
Включите «Режим разработчика»
Нажмите «Загрузить распакованное расширение»
Выберите папку extensions/chrome/dist

Для Firefox:

Откройте about:debugging#/runtime/this-firefox
Нажмите «Загрузить временное дополнение»
Выберите любой файл из папки extensions/firefox

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

blueprint-mcp/
├── server/                     # MCP Server
│   ├── cli.js                  # Server entry point
│   ├── src/
│   │   ├── statefulBackend.js  # Connection state management
│   │   ├── unifiedBackend.js   # MCP tool implementations
│   │   ├── extensionServer.js  # WebSocket server for extension
│   │   ├── mcpConnection.js    # Proxy/relay connection handling
│   │   ├── transport.js        # Transport abstraction layer
│   │   ├── oauth.js            # OAuth2 client for PRO features
│   │   └── fileLogger.js       # Debug logging
│   └── tests/                  # Server test suites
├── extensions/                 # Browser Extensions
│   ├── chrome/                 # Chrome extension (TypeScript + Vite)
│   │   └── src/
│   │       ├── background.ts   # Extension service worker
│   │       ├── content-script.ts # Page content injection
│   │       └── utils/          # Utility functions
│   ├── firefox/                # Firefox extension (Vanilla JS)
│   │   └── src/
│   │       ├── background.js   # Service worker
│   │       └── content-script.js # Page injection
│   ├── shared/                 # Shared code between extensions
│   └── build-*.js              # Build scripts for each browser
├── docs/                       # Documentation
│   ├── testing/                # Test documentation
│   ├── architecture/           # Architecture docs
│   └── stores/                 # Browser store assets
└── releases/                   # Built extensions for distribution
    ├── chrome/
    ├── firefox/
    ├── edge/
    └── opera/

Тестирование

# Run tests
npm test

# Run with coverage
npm run test:coverage

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

Процедуры ручного тестирования — Подробное руководство по ручному тестированию
Спецификация функций — Полная документация по функциям
Прогресс тестирования — Текущий статус покрытия тестами

Конфигурация

Сервер работает «из коробки» с разумными настройками по умолчанию. Для расширенной конфигурации:

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

Создайте файл .env в корне проекта:

# Authentication server (PRO features)
AUTH_BASE_URL=https://blueprint-mcp.railsblueprint.com

# Local WebSocket port (Free tier)
MCP_PORT=5555

# Debug mode
DEBUG=false

Параметры командной строки

blueprint-mcp --debug              # Enable verbose logging
blueprint-mcp --port 8080          # Use custom WebSocket port (default: 5555)
blueprint-mcp --debug --port 8080  # Combine options

Примечание: Если вы измените порт, вам нужно будет обновить настройки расширения браузера соответствующим образом.

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

Расширение не подключается

Проверьте, что расширение установлено и включено
Нажмите на значок расширения — должно отображаться «Подключено»
Проверьте, что MCP-сервер запущен (ищите процесс на порту 5555)
Попробуйте перезагрузить расширение

«Порт 5555 уже используется»

Запущен другой экземпляр. Вы можете:

Завершить существующий процесс:

lsof -ti:5555 | xargs kill -9

Использовать другой порт:

blueprint-mcp --port 8080

Инструменты браузера не работают

Убедитесь, что вы сначала вызвали enable
Проверьте, что вы прикрепились к вкладке с помощью browser_tabs
Убедитесь, что вкладка всё ещё существует (не была закрыта)

Получение помощи

Участие в разработке

Мы приветствуем вклад! Смотрите CONTRIBUTING.md для руководств.

Безопасность

Этот инструмент даёт ИИ-ассистентам контроль над вашим браузером. Пожалуйста, ознакомьтесь:

MCP-сервер по умолчанию принимает только локальные соединения (localhost:5555)
Соединения PRO-ретранслятора аутентифицируются через OAuth
Расширение требует явного действия пользователя для подключения
Все действия браузера проходят через систему разрешений браузера

Нашли проблему безопасности? Пожалуйста, напишите на security@railsblueprint.com вместо создания публичной задачи.

Благодарности

Этот проект изначально был вдохновлён реализацией Playwright MCP от Microsoft, но был полностью переписан для использования автоматизации на основе браузерного расширения вместо Playwright. Архитектура, реализация и подход принципиально отличаются.

Ключевые отличия:

Использует браузерные расширения с DevTools Protocol (не Playwright)
Работает с реальными профилями браузеров (не изолированными контекстами)
Связь на основе WebSocket (не CDP relay)
Опция облачного ретранслятора для удалённого доступа
Модель с бесплатным и PRO уровнями
Поддержка нескольких браузеров (Chrome, Firefox, Edge, Opera)

Мы благодарны команде Playwright за первопроходческую работу по автоматизации браузера через MCP.

Лицензия

Apache License 2.0 — смотрите LICENSE

Создано с ❤️ командой Rails Blueprint

Веб-сайт • GitHub • NPM

Blueprint MCP

Что можно делать с Blueprint MCP?

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

Blueprint MCP

Что это?

Зачем использовать это вместо Playwright/Puppeteer?

Установка

1. Установите MCP-сервер

2. Установите браузерное расширение

3. Настройте ваш MCP-клиент

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

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

Бесплатная версия против PRO

Бесплатный уровень (по умолчанию)

Уровень PRO

Доступные инструменты

Управление соединением

Управление вкладками

Навигация

Контент и инспекция

Взаимодействие

Продвинутые

Управление расширениями

Разработка

Предварительные требования

Настройка

Запуск в режиме разработки

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

Тестирование

Конфигурация

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

Параметры командной строки

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

Расширение не подключается

«Порт 5555 уже используется»

Инструменты браузера не работают

Получение помощи

Участие в разработке

Безопасность

Благодарности

Лицензия