Web Picker

브라우저의 localhost 페이지에서 UI 요소를 선택하고, 수정 요청을 입력하면 MCP 코딩 에이전트(Claude Code, Codex 등)가 해당 요소를 가져와 코드를 수정합니다.

요소를 말로 설명하지 마세요. 요소를 클릭하세요. 캡처는 에이전트가 코드베이스에서 해당 요소를 정확히 찾는 데 필요한 최소한의 단서를 전달하며, 민감한 값은 절대 유출하지 않습니다.

v1은 설계상 localhost 전용입니다. 클라우드 없음, 계정 없음, API 키 없음.

작동 방식

 Browser (localhost page)            Local machine                Coding agent
 ┌────────────────────────┐     ┌───────────────────────┐     ┌──────────────────┐
 │ content script         │     │ Daemon (127.0.0.1)    │     │ MCP adapter      │
 │  pick + mask + rank    │     │  durable queue        │     │  connect / list  │
 │          │ runtime msg │     │  extension HTTP       │     │  pull / resolve  │
 │ service worker ────────┼HTTP►│  token IPC /ipc      │◄────┤  (7 MCP tools)   │
 └────────────────────────┘     └───────────────────────┘ IPC └──────────────────┘

• 데몬은 127.0.0.1에만 바인딩됩니다. 확장 프로그램 워커는 Chrome이 검증한 localhost 탭에서만 메시지를 수락하며, 데몬 확장 엔드포인트는 고정된 chrome-extension://mnglicpibnccgcifnndemfpidkcgboli Origin만 수락합니다. MCP 어댑터의 IPC는 실행별 토큰으로 보호됩니다.

• 에이전트 중립적: 데몬은 에이전트가 Claude Code인지 Codex인지 알지 못합니다. 등록 단계만 다릅니다.

• 마스킹은 정체성을 보존: 입력 값, 이메일, 토큰은 절대 내보내지 않습니다. 짧은 표시 레이블, 선택자, 조상 요소, 랜드마크는 에이전트가 대상을 찾을 수 있도록 유지됩니다.

Related MCP server: Peek

요구 사항

• Node.js >= 20.18.0 (20.20.2로 테스트됨)

• Google Chrome (MV3, 압축 해제하여 로드)

• MCP를 지원하는 코딩 에이전트 (Claude Code 또는 Codex)

설치

./bootstrap.sh          # macOS/Linux  (installs deps + builds)
# or
pwsh ./bootstrap.ps1    # Windows

그런 다음:

1. Chrome 확장 프로그램 로드 chrome://extensions → 개발자 모드 활성화 → 압축 해제된 확장 프로그램 로드 → extension/ 폴더 선택.

2. 에이전트에 MCP 서버 등록:

   ./scripts/register-claude-code.sh   # Claude Code
   ./scripts/register-codex.sh         # Codex

   둘 다 에이전트가 scripts/run.cjs를 가리키게 하며, 이는 데몬을 지연 시작합니다.

5분 심사 경로 (키 없음, 계정 없음)

전체 왕복 과정은 데모 페이지만으로 재현할 수 있습니다. 자동화된 검증은 Chrome이 설치되고 그래픽 데스크톱이 있는 머신에서 일반적으로 5분 이내에 완료됩니다. 모델 API 키나 Playwright 브라우저 다운로드는 필요하지 않습니다.

1. 설정

   ./bootstrap.sh

2. localhost에서 데모 페이지 서빙

   python3 -m http.server 3000 --directory test-page

   http://localhost:3000을 엽니다. 헤더, 메인, 푸터에 모두 저장이라고 표시된 버튼이 세 개 있습니다 — 의도적으로 만든 유인(decoy) 세트입니다.

3. 확장 프로그램 로드(설치 1단계 참조) 및 에이전트 등록(설치 2단계).

4. 요소 선택

   • 픽 버튼(오른쪽 하단) 클릭 → 요소 선택.

   • 메인 영역의 저장 버튼(프로필 카드 내부)에 마우스를 올리고 클릭합니다.

   • 요청을 입력합니다(예: 이 버튼을 파란색으로) → 보내기 클릭.

   • 요청을 큐에 보냈습니다 메시지가 표시됩니다.

5. 에이전트에서 가져오기 Claude Code / Codex 세션에서:

   • connect_web_picker → 피커를 클레임하고 대기 중인 요청 수를 표시합니다.

   • list_web_requests → 요청의 id와 상태를 표시합니다.

   • 해당 id로 get_web_request → 대상 단서를 표시합니다. 세 버튼 모두 표시 레이블이 저장으로 동일하지만, landmark: section(및 선택자 #profile-save)이 헤더/푸터의 저장 유인(landmark: header / landmark: footer)과 구별된다는 점에 유의하세요.

   • id로 resolve_web_request → 요청을 해결됨으로 표시합니다.

이 유인 왕복 과정은 브라우저 없는 통합 테스트 스위트와 아래의 실제 Chrome E2E 모두에서 다룹니다.

브라우저 없이 재현 (완전 자동화)

npm test

test/integration.test.ts는 세 개의 유인 캡처를 게시한 다음 실제 MCP 도구를 connect → list → get → resolve 순서로 구동하여 선택된 요소가 고유하게 식별되는지 검증합니다. 또한 dist/에서 빌드된 데몬을 콜드 스폰합니다.

실제 Chrome 확장 프로그램으로 재현

npm run test:e2e는 설치된 Google Chrome을 새 헤디드 프로필로 열고, extension/을 압축 해제하여 로드하며, 실제 콘텐츠 UI를 통해 프로필 버튼 선택을 수행하고, MCP 클라이언트를 통해 대기 중인 요청을 검증하고 해결합니다. 그래픽 데스크톱 세션이 필요하며 일반적으로 약 10초 안에 완료됩니다. 브라우저를 다운로드하지 않습니다.

macOS 또는 Linux:

npm run test:e2e

# For a non-standard Chrome install:
PLAYWRIGHT_CHROME_EXECUTABLE=/path/to/google-chrome npm run test:e2e

Windows PowerShell:

npm run test:e2e

# For a non-standard Chrome install:
$env:PLAYWRIGHT_CHROME_EXECUTABLE = 'C:\Path\To\chrome.exe'
npm run test:e2e

Chrome이 없거나 오버라이드가 설치된 실행 파일을 가리키지 않으면 테스트는 다음 오류로 실패합니다:

Google Chrome is required for npm run test:e2e; install Chrome or set PLAYWRIGHT_CHROME_EXECUTABLE

보안 기본값

• 데몬은 127.0.0.1에만 바인딩됩니다.

• 확장 프로그램은 localhost / 127.0.0.1 / *.localhost 페이지에서만 활성화됩니다.

• 확장 프로그램 워커는 Chrome이 검증한 localhost 탭 발신자만 수락합니다. 확장 HTTP 엔드포인트는 정확히 고정된 확장 Origin을 요구합니다. IPC는 토큰(상수 시간 비교)을 요구하며, ~/.web-picker/token에 0600 권한으로 저장됩니다.

• 입력 값과 이메일, 긴 숫자, 토큰 형태의 문자열은 절대 내보내지 않습니다. 동일한 필터가 선택자, id, class, role, aria-label, name, 조상 요약, 마스킹된 HTML에도 적용되며, 대상 식별을 위한 안전한 class 토큰은 유지합니다. dataset은 DOM 정규화 후 민감하지 않은 키 이름만 전송하며, 값은 페이지를 벗어나지 않습니다.

MCP 도구

개발

npm test          # vitest (unit + jsdom + integration; excludes real Chrome)
npm run test:e2e  # headed installed-Chrome round trip
npm run build     # tsc -> dist/
npm run benchmark # deterministic target-disambiguation benchmark -> artifacts/
npm run sbom      # CycloneDX 1.5 inventory -> artifacts/sbom.cdx.json

npm run sbom은 문서화된 엔진 최소 버전 미만의 Node 버전을 거부하고, lockfile에서 파생된 무결성/개발/선택 메타데이터를 복원하며, 최종 CycloneDX JSON을 검증하고, npm의 숨겨진 lock 캐시와 무관한 표준 바이트를 작성합니다.

npm run benchmark는 30개의 정적 HTML 픽스처에서만 대상 식별(disambiguation)을 측정합니다. 균형 잡힌 모호한 레이블과 고유 레이블 대조군, 그리고 성공 및 실패 로케이터 해석을 모두 포함합니다. 코딩 에이전트 생산성이나 소스 검색의 척도는 아닙니다. 결과는 텍스트 전용 해석, Web Picker 로케이터 해석, 전역 및 카테고리 × 신뢰도 보정, 레이블 계층, 직렬화된 캡처 페이로드 바이트 크기를 artifacts/benchmark-results.json 및 artifacts/benchmark-results.md에 기록합니다.

아키텍처: 순수 코어(src/daemon/state.ts) + 애플리케이션 핸들러(extension-api, ipc-api, tools) + 얇은 어댑터(server.ts, src/shim/ 아래의 MCP 어댑터 소스, spawn.ts). 포트가 주입되므로 모든 것이 소켓 없이 단위 테스트됩니다. docs/architecture.md를 참조하세요.

제출 증빙: docs/dependencies.md, docs/video-script.md, docs/submission-checklist.md. 공개 저장소 및 YouTube URL은 소유자가 게시하고 검증할 때까지 체크리스트의 명시적 차단 항목으로 남아 있습니다.

라이선스

MIT. 고정된 의존성 라이선스는 설치된 패키지 메타데이터에서 docs/dependencies.md에 기록됩니다. GPL 계열 런타임 의존성은 없습니다.