# Bedrock Server Manager MCP Server

A comprehensive Model Context Protocol (MCP) server that provides natural language access to [Bedrock Server Manager](https://github.com/DMedina559/bedrock-server-manager/) functionality. This server enables you to manage your Minecraft Bedrock Edition servers through AI assistants like Claude Desktop using simple conversational commands.

## 🚀 Features

### Server Management
- **Server Lifecycle**: Start, stop, restart, and monitor server status
- **Server Installation**: Install new servers with custom configurations
- **Server Updates**: Update servers to specific versions or latest releases
- **Server Validation**: Verify server integrity and configuration

### Player & World Management
- **Allowlist Management**: Add/remove players from server allowlists
- **Player Permissions**: View and manage player permission levels
- **World Operations**: Reset worlds, export/import world files, install custom worlds
- **Global Player Lists**: Manage global player lists across servers

### Backup & Restore
- **Automated Backups**: Create server and world backups on demand
- **Backup Management**: List, prune, and manage backup files
- **Restore Operations**: Restore servers from specific backup files
- **Export/Import**: Export worlds and import custom content

### Advanced Features
- **Add-on Management**: Install and manage Bedrock add-ons
- **Plugin Control**: Enable/disable plugins, reload configurations, trigger events
- **Scheduled Tasks**: Create and manage cron jobs (Linux/macOS) or Windows tasks
- **System Monitoring**: View system information and server process details
- **Configuration Management**: Update server properties and service configurations

## 📋 Prerequisites

- Python 3.8 or higher
- Access to a running [Bedrock Server Manager](https://github.com/DMedina559/bedrock-server-manager/) instance
- Valid credentials for your Bedrock Server Manager

## 🛠️ Installation

### 1. Clone or Download
```bash
git clone <repository-url>
cd BedrockMCP
```

### 2. Create Virtual Environment
```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

### 3. Install Dependencies
```bash
pip install -r requirements.txt
```

### 4. Environment Configuration
Create a `.env` file in the project root:

```env
# Required: Your Bedrock Server Manager API endpoint
BEDROCK_API_BASE=http://localhost:11325

# Required: Authentication credentials
BEDROCK_SERVER_MANAGER_USERNAME=your_username
BEDROCK_SERVER_MANAGER_PASSWORD=your_password

# Optional: Enable debug output for API responses
BEDROCK_DEBUG=false
```

**Configuration Notes:**
- The default Bedrock Server Manager port is `11325`
- Replace `localhost` with your server's IP address if running remotely
- Ensure your Bedrock Server Manager instance is running and accessible

## 🎯 Usage

### Standalone Mode
```bash
python bedrock_mcp_server.py
```

Add `--debug` flag for detailed API response logging:
```bash
python bedrock_mcp_server.py --debug
```

### With Claude Desktop

1. **Open Claude Desktop Configuration**
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. **Add MCP Server Configuration**
   ```json
   {
     "mcpServers": {
       "bedrock-server-manager": {
         "command": "/path/to/your/BedrockMCP/start_bedrock_mcp.sh",
         "args": []
       }
     }
   }
   ```

3. **Make Start Script Executable** (macOS/Linux)
   ```bash
   chmod +x start_bedrock_mcp.sh
   ```

4. **Update Script Path**
   Edit `start_bedrock_mcp.sh` and update the project path on line 4:
   ```bash
   cd /your/actual/path/to/BedrockMCP
   ```

5. **Restart Claude Desktop**

## 🔧 Available Tools

- The set of available tools and endpoints is evolving rapidly. For the most up-to-date list, please refer to the OpenAPI specification for the bedrock-server-manager or use natural language commands with your LLM assistant to discover current capabilities.

## 💬 Example Commands

Once configured with Claude Desktop, you can use natural language commands like:

### Server Operations
- *"What servers do I have and what's their status?"*
- *"Start my survival server"*
- *"Stop the creative server and then restart it"*
- *"What's the detailed status of my main server?"*

### Player Management
- *"Who's on the allowlist for my survival server?"*
- *"Add Steve and Alex to the survival server allowlist"*
- *"Remove Bob from the creative server allowlist"*
- *"What are the player permissions on my server?"*

### Server Commands
- *"Send the 'list' command to my survival server"*
- *"Tell all players on the creative server that the server will restart in 5 minutes"*
- *"Change the difficulty to hard on my survival server"*

### Backup Operations
- *"Create a backup of my survival server"*
- *"Show me all backups for the creative server"*
- *"Restore my survival server from yesterday's backup"*
- *"Delete old backups, keeping only the last 5"*

### World Management
- *"Reset the world on my testing server"*
- *"Install the 'skyblock' world on my adventure server"*
- *"Export the world from my survival server"*

### Advanced Operations
- *"Update my main server to the latest version"*
- *"Install the better-spawning addon on all my servers"*
- *"Create a daily backup job for my survival server"*
- *"Show me the system information"*

## 🔍 Troubleshooting

### Connection Issues
1. **Verify Bedrock Server Manager is running**
   ```bash
   curl http://localhost:11325/api/health
   ```

2. **Check credentials in .env file**
   - Ensure username and password are correct
   - Verify BEDROCK_API_BASE URL is accessible

3. **Enable debug mode**
   ```bash
   python bedrock_mcp_server.py --debug
   ```

### Common Problems

**"Unable to fetch servers list"**
- Check if Bedrock Server Manager is running
- Verify network connectivity to the API endpoint
- Confirm authentication credentials

**"Login failed"**
- Double-check username and password in `.env`
- Ensure Bedrock Server Manager allows API access

**Script permission errors (macOS/Linux)**
```bash
chmod +x start_bedrock_mcp.sh
```

## 🧪 API Coverage Testing

To ensure all OpenAPI endpoints are mapped to MCP functions (and vice versa), this project includes automated coverage scripts:

1. **Extract OpenAPI Endpoints:**
   - `extract_openapi_endpoints.py` fetches the OpenAPI spec from your running Bedrock Server Manager instance (host and port configurable) and outputs all endpoints with their `operationId`s to `openapi_endpoints.json`.
2. **Extract MCP Functions:**
   - `extract_mcp_functions.py` scans `bedrock_mcp_server.py` for MCP-exposed functions (decorated with `@mcp_tool_testable`) and outputs them to `mcp_functions.json`.
3. **Run Coverage Test:**
   - `test_api_coverage.py` (run with `pytest`) compares the two lists and reports any unmapped endpoints or functions.
4. **Automated Workflow:**
   - `run_api_coverage_check.py` automates all the above steps.

### How to Use

Run the coverage workflow and optionally specify the server host and port
(defaults `localhost` and `11325`):
```bash
python run_api_coverage_check.py [server] [port]
```
   This will:
   - Generate `openapi_endpoints.json` and `mcp_functions.json`
   - Run the coverage test and print any missing or extra mappings

### Requirements
- `pytest` must be installed (see Dependencies below)

### Purpose
- This workflow helps keep your OpenAPI documentation and MCP implementation in sync, ensuring all endpoints are covered and documented.

## 📝 Dependencies

- **mcp** (>=1.2.0) - Model Context Protocol implementation
- **httpx** (>=0.24.0) - Modern HTTP client for API requests
- **python-dotenv** (>=1.0.0) - Environment variable management
- **pytest** (for API coverage testing)

## 🤝 Contributing

This project interfaces with [Bedrock Server Manager](https://github.com/DMedina559/bedrock-server-manager/). For issues related to the server manager itself, please refer to that project's repository.

## 📄 License

This project is provided as-is for educational and personal use. Please respect the licenses of the underlying Bedrock Server Manager and Minecraft Bedrock Edition.