# FXServer MCP Server (`fxserver-mcp`)

Servidor Model Context Protocol (MCP) para automação e integração de FXServer (FiveM e RedM) com assistentes de IA (Antigravity IDE, Claude Desktop, Cursor e VS Code).

## Recursos

- **Detecção de Jogo**: Identifica o ambiente (`gta5` ou `rdr3`) por convars e estrutura de arquivos.
- **Isolamento de Caminhos (Sandbox)**:
  - Validação estrita contra path traversal (`..`, symlinks e caminhos canônicos).
  - Bloqueio de arquivos e diretórios protegidos (`txData`, `.env`, `.git`, `.mcp_backups`).
  - Restrição de escrita para fora da pasta de recursos (arquivos de configuração de raiz como `server.cfg` são estritamente somente-leitura pelo MCP).
  - Backups automáticos hierárquicos antes de edições ou exclusões (`.mcp_backups/`).
- **Integração em Tempo Real**:
  - Companion resource em Lua (`ncode-fx-bridge`) na porta interna do FXServer.
  - Ações de ciclo de vida de recursos (`restart`, `start`, `stop`, `refresh`, `ensure`).
  - Execução dinâmica de código Lua (Live REPL) com isolamento de erros (`xpcall`), suporte assíncrono e captura de retorno no servidor e no cliente.
  - Consulta de logs do console do servidor e do cliente (F8).
  - Captura de tela in-game para validação visual de interfaces e posicionamento.
- **Scaffolding e Inspeção de Recursos**:
  - Geração de recursos compatíveis com FiveM e RedM (`minimal`, `standalone`, `nui-lua`).
  - Leitura e validação de `fxmanifest.lua` com detecção de scripts ausentes e dependências.

## Arquitetura

```mermaid
flowchart LR
    subgraph Client["Cliente MCP"]
        AI["Assistente IA (Antigravity / Claude)"]
    end

    subgraph MCPServer["FXServer MCP (Node.js / TypeScript)"]
        Core["MCP Engine (stdio)"]
        FSSafe["File Sandbox & Backups"]
        Scaffold["Scaffold Engine"]
        BridgeClient["Bridge Client (HTTP + Bearer Token)"]
    end

    subgraph Server["FXServer Host (Localhost)"]
        FS["resources/ & data/"]
        Bridge["Companion Resource (ncode-fx-bridge)"]
        Engine["FXServer Runtime (FiveM / RedM)"]
    end

    AI <-->|JSON-RPC via stdio| Core
    Core --> FSSafe --> FS
    Core --> Scaffold --> FS
    Core --> BridgeClient
    BridgeClient <-->|HTTP Local| Bridge
    Bridge <--> Engine
```

## Catálogo de Ferramentas (MCP Tools)

| Ferramenta | Descrição |
| :--- | :--- |
| `fx_list_resources` | Lista recursos existentes no servidor agrupados por categorias. |
| `fx_get_resource_info` | Detalhes do `fxmanifest.lua`, scripts declarados, arquivos ausentes e dependências. |
| `fx_create_resource` | Cria novos recursos a partir de templates (`minimal`, `standalone`, `nui-lua`). |
| `fx_read_file` | Lê conteúdo textual de arquivos dentro do `serverRoot`. |
| `fx_write_file` | Grava arquivos com backup prévio automático no diretório de snapshots. |
| `fx_delete_file` | Remove arquivos ou pastas de recursos com backup prévio da árvore. |
| `fx_search_code` | Busca strings ou regex nos recursos do servidor. |
| `fx_server_status` | Consulta estado do FXServer e do companion bridge em tempo real. |
| `fx_resource_action` | Executa ações de ciclo de vida (`restart`, `start`, `stop`, `refresh`, `ensure`). |
| `fx_list_live_resources` | Lista recursos ativos em memória e seus estados (`started`, `stopped`). |
| `fx_list_backups` | Consulta histórico de backups automáticos gerados pelo MCP. |
| `fx_execute_code` | Executa código Lua dinâmico no servidor ou no cliente via companion bridge. |
| `fx_get_players` | Lista jogadores online, coordenadas 3D, heading e ping. |
| `fx_search_models` | Consulta catálogo de modelos 3D do GTA V por categoria ou palavra-chave. |
| `fx_get_console_logs` | Lê as linhas recentes do console do servidor FXServer / txAdmin. |
| `fx_get_client_console` | Lê logs do console do cliente (F8 / CitizenFX.log) para diagnóstico de erros de script. |
| `fx_capture_screenshot` | Captura a tela do FiveM/RedM em modo híbrido (janela do Windows com UI/NUI completa ou render 3D via bridge). |
| `fx_search_natives` | Pesquisa na documentação oficial de nativas do FiveM. |
| `fx_get_native_details` | Retorna assinaturas Lua/JS, parâmetros e escopo de uma nativa. |
| `fx_check_native_environment` | Valida compatibilidade de nativas entre ambientes (client, server ou shared). |
| `fx_list_native_namespaces` | Lista os namespaces oficiais de nativas do FiveM. |

## Instalação

### 1. Dependências e Build
```bash
git clone https://github.com/NCode/fxserver-mcp.git
cd fxserver-mcp
npm install
npm run build
```

### 2. Configuração de Ambiente
Copie `.env.example` para `.env` e configure os caminhos:
```env
FXSERVER_PATH=C:\NCodeBase\base
TARGET_GAME=auto
BRIDGE_URL=http://127.0.0.1:30120/ncode-fx-bridge
BRIDGE_TOKEN=seu_token_secreto_aqui
```

### 3. Instalação do Companion Resource
1. Copie a pasta `companion-resource/ncode-fx-bridge` para a pasta `resources/` do seu servidor.
2. Adicione ao seu `server.cfg`:
```cfg
set mcp_token "seu_token_secreto_aqui"
ensure ncode-fx-bridge
```

## Configuração do Cliente MCP

### Antigravity IDE
Em `.agents/mcp_config.json`:
```json
{
  "mcpServers": {
    "fxserver": {
      "command": "node",
      "args": ["c:/NCodeFivemMCP/dist/index.js"],
      "env": {
        "FXSERVER_PATH": "C:\\NCodeBase\\base",
        "BRIDGE_TOKEN": "seu_token_secreto_aqui"
      }
    }
  }
}
```

### Claude Desktop
No arquivo `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "fxserver": {
      "command": "node",
      "args": ["c:/NCodeFivemMCP/dist/index.js"]
    }
  }
}
```

## Segurança

- **Autenticação**: O companion bridge exige token no cabeçalho `Authorization: Bearer <token>`.
- **Restrição de Rede**: O companion bridge responde apenas a requisições originadas de `127.0.0.1` ou `::1`, usando o socket real (`req.address`).
- **Prevenção de Abuso**: Comparação de tokens em tempo constante (`safe_equals`) e rate limit com bloqueio temporário contra força bruta.
- **Modificações Protegidas**: O MCP não permite edição do arquivo `server.cfg` e não grava fora da pasta de recursos. Alterações geram cópia espelhada em `.mcp_backups/`.

## Licença

Distribuído sob a licença MIT. Consulte [LICENSE](LICENSE) para mais informações.