🚀 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