corlabs

@corlabsdev/mcp

An MCP server that lets a coding agent open a page, pick an element, and get ranked, graded locators for it in the test framework you use.

More at corlabs.dev.

Install

Requires Node 18+ and Google Chrome (Microsoft Edge, or Playwright's Chromium, also work). Nothing is installed globally: your agent runs the server with npx.

Add COR to your client. Every client runs the same command, npx -y @corlabsdev/mcp.

Claude Code

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

To share it with your team, put it in .mcp.json at the project root instead:

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

GitHub Copilot (VS Code) — create .vscode/mcp.json (or run MCP: Add Server from the Command Palette):

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

Then open Copilot Chat, switch to Agent mode, and enable cor in the tools list.

Codex (CLI and IDE extension)

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

or add this to ~/.codex/config.toml:

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

Cursor — .cursor/mcp.json, and Claude Desktop — claude_desktop_config.json:

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

Any other MCP client: register a stdio server whose command is npx with arguments -y @corlabsdev/mcp.

Restart the client (or reload the window), then ask your agent to open your page: "Use COR to open https://example.com/login and write the locators for the sign-in form."

If no browser is found the server says so; install Chrome, or run npx playwright-core install chromium.

Options (append to args, or after -- in claude mcp add):

Flag	Effect
--headless	Run the browser without a window (default: visible)
--idle-minutes <n>	Close the browser after n idle minutes
--no-records	Write no entry records into your project (see below)

Tools

Tool	Does
cor_open	Open a page; lists its controls with refs
cor_snapshot	Text, controls and entries within one region of a large page
cor_inspect	Ranked, graded locators for the elements you name, as entries to place in your code
cor_click, cor_fill, cor_press	Act on the page and report what changed
cor_check	Fail any locator in your files that did not come from COR
cor_grade	Score a locator you wrote yourself
cor_heal	Propose a repair for a locator that stopped matching
cor_close	Close the browser

Workflow

1. cor_open the page, then cor_inspect every element the test touches, in one call.
2. Place each entry as given, its // COR cor:… comment included, in the file it names.
3. Run cor_check before the tests. When a test breaks on a locator, cor_grade it and cor_heal if it is broken.

Updating

npx -y @corlabsdev/mcp runs the latest version each time it starts. To pin one, use npx -y @corlabsdev/[email protected].

Setup: COR as the only browser tool

Configure COR MCP instead of Playwright MCP for test authoring, not alongside it: COR drives the browser (open, click, fill, press), returns locators as entries for your locator files, checks them (cor_check) and repairs them (cor_heal). With a second browser server attached, an agent falls back to its snapshots and types its own selectors — which cor_check will then fail.

Settings are optional. COR infers your test framework and conventions from the repo; to override them, add a cor.config.js at the project root. framework names the test framework and the rest go under locators. Every field is optional; cor_open reports what was inferred and what was overridden:

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',
  },
}

Entry records: what is written inside your project

Every cor_inspect that recommends a locator also gives it an entry: the code to place in your locator file, the file and member it belongs in, and a comment carrying a short id, // COR cor:7f3a2c · … (in a YAML map, # COR cor:…). Keep that comment: cor_check uses the id to tell COR's locators from typed ones, and a later repair uses it to find what the locator pointed at. COR never edits your files — the agent places the entry.

Where: .cor/records/<id>.json in your project root (where your test framework's package.json is), one small file per element. Inspecting the same element again reuses its id and refreshes its file. For a JSON locator map, which cannot hold comments, COR also keeps .cor/ids.json ("file#key": "id") — it never adds keys to your map.

Commit them. They are how a repair works on a teammate's machine or in a CI checkout: the id travels in your code and the record travels with the repo. Add .cor/records/ to .gitignore if you would rather keep them on one machine.

What each record holds: the page (origin and path, masked), the element's position as a tag path, the entry's member name, the element's fingerprint — its tag; aria-label, aria-labelledby, name, placeholder, type, role, title, alt, href, for if present; up to 80 characters of its own text; its first five class names — and up to 12 locators ranked for it, stored as data ({ "kind": "testId", "value": "[data-test=\"…\"]" }), not as code to paste. COR never shows a record's contents to the agent.

What is never stored: what anyone typed into a field (input values), cookies, local storage, or anything from a storage-state file you pass to cor_open.

Masking. On an authenticated page the fields above can contain account data, so before anything is written:

Found in text, attributes, classes or locators	Stored as
an email address	[email]
a run of 6 or more digits (order numbers, phone and card numbers; spaces and dashes allowed)	[number]
a long string of 24+ mixed letters and digits (tokens, session ids)	[token]
the query string or fragment of an href	removed

Short numbers and ordinary words are kept, because a heal needs them ("Step 2", "Qty 12", "Pay now"). Values are masked, not hashed. A heal compares stored values with the live page as plain text, so a hashed value could never match again.

Turning it off: start the server with --no-records or set COR_RECORDS=off (the old --no-fingerprints / COR_FINGERPRINTS=off still work): no record is written; entries still carry an id, and cor_check then checks ids for presence only. The ~/.cor/fingerprints/ store of earlier versions is no longer written or read; deleting it is safe.

Telemetry: anonymous usage metrics

The server sends anonymous usage metrics to help us see how COR is installed and used. Two events:

• mcp_installed, once per install, on the first start: package version, Node version, OS platform.
• mcp_tool_called, once per tool call: tool name, duration in milliseconds, outcome (ok, tool_error, exception, or timeout), package version.

Each install has a random anonymous ID, stored in ~/.cor/install-id. The first start prints one line on stderr saying so.

Never sent: page URLs or origins, element text, locators, file paths, input values, cookies, storage, record contents, error messages, or any email address. Every field is listed in the code (src/telemetry.js), and nothing else is added.

Turning it off: set COR_TELEMETRY=off (or COR_OFFLINE=true, which stops all outbound data). Nothing is sent and no ID file is written.