🎮 Cheat Engine MCP Server (Model Context Protocol)

O Cheat Engine MCP Server é uma ponte de integração bidirecional via protocolo Model Context Protocol (MCP) entre assistentes de Inteligência Artificial (como Claude Desktop, Antigravity CLI/IDE, Cursor, VS Code Copilot) e o Cheat Engine.

Ele conta com um sistema de inicialização automática em PowerShell e Batch que localiza o Cheat Engine no Windows, acopla a ponte Lua no autorun e injeta as configurações do cliente de IA escolhido.

📐 Arquitetura do Projeto

flowchart TD
    Launcher["Launcher Automático<br/>start_mcp_ce.bat / scripts/launcher.ps1"] -->|Acopla Autorun Lua & Configura MCP| AI[Assistente de IA<br/>Claude / Antigravity / Cursor / VS Code]
    AI <-->|MCP Stdio Protocol| PyServer[Servidor Python MCP<br/>src/mcp_cheatengine/server.py]
    PyServer <-->|"TCP Socket / JSON-RPC 2.0<br/>127.0.0.1:52737"| CE[Cheat Engine Lua Engine<br/>lua/ce_mcp_lua.lua]
    CE <-->|Windows API / OpenProcess| Target[Processo Alvo / Jogo]

Para mais detalhes sobre o modelo de execução assíncrona non-blocking e protocolo de comunicação, veja a Documentação de Arquitetura.

Related MCP server: frida-mcp

⚡ Funcionalidades Principais (25 Ferramentas MCP)

• Inicialização & Pré-configuração Automática: Script PowerShell (scripts/launcher.ps1) e Batch (start_mcp_ce.bat) para localização automática do Cheat Engine no registro do Windows, acoplamento da ponte Lua no autorun e injeção do JSON do cliente de IA.

• Gerenciamento de Processos: Listagem, anexo por PID/Nome e encerramento remoto do Cheat Engine (ce_close_cheat_engine).

• Manipulação de Memória: Leitura, escrita, alocação segura (allocateMemory com limite de 10MB) e desalocação de regiões de memória.

• Speedhack & Controle: Ajuste fino do multiplicador de velocidade de processos (0.0x a 500.0x).

• Address List / Cheat Table: Leitura, adição de entradas e congelamento (Active = true/false) de registros na tabela do Cheat Engine.

• Dumps de Memória Seguros: Exportação e restauração de snapshots de memória com Path Sandboxing estrito (pasta dumps\ isolada e extensões .dmp/.bin).

• Resolução de Ponteiros: Navegação automática em cadeias de ponteiros multinível com offsets.

• Array of Bytes (AOB Scan): Busca por assinaturas de bytes em memória com wildcards (48 8B 05 ?? ?? ?? ??).

• Resolução de Símbolos & Módulos: Mapeamento de DLLs, executáveis e expressões relativas (module.dll+0x1234).

• Desensamblador x86/x64: Conversão de código de máquina para assembly em tempo real.

• Auto Assemble Scripting: Execução de scripts Auto Assemble para hooks e code caves.

• Execução Arbitrária de Lua: Automação avançada enviando scripts Lua diretamente para o interpretador do Cheat Engine.

• Breakpoints de Hardware: Configuração de breakpoints para inspeção de execução/leitura/escrita.

📁 Estrutura do Repositório

mcp-cheatengine/
├── .gitignore                      # Configuração completa do GitIgnore (Python, Lua, PowerShell, BAT)
├── LICENSE                         # Licença GNU General Public License v3.0
├── README.md                       # Documentação principal
├── DOCUMENTACAO_CHEAT_ENGINE_MCP.md # Índice central da documentação reestruturada
├── requirements.txt                # Dependências Python (mcp)
├── pyproject.toml                  # Configuração de empacotamento Python
├── start_mcp_ce.bat                # Script de execução rápida para Windows (Batch com elevação UAC)
├── ce_mcp_server.py                # Wrapper de compatibilidade raiz (Python)
├── ce_mcp_lua.lua                  # Wrapper de compatibilidade Lua raiz
├── config/
│   ├── mcp_config.json             # Exemplo de configuração genérica MCP
│   └── claude_desktop_config.json # Exemplo para Claude Desktop
├── docs/                           # Central de Documentação Completa
│   ├── ARCHITECTURE.md             # Especificação técnica e fluxo do sistema
│   ├── QUICKSTART.md               # Guia passo a passo de instalação
│   ├── API_REFERENCE.md            # Referência detalhada das 25 ferramentas MCP
│   ├── EXAMPLES.md                 # Exemplos reais de prompts e casos de uso
│   └── TROUBLESHOOTING.md          # Guia de solução de problemas e erros
├── lua/
│   ├── ce_mcp_lua.lua              # Servidor TCP Lua (para rodar no Cheat Engine)
│   └── autorun/
│       └── ce_mcp_autorun.lua      # Script de carregamento automático (Autorun)
├── scripts/
│   └── launcher.ps1                # Script PowerShell de busca no registro, acoplamento e injeção MCP
└── src/
    └── mcp_cheatengine/            # Pacote Python modularizado
        ├── __init__.py
        ├── __main__.py             # Entrypoint da aplicação
        ├── config.py               # Variáveis de ambiente e portas
        ├── rpc_client.py           # Cliente JSON-RPC via TCP Socket
        ├── server.py               # Servidor FastMCP
        └── tools/                  # Ferramentas categorizadas por domínio
            ├── __init__.py
            ├── process.py          # Gerenciamento de processos
            ├── memory.py           # Leitura e escrita de memória
            ├── scanner.py          # AOB Scan, símbolos e módulos
            ├── assembly.py         # Desensamblagem e Auto Assemble
            ├── lua.py              # Execução de código Lua
            ├── debugger.py         # Breakpoints de hardware/software
            ├── control.py          # Pausa, alocação, speedhack e dumps
            └── table.py            # Gerenciamento da Address List

🚀 Guia Rápido de Instalação e Uso

Método 1: Automático (1-Clique via Batch / PowerShell)

Dê um duplo clique no arquivo start_mcp_ce.bat na raiz do projeto (ou execute no terminal .\start_mcp_ce.bat).

O script irá automaticamente:

1. Localizar o Cheat Engine instalado no seu sistema via Registro do Windows.

2. Copiar a ponte Lua para a pasta autorun do Cheat Engine.

3. Injetar a pré-configuração MCP nos assistentes de IA (Claude Desktop, Antigravity, Cursor, VS Code).

4. Inicializar o Cheat Engine com o MCP ativo na porta 127.0.0.1:52737.

Método 2: Manual

Consulte o Guia de Quickstart para executar passo a passo via terminal.

🛠️ Resumo das Ferramentas MCP Expostas

Consulte a Referência Completa da API para tipos de parâmetros e retornos.

🔒 Auditoria de Segurança

Todas as 25 ferramentas e scripts de automação passaram por auditoria estrita de segurança via agente subespecializado (security_validator):

• Transporte Restrito: Socket TCP escuta exclusivamente em 127.0.0.1 (Loopback).

• Sandboxing de Arquivos: Leitura/escrita de dumps restringida à pasta dumps\, com bloqueio de Path Traversal (..) e sanitização de extensões (.dmp, .bin).

• Proteção contra DoS: Limites rígidos de alocação de memória (10MB) e dumps (50MB).

📄 Licença

Este projeto está licenciado sob a licença GNU General Public License v3.0 (GPLv3).