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:

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.

Related MCP server: openowl

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:

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:

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 é:

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:

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:

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.