# 🚀 FXServer MCP Server (`fxserver-mcp`)
### Servidor MCP de Alta Performance e Segurança para **FiveM** (GTA V) e **RedM** (RDR 3)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-FXServer%20(CitizenFX)-orange.svg)]()
[![Game](https://img.shields.io/badge/Games-FiveM%20%7C%20RedM-green.svg)]()
[![Protocol](https://img.shields.io/badge/Protocol-Model%20Context%20Protocol%20(MCP)-purple.svg)]()

O **FXServer MCP** é um servidor compatível com a especificação **Model Context Protocol (MCP)**, projetado especificamente para conectar assistentes de IA (como **Antigravity IDE**, **Claude Desktop**, **Cursor** e **VS Code**) ao ciclo de vida completo de desenvolvimento e administração de servidores FiveM e RedM.

---

## 📌 Principais Recursos

- ⚡ **Detecção Inteligente de Jogo**: Identifica automaticamente se o ambiente é **FiveM** (`gta5`) ou **RedM** (`rdr3`) analisando convar de build e estrutura do servidor.
- 🛡️ **Segurança Industrial para Produção**:
  - **Sandbox Path Traversal Guard**: Nenhuma operação sai do diretório raiz do servidor.
  - **Pastas Críticas Bloqueadas**: Bloqueio estrito contra alteração ou exclusão de `txData`, `cache`, `databases`, `artifacts`.
  - **Backup Hierárquico Anti-Colisão**: Cria snapshots espelhando a árvore de diretórios antes de qualquer alteração (`.mcp_backups/`), evitando conflitos entre arquivos de mesmo nome (ex: `config.lua`).
- 🎮 **Controle em Tempo Real (Live Server)**:
  - Companion Resource em Lua (`ncode-fx-bridge`) ultra-leve.
  - Ações instantâneas: `restart`, `start`, `stop`, `refresh`, `ensure`.
  - IP Allowlist (`127.0.0.1`), autenticação por Bearer Token (256 bits), proteção contra timing attacks e rate limiting (Fail2Ban).
- 🧩 **Scaffolding e Gestão de Recursos**:
  - Geração automática de manifests modernos (`cerulean`, `lua54 'yes'`).
  - Templates prontos para FiveM e RedM (`minimal`, `standalone`, `nui-lua`).
  - Mapeamento recursivo de recursos e subcategorias (`[scripts]`, `[qb]`, `[cfx-default]`).

---

## 🏗️ Arquitetura do Sistema

```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 + Token)"]
    end

    subgraph Server["FXServer Host (Local)"]
        CFG["server.cfg & resources/"]
        Bridge["Companion Resource (ncode-fx-bridge)"]
        Engine["FXServer Runtime (FiveM / RedM)"]
    end

    AI <-->|JSON-RPC| Core
    Core --> FSSafe --> CFG
    Core --> Scaffold --> CFG
    Core --> BridgeClient
    BridgeClient <-->|Localhost HTTP| Bridge
    Bridge <--> Engine
```

---

## 🧰 Catálogo de Ferramentas (MCP Tools)

| Ferramenta | Descrição |
| :--- | :--- |
| `fx_list_resources` | Lista todos os recursos do servidor, mapeando subpastas `[categoria]` e metadados. |
| `fx_get_resource_info` | Inspeciona manifests, dependências, exports e acusa arquivos ausentes declarados. |
| `fx_create_resource` | Cria novos recursos FiveM ou RedM com templates prontos e opção de `autoEnsure`. |
| `fx_read_file` | Lê com segurança qualquer arquivo dentro do servidor. |
| `fx_write_file` | Grava arquivos gerando automaticamente backup espelhado anti-colisão antes. |
| `fx_delete_file` | Remove arquivos ou pastas de recursos com snapshot de segurança prévio. |
| `fx_search_code` | Busca strings, regex, eventos de rede e exports em todos os scripts do servidor. |
| `fx_manage_server_cfg` | Verifica, adiciona ou remove `ensure [resource]` no `server.cfg`. |
| `fx_server_status` | Consulta status ao vivo (jogadores conectados, game, uptime, contagem de resources). |
| `fx_resource_action` | Dispara ações em tempo real no servidor: `restart`, `start`, `stop`, `refresh`, `ensure`. |
| `fx_list_live_resources` | Lista todos os recursos em memória e seus estados (`started`, `stopped`). |
| `fx_list_backups` | Consulta os snapshots de backups automáticos salvos pelo MCP. |

---

## 🚀 Instalação e Inicialização

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

### 2. Configurar Variáveis de Ambiente
Copie o `.env.example` para `.env`:
```env
# Caminho raiz da base do FXServer
FXSERVER_PATH=C:\NCodeBase

# Jogo alvo: "auto" (detecta automaticamente), "gta5" ou "rdr3"
TARGET_GAME=auto

# Endpoint do bridge companion resource
BRIDGE_URL=http://127.0.0.1:30120/ncode-fx-bridge

# Token secreto de 256 bits gerado
BRIDGE_TOKEN=seu_token_secreto_aqui
```

### 3. Instalar o Companion Resource no Servidor
Copie a pasta `companion-resource/ncode-fx-bridge` para a pasta `resources/` do seu FXServer e adicione ao seu `server.cfg`:
```cfg
# FXServer MCP Companion Bridge
set mcp_token "seu_token_secreto_aqui"
ensure ncode-fx-bridge
```

Se o servidor já estiver em execução:
```cmd
refresh
start ncode-fx-bridge
```

---

## 🧪 Testando a Conexão

Execute o teste de comunicação em tempo real com o servidor:
```bash
npm run test:live
```

Saída esperada:
```text
--- TESTANDO CONEXÃO LIVE COM O FXSERVER ---
✅ SUCESSO! Conexão estabelecida com o FXServer.
Status do Servidor:
 - Servidor: Orion DEV
 - Jogo: GTA5
 - Jogadores Online: 0
 - Resources em Memória: 120
✅ O FXServer MCP está 100% operacional em tempo real!
```

---

## 🔌 Configuração no Antigravity / Claude Desktop

### Antigravity IDE (Workspace)
No arquivo `.agents/mcp_config.json`:
```json
{
  "mcpServers": {
    "fxserver": {
      "command": "node",
      "args": ["c:/Users/naayu/Desktop/NCodeFivemMCP/dist/index.js"],
      "env": {
        "FXSERVER_PATH": "C:\\NCodeBase",
        "BRIDGE_TOKEN": "seu_token_secreto_aqui"
      }
    }
  }
}
```

### Claude Desktop
No seu `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "fxserver": {
      "command": "node",
      "args": ["C:/caminho/para/fxserver-mcp/dist/index.js"]
    }
  }
}
```

---

## 🛡️ Segurança e Boas Práticas

- **Token Secreto**: Nunca compartilhe ou versione o arquivo `.env`.
- **IP Allowlist**: O bridge aceita conexões unicamente originadas de `127.0.0.1` e `::1`.
- **Prevenção de Ataques**: O script Lua compara tokens usando verificação em tempo constante (`safe_equals`) e ativa bloqueio temporário (Fail2Ban) após tentativas inválidas repetidas.
- **Rollback Imediato**: Todos os arquivos alterados pelo MCP geram snapshots preservados em `.mcp_backups/`.

---

## 📄 Licença

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