# ReyxGPT: Minecraft Server Management Agent

ReyxGPT is an MCP server built with [FastMCP 3](https://gofastmcp.com) for managing Minecraft servers via RCON.

## Tools

### Server control
| Tool | Description |
|------|-------------|
| `execute_minecraft_command` | Run any command on the server |
| `execute_batch_commands` | Run multiple commands in sequence |
| `check_server_status` | Get TPS and version info |

### Players
| Tool | Description |
|------|-------------|
| `get_online_players` | List connected players |
| `get_player_location` | Get a player's XYZ coordinates |
| `teleport_player` | Teleport a player to coordinates |

### Command info
| Tool | Description |
|------|-------------|
| `list_commands` | List all ~80 Java Edition commands (filterable by category) |
| `get_command_info` | Get syntax, op level, and description for any command |
| `search_commands` | Search commands by keyword |
| `fetch_command_wiki` | Fetch live documentation from the Minecraft Wiki API |
| `get_server_command_help` | Ask the server itself for `/help <command>` |

## Setup

Copy `.env.example` to `.env` and fill in your RCON credentials:

```bash
cp .env.example .env
```

Make sure your `server.properties` has RCON enabled:
```properties
enable-rcon=true
rcon.port=25575
rcon.password=yourpassword
```

## Running

**stdio** (for Claude Desktop, Cursor, etc.):
```bash
uv run reyxgpt
```

**HTTP** (for network clients or multi-client setups):
```bash
uv run reyxgpt --transport http --host 0.0.0.0 --port 8000
```
MCP endpoint: `http://localhost:8000/mcp`  
Health check: `http://localhost:8000/health`

**SSE** (legacy):
```bash
uv run reyxgpt --transport sse --port 8000
```

## MCP Client Configuration

### Claude Desktop / Cursor (stdio)
```json
"mcpServers": {
  "reyxgpt": {
    "command": "uv",
    "args": ["--directory", "/ABSOLUTE/PATH/TO/ReyxGPT", "run", "reyxgpt"],
    "env": {
      "RCON_HOST": "localhost",
      "RCON_PORT": "25575",
      "RCON_PASSWORD": "yourpassword"
    }
  }
}
```

### HTTP transport
```json
"mcpServers": {
  "reyxgpt": {
    "url": "http://localhost:8000/mcp"
  }
}
```

## Project Structure

```
src/reyxgpt/
├── __init__.py         # exports mcp, registers all tools
├── __main__.py         # CLI entry point (--transport, --host, --port)
├── server.py           # FastMCP instance + lifespan + /health route
├── rcon.py             # RCONServer client
├── data/
│   └── commands.json   # ~80 Java Edition commands database
└── tools/
    ├── commands.py     # execute_minecraft_command, execute_batch_commands
    ├── players.py      # get_online_players, get_player_location, teleport_player
    ├── status.py       # check_server_status
    └── info.py         # list_commands, get_command_info, search_commands,
                        # fetch_command_wiki, get_server_command_help
```

## Requirements

- Python 3.10+
- [uv](https://github.com/astral-sh/uv)
- Minecraft Java Edition server with RCON enabled