Battle Arena

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

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

Variable	Default	Description
BATTLE_ARENA_URL	https://battle-arena.manus.space	Base URL of the Battle Arena API

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:

Method	Endpoint	Description
GET	/api/strategies	List all strategies
GET	/api/strategies/:id/code	Get strategy source code
POST	/api/simulate	Run a single battle
POST	/api/tournament	Run a round-robin tournament
GET	/api/rules	Get game constants

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

License

MIT