What can you do with this server?

The locator-mcp server scans live browser pages to generate and manage structured locator registries for test automation. Key capabilities: * Scan live browser pages (scan_page): Connects to Chrome (CDP) or Playwright (WebSocket) to discover elements, generate ranked XPath/CSS/testId locators (including relational XPaths), validate uniqueness, and save results to a named JSON registry (registry/{scanName}.json). Supports interactive (default), testId, and full scan modes. * Validate locator quality: Each locator is checked for uniqueness on the live page, providing matchCount and confidence levels (high, medium, low). * List available registries (list_registries): View all saved registry files in the registry/ directory. * Fetch lightweight key list (get_registry_keys): Retrieve a compact summary of all element keys (tag name, testId, confidence) — ideal for token-efficient workflows before fetching full details. * Fetch a single locator entry (get_locator): Get full locator details (recommended XPath/CSS, fallbacks, confidence, match count, strategy) for one element by its key. * Search/filter a registry (search_registry): Filter entries by tag name, data-testid substring, text substring, and/or confidence level. * Fetch the full registry (get_registry): Returns the complete registry JSON — high token cost, use sparingly in favor of incremental reads.

Which integrations are available for this server?

Connects to live Chrome browser pages via CDP to scan DOM elements and generate structured locator registries for test automation, supporting XPath, CSS, and testId locators with uniqueness validation.

How do I use locator-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@locator-mcp scan this page and save locators" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

locator-mcp

by Eswarr11

Overview Schema Related Servers Score Discussions

TypeScript

Local

locator-mcp

MCP server that scans live browser pages and builds structured locator registries for test automation. Connects to Chrome via CDP or Playwright WebSocket, discovers elements, generates ranked XPath/CSS/testId locators (including relational XPaths for duplicate data-testid values), validates uniqueness on the page, and saves per-page JSON registries that AI clients can read incrementally.

Built for use alongside Playwright MCP — navigate and interact with the browser using Playwright MCP, then call scan_page to capture locators into a registry.

Related MCP server: paparazzi

Features

Live page scanning — connects to an already-open browser tab (no headless relaunch)
Per-page registries — each scan saves to registry/{scanName}.json for targeted reads
Relational XPath — ancestor-scoped and label-sibling XPaths disambiguate duplicate generic testIds (box, flex, etc.)
Multi-strategy locators — testId, id, aria, form attributes, text, class, positional fallbacks
Uniqueness validation — each locator is checked on the live page (matchCount, confidence)
Dynamic testId templates — detects unstable suffixes and emits contains() + template XPaths
Three scan modes — interactive (default), testId, full to control noise vs coverage
Token-efficient read tools — get_registry_keys and get_locator vs full get_registry
Portable MCP config — committed .cursor/mcp.json with ${workspaceFolder} support

How it works

flowchart LR
  subgraph browser [Browser]
    page[Open tab via CDP/WS]
  end
  subgraph scan [scan_page pipeline]
    discover[discover-elements]
    extract[extract-element-context]
    generate[generate-xpath-variants]
    rank[rank-xpath-variants]
    validate[validate-locator]
    save[save-registry]
  end
  subgraph registry [registry/]
    json["{scanName}.json"]
  end
  subgraph read [Read tools]
    keys[get_registry_keys]
    one[get_locator]
    search[search_registry]
  end
  page --> discover --> extract --> generate --> rank --> validate --> save --> json
  json --> keys
  json --> one
  json --> search

Discover — query the DOM using mode-specific selectors (interactive, testId, or full)
Extract context — per element: attributes, direct text, ancestor chain (up to 6 levels), label siblings
Generate variants — XPath candidates across 9 tiers (testId → relational → text → class → positional)
Rank & validate — score variants, verify matchCount on the live page, pick recommended + fallbacks
Save — write registry/{scanName}.json with keys, metadata, and locator bundles
Read — AI client fetches keys first, then individual entries as needed

Prerequisites

Node.js 18+ (tested on Node 24)
npm
Google Chrome (for CDP mode) or a Playwright browser server (for WebSocket mode)
Cursor or Claude Desktop for MCP integration

Quick start

git clone https://github.com/Eswarr11/locator-mcp.git
cd locator-mcp          # folder name may differ on your machine
npm install

Open the cloned folder as your Cursor workspace
.cursor/mcp.json is preconfigured — reload MCP: Cmd+Shift+J → MCP
Launch Chrome with remote debugging (see With Playwright MCP)
Navigate to your target page using Playwright MCP
Call scan_page with a scanName and cdpEndpoint

Run locally

Command	Description
`npm run mcp`	Start MCP server via `tsx` — used by Cursor / Claude
`npm run dev`	Same as `mcp`, for terminal development
`npm run build`	Compile TypeScript to `dist/`
`npm start`	Run compiled server (`node dist/server.js`)
`npm test`	Run unit tests

# MCP server (stdio transport — used by Cursor / Claude)
npm run mcp

# Production
npm run build && npm start

MCP configuration

Run npm install in the repo before connecting.

Why not cwd + relative paths? Global ~/.cursor/mcp.json ignores cwd, so relative paths like src/server.ts resolve from your home directory and fail with ERR_MODULE_NOT_FOUND. Use the committed project config or npm run mcp --prefix <abs-path>.

Cursor (project) — recommended

.cursor/mcp.json is committed. Open this repo as your workspace — no manual edits needed:

{
  "mcpServers": {
    "locator-mcp": {
      "command": "npm",
      "args": ["run", "mcp", "--prefix", "${workspaceFolder}"]
    }
  }
}

${workspaceFolder} resolves to the project root automatically. Reload MCP after clone: Cmd+Shift+J → MCP.

If locator-mcp is also defined in global ~/.cursor/mcp.json, remove one entry to avoid duplicate servers.

Cursor (global)

For use across workspaces, add to ~/.cursor/mcp.json:

"locator-mcp": {
  "command": "npm",
  "args": ["run", "mcp", "--prefix", "<path-to-repo>"]
}

Example for this machine:

"locator-mcp": {
  "command": "npm",
  "args": ["run", "mcp", "--prefix", "/Users/eswar/Desktop/locator-collector"]
}

Claude Desktop

Claude does not support ${workspaceFolder}. Edit:

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "locator-mcp": {
      "command": "npm",
      "args": ["run", "mcp", "--prefix", "<path-to-repo>"]
    }
  }
}

Restart Claude Desktop after saving.

Production (compiled)

Run npm run build first, then point MCP at the compiled output:

"locator-mcp": {
  "command": "node",
  "args": ["<path-to-repo>/dist/server.js"]
}

With Playwright MCP (for `scan_page`)

scan_page does not launch a browser — it connects to one that is already open. Pair with Playwright MCP on the same CDP endpoint (typically in global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--cdp-endpoint",
        "http://localhost:9222"
      ]
    },
    "locator-mcp": {
      "command": "npm",
      "args": ["run", "mcp", "--prefix", "<path-to-repo>"]
    }
  }
}

Step 1 — Launch Chrome with remote debugging:

open -a "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir=/tmp/pw-chrome

Step 2 — Navigate to your target page using Playwright MCP tools.

Step 3 — Scan with locator-mcp:

{
  "cdpEndpoint": "http://localhost:9222",
  "scanName": "goal-side-panel-locators",
  "scanMode": "interactive"
}

Optional: pass pageUrl (substring) to target a specific tab when multiple are open.

MCP tools reference

`scan_page`

Scan an open browser page and save locators to registry/{scanName}.json.

Parameter	Required	Description
`cdpEndpoint`	One of CDP/WS	CDP HTTP URL, e.g. `http://localhost:9222`
`wsEndpoint`	One of CDP/WS	Playwright WebSocket URL, e.g. `ws://127.0.0.1:PORT/...`
`scanName`	Yes	Registry filename without `.json`
`scanMode`	No	`interactive` (default), `testId`, or `full`
`pageUrl`	No	URL substring to pick a specific tab

Example response (abbreviated):

{
  "scanId": "goal-side-panel-locators",
  "registryFile": "registry/goal-side-panel-locators.json",
  "pageUrl": "https://app.example.com/goals",
  "scannedAt": "2026-06-23T12:00:00.000Z",
  "totalElements": 42,
  "registrySaved": true,
  "stats": {
    "total": 42,
    "unique": 38,
    "duplicate": 4,
    "lowConfidence": 2,
    "interactive": 30
  },
  "warnings": [
    "5 elements share generic testId 'box' — relational XPath applied"
  ],
  "sample": [ "...first 5 elements..." ]
}

`list_registries`

List all available registry files in registry/.

{ "registries": ["goal-side-panel-locators", "goal-create-side-panel-v2"] }

`get_registry_keys`

Return a lightweight list of element keys — use this before fetching individual locators.

Parameter	Required	Description
`scanName`	Yes	Registry filename without `.json`

Returns per key: key, tagName, testId, confidence, matchCount, strategy

Much smaller than get_registry — typically 90%+ token savings on large pages.

`get_locator`

Fetch a single element entry by key.

Parameter	Required	Description
`scanName`	Yes	Registry filename without `.json`
`key`	Yes	Element key from `get_registry_keys`

Returns: key, tagName, text, attributes, locators (recommended, fallbacks, xpath, confidence, matchCount, strategy)

`get_registry`

Return the full registry JSON. High token cost — prefer get_registry_keys + get_locator.

Parameter	Required	Description
`scanName`	Yes	Registry filename without `.json`

`search_registry`

Filter registry entries by attributes.

Parameter	Required	Description
`scanName`	Yes	Registry filename without `.json`
`tagName`	No	Exact HTML tag match, e.g. `button`
`testId`	No	Substring match on `data-testid`
`text`	No	Substring match on direct text
`confidence`	No	`high`, `medium`, or `low`

All provided filters are combined with AND logic.

Scan modes

Mode	Selectors	Best for
`interactive` (default)	Buttons, inputs, links, roles + attributed elements	Most UI pages — low noise, high signal
`testId`	`data-testid`, `data-test`, `data-qa`, `data-cy` only	Apps with consistent test IDs
`full`	All candidate attributes including `[class]`	Maximum coverage — expect more noise

Recommendation: start with interactive. Switch to testId when the app has good testId coverage. Use full only when you need exhaustive discovery.

Registry format

Each scan writes registry/{scanName}.json — a map of element keys to metadata:

{
  "saveButton": {
    "key": "saveButton",
    "tagName": "button",
    "text": "Save",
    "attributes": {
      "testId": "goal-form_button_save",
      "id": null,
      "role": null,
      "ariaLabel": null,
      "placeholder": null
    },
    "locators": {
      "recommended": {
        "xpath": "//button[@data-testid='goal-form_button_save']",
        "tier": 1,
        "strategy": "testId",
        "matchCount": 1,
        "confidenceScore": 90
      },
      "fallbacks": [ "..." ],
      "xpath": "//button[@data-testid='goal-form_button_save']",
      "confidence": "high",
      "matchCount": 1,
      "strategy": "testId"
    }
  }
}

Locator confidence:

Level	Meaning
`high`	`matchCount === 1`, stable strategy (testId, id, relational)
`medium`	Unique but weaker strategy (text, aria)
`low`	`matchCount > 1` or positional/generic fallback

Registry JSON files are gitignored — generated locally via scan_page. Only registry/.gitkeep is committed to preserve the folder.

Token-efficient workflow

For AI clients reading registries, follow this order to minimize token usage:

1. list_registries          → see what's available
2. get_registry_keys        → lightweight key list (~500–4k tokens)
3. get_locator (per key)    → single entry (~100–200 tokens each)
   OR search_registry       → filtered subset

Avoid: get_registry         → full file (10k–80k+ tokens)

Registry size	`get_registry` (est.)	`get_registry_keys` (est.)
~39 KB	~10,000 tokens	~500–1,000 tokens
~321 KB	~80,000 tokens	~2,000–4,000 tokens

Estimates use characters / 4 — good for relative comparison, not exact billing.

Project structure

locator-mcp/
├── .cursor/
│   ├── mcp.json              # Cursor MCP config (committed, portable)
│   └── rules/                # Cursor AI rules for this repo
├── registry/
│   └── .gitkeep              # Scan output dir (JSON files gitignored)
├── src/
│   ├── server.ts             # MCP tool definitions
│   ├── index.ts              # Package entry
│   ├── scanner/
│   │   ├── scanner.service.ts        # Scan orchestration
│   │   ├── discover-elements.ts      # DOM element discovery by scan mode
│   │   ├── extract-element-context.ts # Attributes, ancestors, labels
│   │   ├── generate-xpath-variants.ts
│   │   ├── generate-relational-xpath.ts
│   │   ├── rank-xpath-variants.ts
│   │   ├── validate-locator.ts
│   │   ├── generate-key.ts
│   │   ├── detect-dynamic-value.ts
│   │   ├── generate-locators.ts
│   │   ├── save-registry.ts
│   │   └── scanner.types.ts
│   └── shared/
│       ├── constants.ts      # Selectors, scan modes, deny lists
│       ├── registry.ts       # Registry file I/O
│       └── utils.ts
├── tests/
│   └── scanner.spec.ts       # Unit tests
├── package.json
├── tsconfig.json
└── README.md

Development

# Install dependencies
npm install

# Run MCP server in terminal (stdio)
npm run dev

# Run tests
npm test

# Compile TypeScript
npm run build

Key conventions:

ESM imports with .js extension: import { x } from './foo.js'
XPath locators prefer data-testid: //tag[@data-testid="..."]
Relational XPaths disambiguate duplicate generic testIds
Registry path: registry/{scanName}.json

See .cursor/rules/ for full AI coding standards.

Testing

npm test

Uses Node built-in test runner (node:test) with tsx for TypeScript. Tests cover:

XPath variant generation and scoring
Generic testId disambiguation and relational XPath
Dynamic value detection and templates
Key generation with ancestor context
Constants and denylist behavior

Git conventions

Committed:

Source (src/), tests, config, .cursor/mcp.json, .cursor/rules/
registry/.gitkeep (empty folder placeholder)

Not committed (.gitignore):

Path	Reason
`node_modules/`	Dependencies — run `npm install`
`dist/`	Build output — run `npm run build`
`registry/*.json`	Local scan data — run `scan_page`
`.env*`	Secrets

Troubleshooting

`Cannot find module '/Users/you/src/server.ts'`

Global ~/.cursor/mcp.json ignored cwd. Fix: use project .cursor/mcp.json or npm run mcp --prefix <abs-path>.

`Failed to connect to browser`

Chrome must be running with --remote-debugging-port=9222
Playwright MCP must use the same --cdp-endpoint
Relaunch Chrome:

open -a "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir=/tmp/pw-chrome

`Connected to browser but no open page was found`

Open at least one tab in the debug Chrome instance before calling scan_page.

`registry '{scanName}.json' not found`

Run scan_page first, or call list_registries to see available files.

Duplicate / low-confidence locators

Use scanMode: "interactive" to reduce noise
Check warnings in the scan_page response
Prefer entries with confidence: "high" and matchCount: 1
For duplicate generic testIds, relational XPaths are generated automatically

MCP server shows twice in Cursor

Remove locator-mcp from either global ~/.cursor/mcp.json or project .cursor/mcp.json — keep only one.

Available Tools

6 tools

get_locatorB

Return a single element locator entry by key from a named registry.

ParametersJSON Schema

Name	Required	Description	Default
`scanName`	Yes	Registry filename without .json.
`key`	Yes	Element key from the registry.

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are available, so the description must fully disclose behavior. It only states that a single locator entry is returned, but omits important details like error handling for missing keys, side effects (none expected, not stated), or response format. This is insufficient for a mutation-free lookup tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no extraneous content. It is concise and front-loaded, conveying the essential purpose immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (2 required parameters, no output schema, no annotations), the description covers the basic operation but lacks details on return structure and error behavior. For a simple lookup tool, it is minimally complete but could benefit from mentioning that the locator entry is returned as an object with specific fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond the schema; it merely restates that the tool operates by key and registry name. The parameter descriptions in the schema already clarify the parameters adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a single element locator entry by key from a named registry. It uses a specific verb ('Return') and resource ('single element locator entry'), and distinguishes from siblings like 'get_registry' (returns entire registry) and 'get_registry_keys' (returns keys only).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus alternatives such as 'search_registry' or 'get_registry'. It lacks explicit usage context, prerequisites, or exclusions, leaving the agent without decision support.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_registryA

Return the full contents of registry/{scanName}.json — the map of element keys to CSS, XPath, and template locators.

ParametersJSON Schema

Name	Required	Description	Default
`scanName`	Yes	Registry filename without .json, e.g. goal-side-panel-locators.

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool returns file contents, implying a read-only operation with no side effects. However, it does not explicitly mention permissions, error handling, or confirm lack of destructive impact, leaving some ambiguity about behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the purpose and includes necessary details about the file path and contents. Every word adds value, with no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter, the description provides complete context: what the tool does (returns registry contents), how to use it (scanName param with example), and what the return structure is (map of locators). No output schema exists, but the description adequately covers return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds value by providing an example value ('goal-side-panel-locators') and showing the file path pattern ('registry/{scanName}.json'), which clarifies the parameter usage beyond the schema's description of 'Registry filename without .json'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns the full contents of a registry JSON file, specifying the file path pattern and that it contains a map of element keys to CSS, XPath, and template locators. This clearly distinguishes it from sibling tools like get_locator (single locator) or list_registries (listing names).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for retrieving the entire registry, but it does not explicitly state when to use it versus alternatives (e.g., get_locator for a single locator, get_registry_keys for keys only). The usage context is implied rather than explicitly guided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_registry_keysA

Return a lightweight list of element keys with tagName, testId, and confidence — much smaller than the full registry.

ParametersJSON Schema

Name	Required	Description	Default
`scanName`	Yes	Registry filename without .json.

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It only describes the return content but fails to disclose any behavioral traits such as read-only nature, performance characteristics, or potential side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the action and keeps all information relevant. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description mentions the fields returned, it lacks details on the structure (e.g., array of objects?), pagination, or error conditions. Given no output schema, more completeness would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter scanName, with a clear description. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns a lightweight list of element keys with specific properties (tagName, testId, confidence) and contrasts it with the full registry, effectively distinguishing from sibling tools like get_registry.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (when a lightweight list is needed instead of the full registry) but does not explicitly exclude use cases or mention alternatives beyond the contrast.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_registriesB

List all available registry files in the registry/ directory.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry full burden. It only states the operation (list) and location, but does not disclose side effects, permissions needed, output format, or limitations. For a read operation, minimal transparency is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no wasted words. It is front-loaded and directly states the purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (no parameters, no output schema, no annotations), the description is mostly complete. It specifies what is listed and where. However, it could mention whether the output is just names or full paths.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema already covers 100%. Per guidelines, baseline is 4 since the description need not add parameter semantics. No parameters to elaborate on.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists all available registry files in a specific directory. The verb 'list' and resource 'registry files' are specific. It implicitly distinguishes from siblings like 'get_registry' and 'get_registry_keys', but does not explicitly differentiate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus its siblings (e.g., get_registry, search_registry). The description lacks any context about use cases or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

scan_pageA

Scan an open browser page and extract all element locators. Supports two connection modes: (1) cdpEndpoint — Chrome DevTools Protocol HTTP URL (e.g. http://localhost:9222). Requires Chrome launched with --remote-debugging-port=9222. Use this when @playwright/mcp is also connected to the same external Chrome. (2) wsEndpoint — Playwright WebSocket URL (e.g. ws://127.0.0.1:PORT/...). Use this if you have the browser WS endpoint from a Playwright browser server. Exactly one of cdpEndpoint or wsEndpoint must be provided. scanName determines the registry file: registry/{scanName}.json. scanMode: interactive (default), testId, or full.

ParametersJSON Schema

Name	Required	Description
`cdpEndpoint`	No	CDP HTTP endpoint, e.g. http://localhost:9222. Use when Chrome was started with --remote-debugging-port.
`wsEndpoint`	No	Playwright WS endpoint, e.g. ws://127.0.0.1:PORT/GUID. Use when connecting via Playwright browser server.
`pageUrl`	No	URL substring to target a specific tab. Omit to use the first active page.
`scanName`	Yes	Registry filename without .json, e.g. goal-side-panel-locators.
`scanMode`	No	Element discovery mode: interactive (default), testId, or full.

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It explains connection modes and registry file naming, but doesn't mention side effects or safety. Since it's a read-like operation, it's acceptable but could note if it alters the page.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is well-structured with numbered modes, but slightly verbose; could be trimmed without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and sibling tools, the description fully explains operation, parameters, and usage context, leaving no key gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but the description adds value by clarifying mutual exclusivity of cdpEndpoint/wsEndpoint and specifying scanName usage, going beyond schema info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool scans an open browser page to extract element locators, with two specific connection modes, making the purpose unambiguous and distinct from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly describes when to use each connection mode (cdpEndpoint vs wsEndpoint) with examples, and states exactly one must be provided, providing clear guidance over alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_registryA

Search a registry by tagName, testId, text, or confidence. Returns matching entries only.

ParametersJSON Schema

Name	Required	Description
`scanName`	Yes	Registry filename without .json.
`tagName`	No	Filter by HTML tag name.
`testId`	No	Filter by data-testid (substring match).
`text`	No	Filter by direct text (substring match).
`confidence`	No	Filter by locator confidence.

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description states it returns matching entries only, but with no annotations, it lacks disclosure on side effects, authorization needs, rate limits, or behavior when no matches found.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each serving a purpose. The first sentence specifies action and parameters, the second clarifies return behavior. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a search tool with 5 parameters and no output schema, the description is missing details on return format, pagination, error handling, or performance implications. It is minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description lists the filter parameters but does not add new semantics beyond the schema; the required scanName is not mentioned in description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches a registry and lists the filter parameters (tagName, testId, text, confidence). It distinguishes from siblings like get_registry (full retrieval) and list_registries (listing all).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (when filtering by tag, testId, text, or confidence) but does not explicitly state when not to use or provide comparison with alternatives like get_registry_keys or get_locator.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

6 tool updatesv0.1.0Jun 23, 2026
- First observedget_locator
- First observedget_registry
- First observedget_registry_keys
- First observedlist_registries
- First observedscan_page
- First observedsearch_registry

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

Disambiguation5/5

Each tool targets a distinct operation: retrieving a single locator, full registry, keys list, registry listing, scanning, or searching. No overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with snake_case: get_locator, get_registry, get_registry_keys, list_registries, scan_page, search_registry.

Tool Count5/5

Six tools is well-scoped for a locator management server, covering scanning, retrieval, listing, and searching without being excessive or insufficient.

Completeness5/5

The tool set covers the full lifecycle: scanning pages to extract locators, retrieving entire registries or specific entries, searching, and listing. No obvious gaps.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

JxBrowser MCP Server A
io.github.TeamDev-IP
MCP server to assist with JxBrowser development.
Developer Tools Browser Automation
22
mcp-webextratorOAuth
io.github.AceDataCloud
MCP server for web extraction and rendering via AceDataCloud WebExtrator
Web Scraping Browser Automation
2
UI Verify A
io.github.igrlk
MCP server for visual regression testing: triage a PR's UI diffs from your coding agent.
9118
Ua E Commerce Price Tracker Mcp
io.github.varvararatta
MCP server for ua_e_commerce_price_tracker_mcp
E-commerce & Retail Web Scraping
2

Related MCP Servers

selenium-mcp
Browser Automation Web Scraping
SCV-Consultants
A
license
B
quality
C
maintenance
A production-ready MCP server that exposes Selenium 4 browser automation as MCP tools.
Updated 5 months ago (2026-04-07 14:57 UTC)
27
MIT
paparazzi
Browser Automation Developer Tools
nicksenap
A
license
Not graded
quality
D
maintenance
MCP server that connects to your browser to capture screenshots, inspect console logs, network requests, and more via Chrome DevTools Protocol.
Updated 6 months ago (2026-02-24 18:51 UTC)
6
2
MIT
qa-ai-mcp-server-gits
Testing & QA Tools CI/CD & DevOps Developer Tools
gits5213
A
license
B
quality
D
maintenance
MCP server for end-to-end QA automation: generates test scenarios, discovers Playwright locators, creates TypeScript test code, executes tests, and creates GitHub issues for failures.
Updated 3 months ago (2026-06-12 20:07 UTC)
6
17
MIT
Playwright Pool
Browser Automation Testing & QA Tools
zbrooklyn-claude-labs
A
license
Not graded
quality
C
maintenance
MCP server for browser automation with shared authentication and built-in UI auditing.
Updated 3 months ago (2026-06-21 18:45 UTC)
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Eswarr11/locator-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

locator-mcp

Table of contents

Features

How it works

Prerequisites

Quick start

Run locally

MCP configuration

Cursor (project) — recommended

Cursor (global)

Claude Desktop

Production (compiled)

With Playwright MCP (for scan_page)

MCP tools reference

scan_page

list_registries

get_registry_keys

get_locator

get_registry

search_registry

Scan modes

Registry format

Token-efficient workflow

Project structure

Development

Testing

Git conventions

Troubleshooting

Cannot find module '/Users/you/src/server.ts'

Failed to connect to browser

Connected to browser but no open page was found

registry '{scanName}.json' not found

Duplicate / low-confidence locators

MCP server shows twice in Cursor

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

With Playwright MCP (for `scan_page`)

`scan_page`

`list_registries`

`get_registry_keys`

`get_locator`

`get_registry`

`search_registry`

`Cannot find module '/Users/you/src/server.ts'`

`Failed to connect to browser`

`Connected to browser but no open page was found`

`registry '{scanName}.json' not found`