BerryRAG

Un sistema RAG local con integración de Playwright MCP para Claude y embeddings de OpenAI, utilizando almacenamiento local.

GitHubPrueba este MCPPatrocinado

Documentación

🍓 BerryRAG: Base de datos vectorial local con integración Playwright MCP

Un sistema RAG (Generación Aumentada por Recuperación) local completo que integra el scraping web de Playwright MCP con almacenamiento en base de datos vectorial para Claude.

✨ Características

Base de datos vectorial autohospedada sin coste
Integración Playwright MCP para scraping web automatizado
Múltiples proveedores de embeddings (sentence-transformers, OpenAI, respaldo)
Procesamiento inteligente de contenido con filtros de calidad
Formato de contexto optimizado para Claude
Servidor MCP para integración directa con Claude
Herramientas de línea de comandos para operación manual

🚀 Inicio rápido

1. Instalación

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. Configurar Claude Desktop

Añade a tu 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. Empezar 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"

📁 Estructura del proyecto

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

Interfaz web Streamlit

Lanza la interfaz web para interactuar fácilmente con tu sistema RAG:

# Start the Streamlit web interface
python run_streamlit.py

# Or directly with streamlit
streamlit run streamlit_app.py

La interfaz web proporciona:

🔍 Búsqueda: Búsqueda interactiva de documentos con controles de similitud
📄 Contexto: Genera contexto formateado para asistentes de IA
➕ Añadir documento: Sube archivos o pega contenido directamente
📚 Listar documentos: Explora tu biblioteca de documentos
📊 Estadísticas: Métricas de salud y rendimiento del sistema

Scripts NPM

Comando	Descripción
`npm run install-deps`	Instalar todas las dependencias
`npm run setup`	Inicializar directorios e instrucciones
`npm run build`	Compilar el servidor MCP TypeScript
`npm run process-scraped`	Procesar archivos extraídos en la base de datos vectorial
`npm run search`	Buscar en la base de conocimiento
`npm run list-docs`	Listar todos los documentos

CLI de 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 con Claude

1. Extracción de documentación

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

2. Procesamiento en la base de datos vectorial

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

3. Consulta de la base de conocimiento

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

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

🔌 Herramientas MCP disponibles para Claude

BerryRAG proporciona dos potentes servidores MCP para la integración con Claude:

Herramientas del servidor Vector DB

add_document - Añadir contenido directamente a la base de datos vectorial
search_documents - Buscar contenido similar
get_context - Obtener contexto formateado para consultas
list_documents - Listar todos los documentos almacenados
get_stats - Estadísticas de la base de datos vectorial
process_scraped_files - Procesar contenido extraído con Playwright
save_scraped_content - Guardar contenido para procesamiento posterior

Herramientas del servidor BerryExa

crawl_content - Extracción avanzada de contenido web con soporte de subpáginas
extract_links - Extraer enlaces internos para descubrir subpáginas
get_content_preview - Vista previa rápida de contenido sin procesamiento completo

📖 Para la guía completa de configuración y uso de MCP, consulta BERRY_MCP.md

🧠 Proveedores de embeddings

El sistema admite múltiples proveedores de embeddings con respaldo automático:

sentence-transformers (recomendado, gratuito, local)
Embeddings de OpenAI (requiere clave API, establece OPENAI_API_KEY)
Basado en hash simple (respaldo, no recomendado para producción)

⚙️ Configuración

Variables de entorno

# Optional: for OpenAI embeddings
export OPENAI_API_KEY=your_key_here

Filtros de calidad de contenido

El sistema filtra automáticamente:

Contenido de menos de 100 caracteres
Contenido solo de navegación
Contenido repetitivo/duplicado
Archivos de más de 500KB

Estrategia de fragmentación

Tamaño de fragmento predeterminado: 500 caracteres
Solapamiento: 50 caracteres
Detección inteligente de límites (oraciones, párrafos)

📊 Monitorización

Comprobar el estado del 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

Información de almacenamiento

Base de datos: storage/documents.db (metadatos SQLite)
Vectores: storage/vectors/ (arrays NumPy)
Contenido extraído: scraped_content/ (archivos Markdown)

🔍 Flujos de trabajo de ejemplo

Investigación académica

Extrae artículos de investigación con Playwright
Procesa en la base de datos vectorial
Consulta conceptos específicos en todos los artículos

Gestión de documentación

Extrae documentación de API de múltiples fuentes
Construye una base de conocimiento unificada y buscable
Obtén respuestas contextuales sobre detalles de implementación

Agregación de contenido

Extrae publicaciones de blog y artículos
Crea clústeres de conocimiento basados en temas
Encuentra contenido relacionado entre fuentes

🛠️ Desarrollo

Compilar el servidor MCP

npm run build

Ejecutar en modo desarrollo

npm run dev  # TypeScript watch mode

Pruebas

# 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

🚨 Solución de problemas

Problemas comunes

Faltan dependencias de Python:

pip install -r requirements.txt

Errores de compilación de TypeScript:

npm install
npm run build

Descarga lenta del modelo de embeddings: La primera ejecución descarga el modelo sentence-transformers (~90MB). Esto es normal.

Sin resultados en la búsqueda:

Comprueba si los documentos se procesaron: python src/rag_system.py list
Verifica que los filtros de calidad de contenido no sean demasiado estrictos
Prueba términos de búsqueda más amplios

Registros y depuración

Registros de Python: Comprueba la salida de consola
Registros del servidor MCP: Salida de stderr
Estado del procesamiento: scraped_content/.processed_files.json

📝 Licencia

Licencia MIT: siéntete libre de modificar y ampliar según tus necesidades.

🤝 Contribuciones

Este es un proyecto personal de Eric Berry, pero siéntete libre de hacer un fork y adaptarlo para tus propios casos de uso.

¡Feliz extracción y búsqueda! 🕷️🔍✨