index.html•19.9 kB
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>MCP RAG - Documentação</title>
<style>
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
line-height: 1.6;
color: #333;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
min-height: 100vh;
}
.container {
max-width: 1200px;
margin: 0 auto;
padding: 20px;
}
.header {
background: rgba(255, 255, 255, 0.95);
backdrop-filter: blur(10px);
border-radius: 20px;
padding: 40px;
margin-bottom: 30px;
text-align: center;
box-shadow: 0 20px 40px rgba(0, 0, 0, 0.1);
}
.header h1 {
font-size: 3rem;
color: #2c3e50;
margin-bottom: 10px;
background: linear-gradient(135deg, #667eea, #764ba2);
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
background-clip: text;
}
.header p {
font-size: 1.2rem;
color: #666;
max-width: 600px;
margin: 0 auto;
}
.content {
background: rgba(255, 255, 255, 0.95);
backdrop-filter: blur(10px);
border-radius: 20px;
padding: 40px;
margin-bottom: 30px;
box-shadow: 0 20px 40px rgba(0, 0, 0, 0.1);
}
.section {
margin-bottom: 40px;
}
.section h2 {
font-size: 2rem;
color: #2c3e50;
margin-bottom: 20px;
border-bottom: 3px solid #667eea;
padding-bottom: 10px;
}
.section h3 {
font-size: 1.5rem;
color: #34495e;
margin: 30px 0 15px 0;
}
.section h4 {
font-size: 1.2rem;
color: #34495e;
margin: 20px 0 10px 0;
}
.feature-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
gap: 20px;
margin: 20px 0;
}
.feature-card {
background: #f8f9fa;
border-radius: 15px;
padding: 25px;
border-left: 5px solid #667eea;
transition: transform 0.3s ease, box-shadow 0.3s ease;
}
.feature-card:hover {
transform: translateY(-5px);
box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
}
.feature-card h4 {
color: #2c3e50;
margin-bottom: 10px;
}
.code-block {
background: #2c3e50;
color: #ecf0f1;
padding: 20px;
border-radius: 10px;
font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
font-size: 0.9rem;
overflow-x: auto;
margin: 15px 0;
position: relative;
}
.code-block::before {
content: attr(data-lang);
position: absolute;
top: 10px;
right: 15px;
background: #34495e;
color: #ecf0f1;
padding: 2px 8px;
border-radius: 4px;
font-size: 0.7rem;
text-transform: uppercase;
}
.inline-code {
background: #e8f4f8;
color: #2c3e50;
padding: 2px 6px;
border-radius: 4px;
font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
font-size: 0.9rem;
}
.tool-list {
background: #f8f9fa;
border-radius: 10px;
padding: 20px;
margin: 15px 0;
}
.tool-item {
background: white;
border-radius: 8px;
padding: 15px;
margin: 10px 0;
border-left: 4px solid #667eea;
}
.tool-item h5 {
color: #2c3e50;
margin-bottom: 5px;
}
.tool-item p {
color: #666;
font-size: 0.9rem;
}
.warning {
background: #fff3cd;
border: 1px solid #ffeaa7;
border-radius: 10px;
padding: 15px;
margin: 15px 0;
border-left: 5px solid #f39c12;
}
.info {
background: #d1ecf1;
border: 1px solid #bee5eb;
border-radius: 10px;
padding: 15px;
margin: 15px 0;
border-left: 5px solid #17a2b8;
}
.success {
background: #d4edda;
border: 1px solid #c3e6cb;
border-radius: 10px;
padding: 15px;
margin: 15px 0;
border-left: 5px solid #28a745;
}
.step {
background: #f8f9fa;
border-radius: 10px;
padding: 20px;
margin: 15px 0;
border-left: 5px solid #28a745;
}
.step-number {
background: #28a745;
color: white;
width: 30px;
height: 30px;
border-radius: 50%;
display: inline-flex;
align-items: center;
justify-content: center;
font-weight: bold;
margin-right: 15px;
}
.footer {
text-align: center;
color: rgba(255, 255, 255, 0.8);
padding: 20px;
}
.footer a {
color: rgba(255, 255, 255, 0.9);
text-decoration: none;
}
.footer a:hover {
text-decoration: underline;
}
@media (max-width: 768px) {
.header h1 {
font-size: 2rem;
}
.content {
padding: 20px;
}
.feature-grid {
grid-template-columns: 1fr;
}
}
</style>
</head>
<body>
<div class="container">
<div class="header">
<h1>MCP RAG</h1>
<p>Servidor MCP para RAG (Retrieval-Augmented Generation) com gerenciamento de arquivos e memória vetorial para agentes</p>
</div>
<div class="content">
<div class="section">
<h2>🚀 O que é o MCP RAG?</h2>
<p>O MCP RAG é um servidor Model Context Protocol (MCP) que implementa um sistema completo de RAG (Retrieval-Augmented Generation) com as seguintes funcionalidades:</p>
<div class="feature-grid">
<div class="feature-card">
<h4>📄 Gerenciamento de Arquivos</h4>
<p>Adicione, remova e pesquise documentos em diversos formatos (PDF, DOCX, TXT, MD, CSV, JSON)</p>
</div>
<div class="feature-card">
<h4>🧠 Memória Vetorial</h4>
<p>Sistema separado para que agentes armazenem informações importantes para uso futuro</p>
</div>
<div class="feature-card">
<h4>🔍 Busca Semântica</h4>
<p>Utiliza embeddings do Hugging Face para busca semântica avançada</p>
</div>
<div class="feature-card">
<h4>💾 Banco Vetorial Local</h4>
<p>ChromaDB local para armazenamento eficiente de vetores e metadados</p>
</div>
</div>
</div>
<div class="section">
<h2>🛠️ Instalação e Configuração</h2>
<div class="step">
<span class="step-number">1</span>
<strong>Clone o repositório</strong>
<div class="code-block" data-lang="bash">
git clone https://github.com/seu-usuario/mcp-rag.git
cd mcp-rag
</div>
</div>
<div class="step">
<span class="step-number">2</span>
<strong>Instale as dependências</strong>
<div class="code-block" data-lang="bash">
npm install
</div>
</div>
<div class="step">
<span class="step-number">3</span>
<strong>Configure as variáveis de ambiente</strong>
<div class="code-block" data-lang="bash">
cp .env.example .env
</div>
<p>Edite o arquivo <span class="inline-code">.env</span> e configure:</p>
<div class="code-block" data-lang="env">
# Chave da API do Hugging Face (obrigatória)
HUGGINGFACE_API_KEY=sua_chave_aqui
# Modelo de embedding (opcional)
HUGGINGFACE_MODEL=sentence-transformers/all-MiniLM-L6-v2
# Configurações do ChromaDB
CHROMA_PERSIST_DIRECTORY=./data/chroma
CHROMA_COLLECTION_FILES=rag_files
CHROMA_COLLECTION_MEMORY=agent_memory
</div>
</div>
<div class="step">
<span class="step-number">4</span>
<strong>Compile o projeto</strong>
<div class="code-block" data-lang="bash">
npm run build
</div>
</div>
<div class="info">
<strong>💡 Dica:</strong> Para obter uma chave da API do Hugging Face, visite <a href="https://huggingface.co/settings/tokens" target="_blank">https://huggingface.co/settings/tokens</a>
</div>
</div>
<div class="section">
<h2>🔧 Configuração no Cursor</h2>
<div class="step">
<span class="step-number">1</span>
<strong>Abra as configurações do Cursor</strong>
<p>Vá para <span class="inline-code">File → Preferences → Settings</span> ou use <span class="inline-code">Ctrl+,</span></p>
</div>
<div class="step">
<span class="step-number">2</span>
<strong>Configure o MCP</strong>
<p>Adicione a seguinte configuração no arquivo de configurações do MCP:</p>
<div class="code-block" data-lang="json">
{
"mcpServers": {
"mcp-rag": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "/caminho/para/mcp-rag"
}
}
}
</div>
</div>
<div class="step">
<span class="step-number">3</span>
<strong>Reinicie o Cursor</strong>
<p>Reinicie o Cursor para carregar a nova configuração do MCP.</p>
</div>
</div>
<div class="section">
<h2>🤖 Configuração no Claude Desktop</h2>
<div class="step">
<span class="step-number">1</span>
<strong>Localize o arquivo de configuração</strong>
<p>O arquivo de configuração do Claude Desktop está localizado em:</p>
<ul>
<li><strong>Windows:</strong> <span class="inline-code">%APPDATA%\Claude\claude_desktop_config.json</span></li>
<li><strong>macOS:</strong> <span class="inline-code">~/Library/Application Support/Claude/claude_desktop_config.json</span></li>
<li><strong>Linux:</strong> <span class="inline-code">~/.config/claude/claude_desktop_config.json</span></li>
</ul>
</div>
<div class="step">
<span class="step-number">2</span>
<strong>Adicione a configuração do MCP</strong>
<div class="code-block" data-lang="json">
{
"mcpServers": {
"mcp-rag": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "/caminho/para/mcp-rag"
}
}
}
</div>
</div>
<div class="step">
<span class="step-number">3</span>
<strong>Reinicie o Claude Desktop</strong>
<p>Feche e reabra o Claude Desktop para carregar a nova configuração.</p>
</div>
</div>
<div class="section">
<h2>⚙️ Configuração no VS Code</h2>
<div class="step">
<span class="step-number">1</span>
<strong>Instale a extensão MCP</strong>
<p>Instale a extensão "Model Context Protocol" no VS Code.</p>
</div>
<div class="step">
<span class="step-number">2</span>
<strong>Configure o servidor MCP</strong>
<p>Adicione a configuração no arquivo <span class="inline-code">settings.json</span>:</p>
<div class="code-block" data-lang="json">
{
"mcp.servers": {
"mcp-rag": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "/caminho/para/mcp-rag"
}
}
}
</div>
</div>
</div>
<div class="section">
<h2>🛠️ Ferramentas Disponíveis</h2>
<div class="tool-list">
<div class="tool-item">
<h5>📄 Gerenciamento de Arquivos</h5>
<p><strong>add_file:</strong> Adiciona um arquivo ao sistema RAG</p>
<p><strong>search_files:</strong> Busca documentos relevantes</p>
<p><strong>remove_file:</strong> Remove um arquivo do sistema</p>
<p><strong>list_files:</strong> Lista todos os arquivos no sistema</p>
</div>
<div class="tool-item">
<h5>🧠 Gerenciamento de Memória</h5>
<p><strong>add_memory:</strong> Adiciona informação à memória do agente</p>
<p><strong>search_memory:</strong> Busca na memória do agente</p>
<p><strong>remove_memory:</strong> Remove uma entrada da memória</p>
<p><strong>get_memory_by_agent:</strong> Obtém toda a memória de um agente</p>
</div>
<div class="tool-item">
<h5>🔧 Utilitários</h5>
<p><strong>get_stats:</strong> Obtém estatísticas do sistema</p>
<p><strong>clear_data:</strong> Limpa dados do sistema</p>
<p><strong>test_connection:</strong> Testa a conexão com o serviço de embeddings</p>
</div>
</div>
</div>
<div class="section">
<h2>📋 Script de Manutenção</h2>
<p>O projeto inclui um script CLI para manutenção e gerenciamento:</p>
<div class="code-block" data-lang="bash">
# Adicionar um arquivo
npm run maintenance add-file /caminho/para/arquivo.pdf
# Adicionar todos os arquivos de um 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
# Adicionar memória
npm run maintenance add-memory "conteúdo" "agent-id" "session-id"
# Buscar memória
npm run maintenance search-memory "sua consulta"
# Ver estatísticas
npm run maintenance stats
# Limpar dados
npm run maintenance clear all
</div>
</div>
<div class="section">
<h2>🔍 Exemplos de Uso</h2>
<div class="step">
<h4>Adicionando um documento</h4>
<div class="code-block" data-lang="bash">
# Via CLI
npm run maintenance add-file ./documentos/manual.pdf
# Via MCP (no Cursor/Claude)
# Use a ferramenta add_file com o caminho do arquivo
</div>
</div>
<div class="step">
<h4>Buscando informações</h4>
<div class="code-block" data-lang="bash">
# Via CLI
npm run maintenance search-files "como configurar o sistema"
# Via MCP
# Use a ferramenta search_files com sua consulta
</div>
</div>
<div class="step">
<h4>Armazenando memória do agente</h4>
<div class="code-block" data-lang="bash">
# Via CLI
npm run maintenance add-memory "O usuário prefere Python para automação" "agent-001" "session-123" "preferences" 8 "python,automation"
# Via MCP
# Use a ferramenta add_memory com os parâmetros apropriados
</div>
</div>
</div>
<div class="section">
<h2>⚠️ Solução de Problemas</h2>
<div class="warning">
<strong>Erro: "HUGGINGFACE_API_KEY is required"</strong>
<p>Certifique-se de que você configurou a chave da API do Hugging Face no arquivo <span class="inline-code">.env</span>.</p>
</div>
<div class="warning">
<strong>Erro: "Rate limit exceeded"</strong>
<p>O Hugging Face tem limites de taxa. Aguarde alguns minutos antes de tentar novamente.</p>
</div>
<div class="warning">
<strong>Erro: "Model is currently loading"</strong>
<p>O modelo está sendo carregado. Aguarde alguns momentos e tente novamente.</p>
</div>
<div class="info">
<strong>💡 Dica:</strong> Use <span class="inline-code">npm run maintenance test-connection</span> para verificar se o serviço de embeddings está funcionando.
</div>
</div>
<div class="section">
<h2>📊 Formatos Suportados</h2>
<ul>
<li><strong>PDF:</strong> Documentos PDF com texto extraível</li>
<li><strong>DOCX:</strong> Documentos do Microsoft Word</li>
<li><strong>TXT:</strong> Arquivos de texto simples</li>
<li><strong>MD:</strong> Arquivos Markdown</li>
<li><strong>CSV:</strong> Arquivos de dados separados por vírgula</li>
<li><strong>JSON:</strong> Arquivos de dados JSON</li>
</ul>
</div>
<div class="section">
<h2>🔧 Configurações Avançadas</h2>
<div class="code-block" data-lang="env">
# Tamanho máximo de arquivo (MB)
MAX_FILE_SIZE_MB=50
# Extensões suportadas
SUPPORTED_EXTENSIONS=.pdf,.docx,.txt,.md,.csv,.json
# Configurações de chunking
CHUNK_SIZE=1000
CHUNK_OVERLAP=200
# Dimensão dos embeddings
EMBEDDING_DIMENSION=384
# Nível de log
LOG_LEVEL=info
</div>
</div>
</div>
<div class="footer">
<p>MCP RAG - Sistema de RAG com MCP para agentes inteligentes</p>
<p>Desenvolvido com ❤️ para a comunidade de IA</p>
</div>
</div>
</body>
</html>