AIWebHelper

브라우저 한 창을 사람과 AI 가 같이 보는 MCP 서버. 사람은 고칠 곳을 짚고, AI 는 같은 화면을 읽고 누른다.

왜

사람은 화면을 보고 AI 는 파일을 본다. 그 사이를 스크린샷으로 이으면 서로 짐작하게 되고, 짐작은 틀린다. 「이 부분 좀 고쳐 줘」 — 「어느 부분요?」 — 스크린샷 — 「거기 말고 그 위」.

이 도구는 그 왕복을 없앤다. 사람이 Alt+클릭으로 짚으면 AI 가 이렇게 받는다:

  하고 싶은 말: 이 합계 글씨가 너무 작아요
  글자: 8,700,000원
  요소: span.v.mono.income
  선택자: div.ledg-sum span.v.mono.income
  짐작: apps/mail/src/client/ledger/  (클래스 ledg-sum)
  감싼 것: div.ledg-sum ← div.ledg-sums ← div.ledg
  ⚠ 잘림: 6px 모자람 (112px 필요, 106px 있음)
  크기: 106×23
  스타일: block · 17px · rgb(30,142,90)
  주소: http://localhost:5360/ledger/e2fa416e
  창 폭: 1000px (기기 픽셀비 2)

창 폭과 잘린 양이 같이 오는 것이 특히 값지다. 잘림은 폭에 따라 나타났다 사라져서, 「잘려요」와 「안 잘리는데요」가 둘 다 참인 일이 실제로 생긴다.

어떻게 도나

두 짝이다.

• 브라우저 확장 (extension/) — 도구 버튼이나 Alt+Shift+P 로 켠다. 켠 탭에만 붙는다. 켜기 전에는 어느 페이지에도 들어가지 않는다. 서버를 부르는 일은 확장이 대신 한다(bridge.js). 페이지에서 직접 127.0.0.1 을 부르면 사이트가 막을 수 있어서다 — X 처럼 connect-src 를 못 박아 둔 곳에서는 짚어도 「Failed to fetch」 로 끝난다. 확장은 그 벽에 걸리지 않아 어디서나 같게 돈다. (북마클릿에는 다리가 없으므로 그때는 페이지가 직접 부른다.)
• 여기 (server.js) — 짚기를 HTTP 로 받아 두고(127.0.0.1:47391), AI 에게 MCP 도구로 내준다. 반대 방향도 같은 문으로 간다 — AI 가 시킬 일을 두면 페이지가 열어 둔 물음으로 가져간다. 0.5초마다 두드리는 대신 열어 두어서, 사람이 쓰는 페이지 안에서 종일 돌아도 조용하다.

프로젝트에 심지 않는 것이 요점이다. 도구가 프로젝트를 따라다니면 프로젝트마다 다시 심어야 하고, 배포에 섞일 걱정도 생긴다.

짚기 조각(extension/picker.js)은 한 벌뿐이다. 확장이 그 파일을 넣고, 서버도 같은 파일을 /picker.js 로 내준다(북마클릿용). 두 벌을 두면 «북마클릿에서는 되는데 확장에서는 안 되는» 종류의 일이 생긴다.

포트

47391. 7000·8000·5000번대는 개발 서버가 붐벼서 언젠가 부딪히고, 부딪히면 짚기가 먼저 뜬 쪽으로 조용히 흘러간다. 그래서 문을 못 열면 모든 도구 응답 앞에 그 사실을 붙인다. AIWH_PORT 로 옮길 수 있고, 그때 /picker.js 는 자기가 듣는 포트를 박아서 내준다.

붙이기

~/.claude.json (또는 쓰는 MCP 클라이언트의 설정)에:

{
  "mcpServers": {
    "aiwebhelper": {
      "command": "node",
      "args": ["/절대/경로/AIWebHelper/server.js"]
    }
  }
}

포트를 바꾸려면 "env": { "AIWH_PORT": "47391" }.

확장 얹기 (처음 한 번)

1. 크롬에서 chrome://extensions 를 연다
2. 오른쪽 위 개발자 모드를 켠다
3. 압축해제된 확장 프로그램을 로드합니다 → 이 저장소의 extension/ 폴더를 고른다

명령줄 --load-extension 은 최근 크롬(137+)에서 막혔다. 위 세 걸음이 유일한 길이고, 한 번만 하면 된다. 엣지·웨일도 같은 자리에 있다.

북마클릿으로 쓰고 싶으면 AI 에게 «how_to_start» 를 물으면 준다 — 확장을 못 얹는 브라우저용이다.

쓰기

1. 고칠 화면으로 간다 (프로덕션이든 로컬이든)
2. 도구 버튼을 누르거나 Alt+Shift+P — 배지에 ON 이 뜬다
3. 그냥 쓴다 — 도구는 방해하지 않는다. 앱이 평소대로 돈다
4. 고칠 곳에서 Alt+클릭 → 화면 안 입력칸에 무엇을 고쳤으면 하는지 적고 Enter (비워도 된다)
5. AI 는 wait_for_pick 으로 기다리다가 그대로 받는다

켜 두면 그때부터 한 창을 같이 본다. 「이 화면 좀 봐 줘」 하면 AI 가 읽고, 「여기 눌러 봐」 하면 누른다. AI 도 「이거 말씀이신가요」를 말 대신 page_point 로 짚어 보인다.

Alt+P 로 «늘 고르기»(여러 개를 잇달아 짚을 때), Esc 로 끄기, 버튼 다시 누르면 꺼짐.

도구

사람 → AI:

wait_for_pick	사람이 짚을 때까지 기다렸다 받는다. «어디 고칠까요» 대신 부른다
latest_pick	가장 최근에 짚은 것
list_picks	최근 것들
clear_picks	비우기
how_to_start	사람에게 건넬 안내(북마클릿)

AI → 사람이 보는 그 창:

page_look	지금 화면 — 주소·글·누를 수 있는 것들
page_point	「이거 말하는 거예요」 형광펜으로 짚어 보인다
page_measure	크기·자리·글자·여백, 잘렸으면 몇 px 모자란지
page_click · page_fill · page_key	누르기 · 적기 · 키
page_goto	그 탭을 다른 주소로
page_run	나머지 전부 — 스크롤·폭 바꾸기·여러 단계
page_list	지금 켜 둔 탭들

탭이 둘 이상이면 조작 도구는 하지 않고 되묻는다. page 에 주소나 제목의 일부를 준다. 같은 주소가 둘로 보이면 짚기가 두 벌 뜬 것이라 되묻지 않고 나중 벌이 한다 — 같은 화면이니 고를 것이 없다.

page_run 은 사이트가 unsafe-eval 을 막아 두면(X 가 그렇다) 확장에게 넘겨 돌린다. 그마저 안 되는 브라우저에서는 page_measure 를 쓴다 — 재는 일에는 코드 실행이 필요 없다.

같이 보기 — 알고 쓸 것

page_* 는 사람이 로그인해 둔 진짜 창을 움직인다. 눌리면 진짜로 저장되고 발송되고 지워진다. 되돌릴 수 없다. 편한 만큼 그게 값이다.

울타리는 셋이다.

• 켠 탭에서만 돈다. 켜기 전에는 어느 페이지에도 들어가지 않는다. Esc 나 도구 버튼으로 끄면 그 자리에서 끊긴다. 배지의 ON 이 지금 이어져 있다는 표시다.
• 127.0.0.1 에만 연다. 밖에서 이 창을 움직일 길은 없다.
• 애매하면 안 누른다. 「저장」이 셋인 화면에서 첫 번째를 몰래 고르지 않고, 목록을 돌려주고 nth 로 정하게 한다. 되묻는 값은 왕복 한 번이지만 틀리는 값은 되돌릴 수 없다.

host_permissions 가 넓은 것은 켠 탭이 페이지를 옮겨도 관을 잇기 위해서다. activeTab 은 화면을 옮기면 사라져서, 켜 두고 링크 한 번만 눌러도 끊긴다. 넓은 만큼 켠 탭 목록이 유일한 울타리이므로, 안 쓸 때는 꺼 두는 편이 낫다.

고칠 때

node test.mjs

서버·확장·페이지 셋에 걸쳐 있어서, 한 곳만 고치고 올리면 나머지는 옛것으로 남는다. 그때 증상은 «고쳤는데 그대로» 라 무엇이 옛것인지 알아내는 데만 한참 걸린다 — 실제로 그렇게 새로고침을 다섯 번 되돌렸다. 브라우저 없이 20초 안에 도니 올리기 전에 한 번 돌린다.

판 번호를 세 곳에서 맞춘다 — server.js·extension/picker.js 의 AIWH_VERSION, extension/manifest.json 의 version. 시험이 검사하고, 어긋나면 서버가 도구 답 앞에 «무엇이 옛것인지» 를 붙인다.

브라우저에서만 알 수 있는 것(진짜 클릭 · 사이트의 CSP · 확장 다리)은 시험에서 안 잡힌다. 그건 확장을 새로고침하고 한 번 짚어 보는 수밖에 없다.

규칙 — 클래스에서 파일 짚기

presets/*.json 에 프로젝트마다 「클래스 접두어 → 파일 자리」를 적어 둔다. 주소로 알아서 고른다(match).

{
  "name": "내 프로젝트",
  "match": ["localhost", "example.com"],
  "rules": [{ "prefix": "ledg-", "home": "src/client/ledger/" }]
}

규칙이 없어도 된다. 요소·선택자·감싼 것·잘림·창 폭은 그대로 나온다 — 규칙은 덤이다.

이 방식이 React 의 소스 정보(_debugSource)보다 오래간다. 그건 React 19 에서 없어졌고, 프로덕션 빌드에서는 컴포넌트 이름도 압축되어 사라진다. CSS 클래스는 빌드를 지나도 남는다.

안 만든 것

• 화면 캡처. 글자·크기·잘린 양이 있으면 대개 그림이 필요 없고, 그림은 대화를 무겁게 한다.
• 앱에 심는 방식. 프로젝트마다 다시 심어야 하고 배포에 섞일 걱정이 따라온다.
• Electron 껍데기. 처음엔 그렇게 만들었는데, 그러면 사람이 복사해서 붙여넣는 왕복이 남는다. MCP 면 AI 가 바로 받는다.
• 원격 접속. 127.0.0.1 에만 연다. 남의 브라우저에서 온 짚기를 받을 이유가 없다.