Browse, search, and import Star Wars character data from SWAPI into a local DB.
🚀 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 p |
Tools (1)
star-wars-toolSearch local characters, list all characters, or import new characters from the SWAPI external API.Configuration
{
"mcpServers": {
"star-wars-explorer": {
"command": "./vendor/bin/sail",
"args": [
"artisan",
"mcp:start",
"star-wars-explorer"
]
}
}
}