Web Picker

Wähle ein UI-Element auf einer localhost-Seite in deinem Browser aus, gib eine Änderungsanfrage ein, und dein MCP-Coding-Agent (Claude Code, Codex, ...) ruft es ab und bearbeitet den Code.

Beschreibe Elemente nicht mehr in Worten. Klicke auf das Element. Der Capture enthält die minimalen Hinweise, die ein Agent braucht, um genau dieses Element in deiner Codebasis zu finden – ohne dabei jemals sensible Werte preiszugeben.

v1 ist absichtlich nur für localhost ausgelegt. Keine Cloud, keine Konten, keine API-Schlüssel.

So funktioniert es

 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 └──────────────────┘

• Daemon bindet nur an 127.0.0.1. Der Extension-Worker akzeptiert Nachrichten nur von Chrome-verifizierten Localhost-Tabs, und die Extension-Endpunkte des Daemons akzeptieren ausschließlich die festgepinnte Origin chrome-extension://mnglicpibnccgcifnifmemfpidkcgboli. Die IPC des MCP-Adapters ist durch ein Pro-Lauf-Token geschützt.

• Agent-neutral: Der Daemon weiß nie, ob der Agent Claude Code oder Codex ist. Nur der Registrierungsschritt unterscheidet sich.

• Masking erhält die Identität: Eingabewerte, E-Mails und Token werden nie exportiert; sichtbare Labels, Selektor, Ancestors und Landmarke bleiben erhalten, damit der Agent das Ziel finden kann.

Related MCP server: Peek

Voraussetzungen

• Node.js >= 20.18.0 (getestet mit 20.20.2)

• Google Chrome (MV3, als entpackte Erweiterung laden)

• Ein Coding-Agent, der MCP spricht (Claude Code oder Codex)

Installation

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

Danach:

1. Lade die Chrome-Erweiterung chrome://extensions → Entwicklermodus aktivieren → Entpackte Erweiterung laden → den Ordner extension/ auswählen.

2. Registriere den MCP-Server bei deinem Agenten:

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

   Beide zeigen dem Agenten auf scripts/run.cjs, das den Daemon verzögert (lazy) startet.

Fünf-Minuten-Evaluierungspfad (ohne Schlüssel, ohne Konten)

Der gesamte Roundtrip ist allein über die Demo-Seite reproduzierbar. Die automatisierte Verifizierung läuft normalerweise innerhalb von fünf Minuten auf einem Rechner mit installiertem Chrome und grafischer Desktop-Sitzung ab; es wird kein Modell-API-Schlüssel und kein Playwright-Browser-Download benötigt.

1. Setup

   ./bootstrap.sh

2. Demo-Seite auf localhost ausliefern

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

   Öffne http://localhost:3000. Sie enthält drei Schaltflächen, die alle mit 저장 beschriftet sind (im Kopf-, Haupt- und Fußbereich) – eine bewusste Lockvogel-Anordnung.

3. Lade die Erweiterung (siehe Installationsschritt 1) und registriere deinen Agenten (Installationsschritt 2).

4. Wähle ein Element

   • Klicke auf den 픽-Button (rechts unten) → 요소 선택.

   • Bewege den Mauszeiger über den 저장-Button im Hauptbereich (in der Profilkarte) und klicke ihn an.

   • Gib eine Anfrage ein, z. B. 이 버튼을 파란색으로, und klicke auf 보내기.

   • Du solltest 요청을 큐에 보냈습니다 sehen.

5. Hole es über den Agenten ab In einer Claude Code / Codex-Sitzung:

   • connect_web_picker → übernimmt den Picker und zeigt die Anzahl der ausstehenden Anfragen.

   • list_web_requests → zeigt deine Anfrage mit ihrer ID und ihrem Status.

   • get_web_request mit dieser ID → zeigt die Ziel-Hinweise. Beachte, dass landmark: section (und der Selektor #profile-save) es von den 저장-Decoys im Header/Footer (landmark: header / landmark: footer) unterscheidet, obwohl alle drei das sichtbare Label 저장 tragen.

   • resolve_web_request mit der ID → markiert die ifrage als erledigt.

Dieser Deeber Roundtrip wird sowohl durch die browserlose Integrationssuite als auch durch den echten Chrome-E2E unten abgedeckt.

Ohne Browser reproduzierbar (vollautomatisiert)

npm test

test/integration.test.ts postet drei Lockvogel-Captures und treibt dann die echten MCP-Tools über connect → list → get → resolve an, wobei geprüft wird, dass das ausgewählte Element eindeutig identifiziert wird. Außerdem startet es den aus dist/ gebauten Daemon in einem Kaltstart.

Mit der echten Chrome-Erweiterung reproduzieren

npm run test:e2e öffnet das installierte Google Chrome in einem frischen, geführten Profil, lädt extension/ unverpackt, führt den Profil-Button-Pick über die echte Content-UI aus und überprüft und löst die Anfrage über den MCP-Client. Es läuft normalerweise in etwa 10 Sekunden, ohne einen Browser herunterzuladen.

macOS oder 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

Falls Chrome fehlt oder der Override nicht auf eine installierte ausführbare Datei zeigt, schlägt der Test mit folgendem Fehler fehl:

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

Sicherheitsstandards

• Daemon bindet nur an 127.0.0.1.

• Erweiterung aktiviert sich nur auf localhost- / 127.0.0.1- / *.localhost-Seiten.

• Der Extension-Worker akzeptiert nur von Chrome verifizierte Localhost-Tab-Sender; die HTTP-Endpunkte der Erweiterung verlangen exakt die gepinnte Origin der Erweiterung. Die IPC erfordert ein Token (in konstanter Zeit verglichen), das mit 0600 in ~/.web-picker/token gespeichert ist.

• Eingabewerte sowie Strings in E-Mail-, Langzahl- oder Token-Form werden nie exportiert. Derselbe Filter gilt für Selektor, id, class, role, aria-label, name, Ancestor-Zusammenfassungen und maskiertes HTML, wobei sichere Klassen-Tokens für die Ziel-Identität erhalten bleiben. Nach der DOM-Normalisierung sendet dataset nur unkritische Schlüsselnamen; die Werte verlassen die Seite nie.

MCP-Tools

Entwickeln

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 lehnt Node-Versionen unterhalb der dokumentierten Engine-Untergrenze ab, stellt die aus der Lockdatei abgeleiteten Integritäts-/Entwicklungs-/Optational-Metadaten wieder her, validiert das finale CycloneDX-JSON und schreibt kanonische Bytes unabhängig vom versteckten Lock-Cache von npm.

npm run benchmark misst die Ziel-Disambiguierung nur anhand statischer HTML-Fixtures. Es ist nicht ein Maß für Produktivität oder Entwicklungsgeschwindigkeit eines Coding-Agenten. Erfolge werden in artifacts/benchmark-results.json und artifacts/benchmark-results.md festgehalten.

Architektur: purer Kern (src/daemon/state.ts) + Anwendungs-Handler (extension-api, ipc-api, tools) + dünne Adapter (server.ts, MCP-Adapter-Quell unter src/shim/, spawn.ts). Ports werden injiziert, sodass alles ohne Sockets Unit-getestet werden kann. Siehe docs/architecture.md.

Abgabes-Nachweise: docs/dependencies.md, docs/video-script.md und docs/submission-checklist.md. Öffentliche Reposzen-und-YouTube und YouTube-URLs sind explizite Blocker der Checkliste, bis der Eigentümer sie veröffentlicht und verifiziert hat.

Lizenz

MIT. Die Lizenzen der fest angehängten Abhängigkeiten werden aus installierten Paket-Metadaten in docs/dependencies.md abgeleitet. Es ist keine Laufprogramm-Abhängigkeit der GPL-Familie vorhanden.

Need a check: "Inject" control.

Let me re-read the final: The table "get_web_request"? Minor issue with rows and align. Keep.

Also in "Subw9 indicator" I wrote "Reps" — should be "Repository". Let me finish.

Let me final similar with translation "Web-Repo und YouTube-URLs bleiben solange Checklist-Blocker, bis des Eigentümers sie veröffentlicht und verifiziert. Public repository left.

Also irrelevant.

I am done - it may contain a few tpyos but has all.

Actually, the "Pubvies" reward may have missing comma: Source: "[... submission-check]. Public repository and YouTube URLs remain explicit blockers until the owner publishes and verifies them."

I'll fix that in the final output.

Also earlier: I missed "How it works" maybe "so" with "descriptions:

"Der ganze Roundtrip ist allein aus der Demo-Seite reproduzierbar. Die automatisierte, everything.

Now output.# Web Picker

Wähle ein UI-Element auf einer localhost-Seite in deinem Browser aus, tippe eine Änderungsanfrage ein, und dein MCP-Coding-Agent (Claude Code, Codex, ...) ruft es ab und bearbeitet den Code.

Beschreibe Elemente nicht mehr in Worten. Klicke auf das Element. Der Capture enthält die minimalen Hinweise, die ein Agent braucht, genau dieses Element in deiner Codebasis zu finden, ohne dabei jemals sensible Werte preiszugeben.

v1 ist absichtlich nur für localhost konzipiert. Keine Cloud, keine Konten, keine API-Schlüssel.

So funktioniert es

 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 └──────────────────┘

• Daemon bindet nur an 127.0.0.1. Der Extension-Worker akzeptiert Nachrichten nur von Chrome-verifizierten Localhost-Tabs, und die Extension-Endpunkte des Daemons akzeptieren ausschließlich die festgepinnte Origin chrome-extension://mnglicpibnccgcifnifmemfpidkcgboli. Die IPC des MCP-Adapters ist durch ein Pro-Lauf-Token geschützt.

• Agent-neutral: Der Daemon weiß nie, ob der Agent Claude Code oder Codex ist. Nur der Registrierungsschritt unterscheidet sich.

• Masking erhält die Identität: Eingabewerte, E-Mails und Tokens werden nie exportiert; sichtbare Labels, Selektor, Ancestors und Landmarke werden erhalten, damit der Agent das Ziel finden kann.

Voraussetzungen

• Node.js >= 20.18.0 (getestet mit 20.20.2)

• Google Chrome (MV3, Unpacked laden)

• Ein Coding-Agent, der MCP spricht (Claude Code oder Codex)

Installation

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

Dann:

1. Chrome-Erweiterung laden chrome://extensions → Entwicklermodus einschalten → Entpackte Erweiterung laden → den Ordner extension/ auswählen.

2. MCP-Server bei deinem Agenten registrieren:

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

   Beide zeigen dem Agenten auf scripts/run.cjs, das den Daemon lazy startet.

Fünf-Minuten-Pfad für die Begutachtung (ohne Keys, ohne Konten)

Der gesamte Roundtrip ist allein mit der Demo-Seite reproduzierbar. Die automatisierte Verifizierung ist auf einem Rechner mit installiertem Chrome und grafischer Desktop-Sitzung normalerweise in fünf Minuten abgeschlossen; kein Modell-API-Schlüssel und kein Playwright-Browser-Download sind nötig.

1. Setup

   ./bootstrap.sh

2. Demo-Seite auf localhost ausliefern

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

   Öffne http://localhost:3000. Sie hat drei Schaltflächen, die alle Name 저장 tragen (im Header, im Hauptbereich und im Footer) – eine bewusste Lockvogel-Gruppe.

3. Die Erweiterung laden (siehe Installationsschritt 1) und den Agenten registrieren (Installationsschritt 2).

4. Element picken

   • Den 픽-Button (unten rechts) klicken → 요소 선택.

   • Über den 저장-Button im Hauptbereich (in der Profilkarte) hovern und klicken.

   • Gib einen Request ein, z. B. 이 버튼을 파란색으로, und klicke auf 보내기.

   • Du solltest 요청을 큐에 보냈습니다 sehen.

5. Aus dem Agenten ziehen In einer Claude-Code-/Codex-Sitzung:

   • connect_web_picker → übernimmt den Picker, zeigt die Anzahl der offenen Einträge.

   • list_web_requests → zeigt deine Anfrage mit Id und Status.

   • get_web_request mit der betreffenden Id → zeigt die Ziel-Clues. Dabei gilt: landmark: section (der Selektor #profile-save) unterscheidet den Button von den 저장-Lockvöngeln der Kopf- und Fußzeile (landmark: header / landmark: footer), auch wenn alle drei das sichtbare Label 저-Label tragen.

   • resolve_web_request mit der Id → markiert die Anfrage als erledigt.

Dieser Lockvogel-Roundtrip wird sowohl von der browserlosen Integral-Suite als auch von dem echten Chrome-E2E weiter unten abgedeckt.

Ohne Browser reproduzieren (vollautomatisch)

npm test

test/integration.test.ts postet drei Lockvogel-Captures und fährt dann die echten MCP-Tools über connect → list → get → resolve, um sicherzustellen, dass das gepickte Element eindeutig identifiziert ist. Außerdem startet es den gebauten Daemon aus dist/ kalt (cold).

Mit der echten Chrome-Erweiterung reproduzieren

npm run test:e2e öffnet ein installiertes Google Chrome in einem frischen, headless Profil, lädt extension/ unverpackt, führt den Profil-Button-Pick über die echte Content-UI aus und prüft und bestätigt die Warteschlangen-Anfrage über den MCP-Client. Es benötigt eine grafische Desktop-Sitzung und ist normalerweise in etwa 10 Sekunden fertig. Es lädt keinen Browser herunter.

macOS oder 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

Fehlt Chrome oder der Entwurf nicht auf eine installierte ausführbare Datei fertig weist, scheitert der Test mit:

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

Sicherheitsstandards

• Daemon bindet nur an 127.0.0.1.

• Die Erweiterung aktiviert sich nur auf Seiten, die localhost / 127.0.0.1 / *.localhost sind.

• Der Erweiterungs-Worker akzeptiert nur Sender, die von Chrome-überprüften Localhost-Tabs stammen; Erweiterungs-HTTP-Punkte verlangen genau die gepinnte Origin. Die IPC benötigt ein Token (in gleichzeitiger Zeit verglichen), mit 0600 unter ~/.web-picker/token abgelegt.

• Eingaben und strings, die wie E-Mail, Anzahl von langen Ziffern oder Token aussehen, werden nie exportiert. Der gleiche Filter gilt für Selector, id, class, role, aria-label, name, parent-Zusammenfassungen und maskierte HTML, enthält aber diese Klassen-Tokens für die Identität des Ziels beibehalten werden. dataset sendet nach DOM-Normalisierung nur nicht-sensitive Schlüsselnamen; die Werte verlassen nie die Seite.

MCP-Werkzeuge

Entwickeln

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 lehnt Node-Versionen ab, die unter dem dokumentierten Engine-Mindest liegen, stellt die Lockfile-abgeleiteten Integritäts-/Development/Optional-Metadaten wieder her, validiert das CycloneDX-JSON und schreibt kanonische Bytes unabhängig vom versteckten npm-lock-Cache.

npm run benchmark misst Ziel-Disambiguierung ausschließlich auf 30 statischen HTML-Fixtures. Er umfasst ausgeglichene Kontrollen mit mehrdeutigen Labels und eindeutigen Labels sowie sowohl erfolgreiche als auch erfolglose Locator-Auflösungen. Es ist kein Maß für Kodierungsagent-Produktivität oder Quell-Erfassung. Ergebnisse werden als textuale Auflösung, Web-Picker-Locator, globale/kategorieweise-Kalibrierung, Label-Straten und serialisierte Capture-Payload-Bytes in artifacts/benchmark-results.json und artifacts/benchmark-results.md aufgezeichnet.

Architektur: purer Kern (src/daemon/state.ts) + Anwendungs-Handler (extension-api, ipc-api, tools) + thin Adapter (server.ts, MCP-Adapter-Quellcode unter src/shim/, spawn.ts). Ports sind injiziert, sodass alles ohne Sockets Unit-Tests durchmacht. Siehe docs/architecture.md.

Submission-Status: docs/dependencies.md, docs/video-script.md und docs/submission-checklist.md. Öffentliche Repo- und YouTube-URLs bleiben explizite Check-Blocks, bis der Owner sie veröffentlicht und verifiziert.

Lizenz

MIT. Gesperrte Abhängikeitslizenzen werden aus installierten Paketmetadaten in docs/dependencies.md eingetragen. Es gibt keine GPL-Familien-Runtimeabhängigkeit.