Skip to main content
Glama
README.md
# yafmcp

Servidor **MCP** para operar um servidor **FiveM**: o agente manda um comando, o comando
entra no console do FXServer e a saída do console volta como resposta.

Funciona com qualquer cliente MCP — Claude Code, Hermes, Codex, OpenCode, ou o que vier
depois — porque é MCP por stdio puro (e HTTP streamable quando você quiser).

## Como ele fala com o servidor

Pelo **live console do txAdmin** (v7/v8): login por senha em `/auth/password`, sessão
guardada em cookie, e o comando vai pelo socket.io na sala `liveconsole`, exatamente
como a aba Live Console do painel faz. A saída é capturada do stream `consoleData`,
limpa de ANSI e devolvida.

Não precisa de `rcon_password`, não precisa reiniciar o servidor, não precisa de acesso
ao container.

> O socket.io do txAdmin só responde por **long-polling**: o servidor HTTP que escuta na
> porta do painel roteia `/socket.io` para `engine.handleRequest`, e não trata upgrade de
> websocket. O cliente aqui já vem fixado em `polling` por causa disso.

## Instalação

Pelo npm, sem clonar nada:

```bash
npx -y yafmcp --setup     # grava as credenciais do txAdmin
npx -y yafmcp --doctor    # confere a conexão
```

Ou do repositório, para mexer no código:

```bash
git clone https://github.com/ggfto/yafmcp.git
cd yafmcp
pnpm install
pnpm run setup     # pergunta URL do txAdmin, usuário e senha; grava 600 em ~/.config/yafmcp/config.json
pnpm run doctor    # loga, conecta no console e roda um "version"
```

Requer Node 18+ (testado no 22) e um admin do txAdmin com permissão de console
(`console.view` + `console.write`; o master já tem).

### Configuração

`~/.config/yafmcp/config.json` (ou variáveis de ambiente, que têm precedência):

| Campo | Env | Padrão |
| --- | --- | --- |
| `txadminUrl` | `FIVEM_TXADMIN_URL` | `http://127.0.0.1:40120` |
| `serverUrl` | `FIVEM_SERVER_URL` | `http://127.0.0.1:30120` |
| `username` | `FIVEM_TXADMIN_USER` | — |
| `password` | `FIVEM_TXADMIN_PASS` | — |
| `quietMs` | `FIVEM_QUIET_MS` | `900` — silêncio no console que fecha a captura |
| `timeoutMs` | `FIVEM_TIMEOUT_MS` | `10000` — teto da captura |
| `scrollback` | — | `2000` linhas guardadas em memória |
| `logsDir` | `FIVEM_LOGS_DIR` | vazio — acha `txData/<perfil>/logs` pelo FXServer rodando na mesma máquina |

## Registrando nos agentes

```bash
node src/register.js          # registra em todos os clientes presentes na máquina
node src/register.js --print  # só imprime os trechos, você cola onde quiser
```

Ou na mão:

Em todos os exemplos abaixo, `npx -y yafmcp` e `node /caminho/yafmcp/src/index.js`
são intercambiáveis — o primeiro dispensa clone, o segundo usa a sua cópia local.

```bash
# Claude Code
claude mcp add --scope user fivem -- npx -y yafmcp
```

```toml
# Codex — ~/.codex/config.toml
[mcp_servers.fivem]
command = "node"
args = ["/caminho/yafmcp/src/index.js"]
```

```json
// OpenCode — ~/.config/opencode/opencode.json
{ "mcp": { "fivem": { "type": "local", "command": ["node", "/caminho/yafmcp/src/index.js"], "enabled": true } } }
```

```yaml
# Hermes — ~/.hermes/config.yaml
mcp_servers:
  fivem:
    command: node
    args:
      - /caminho/yafmcp/src/index.js
    enabled: true
```

## Ferramentas

| Ferramenta | O que faz |
| --- | --- |
| `fivem_command` | Executa qualquer comando no console e devolve a saída. Para resource, `ensure <resource>` é o padrão (inicia ou reinicia); `refresh` antes se o resource é novo no disco. `timeoutMs`, `quietMs` e `timestamps` são opcionais. |
| `fivem_console` | Últimas linhas do console capturadas pela sessão, com `filter` por regex. |
| `fivem_logs` | Arquivos de log do txAdmin: `fxserver.log` (dia inteiro, boots anteriores), dias rotacionados e `admin.log`. `sinceBoot` corta no último start, `filter` por regex, `list` mostra os arquivos. Só lê arquivo de dentro da pasta de logs. |
| `fivem_status` | No ar?, hostname, jogadores, game build, nº de resources. |
| `fivem_players` | Jogadores online com id, ping e identificadores. |
| `fivem_server_control` | `start` / `stop` / `restart` do processo do servidor (derruba quem estiver online). |

```
> recarrega o resource mri_Qadmin
  fivem_command("ensure mri_Qadmin")
  $ ensure mri_Qadmin
  [           resources] Stopping resource mri_Qadmin
  [    c-scripting-core] Creating script environments for mri_Qadmin
  [           resources] Started resource mri_Qadmin
```

## Outros modos

```bash
node src/index.js                   # MCP stdio (o normal)
node src/index.js --http --port 8765  # MCP streamable HTTP em /mcp, para clientes que falam por URL
node src/index.js --exec "refresh"  # um comando direto pelo terminal, sem agente no meio
node src/index.js --logs "error"    # fxserver.log desde o último boot, filtrado
node src/index.js --doctor          # diagnóstico da conexão
```

## Agente dedicado no Clink (opcional)

Quem usa o [Clink](https://github.com/ggfto/clink) pode criar um tipo de agente
**FiveM Ops** — mission + rule sheet — que nasce sabendo operar o servidor:

```bash
node tools/clink-agent.js
clink new "FiveM Ops" "FiveM"
```

`FIVEM_DEFAULT_PATH` escolhe a pasta em que esse agente abre (padrão `~/fx-panel`).

## Segurança

Nenhum comando é bloqueado: quem tem o MCP tem o console do servidor inteiro. A senha
fica só no arquivo de config (modo 600) ou no ambiente — nunca no repositório, nunca no
prompt do agente. Se isso for demais para o seu caso, dê ao MCP um admin do txAdmin com
permissões reduzidas: a checagem de permissão é feita pelo próprio txAdmin.

## Publicando o pacote

Mesmo esquema do `mri-ui-kit`, sem passo manual:

- **Commits no padrão [Conventional Commits](https://www.conventionalcommits.org/)** — é
  deles que sai a versão. `fix:` vira patch, `feat:` vira minor, `feat!:`/`BREAKING CHANGE`
  vira major; `chore:`, `ci:`, `docs:`, `test:` não geram versão.
- **`release.yml`** roda a cada push na `main`: testa e chama o `semantic-release`, que
  bumpa o `package.json`, escreve o `CHANGELOG.md`, commita `chore(release): x.y.z` e cria
  a tag e a release no GitHub. Não publica nada.
- **`publish.yml`** roda logo depois (ou na mão, pela aba Actions) e publica no npmjs.com
  por **trusted publishing (OIDC)**, sem `NPM_TOKEN`. Se a versão do `package.json` já
  está no npm, não faz nada.

Configuração única no npmjs.com: pacote `yafmcp` → Settings → Trusted publisher → GitHub
Actions, repositório `mri-Qbox-Brasil/yafmcp`, workflow `publish.yml`.

`ci.yml` roda os testes em push e PR, no Node 20, 22 e 24.

## Licença

MIT.

TDQS

A3.9/5.0

Scored across 6 tools

Disambiguation4/5

The tools mostly target distinct surfaces: command execution, log files, server lifecycle, live console tail, player list, and status. The main risk is overlap between fivem_command (which already returns console output), fivem_console, and fivem_logs, plus fivem_status duplicating the player count from fivem_players, but descriptions explicitly steer usage (e.g. server_control pointing to 'ensure' via fivem_command, console for output after a long-running command).

Naming Consistency4/5

All names share a consistent fivem_ prefix in snake_case, which makes the set predictable. The only minor deviation is that names are noun/resource-based (fivem_console, fivem_logs, fivem_status) rather than a uniform verb_noun pattern, but they remain readable and grouped coherently.

Tool Count5/5

Six tools is well-scoped for a FiveM/txAdmin server-management server, with each tool covering a clear, non-redundant facet (execute, logs, lifecycle, console, players, status). Nothing feels padded or missing at the count level.

Completeness4/5

The surface covers the core operational lifecycle: status inspection, player listing, command execution (including resource ensure/refresh), console tailing, and full server start/stop/restart. Gaps are minor, such as no direct resource/file or manifest editing and no dedicated player-management action, though these can be worked around via fivem_command.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues