# 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

## 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

```bash
# 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)

```bash
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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:

```javascript
// 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