🚀 Star Wars Explorer - MCP Server
Um servidor Model Context Protocol (MCP) desenvolvido com Laravel que fornece acesso a dados da franquia Star Wars através de uma API externa e banco de dados local.
📋 Sobre o Projeto
Este projeto implementa um servidor MCP usando Laravel que permite:
- 🔍 Buscar personagens de Star Wars no banco de dados local
- 📥 Importar personagens da API externa (SWAPI) para o banco local
- 💾 Armazenar dados localmente para consultas rápidas
- 🤖 Integração com IAs através do protocolo MCP
🛠️ Tecnologias
- PHP 8.5+
- Laravel 12
- Laravel MCP - Protocolo Model Context Protocol
- Laravel Sail - Ambiente Docker
- MySQL 8.4 - Banco de dados
- Redis - Cache
📦 Pré-requisitos
Antes de começar, certifique-se de ter instalado:
Nota: Como utilizamos Laravel Sail, não é necessário ter PHP instalado localmente. Tudo roda dentro do Docker.
🚀 Instalação
Passo 1: Clonar o Repositório
git clone <url-do-repositorio>
cd mcp-app
Passo 2: Configurar o Ambiente
# Copiar o arquivo de configuração de ambiente
cp .env.example .env
Passo 3: Instalar Dependências
# Instalar dependências do Composer via Sail
./vendor/bin/sail composer install
Dica: Se você não tiver o
vendor/bin/sail, execute primeiro:composer install
Passo 4: Configurar a Aplicação
# Gerar a chave da aplicação
./vendor/bin/sail artisan key:generate
# Executar as migrations do banco de dados
./vendor/bin/sail artisan migrate
Passo 5: Iniciar os Containers
# Iniciar os containers em background
./vendor/bin/sail up -d
# Ou iniciar e ver os logs em tempo real
./vendor/bin/sail up
▶️ Executando o Servidor MCP
Após a instalação, você tem duas formas de executar o servidor:
Opção 1: Modo STDIO (Produção)
Execute o servidor MCP diretamente:
./vendor/bin/sail artisan mcp:start star-wars-explorer
Este comando inicia o servidor no modo STDIO, pronto para comunicação via protocolo MCP.
Opção 2: Inspector (Desenvolvimento/Testes) ⭐ Recomendado
Use o Inspector para testar o servidor com uma interface visual:
./vendor/bin/sail artisan mcp:inspector star-wars-explorer
O Inspector:
- 🌐 Abre uma interface web interativa
- 🧪 Permite testar todas as tools disponíveis
- 📊 Mostra as respostas do servidor em tempo real
- 🔍 Facilita o debug e desenvolvimento
🧪 Testando as Funcionalidades
O servidor MCP expõe uma tool chamada star-wars-tool com as seguintes funcionalidades:
1. Buscar Todos os Personagens
Chame a tool sem parâmetros para listar todos os personagens salvos localmente:
{}
2. Buscar por Nome
Busque personagens pelo nome no banco de dados local:
{
"search": "Luke"
}
3. Importar da API Externa
Importe um personagem da API SWAPI usando o ID:
{
"id": 1
}
IDs disponíveis na API: 1, 2, 3, 4, 5... (consulte a documentação da SWAPI)
📁 Estrutura do Projeto
mcp-app/
├── app/
│ ├── Mcp/
│ │ ├── Servers/
│ │ │ ├── StarWarsServer.php # Servidor MCP principal
│ │ │ └── MyAssistantServer.php # Servidor exemplo
│ │ └── Tools/
│ │ ├── StarWarsTool.php # Tool principal
│ │ └── GetProjectStats.php # Tool exemplo
│ ├── Models/
│ │ └── Character.php # Model do personagem
│ └── Services/
│ ├── External/
│ │ └── SwapiService.php # Serviço de integração com API
│ └── Models/
│ └── CharacterService.php # Lógica de negócio
├── routes/
│ └── ai.php # Registro dos servidores MCP
├── database/
│ └── migrations/ # Migrations do banco
└── compose.yaml # Configuração Docker
🔧 Comandos Úteis
Gerenciamento do Docker
# Iniciar containers
./vendor/bin/sail up -d
# Parar containers
./vendor/bin/sail down
# Ver logs
./vendor/bin/sail logs
# Acessar shell do container
./vendor/bin/sail shell
Comandos Artisan
# Ver logs do Laravel
./vendor/bin/sail artisan pail
# Limpar cache
./vendor/bin/sail artisan config:clear
./vendor/bin/sail artisan cache:clear
# Executar migrations
./vendor/bin/sail artisan migrate
# Rollback migrations
./vendor/bin/sail artisan migrate:rollback
Comandos MCP
# Listar servidores MCP disponíveis
./vendor/bin/sail artisan mcp:inspector
# Iniciar servidor específico
./vendor/bin/sail artisan mcp:start star-wars-explorer
# Abrir inspector para testes
./vendor/bin/sail artisan mcp:inspector star-wars-explorer
🎯 Funcionalidades da Tool
A StarWarsTool oferece três modos de operação:
| Parâmetro | Tipo | Descrição |
|---|---|---|
id | integer (opcional) | ID do personagem na API SWAPI para importar |
search | string (opcional) | Nome do personagem para buscar localmente |
Comportamento:
- Se
idfor fornecido: importa da API e salva no banco local - Se
searchfor fornecido: busca no banco local por nome - Se nenhum parâmetro: retorna todos os personagens do banco local
🔌 Integração com Clientes MCP
Para integrar este servidor MCP com um cliente (como Claude Desktop, Cursor, etc.), configure:
Handle: star-wars-explorer
Comando:
php artisan mcp:start star-wars-explorer
Transport: STDIO
📝 Padrões de Código
Este projeto segue as melhores práticas do Laravel:
- ✅
declare(strict_types=1);em todos os arquivos PHP - ✅ Tipagem estrita em propriedades, parâmetros e retornos
- ✅ Services como
final readonly class - ✅ Controllers magros (Thin Controllers)
- ✅ Lógica de negócio em Services
- ✅ Dependency Injection via construtor
🐛 Troubleshooting
Erro: "MCP Server with name [star-wars-explorer] not found"
Verifique se o servidor está registrado em routes/ai.php:
Mcp::local('star-wars-explorer', StarWarsServer::class);
Erro: "Connection refused" ao iniciar Sail
Certifique-se de que o Docker está rodando:
docker ps
Erro ao executar migrations
Verifique se o banco de dados está configurado corretamente no .env:
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=password
📚 Recursos Adicionais
📄 Licença
Este projeto está sob a licença MIT.
Desenvolvido com ❤️ usando Laravel e MCP
