<div align="center">

# MCP RAG Server

### Servidor MCP para RAG com Embeddings Vetoriais e Chunking Inteligente

[![CI](https://github.com/amaralphp/mcp-rag-server/actions/workflows/ci.yml/badge.svg)](https://github.com/amaralphp/mcp-rag-server/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.104%2B-009688?style=for-the-badge&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
[![Qdrant](https://img.shields.io/badge/Qdrant-Vector--DB-FF6B35?style=for-the-badge&logo=qdrant&logoColor=white)](https://qdrant.tech/)
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://www.docker.com/)
[![License](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](LICENSE)

<br/>

**Servidor MCP completo para Retrieval Augmented Generation — embeddings vetoriais, chunking inteligente e busca semantica.**

[Funcionalidades](#funcionalidades) | [Screenshots](#screenshots) | [Instalacao](#instalacao) | [Uso](#uso) | [API](#api)

</div>

---

## Stack Tecnologica

<div align="center">

| Tecnologia | Versao | Uso |
|:----------:|:------:|:---:|
| <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/python/python-original.svg" width="40" height="40"/> | 3.11+ | Backend async |
| <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/fastapi/fastapi-original.svg" width="40" height="40"/> | 0.104+ | API REST |
| <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/docker/docker-original.svg" width="40" height="40"/> | 24+ | Containerizacao |

</div>

---

## Screenshots

<div align="center">

> **Swagger UI — Endpoints da API**

![Swagger](https://placehold.co/900x500/0f172a/38bdf8?text=Swagger+UI+-+API+REST)

> **Qdrant Dashboard — Busca Semantica**

![Qdrant](https://placehold.co/900x500/0f172a/f472b6?text=Qdrant+Dashboard+-+Vetores)

</div>

> **Nota:** Substitua as imagens por screenshots reais do servidor.

---

## Funcionalidades

<table>
<tr>
<td width="50%">

### Tools MCP
- `ingest_document` — Ingerir documento
- `rag_query` — Busca semantica
- `list_documents` — Listar docs
- `delete_document` — Remover doc
- `health_check` — Status

</td>
<td width="50%">

### Recursos
- **Chunking** inteligente (paragrafos, sentencas)
- **Embeddings** locais ou OpenAI
- **Cache** de embeddings
- **CLI** para testes rapidos
- **API REST** complementar

</td>
</tr>
</table>

### Providers de Embedding

| Provider | Modelo | Dimensoes | Custo |
|----------|--------|:---------:|:-----:|
| **Local** | all-MiniLM-L6-v2 | 384 | Gratuito |
| **OpenAI** | text-embedding-3-small | 1536 | Pago |

---

## Instalacao

### Pre-requisitos

| Requisito | Versao Minima | Como verificar |
|-----------|:-------------:|----------------|
| Python | 3.11+ | `python --version` |
| Docker | 24+ | `docker --version` |

### Opcao 1 — Docker (Recomendado)

```bash
# Clonar
git clone https://github.com/amaralphp/mcp-rag-server.git
cd mcp-rag-server

# Configurar
cp .env.example .env

# Iniciar (Qdrant + Server)
docker compose up -d

# Acessar
# API:     http://localhost:8000
# Swagger: http://localhost:8000/docs
# Qdrant:  http://localhost:6333/dashboard
```

### Opcao 2 — Instalacao Manual

```bash
# Clonar
git clone https://github.com/amaralphp/mcp-rag-server.git
cd mcp-rag-server

# Ambiente virtual
python -m venv venv
source venv/bin/activate  # Linux/Mac
.\venv\Scripts\Activate.ps1  # Windows

# Dependencias
pip install -e .

# Qdrant (Docker separado)
docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant

# Iniciar servidor MCP
python -m src.mcp_server

# OU API REST
uvicorn src.api.main:app --reload --port 8000
```

---

## Variaveis de Ambiente

| Variavel | Padrao | Descricao |
|----------|--------|-----------|
| `EMBEDDING_PROVIDER` | `local` | `local` ou `openai` |
| `OPENAI_API_KEY` | — | Chave OpenAI (se usar) |
| `QDRANT_HOST` | `localhost` | Host do Qdrant |
| `QDRANT_PORT` | `6333` | Porta HTTP Qdrant |
| `DEFAULT_CHUNK_SIZE` | `500` | Tamanho do chunk |
| `DEFAULT_CHUNK_OVERLAP` | `50` | Overlap entre chunks |

---

## Uso

### Via MCP

```python
# Ingerir documento
result = await ingest(
    content="Texto do documento...",
    source="arquivo.md",
    chunk_size=500
)

# Buscar contexto
result = await query(
    query="Qual e a pergunta?",
    top_k=5
)
```

### Via CLI

```bash
mcp-rag ingest --file documento.md
mcp-rag query "minha pergunta"
mcp-rag list
mcp-rag delete <doc_id>
mcp-rag health
```

### Via API REST

```bash
# Ingerir
curl -X POST http://localhost:8000/ingest \
  -H "Content-Type: application/json" \
  -d '{"content": "Texto...", "source": "doc.md"}'

# Buscar
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "minha pergunta", "top_k": 5}'
```

---

## API

| Metodo | Endpoint | Descricao |
|:------:|----------|-----------|
| `POST` | `/ingest` | Ingerir documento |
| `POST` | `/query` | Busca semantica |
| `GET` | `/documents` | Listar documentos |
| `DELETE` | `/documents/{id}` | Remover documento |
| `GET` | `/health` | Health check |

---

## Estrutura do Projeto

```
mcp-rag-server/
├── src/
│   ├── mcp_server.py
│   ├── cli.py
│   ├── tools/
│   ├── chunking/
│   ├── embeddings/
│   ├── vectorstore/
│   └── api/
│       ├── main.py
│       ├── routes/
│       └── schemas.py
├── tests/
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── pyproject.toml
├── .env.example
├── .github/workflows/ci.yml
├── LICENSE
└── README.md
```

---

## Testes

```bash
pytest -v
pytest --cov=src --cov-report=html
```

---

## CI/CD

```mermaid
flowchart LR
    A[Push/PR] --> B[Ruff Lint]
    B --> C[MyPy]
    C --> D[Pytest]
    D --> E[Docker Build]
    E --> F{Branch main?}
    F -->|Sim| G[Push Image]
    F -->|Nao| H[Pronto]
```

---

## Roadmap

- [ ] Hugging Face embeddings
- [ ] Cohere embeddings
- [ ] Reranking de resultados
- [ ] Suporte a PDF/DOCX
- [ ] Dashboard de metricas

---

## Contribuindo

1. Fork o repositorio
2. Crie uma branch (`git checkout -b feature/minha-feature`)
3. Commit (`git commit -m 'feat: novo provider'`)
4. Push (`git push origin feature/minha-feature`)
5. Abra um Pull Request

---

## Licenca

Este projeto esta licenciado sob a **MIT License**.

Veja o arquivo [LICENSE](LICENSE) para detalhes.

---

<div align="center">

Feito com :heart: para a comunidade de AI/ML

</div>