BerryRAG

Um sistema RAG local com integração Playwright MCP para Claude e embeddings OpenAI, utilizando armazenamento local.

Documentação

🍓 BerryRAG: Banco de Dados Vetorial Local com Integração Playwright MCP

Um sistema RAG (Geração Aumentada por Recuperação) local completo que integra web scraping do Playwright MCP com armazenamento em banco de dados vetorial para Claude.

✨ Recursos

Banco de dados vetorial auto-hospedado com custo zero
Integração Playwright MCP para web scraping automatizado
Múltiplos provedores de embeddings (sentence-transformers, OpenAI, fallback)
Processamento inteligente de conteúdo com filtros de qualidade
Formatação de contexto otimizada para Claude
Servidor MCP para integração direta com Claude
Ferramentas de linha de comando para operação manual

🚀 Início Rápido

1. Instalação

git clone https://github.com/berrydev-ai/berry-rag.git
cd berry-rag

# Install dependencies
npm run install-deps

# Setup directories and instructions
npm run setup

2. Configure o Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "berry-rag": {
      "command": "node",
      "args": ["mcp_servers/vector_db_server.js"],
      "cwd": "/Users/eberry/BerryDev/berry-rag"
    }
  }
}

3. Comece a Usar

# Example workflow:
# 1. Scrape with Playwright MCP through Claude
# 2. Process into vector DB
npm run process-scraped

# 3. Search your knowledge base
npm run search "React hooks"

📁 Estrutura do Projeto

berry-rag/
├── src/                          # Python source code
│   ├── rag_system.py            # Core vector database system
│   └── playwright_integration.py # Playwright MCP integration
├── mcp_servers/                  # MCP server implementations
│   └── vector_db_server.ts      # TypeScript MCP server
├── storage/                      # Vector database storage
│   ├── documents.db             # SQLite metadata
│   └── vectors/                 # NumPy embedding files
├── scraped_content/             # Playwright saves content here
└── dist/                        # Compiled TypeScript

🔧 Comandos

Interface Web Streamlit

Inicie a interface web para interação fácil com seu sistema RAG:

# Start the Streamlit web interface
python run_streamlit.py

# Or directly with streamlit
streamlit run streamlit_app.py

A interface web fornece:

🔍 Pesquisa: Pesquisa interativa de documentos com controles de similaridade
📄 Contexto: Gere contexto formatado para assistentes de IA
➕ Adicionar Documento: Envie arquivos ou cole conteúdo diretamente
📚 Listar Documentos: Navegue pela sua biblioteca de documentos
📊 Estatísticas: Métricas de saúde e desempenho do sistema

Scripts NPM

Comando	Descrição
`npm run install-deps`	Instalar todas as dependências
`npm run setup`	Inicializar diretórios e instruções
`npm run build`	Compilar servidor MCP TypeScript
`npm run process-scraped`	Processar arquivos raspados no banco vetorial
`npm run search`	Pesquisar na base de conhecimento
`npm run list-docs`	Listar todos os documentos

CLI Python

# RAG System Operations
python src/rag_system.py search "query"
python src/rag_system.py context "query"  # Claude-formatted
python src/rag_system.py add <url> <title> <file>
python src/rag_system.py list
python src/rag_system.py stats

# Playwright Integration
python src/playwright_integration.py process
python src/playwright_integration.py setup
python src/playwright_integration.py stats

🤖 Uso com Claude

1. Raspagem de Documentação

"Use Playwright to scrape the React hooks documentation from https://react.dev/reference/react and save it to the scraped_content directory"

2. Processamento no Banco de Dados Vetorial

"Process all new scraped files and add them to the BerryRAG vector database"

3. Consultando a Base de Conhecimento

"Search the BerryRAG database for information about React useState best practices"

"Get context from the vector database about implementing custom hooks"

🔌 Ferramentas MCP Disponíveis para Claude

BerryRAG fornece dois servidores MCP poderosos para integração com Claude:

Ferramentas do Servidor Vector DB

add_document - Adicionar conteúdo diretamente ao banco de dados vetorial
search_documents - Pesquisar conteúdo semelhante
get_context - Obter contexto formatado para consultas
list_documents - Listar todos os documentos armazenados
get_stats - Estatísticas do banco de dados vetorial
process_scraped_files - Processar conteúdo raspado pelo Playwright
save_scraped_content - Salvar conteúdo para processamento posterior

Ferramentas do Servidor BerryExa

crawl_content - Extração avançada de conteúdo web com suporte a subpáginas
extract_links - Extrair links internos para descoberta de subpáginas
get_content_preview - Visualização rápida de conteúdo sem processamento completo

📖 Para guia completo de configuração e uso do MCP, veja BERRY_MCP.md

🧠 Provedores de Embeddings

O sistema suporta múltiplos provedores de embeddings com fallback automático:

sentence-transformers (recomendado, gratuito, local)
OpenAI embeddings (requer chave de API, defina OPENAI_API_KEY)
Baseado em hash simples (fallback, não recomendado para produção)

⚙️ Configuração

Variáveis de Ambiente

# Optional: for OpenAI embeddings
export OPENAI_API_KEY=your_key_here

Filtros de Qualidade de Conteúdo

O sistema filtra automaticamente:

Conteúdo com menos de 100 caracteres
Conteúdo apenas de navegação
Conteúdo repetitivo/duplicado
Arquivos maiores que 500KB

Estratégia de Fragmentação

Tamanho padrão do fragmento: 500 caracteres
Sobreposição: 50 caracteres
Detecção inteligente de limites (frases, parágrafos)

📊 Monitoramento

Verificar Status do Sistema

# Vector database statistics
python src/rag_system.py stats

# Processing status
python src/playwright_integration.py stats

# View recent documents
python src/rag_system.py list

Informações de Armazenamento

Banco de dados: storage/documents.db (metadados SQLite)
Vetores: storage/vectors/ (arrays NumPy)
Conteúdo raspado: scraped_content/ (arquivos Markdown)

🔍 Exemplos de Fluxos de Trabalho

Pesquisa Acadêmica

Raspe artigos de pesquisa com Playwright
Processe no banco de dados vetorial
Consulte conceitos específicos em todos os artigos

Gerenciamento de Documentação

Raspe documentação de API de múltiplas fontes
Construa uma base de conhecimento unificada e pesquisável
Obtenha respostas contextuais sobre detalhes de implementação

Agregação de Conteúdo

Raspe postagens de blog e artigos
Crie clusters de conhecimento baseados em tópicos
Encontre conteúdo relacionado entre fontes

🛠️ Desenvolvimento

Construindo o Servidor MCP

npm run build

Executando em Modo de Desenvolvimento

npm run dev  # TypeScript watch mode

Testes

# Test RAG system
python src/rag_system.py stats

# Test integration
python src/playwright_integration.py setup

# Test MCP server
node mcp_servers/vector_db_server.js

🚨 Solução de Problemas

Problemas Comuns

Dependências Python ausentes:

pip install -r requirements.txt

Erros de compilação TypeScript:

npm install
npm run build

Download do modelo de embeddings lento: A primeira execução baixa o modelo sentence-transformers (~90MB). Isso é normal.

Nenhum resultado da pesquisa:

Verifique se os documentos foram processados: python src/rag_system.py list
Verifique se os filtros de qualidade de conteúdo não estão muito rígidos
Tente termos de pesquisa mais amplos

Logs e Depuração

Logs Python: Verifique a saída do console
Logs do servidor MCP: Saída de stderr
Status de processamento: scraped_content/.processed_files.json

📝 Licença

Licença MIT - sinta-se à vontade para modificar e estender conforme suas necessidades.

🤝 Contribuição

Este é um projeto pessoal de Eric Berry, mas sinta-se à vontade para fazer fork e adaptar para seus próprios casos de uso.

Feliz raspagem e pesquisa! 🕷️🔍✨