docs/MCP_USAGE_GUIDE.md

# MCP Usage Guide

This guide explains how to use the MCP (Model Context Protocol) integration for the RTS Commander game.

## Understanding MCP

MCP (Model Context Protocol) is a standardized way for AI systems to interact with applications. It defines how AI agents can:
1. Access information about an application (resources)
2. Perform actions in an application (tools)
3. Maintain a persistent connection for ongoing interaction

## Our Implementation

We've implemented an MCP server for the RTS Commander game that:
- Runs on port 8001
- Exposes game state information
- Provides tools for performing game actions
- Integrates with the existing AI analysis system

## Available Tools

The MCP server provides the following tools:

1. **get_game_state()** - Returns the current game state as JSON
2. **get_ai_analysis(language)** - Returns AI tactical analysis in the specified language
3. **move_units(unit_ids, target_x, target_y)** - Moves units to a target position
4. **attack_unit(attacker_ids, target_id)** - Commands units to attack an enemy unit
5. **build_building(building_type, position_x, position_y, player_id)** - Builds a structure
6. **send_game_command(command_type, **kwargs)** - Sends a generic command to the game

## Available Resources

The MCP server provides the following resources:

1. **game_documentation** - Provides the game's README documentation
2. **game_rules** - Provides the game's architecture and rules documentation

## How to Use the MCP Server

### 1. Start the Servers

First, you need to start both the main game server and the MCP server:

```bash
# Terminal 1: Start main game server
cd /home/luigi/rts/web
python start.py

# Terminal 2: Start MCP server
cd /home/luigi/rts/web
python mcp_server.py
```

Or you can start both with a single command:
```bash
cd /home/luigi/rts/web
python start_with_mcp.py
```

### 2. Verify the Server is Running

Check that the MCP server is listening on port 8001:
```bash
netstat -tlnp | grep :8001
```

You should see output showing that a process is listening on port 8001.

### 3. Connect an MCP-Compatible Client

To actually use the MCP server, you need an MCP-compatible client. Some options include:

#### Option 1: Use a Generic MCP Client

You can create a simple Python client to test the connection:

```python
# mcp_test_client.py
import asyncio
import json
from mcp.client.stdio import stdio_client
from mcp.types import InitializeRequest

async def test_mcp_client():
    # This is a simplified example
    print("Connecting to MCP server...")
    # In practice, you would connect to localhost:8001
    
if __name__ == "__main__":
    asyncio.run(test_mcp_client())
```

#### Option 2: Use an AI Framework with MCP Support

Some AI frameworks have built-in MCP support. You would typically configure them to connect to:
- Host: localhost
- Port: 8001

#### Option 3: Manual Testing with curl

You can test basic connectivity with curl:
```bash
curl -v http://localhost:8001
```

Note that MCP typically uses a more complex protocol than simple HTTP requests, so full functionality requires an actual MCP client.

## Common Issues and Troubleshooting

### "Connection refused" Error

If you get a connection refused error:
1. Make sure both servers are running
2. Check that the MCP server is listening on port 8001:
   ```bash
   netstat -tlnp | grep :8001
   ```
3. Verify firewall settings if running on a remote machine

### "claude: command not found"

The `claude` command is not a standard command. It would only exist if you had installed a specific AI client that provides this command. Our implementation provides the MCP server, but you need to separately obtain an MCP client.

### Port Conflicts

If port 8001 is already in use:
1. You can modify the port in `mcp_server.py`
2. Or stop the process using port 8001:
   ```bash
   lsof -i :8001
   kill -9 <PID>
   ```

## Example Usage Scenarios

### Scenario 1: Getting Game State

An AI agent could call the `get_game_state()` tool to understand the current situation:
```json
{
  "tool": "get_game_state"
}
```

### Scenario 2: Moving Units

An AI agent could move units to a position:
```json
{
  "tool": "move_units",
  "arguments": {
    "unit_ids": ["unit1", "unit2"],
    "target_x": 100,
    "target_y": 200
  }
}
```

### Scenario 3: Building a Structure

An AI agent could build a barracks:
```json
{
  "tool": "build_building",
  "arguments": {
    "building_type": "barracks",
    "position_x": 150,
    "position_y": 150,
    "player_id": 0
  }
}
```

## Security Considerations

The MCP server runs on a separate port (8001) from the main game server (7860) to isolate AI access from player connections. In a production environment, you should consider:

1. Adding authentication for MCP clients
2. Implementing rate limiting for commands
3. Adding input validation for all commands
4. Running the server in a secure network environment

## Extending the Integration

To add new tools or resources:

1. Add new methods to the `_register_tools` or `_register_resources` methods in `RTSGameMCP` in `mcp_server.py`
2. Implement the functionality using existing game infrastructure
3. Test the new functionality

## Conclusion

The MCP integration provides a robust foundation for AI agents to interact with the RTS Commander game. While you need an MCP-compatible client to actually use it, the server is fully functional and ready for integration with AI systems.