# healix-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an AI agent (Claude Code, Cursor, Windsurf, …) **build and heal real WebdriverIO tests by watching your live app** — observing the actual DOM, deriving durable selectors, scaffolding page objects and specs, running them, and self-healing on failure.

What it produces is a standalone [`wdio-healix-service`](https://www.npmjs.com/package/wdio-healix-service) suite that runs in CI with **no AI in the loop**.

The local triage-v1 implementation distinguishes application defects, automation
defects, test-data/environment blockages and unresolved outcomes. It requires
diagnosis before paused locator repair and separates interactive progress from
standalone acceptance. See [implementation, compatibility and verification](TRIAGE-IMPLEMENTATION.md)
for the coordinated-release requirements and remaining evaluation gates. These
changes are not yet published.

```jsonc
// .mcp.json
{
  "mcpServers": {
    "healix": { "command": "npx", "args": ["healix-mcp"], "env": { "HEALIX_PORT": "4000" } }
  }
}
```
> Or scaffold everything at once: `npx create-healix my-app`

## What it gives the agent
- **`healix_guide`** — the authoritative framework model + workflow (read first).
- **`healix_start_session` / `healix_status` / `healix_run_test`** — drive a live, stateful session.
- **`healix_wait`** — block until the worker's next lifecycle event (test/hook end, pause, terminal dialog open/close, abort); every response ends with "Console since your last look" (chronological, nothing skipped).
- **`healix_get_dom` / `healix_validate_locator` / `healix_get_aria_resolve`** — observe the real UI and derive durable selectors (never guessed).
- **`healix_scaffold_page` / `healix_scaffold_suite`** — author POMs and specs that can't get the import, decorators, or wrappers wrong.
- **`healix_fix_locator` / `healix_replace_locator`** — heal a paused test in place.

Edit a spec or page object and just **re-run** — Healix auto-reloads the changed files before running.

## Requirements
- A project using **`wdio-healix-service`** (the [`create-healix`](https://www.npmjs.com/package/create-healix) scaffold sets both up).
- Node 18+.