bgmatch-mcp

Servidor MCP do BGMatch, o sistema em que o grupo registra as partidas de boardgame e acompanha o ranking do ano. Com ele, um assistente como o Claude consulta partidas, jogos e ranking e registra partidas novas a partir de uma conversa ("registra um Wingspan com a Europa ontem na Ludoteca: Gedvan ganhou, Rodrigo e Bruno empataram em segundo").

O servidor não acessa o banco. Ele chama a API REST do BGMatch com uma conta de serviço, então valem as mesmas validações do site.

Como usar

Peça um token ao Rodrigo. Cada pessoa tem o seu, e toda alteração feita pelo MCP fica registrada no log com o nome de quem a fez.

No Claude Code:

claude mcp add --transport http --scope user bgmatch https://bgmatch.vps.rodrigor.com/mcp --header "Authorization: Bearer SEU_TOKEN"

No Claude Desktop, o servidor entra pelo mcp-remote, no claude_desktop_config.json:

{
  "mcpServers": {
    "bgmatch": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://bgmatch.vps.rodrigor.com/mcp", "--header", "Authorization: Bearer SEU_TOKEN"]
    }
  }
}

Outros clientes funcionam se aceitarem MCP por HTTP (Streamable HTTP) com o cabeçalho Authorization.

Related MCP server: mcp-homeassistant

Ferramentas

Jogos e jogadores são informados pelo nome, sem diferenciar acentos e maiúsculas, ou pelo id. Se o nome bater com mais de um registro, a ferramenta devolve as opções em vez de escolher.

As ferramentas que alteram ou apagam dados vêm marcadas como destrutivas, e os clientes MCP costumam pedir confirmação antes de executá-las.

Duas limitações de hoje:

• ranking depende do endpoint GET /api/ranking/{ano} com o cálculo no backend, que ainda não está publicado no BGMatch em produção. Até lá, a ferramenta responde avisando disso.

• A Ludopedia tem recusado as requisições do servidor com HTTP 403, então pesquisar_ludopedia e importar_jogo falham também pelo site. Jogo novo entra por buscar_jogo_bgg e cadastrar_jogo_bgg, que dependem do endpoint POST /api/jogos/novo do BGMatch.

A categoria sugerida segue a faixa de peso do cadastro do grupo: peso 2,7 ou mais é pesado, de 1,9 a 2,7 é médio e abaixo disso é leve. Party e infantil no BGG viram party/infantil, e expansão vira expansão.

Administração

Variáveis de ambiente

Veja .env.example.

Dar acesso a alguém

npm run token -- nome

O comando imprime nome:token. Acrescente essa linha em BGMATCH_MCP_TOKENS, reinicie o container e mande o token para a pessoa por um canal privado. Para revogar, tire a entrada e reinicie.

Deploy

docker compose up -d --build

O compose.yaml publica a porta só em 127.0.0.1. O acesso externo passa pelo proxy com TLS, que encaminha /mcp para o container. As alterações ficam no log do container, uma linha JSON por ação:

docker logs bgmatch-mcp | grep '"acao"'

Depois de 20 tentativas com token inválido em 10 minutos, o IP recebe HTTP 429 até a janela passar.

Desenvolvimento

npm install
npm test
BGMATCH_API_URL=http://localhost:8000/api BGMATCH_USUARIO=mcp BGMATCH_SENHA=... BGMATCH_MCP_TOKENS=eu:$(openssl rand -hex 24) npm run dev

Para conferir um servidor no ar, o scripts/fumaca.mjs lista as ferramentas e chama as de leitura:

BGMATCH_MCP_URL=https://bgmatch.vps.rodrigor.com/mcp BGMATCH_MCP_TOKEN=SEU_TOKEN node scripts/fumaca.mjs

Licença

MIT