# screen-mcp

MCP local (stdio) que dá ao Claude controle da sua tela no Windows: **ver, achar por imagem, clicar/digitar, gravar e repetir macros, e agendar**. Sem porta exposta.

Veja [SPEC.md](SPEC.md) pro design completo.

## Instalar

```
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
```

Registre no seu `~/.claude.json`:

```json
{
  "mcpServers": {
    "screen-mcp": {
      "command": "<caminho>\\.venv\\Scripts\\python.exe",
      "args": ["<caminho>\\screenmcp\\cli.py", "serve"]
    }
  }
}
```

**Reinicie o Claude Code** pra ele carregar o server. Depois é só pedir em linguagem natural ("tira um print", "acha o botão X e clica", "grava uma macro", etc.).

## Ferramentas

- **Ver/achar:** `list_monitors`, `screenshot`, `screen_info`, `find_image`, `wait_for_image`
- **Agir:** `move`, `click`, `drag`, `type_text`, `press_keys`, `scroll`
- **Macros:** `list_macros`, `record_macro`, `replay_macro`, `delete_macro`
- **Agendar:** `schedule_macro`, `list_schedules`, `unschedule`

## Os 4 modos

1. **Ao vivo** — eu uso as ferramentas vendo a tela e decidindo.
2. **Macro gravada** — `record_macro("nome")` abre uma janela; você faz as ações; **F9** salva. Depois `replay_macro("nome", times=N)`.
3. **Loop com condição** — `wait_for_image(...)` + ação, repetido (ex: refresh até um botão aparecer).
4. **Agendado** — `schedule_macro("nome", "DAILY:09:00")` cria tarefa no Agendador do Windows (`MINUTE:N` | `HOURLY` | `DAILY:HH:MM` | `ONLOGON`); roda sem o Claude presente.

## Achar por imagem (o jeito robusto)

Salve um recorte (.png) do elemento em `templates/` e use `find_image("botao.png")` → devolve `x,y` globais do centro pra `click`. Resistente a janela que se move, melhor que chutar coordenada.

## Segurança

- **Mouse no canto superior-esquerdo aborta tudo na hora** (failsafe).
- **F12 aborta** um replay em andamento.
- Teto de loops + pausa entre ações. Log em `logs/actions.jsonl`.

## Rodar standalone (sem Claude)

```
.venv\Scripts\python.exe screenmcp\cli.py list
.venv\Scripts\python.exe screenmcp\cli.py record minha_macro
.venv\Scripts\python.exe screenmcp\cli.py replay minha_macro --times 5
```

## Reinstalar deps

```
.venv\Scripts\python.exe -m pip install -r requirements.txt
```

## Coordenadas / multi-monitor

Tudo em coords globais do virtual desktop (monitor primário = origem; monitores à esquerda têm x negativo). Processo é per-monitor DPI aware. Em setups com **DPI mista** entre monitores, prefira `find_image` a chutar coordenada.

## Licença

MIT