Battle Arena MCP Server

An MCP (Model Context Protocol) server that connects AI agents to the Battle Arena - AI Strategy Competition game. Run battles, tournaments, and analyze strategies programmatically.

What is this?

This MCP server wraps the Battle Arena REST API, giving any MCP-compatible AI agent (like Manus) direct access to:

• List strategies — See all available student and example fighters

• Get strategy code — Read the source code of any strategy

• Run battles — Pit two strategies against each other with configurable HP

• Run tournaments — Round-robin competition with leaderboard

• Get game rules — All damage values, ranges, and mechanics

Related MCP server: PokeArena

Quick Start

Option 1: Use with Manus (Custom MCP Connector)

1. In your Manus project, go to Settings → Connectors → Custom MCP

2. Add this server with the command:

   npx battle-arena-mcp

3. Set the environment variable (optional, defaults to the hosted arena):

   BATTLE_ARENA_URL=https://battle-arena.manus.space

Option 2: Run Locally

# Clone and install
git clone https://github.com/Oscarlight/battle-arena-mcp.git
cd battle-arena-mcp
npm install
npm run build

# Run
node dist/index.js

Option 3: npx (no install)

npx battle-arena-mcp

Environment Variables

Available Tools

list_strategies

Lists all available strategies with their IDs, names, and fighting styles.

Example response:

{
  "strategies": [
    { "id": "jayden", "name": "Jayden", "style": "Balanced adaptive", "source": "student" },
    { "id": "rushdown_rex", "name": "Rushdown Rex", "style": "Aggressive pressure", "source": "example" }
  ],
  "total": 23
}

get_strategy_code

Returns the JavaScript source code of a strategy.

Parameters:

• id (required): Strategy ID from list_strategies

run_battle

Runs a 1v1 battle. Provide strategies by ID or custom code.

Parameters:

• strategyIdA / strategyA: Strategy A (by ID or code)

• strategyIdB / strategyB: Strategy B (by ID or code)

• hp (optional): HP value, 50-1000. Default: 100. Tournament: 250.

• includeTurnLog (optional): Include full turn-by-turn data

Example response:

{
  "winner": "Jayden",
  "winnerSide": "A",
  "nameA": "Jayden",
  "nameB": "80 Year Old Grandpa",
  "finalHpA": 48,
  "finalHpB": 0,
  "totalTurns": 55,
  "hp": 250
}

run_tournament

Runs a round-robin tournament between 2-20 strategies.

Parameters:

• strategyIds (optional): Array of strategy IDs

• strategies (optional): Array of custom strategies with code and optional id

• hp (optional): HP for all matches

Example response:

{
  "hp": 250,
  "totalMatches": 6,
  "leaderboard": [
    { "id": "jayden", "name": "Jayden", "wins": 2, "losses": 1, "winRate": 67 }
  ],
  "matches": [...]
}

get_game_rules

Returns all game constants (damage, ranges, stamina, etc.).

Writing Custom Strategies

A strategy is a JavaScript function that receives game state and returns an action:

// Strategy Name: My Fighter
// Strategy Style: Aggressive rushdown

function strategy(state) {
  // Available state:
  // state.myHp, state.enemyHp, state.distanceToEnemy
  // state.myStamina, state.isInLightRange, state.isInHeavyRange
  // state.turn, state.myIsRecovering, state.enemyIsRecovering
  // state.mustAttackSoon, state.mustMoveSoon
  
  // Available actions:
  // "move_up", "move_down", "move_left", "move_right"
  // "dash_toward", "dash_away"
  // "light_attack", "heavy_attack"
  // "block", "grab", "special"
  
  if (state.distanceToEnemy > 2) return "dash_toward";
  if (state.isInHeavyRange) return "heavy_attack";
  return "light_attack";
}

REST API (Direct Access)

The MCP server wraps these public endpoints:

No authentication required. Rate limited to 30 requests/minute.

License

MIT