# uv
uv pip install -e .

# pipx (stdio MCP server on PATH)
pipx install .

mcp-vision doctor          # display / accessibility / backends
mcp-vision install         # write Claude Desktop + Cursor MCP config
mcp-vision serve           # stdio JSON-RPC (logs on stderr only)

{
  "mcpServers": {
    "mcp-vision": {
      "command": "mcp-vision",
      "args": ["serve"]
    }
  }
}

flowchart TB
    Host["Claude / Cursor / agent.py"] -->|stdio JSON-RPC| Server["mcp-vision serve"]
    Server --> Inspect["inspect_screen"]
    Inspect --> Capture["mss capture + JPEG downscale"]
    Capture --> Parser["SoM boxes + optional OCR"]
    Parser --> Governor{"governor"}
    Governor -->|SAFE_READ / ROUTINE_WRITE| Actuate["click / type / hotkey"]
    Governor -->|RESTRICTED| HUD["transparent HUD confirm"]
    HUD -->|Space| Actuate
    HUD -->|Esc / timeout| Abort["ActionResult.ok=false"]

python agent.py --as general "make a note called Ideas with a haiku about the sea"
python agent.py --as web-researcher "summarize the top story on news.ycombinator.com"
python agent.py --as general --model claude "..."
python agent.py --tui --as general "..."

graph LR
    A[Task] --> B[qwen3:8b picks a tool]
    B --> C{Tool}
    C -->|Notes / Reminders / Calendar| D[AppleScript]
    C -->|web_*| E[Playwright AX + SoM fallback]
    D --> V{eval gate}
    E --> V
    V --> F[trace.jsonl + OTLP runs/id/trace.json]
    F --> B

PYTHONPATH=src pytest tests/test_capture.py tests/test_parser.py tests/test_governor.py tests/test_mcp_tools.py tests/test_config_sync.py
python tests/run.py          # existing module self-checks
python bench/runner.py       # dry agent loop
python tests/e2e_web.py      # headless Playwright workflows