This server provides browser/mobile automation with self-healing selectors. Capabilities include:
Navigate: Open a URL in the browser or mobile app.
Click elements: Tap/click an element, automatically healing failed selectors.
Fill elements: Input values into form fields, with automatic selector healing.
Get content: Retrieve text content from the current web page or layout XML from a mobile screen.
Evaluate JavaScript: Run JS scripts on the current web page.
Take screenshots: Capture and save a screenshot of the current page/screen.
Allows Appium to be used as the automation engine for native mobile apps, with selector healing based on XML page source layouts.
Allows a local Ollama instance to power the healing LLM via an OpenAI-compatible endpoint.
Allows OpenAI-compatible models and custom endpoints to be used as the LLM backend for selector healing.
Allows Selenium WebDriver to be used as the browser automation engine instead of Playwright, with the same self-healing tools.
Local-first Model Context Protocol (MCP) server & agents for Playwright QA self-healing and FinOps SaaS license reclamation. Zero DOM egress.
Website & Docs • Healwright Guide • SeatPrune Guide • Commercial Pricing
SeatPrune (skildunne/seatprune) is an autonomous SaaS seat governance and license reclamation MCP server that audits GitHub, Copilot, and Slack utilization to detect zombie seats, enforce dry-run safety locks, and reclaim spend leakage.
Related MCP server: Mochi
Healwright (healwright-mcp) is an autonomous Playwright self-healing selector engine that turns red CI pipelines green in under 500ms by analyzing compact ARIA snapshots via Gemini 2.5 and hot-fixing spec files on disk.
sequenceDiagram
autonumber
participant Runner as Playwright Test Runner
participant Fixture as @healwright/fixture (Client Hook)
participant Server as Healwright MCP Server
participant Gemini as Gemini API (2.5 Pro / Flash)
participant Sandbox as Headless Playwright Sandbox
participant Patcher as AST / Text Patcher
Runner->>Runner: Locator fails (Timeout / Assertion Error)
Runner-->>Fixture: Catch Exception + stack trace
Note over Fixture: Extract spec file coordinates (file, line, col)
Fixture->>Fixture: Capture page.ariaSnapshot({ boxes: true })
Fixture->>Server: Call heal_selector(broken, error, ARIA, URL, file, line, col)
Server->>Gemini: Request Healed Locator (response_schema, temp 0.1)
Note over Gemini: Prioritize accessibility (getByRole, getByTestId, locator.or())
Gemini-->>Server: Return JSON (proposed_playwright_call, fallback_expression, rationale, type)
Server->>Sandbox: Load ARIA snapshot / DOM content
Note over Sandbox: Translate TS selectors to Python syntax if evaluating on python host
Server->>Sandbox: Evaluate locator count & visibility
alt Verification Success (count == 1 & visible)
Sandbox-->>Server: Selector verified!
Note over Server: status = "verified_unique"
else Verification Failed
Note over Server: Evaluate fallback_expression
Sandbox-->>Server: Status = "failed" or "ambiguous_match"
end
alt status == "verified_unique" AND coordinates provided
Server->>Patcher: Invoke patch_source_file(file, line, col, healed_locator)
Note over Patcher: Parse AST (Python AST / Babel JS) & rewrite spec call
Patcher-->>Server: Patch completed on disk
end
Server-->>Fixture: Return HealedSelectorResponse (healed_locator, status)
Fixture->>Fixture: Dynamically evaluate healed locator via eval()
Fixture->>Runner: Re-execute action and resume test executionCompact ARIA Snapshot Ingestion: Utilizes Playwright's native page.ariaSnapshot({ boxes: true }) API to capture clean, token-efficient YAML accessibility tree layouts instead of bloated raw HTML structure.
Resilient Locator Generation: Directs Gemini to produce modern Playwright locators mapped strictly to accessibility guidelines:
page.getByRole() matching accessibility labels and descriptions.
page.getByTestId(), page.getByLabel(), or page.getByPlaceholder().
Chained fallback structures using locator.or().
Brittle CSS/XPath locators as a last resort.
Sandboxed Locator Evaluator: Automatically evaluates and executes JS/TS Playwright locator call expressions dynamically inside a headless Playwright Chromium sandbox browser to guarantee element uniqueness (count === 1) and visibility.
AST-Based Source Code Patching: Includes a Python AST rewriter (using ast modules) and JavaScript/TypeScript rewriter (using @babel/parser / @babel/traverse) that locates the exact code coordinates of the failing locator in the source file on disk and overwrites it.
Smart Playwright Client Hooks: Fully integrated via @healwright/fixture (TypeScript) and healwright_locator (Python pytest) to capture error line/col locations from stack traces and run self-healing.
Ensure you have Python 3.11+ and Node.js installed on your VM or runner.
# Clone the repository
git clone https://github.com/skildunne/awarse-mcp.git
cd awarse-mcpCreate a .env file in the root directory:
GEMINI_API_KEY="your-gemini-api-key"
GEMINI_MODEL="gemini-2.5-pro" # Defaults to gemini-2.5-pro
HEALWRIGHT_HOST="0.0.0.0"
HEALWRIGHT_PORT=8000
HEALWRIGHT_MOCK_HEAL=false # Set to true for offline testing# Set up virtual environment and install python packages
uv venv
source venv/bin/activate
uv pip install -r requirements.txt
uv run playwright install chromium --with-deps
# Optional: Install Babel for TS AST parsing (falls back to text-slice parser if missing)
npm install @babel/parser @babel/traverse @babel/generatorHealwright supports dual transport channels:
Local stdio mode (Default):
uv run src/server/mcp_server.pyRemote SSE mode (shared server):
uv run src/server/mcp_server.py sseAdd this block to your local claude_desktop_config.json:
{
"mcpServers": {
"healwright-mcp": {
"command": "/path/to/awarse-mcp/venv/bin/python",
"args": [
"/path/to/awarse-mcp/src/server/mcp_server.py"
],
"env": {
"GEMINI_API_KEY": "YOUR_GEMINI_API_KEY_HERE"
}
}
}
}Add this to your Cursor settings under MCP -> Add New MCP Server:
Name: healwright-mcp
Type: stdio
Command: /path/to/awarse-mcp/venv/bin/python /path/to/awarse-mcp/src/server/mcp_server.py
heal_selectorInvokes the Healwright healing pipeline:
broken_selector (string, required): The failing locator expression.
error_message (string, required): The error message details.
dom_snapshot (string, required): Compact YAML ARIA snapshot.
target_url (string, optional): Active URL context.
file_path (string, optional): Absolute path of the test file on disk.
line_number (integer, optional): The line number of the failing locator call.
column_number (integer, optional): The column number of the failing locator call.
{
"proposed_playwright_call": "page.getByRole('button', { name: 'Submit' })",
"selector_type": "role",
"confidence_score": 0.98,
"rationale": "The original ID selector was removed during UI layout changes. The target button is uniquely identifiable by its accessible role and text label.",
"fallback_expression": "page.locator('#healed-submit-action-button')",
"verification_status": "verified_unique"
}To run the full unit and integration test suite:
# Run pytest tests
PYTHONPATH=. uv run pytest tests/Integrate Healwright into your test runners using the templates in examples/ or the npm package @healwright/fixture / npx healwright:
TypeScript Playwright Fixture: See examples/healwrightFixture.ts (captures ariaSnapshot, parses the spec file stack trace, calls Healwright, and patches the file).
Python Playwright pytest Fixture: See examples/healwright_locator.py.
Awarse Labs provides local-first, privacy-preserving developer tooling.
Capability | Community (CLI / OSS) | Pro Edition |
Healwright: Local FastMCP Locator Healing | ✅ | ✅ |
Zero DOM / Trace Egress | ✅ | ✅ |
SeatPrune: Dry-Run SaaS License Audits | ✅ | ✅ |
Pre-built FastMCP Binary Distributions | — | ✅ Included |
Automated CI/CD Test Branch Healing (PR bot) | — | ✅ Included |
Multi-Provider Connectors (GitHub, Slack, Jira) | Basic CLI | ✅ Automated Action |
Commercial SLA & Priority Locator Heuristics | — | ✅ Included |
👉 Compare plans and activate licenses at awarselabs.com/#pricing.
Core packages are licensed under the MIT License.
Commercial subscriptions and Pro features are operated by Awarse Labs (CRO Business Name Registration No. 793328, Ireland).
For enterprise support or custom FastMCP integration inquiries: support@awarselabs.com.
⭐ If you find Awarse MCP useful for stabilizing your Playwright CI pipelines, consider giving us a star!
Click/tap an element. Automatically heals the selector if it fails.
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a notable behavior (automatic selector healing) and explicitly states the action (click/tap). It does not hide major side effects or expectations, though it does not mention potential errors or side effects like navigation. Given the absence of annotations, this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using only two short sentences. It conveys the essential action and a key behavioral feature without any unnecessary words. This is ideal for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple click action, the description covers the core functionality but omits details about return values, error handling, or expected behavior on failure (beyond selector healing). Given the simplicity and the presence of sibling tools, the description is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, 'selector', has no description in the schema or in the tool description. The description does not explain what format the selector should be (CSS, XPath, etc.) or any constraints. This leaves the parameter meaning largely unspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Click/tap') and target ('an element'), which distinguishes it from siblings like fill_element, navigate, and get_content. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that it automatically heals selectors, which is a useful behavior note, but it does not provide any guidance on when to use this tool versus alternatives (e.g., when to use fill_element instead). No explicit conditions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate a JavaScript string on the current web page (Supported on Web frameworks only).
| Name | Required | Description | Default |
|---|---|---|---|
| script | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source of behavioral information. It does not disclose whether evaluation is sandboxed, can modify the page, returns a value, or has side effects. This is a significant gap for a tool that executes arbitrary code.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that includes the core action and a necessary constraint in parentheses. It wastes no words and is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides enough for basic understanding, but omits details about output, failure modes, or security implications. For a tool with one parameter, the context is adequate but not comprehensive, especially given the arbitrary code execution nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, 'script', is described implicitly as a 'JavaScript string', which clarifies its type. However, it does not specify expected format, allowed content, error handling, or return value. Partial coverage of the parameter's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (evaluate a JavaScript string) and the target (current web page), and includes a specific constraint ('Supported on Web frameworks only'). This leaves no ambiguity about the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a conditional usage note (only on web frameworks), but does not explicitly contrast with sibling tools like navigate or click_element, nor does it state when custom JavaScript is preferred over other operations. The constraint provides partial guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fill a form/input element with a value. Automatically heals the selector if it fails.
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | ||
| selector | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds the useful behavioral trait that the selector is 'automatically healed' if it fails, which goes beyond the schema. However, it does not mention whether it types like a user, clears existing values, triggers events, or requires focused/visible elements, leaving significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: two short sentences with no fluff. The core purpose is front-loaded in the first sentence, and the second sentence adds meaningful behavior. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the context is thin. The description tells what the tool does and one behavioral nuance, but it omits important details: selector format, whether it replaces or appends text, and any page-level constraints. For a two-parameter tool it is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It implications that 'selector' refers to the form/input element and 'value' is the value to fill, but it does not explain selector syntax or value subtlety. It provides basic meaning above the raw schema but does not fully compensate for the missing parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Fill a form/input element with a value.' It clearly describes what the tool does and is distinct from siblings like click_element and get_content. However, it does not explicitly name any sibling or contrast itself with them, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not say when to use fill_element over click_element or evaluate_js, nor does it mention prerequisites such as element visibility or page readiness. The context for when this tool is appropriate must be inferred from its name and first sentence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the text content (web) or layout XML (mobile) of the current page/screen.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the two output modes (text for web, layout XML for mobile), which is helpful, but it does not state that the operation is read-only, whether any session-side effects occur, or what happens if no page is loaded. Lacking those details, transparency is only partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that states the action and the platform-dependent outcome with no fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters and has an output schema, so the description needn't detail return values. It covers the core behavior well for both web and mobile contexts. A minor gap is lack of a note on expected preconditions (e.g., a session must exist), but this is not critical for a getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema is empty, so the description cannot add parameter-level meaning. Baseline for no parameters is 4, and the description needs no additional detail here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Retrieve') and resource ('text content (web) or layout XML (mobile) of the current page/screen'). It clearly distinguishes the tool from siblings like navigate, click_element, and take_screenshot, none of which retrieve content in this way.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool reads the current page/screen but gives no explicit when-to-use context or exclusions relative to siblings such as evaluate_js, which could also extract DOM content. Usage guidance is only implicit, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take a screenshot of the current page/screen and save it locally.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | No | screenshot.png |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'save it locally', indicating file creation, but does not mention potential side effects like overwriting existing files or file format details beyond the default extension.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It directly states the action and outcome without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple action, the description is adequate. It specifies the output (screenshot saved locally) but could benefit from mentioning that it captures the visible viewport or current screen area, which is implied but not explicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'filename' is self-explanatory, and its default value 'screenshot.png' clarifies the expected format. The description does not explicitly explain it, but the meaning is obvious and low-risk.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Take' and resource 'screenshot' clearly define the action, and it is distinct from the sibling tools (navigate, click, fill, get_content, evaluate_js). No ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for capturing the current visual state, but it does not explicitly state when to use it versus alternatives. However, given its unique purpose, the lack of explicit guidance is acceptable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0click_elementevaluate_jsfill_elementget_contentnavigatetake_screenshotScored across 6 tools
Each tool has a clearly distinct purpose: navigation, clicking, filling, content retrieval, JS evaluation, and screenshots. No two tools overlap in functionality.
All tools follow a consistent verb_noun pattern (navigate, click_element, fill_element, get_content, evaluate_js, take_screenshot). The naming is uniform and predictable.
Six tools is a well-scoped set for a browser/mobile automation server, covering essential actions without unnecessary bloat or excessive granularity.
The set covers the core automation lifecycle: navigation, interaction, content extraction, JS execution, and screenshots. Missing explicit waiting or element-state checks, but these are minor gaps.
MCP server for Mint — AI-powered QA that runs your app in a real browser on every PR.
SEO MCP server: crawl your site, find AI-visibility gaps, and ship the fix from your coding agent.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Run, debug, and triage tests from your IDE using natural language, no dashboard switching, no manual data transfers. The TestMu AI (formerly LambdaTest) MCP Server is a single remote server exposing four tool suites: HyperExecute — analyze your project, generate YAML configs and test runner commands, then monitor jobs and sessions. Automation — pull a TestID's details plus command, network, and console logs into one chat for instant root-cause analysis. Includes mobile app upload. SmartUI — explain pixel, layout, DOM, and perceptual changes in a visual regression run, with context-aware React/HTML/CSS fixes. Accessibility — audit any public URL or a local React app against WCAG and get ready-to-apply remediation steps. Connects over https://mcp.lambdatest.com/mcp using OAuth 2.1 — no API keys in your config. One-click install in Cursor; works with Claude, GitHub Copilot, Cline, and any MCP client. Tests execute on the TestMu AI cloud: 3,000+ browsers and 10,000+ real devices.
