Blueprint MCP Server

официальный

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

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

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
Расширение требует явного действия пользователя для подключения
Все действия браузера проходят через систему разрешений браузера

Нашли проблему безопасности? Пожалуйста, напишите на [email protected] вместо создания публичной задачи.

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

Этот проект изначально был вдохновлён реализацией 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