Local RAG

Servidor RAG local con prioridad en la privacidad para búsqueda semántica de documentos sin APIs externas.

Documentación

MCP Local RAG

Busque documentos privados desde un cliente MCP o la terminal sin enviarlos a una API de embedding.

mcp-local-rag indexa archivos PDF, DOCX, Markdown y de texto en su 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.

Características

Se ejecuta localmente: El análisis de documentos, los embeddings, el almacenamiento y la búsqueda se ejecutan en su máquina. Después de la descarga inicial del modelo, la ingesta de texto y la búsqueda funcionan sin conexión.
Búsqueda híbrida: La recuperación semántica encuentra conceptos relacionados, mientras que la coincidencia de palabras clave resalta términos técnicos exactos.
Segmentación semántica: Los documentos se dividen en límites de tema en lugar de recuentos fijos de caracteres. Los bloques de código Markdown permanecen intactos.
MCP y CLI: Use el mismo índice desde una herramienta de codificación con IA o directamente desde la terminal.

No se requiere API key, Docker, Python ni base de datos externa.

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 embedding
Un directorio que contenga los documentos que desea buscar

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

mcp-local-rag utiliza el protocolo MCP estándar sobre un servidor stdio local, por lo que funciona con herramientas de codificación de IA y otros hosts MCP que admiten servidores MCP locales.

Use uno de los ejemplos a continuación, o registre npx -y mcp-local-rag y establezca BASE_DIR usando el formato de configuración MCP de su cliente.

Para Claude Code: Ejecute este comando:

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

Para Codex: Agregue a ~/.codex/config.toml:

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

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

Para OpenCode: Agregue a ~/.config/opencode/opencode.json (o opencode.jsonc):

{
  "$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"
      }
    }
  }
}

Para Cursor: Agregue a ~/.cursor/mcp.json:

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

Reinicie el cliente y luego pídale que construya el índice:

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

La primera sincronización descarga el modelo de embedding predeterminado (alrededor de 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 completada la sincronización:

What does the API documentation say about authentication?

Inicio Rápido 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 raíz de documentos de forma predeterminada. Ejecute ambos comandos desde el mismo directorio para que usen el mismo índice predeterminado, o establezca BASE_DIR y DB_PATH explícitamente.

Por Qué Existe Esto

Algunos conjuntos de documentos no pueden enviarse a un servicio de embedding alojado debido a la confidencialidad o a políticas organizacionales. Mantener el índice local permite que sean buscables sin agregar un costo de API por consulta.

La búsqueda semántica por sí sola puede omitir identificadores exactos que son importantes en documentación técnica. El reordenamiento por palabras clave mantiene esos términos visibles sin renunciar a la recuperación en lenguaje natural.

Contenido Soportado

Entrada	Cómo ingerir
PDF, DOCX, TXT, Markdown	Ingestión de archivos o sincronización de directorios
HTML ya obtenido por el cliente	`ingest_data`; limpiado con Readability y convertido a Markdown
Texto plano o Markdown en memoria	`ingest_data` con un identificador de fuente estable

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 ingestión 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.

Herramientas MCP

Herramienta	Propósito
`sync_start`	Reconciliar el índice con todas las raíces configuradas o una ruta
`sync_status`	Consultar un trabajo de sincronización en ejecución
`ingest_file`	Ingerir o reemplazar un archivo
`ingest_data`	Ingerir texto, Markdown o HTML ya en manos del cliente
`query_documents`	Buscar con coincidencia semántica y refuerzo de palabras clave
`read_chunk_neighbors`	Leer fragmentos circundantes de un resultado de búsqueda
`list_files`	Mostrar archivos soportados y su estado de ingestión
`delete_file`	Eliminar un archivo indexado o un elemento de `ingest_data`
`status`	Mostrar estado del índice y de la búsqueda

Sincronización de una Raíz de Documentos

sync_start ingiere archivos nuevos y modificados, omite archivos idénticos por bytes y elimina entradas del índice para archivos que ya no existen:

Sync everything under the configured document roots and wait for completion.

La herramienta devuelve un jobId inmediatamente. Los clientes deben consultar sync_status hasta que su estado sea succeeded o failed. No hay modo visual durante la sincronización; los PDF modificados se ingieren como texto.

Solo se conserva un trabajo de sincronización en el proceso del servidor. Un trabajo más nuevo reemplaza un registro finalizado, y reiniciar el servidor lo descarta.

Ingestión de un Archivo

ingest_file acepta PDF, DOCX, TXT y Markdown. Las rutas de archivo MCP deben ser absolutas y permanecer dentro de una raíz de documentos configurada:

Ingest the document at /Users/me/docs/api-spec.pdf.

Re-ingerir la misma ruta reemplaza sus fragmentos existentes.

Búsqueda y Lectura de Más Contexto

What does the API documentation say about authentication?
Find the documented behavior of ERR_CONNECTION_REFUSED.

Los resultados contienen el texto, la ruta de origen, el título, el índice de fragmento y la puntuación de relevancia. Pase el chunkIndex y ya sea filePath o source de un resultado a read_chunk_neighbors cuando la respuesta necesite más contexto:

Read the surrounding chunks for that authentication result.

Tanto query_documents como list_files aceptan un prefijo de ruta absoluta opcional scope, o una lista de prefijos. Un prefijo coincide con la ruta exacta y sus descendientes.

Ingestión de HTML

Use ingest_data después de que el cliente MCP obtenga una página:

Fetch https://example.com/docs and ingest the HTML.

El servidor extrae el artículo principal, lo convierte a Markdown y lo almacena bajo el identificador de fuente suministrado. Reutilizar la misma fuente actualiza el contenido existente.

Respete los términos y derechos de autor del sitio de origen al indexar contenido externo.

Figuras en PDF

El modo visual agrega una leyenda generada para páginas PDF con muchas figuras. Es opcional y no carga un modelo de visión durante la ingestión normal.

Ingest /Users/me/docs/research-paper.pdf with visual: true.

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

Perfil	Caché de modelo	Caso de uso
`fast` (predeterminado)	unos 250 MB	Indexación visual ligera
`quality`	unos 2,9 GB	Figuras que contienen etiquetas, anotaciones u otro texto dentro de la imagen

Seleccione el modelo más grande con visualQuality: "quality" a través de MCP o --visual-quality quality a través de CLI. La inferencia medida en CPU fue aproximadamente el doble de lenta que fast, aunque los resultados dependen del hardware y de las actualizaciones del modelo.

Las leyendas son texto auxiliar, no transcripciones fieles. Trate las leyendas recuperadas y el texto del documento como entrada no confiable, no como instrucciones.

CLI

La CLI usa el mismo analizador, generador de embeddings y almacén vectorial sin un cliente MCP:

npx mcp-local-rag ingest ./docs/
npx mcp-local-rag sync ./docs/
npx mcp-local-rag query "authentication API"
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"

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"

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

La CLI no lee la configuración del cliente MCP. Establezca las mismas variables de entorno o banderas si ambas interfaces deben compartir un índice. En particular, MODEL_NAME y la CLI deben coincidir en --model-name para una base de datos compartida.

Ajuste de la Búsqueda

El refuerzo de palabras clave está habilitado de forma predeterminada. El agrupamiento por brechas de relevancia y los filtros de distancia y archivos son controles opcionales para corpus que necesitan una selección de resultados más precisa.

Variable	Predeterminado	Descripción
`RAG_HYBRID_WEIGHT`	`0.6`	Factor de refuerzo de palabras clave (0.0–1.0). 0 desactiva el reordenamiento por palabras clave; 1 aplica el refuerzo máximo.
`RAG_GROUPING`	(no establecido)	`similar` conserva el primer grupo de relevancia; `related` conserva hasta dos, usando brechas significativas de distancia vectorial como límites.
`RAG_MAX_DISTANCE`	(no establecido)	Filtra resultados de baja relevancia (por ejemplo, `0.5`).
`RAG_MAX_FILES`	(no establecido)	Limita los resultados a los mejores N archivos (por ejemplo, `1` para un solo archivo mejor).

Para especificaciones de API y otros documentos que contienen muchos identificadores, un peso de palabra clave más fuerte puede mejorar la clasificación de términos exactos:

"env": {
  "RAG_HYBRID_WEIGHT": "0.7"
}

0.7: reordenamiento de términos exactos ligeramente más fuerte que el predeterminado
1.0: refuerzo máximo de palabras clave

Cómo Funciona

Durante la ingestión:

El analizador extrae texto para el formato de entrada.
El segmentador semántico encuentra límites de tema y preserva los bloques de código Markdown.
Transformers.js crea embeddings localmente.
LanceDB almacena los fragmentos, metadatos, vectores e índice de texto completo.

Durante la búsqueda:

La consulta se incorpora con el mismo modelo.
La búsqueda vectorial recupera fragmentos semánticamente relacionados.
Los filtros opcionales de distancia y grupo de relevancia reducen los candidatos cuando están configurados.
Las coincidencias de texto completo refuerzan los términos exactos de la consulta.

Habilidades del Agente

Agent Skills proporcionan guía de consulta e ingestión 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 formulación de consultas, refinamiento de resultados e ingestión de HTML. Pida al asistente que use la habilidad mcp-local-rag explícitamente si no se activa automáticamente.

Configuración

El servidor MCP lee variables de entorno. La CLI acepta las mismas variables más las banderas indicadas, y las banderas CLI tienen prioridad.

Variable de Entorno	Bandera CLI	Predeterminado	Descripción
`BASE_DIR`	`--base-dir`	Directorio actual	Una raíz de documentos; la bandera CLI es repetible en `ingest`, `list` y `sync`
`BASE_DIRS`	N/A	(sin establecer)	Matriz JSON de raíces de documentos; tiene prioridad sobre `BASE_DIR`
`DB_PATH`	`--db-path`	`./lancedb/`	Ubicación de la base de datos vectorial
`CACHE_DIR`	`--cache-dir`	`./models/`	Directorio de caché del modelo
`MODEL_NAME`	`--model-name`	`Xenova/all-MiniLM-L6-v2`	Modelo de embedding de Hugging Face
`MAX_FILE_SIZE`	`--max-file-size`	`104857600` (100 MB)	Tamaño máximo de archivo en bytes
`CHUNK_MIN_LENGTH`	`--chunk-min-length`	`50`	Longitud mínima de fragmento en caracteres (1–10000)
`RAG_DEVICE`	N/A	`cpu`	Dispositivo de ejecución de ONNX Runtime
`RAG_DTYPE`	N/A	`fp32`	Tipo de dato de embedding suministrado por el modelo seleccionado

Raíces de Documentos (`BASE_DIR` y `BASE_DIRS`)

mcp-local-rag solo permite operaciones de archivos dentro de las raíces configuradas. Para múltiples raíces, BASE_DIRS debe ser una matriz JSON de rutas no vacías:

export BASE_DIRS='["/Users/me/Documents/work","/Users/me/Projects/specs"]'

La configuración de raíces se resuelve en este orden:

Bandera CLI --base-dir <path> (repetible en ingest, list y sync)
BASE_DIRS
BASE_DIR
Directorio actual

Cada fuente reemplaza a la fuente de menor prioridad en lugar de fusionarse con ella. Una configuración de BASE_DIRS inválida falla en lugar de recurrir a BASE_DIR o al directorio actual. status permanece disponible en MCP para que el cliente pueda informar el error de configuración.

npx mcp-local-rag ingest --base-dir /Users/me/work --base-dir /Users/me/specs /Users/me/work/readme.md
npx mcp-local-rag list --base-dir /Users/me/work --base-dir /Users/me/specs
npx mcp-local-rag sync --base-dir /Users/me/work --base-dir /Users/me/specs
BASE_DIRS='["/Users/me/work","/Users/me/specs"]' npx mcp-local-rag list

Almacenamiento y Modelos

DB_PATH y CACHE_DIR son relativos al directorio de trabajo del proceso de forma predeterminada. Establezca rutas absolutas cuando el cliente MCP pueda iniciar el servidor desde diferentes directorios de proyecto.

Cambiar MODEL_NAME, RAG_DEVICE o RAG_DTYPE puede hacer que los vectores existentes sean incompatibles. Use un nuevo DB_PATH o elimine el índice existente y vuelva a ingerir después de cambiar la configuración de embedding.

Ejemplos de modelos:

Documentos multilingües: onnx-community/embeddinggemma-300m-ONNX
Artículos científicos: sentence-transformers/allenai-specter

Seguridad y Operación

Translated Markdown

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é.
El servidor está diseñado para un usuario local y no proporciona autenticación ni control de acceso.
No ejecute múltiples escritores CLI o MCP contra el mismo DB_PATH. Las consultas de solo lectura pueden ejecutarse mientras una sincronización está activa.
Realice una copia de seguridad de un índice copiando su directorio DB_PATH mientras ningún escritor esté activo.

Solución de problemas

"No se encontraron resultados"

Los documentos deben ingerirse primero. Ejecute "List all ingested files" para verificar.

Error al descargar el modelo

Verifique la conexión a internet. Si está detrás de un proxy, configure los ajustes de red. El modelo también se puede descargar manualmente.

"Archivo demasiado grande"

El límite predeterminado es de 100 MB. Divida archivos grandes o aumente MAX_FILE_SIZE.

Consultas lentas

Verifique el número de fragmentos con status. Los documentos grandes con muchos fragmentos pueden ralentizar las consultas. Considere dividir archivos muy grandes.

"Ruta fuera de BASE_DIR"

Asegúrese de que las rutas de archivo estén dentro de una de las raíces configuradas (BASE_DIR, cualquier entrada de BASE_DIRS o cualquier CLI --base-dir). Use rutas absolutas.

"BASE_DIRS debe ser un array JSON..."

BASE_DIRS acepta un array JSON de una o más cadenas de ruta no vacías:

Válido: BASE_DIRS='["/Users/me/work","/Users/me/specs"]'
Inválido: BASE_DIRS=/a:/b (sintaxis de delimitador no compatible)
Inválido: BASE_DIRS='[]' (array vacío)

El cliente MCP no ve las herramientas

Verifique la sintaxis del archivo de configuración
Reinicie el cliente por completo (Cmd+Q en Mac para Cursor)
Pruebe directamente: npx mcp-local-rag debería ejecutarse sin errores

Contribuciones

¡Las contribuciones son bienvenidas! Consulte CONTRIBUTING.md para la configuración y las pautas.

Licencia

Licencia MIT. Gratuita para uso personal y comercial.

Publicaciones del blog

Construyendo un RAG local para codificación agéntica: Análisis técnico 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.