# 🚀 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](https://www.docker.com/get-started) e Docker Compose
- [Git](https://git-scm.com/)

> **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

```bash
git clone <url-do-repositorio>
cd mcp-app
```

### Passo 2: Configurar o Ambiente

```bash
# Copiar o arquivo de configuração de ambiente
cp .env.example .env
```

### Passo 3: Instalar Dependências

```bash
# Instalar dependências do Composer via Sail
./vendor/bin/sail composer install
```

> **Dica:** Se você não tiver o `vendor/bin/sail`, execute primeiro:
> ```bash
> composer install
> ```

### Passo 4: Configurar a Aplicação

```bash
# 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

```bash
# 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:

```bash
./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:

```bash
./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:

```json
{}
```

### 2. Buscar por Nome

Busque personagens pelo nome no banco de dados local:

```json
{
  "search": "Luke"
}
```

### 3. Importar da API Externa

Importe um personagem da API SWAPI usando o ID:

```json
{
  "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

```bash
# 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

```bash
# 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

```bash
# 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:**
```bash
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`:

```php
Mcp::local('star-wars-explorer', StarWarsServer::class);
```

### Erro: "Connection refused" ao iniciar Sail

Certifique-se de que o Docker está rodando:

```bash
docker ps
```

### Erro ao executar migrations

Verifique se o banco de dados está configurado corretamente no `.env`:

```env
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=password
```

## 📚 Recursos Adicionais

- [Documentação Laravel MCP](https://laravel.com/docs/mcp)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Laravel Sail](https://laravel.com/docs/sail)
- [SWAPI - Star Wars API](https://swapi.bry.com.br/)

## 📄 Licença

Este projeto está sob a licença MIT.

---

**Desenvolvido com ❤️ usando Laravel e MCP**