corlabs

@corlabsdev/mcp

一个 MCP 服务，让编码 Agent 能打开页面、选取元素，并获取适用于所用测试框架的分级定位器。

了解更多信息，请访问 corlabs.dev。

安装

需要 Node 18+ 和 Google Chrome（Microsoft Edge 或 Playwright 的 Chromium 也可以）。不会进行全局安装：Agent 会通过 npx 运行该服务。

将 COR 添加到客户端。所有客户端都运行相同的命令：npx -y @corlabsdev/mcp。

Claude Code

claude mcp add cor -- npx -y @corlabsdev/mcp

如需与团队共享，请改为将其放入项目根目录下的 .mcp.json：

{ "mcpServers": { "cor": { "command": "npx", "args": ["-y", "@corlabsdev/mcp"] } } }

GitHub Copilot（VS Code） — 创建 .vscode/mcp.json（或从命令面板运行 MCP: Add Server）：

{ "servers": { "cor": { "type": "stdio", "command": "npx", "args": ["-y", "@corlabsdev/mcp"] } } }

然后打开 Copilot Chat，切换到 Agent 模式，并在工具列表中启用 cor。

Codex（CLI 和 IDE 扩展）

codex mcp add cor -- npx -y @corlabsdev/mcp

或将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.cor]
command = "npx"
args = ["-y", "@corlabsdev/mcp"]

Cursor — .cursor/mcp.json，以及 Claude Desktop — claude_desktop_config.json：

{ "mcpServers": { "cor": { "command": "npx", "args": ["-y", "@corlabsdev/mcp"] } } }

对于其他 MCP 客户端：注册一个 stdio 服务，其命令为 npx，参数为 -y @corlabsdev/mcp。

重启客户端（或重新加载窗口），然后让 Agent 打开页面：“使用 COR 打开 https://example.com/login，并为登录表单编写定位器。”

如果找不到浏览器，服务会提示；请安装 Chrome，或运行 npx playwright-core install chromium。

选项（追加到 args，或添加在 claude mcp add 的 -- 之后）：

标志	作用
--headless	无窗口运行浏览器（默认：显示窗口）
--idle-minutes <n>	空闲 n 分钟后关闭浏览器
--no-records	不在项目中写入记录条目（见下文）

工具

工具	功能
cor_open	打开页面；列出页面控件及其 refs
cor_snapshot	查看大型页面中某个区域的文本、控件和条目
cor_inspect	为指定元素生成分级定位器，并以条目形式提供，以便加入代码
cor_click、cor_fill、cor_press	操作页面并报告变更
cor_check	检查文件中的定位器，若定位器并非由 COR 提供则报错
cor_grade	为你自行编写的定位器评分
cor_heal	为已无法匹配的定位器提供修复建议
cor_close	关闭浏览器

工作流

1. 对页面运行 cor_open，然后在一次调用中对测试涉及的每个元素运行 cor_inspect。
2. 按原样放置每个条目，包括其 // COR cor:… 注释，并放入条目指定的文件中。
3. 在运行测试前执行 cor_check。如果测试因定位器而失败，运行 cor_grade；如果定位器已失效，再运行 cor_heal。

更新

每次启动时，npx -y @corlabsdev/mcp 都会运行最新版本。如需固定版本，请使用 npx -y @corlabsdev/[email protected]。

设置：将 COR 作为唯一的浏览器工具

配置 COR MCP 而不是 Playwright MCP 来编写测试，不要同时使用两者：COR 会驱动浏览器（打开、点击、填充、按键），以条目形式返回定位器，供你添加到定位器文件中，并对其进行检查（cor_check）和修复（cor_heal）。如果同时连接了另一个浏览器服务，Agent 就会改用其快照并自行编写选择器——这些选择器会被 cor_check 判定为失败。

设置为可选项。COR 会根据代码库推断测试框架和惯例；如需覆盖推断结果，请在项目根目录添加 cor.config.js。framework 用于指定测试框架，其余配置放在 locators 下。所有字段均为可选；cor_open 会报告推断结果和覆盖项：

module.exports = {
  framework: 'playwright',          // 'playwright' | 'cypress' | 'webdriverio'
  locators: {
    order: 'framework',             // 'framework' (default: each framework's published guidance, after uniqueness) or 'testid-first'
    testIdAttribute: 'data-test',   // what getByTestId reads (default: playwright.config's testIdAttribute, else data-testid)
    store: 'page-object-class',     // 'page-object-class' | 'constants' | 'json' | 'yaml'
    storeDir: 'tests/pages',
  },
}

条目记录：项目中写入的内容

每次 cor_inspect 推荐定位器时，都会给它一个条目：要放进定位器文件的代码、它所属的文件和成员，以及一条带有短 ID 的注释 // COR cor:7f3a2c · …（在 YAML 映射中为 # COR cor:…）。请保留这条注释：cor_check 会用该 ID 区分 COR 的定位器和手动填写的定位器，后续修复也会用它来查找该定位器指向的元素。COR 绝不会编辑你的文件——由 Agent 放置条目。

位置： 项目根目录中的 .cor/records/<id>.json（即测试框架的 package.json 所在位置），每个元素对应一个小文件。再次检查同一元素时会复用其 ID 并更新对应文件。对于无法保存注释的 JSON 定位器映射，COR 还会维护 .cor/ids.json（"file#key": "id"）——它绝不会向你的映射中添加键。

请提交这些文件。 修复在队友的机器上或 CI 检出目录中运行时需要它们：ID 会随代码保存，记录会随仓库一起保存。如果你更愿意将它们留在一台机器上，可以将 .cor/records/ 添加到 .gitignore。

**每条记录包含的内容：**页面（已遮蔽的来源和路径）、元素的位置（标签路径）、条目的成员名称、元素指纹——其标签；存在时的 aria-label、aria-labelledby、name、placeholder、type、role、title、alt、href、for；元素自身最多 80 个字符的文本；前五个类名——以及最多 12 个按排名列出的适用定位器，以数据形式保存（{ "kind": "testId", "value": "[data-test=\"…\"]" }），而不是可直接粘贴的代码。COR 绝不会向 Agent 展示记录内容。

**绝不会存储的内容：**任何人在字段中输入的内容（输入值）、Cookie、本地存储，或传递给 cor_open 的存储状态文件中的任何内容。

**遮蔽。**在已通过身份验证的页面上，上述字段可能包含账户数据，因此写入任何内容前都会进行以下处理：

在文本、属性、类名或定位器中发现的内容	存储为
电子邮件地址	[email]
连续 6 位或更多数字（订单号、电话号码和卡号；允许包含空格和连字符）	[number]
长度为 24 位或以上、由字母和数字混合组成的字符串（令牌、会话 ID）	[token]
href 的查询字符串或片段	移除

短数字和普通词语会保留，因为修复需要它们（“Step 2”“Qty 12”“Pay now”）。值会被遮蔽，而不是哈希处理。修复会将存储的值与实时页面上的纯文本进行比较，因此哈希值之后绝不可能再次匹配。

**关闭记录功能：**启动服务时添加 --no-records，或设置 COR_RECORDS=off（旧选项 --no-fingerprints / COR_FINGERPRINTS=off 仍可使用）：不会写入记录；条目仍会携带 ID，而 cor_check 此时只会检查 ID 是否存在。早期版本使用的 ~/.cor/fingerprints/ 存储不再写入或读取；可以安全删除。

遥测：匿名使用指标

服务会发送匿名使用指标，帮助我们了解 COR 的安装和使用情况。共有两个事件：

• mcp_installed：每次安装仅发送一次，在首次启动时发送；包含软件包版本、Node 版本、OS 平台。
• mcp_tool_called：每次工具调用发送一次；包含工具名称、耗时（毫秒）、结果（ok、tool_error、exception 或 timeout）、软件包版本。

每次安装都有一个随机匿名 ID，存储在 ~/.cor/install-id。首次启动时，stderr 会打印一行说明。

**绝不会发送：**页面 URL 或来源、元素文本、定位器、文件路径、输入值、Cookie、存储内容、记录内容、错误消息或任何电子邮件地址。每个字段都列在代码中（src/telemetry.js），不会添加其他内容。

**关闭遥测：**设置 COR_TELEMETRY=off（或设置 COR_OFFLINE=true，这会停止所有出站数据）。不会发送任何内容，也不会写入 ID 文件。