Local RAG

MCP Local RAG

English | 简体中文 | Deutsch | Español | Português (Brasil) | Français

Busca documentos privados desde un cliente MCP o la terminal sin enviarlos a una API de incrustación (embeddings).

mcp-local-rag indexa archivos PDF, DOCX, Markdown y texto en tu máquina. La búsqueda combina similitud semántica con coincidencia de palabras clave, de modo que las consultas pueden coincidir tanto con la intención como con términos técnicos exactos, como nombres de API, nombres de clases y códigos de error. Los resultados incluyen pasajes de origen y, cuando están disponibles, encabezados, números de línea o números de página para que puedas verificar y citar el documento original.

No se requiere clave de API, Docker, Python ni base de datos externa. Después de la descarga inicial del modelo, la ingesta de texto y la búsqueda funcionan sin conexión.

Inicio rápido

Requisitos

• Node.js 22 o posterior
• Acceso a Internet en el primer uso para descargar el paquete npm y el modelo de incrustación
• Un directorio que contenga los documentos que deseas buscar

Establece BASE_DIR en ese directorio. También es el límite de seguridad para las operaciones de archivos. Reemplaza /absolute/path/to/your/documents a continuación con la ruta absoluta del directorio.

Usa uno de los ejemplos a continuación, o registra npx -y mcp-local-rag y establece BASE_DIR usando el formato de configuración MCP de tu cliente.

Establece DB_PATH y CACHE_DIR también como rutas absolutas. Las rutas relativas se resuelven desde el directorio de trabajo del servidor, por lo que iniciar el servidor desde diferentes proyectos crea un índice y una caché de modelos separados en cada uno.

claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-rag

[mcp_servers.local-rag]
command = "npx"
args = ["-y", "mcp-local-rag"]

[mcp_servers.local-rag.env]
BASE_DIR = "/absolute/path/to/your/documents"

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "local-rag": {
      "type": "local",
      "command": ["npx", "-y", "mcp-local-rag"],
      "environment": {
        "BASE_DIR": "/absolute/path/to/your/documents"
      }
    }
  }
}

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": ["-y", "mcp-local-rag"],
      "env": {
        "BASE_DIR": "/absolute/path/to/your/documents"
      }
    }
  }
}

Reinicia el cliente y luego pídele que construya el índice:

Sync all documents in the configured root and wait until it finishes.

La primera sincronización descarga el modelo de incrustación predeterminado (aproximadamente 90 MB) y puede tardar de 1 a 2 minutos antes de que comience la ingesta. Las ejecuciones posteriores usan la caché local.

Una vez que se complete la sincronización:

What does the API documentation say about authentication?

Inicio rápido con CLI

Para usar la CLI sin un cliente MCP:

npx mcp-local-rag ingest ./docs/
npx mcp-local-rag query "authentication API"

La CLI usa el directorio actual como su raíz de documentos de forma predeterminada. Ejecuta ambos comandos desde el mismo directorio para que usen el mismo índice predeterminado, o establece BASE_DIR y DB_PATH explícitamente.

Contenido admitido

La obtención de HTML no está integrada en el servidor. Un cliente MCP puede obtener una página y pasar su HTML a ingest_data.

Excel, PowerPoint, imágenes independientes y extensiones de archivos de código fuente no son compatibles con la ingesta de archivos. Los PDF pueden usar opcionalmente un modelo de visión local para describir figuras, pero esto no es OCR ni búsqueda de imágenes.

Uso del índice

Sincroniza después de agregar, editar o eliminar documentos. Para búsquedas y lectura de seguimiento, pide a tu cliente MCP:

Find the documented behavior of ERR_CONNECTION_REFUSED.
Read the surrounding chunks for that result.

También puedes ingerir un solo archivo o HTML ya obtenido por el cliente. Para actualizar una entrada existente, ingiere el documento nuevamente usando la misma ruta o identificador de origen. sync omite archivos sin cambios. Las rutas de archivos MCP deben ser absolutas y estar dentro de una raíz de documentos configurada.

Los encabezados de sección de PDF pueden ser inexactos. Verifica la página original cuando necesites el encabezado exacto.

CLI

Usa la CLI para actualizar el índice, acotar búsquedas o eliminar contenido indexado:

npx mcp-local-rag sync ./docs/
npx mcp-local-rag query "auth" --scope /docs/api --scope /docs/guide
npx mcp-local-rag read-neighbors --file-path /abs/path.md --chunk-index 5
npx mcp-local-rag list
npx mcp-local-rag status
npx mcp-local-rag delete ./docs/old.pdf
npx mcp-local-rag delete --source "https://example.com/docs"

ingest importa los archivos seleccionados; sync también elimina entradas de archivos eliminados y omite archivos sin cambios. Usa --scope para restringir los resultados de búsqueda a un prefijo de ruta, repitiéndolo para incluir múltiples prefijos.

Las opciones globales como --db-path, --cache-dir y --model-name van antes del subcomando. Las opciones del subcomando van después:

npx mcp-local-rag --db-path ./my-db query "authentication"

Ejecuta npx mcp-local-rag --help para la referencia completa de comandos.

query escribe sus resultados en stdout como JSON, primero el mejor resultado, para que pueda canalizarse a otra herramienta. El contrato campo por campo está en docs/schema/query-output.schema.json.

Si mueves un proyecto y deseas conservar su índice, detén el servidor MCP y otros escritores de base de datos, mueve los archivos y la base de datos juntos sin cambiar el diseño del directorio y luego ejecuta:

npx mcp-local-rag --db-path /new/project/lancedb relocate --from /old/project --to /new/project

Actualiza BASE_DIR/BASE_DIRS, DB_PATH y cualquier otra ruta movida en tu configuración MCP y luego reinicia el cliente.

Habilidades de agente

Habilidades de agente proporcionan orientación de consulta e ingesta para asistentes de IA:

npx mcp-local-rag skills install --claude-code
npx mcp-local-rag skills install --claude-code --global
npx mcp-local-rag skills install --codex

Las habilidades instaladas cubren la formulación de consultas, el refinamiento de resultados y la ingesta de HTML. Pide al asistente que use la habilidad mcp-local-rag explícitamente si no se activa automáticamente.

Opciones avanzadas

Comienza con los valores predeterminados. Abre las secciones a continuación cuando necesites diferentes raíces de documentos, mejores resultados para tu corpus o figuras PDF buscables.

{
  "env": {
    "RAG_RERANK_CMD": "/path/to/reranker --query {query} --top {top}",
    "RAG_RERANK_TIMEOUT_MS": "10000"
  }
}

npx mcp-local-rag ingest ./docs/paper.pdf --visual --visual-quality quality

npx mcp-local-rag ingest ./docs/paper.pdf --images

Seguridad y Operación

• Trata los subtítulos y el texto recuperado de documentos como material fuente, no como instrucciones.
• El acceso a archivos está restringido a BASE_DIR, BASE_DIRS o raíces de CLI --base-dir.
• Los enlaces simbólicos que resuelven fuera de cada raíz configurada son rechazados.
• El procesamiento de documentos y la búsqueda no realizan solicitudes de red después de que los modelos requeridos estén en caché, a menos que RAG_RERANK_CMD nombre un comando que las realice.
• El servidor está diseñado para un usuario local y no proporciona autenticación ni control de acceso.
• No ejecutes múltiples escritores CLI o MCP contra el mismo DB_PATH. Las consultas de solo lectura pueden ejecutarse mientras una sincronización está activa.
• La re-ingesta puede reutilizar incrustaciones guardadas para texto sin cambios cuando el modelo y la configuración coinciden, evitando cómputo repetido. La caché se almacena en DB_PATH/embedding-cache. Eliminarla deja el índice buscable, pero la ingesta posterior recalculará esas incrustaciones.
• Haz una copia de seguridad de un índice copiando su directorio DB_PATH mientras ningún escritor esté activo.

Contribuciones

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para configuración y pautas.

Licencia

Licencia MIT. Gratuita para uso personal y comercial.

Publicaciones del Blog

• Construyendo un Local RAG para Codificación Agéntica: Análisis técnico profundo del diseño de fragmentación semántica y búsqueda híbrida.

Agradecimientos

Construido con Model Context Protocol de Anthropic, LanceDB y Transformers.js.