docs/MCP_GAME_CONTROL_DETAILS.md

# Detailed Game Control via MCP Interface

## Overview

The MCP interface we've implemented provides comprehensive control over the RTS Commander game, allowing AI agents to both observe and manipulate the game state through standardized tools. This document details exactly what aspects of the game can be controlled via the MCP interface.

## Game State Observation

### Full Game State Access
The `get_game_state()` tool provides complete visibility into the game:

1. **Units Information**
   - All units on the map (player and enemy)
   - Unit types (infantry, tanks, helicopters, harvesters)
   - Current positions, health, and status
   - Cargo capacity for harvesters
   - Movement targets and combat targets
   - Manual control status

2. **Buildings Information**
   - All buildings (HQ, power plants, barracks, etc.)
   - Building types and positions
   - Health status
   - Production queues and progress
   - Defensive targeting for turrets

3. **Player Information**
   - Resources (credits)
   - Power production and consumption
   - Superweapon charge status
   - Language preferences
   - AI vs human player status

4. **Map Information**
   - Terrain types (grass, ore, gems, water)
   - Fog of war visibility
   - Map dimensions

5. **Game Status**
   - Current game tick
   - Game started/over status
   - Winner information
   - Last AI analysis

## Game Actions (Control)

### Unit Control

1. **Movement**
   - `move_units(unit_ids, target_x, target_y)`: Move any units to specific coordinates
   - Supports single unit or group movement
   - Automatic formation spreading for multiple units

2. **Combat**
   - `attack_unit(attacker_ids, target_id)`: Command units to attack specific enemies
   - Works for both unit-vs-unit and unit-vs-building combat
   - Sets manual order flags to override AI behavior

### Building Control

1. **Construction**
   - `build_building(building_type, position_x, position_y, player_id)`: Construct any building type
   - Enforces game rules (cost, positioning, requirements)
   - Handles all building types: HQ, power plants, barracks, war factories, refineries, defense turrets

2. **Unit Production**
   - `send_game_command(command_type="build_unit", ...)`: Produce units in appropriate buildings
   - Validates production requirements (barracks for infantry, etc.)
   - Manages production queues

### Strategic Actions

1. **Superweapon**
   - Launch nukes when charged
   - Prepare and cancel nuke targeting
   - Automatic charge management

2. **Game Management**
   - `send_game_command(command_type="change_language", ...)` : Change player language
   - `send_game_command(command_type="request_ai_analysis", ...)` : Request tactical analysis

## AI Integration

### Tactical Analysis
The `get_ai_analysis(language)` tool provides:
- Strategic situation summary
- Tactical recommendations (4 tips)
- Motivational coaching line
- Language-specific output (EN/FR/ZH-TW)

This connects to the same Qwen2.5-0.5B LLM that powers the in-game AI analysis panel.

## Detailed Tool Breakdown

### 1. get_game_state()
**Purpose**: Retrieve complete current game state
**Returns**: JSON object with all game information
**Use Cases**:
- Understanding current tactical situation
- Planning strategic moves
- Monitoring resource levels
- Tracking unit positions and health

### 2. get_ai_analysis(language)
**Purpose**: Get tactical analysis from built-in AI
**Parameters**: 
- language (optional, default="en"): Language for output
**Returns**: JSON with summary, tips, and coach message
**Use Cases**:
- Getting strategic advice
- Understanding tactical priorities
- Learning from AI recommendations

### 3. move_units(unit_ids, target_x, target_y)
**Purpose**: Move units to specific location
**Parameters**:
- unit_ids: List of unit IDs to move
- target_x: X coordinate destination
- target_y: Y coordinate destination
**Returns**: Success/failure message
**Use Cases**:
- Positioning units for attack
- Moving harvesters to ore
- Relocating defensive units
- Executing tactical maneuvers

### 4. attack_unit(attacker_ids, target_id)
**Purpose**: Command units to attack an enemy
**Parameters**:
- attacker_ids: List of unit IDs to attack with
- target_id: ID of enemy unit to attack
**Returns**: Success/failure message
**Use Cases**:
- Engaging enemy forces
- Targeting high-priority units
- Executing coordinated attacks
- Defending against enemy advances

### 5. build_building(building_type, position_x, position_y, player_id)
**Purpose**: Construct a building at specific location
**Parameters**:
- building_type: Type of building to construct
- position_x: X coordinate for placement
- position_y: Y coordinate for placement
- player_id: Player ID (typically 0 for human player)
**Returns**: Success/failure message
**Use Cases**:
- Expanding base infrastructure
- Building production facilities
- Constructing defensive positions
- Managing power supply

### 6. send_game_command(command_type, **kwargs)
**Purpose**: Send any supported game command
**Parameters**:
- command_type: Type of command to send
- **kwargs: Command-specific parameters
**Returns**: Success/failure message
**Supported Commands**:
- "move_unit": Move units (same as move_units tool)
- "attack_unit": Attack units (same as attack_unit tool)
- "attack_building": Attack buildings
- "build_unit": Produce units
- "build_building": Build structures (same as build_building tool)
- "stop_units": Stop unit movement
- "prepare_nuke": Prepare superweapon
- "cancel_nuke": Cancel superweapon preparation
- "launch_nuke": Launch superweapon at target
- "change_language": Change player language
- "request_ai_analysis": Request AI tactical analysis

## Game Systems Accessible via MCP

### 1. Economic System
- **Resource Management**: Monitor and control credits
- **Production**: Build structures and units
- **Power System**: Manage power production and consumption

### 2. Military System
- **Unit Control**: Full movement and combat control
- **Formation Management**: Group unit movements
- **Combat Tactics**: Target selection and engagement

### 3. Base Building System
- **Construction**: Build all structure types
- **Placement Rules**: Respects game constraints
- **Production Queues**: Manage unit production

### 4. Strategic Systems
- **Superweapon**: Nuke launch capability
- **AI Analysis**: Tactical situation assessment
- **Language**: Multi-language support

### 5. Game State Management
- **Progress Tracking**: Current tick and game status
- **Victory Conditions**: Monitor win/lose state
- **Fog of War**: Visibility information

## Limitations and Security

### Current Limitations
1. **Player ID Restriction**: All actions are restricted to player ID 0 (human player)
2. **No Direct Enemy Control**: Cannot directly control enemy AI units
3. **Game Rules Enforcement**: All actions must comply with game rules

### Security Features
1. **Port Isolation**: MCP server runs on separate port (8001) from game server (7860)
2. **Input Validation**: All commands are validated by existing game logic
3. **Cost Checking**: Resource costs are enforced for all building/unit actions

## Example AI Strategies Enabled

### 1. Resource Management AI
An AI could:
1. Use `get_game_state()` to check current credits
2. Identify optimal harvester positions with `get_game_state()`
3. Move harvesters using `move_units()`
4. Build refineries with `build_building()`
5. Request analysis with `get_ai_analysis()` to confirm strategy

### 2. Military Tactics AI
An AI could:
1. Assess enemy positions with `get_game_state()`
2. Move forces into position with `move_units()`
3. Coordinate attacks with `attack_unit()`
4. Build defensive structures with `build_building()`
5. Get tactical advice with `get_ai_analysis()`

### 3. Base Expansion AI
An AI could:
1. Monitor power status with `get_game_state()`
2. Build power plants when needed with `build_building()`
3. Expand to new areas with `move_units()`
4. Construct new production facilities with `build_building()`
5. Verify expansion success with `get_game_state()`

## Integration with Existing Systems

The MCP interface seamlessly integrates with all existing game systems:
- **Connection Manager**: Uses the same `handle_command` method as human players
- **AI Analysis**: Connects to the same Qwen2.5 LLM system
- **Game Rules**: All actions respect the same rules as human gameplay
- **Notifications**: AI actions trigger the same UI notifications
- **State Sync**: Game state updates are broadcast to all clients the same way

## Future Enhancement Possibilities

While the current implementation is comprehensive, potential future enhancements could include:
1. **Advanced Unit Control**: Formation patterns, patrol routes
2. **Economic AI**: Automated resource optimization
3. **Diplomacy System**: Multiplayer interaction controls
4. **Scenario Management**: Custom game setup tools
5. **Replay System**: Game recording and playback controls

## Conclusion

The MCP interface provides complete control over all strategic and tactical aspects of the RTS Commander game. AI agents can observe the full game state, make informed decisions using AI analysis, and execute any action available to human players. The implementation maintains all existing game balance and rules while providing a standardized interface for AI integration.