web-bridge — MCP-инструмент, позволяющий ИИ-редактору управлять произвольными статическими веб-страницами

web-bridge — это MCP Server (один процесс Node, два интерфейса), который позволяет ИИ-редактору выполнять JavaScript на статических веб-страницах, подключивших client.js, читать консоль, имитировать клики/ввод. Подходит для локальной отладки в нескольких браузерах и вкладках, а также поддерживает развёртывание на внешнем сервере (--transport http, см. ниже «Удалённое развёртывание»).

   AI 编辑器                ┌───────────────────┐              浏览器页面
┌──────────────┐           │    MCP Server     │           ┌──────────────────┐
│  MCP Client  │           │  （Node 单进程）    │           │ <script src=     │
│              │ stdio 或   │ · 接口B: MCP       │  WebSocket │  :3210/client.js">│
│  AI 只到这里  │◄─────────►│   (stdio / http)  │◄──────────►│  client.js       │
└──────────────┘  Streamable│ · 接口A: WebSocket │  接口A     │  （eval 执行/     │
      HTTP(远程)           │ · HTTP /client.js │            │   console 捕获）  │
                           └───────────────────┘            └──────────────────┘

ИИ-редактор и браузер не соединяются напрямую: оба соединения завершаются на MCP Server (server.js), ИИ управляет страницей косвенно через вызовы инструментов.

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

cd web-bridge
npm install          # 首次

1. Подключите скрипт к статической веб-странице (подходит любая страница и любой порт, кросс-доменный доступ разрешён):

   <script src="http://127.0.0.1:3210/client.js"></script>

2. Настройте MCP-сервис в ИИ-редакторе: замените <REPO>/server.js в mcp.json на абсолютный путь к этому репозиторию и вставьте так, как показано ниже для соответствующего редактора. Как только редактор запустит server.js, WebSocket-сервис (по умолчанию 127.0.0.1:3210) будет готов.

3. Скажите ИИ: «используй list_pages из web-bridge, чтобы посмотреть, какие страницы подключены, затем eval_js помоги мне нажать #btn и прочитать консоль».

Примечание о порядке подключения: можно подключить скрипт на странице заранее — client.js будет автоматически переподключаться (с экспоненциальной задержкой 1s→2s→5s→10s), и после запуска редактора страница подключится сама. Страница состояния hub: http://127.0.0.1:3210/

Инструменты MCP

Правило pageId: если подключена только одна страница, его можно опустить; если подключено несколько страниц и pageId не указан, инструмент вернёт ошибку и список страниц, и ИИ сам добавит pageId и повторит.

Подключение в различных редакторах

В следующих примерах предполагается абсолютный путь к репозиторию /path/to/web-bridge; при необходимости замените его.

ZCode / Claude Code (в корне проекта .mcp.json или claude mcp add):

{
  "mcpServers": {
    "web-bridge": {
      "command": "node",
      "args": ["/path/to/web-bridge/server.js"],
      "env": { "PORT": "3210" }
    }
  }
}

Cursor (.cursor/mcp.json): формат тот же.

Claude Desktop (claude_desktop_config.json): формат тот же.

Аргументы командной строки: node server.js --port 3210 --host 127.0.0.1 --token <secret> (можно также использовать переменные окружения PORT / HOST / TOKEN).

Удалённое развёртывание (внешний сервер)

Обычный режим stdio требует, чтобы редактор запускал процесс локально; при развёртывании web-bridge на внешнем сервере используйте режим HTTP-транспорта — редактору достаточно указать один url в конфигурации MCP:

1. Запустите на сервере (рекомендуется управление через systemd / pm2; для публичного доступа обязательно включите токен):

node server.js --transport http --host 0.0.0.0 --port 3210 --token <secret>

2. Конфигурация редактора (Claude Code / Cursor / ZCode и др., вставьте в место исходной конфигурации):

{
  "mcpServers": {
    "web-bridge": {
      "type": "http",
      "url": "https://your-domain.com/mcp",
      "headers": { "Authorization": "Bearer <secret>" }
    }
  }
}

При прямом подключении (без обратного прокси/TLS) url укажите как http://<服务器IP>:3210/mcp. Примечание: Claude Desktop поддерживает только локальный режим stdio и не поддерживает удалённый url.

3. Скрипт на странице измените так, чтобы он указывал на сервер:

<script src="https://your-domain.com/client.js?token=<secret>"></script>

Пояснения:

• HTTPS-страницы могут подключаться только через https/wss (ограничение смешанного содержимого). Рекомендуется использовать обратный прокси, например nginx / caddy, для терминации TLS и пересылки на этот сервис; при отправке client.js автоматически распознаёт X-Forwarded-Proto / X-Forwarded-Host и формирует правильный адрес подключения wss://, без дополнительной настройки. Пример для caddy (автоматический выпуск сертификата):

  your-domain.com {
    reverse_proxy 127.0.0.1:3210
  }

• После включения токена конечная точка /mcp поддерживает три способа аутентификации: Authorization: Bearer <secret> (рекомендуется; в конфигурации редактора укажите headers), X-Web-Bridge-Token: <secret>, параметр url ?token=.

• HTTP-транспорт использует официальный протокол Streamable HTTP (режим stateless); каждый запрос обрабатывается независимо, все разделяют общий hub, и несколько редакторов могут подключаться одновременно.

• При публичном развёртывании обязательно: задайте --token, используйте TLS, в файрволе откройте только необходимые порты.

Замечания по безопасности

• По умолчанию прослушивается только 127.0.0.1. Любая открытая на этом компьютере веб-страница (включая сторонние сайты, которые вы просматриваете) может попытаться подключиться к локальному порту — в режиме без токена по умолчанию она сможет получать код от ИИ, а также подделывать результаты.

• В недоверенной сетевой среде или при необходимости подключить локальные устройства (например, телефон) через --host 0.0.0.0 обязательно включите --token: в этом случае запрос client.js должен содержать ?token=<secret>, и первый пакет WebSocket также проверяет токен.

Протокол сообщений WebSocket (внутренняя справка)

WS-сообщения между браузером и MCP Server представляют собой текстовые JSON-фреймы; используйте это при поддержке lib/hub.mjs / client.js:

Соглашения выполнения eval (client.js): сначала код оборачивается как выражение async () => ( code ); при SyntaxError происходит возврат к блоку операторов (можно использовать return); предустановлены $ / $$; тайм-аут отсчитывается на стороне hub (по умолчанию 30 с, максимум 120 с); результат безопасно сериализуется в строковое представление (Error→stack, DOM→краткое содержимое outerHTML, пометка циклических ссылок, глубина ≤ 6, ≤ 50k символов).

Разработка

• Тесты: npm test (Node e2e: запуск процесса + имитация страницы + вызов инструментов через два транспорта stdio/HTTP); npm run test:browser (сценарий с реальным браузером через Playwright: Chromium загружает test/test-page.html, через реальный WebSocket проверяются 6 инструментов; перед первым запуском выполните npx playwright install chromium). Сценарий с реальным браузером можно также проверить вручную, открыв тестовую страницу.

• Зависимости: ws (WebSocket), @modelcontextprotocol/sdk (MCP), zod (проверка параметров); dev-зависимость @playwright/test. Node ≥ 18.