How do I use Star Wars Explorer?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Star Wars Explorer search for characters named Luke Skywalker" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

🚀 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:

Docker e Docker Compose
Git

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 id for fornecido: importa da API e salva no banco local
Se search for 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

Star Wars Explorer