Bedrock Server Manager

Gerencie seu servidor Bedrock com comandos em linguagem natural usando a API do Bedrock Server Manager.

Documentação

Servidor MCP do Bedrock Server Manager

Um servidor abrangente do Model Context Protocol (MCP) que fornece acesso em linguagem natural à funcionalidade do Bedrock Server Manager. Este servidor permite gerenciar seus servidores Minecraft Bedrock Edition por meio de assistentes de IA, como o Claude Desktop, usando comandos conversacionais simples.

🚀 Recursos

Gerenciamento de Servidores

Ciclo de Vida do Servidor: Iniciar, parar, reiniciar e monitorar o status do servidor
Instalação de Servidores: Instalar novos servidores com configurações personalizadas
Atualizações de Servidores: Atualizar servidores para versões específicas ou versões mais recentes
Validação de Servidores: Verificar a integridade e a configuração do servidor

Gerenciamento de Jogadores e Mundos

Gerenciamento de Lista de Permissões: Adicionar/remover jogadores das listas de permissões do servidor
Permissões de Jogadores: Visualizar e gerenciar níveis de permissão dos jogadores
Operações de Mundo: Redefinir mundos, exportar/importar arquivos de mundo, instalar mundos personalizados
Listas Globais de Jogadores: Gerenciar listas globais de jogadores entre servidores

Backup e Restauração

Backups Automatizados: Criar backups de servidores e mundos sob demanda
Gerenciamento de Backups: Listar, podar e gerenciar arquivos de backup
Operações de Restauração: Restaurar servidores a partir de arquivos de backup específicos
Exportar/Importar: Exportar mundos e importar conteúdo personalizado

Recursos Avançados

Gerenciamento de Add-ons: Instalar e gerenciar add-ons do Bedrock
Controle de Plugins: Ativar/desativar plugins, recarregar configurações, acionar eventos
Tarefas Agendadas: Criar e gerenciar cron jobs (Linux/macOS) ou tarefas do Windows
Monitoramento do Sistema: Visualizar informações do sistema e detalhes dos processos do servidor
Gerenciamento de Configuração: Atualizar propriedades do servidor e configurações de serviço

📋 Pré-requisitos

Python 3.8 ou superior
Acesso a uma instância em execução do Bedrock Server Manager
Credenciais válidas para o seu Bedrock Server Manager

🛠️ Instalação

1. Clonar ou Baixar

git clone <repository-url>
cd BedrockMCP

2. Criar Ambiente Virtual

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Instalar Dependências

pip install -r requirements.txt

4. Configuração de Ambiente

Crie um arquivo .env na raiz do projeto:

# 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

Notas de Configuração:

A porta padrão do Bedrock Server Manager é 11325
Substitua localhost pelo endereço IP do seu servidor se estiver executando remotamente
Certifique-se de que sua instância do Bedrock Server Manager esteja em execução e acessível

🎯 Uso

Modo Autônomo

python bedrock_mcp_server.py

Adicione o sinalizador --debug para registro detalhado de respostas da API:

python bedrock_mcp_server.py --debug

Com o Claude Desktop

Abra a Configuração do Claude Desktop
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Adicione a Configuração do Servidor MCP

{
  "mcpServers": {
    "bedrock-server-manager": {
      "command": "/path/to/your/BedrockMCP/start_bedrock_mcp.sh",
      "args": []
    }
  }
}

Torne o Script de Inicialização Executável (macOS/Linux)
```
chmod +x start_bedrock_mcp.sh
```
Atualize o Caminho do Script Edite start_bedrock_mcp.sh e atualize o caminho do projeto na linha 4:
```
cd /your/actual/path/to/BedrockMCP
```
Reinicie o Claude Desktop

🔧 Ferramentas Disponíveis

O conjunto de ferramentas e endpoints disponíveis está evoluindo rapidamente. Para obter a lista mais atualizada, consulte a especificação OpenAPI do bedrock-server-manager ou use comandos em linguagem natural com seu assistente de LLM para descobrir os recursos atuais.

💬 Exemplos de Comandos

Depois de configurado com o Claude Desktop, você pode usar comandos em linguagem natural como:

Operações de Servidor

"Quais servidores eu tenho e qual é o status deles?"
"Inicie meu servidor de sobrevivência"
"Pare o servidor criativo e depois reinicie-o"
"Qual é o status detalhado do meu servidor principal?"

Gerenciamento de Jogadores

"Quem está na lista de permissões do meu servidor de sobrevivência?"
"Adicione Steve e Alex à lista de permissões do servidor de sobrevivência"
"Remova Bob da lista de permissões do servidor criativo"
"Quais são as permissões dos jogadores no meu servidor?"

Comandos do Servidor

"Envie o comando 'list' para meu servidor de sobrevivência"
"Diga a todos os jogadores do servidor criativo que o servidor será reiniciado em 5 minutos"
"Altere a dificuldade para difícil no meu servidor de sobrevivência"

Operações de Backup

"Crie um backup do meu servidor de sobrevivência"
"Mostre todos os backups do servidor criativo"
"Restaure meu servidor de sobrevivência a partir do backup de ontem"
"Exclua backups antigos, mantendo apenas os últimos 5"

Gerenciamento de Mundos

"Redefina o mundo no meu servidor de testes"
"Instale o mundo 'skyblock' no meu servidor de aventura"
"Exporte o mundo do meu servidor de sobrevivência"

Operações Avançadas

"Atualize meu servidor principal para a versão mais recente"
"Instale o addon better-spawning em todos os meus servidores"
"Crie um trabalho de backup diário para meu servidor de sobrevivência"
"Mostre as informações do sistema"

🔍 Solução de Problemas

Problemas de Conexão

Verifique se o Bedrock Server Manager está em execução
```
curl http://localhost:11325/api/health
```
Verifique as credenciais no arquivo .env
- Certifique-se de que o nome de usuário e a senha estejam corretos
- Verifique se a URL BEDROCK_API_BASE está acessível
Ative o modo de depuração
```
python bedrock_mcp_server.py --debug
```

Problemas Comuns

"Não foi possível buscar a lista de servidores"

Verifique se o Bedrock Server Manager está em execução
Verifique a conectividade de rede com o endpoint da API
Confirme as credenciais de autenticação

"Falha no login"

Verifique novamente o nome de usuário e a senha em .env
Certifique-se de que o Bedrock Server Manager permite acesso à API

Erros de permissão de script (macOS/Linux)

chmod +x start_bedrock_mcp.sh

🧪 Teste de Cobertura da API

Para garantir que todos os endpoints OpenAPI estejam mapeados para funções MCP (e vice-versa), este projeto inclui scripts automatizados de cobertura:

Extrair Endpoints OpenAPI:
- extract_openapi_endpoints.py busca a especificação OpenAPI da sua instância em execução do Bedrock Server Manager (host e porta configuráveis) e gera todos os endpoints com seus operationIds em openapi_endpoints.json.
Extrair Funções MCP:
- extract_mcp_functions.py examina bedrock_mcp_server.py em busca de funções expostas ao MCP (decoradas com @mcp_tool_testable) e as gera em mcp_functions.json.
Executar Teste de Cobertura:
- test_api_coverage.py (executado com pytest) compara as duas listas e relata quaisquer endpoints ou funções não mapeados.
Fluxo de Trabalho Automatizado:
- run_api_coverage_check.py automatiza todas as etapas acima.

Como Usar

Execute o fluxo de trabalho de cobertura e, opcionalmente, especifique o host e a porta do servidor (padrões localhost e 11325):

python run_api_coverage_check.py [server] [port]

Isso irá:

Gerar openapi_endpoints.json e mcp_functions.json
Executar o teste de cobertura e imprimir quaisquer mapeamentos ausentes ou extras

Requisitos

pytest deve estar instalado (consulte Dependências abaixo)

Propósito

Este fluxo de trabalho ajuda a manter sua documentação OpenAPI e implementação MCP sincronizadas, garantindo que todos os endpoints estejam cobertos e documentados.

📝 Dependências

mcp (>=1.2.0) - Implementação do Model Context Protocol
httpx (>=0.24.0) - Cliente HTTP moderno para requisições de API
python-dotenv (>=1.0.0) - Gerenciamento de variáveis de ambiente
pytest (para teste de cobertura da API)

🤝 Contribuindo

Este projeto faz interface com o Bedrock Server Manager. Para problemas relacionados ao gerenciador de servidores em si, consulte o repositório desse projeto.

📄 Licença

Este projeto é fornecido como está, para uso educacional e pessoal. Respeite as licenças do Bedrock Server Manager e do Minecraft Bedrock Edition subjacentes.