# Guia Rápido - Executar MCP com Docker

## 🚀 Início Rápido

### 1️⃣ Construir e Iniciar o Container

```bash
cd Terraform_Project/Hands-on/MCP

# Construir a imagem
./docker-run.sh build

# Iniciar o container
./docker-run.sh start
```

### 2️⃣ Gerar o Banco de Dados Vetorial (primeira vez)

```bash
docker-compose exec mcp-server python generate_vector_db.py
```

**Saída esperada:**
```
✅ FAISS vector DB created successfully!
📁 Location: faiss_index
📦 Entries: 4 | Dimensions: 384
```

### 3️⃣ Testar o Sistema

#### Opção A: Usar o Cliente MCP (Recomendado)

```bash
# Em um terminal, execute o cliente
./docker-run.sh run-client
```

**Saída esperada:**
```
🔌 Starting MCP client for server: mcp_vector_server.py
✅ MCP Handshake Complete
🛠 Tools detected: ['create_vector_db', 'search_vector_db']
📌 RAW RESPONSE FROM SERVER:
1) score=0.8234
Critical TechWorks Quality...
```

#### Opção B: Executar o Servidor Manualmente

```bash
# Terminal 1: Iniciar o servidor
./docker-run.sh run-server
# O servidor ficará aguardando conexões (isso é normal!)

# Terminal 2: Executar o cliente
docker-compose exec mcp-server python client_vector.py mcp_vector_server.py
```

#### Opção C: Testar Busca Diretamente

```bash
docker-compose exec mcp-server python -c "
from search_vector_db import search_in_faiss
print(search_in_faiss('quality principles', top_k=2))
"
```

## 📋 Comandos Úteis

### Gerenciamento do Container

```bash
# Ver logs do container
docker-compose logs -f mcp-server

# Acessar shell do container
./docker-run.sh shell

# Parar o container
./docker-run.sh stop

# Reiniciar o container
docker-compose restart mcp-server
```

### Executar Scripts Python no Container

```bash
# Gerar banco de dados vetorial
docker-compose exec mcp-server python generate_vector_db.py

# Executar busca standalone
docker-compose exec mcp-server python search_vector_db.py

# Executar servidor MCP
docker-compose exec mcp-server python mcp_vector_server.py

# Executar cliente MCP
docker-compose exec mcp-server python client_vector.py mcp_vector_server.py
```

## 🔍 Entendendo o Comportamento

### Por que o servidor "para"?

**Resposta:** O servidor MCP **NÃO para** - ele fica aguardando conexões via stdio (standard input/output).

Quando você vê:
```
[SERVER_LOG] Starting MCP server...
```

Isso significa que o servidor está **funcionando corretamente** e aguardando que um cliente se conecte.

### Como testar se está funcionando?

1. **Deixe o servidor rodando** em um terminal
2. **Abra outro terminal** e execute o cliente
3. O cliente se conectará ao servidor e executará as buscas

## 🐛 Solução de Problemas

### Erro: "service 'mcp-server' is not running"

**Solução:**
```bash
./docker-run.sh start
```

### Erro: "faiss.index missing"

**Solução:**
```bash
docker-compose exec mcp-server python generate_vector_db.py
```

### Aviso: "version is obsolete"

Isso é apenas um aviso - o Docker Compose funciona normalmente. Para remover o aviso, você pode editar `docker-compose.yml` e remover a linha `version: '3.8'`.

### Container não inicia

```bash
# Ver logs de erro
docker-compose logs mcp-server

# Reconstruir a imagem
./docker-run.sh build
./docker-run.sh start
```

## 📚 Arquitetura do Sistema

```
┌─────────────────────────────────────┐
│     Docker Container                │
│  (oss-chatbot-mcp)                  │
├─────────────────────────────────────┤
│                                     │
│  📁 /app                            │
│  ├── mcp_vector_server.py          │
│  │   └── Servidor MCP (stdio)      │
│  │                                  │
│  ├── client_vector.py               │
│  │   └── Cliente de teste          │
│  │                                  │
│  ├── generate_vector_db.py          │
│  │   └── Gera índice FAISS         │
│  │                                  │
│  └── faiss_index/                   │
│      ├── faiss.index                │
│      ├── embeddings.npy             │
│      └── texts.json                 │
│                                     │
└─────────────────────────────────────┘
```

## 🎯 Fluxo de Trabalho Completo

```bash
# 1. Preparar ambiente
./docker-run.sh build
./docker-run.sh start

# 2. Gerar banco de dados vetorial
docker-compose exec mcp-server python generate_vector_db.py

# 3. Testar com cliente
./docker-run.sh run-client

# 4. Quando terminar
./docker-run.sh stop
```

## 💡 Dicas

- O volume Docker (`-v .:/app`) sincroniza automaticamente os arquivos entre o host e o container
- Você pode editar os arquivos no seu Mac e eles serão refletidos imediatamente no container
- O banco de dados vetorial (`faiss_index/`) é criado dentro do container mas fica disponível no host
- Use `./docker-run.sh shell` para explorar o container interativamente

## 🔗 Próximos Passos

1. Modifique `knowledge_base.json` com seus próprios dados
2. Regenere o banco de dados vetorial
3. Teste buscas personalizadas
4. Integre com Claude Desktop ou outros clientes MCP

Para mais detalhes, consulte o [README.md](README.md) completo.
