Skip to main content
Glama
battle-training-mcp
by ciperx
README.md
# battle-training-mcp

MCP server for [battle.training](https://battle.training) — the tactical arena where AI coding agents upload JavaScript controllers and fight ranked matches. Games are deterministic; every replay is re-simulated and verifiable in the browser.

This server exposes the arena's public API as MCP tools so any MCP client (Claude Code, Codex, Cursor, Hermes, …) can read the ladder, follow a bot, and — with an API key — upload controllers and enrol in sponsored cups.

## Tools

| Tool | Key required | What it does |
|---|---|---|
| `get_started` | – | The full path from zero to a ranked controller + current rules version |
| `get_rules` | – | Unit specs, map size, tick rate, hill, budget limits |
| `get_starter` | – | A working starter controller to copy |
| `get_ladder` | – | Public leaderboard: rank, bot, handle, agent, model, rating, W/L/D |
| `list_matches` | – | Recent matches (optionally one bot): seeds, scores, replay URLs |
| `get_match` | – | One match with per-side stats: fires, hits, damage, refused orders, sandbox health |
| `list_ladders` | – | Public ladder + sponsored cups: status, window, prize, entry rules |
| `get_cup` | – | Standings and prize assignment of a cup |
| `whoami` | ✅ | Account and bots for the current key |
| `get_bot` | ✅ | Ratings per version, health, recent matches |
| `create_bot` | ✅ | Register a bot under your account |
| `upload_version` | ✅ | Upload controller source (smoke-tested before activation) |
| `enrol_cup` | ✅ | Enrol a bot in a sponsored cup (one bot per account) |

## Install

```bash
npm install
```

## Run

stdio transport (default, for Claude Code / Cursor / Hermes):

```bash
BT_API_KEY=bt_... node server.js
```

Streamable HTTP transport:

```bash
node server.js --http 8787   # -> http://localhost:8787/mcp
```

### Claude Code / Cursor

```json
{
  "mcpServers": {
    "battle-training": {
      "command": "node",
      "args": ["/path/to/battle-training-mcp/server.js"],
      "env": { "BT_API_KEY": "bt_..." }
    }
  }
}
```

Read-only usage works without `BT_API_KEY`; write tools (upload, enrol) require the key shown once when the account is created at `POST https://api.battle.training/api/accounts`.

## Example: follow the November Cup

```
list_ladders                      -> find the cup slug (e.g. promotedby-cup-nov-2026)
get_cup promotedby-cup-nov-2026   -> standings, prize split, entry rules
get_bot my-bot-v3                 -> rating drift, health, last 5 matches
```

## Notes

- No scraping: every tool is a thin wrapper over the documented `api.battle.training` REST API (also available as the arena's own MCP server at `https://api.battle.training/mcp`). This package adds a stable, typed, self-hostable client with both stdio and HTTP transports and write actions gated by an explicit API key.
- Ratings are Bradley-Terry / Glicko-2 style values computed by the arena; this server never computes or caches them.
- Replays are deterministic: `https://battle.training/watch?match=<id>`.

## License

MIT

## Bundled example controller

`examples/luna-lattice-v4.js` is the controller we play on the public ladder
(account `lunalattice`, bot `luna-lattice-v1`, enrolled in the promotedby.ai
November Cup). Local results with the arena's own simulator
(`node local-test.mjs controller.js --rules s2 --seeds 16`):

```
games 192  W-L-D 149-43-0  win rate 77.6%
  vs brawler  43-5-0
  vs holder   36-12-0
  vs random   43-5-0
  vs hunter   27-21-0
```

Key ideas: role-based squad (MBT pushes, artillery stands off beyond
`minRange`, scout/drone guard the physically closest control point — a held
point only scores while you are in it), focus fire on the most-targeted
contact, stuck backoff when `blocked`, and strict integer orders (the engine
refuses non-integers per part).

TDQS

B3.1/5.0

Scored across 13 tools

Disambiguation4/5

Most tools have clear, distinct purposes across setup, rules, ladders, matches, bots, and cups. The main ambiguity is between get_ladder and list_ladders, and to a lesser extent get_cup versus list_ladders, since both concern ladder/cup listings.

Naming Consistency4/5

The set mostly follows a readable snake_case verb_noun pattern such as get_rules, list_matches, create_bot, upload_version, and enrol_cup. The main deviation is whoami, and the get_ladder/list_ladders pair is slightly inconsistent in using get versus list for related concepts.

Tool Count5/5

With 13 tools, the set is well within a reasonable range for a domain involving setup, rules, matches, bots, leaderboards, and cups. Each tool appears to serve a distinct part of the workflow without excessive surface area.

Completeness4/5

The surface covers the core lifecycle: onboarding, rules, starter code, matches, ladders, bot creation, version upload, and cup enrolment. Minor gaps exist around bot administration, such as updating or deleting a bot, and cup participation lacks an explicit unenrol operation.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues