# MCP PC Controller

Plataforma Windows para permitir que um agente MCP observe e opere um PC remoto por **captura HDMI + HID ESP32-S3**, mantendo separadas as responsabilidades do PC controlador (`MCP_HOST`) e da máquina física controlada (`REMOTE_PC`). O projeto também inclui OCR/visão, automação de Visual Studio, memória/estratégia, supervisão, recuperação e mecanismos de inteligência operacional.

O objetivo do projeto é evoluir para um controlador cada vez mais **rápido, confiável, seguro, observável e autônomo**, capaz de verificar o efeito real de suas ações em vez de considerar apenas o envio de comandos como sucesso.

## Arquitetura geral

Fluxo principal:

```text
ChatGPT / cliente MCP
        |
        v
MCP Streamable HTTP
        |
        v
Control plane / Work plane
        |
        +--> Captura HDMI --> visão/OCR --> contexto/decisão
        |
        +--> ESP32-S3 --> BLE/USB HID --> teclado/mouse do REMOTE_PC
        |
        +--> memória / estratégia / observabilidade / recuperação
```

Princípios importantes:

- `MCP_HOST` e `REMOTE_PC` são targets diferentes e não devem ser confundidos.
- Operações potencialmente bloqueantes são isoladas do control plane quando necessário.
- Ações físicas devem, sempre que possível, ser confirmadas por observação posterior da tela.
- ACK de transporte não significa necessariamente que o objetivo visual foi atingido.
- Estado, memória e aprendizado devem melhorar decisões futuras sem armazenar conteúdo confidencial desnecessariamente.

## Instalação e início

1. Execute `setup.bat` com Python compatível instalado.
2. Se `cloudflared` não estiver no `PATH`, coloque `cloudflared.exe` em `tools\cloudflared\`.
3. Conecte a placa de captura HDMI ao `MCP_HOST`.
4. Conecte o ESP32-S3 responsável pelo HID.
5. Execute `start.bat` e utilize a GUI para iniciar os componentes necessários.

O endpoint MCP local normalmente utiliza:

```text
http://127.0.0.1:8765/mcp
```

Quando um túnel remoto estiver habilitado, trate sua URL como uma credencial de alto privilégio: ela pode conceder acesso às capacidades expostas pelo MCP. Para exposição permanente, utilize autenticação e controle de acesso apropriados. Não publique URLs, tokens ou credenciais no repositório.

## Componentes

O projeto é dividido em áreas com responsabilidades distintas, incluindo:

- `app/` — runtime, coordenação, GUI, decisões, contexto, automações e integrações.
- `mcp_server/` — servidor MCP, catálogo de tools, schemas, guidance e roteamento.
- `capture/` — captura HDMI, frames, regiões, detecção de mudança, visão e OCR local.
- `esp32/` — comunicação serial e transporte de comandos HID.
- `cloudflare/` — gerenciamento do túnel sem misturar seu lifecycle com o lifecycle do MCP.
- `memory/` — código de memória/estratégia; artefatos de runtime não devem ser versionados.
- `tests/` — regressões determinísticas e gates de segurança/compatibilidade.

## OCR e percepção visual

A percepção visual é parte do feedback operacional do agente, não apenas uma ferramenta de screenshot.

O pipeline procura trabalhar no formato:

```text
captura
  -> freshness / mudança de frame
  -> ROI
  -> OCR / visão
  -> confidence e contexto
  -> decisão
  -> ação
  -> nova captura
  -> verificação da pós-condição
```

Entre as capacidades e objetivos arquiteturais estão:

- captura completa e por ROI;
- detecção de mudança para evitar processamento redundante;
- cache de OCR com invalidação baseada no conteúdo visual;
- localização de texto e elementos visuais;
- reconstrução de conteúdo rolável;
- confirmação de frames frescos após ações;
- leitura de conteúdo do topo até o fim quando a tarefa exige visão completa;
- diferenciação entre leitura `COMPLETE` e `PARTIAL` quando os limites do conteúdo não puderem ser comprovados.

O leitor de documentos/conteúdo rolável procura primeiro estabelecer o **topo real da região**, coleta as viewports progressivamente e só deve declarar leitura completa quando também houver evidência de término. Tanto a busca pelo topo quanto a detecção de fim por ausência de mudança são avaliadas na **mesma ROI alvo da leitura**, de modo que animações, cursor, status bar ou outras alterações fora do conteúdo não provoquem scrolls/OCR extras nem ocultem o fim real.

Depois de um scroll, o frame devolvido pelo `fresh_frame_barrier` é reutilizado diretamente como a próxima viewport de OCR. Isso evita uma nova `capture.read()`/cópia redundante entre páginas e mantém o OCR vinculado ao frame que realmente satisfez a barreira de freshness.

## Mouse e teclado

O subsistema HID busca fornecer operações confiáveis de:

- movimento relativo e posicionamento verificado do mouse;
- click, double-click, drag/drop e scroll;
- teclado, hotkeys e liberação segura de teclas/modificadores;
- digitação longa por protocolo transacional em chunks;
- Unicode/layouts suportados pelo pipeline;
- recuperação de falhas de comunicação;
- autorização de digitação quando exigida pelo contexto;
- confirmação visual de ações importantes.

O projeto mantém modelo de topologia/calibração para relacionar captura, monitor e coordenadas do cursor. Atualizações desse estado são protegidas contra concorrência para evitar perda silenciosa de amostras de calibração.

### Smart HID Protocol v2 no HOST

O `MCP_HOST` possui um adapter de negociação para o **Smart HID Protocol v2** do firmware ESP32. A extensão é aditiva e mantém fallback transparente para o protocolo legado quando o firmware não anuncia suporte.

- `CAPABILITIES` é consultado e cacheado por um TTL curto; Smart HID só é aceito quando `SMART_HID_PROTOCOL >= 2` e o firmware declara `REMOTE_USB_PROFILE=KEYBOARD_MOUSE_HID_ONLY`.
- Limites estruturais anunciados em `JOB_MAX_ACTIONS` e `JOB_MAX_ACTION_BYTES` são normalizados ao teto do contrato conhecido do firmware (32 ações e 192 bytes por ação). Valores anunciados acima desses tetos não fazem o HOST montar jobs/payloads que o ESP32 real rejeitaria depois do round-trip.
- Limites anunciados em `CAPABILITIES` não são adivinhados quando ausentes ou inválidos: `JOB_MAX_ACTION_BYTES` ausente, malformado ou não positivo desativa `EXEC_IDEMPOTENT` e `JOB_ATOMIC`; `JOB_MAX_ACTIONS` inválido desativa somente `JOB_ATOMIC`. O protocolo/perfil e capabilities independentes como telemetry/watchdog/pacing continuam utilizáveis, e o `raw` original permanece disponível para diagnóstico.
- `EXEC` usa `command_id` idempotente para impedir duplicação de efeitos físicos em retries.
- IDs fornecidos pelo chamador para `EXEC` e jobs são preservados exatamente quando válidos; o HOST não remove espaços nem trunca silenciosamente. Qualquer whitespace Unicode ou valor acima de 64 bytes UTF-8 é rejeitado antes de `EXEC`/`JOB_BEGIN`; quando o ID é omitido, o HOST gera um identificador seguro. O fallback legado continua sem validar um ID Smart HID que não será usado.
- `JOB_BEGIN`/`JOB_ADD`/`JOB_COMMIT` permitem sequências bounded e retry-safe; textos são divididos por **bytes UTF-8** respeitando o limite anunciado pelo firmware.
- O retry de um `job_id` já concluído é encerrado ainda no `JOB_BEGIN` quando o firmware retorna `DUPLICATE_COMPLETE`; o HOST considera o job duplicado suprimido e **não envia novamente `JOB_ADD` nem `JOB_COMMIT`**, evitando repetir os efeitos físicos do job inteiro.
- Ações Smart HID de `TYPE_TEXT` mantêm o conteúdo exato do chunk, incluindo espaços e quebras de linha intencionais nas bordas; o HOST não normaliza nem remove esses bytes antes de codificar a ação.
- `TYPE_TEXT` com texto vazio é tratado no HOST como **no-op seguro**: nenhuma ação vazia é serializada para o firmware, inclusive dentro de jobs mistos, enquanto textos não vazios continuam preservados byte a byte.
- Para texto não vazio, o orçamento de `TYPE_TEXT` inclui também os bytes do prefixo `TYPE_TEXT `: se `JOB_MAX_ACTION_BYTES` não comportar prefixo + ao menos um byte de payload, o HOST falha localmente com `ACTION_TOO_LARGE:type_text` em vez de serializar uma ação acima do limite anunciado.
- `DOUBLE_CLICK`, `MOVE_SMOOTH`, `DRAG_REL`, `WAIT` e primitivas de teclado/mouse podem ser executadas localmente pelo ESP32 para reduzir round trips quando a capability correspondente existe.
- `TELEMETRY` e capabilities são tratados como evidência de transporte/dispositivo, não como confirmação de sucesso semântico.
- Firmware legado continua usando os comandos existentes; fallback de drag executa `RELEASE_ALL` em recuperação para reduzir risco de botão preso.
- O framing HOST valida antes da escrita IDs Smart HID vazios, acima de 64 bytes ou contendo qualquer whitespace Unicode, além dos limites observáveis de `WATCHDOG` (250..60000 ou `OFF`) e `KEYBOARD_PACING` (press 1..250 ms, gap 0..250 ms), evitando ambiguidades de framing e round trips que o firmware determinístico rejeitaria.
- A gramática de teclado também é validada no HOST antes de qualquer fallback HID: teclas individuais aceitam somente os aliases, ASCII e F1..F12 suportados pelo firmware, enquanto hotkeys aceitam no máximo seis teclas não-modificadoras; entradas como `F1XYZ` ou nomes desconhecidos falham localmente em vez de chegar ao ESP32/parser legado.
- Tokens de tecla não são normalizados por trim: qualquer whitespace ASCII ou Unicode dentro ou ao redor de um token é rejeitado localmente. Em hotkeys, cada tecla/modificador deve ser um elemento separado; a tecla de espaço é representada explicitamente pelo alias `SPACE`.
- As primitivas motoras também são validadas antes de qualquer fallback físico: `DOUBLE_CLICK` aceita 10..1000 ms e `MOVE_SMOOTH`/`DRAG_REL` aceitam `steps` 1..200 e duração 0..10000 ms; entradas fora desses limites falham no HOST sem virar clique, movimento ou drag legado.
- Os operandos assinados de `MOVE`, `MOVE_SMOOTH`, `DRAG_REL`, `SCROLL` e `HSCROLL` seguem exatamente o `int32_t` usado pelos parsers do ESP32: `-2147483648..2147483647`. Overflow ou underflow é rejeitado no HOST antes de `EXEC`, jobs ou fallback legado, em vez de falhar tardiamente no firmware.
- O builder serial low-level `esp32.protocol.command()` aplica o mesmo contrato `int32_t` a `MOVE`, `MOVE_SMOOTH`, `DRAG_REL`, `SCROLL` e `HSCROLL`; assim chamadas diretas de `SerialBridge.send()` também rejeitam overflow, underflow e valores não inteiros antes de escrever na serial.
- O mesmo builder low-level replica os bounds motores do firmware: `MOVE_SMOOTH`/`DRAG_REL` exigem `steps` 1..200 e duração 0..10000 ms, `DRAG_REL` exige botão válido e `DOUBLE_CLICK` aceita apenas botão válido com intervalo opcional 10..1000 ms. Entradas inválidas falham antes da escrita serial.
- O builder serial low-level também valida a gramática estrutural de `EXEC` e `JOB_*`: aridade exata, índice de `JOB_ADD` em 0..31 e payload hex não vazio/par com no máximo 192 bytes codificados, rejeitando framing malformado antes da escrita serial.
- `WAIT` segue o mesmo contrato temporal do firmware, aceitando apenas 0..5000 ms antes de Smart v2 ou fallback legado; valores negativos ou acima do limite são rejeitados em vez de serem silenciosamente clampados pelo fallback.
- Configuração administrativa respeita as capabilities anunciadas: se `WATCHDOG_RELEASE_ALL` ou `KEYBOARD_PACING` não estiver disponível, o HOST retorna `UNSUPPORTED_BY_FIRMWARE` e não envia o comando incompatível. Quando suportado, watchdog não positivo mantém a convenção de desligar (`OFF`); valores positivos devem estar em 250..60000 ms, e pacing deve usar press 1..250 ms e gap 0..250 ms. Valores fora desses limites falham localmente antes do envio.
- Fallback de jobs informa a causa real: firmware/protocolo indisponível preserva o motivo de capability, ausência de `JOB_ATOMIC` retorna `JOB_ATOMIC_UNAVAILABLE`, e somente excesso do limite anunciado retorna `JOB_TOO_LARGE`.

A fronteira de sucesso permanece explícita: `transport_success`/ACK do ESP32 não implica efeito visual, pós-condição nem `goal_success`. A camada de captura HDMI/OCR/visão continua responsável pela verificação semântica no `REMOTE_PC`.

## Inteligência e autonomia

O MCP vem evoluindo de um simples catálogo de comandos para um agente operacional orientado a objetivo.

O ciclo desejado é:

```text
OBSERVAR
  -> INTERPRETAR
  -> RECUPERAR CONTEXTO / MEMÓRIA
  -> GERAR ALTERNATIVAS
  -> RANQUEAR
  -> EXECUTAR
  -> VERIFICAR
  -> APRENDER
  -> REPLANEJAR
```

Componentes de contexto, estratégia, memória, decision engines, agent bus e supervisão podem usar resultados anteriores para melhorar decisões futuras. O sistema deve evitar repetir cegamente uma estratégia que falhou e deve distinguir diferentes níveis de sucesso:

```text
comando enviado
!= transporte confirmado
!= dispositivo executou
!= efeito visual observado
!= pós-condição atingida
!= objetivo concluído
```

Resultados sem progresso semântico são limitados pela mesma assinatura de **ação + argumentos + estado visual**. Para `UNVERIFIED`, a engine permite uma verificação inicial, mas ao atingir o limite configurado (2 por padrão) interrompe `VERIFY -> UNVERIFIED` e retorna `REPLAN`. O mesmo vale para `NO_MATCH`: repetir a mesma busca/observação no mesmo estado sem encontrar evidência não pode gerar indefinidamente `CONTINUE_OR_REFRAME`; ao atingir o limite, a engine retorna `REPLAN` com `get_relevant_action_context`. As métricas permanecem separadas (`equivalent_unverified` e `equivalent_no_match`), e uma mudança real de estado ou outcome quebra a sequência.

A inteligência deve permanecer explicável por dados estruturados de decisão/outcome, sem depender de conteúdo confidencial ou de chain-of-thought privado.

## Tools MCP

O catálogo MCP está em evolução contínua. A direção arquitetural é manter um conjunto **CORE pequeno, claro e fácil de selecionar**, utilizando progressive disclosure para capacidades especializadas quando possível.

Em vez de depender de uma lista estática neste README, consulte o catálogo exposto pela versão em execução. As descrições das tools devem indicar:

- o que a operação faz;
- quando usar e quando não usar;
- target (`MCP_HOST` ou `REMOTE_PC`);
- pré-condições;
- parâmetros e unidades;
- efeitos colaterais e riscos;
- resultado esperado e erros relevantes.

Quando o agente não souber qual tool utilizar, `get_best_tool_for` é o advisor principal de seleção. `get_tool_help` serve para consultar detalhes de uma tool já identificada. Interfaces antigas de busca podem permanecer por compatibilidade, mas não devem necessariamente ser a primeira escolha para roteamento cotidiano.

## Administração do MCP_HOST

O projeto também possui capacidades administrativas para arquivos, diretórios, processos e comandos no computador que hospeda o MCP. Essas operações pertencem ao target `MCP_HOST` e não equivalem a ações HID executadas no `REMOTE_PC`.

Operações destrutivas devem exigir os mecanismos de confirmação definidos pelo servidor. Timeouts, limites de saída e demais guardrails devem ser preservados.

## Segurança e privacidade

Este repositório não deve armazenar artefatos privados produzidos durante uso ou estudo de outros projetos.

Não versione:

- código confidencial de terceiros ou empresas;
- screenshots e capturas do PC remoto;
- áudio de sessões;
- dumps e logs contendo conteúdo privado;
- bancos/índices de estudo;
- observations, knowledge ou solution trees derivados de projetos privados;
- credenciais, tokens, chaves ou secrets;
- dados pessoais;
- estado transitório de runtime/sessões.

O projeto possui testes destinados a impedir que categorias conhecidas de artefatos locais sejam adicionadas novamente ao Git. Sanitização e `.gitignore` são camadas adicionais, não substitutos para revisão de segurança.

## Desenvolvimento e testes

Mudanças devem preferencialmente seguir:

```text
reprodução determinística
  -> menor correção segura
  -> teste de regressão
  -> Fast regression gate
  -> integração
  -> validação pós-merge
```

O **Fast regression gate** valida regressões locais críticas do MCP. Além dele, o **ESP32 compatibility gate** faz checkout da `main` oficial de `gocsilva/ESP32-PC-CONTROLLER` e executa o `SmartHidHost` deste commit contra o dispositivo Smart HID virtual determinístico do firmware. Esse gate cobre negociação de capabilities, perfil remoto `KEYBOARD_MOUSE_HID_ONLY`, idempotência/replay de `EXEC` e jobs, preservação exata de `TYPE_TEXT` e round-trip de configuração/telemetria. O dispositivo virtual representa somente o contrato observável do Smart HID v2; ele não simula comportamento elétrico de USB/BLE nem substitui validação física.

O **Smart HID host regression gate** executa separadamente as regressões do framing/protocolo e do adapter `SmartHidHost`. `tests/test_protocol.py` cobre também o framing `int32_t`, bounds motores e framing estrutural Smart HID `EXEC`/`JOB_*` no builder serial low-level, enquanto as regressões do adapter cobrem negociação/perfil, bounds máximos conhecidos e sanitização de limites ausentes/malformados/nonpositive, preservação/rejeição determinística de IDs idempotentes, gramática e whitespace estrito dos tokens de teclado, framing `int32_t` de movimento/drag/scroll, bounds administrativos de watchdog/pacing, o no-op de `TYPE_TEXT` vazio, o orçamento mínimo de `TYPE_TEXT`, os guards de capability para configuração administrativa, bounds motores/`WAIT`, diagnósticos de fallback de jobs e a validação fail-fast antes de `ser.write()`. Esse gate é obrigatório junto com o Fast regression gate e o ESP32 compatibility gate antes de integrar mudanças na `main`.

Para otimizações de performance, compare a mesma carga antes e depois e mantenha a alteração apenas quando houver benefício mensurável fora do ruído.

Áreas especialmente importantes para regressão:

- concorrência e IPC;
- lifecycle/supervisor;
- OCR, cache e freshness;
- leitura rolável completa;
- coordenadas/calibração do mouse;
- digitação longa e chunking;
- memória/estratégia;
- schemas e seleção de tools MCP;
- segurança de artefatos versionados;
- negociação/fallback, replay integral de jobs e idempotência Smart HID host↔firmware.

Testes automatizados não substituem validação física de HDMI, ESP32, BLE, mouse ou teclado. Quando um comportamento tiver sido validado apenas em software, ele deve ser reportado dessa forma.

## Solução de problemas

- **COM ocupada:** feche outro monitor serial ou uma instância antiga que esteja usando a porta.
- **ESP32 sem resposta:** confirme conexão, modo HID e estado do transporte antes de repetir comandos.
- **Captura vazia/congelada:** confirme a fonte HDMI, dispositivo selecionado e se outro aplicativo está monopolizando a captura.
- **OCR inesperado:** verifique freshness do frame, ROI, confidence e se o estado visual é transitório.
- **Mouse impreciso:** valide topologia, monitor capturado, resolução e calibração antes de aumentar retries.
- **Digitação longa interrompida:** verifique ACKs de chunks, conexão HID e timeouts; o transporte possui orçamento de timeout escalável para textos extensos.
- **Tunnel offline:** diagnostique MCP e túnel separadamente; reiniciar o MCP não deve implicar trocar ou reiniciar desnecessariamente um túnel saudável.

## Direção do projeto

O objetivo de evolução contínua é tornar o MCP PC Controller progressivamente melhor em quatro dimensões combinadas:

1. **Percepção** — enxergar e compreender melhor a tela.
2. **Ação** — operar mouse e teclado com maior precisão e confiabilidade.
3. **Inteligência** — escolher estratégias melhores, aprender com outcomes e replanejar após falhas.
4. **Engenharia** — reduzir complexidade, tools redundantes, latência, races e pontos únicos de falha.

Toda evolução deve preservar segurança, compatibilidade, observabilidade e a fronteira entre `MCP_HOST` e `REMOTE_PC`.