MCP RAG

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

Caractersticas

• ** Gerenciamento de Arquivos**: Adicione, remova e pesquise documentos em diversos formatos (PDF, DOCX, TXT, MD, CSV, JSON)
• ** Memria Vetorial**: Sistema separado para que agentes armazenem informaes importantes para uso futuro
• ** Busca Semntica**: Utiliza embeddings do Hugging Face para busca semntica avanada
• ** Banco Vetorial Local**: ChromaDB local para armazenamento eficiente de vetores e metadados
• ** Script de Manuteno**: CLI completo para gerenciamento e manuteno do sistema
• ** Documentao Completa**: HTML para GitHub Pages com guias de configurao

Pr-requisitos

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

Instalao

1. Clone o repositrio

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

2. Instale as dependncias

   npm install
   

3. Configure as variveis 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
   

4. Compile o projeto

   npm run build
   

Configurao

Cursor

Adicione a seguinte configurao no arquivo de configuraes do MCP:

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

Claude Desktop

Adicione a configurao 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 Manuteno

O projeto inclui um CLI completo para manuteno:

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

# Adicionar diretrio
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 memria
npm run maintenance add-memory "contedo" "agent-id" "session-id"
npm run maintenance search-memory "sua consulta"

# Ver estatsticas
npm run maintenance stats

# Limpar dados
npm run maintenance clear all

Ferramentas MCP Disponveis

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 Memria

• add_memory: Adiciona informao memria do agente
• search_memory: Busca na memria do agente
• remove_memory: Remove uma entrada da memria
• get_memory_by_agent: Obtm toda a memria de um agente

Utilitrios

• get_stats: Obtm estatsticas do sistema
• clear_data: Limpa dados do sistema
• test_connection: Testa a conexo com o servio de embeddings

Formatos Suportados

• PDF: Documentos PDF com texto extravel
• DOCX: Documentos do Microsoft Word
• TXT: Arquivos de texto simples
• MD: Arquivos Markdown
• CSV: Arquivos de dados separados por vrgula
• JSON: Arquivos de dados JSON

Configuraes

Variveis 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

Documentao

A documentao completa est disponvel em HTML para GitHub Pages em docs/index.html. Ela inclui:

• Guias de instalao e configurao
• Instrues para Cursor, Claude Desktop e VS Code
• Exemplos de uso
• Soluo de problemas
• Referncia completa das ferramentas

Contribuio

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanas (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

Licena

Este projeto est licenciado sob a Licena MIT - veja o arquivo LICENSE para detalhes.

Agradecimentos

• Model Context Protocol - Protocolo base
• Hugging Face - Servio de embeddings
• ChromaDB - Banco de dados vetorial
• Anthropic - Claude e MCP

Suporte

Se voc encontrar problemas ou tiver dvidas:

1. Verifique a documentao HTML
2. Abra uma issue
3. Consulte a seo de soluo de problemas na documentao

Desenvolvido com para a comunidade de IA