MCP 服务器

MCP RAG

A complete MCP server for Retrieval-Augmented Generation with file management and vector memory for agents. Supports multiple document formats (PDF, DOCX, TXT, MD, CSV, JSON) with semantic search using Hugging Face embeddings and ChromaDB for efficient vector storage.

README

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