# 🔌 Conectando MCP Server ao Claude Desktop

Este guia explica como configurar e conectar o servidor MCP (Model Context Protocol) de Vector Database ao Claude Desktop.

## 📋 Índice

1. [Pré-requisitos](#pré-requisitos)
2. [Estrutura do Projeto](#estrutura-do-projeto)
3. [Instalação](#instalação)
4. [Gerando o Vector Database](#gerando-o-vector-database)
5. [Configurando o Claude Desktop](#configurando-o-claude-desktop)
6. [Testando a Conexão](#testando-a-conexão)
7. [Usando as Ferramentas](#usando-as-ferramentas)
8. [Troubleshooting](#troubleshooting)

---

## 🔧 Pré-requisitos

- **macOS** (ou Linux/Windows com adaptações)
- **Python 3.10+** instalado
- **Claude Desktop App** instalado ([download](https://claude.ai/download))
- Ambiente virtual Python (recomendado)

---

## 📁 Estrutura do Projeto

```
MCP + Claude Desktop/
├── mcp_vector_server.py    # Servidor MCP principal
├── generate_vector_db.py   # Script para gerar o índice FAISS (lê PDFs)
├── search_vector_db.py     # Script de busca standalone
├── client_vector.py        # Cliente de teste
├── requirements.txt        # Dependências Python
├── data/                   # Todos os dados do projeto
│   ├── PDF/                # Coloque seus PDFs aqui
│   │   └── *.pdf           # Serão processados automaticamente
│   ├── knowledge_base.json # Texto extraído (gerado)
│   └── faiss_index/        # Índice FAISS gerado
│       ├── faiss.index
│       ├── texts.json
│       └── embeddings.npy
```

---

## ⚙️ Instalação

### 1. Clone ou navegue até o diretório do projeto

```bash
cd /caminho/para/seu/projeto/MCP\ +\ Claude\ Desktop
```

### 2. Crie e ative um ambiente virtual

```bash
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# ou
.venv\\Scripts\\activate     # Windows
```

### 3. Instale as dependências

```bash
pip install -r requirements.txt
```

**Conteúdo do `requirements.txt`:**
```
mcp>=0.1.0
fastmcp>=0.1.0
faiss-cpu>=1.7.4
sentence-transformers>=2.2.0
numpy>=1.24.0
PyPDF2>=3.0.0
```

---

## 🗄️ Gerando o Vector Database

### 1. Adicione seus PDFs na pasta data/PDF/

```bash
# Crie a estrutura de pastas se não existir
mkdir -p data/PDF

# Copie seus PDFs para a pasta
cp /caminho/para/seus/documentos/*.pdf data/PDF/
```

**Estrutura esperada:**
```
data/PDF/
├── documento1.pdf
├── documento2.pdf
└── ...
```

### 2. Execute o script de geração

```bash
python generate_vector_db.py
```

**Saída esperada:**
```
============================================================
🚀 FAISS Vector DB Generator from PDFs
============================================================
📂 Found 1 PDF file(s) in: /path/to/data/PDF
📄 Processing: CTW-2019-PCS-00043-book-of-delivery.pdf
   ✓ Extracted 27 chunks

💾 Knowledge base saved to: data/knowledge_base.json

📚 27 knowledge chunks to index.
⚙️ Generating embeddings with model: all-MiniLM-L6-v2

✅ FAISS vector DB created successfully!
📁 Location: data/faiss_index
📦 Entries: 27 | Dimensions: 384
============================================================
```

Isso criará o diretório `data/faiss_index/` com:
- `faiss.index` - Índice FAISS para busca vetorial
- `texts.json` - Textos originais com metadados da fonte
- `embeddings.npy` - Embeddings gerados

---

## 🖥️ Configurando o Claude Desktop

### 1. Localize o arquivo de configuração

**macOS:**
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```

**Linux:**
```
~/.config/Claude/claude_desktop_config.json
```

### 2. Edite o arquivo de configuração

Abra o arquivo (crie se não existir) e adicione a configuração do servidor MCP:

```json
{
  "mcpServers": {
    "vector-db": {
      "command": "/CAMINHO/ABSOLUTO/PARA/SEU/.venv/bin/python3",
      "args": ["/CAMINHO/ABSOLUTO/PARA/SEU/MCP/mcp_vector_server.py"],
      "env": {
        "PYTHONPATH": "/CAMINHO/ABSOLUTO/PARA/SEU/MCP"
      }
    }
  }
}
```

### ⚠️ IMPORTANTE: Use caminhos absolutos!

**Exemplo real (macOS):**
```json
{
  "mcpServers": {
    "vector-db": {
      "command": "/Users/seuusuario/projeto/.venv/bin/python3",
      "args": ["/Users/seuusuario/projeto/MCP/mcp_vector_server.py"],
      "env": {
        "PYTHONPATH": "/Users/seuusuario/projeto/MCP"
      }
    }
  }
}
```

### 3. Reinicie o Claude Desktop

> ⚡ **CRÍTICO:** Após editar a configuração, você DEVE reiniciar completamente o Claude Desktop:

1. Feche o Claude Desktop completamente (Cmd+Q no macOS)
2. Abra novamente o Claude Desktop
3. O servidor MCP será carregado automaticamente

---

## ✅ Testando a Conexão

### Verificar nos logs

Você pode verificar se o servidor foi carregado corretamente:

```bash
cat ~/Library/Logs/Claude/mcp-server-vector-db.log
```

Procure por:
```
[SERVER_LOG] Server loading...
[SERVER_LOG] Loading SentenceTransformer model...
[SERVER_LOG] Model loaded successfully!
[SERVER_LOG] Starting MCP server...
```

### Teste via cliente Python

```bash
python client_vector.py mcp_vector_server.py
```

Saída esperada:
```
🛠 Tools detected: ['create_vector_db', 'search_vector_db']
📌 RAW RESPONSE FROM SERVER:
1) score=0.7131
Seu texto mais relevante aqui...
```

---

## 🔍 Usando as Ferramentas

Após configurar, você pode usar as ferramentas diretamente no Claude Desktop.

### Ferramenta 1: `search_vector_db`

Busca semântica no banco de dados vetorial.

**Como usar no Claude Desktop:**
```
Busque "sua query aqui" usando search_vector_db com 
index_dir='/CAMINHO/ABSOLUTO/PARA/data/faiss_index'
```

**Parâmetros:**
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `query` | string | Texto para buscar |
| `index_dir` | string | Caminho absoluto para o diretório do índice FAISS |
| `top_k` | int | Número de resultados (padrão: 5) |

### Ferramenta 2: `create_vector_db`

Cria um novo banco de dados vetorial a partir de um JSON.

**Como usar no Claude Desktop:**
```
Crie um vector database a partir de '/caminho/para/knowledge.json' 
no diretório '/caminho/para/output'
```

**Parâmetros:**
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `json_path` | string | Caminho para o arquivo JSON com os textos |
| `output_dir` | string | Diretório onde salvar o índice |

---

## 🛠️ Troubleshooting

### Problema: "No result received from client-side tool execution"

**Causas possíveis:**
1. O servidor MCP não está rodando
2. Caminho incorreto no `index_dir`
3. Erro no servidor (ver logs)

**Solução:**
1. Verifique os logs: `cat ~/Library/Logs/Claude/mcp-server-vector-db.log`
2. Reinicie o Claude Desktop
3. Use caminhos absolutos completos

---

### Problema: "BrokenPipeError"

**Causa:** Claude Desktop fechou a conexão antes do servidor responder.

**Solução:** A versão atual do servidor já trata esse erro. Se persistir:
1. Verifique se o modelo SentenceTransformer está sendo carregado corretamente
2. Aguarde alguns segundos após abrir o Claude Desktop antes de usar as ferramentas

---

### Problema: "Server not found" ou ferramentas não aparecem

**Soluções:**
1. Verifique se o caminho do Python está correto:
   ```bash
   which python3  # Use este caminho no config
   ```
2. Verifique se o caminho do script está correto:
   ```bash
   ls -la /seu/caminho/mcp_vector_server.py
   ```
3. Reinicie completamente o Claude Desktop (Cmd+Q e abra novamente)

---

### Problema: "faiss.index missing" ou "texts.json missing"

**Causa:** O índice FAISS não foi gerado ou o caminho está errado.

**Solução:**
1. Gere o índice:
   ```bash
   python generate_vector_db.py
   ```
2. Verifique se os arquivos existem:
   ```bash
   ls -la faiss_index/
   ```
3. Use o caminho absoluto correto no Claude Desktop

---

## 📊 Verificando Logs

Para debug avançado, monitore os logs em tempo real:

```bash
# Log específico do vector-db
tail -f ~/Library/Logs/Claude/mcp-server-vector-db.log

# Todos os logs MCP
tail -f ~/Library/Logs/Claude/mcp.log
```

---

## 🔗 Referências

- [MCP Documentation](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/download)
- [FAISS Documentation](https://github.com/facebookresearch/faiss)
- [Sentence Transformers](https://www.sbert.net/)

---

## 📝 Exemplo Completo

### 1. Estrutura de diretórios
```
/Users/seuusuario/projeto/
├── .venv/
│   └── bin/python3
└── MCP + Claude Desktop/
    ├── mcp_vector_server.py
    └── data/
        ├── PDF/
        │   └── seus-pdfs.pdf
        ├── knowledge_base.json
        └── faiss_index/
```

### 2. Configuração Claude Desktop
```json
{
  "mcpServers": {
    "vector-db": {
      "command": "/Users/seuusuario/projeto/.venv/bin/python3",
      "args": ["/Users/seuusuario/projeto/MCP + Claude Desktop/mcp_vector_server.py"],
      "env": {
        "PYTHONPATH": "/Users/seuusuario/projeto/MCP + Claude Desktop"
      }
    }
  }
}
```

### 3. Prompt no Claude Desktop
```
Busque "quality principles" usando search_vector_db com 
index_dir='/Users/seuusuario/projeto/MCP + Claude Desktop/data/faiss_index' e top_k=3
```

### 4. Resultado esperado
```
1) score=0.5410
[Source: CTW-2019-PCS-00043-book-of-delivery.pdf]
Critical TechWorks Principles...

2) score=0.4262
[Source: CTW-2019-PCS-00043-book-of-delivery.pdf]
Critical TechWorks Quality...

3) score=0.2408
[Source: CTW-2019-PCS-00043-book-of-delivery.pdf]
Critical TechWorks Visibility...
```

---

Any question just let me know
