@ssmeo/mcp-local-rag 0.18.14 → 0.19.0

package/README.es.md

@@ -4,10 +4,14 @@
 
 # MCP Local RAG
 
-[![GitHub stars](https://img.shields.io/github/stars/shinpr/mcp-local-rag?style=social)](https://github.com/shinpr/mcp-local-rag)
-[![npm version](https://img.shields.io/npm/v/mcp-local-rag.svg)](https://www.npmjs.com/package/mcp-local-rag)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![MCP Registry](https://img.shields.io/badge/MCP-Registry-green.svg)](https://registry.modelcontextprotocol.io/)
+[![GitHub
+stars](https://img.shields.io/github/stars/shinpr/mcp-local-rag?style=social)](https://github.com/shinpr/mcp-local-rag)
+[![npm
+version](https://img.shields.io/npm/v/mcp-local-rag.svg)](https://www.npmjs.com/package/mcp-local-rag)
+[![License:
+MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP
+Registry](https://img.shields.io/badge/MCP-Registry-green.svg)](https://registry.modelcontextprotocol.io/)
 
 <p align="center">
   <a href="README.md">English</a> |
@@ -18,41 +22,52 @@
   <a href="README.fr.md">Français</a>
 </p>
 
-Busca en documentos privados desde un cliente MCP o desde la terminal sin enviarlos a una API de embeddings.
+Busca en documentos privados desde un cliente MCP o desde la terminal sin enviarlos a una API
+de embeddings.
 
-mcp-local-rag indexa archivos PDF, DOCX y Markdown, además de archivos de texto, en tu equipo. La búsqueda combina similitud semántica y coincidencia de palabras clave. Así tiene en cuenta tanto el sentido de la consulta como los términos técnicos exactos, por ejemplo nombres de API, clases y códigos de error.
+mcp-local-rag indexa archivos PDF, DOCX y Markdown, además de archivos de texto, en tu equipo.
+La búsqueda combina similitud semántica y coincidencia de palabras clave. Así tiene en cuenta
+tanto el sentido de la consulta como los términos técnicos exactos, por ejemplo nombres de API,
+clases y códigos de error. Los resultados incluyen pasajes del documento y, cuando están
+disponibles, títulos de sección y números de línea o página para consultar y citar el original.
 
-## Funciones
-
-- **Ejecución local:** El análisis de documentos, los embeddings, el almacenamiento y la búsqueda se realizan en tu equipo. Después de descargar el modelo por primera vez, la incorporación de texto y las búsquedas funcionan sin conexión.
-- **Búsqueda híbrida:** La recuperación semántica encuentra conceptos relacionados y la coincidencia de palabras clave da más peso a los términos técnicos exactos.
-- **Embeddings configurables:** Puedes elegir un modelo de embeddings de Hugging Face adecuado para el idioma y el ámbito de tus documentos.
-- **Segmentación semántica:** Los documentos se dividen cuando cambia el tema, no cada cierto número de caracteres. Los bloques de código Markdown se mantienen intactos.
-- **MCP y CLI:** Usa el mismo índice desde una herramienta de programación con IA o directamente desde la terminal.
-
-No hace falta una clave de API, Docker, Python ni una base de datos externa.
+No hace falta una clave de API, Docker, Python ni una base de datos externa. Tras descargar el
+modelo por primera vez, la incorporación de texto y la búsqueda funcionan sin conexión.
 
 ## Inicio rápido
 
 ### Requisitos
 
-- Node.js 22 o posterior
+- Node.js 22.20 o posterior
 - Acceso a Internet durante el primer uso para descargar el paquete npm y el modelo de embeddings
 - Un directorio con los documentos que quieras consultar
 
-Asigna ese directorio a `BASE_DIR`. También será el límite de seguridad para las operaciones con archivos. Sustituye `/absolute/path/to/your/documents` en los ejemplos por la ruta absoluta del directorio.
+Asigna ese directorio a `BASE_DIR`. También será el límite de seguridad para las operaciones
+con archivos. Sustituye `/absolute/path/to/your/documents` en los ejemplos por la ruta absoluta
+del directorio.
 
-mcp-local-rag usa el protocolo MCP estándar mediante un servidor stdio local. Por eso funciona con herramientas de programación con IA y otros hosts MCP que admitan servidores MCP locales.
+Usa uno de los ejemplos siguientes o registra `npx -y mcp-local-rag` y configura `BASE_DIR` con
+el formato de configuración MCP de tu cliente.
 
-Usa uno de los ejemplos siguientes o registra `npx -y mcp-local-rag` y configura `BASE_DIR` con el formato de configuración MCP de tu cliente.
+Configura también `DB_PATH` y `CACHE_DIR` con rutas absolutas. Las rutas relativas parten del
+directorio de trabajo del servidor, por lo que iniciarlo desde distintos proyectos crea un
+índice y una caché de modelos en cada uno.
 
-**Claude Code:** Ejecuta este comando:
+<details>
+<summary>Claude Code</summary>
+
+Ejecuta este comando:
 
 ```bash
 claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-rag
 ```
 
-**Codex:** Añade lo siguiente a `~/.codex/config.toml`:
+</details>
+
+<details>
+<summary>Codex</summary>
+
+Añade lo siguiente a `~/.codex/config.toml`:
 
 ```toml
 [mcp_servers.local-rag]
@@ -63,7 +78,12 @@ args = ["-y", "mcp-local-rag"]
 BASE_DIR = "/absolute/path/to/your/documents"
 ```
 
-**OpenCode:** Añade lo siguiente a `~/.config/opencode/opencode.json` (o `opencode.jsonc`):
+</details>
+
+<details>
+<summary>OpenCode</summary>
+
+Añade lo siguiente a `~/.config/opencode/opencode.json` (o `opencode.jsonc`):
 
 ```json
 {
@@ -80,7 +100,12 @@ BASE_DIR = "/absolute/path/to/your/documents"
 }
 ```
 
-**Cursor:** Añade lo siguiente a `~/.cursor/mcp.json`:
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+Añade lo siguiente a `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -96,13 +121,17 @@ BASE_DIR = "/absolute/path/to/your/documents"
 }
 ```
 
+</details>
+
 Reinicia el cliente y pídele que construya el índice:
 
 ```text
 Sincroniza todos los documentos del directorio raíz configurado y espera a que termine.
 ```
 
-La primera sincronización descarga el modelo de embeddings predeterminado (unos 90 MB). Pueden pasar entre 1 y 2 minutos antes de que comience la incorporación. Las ejecuciones posteriores usan la caché local.
+La primera sincronización descarga el modelo de embeddings predeterminado (unos 90 MB). Pueden
+pasar entre 1 y 2 minutos antes de que comience la incorporación. Las ejecuciones posteriores
+usan la caché local.
 
 Cuando termine la sincronización, prueba con una consulta:
 
@@ -119,27 +148,45 @@ npx mcp-local-rag ingest ./docs/
 npx mcp-local-rag query "API de autenticación"
 ```
 
-La CLI usa el directorio actual como raíz de documentos de forma predeterminada. Ejecuta ambos comandos desde el mismo directorio para que compartan el índice predeterminado, o configura `BASE_DIR` y `DB_PATH` de forma explícita.
-
-## Por qué existe
-
-Algunos conjuntos de documentos no se pueden enviar a un servicio de embeddings alojado por motivos de confidencialidad o por las políticas de una organización. Un índice local permite consultarlos sin añadir un coste de API por búsqueda.
-
-Una búsqueda puramente semántica puede pasar por alto identificadores exactos que son importantes en la documentación técnica. El reajuste por palabras clave mantiene visibles esos términos sin renunciar a las consultas en lenguaje natural.
+La CLI usa el directorio actual como raíz de documentos de forma predeterminada. Ejecuta ambos
+comandos desde el mismo directorio para que compartan el índice predeterminado, o configura
+`BASE_DIR` y `DB_PATH` de forma explícita.
 
 ## Contenido compatible
 
 | Entrada | Cómo incorporarla |
 |---|---|
 | PDF, DOCX, TXT, Markdown | Incorporación de archivos o sincronización de directorios |
-| HTML ya obtenido por el cliente | `ingest_data`; se limpia con Readability y se convierte a Markdown |
+| HTML ya obtenido por el cliente | `ingest_data` |
 | Texto sin formato o Markdown en memoria | `ingest_data` con un identificador de origen estable |
 
-El servidor no descarga páginas HTML. Un cliente MCP puede obtener una página y pasar su HTML a `ingest_data`.
+El servidor no descarga páginas HTML. Un cliente MCP puede obtener una página y pasar su HTML a
+`ingest_data`.
+
+La incorporación de archivos no admite Excel, PowerPoint, imágenes independientes ni
+extensiones de código fuente. De forma opcional, los PDF pueden usar un modelo visual local
+para describir figuras, pero esta función no es OCR ni búsqueda de imágenes.
+
+## Usar el índice
+
+Sincroniza el índice después de añadir, modificar o eliminar documentos. Para buscar y ampliar
+el contexto, puedes pedirle al cliente MCP:
 
-La incorporación de archivos no admite Excel, PowerPoint, imágenes independientes ni extensiones de código fuente. De forma opcional, los PDF pueden usar un modelo visual local para describir figuras, pero esta función no es OCR ni búsqueda de imágenes.
+```text
+Busca qué dice la documentación sobre ERR_CONNECTION_REFUSED.
+Lee también los segmentos anteriores y posteriores a ese resultado.
+```
+
+También puedes incorporar un solo archivo o HTML que el cliente ya haya obtenido. Para
+actualizar una entrada existente, vuelve a incorporar el documento con la misma ruta o
+identificador de origen. `sync` omite los archivos sin cambios. Las rutas de archivos en MCP
+deben ser absolutas y estar dentro de un directorio raíz configurado.
 
-## Herramientas MCP
+Los títulos de sección detectados en un PDF pueden ser incorrectos. Si necesitas el título
+exacto, compruébalo en la página original.
+
+<details>
+<summary>Herramientas MCP</summary>
 
 | Herramienta | Función |
 |---|---|
@@ -153,131 +200,140 @@ La incorporación de archivos no admite Excel, PowerPoint, imágenes independien
 | `delete_file` | Eliminar un archivo indexado o un elemento de `ingest_data` |
 | `status` | Mostrar el estado del índice y de la búsqueda |
 
-### Sincronizar un directorio raíz
-
-`sync_start` incorpora archivos nuevos o modificados, omite los que son idénticos byte a byte y elimina del índice los archivos que ya no existen:
-
-```text
-Sincroniza todo el contenido de los directorios raíz configurados y espera a que termine.
-```
-
-La herramienta devuelve un `jobId` de inmediato. El cliente debe consultar `sync_status` hasta que el estado sea `succeeded` o `failed`. Un PDF modificado conserva el perfil visual con el que se indexó; un PDF sin perfil registrado se mantiene solo como texto. `sync_start` no puede cambiar el perfil.
-
-El proceso del servidor solo conserva un trabajo de sincronización. Un trabajo nuevo sustituye el registro de uno ya terminado y el registro se pierde al reiniciar el servidor.
-
-### Incorporar un archivo
-
-`ingest_file` admite PDF, DOCX, TXT y Markdown. Las rutas de archivo enviadas mediante MCP deben ser absolutas y estar dentro de un directorio raíz configurado:
-
-```text
-Incorpora el documento /Users/me/docs/api-spec.pdf.
-```
-
-Si se vuelve a incorporar la misma ruta, sus segmentos anteriores se sustituyen.
-
-### Buscar y leer más contexto
+</details>
 
-```text
-¿Qué dice la documentación de la API sobre la autenticación?
-Busca el comportamiento documentado de ERR_CONNECTION_REFUSED.
-```
+## CLI
 
-Los resultados contienen el texto, la ruta de origen, el título, el índice del segmento y la puntuación de relevancia. Si necesitas más contexto, pasa a `read_chunk_neighbors` el `chunkIndex` y el `filePath` o `source` del resultado:
+Usa la CLI para actualizar el índice, acotar las búsquedas o eliminar contenido indexado:
 
-```text
-Lee los segmentos contiguos a ese resultado sobre autenticación.
+```bash
+npx mcp-local-rag sync ./docs/
+npx mcp-local-rag query "autenticación" --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"
 ```
 
-Tanto `query_documents` como `list_files` aceptan un prefijo de ruta absoluto opcional en `scope`, o una lista de prefijos. Cada prefijo coincide con la ruta exacta y con todo lo que contiene.
-
-### Incorporar HTML
+`ingest` incorpora los archivos seleccionados; `sync` también retira del índice los archivos
+eliminados y omite los que no han cambiado. Usa `--scope` para limitar los resultados a un
+prefijo de ruta y repítelo para incluir varios prefijos.
 
-Usa `ingest_data` después de que el cliente MCP haya obtenido la página:
+Las opciones globales, como `--db-path`, `--cache-dir` y `--model-name`, van antes del
+subcomando. Las opciones propias del subcomando van después:
 
-```text
-Obtén https://example.com/docs e incorpora el HTML.
+```bash
+npx mcp-local-rag --db-path ./my-db query "autenticación"
 ```
 
-El servidor extrae el artículo principal, lo convierte a Markdown y lo guarda con el identificador de origen indicado. Si se reutiliza el mismo origen, se actualiza el contenido existente.
-
-Respeta las condiciones y los derechos de autor del sitio de origen al indexar contenido externo.
-
-### Figuras de PDF
+Ejecuta `npx mcp-local-rag --help` para ver la referencia completa de comandos.
 
-El modo visual añade una descripción generada a las páginas de un PDF que contienen muchas figuras. Es opcional y no carga ningún modelo visual durante una incorporación normal.
+`query` escribe sus resultados en stdout como JSON, con la mejor coincidencia primero, de modo
+que puedes canalizarlos hacia otra herramienta. La definición de cada campo está en
+[`docs/schema/query-output.schema.json`](docs/schema/query-output.schema.json).
 
-```text
-Incorpora /Users/me/docs/research-paper.pdf con visual: true.
-```
+Si vas a mover un proyecto y quieres conservar su índice, detén el servidor MCP y los demás
+procesos de escritura. Mueve juntos los archivos y la base de datos, manteniendo la estructura
+de directorios, y ejecuta:
 
 ```bash
-npx mcp-local-rag ingest ./docs/research-paper.pdf --visual
+npx mcp-local-rag --db-path /new/project/lancedb relocate --from /old/project --to /new/project
 ```
 
-| Perfil | Caché del modelo | Uso |
-|---|---:|---|
-| `fast` (predeterminado) | unos 250 MB | Indexación visual ligera |
-| `quality` | unos 1,7 GB | Figuras con etiquetas, anotaciones u otro texto dentro de la imagen |
-
-Selecciona el modelo más grande con `visualQuality: "quality"` en MCP o con `--visual-quality quality` en la CLI. En pruebas con CPU, la inferencia tardó aproximadamente el triple que con `fast`, aunque el resultado depende del hardware y de las actualizaciones del modelo.
+En la configuración MCP, actualiza `BASE_DIR`/`BASE_DIRS`, `DB_PATH` y las demás rutas
+afectadas. Luego reinicia el cliente.
 
-#### Actualizar las descripciones `quality` existentes
+## Agent Skills
 
-Desde 0.18.4, `quality` usa Qwen3.5-2B; las versiones anteriores usaban Qwen2.5-VL-3B. Las descripciones ya indexadas conservan el texto del modelo anterior y `sync` no las regenera, así que vuelve a importar los archivos que quieras actualizar:
+Las [Agent Skills](https://agentskills.io/) ofrecen a los asistentes de IA instrucciones para
+formular consultas e incorporar contenido:
 
 ```bash
-npx mcp-local-rag ingest ./docs/research-paper.pdf --visual --visual-quality quality
+npx mcp-local-rag skills install --claude-code
+npx mcp-local-rag skills install --claude-code --global
+npx mcp-local-rag skills install --codex
 ```
 
-Añade `--images` si el archivo se incorporó con esa opción, porque una ejecución sin ella reemplaza las imágenes almacenadas. El modelo anterior permanece en el disco. Cuando ya nada lo use, elimina `onnx-community/Qwen2.5-VL-3B-Instruct-ONNX/` del directorio de caché de modelos: `<cache-dir>`, que por defecto es `./models/`.
+Las habilidades instaladas cubren la formulación de consultas, el refinamiento de resultados y
+la incorporación de HTML. Si alguna no se activa de forma automática, pide al asistente que use
+de manera explícita la habilidad mcp-local-rag.
 
-#### Modo visual entre sincronizaciones
+## Opciones avanzadas
 
-El perfil con el que se indexó un PDF queda registrado y `sync` lo reutiliza: un PDF indexado con `fast` o `quality` se vuelve a incorporar con ese mismo perfil y un PDF sin perfil registrado se incorpora como texto.
+Empieza con la configuración predeterminada. Consulta las siguientes secciones si necesitas
+varios directorios raíz, adaptar la búsqueda a tus documentos o buscar en figuras de PDF.
 
-```bash
-npx mcp-local-rag sync ./docs/                      # conservar el perfil registrado de cada PDF
-npx mcp-local-rag sync ./docs/ --visual             # solicitar fast para todos los PDF del ámbito
-npx mcp-local-rag sync ./docs/ --visual --visual-quality quality
-```
-
-`--visual` sustituye los perfiles registrados, así que también describe los PDF que se indexaron como texto. Cambiar de perfil vuelve a incorporar el PDF aunque el archivo no haya cambiado; repetir el mismo comando no hace nada ni carga ningún modelo.
+<details>
+<summary>Almacenamiento y directorios raíz</summary>
 
-Para desactivar las descripciones en una ruta, ejecuta `ingest` sobre ella: una incorporación normal correcta borra el perfil registrado. Para reintentar una página cuya descripción falló, ejecuta `ingest <ruta> --visual --visual-quality <perfil>` con el perfil que quieras: un `ingest` sin más lo borra. Si las filas indexadas de un PDF no coinciden en el perfil, `sync` se detiene antes de cambiar nada e indica el archivo; vuelve a ejecutarlo con `--visual` para fijar el perfil.
+El servidor MCP lee variables de entorno. La CLI acepta las variables y opciones indicadas.
+Mantén el mismo `DB_PATH` si los comandos deben compartir un índice.
 
-Las descripciones son texto auxiliar, no transcripciones fieles. Trata las descripciones y el texto recuperado de los documentos como entradas no fiables, no como instrucciones.
+| Variable de entorno | Opción de la CLI | Valor predeterminado | Descripción |
+|---------------------|----------|---------|-------------|
+| `BASE_DIR` | `--base-dir` | Directorio actual | Un directorio raíz; la opción de la CLI puede repetirse en `ingest`, `list` y `sync` |
+| `BASE_DIRS` | No disponible | sin configurar | Matriz JSON de directorios raíz; tiene prioridad sobre `BASE_DIR` |
+| `IGNORE_PATHS` | No disponible | sin configurar | Matriz JSON de patrones glob para archivos que deben quedar fuera del índice |
+| `DB_PATH` | `--db-path` | `./lancedb/` | Ubicación de la base de datos vectorial |
+| `CACHE_DIR` | `--cache-dir` | `./models/` | Directorio de caché de modelos |
+| `HF_ENDPOINT` | No disponible | `https://huggingface.co` | Dirección de descarga de modelos de Hugging Face; usa la URL de un servidor espejo si las descargas directas están bloqueadas |
+| `MAX_FILE_SIZE` | `--max-file-size` | `104857600` (100 MB) | Tamaño máximo del archivo en bytes |
 
-## CLI
+Las operaciones con archivos se limitan a los directorios raíz configurados. Para usar varios,
+configura `BASE_DIRS='["/absolute/docs","/absolute/specs"]'` o repite `--base-dir` en la CLI.
+Prioridad: directorios de la CLI, `BASE_DIRS`, `BASE_DIR` y directorio actual. Solo se usa la
+fuente de mayor prioridad; los directorios de distintas fuentes no se combinan. Un `BASE_DIRS`
+incorrecto produce un error. Las rutas relativas de `DB_PATH` y `CACHE_DIR` parten del
+directorio de trabajo.
+
+Para dejar archivos fuera del índice, configura `IGNORE_PATHS` con una matriz JSON de patrones
+glob, por ejemplo `IGNORE_PATHS='["plugs/**","**/*.draft.md"]'`. Cada patrón se compara con la
+ruta del archivo relativa al directorio raíz que lo contiene, escrita con `/` en cualquier
+sistema operativo. `*` y `**` no coinciden con nombres que empiezan por `.`, así que escribe
+esos directorios completos, como `".obsidian/**"`. Cuando `ingest`, `list` y `sync` recorren un
+directorio, omiten los archivos que coinciden, y `sync` retira del índice los que ya estaban
+indexados. Un `IGNORE_PATHS` incorrecto produce un error.
 
-La CLI usa el mismo analizador, generador de embeddings y almacén vectorial sin necesidad de un cliente MCP:
+</details>
 
-```bash
-npx mcp-local-rag ingest ./docs/
-npx mcp-local-rag sync ./docs/
-npx mcp-local-rag query "API de autenticación"
-npx mcp-local-rag query "autenticación" --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"
-```
+<details>
+<summary>Modelos y ajuste de la búsqueda</summary>
 
-Las opciones globales, como `--db-path`, `--cache-dir` y `--model-name`, van antes del subcomando. Las opciones propias del subcomando van después:
+Elige un modelo de embeddings adecuado para el idioma y el tema de tus documentos. Compara los
+ajustes con tus consultas habituales y comprueba los pasajes que devuelve la búsqueda. Elige un
+modelo compatible con mean pooling y normalización L2, que son los métodos usados para generar
+los embeddings.
 
-```bash
-npx mcp-local-rag --db-path ./my-db query "autenticación"
-```
+| Variable de entorno | Opción de la CLI | Valor predeterminado | Descripción |
+|---------------------|----------|---------|-------------|
+| `MODEL_NAME` | `--model-name` | `Xenova/all-MiniLM-L6-v2` | Modelo de embeddings de Hugging Face |
+| `CHUNK_MIN_LENGTH` | `--chunk-min-length` | `50` | Longitud mínima de un segmento normal en caracteres (1–10000); un fragmento resultante de dividir contenido para respetar el límite de tokens del modelo puede ser más corto |
+| `EMBED_TITLE_PREFIX` | No disponible | `false` | Añade el título del documento a la entrada usada para generar el embedding de cada segmento |
+| `EMBED_HEADING_PREFIX` | No disponible | `false` | Añade la jerarquía de títulos de sección a la entrada de cada segmento, si cabe en el límite de tokens |
+| `RAG_DEVICE` | No disponible | `cpu` | Dispositivo de ejecución de ONNX Runtime |
+| `RAG_DTYPE` | No disponible | `fp32` | Tipo de datos de los embeddings que recibe el modelo seleccionado |
 
-Ejecuta `npx mcp-local-rag --help` para ver la referencia completa de comandos.
+Ambas opciones de prefijo están desactivadas por defecto (`false`) y son independientes. Prueba
+`EMBED_TITLE_PREFIX` cuando un segmento necesite el tema general del documento, o
+`EMBED_HEADING_PREFIX` cuando le falte el tema de su sección. Activar ambas no siempre mejora
+los resultados. Afectan a los embeddings, no al texto devuelto ni al índice de palabras clave;
+el contexto de sección se omite si supera el presupuesto de entrada.
 
-La CLI no lee la configuración del cliente MCP. Configura las mismas variables de entorno u opciones si ambas interfaces deben compartir un índice. En particular, `MODEL_NAME` y la opción `--model-name` de la CLI deben coincidir cuando usan la misma base de datos.
+Al cambiar de modelo de embeddings, crea un índice nuevo en otro `DB_PATH`. Los vectores de
+modelos distintos no son comparables, aunque tengan las mismas dimensiones. Si cambias
+`RAG_DTYPE` o una opción de prefijo, vuelve a incorporar todos los documentos indexados antes
+de buscar. `sync` omite los archivos sin cambios.
 
-`query` escribe sus resultados en stdout como JSON, con la mejor coincidencia primero, de modo que puedes canalizarlos hacia otra herramienta. La definición de cada campo está en [`docs/schema/query-output.schema.json`](docs/schema/query-output.schema.json).
+La CLI no lee la configuración del cliente MCP. Si comparten un índice, usa el mismo modelo,
+`RAG_DTYPE` y ajustes de prefijo al incorporar documentos y al buscar. Cambiar únicamente
+`RAG_DEVICE` no exige crear otro índice.
 
-## Ajuste de la búsqueda
+### Ajustes de búsqueda
 
-El refuerzo de palabras clave está activado de forma predeterminada. Para corpus que necesiten una selección más estricta, también se pueden configurar la agrupación por saltos de relevancia y los filtros de distancia y de archivos. Las cuatro se aplican por igual al servidor MCP y a `query` en la CLI.
+Los primeros cuatro ajustes de la tabla se aplican tanto a MCP como a la CLI. Para dar más peso
+a los términos exactos, prueba a subir `RAG_HYBRID_WEIGHT` y compara los resultados con tus
+propias consultas. El reordenamiento externo solo está disponible en MCP.
 
 | Variable | Valor predeterminado | Descripción |
 |----------|---------|-------------|
@@ -285,125 +341,86 @@ El refuerzo de palabras clave está activado de forma predeterminada. Para corpu
 | `RAG_GROUPING` | sin configurar | `similar` conserva el primer grupo de relevancia; `related` conserva hasta dos y usa saltos importantes de distancia vectorial como límites. |
 | `RAG_MAX_DISTANCE` | sin configurar | Descarta resultados poco relevantes (por ejemplo, `0.5`). |
 | `RAG_MAX_FILES` | sin configurar | Limita los resultados a los N archivos mejor clasificados (por ejemplo, `1` deja solo el mejor archivo). |
-| `RAG_RERANK_CMD` | sin configurar | Solo servidor MCP: comando externo que reordena los resultados. Tu consulta y el texto encontrado se le envían. |
+| `RAG_RERANK_CMD` | sin configurar | Solo MCP: comando externo; `{query}` pasa la consulta y `{top}` la cantidad de resultados solicitada. |
 | `RAG_RERANK_TIMEOUT_MS` | `10000` | Tiempo máximo por llamada de reordenamiento en milisegundos (100–600000). |
 
-En especificaciones de API y otros documentos con muchos identificadores, un peso mayor de palabras clave puede mejorar la clasificación de términos exactos:
-
-```json
-"env": {
-  "RAG_HYBRID_WEIGHT": "0.7"
-}
-```
-
-- `0.7`: reajuste de términos exactos algo más fuerte que el valor predeterminado
-- `1.0`: refuerzo máximo de palabras clave
-
 ### Reordenamiento externo (`RAG_RERANK_CMD`)
 
-Indica aquí un comando y el servidor le entrega cada conjunto de resultados para reordenarlo, junto con tu consulta y el texto de los fragmentos encontrados. Un comando que contacta con un servicio remoto envía todo eso fuera de esta máquina.
+El comando recibe los resultados y el texto encontrado por la entrada estándar. Si llama a un
+servicio remoto, ese texto puede salir del equipo.
 
-Escribe el comando y sus argumentos separados por espacios. Tiene que ser un ejecutable: el servidor lo lanza sin shell, así que en Windows un adaptador `.cmd` instalado por npm no arranca.
+Escribe el ejecutable y su plantilla completa de argumentos. Coloca `{query}` y `{top}` donde
+el comando espera la consulta y el número de resultados. Las comillas simples o dobles agrupan
+rutas o argumentos con espacios, y las barras invertidas se conservan literalmente. El servidor
+lanza el ejecutable sin shell, así que en Windows un adaptador `.cmd` instalado por npm no
+arranca.
 
 ```json
-"env": {
-  "RAG_RERANK_CMD": "/path/to/reranker",
-  "RAG_RERANK_TIMEOUT_MS": "10000"
+{
+  "env": {
+    "RAG_RERANK_CMD": "/path/to/reranker --query {query} --top {top}",
+    "RAG_RERANK_TIMEOUT_MS": "10000"
+  }
 }
 ```
 
-El comando recibe cada resultado con la forma publicada en [`docs/schema/query-output.schema.json`](docs/schema/query-output.schema.json) y debe responder con esa misma forma. Dentro de ella lo decide todo: qué conservar, cómo ordenarlo y qué dice el texto. Lo que devuelva es lo que verás.
-
-Los resultados conservan su orden original si el comando falla, agota el tiempo o responde con algo que no tiene esa forma.
+El comando debe leer y devolver resultados con el formato definido en el [esquema de
+salida](docs/schema/query-output.schema.json). Puede eliminar o reordenar resultados y
+modificar su texto. El servidor devuelve la salida del comando.
 
-## Cómo funciona
+Los resultados conservan su orden original si el comando falla, supera el tiempo límite o
+devuelve una respuesta que no cumple el esquema.
 
-Durante la incorporación:
-
-1. El analizador extrae el texto del formato de entrada.
-2. El segmentador semántico localiza cambios de tema y conserva los bloques de código Markdown.
-3. Transformers.js crea los embeddings de forma local.
-4. LanceDB almacena los segmentos, los metadatos, los vectores y el índice de texto completo.
+</details>
 
-Durante la búsqueda:
+<details>
+<summary>Figuras PDF e imágenes guardadas</summary>
 
-1. La consulta se convierte en un embedding con el mismo modelo.
-2. La búsqueda vectorial recupera segmentos relacionados por su significado.
-3. Los filtros opcionales de distancia y los grupos de relevancia reducen los candidatos cuando están configurados.
-4. Las coincidencias de texto completo refuerzan los términos exactos de la consulta.
+De forma predeterminada, la incorporación solo indexa texto. Para buscar también en las figuras
+PDF, activa la generación local de descripciones con `visual: true` en MCP o `--visual` en la
+CLI. Son descripciones generadas, no OCR ni transcripciones exactas.
 
-## Agent Skills
+`fast` (predeterminado) descarga unos 250 MB la primera vez. Elige `quality` para etiquetas y
+texto dentro de las figuras; descarga unos 1,7 GB y tarda más en procesar.
 
-Las [Agent Skills](https://agentskills.io/) ofrecen a los asistentes de IA instrucciones para formular consultas e incorporar contenido:
+Selecciona el perfil con `visualQuality: "quality"` en MCP o `--visual-quality quality` en la
+CLI.
 
 ```bash
-npx mcp-local-rag skills install --claude-code
-npx mcp-local-rag skills install --claude-code --global
-npx mcp-local-rag skills install --codex
+npx mcp-local-rag ingest ./docs/paper.pdf --visual --visual-quality quality
 ```
 
-Las habilidades instaladas cubren la formulación de consultas, el refinamiento de resultados y la incorporación de HTML. Si alguna no se activa de forma automática, pide al asistente que use de manera explícita la habilidad mcp-local-rag.
-
-## Configuración
-
-El servidor MCP lee variables de entorno. La CLI acepta las mismas variables y las opciones de la tabla; las opciones de la CLI tienen prioridad.
-
-| Variable de entorno | Opción de la CLI | Valor predeterminado | Descripción |
-|---------------------|----------|---------|-------------|
-| `BASE_DIR` | `--base-dir` | Directorio actual | Un directorio raíz; la opción de la CLI puede repetirse en `ingest`, `list` y `sync` |
-| `BASE_DIRS` | No disponible | sin configurar | Matriz JSON de directorios raíz; 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é de modelos |
-| `HF_ENDPOINT` | No disponible | `https://huggingface.co` | Dirección de descarga de modelos de Hugging Face; usa la URL de un servidor espejo si las descargas directas están bloqueadas |
-| `MODEL_NAME` | `--model-name` | `Xenova/all-MiniLM-L6-v2` | Modelo de embeddings de Hugging Face |
-| `MAX_FILE_SIZE` | `--max-file-size` | `104857600` (100 MB) | Tamaño máximo del archivo en bytes |
-| `CHUNK_MIN_LENGTH` | `--chunk-min-length` | `50` | Longitud mínima de un segmento normal en caracteres (1–10000); un fragmento resultante de dividir contenido para respetar el límite de tokens del modelo puede ser más corto |
-| `RAG_DEVICE` | No disponible | `cpu` | Dispositivo de ejecución de ONNX Runtime |
-| `RAG_DTYPE` | No disponible | `fp32` | Tipo de datos de los embeddings que recibe el modelo seleccionado |
-
-### Directorios raíz (`BASE_DIR` y `BASE_DIRS`)
-
-mcp-local-rag solo permite operaciones con archivos dentro de los directorios raíz configurados. Para usar varios, `BASE_DIRS` debe ser una matriz JSON de rutas no vacías:
-
-```bash
-export BASE_DIRS='["/Users/me/Documents/work","/Users/me/Projects/specs"]'
-```
-
-La configuración se resuelve en este orden:
-
-1. Opciones `--base-dir <path>` de la CLI (se pueden repetir en `ingest`, `list` y `sync`)
-2. `BASE_DIRS`
-3. `BASE_DIR`
-4. Directorio actual
-
-Cada origen sustituye al de menor prioridad, no se combina con él. Una configuración de `BASE_DIRS` no válida produce un error en lugar de recurrir a `BASE_DIR` o al directorio actual. `status` sigue disponible en MCP para que el cliente pueda informar del error de configuración.
+Para recibir imágenes con los pasajes encontrados, usa `STORE_IMAGES=true` en MCP o `--images`
+con `ingest` y `sync` en la CLI. Es independiente de las descripciones y admite figuras y
+tablas detectadas en PDF, además de las imágenes PNG/JPEG compatibles de DOCX.
 
 ```bash
-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
+npx mcp-local-rag ingest ./docs/paper.pdf --images
 ```
 
-### Almacenamiento y modelos
+La sincronización conserva el perfil de descripción de cada PDF. El comando CLI `sync --visual
+--visual-quality quality` lo cambia incluso para PDF sin cambios; la sincronización MCP lo
+conserva. Una incorporación normal desactiva las descripciones. Para reintentar una descripción
+fallida, vuelve a incorporar el archivo con el perfil visual deseado.
 
-`DB_PATH` y `CACHE_DIR` son relativos al directorio de trabajo del proceso de forma predeterminada. Usa rutas absolutas si el cliente MCP puede iniciar el servidor desde distintos directorios de proyecto.
+Activa el almacenamiento de imágenes en cada incorporación o sincronización que procese el
+archivo. Cambiar solo esta opción no actualiza archivos sin cambios; vuelve a incorporarlos
+para aplicarla.
 
-Configura `MODEL_NAME` o pasa `--model-name` para elegir un modelo de embeddings de Hugging Face que se ajuste al idioma y al ámbito de tus documentos.
-
-mcp-local-rag genera embeddings mediante mean pooling y normalización L2. Al elegir un modelo, comprueba si estos ajustes coinciden con su configuración de inferencia recomendada, ya que el método de pooling puede influir en la calidad de la búsqueda.
-
-Cambiar `MODEL_NAME`, `RAG_DEVICE` o `RAG_DTYPE` puede hacer que los vectores existentes sean incompatibles. Usa un `DB_PATH` nuevo o elimina el índice existente y vuelve a incorporar los documentos después de cambiar la configuración de embeddings.
-
-Un ejemplo de modelo disponible para documentos en español es `jinaai/jina-embeddings-v2-base-es`.
+</details>
 
 ## Seguridad y funcionamiento
 
+- Trata las descripciones y el texto encontrado como fuentes, no como instrucciones.
 - El acceso a archivos está limitado a los directorios raíz configurados con `BASE_DIR`, `BASE_DIRS` o `--base-dir` en la CLI.
 - Se rechazan los enlaces simbólicos cuyo destino esté fuera de todos los directorios raíz configurados.
 - El procesamiento de documentos y las búsquedas no realizan solicitudes de red una vez que los modelos necesarios están en caché, salvo que `RAG_RERANK_CMD` indique un comando que sí las realice.
 - El servidor está diseñado para un único usuario local y no ofrece autenticación ni control de acceso.
 - No ejecutes varios procesos de escritura de la CLI o MCP sobre el mismo `DB_PATH`. Las consultas de solo lectura pueden ejecutarse mientras hay una sincronización en curso.
+- Al volver a incorporar un documento, se pueden reutilizar los embeddings del texto sin
+  cambios si coinciden el modelo y los ajustes, evitando repetir ese cálculo. Se guardan en
+  `DB_PATH/embedding-cache`. Puedes borrar esta caché sin perder el índice de búsqueda.
+  En la siguiente incorporación se volverán a calcular esos embeddings.
 - Para crear una copia de seguridad del índice, copia el directorio `DB_PATH` cuando no haya ningún proceso de escritura activo.
 
 <details>
@@ -411,11 +428,15 @@ Un ejemplo de modelo disponible para documentos en español es `jinaai/jina-embe
 
 ### "No results found"
 
-Primero hay que incorporar los documentos. Ejecuta `"Enumera todos los archivos incorporados"` para comprobarlo.
+Primero hay que incorporar los documentos. Ejecuta `"Enumera todos los archivos incorporados"`
+para comprobarlo. Si no aparecen resultados después de sincronizar, comprueba que la
+incorporación y la búsqueda usan el mismo `DB_PATH` absoluto. Una ruta relativa puede apuntar a
+otro índice.
 
 ### Error al descargar el modelo
 
-Comprueba la conexión a Internet. Si usas un proxy, revisa la configuración de red. También puedes [descargar el modelo manualmente](https://huggingface.co/Xenova/all-MiniLM-L6-v2).
+Comprueba la conexión a Internet. Si usas un proxy, revisa la configuración de red. También
+puedes [descargar el modelo manualmente](https://huggingface.co/Xenova/all-MiniLM-L6-v2).
 
 ### "File too large"
 
@@ -423,11 +444,13 @@ El límite predeterminado es de 100 MB. Divide el archivo o aumenta `MAX_FILE_SI
 
 ### Consultas lentas
 
-Comprueba el número de segmentos con `status`. Los documentos grandes con muchos segmentos pueden ralentizar las consultas. Considera dividir los archivos muy grandes.
+Comprueba el número de segmentos con `status`. Los documentos grandes con muchos segmentos
+pueden ralentizar las consultas. Considera dividir los archivos muy grandes.
 
 ### "Path outside BASE_DIR"
 
-La ruta debe estar dentro de uno de los directorios raíz configurados: `BASE_DIR`, una entrada de `BASE_DIRS` o una ruta indicada mediante `--base-dir` en la CLI. Usa una ruta absoluta.
+La ruta debe estar dentro de uno de los directorios raíz configurados: `BASE_DIR`, una entrada
+de `BASE_DIRS` o una ruta indicada mediante `--base-dir` en la CLI. Usa una ruta absoluta.
 
 ### "BASE_DIRS must be a JSON array..."
 
@@ -447,7 +470,8 @@ La ruta debe estar dentro de uno de los directorios raíz configurados: `BASE_DI
 
 ## Colaboración
 
-Las contribuciones son bienvenidas. Consulta [CONTRIBUTING.md](CONTRIBUTING.md) para preparar el entorno y revisar las pautas.
+Las contribuciones son bienvenidas. Consulta [CONTRIBUTING.md](CONTRIBUTING.md) para preparar
+el entorno y revisar las pautas.
 
 ## Licencia
 
@@ -459,4 +483,6 @@ Licencia MIT. Uso gratuito para fines personales y comerciales.
 
 ## Agradecimientos
 
-Creado con el [Model Context Protocol](https://modelcontextprotocol.io/) de Anthropic, [LanceDB](https://lancedb.com/) y [Transformers.js](https://huggingface.co/docs/transformers.js).
+Creado con el [Model Context Protocol](https://modelcontextprotocol.io/) de Anthropic,
+[LanceDB](https://lancedb.com/) y
+[Transformers.js](https://huggingface.co/docs/transformers.js).