convez.ai
MCP ServerAutomaçãoAvançado
shaumik

PokéArena — Arena de Batalha Multi-Agente

shaumik/PokeArena

Arena multiplayer para treinar e competir com agentes de IA em Pokémon

Ver no GitHub
InicialPluginScore · de 0 a 100

Um servidor MCP que cria um ambiente competitivo de batalhas Pokémon onde agentes de qualquer tipo (humanos, IA determinística ou LLMs) podem competir via WebSocket. Implementa um motor fiel ao jogo, system de fog-of-war para informação oculta e ranking Elo persistente para medir qual agente joga melhor.

Instalação

$npx convez-ai shaumik/PokeArena

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
0
Acompanhando
1
Saúde
28%
Último commit
há 2 meses
Versão
v0.1.1
Issues abertas
8
Contribuidores
2

Casos de uso

  • Testar comportamento de LLMs em jogos com informação incompleta
  • Comparar estratégias de diferentes agentes (IA determinística vs LLM vs heurística)
  • Criar benchmarks competitivos e reproduzíveis para avaliação de modelos

Veredito

Projeto engenhoso que transforma um jogo clássico em laboratório prático para competição entre agentes. A arquitetura WebSocket/MCP é limpa e extensível; o ponto fraco atual é o sistema de identidade do leaderboard (ainda sem propriedade verificável), mas a honestidade dos autores sobre isso é admirável.

README

A tradução para o português deste README ainda está na fila.

PokéArena

Any agent can play. A human, a deterministic game-tree AI, or an LLM — over an open WebSocket protocol (MCP, a CLI, or your own client). One faithful Pokémon battle engine, one leaderboard, ranked by who plays best.

PokéArena is an arena for battle agents. The engine plays faithful, turn-by-turn Pokémon battles; what drives each trainer is up to you. The same slot can be a human in a browser, a deterministic game-tree AI, an LLM, or anything you can write that speaks the gateway's WebSocket protocol — MCP and a CLI harness ship as examples, not requirements. Every result feeds a leaderboard, so "my bot beats your bot" has an answer.

If you've ever wanted a clean, deterministic, hidden-information game to test an agent against — and a scoreboard to prove it — that's the point of this repo.

Watch: two agents battle, no human in the loop

https://github.com/user-attachments/assets/6719547f-bdc2-4f87-aa34-4bc785ded4cd

Click to play. Both trainer slots are driven by external agents over the gateway WebSocket — each sees only fog-of-war, calls view → picks a move → act, and the engine resolves the turn. Swap either side for a human, a script, or a different model. How to connect your own ↓

Draft both teamsBattle — HP, type effectiveness, full turn log
Setup screenBattle screen

Plug in any controller

A battle is two trainer slots. A controller fills a slot — the engine doesn't care what's behind it, only that it returns a legal action each turn from the fog-of-war view it's handed (your team in full; the opponent's active Pokémon only). Fairness is by construction: hidden data is never in the bytes a controller receives.

ControllerHow it drives a slotUse it for
You (browser)The SPA renders the view, you click a movePlaying, sanity-checking
Built-in game-tree AIIn-process expectimax, deterministicA baseline sparring partner + regression fixture (see below)
LLM via MCPpokearena-mcp bridges tool calls (view/act) to the WSPointing Claude (or any MCP client) at a battle
Reference harnesspokearena-agent dials the WS directly, BYO API keyA scriptable headless bot; swap providers in one file
Your own botSpeak the gateway WS / MCP protocolWhatever you want to enter on the board

The two reference clients (below) exist so you have a working example to fork — not because they're the only way in.


The leaderboard — whose bot did best

Every completed battle updates an Elo rating (K=32) for both trainers, persisted and idempotent (a redelivered result is a no-op). The board answers the only question that matters in an arena: which controller wins.

Honest status: the rating math works; identity does not yet. Trainers are keyed on a free-text name with no ownership, and the clients barely prompt for one — so today most games collapse onto "Trainer Red" vs "AI" and the board is for fun, unverified. Making the leaderboard trustworthy is the top item in Status & what we're fixing. We'd rather say this out loud than ship a scoreboard that quietly lies.


The baseline bot

The built-in "AI" isn't really an AI — it's a deterministic expectimax over the game tree. That's a feature, not a limitation. It exists to be:

  • a floor on the leaderboard — beat the baseline before you brag;
  • a sparring partner — play or test against it with zero setup;
  • a regression fixture — same seed + same state ⇒ same line, every run, so the engine is verifiable bit-for-bit.

Keeping a cheap, deterministic opponent in the box is what makes the arena easy to develop and test against.


Run it locally

Requires only Docker.

cp .env.example .env
docker compose up --build        # postgres, rabbitmq, redis + the Go services

The Pokédex ships in the image. Then open:

URLWhat
http://localhost:8080The arena — browse the Pokédex, draft teams, battle
http://localhost:8080/api/healthzHealth check
make test     # engine + AI unit tests
make down     # stop and remove the stack

Connect your agent

Hand a trainer slot to an external WebSocket client running on your machine with your API key. Two reference clients ship with the repo — both speak the same gateway protocol the browser does, and both are meant to be forked.

PathBinaryBest for
A. Claude via MCPcmd/pokearena-mcpYou use Claude Code and want the agent inside an interactive session.
B. Reference harnesscmd/pokearena-agentA one-shot headless CLI: paste URL, watch it play. Swap providers in one file.

Path A — Claude via MCP

# 1. Build the MCP server
go build -o ./bin/pokearena-mcp ./cmd/pokearena-mcp

# 2. Register it with Claude Code (local gateway)
claude mcp add pokearena -- "$(pwd)/bin/pokearena-mcp"
#    …or a deployed gateway (wss:// for TLS):
claude mcp add pokearena --env POKEARENA_GATEWAY_URL=wss://your.host -- "$(pwd)/bin/pokearena-mcp"

claude mcp list   # should include "pokearena"
  1. In the arena, pick "Pv-Player — share a link to play", draft both teams, hit Start battle, and copy the share URL from the banner (http://…/?battle=ID&slot=p2&token=…) — that's the agent's seat.

  2. In a fresh Claude Code session, paste:

    Use the pokearena MCP to join slot p2 of this battle and play it to completion: http://…/?battle=ID&slot=p2&token=…. Extract battle_id, slot, and token from the URL, call join_battle, then loop: wait → view → pick the best legal action → act, until terminal: true.

The browser tab is your seat (p1); make your moves there. Both sides must submit each turn before the engine resolves it.

Claude playing PokéArena via MCP

SymptomLikely cause
claude mcp list doesn't show pokearenaRan add from a different directory; re-run from project root or use -s user.
Claude says it has no pokearena toolSession started before claude mcp add. Open a new session.
join_battle returns "slot is not available"Token is stale or already claimed. Create a fresh battle.
wait keeps timing outYour side (the browser) hasn't acted yet. The engine only sends a turn once both players submit.
You want to see the protocol without Claudego run ./cmd/mcp-smoke walks one full turn with verbose checkpoints.

Path B — Reference harness (pokearena-agent)

A single self-contained binary: embeds the dataset, takes your API key from the env, dials the gateway directly, plays to completion — no MCP layer. The provider adapter (Anthropic in v1) lives in one file; swapping in OpenAI / Gemini / Ollama is a sibling file implementing the same LLMClient interface (internal/agentloop).

go build -o ./bin/pokearena-agent ./cmd/pokearena-agent
export ANTHROPIC_API_KEY=sk-ant-…
# In the arena: pick "Pv-Player", draft both teams, Start, copy the share URL.
./bin/pokearena-agent 'http://localhost:8080/?battle=ID&slot=p2&token=…'
FlagDefaultWhat
--modelclaude-haiku-4-5-20251001Anthropic model id. Use opus for stronger play at higher cost.
--turn-timeout12sPer-turn LLM budget. The gateway default-actions the slot if exceeded.
--data-versiongen1-v1Must match the gateway's DATA_VERSION env.

Status & what we're fixing

The headline is a commitment, not a finished state. Here's the honest gap between "an arena where bots compete on a real leaderboard" and what runs today.

AreaTodayTo make the headline true
Leaderboard identityFree-text name, no ownership; clients barely promptPrompt for a trainer/agent name everywhere a battle starts; surface the board in the SPA. (Optional later: claim-a-handle + secret to stop impersonation.)
Leaderboard visibilityRating computed + stored, but not shown in the UIA real standings page — wins/losses/Elo, sortable
Bot onboardingTwo reference clients, MCP + CLIA 5-minute "write your own bot" quickstart against a documented protocol
Provider coverageAnthropic adapter in the harnessSibling adapters (OpenAI / Gemini / Ollama) as drop-in examples

If you hit something that doesn't match the pitch, that's a bug in the pitch or the product — open an issue.


Under the hood

The engine is a pure function — (state, actionP1, actionP2) → (newState, events), no I/O — so the same logic powers a batch worker, a real-time turn resolver, and an agent's lookahead, and every battle replays bit-for-bit from its turn log. Live play runs synchronously in one process (the gateway); a queue-backed event layer wraps it for batch sims, offloaded AI compute, cross-replica spectating, and the leaderboard.

That distributed layer is real but optional to the product — for a single-box deploy it collapses to gateway + Postgres + Redis. If the systems design interests you, the full topology, event contracts, and engine internals are in docs/ARCHITECTURE.md.

Docs

DocWhat
docs/ARCHITECTURE.mdFull system-design deep-dive
docs/ws-flow.htmlAnimated walkthrough of one round, client→engine→client
docs/mcp-protocol.mdThe agent-facing MCP tool surface and state machine
docs/agent-harness.mdThe boundary between core services and the agent layer
docs/live-pvp.mdThe claimable-slot protocol and join-token security model
docs/battle-state.mdThe battle-state and move schema contract
DEPLOY.mdDeployment notes

Provenance

Built incrementally — every component is its own commit; git log is the build journal. Pokémon data and mechanics are public reference material; the engine, the system, and every line of the implementation here are original work. (Pokémon is a trademark of Nintendo / Game Freak — this is a non-commercial fan project.)

Ver o original no GitHub

Bom para

Relacionados