<div align="center">

MCP RAG Server

Servidor MCP para RAG com Embeddings Vetoriais e Chunking Inteligente

<br/>

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

Funcionalidades | Screenshots | Instalacao | Uso | 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

Qdrant Dashboard — Busca Semantica

</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)

# 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

# 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

# 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

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

# 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

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

---

CI/CD

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 para detalhes.

---

<div align="center">

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

</div>