MCP RAG

Um servidor MCP (Model Context Protocol) completo para RAG (Retrieval-Augmented Generation) com gerenciamento de arquivos e memória vetorial para agentes.

🚀 Características

📄 Gerenciamento de Arquivos: Adicione, remova e pesquise documentos em diversos formatos (PDF, DOCX, TXT, MD, CSV, JSON)
🧠 Memória Vetorial: Sistema separado para que agentes armazenem informações importantes para uso futuro
🔍 Busca Semântica: Utiliza embeddings do Hugging Face para busca semântica avançada
💾 Banco Vetorial Local: ChromaDB local para armazenamento eficiente de vetores e metadados
🛠️ Script de Manutenção: CLI completo para gerenciamento e manutenção do sistema
📚 Documentação Completa: HTML para GitHub Pages com guias de configuração

📋 Pré-requisitos

Node.js 18+
npm ou yarn
Chave da API do Hugging Face

🛠️ Instalação

Clone o repositório

git clone https://github.com/seu-usuario/mcp-rag.git
cd mcp-rag

Instale as dependências
```
npm install
```
Configure as variáveis de ambiente
```
cp .env.example .env
```
Edite o arquivo .env e configure sua chave da API do Hugging Face:
```
HUGGINGFACE_API_KEY=sua_chave_aqui
```
Compile o projeto
```
npm run build
```

🔧 Configuração

Cursor

Adicione a seguinte configuração no arquivo de configurações do MCP:

{
  "mcpServers": {
    "mcp-rag": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/caminho/para/mcp-rag"
    }
  }
}

Claude Desktop

Adicione a configuração no arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-rag": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/caminho/para/mcp-rag"
    }
  }
}

VS Code

Configure no settings.json:

{
  "mcp.servers": {
    "mcp-rag": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/caminho/para/mcp-rag"
    }
  }
}

🛠️ Script de Manutenção

O projeto inclui um CLI completo para manutenção:

# Adicionar arquivo
npm run maintenance add-file /caminho/para/arquivo.pdf

# Adicionar diretório
npm run maintenance add-dir /caminho/para/diretorio

# Buscar arquivos
npm run maintenance search-files "sua consulta"

# Listar arquivos
npm run maintenance list-files

# Gerenciar memória
npm run maintenance add-memory "conteúdo" "agent-id" "session-id"
npm run maintenance search-memory "sua consulta"

# Ver estatísticas
npm run maintenance stats

# Limpar dados
npm run maintenance clear all

🔍 Ferramentas MCP Disponíveis

Gerenciamento de Arquivos

add_file: Adiciona um arquivo ao sistema RAG
search_files: Busca documentos relevantes
remove_file: Remove um arquivo do sistema
list_files: Lista todos os arquivos no sistema

Gerenciamento de Memória

add_memory: Adiciona informação à memória do agente
search_memory: Busca na memória do agente
remove_memory: Remove uma entrada da memória
get_memory_by_agent: Obtém toda a memória de um agente

Utilitários

get_stats: Obtém estatísticas do sistema
clear_data: Limpa dados do sistema
test_connection: Testa a conexão com o serviço de embeddings

📊 Formatos Suportados

PDF: Documentos PDF com texto extraível
DOCX: Documentos do Microsoft Word
TXT: Arquivos de texto simples
MD: Arquivos Markdown
CSV: Arquivos de dados separados por vírgula
JSON: Arquivos de dados JSON

⚙️ Configurações

Variáveis de Ambiente

# MCP Configuration
MCP_SERVER_NAME=mcp-rag
MCP_SERVER_VERSION=1.0.0

# Hugging Face Configuration
HUGGINGFACE_API_KEY=your_huggingface_api_key_here
HUGGINGFACE_MODEL=sentence-transformers/all-MiniLM-L6-v2

# ChromaDB Configuration
CHROMA_PERSIST_DIRECTORY=./data/chroma
CHROMA_COLLECTION_FILES=rag_files
CHROMA_COLLECTION_MEMORY=agent_memory

# File Processing Configuration
MAX_FILE_SIZE_MB=50
SUPPORTED_EXTENSIONS=.pdf,.docx,.txt,.md,.csv,.json

# Vector Configuration
CHUNK_SIZE=1000
CHUNK_OVERLAP=200
EMBEDDING_DIMENSION=384

# Logging
LOG_LEVEL=info

🚀 Uso

Iniciando o Servidor

npm start

Desenvolvimento

npm run dev

Testes

npm test

📚 Documentação

A documentação completa está disponível em HTML para GitHub Pages em docs/index.html. Ela inclui:

Guias de instalação e configuração
Instruções para Cursor, Claude Desktop e VS Code
Exemplos de uso
Solução de problemas
Referência completa das ferramentas

🤝 Contribuição

Fork o projeto
Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
Commit suas mudanças (git commit -m 'Add some AmazingFeature')
Push para a branch (git push origin feature/AmazingFeature)
Abra um Pull Request

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🙏 Agradecimentos

Model Context Protocol - Protocolo base
Hugging Face - Serviço de embeddings
ChromaDB - Banco de dados vetorial
Anthropic - Claude e MCP

📞 Suporte

Se você encontrar problemas ou tiver dúvidas:

Verifique a documentação HTML
Abra uma issue
Consulte a seção de solução de problemas na documentação

Desenvolvido com ❤️ para a comunidade de IA