web-bridge — AI 편집기가 임의의 정적 웹 페이지를 조작하도록 하는 MCP 도구

web-bridge는 MCP Server(Node 단일 프로세스, 이중 인터페이스)로, AI 편집기가 client.js를 도입한 정적 웹 페이지에서 JavaScript를 실행하고 콘솔을 읽고 클릭/입력을 시뮬레이션할 수 있게 합니다. 브라우저 간, 다중 탭 로컬 연동에 적합하며, 외부 서버에 배포할 수도 있습니다(--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 捕获）  │
                           └───────────────────┘            └──────────────────┘

AI 편집기와 브라우저는 서로 직접 연결되지 않습니다: 두 연결 모두 MCP Server(server.js)에서 종료되며, AI는 도구 호출을 통해 간접적으로 페이지를 조작합니다.

빠른 시작

cd web-bridge
npm install          # 首次

1. 정적 웹 페이지에 스크립트 추가 (모든 웹 페이지, 모든 포트 가능, 교차 출처 허용됨):

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

2. MCP 서비스를 AI 편집기에 구성: mcp.json의 <REPO>/server.js를 이 저장소의 절대 경로로 바꾸고, 아래 해당 편집기 방식으로 붙여넣으세요. 편집기가 server.js를 실행하면 WebSocket 서비스(기본 127.0.0.1:3210)가 준비됩니다.

3. AI에게 말하기: “web-bridge의 list_pages로 연결된 페이지를 확인하고, eval_js로 #btn을 클릭하고 콘솔을 읽어줘”.

도입 순서 설명: 페이지가 먼저 스크립트를 도입해도 괜찮습니다. client.js가 자동으로 재연결하고(1s→2s→5s→10s 백오프), 편집기가 시작된 후 페이지가 자동으로 다시 연결됩니다. hub 상태 페이지: http://127.0.0.1:3210/

MCP 도구

pageId 규칙: 페이지가 하나만 연결된 경우 생략할 수 있습니다. 여러 페이지가 연결된 상태에서 지정하지 않으면 도구가 오류와 페이지 목록을 반환하고, AI가 스스로 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 전송 모드로 전환하면, 편집기는 MCP 구성에 url 하나만 채우면 됩니다:

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만 수신합니다. 이 컴퓨터에서 열린 모든 웹 페이지(사용자가 방문한 타사 웹사이트 포함)는 로컬 포트에 연결을 시도할 수 있습니다. 기본 토큰 없는 모드에서는 AI가 보낸 코드를 받을 수도 있고 결과를 위조할 수도 있습니다.

• 신뢰할 수 없는 네트워크 환경에서, 또는 휴대폰 등 LAN 장치를 연결하려는 경우(--host 0.0.0.0) 반드시 --token을 활성화하세요. 이 경우 client.js를 가져올 때 ?token=<secret>이 필요하며, WebSocket 첫 패킷도 토큰을 검증합니다.

WebSocket 메시지 프로토콜(내부 참조)

브라우저와 MCP Server 간 WS 메시지는 모두 JSON 텍스트 프레임입니다. lib/hub.mjs / client.js 유지 시 참조하세요:

eval 실행 규약(client.js): 먼저 표현식으로 async () => ( code )를 감싸고, SyntaxError 시 명령문 블록으로 폴백합니다(return 사용 가능). $ / $$가 사전 정의됩니다. 타임아웃은 hub 쪽에서 측정합니다(기본 30s, 최대 120s). 결과는 안전하게 문자열 미리보기로 직렬화됩니다(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(매개변수 검증); 개발 의존성 @playwright/test. Node ≥ 18.