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。扩展 worker 只接受来自 Chrome 验证过的 localhost 标签页的消息，守护进程扩展端点只接受固定的 chrome-extension://mnglicpibnccgcifnndemfpidkcgboli Origin。MCP 适配器的 IPC 由每次运行生成的令牌保护。

• 代理中立：守护进程永远不知道代理是 Claude Code 还是 Codex。只有注册步骤不同。

• 掩蔽保留身份：输入值、电子邮件、令牌绝不导出；保留简短可见标签、选择器、祖先元素和地标，以便代理定位目标。

Related MCP server: claude-annotate

要求

• 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，该脚本会惰性启动守护进程。

五分钟评审路径（无需密钥、无需账户）

仅凭演示页面即可完整复现整个往返流程。在装有 Chrome 和图形桌面的机器上，自动化验证通常可在五分钟内完成；无需模型 API 密钥或 Playwright 浏览器下载。

1. 设置

   ./bootstrap.sh

2. 在 localhost 上提供演示页面

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

   打开 http://localhost:3000。页面有三个按钮，均标记为 저장（分别位于页头、主体和页脚）——这是一组刻意设置的诱饵。

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 发布三个诱饵捕获，然后通过 connect → list → get → resolve 驱动真实的 MCP 工具，断言所选取的元素被唯一标识。它还会从 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，同时保留安全的类令牌以用于目标身份。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 版本，恢复基于锁文件的完整性/开发/可选元数据，验证最终的 CycloneDX JSON，并写入独立于 npm 隐藏锁缓存的规范字节。

npm run benchmark 仅测量 30 个静态 HTML 固定样本上的目标消歧。它包含平衡的歧义标签和唯一标签对照，以及成功和不成功的定位器解析。它不是编码代理生产力或源代码检索的度量。结果记录纯文本解析、Web Picker 定位器解析、全局和类别 × 置信度校准、标签分层，以及序列化捕获负载字节大小，保存在 artifacts/benchmark-results.json 和 artifacts/benchmark-results.md 中。

架构：纯核心（src/daemon/state.ts）+ 应用处理器（extension-api、ipc-api、tools）+ 薄适配器（server.ts、MCP 适配器源码位于 src/shim/、spawn.ts）。端口被注入，因此所有内容都可以在没有套接字的情况下进行单元测试。参见 docs/architecture.md。

提交证据：docs/dependencies.md、docs/video-script.md 和 docs/submission-checklist.md。公共仓库和 YouTube URL 在所有者发布并验证之前，仍是明确的清单阻塞项。

许可证

MIT。锁定的依赖许可证记录在 docs/dependencies.md 中，来自已安装的包元数据。不存在 GPL 系列运行时依赖。