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, Markdown y de 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.
Se ejecuta localmente: El análisis de documentos, los embeddings, el almacenamiento y la búsqueda se ejecutan en tu 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 potencia los términos técnicos exactos.
Embeddings configurables: Elige un modelo de embeddings de Hugging Face que se ajuste al idioma y al dominio de tus documentos.
Segmentación semántica: Los documentos se dividen en los límites de los temas en lugar de por recuentos fijos de caracteres. Los bloques de código Markdown permanecen intactos.
MCP y CLI: Usa el mismo índice desde una herramienta de codificación con IA o directamente desde la terminal.
No se requiere clave de API, Docker, Python ni una base de datos externa.
Related MCP server: cowork-semantic-search
Node.js 22 o posterior
Acceso a Internet en el primer uso para descargar el paquete npm y el modelo de embeddings
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
con archivos. Reemplaza /absolute/path/to/your/documents a continuación con la ruta absoluta
del directorio.
mcp-local-rag utiliza el protocolo MCP estándar a través de un servidor stdio local, por lo que funciona con herramientas de codificación con IA y otros hosts MCP que admiten servidores MCP locales.
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.
Para Claude Code: Ejecuta este comando:
claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-ragPara Codex: Añade 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: Añade 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: Añade a ~/.cursor/mcp.json:
{
"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 embeddings 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 la sincronización se complete:
What does the API documentation say about authentication?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.
Algunos conjuntos de documentos no pueden enviarse a un servicio de embeddings alojado debido a la confidencialidad o a la política organizacional. Mantener el índice local los hace buscables sin añadir un costo de API por consulta.
La búsqueda semántica por sí sola puede omitir identificadores exactos que son importantes en la documentación técnica. El reordenamiento por palabras clave mantiene esos términos visibles sin renunciar a la recuperación en lenguaje natural.
Entrada | Cómo ingerir |
PDF, DOCX, TXT, Markdown | Ingesta de archivos o sincronización de directorios |
HTML ya obtenido por el cliente |
|
Texto plano o Markdown en memoria |
|
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 admitidos por 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.
Herramienta | Propósito |
| Reconciliar el índice con todas las raíces configuradas o una ruta |
| Consultar un trabajo de sincronización en ejecución |
| Ingerir o reemplazar un archivo |
| Ingerir texto, Markdown o HTML ya retenido por el cliente |
| Buscar con coincidencia semántica y refuerzo de palabras clave |
| Leer los fragmentos circundantes de un resultado de búsqueda |
| Mostrar los archivos admitidos y su estado de ingesta |
| Eliminar un archivo indexado o un elemento de |
| Mostrar el estado del índice y de la búsqueda |
sync_start ingiere archivos nuevos y modificados, omite archivos idénticos por bytes y elimina
las 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 se convierta en succeeded o failed. La sincronización no genera
subtítulos visuales. Establece STORE_IMAGES=true en el entorno del servidor MCP para almacenar
imágenes admitidas de PDF y DOCX para archivos nuevos o modificados seleccionados por la
sincronización; los archivos sin cambios permanecen omitidos.
El proceso del servidor conserva solo un trabajo de sincronización. Un trabajo más nuevo reemplaza un registro finalizado, y reiniciar el servidor lo descarta.
ingest_file acepta PDF, DOCX, TXT y Markdown. Las rutas de archivo MCP deben ser absolutas y
deben permanecer dentro de una raíz de documentos configurada:
Ingest the document at /Users/me/docs/api-spec.pdf.Volver a ingerir la misma ruta reemplaza sus fragmentos existentes.
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 del fragmento, la
puntuación de relevancia y cualquier imagen almacenada en ese fragmento. MCP devuelve cada imagen
como un bloque de contenido de imagen emparejado con su identidad de resultado; la CLI query
incluye un arreglo images de { imageIndex, mimeType, data } en cada resultado. Pasa 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 scope absoluto opcional, o
una lista de prefijos. Un prefijo coincide con la ruta exacta y sus descendientes.
Usa 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 origen proporcionado. Reutilizar el mismo origen actualiza el contenido existente.
Respeta los términos y los derechos de autor del sitio de origen al indexar contenido externo.
El modo visual añade un subtítulo generado para páginas PDF con muchas figuras. Es opcional y no carga un modelo de visión durante la ingesta normal.
Ingest /Users/me/docs/research-paper.pdf with visual: true.npx mcp-local-rag ingest ./docs/research-paper.pdf --visualEl almacenamiento de imágenes es independiente de los subtítulos visuales. Establece
STORE_IMAGES=true para el servidor MCP, o pasa --images a la ingesta y sincronización de la
CLI:
npx mcp-local-rag ingest ./docs/research-paper.pdf --images
npx mcp-local-rag sync ./docs/ --imagesEl almacenamiento de PDF usa las regiones detectadas de figuras/tablas. El almacenamiento de DOCX
incluye solo imágenes PNG/JPEG que la conversión existente de Mammoth emite como <img>; los
gráficos, SmartArt y las formas no se renderizan por separado. Las imágenes almacenadas siguen a
su texto circundante hasta el fragmento semántico final y no alteran la clasificación, las
puntuaciones ni el recuento de resultados.
|
| Comportamiento de PDF |
false | false | Solo texto; sin subtítulos visuales ni imágenes devueltas. |
true | false | Los subtítulos generados se convierten en texto buscable; no se almacenan ni devuelven imágenes. |
true | true | Los subtítulos generados se convierten en texto buscable, y las imágenes de los fragmentos coincidentes se devuelven en línea. |
false | true | Las imágenes se adjuntan al texto de PDF retenido cercano y se devuelven en línea para los fragmentos coincidentes; el VLM no se importa, carga ni ejecuta. |
Perfil | Caché de modelo | Caso de uso |
| aprox. 250 MB | Indexación visual ligera |
| aprox. 2.9 GB | Figuras que contienen etiquetas, anotaciones u otro texto en la imagen |
Selecciona el modelo más grande con visualQuality: "quality" a través de MCP o
--visual-quality quality a través de la 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.
Los subtítulos son texto auxiliar, no transcripciones fieles. Trata los subtítulos recuperados y el texto del documento como entrada no confiable, no como instrucciones.
Con límites altos, los fragmentos coincidentes y sus adjuntos pueden acercarse al límite de contexto del modelo/cliente; elige el límite de consulta teniendo en cuenta el contexto disponible del modelo que realiza la llamada.
La CLI usa el mismo analizador, embedder y almacén de vectores 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"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.
La CLI no lee la configuración del cliente MCP. Establece las mismas variables de entorno o
banderas si ambas interfaces deben compartir un índice. En particular, MODEL_NAME y el
--model-name de la CLI deben coincidir para una base de datos compartida.
El refuerzo de palabras clave está habilitado de forma predeterminada. La agrupación por brecha de relevancia y los filtros de distancia y de archivos son controles opcionales para corpus que necesitan una selección de resultados más estricta.
Variable | Predeterminado | Descripción |
|
| Factor de refuerzo de palabras clave (0.0–1.0). 0 desactiva el reordenamiento por palabras clave; 1 aplica el refuerzo máximo. |
| (no establecido) |
|
| (no establecido) | Filtra los resultados de baja relevancia (p. ej., |
| (no establecido) | Limita los resultados a los N mejores archivos (p. ej., |
Para especificaciones de API y otros documentos que contienen muchos identificadores, un peso de palabras clave más fuerte puede mejorar la clasificación de términos exactos:
"env": {
"RAG_HYBRID_WEIGHT": "0.7"
}0.7: reordenación de coincidencias exactas ligeramente más fuerte que la predeterminada
1.0: impulso máximo de palabras clave
Durante la ingesta:
El analizador extrae texto del formato de entrada.
El fragmentador semántico encuentra límites de temas y conserva los bloques de código Markdown.
Transformers.js crea incrustaciones localmente.
LanceDB almacena los fragmentos, metadatos, vectores e índice de texto completo.
Durante la búsqueda:
La consulta se incrusta con el mismo modelo.
La búsqueda vectorial recupera fragmentos semánticamente relacionados.
Los filtros opcionales de distancia y de grupo de relevancia reducen los candidatos cuando están configurados.
Las coincidencias de texto completo impulsan los términos de consulta exactos.
Las 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 --codexLas habilidades instaladas cubren la formulación de consultas, el refinamiento de resultados y la ingesta de HTML. Pida al asistente que use la habilidad mcp-local-rag explícitamente si no se activa automáticamente.
El servidor MCP lee variables de entorno. La CLI acepta las variables de entorno globales y las banderas enumeradas; el almacenamiento de imágenes en la ingesta y sincronización de la CLI solo está habilitado con --images.
Variable de entorno | Bandeira de CLI | Predeterminado | Descripción |
|
| Directorio actual | Una raíz de documentos; la bandera de CLI es repetible en |
| N/A | (sin establecer) | Matriz JSON de raíces de documentos; tiene prioridad sobre |
|
|
| Ubicación de la base de datos vectorial |
|
|
| Directorio de caché de modelos |
|
|
| Modelo de incrustación de Hugging Face |
|
|
| Tamaño máximo de archivo en bytes |
|
|
| Longitud mínima de fragmento en caracteres (1–10000) |
| N/A |
| Solo servidor MCP: almacena imágenes PDF/DOCX compatibles y las devuelve con los fragmentos coincidentes. La CLI usa |
| N/A |
| Dispositivo de ejecución de ONNX Runtime |
| N/A |
| Tipo de dato de incrustación pasado al modelo seleccionado |
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:
Banderas de CLI --base-dir <ruta> (repetibles en ingest, list y sync)
BASE_DIRS
BASE_DIR
Directorio actual
Cada fuente reemplaza la fuente de menor prioridad en lugar de fusionarse con ella. Una configuración de BASE_DIRS no vá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 listDB_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.
Establezca MODEL_NAME o pase --model-name para elegir un modelo de incrustación de Hugging Face que se ajuste al idioma y dominio de sus documentos.
mcp-local-rag genera incrustaciones con agrupación de medias y normalización L2. Al elegir un modelo, verifique si estos ajustes coinciden con su configuración de inferencia recomendada, ya que el método de agrupación puede afectar la calidad de la recuperación.
Cambiar MODEL_NAME, RAG_DEVICE o RAG_DTYPE puede hacer que los vectores existentes sean incompatibles. Use un DB_PATH nuevo o elimine el índice existente y vuelva a ingerir después de cambiar la configuración de incrustación.
Un ejemplo de modelo para documentos en inglés es Xenova/bge-small-en-v1.5.
El acceso a archivos está restringido a las raíces de BASE_DIR, BASE_DIRS o --base-dir de la CLI.
Se rechazan los enlaces simbólicos que resuelven fuera de cada raíz configurada.
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 de CLI o MCP contra el mismo DB_PATH. Las consultas de solo lectura pueden ejecutarse mientras una sincronización está activa.
Haga una copia de seguridad de un índice copiando su directorio DB_PATH mientras no haya un escritor activo.
Los documentos deben ingerirse primero. Ejecute "List all ingested files" para verificar.
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.
El límite predeterminado es 100MB. Divida archivos grandes o aumente MAX_FILE_SIZE.
Verifique el número de fragmentos con status. Los documentos grandes con muchos fragmentos pueden ralentizar las consultas. Considere dividir archivos muy grandes.
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 --base-dir de la CLI). Use rutas absolutas.
BASE_DIRS acepta una matriz JSON de una o más cadenas de ruta no vacías:
Válido: BASE_DIRS='["/Users/me/work","/Users/me/specs"]'
No válido: BASE_DIRS=/a:/b (la sintaxis de delimitador no es compatible)
No válido: BASE_DIRS='[]' (matriz vacía)
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
¡Las contribuciones son bienvenidas! Consulte CONTRIBUTING.md para la configuración y las pautas.
Licencia MIT. Gratuita para uso personal y comercial.
Building a Local RAG for Agentic Coding: Análisis técnico en profundidad del diseño de fragmentación semántica y búsqueda híbrida.
Construido con Model Context Protocol de Anthropic, LanceDB y Transformers.js.
Delete a previously ingested file or data from the vector database. Use filePath for files ingested via ingest_file, or source for data ingested via ingest_data. Either filePath or source must be provided. Returns deleted (operation succeeded), removedChunks, and existed (whether anything was actually present).
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | Source identifier used in ingest_data. Examples: "https://example.com/page", "clipboard://2024-12-30" | |
| filePath | No | Absolute path to the file (for ingest_file). Example: "/Users/user/documents/manual.pdf" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Mentions return fields but does not disclose side effects, permissions, or error cases (e.g., what happens if nothing matches).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no redundancy. Purpose, usage, and return are clearly separated and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameters, constraints, and return values. Lacks explanation of edge cases (both params provided or neither) but is generally sufficient given tool simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, yet description adds context by linking each parameter to the specific ingestion method and clarifying the mutual exclusivity requirement, which is not in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (delete) and object (previously ingested file/data from vector database). Distinguishes from sibling tools which are for ingestion, listing, querying, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use filePath vs. source and states that at least one must be provided. Could further specify behavior if both are given or if the item does not exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest in-memory content as a string (use ingest_file for files on disk). The source identifier enables re-ingestion to update existing content. Returns { filePath, chunkCount, timestamp, fileTitle }.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The content to ingest (text, HTML, or Markdown) | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses return format but does not discuss side effects, idempotency, or rate limits. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste: first sentence states purpose and sibling alternative, second sentence adds key behavioral detail and return format. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given nested object parameters and no output schema, the description covers purpose, parameters with examples, and return values. Lacks error conditions or prerequisites, but sufficient for most agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds meaning to both parameters: content format types and detailed metadata source examples. Schema coverage is 50% but description compensates with concrete usage guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states it ingests in-memory content as a string and differentiates from ingest_file for files on disk. Specific verb+resource with clear distinction from a sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions when to use this tool ('use ingest_file for files on disk') and hints at re-ingestion capability. Lacks explicit when-not-to-use scenarios, but the sibling distinction is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest a document file (PDF, DOCX, TXT, MD) into the vector database. Path must be absolute; re-ingesting the same path replaces its existing data. Returns { filePath, chunkCount, timestamp, fileTitle }.
| Name | Required | Description | Default |
|---|---|---|---|
| visual | No | Run VLM captioning on figure pages (PDF only; default false). | |
| filePath | Yes | Absolute path to the file to ingest. Example: "/Users/user/documents/manual.pdf" | |
| visualQuality | No | VLM profile when visual is true (default "fast"). "quality" is more accurate on figures with in-image text but much heavier and slower. Ignored when visual is false. | fast |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that ingestion is a write operation, that re-ingesting replaces existing data, and that it supports VLM captioning for PDFs with different quality profiles. It also specifies the return structure. This is thorough for a tool of this complexity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence front-loads the main purpose, and the second adds critical behavioral details. No extra words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, and no nested objects, the description covers input requirements (absolute path), behavior (replace on re-ingest), return fields, and an optional feature (VLM captioning). It briefly addresses PDF-only behavior. Missing details like error handling or unsupported file types, but overall sufficient for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds context like 'Path must be absolute' and the effect of re-ingesting, but the schema already describes each parameter adequately. No additional semantic depth beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Ingest', the resource 'document file (PDF, DOCX, TXT, MD)', and the destination 'into the vector database'. It distinguishes from siblings like 'delete_file' and 'list_files' by specifying file ingestion. The mention of absolute path and re-ingest behavior adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context: 'Path must be absolute' and 're-ingesting the same path replaces its existing data'. However, it does not explicitly state when to use this tool versus alternatives (e.g., 'ingest_data'), nor does it give exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List supported files (PDF, DOCX, TXT, MD) under the configured base directories and whether each is ingested. Returns { baseDirs, files, sources }; sources lists ingested items reported apart from the file scan, chiefly ingest_data content (web pages, clipboard, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. "/docs/api" matches "/docs/api/x.md" but not "/docs/apiv2". Must be absolute (server OS style); a relative prefix matches nothing. A prefix outside every base directory yields an empty files list, so compare it against the baseDirs in the response before concluding no files exist. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds value by explaining that 'sources' contains ingested items like web pages/clipboard, and that files are scanned from base directories. It doesn't explicitly state this is read-only or describe side effects, but the 'list' verb implies safety. Some edge behavior (e.g., invalid scope yielding empty files list) is only visible in the schema, not the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: the first states the core purpose, and the second explains the return structure and the 'sources' nuance. There is no redundancy or filler, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with one optional parameter and no output schema, the description sufficiently covers the purpose, return shape, and the non-obvious 'sources' concept. It doesn't need to explain return values in detail since the return shape is stated. Path edge cases are handled in the schema, so the description is complete enough for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of the parameter 'scope' with a detailed explanation of prefix matching and path constraints. The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('list') and resource ('supported files (PDF, DOCX, TXT, MD)') under configured base directories, plus the ingestion status. This clearly distinguishes it from sibling tools like ingest_file, delete_file, and sync_status, which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for inspecting the file inventory and its ingestion status, which is a distinct use case. It also explains the return shape to set expectations. However, it doesn't explicitly mention when not to use it or reference sibling alternatives, though the purpose is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search ingested documents with hybrid keyword + semantic matching. Returns results sorted by relevance, each with filePath, chunkIndex, text, fileTitle, score (0 = best, higher = worse), and source (for ingest_data items).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 10, range 1-20). Lower favors precision, higher recall. | |
| query | Yes | Search query. Preserve specific user terms (for keyword match); add context when the query is vague (for semantic match). | |
| scope | No | Optional absolute path prefix(es) — one string or a list (unioned) — restricting results to a filePath equal to or under a prefix. "/docs/api" matches "/docs/api/auth.md" but not "/docs/apiv2". Must be absolute (server OS style); a relative prefix matches nothing — derive one from a filePath returned by an earlier query, or omit scope. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description details return fields, sorting by relevance, and score meaning (0=best, higher=worse). It lacks pagination details but is generally transparent for a read-only search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with clear, front-loaded purpose and a concise list of return fields. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers purpose, behavior, and return fields comprehensively. Context from sibling tools and parameter count is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds value by listing output fields not present in schema, enhancing parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches ingested documents using hybrid keyword and semantic matching, and lists the return fields. It is distinct from sibling tools like list_files and read_chunk_neighbors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (for searching documents) but does not explicitly state when not to use or provide alternatives among siblings. No exclusion criteria mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the chunks immediately before and after a query_documents result, in the same document, for more surrounding context. Pass chunkIndex from the result plus exactly one of filePath (ingest_file) or source (ingest_data). Returns the target chunk (isTarget: true) and its neighbors, ascending by chunkIndex; an out-of-range chunkIndex returns []. Defaults: before=2, after=2 (max 50 each).
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Number of chunks to retrieve after the target (0–50, default 2). | |
| before | No | Number of chunks to retrieve before the target (0–50, default 2). | |
| source | No | Source identifier (for ingest_data documents). Provide exactly one of filePath or source. Examples: "https://example.com/page", "clipboard://2024-12-30". | |
| filePath | No | Absolute path to the file (for ingest_file documents). Provide exactly one of filePath or source. Example: "/Users/user/documents/manual.pdf". | |
| chunkIndex | Yes | Zero-based target chunk index (non-negative integer). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It details the behavior (reads neighbors), return structure (target with isTarget: true, ascending order), edge case (out-of-range returns []), and limits (defaults before/after=2, max 50 each). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise, and front-loaded with the most important information. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully covers the tool's behavior, parameter usage, return structure, and edge cases. It ties to the sibling tool query_documents, providing necessary context for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with descriptions for all five parameters. The description adds value by explaining the mutual exclusivity of filePath and source, the default values for before and after, and the connection to query_documents for chunkIndex.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb ('Read'), the resource ('chunks immediately before and after'), and the context ('in the same document, for more surrounding context'). It ties the tool to query_documents, distinguishing it from siblings like query_documents itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit instructions on parameter usage: pass chunkIndex from query_documents and exactly one of filePath or source. It also states defaults and max limits. However, it doesn't explicitly state when not to use this tool or mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get index status: { documentCount, chunkCount, memoryUsage (MB), uptime (s), ftsIndexEnabled, searchMode }.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not explicitly state read-only nature or other behavioral traits like cost or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, description fully covers functionality and return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; description adds value by listing return fields beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states it gets index status and lists return fields, clearly distinguishing from sibling tools like delete_file or query_documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives, but the simple nature (no parameters) makes usage implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reconcile the index with the files on disk: ingest new and changed files, leave unchanged files alone, and remove index entries for files that are gone. Returns { jobId } without waiting for the run to finish; poll sync_status with that jobId for progress and the final outcome. Only one job is kept, and it is lost when the server process exits.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Optional absolute path to a file or directory inside a configured base directory; list_files returns those directories as baseDirs. A file synchronizes only itself and a directory only its own subtree, leaving every path outside it untouched. Omit it to synchronize every configured base directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: asynchronous execution (returns jobId without waiting), single-job constraint, and job loss on server exit. It also notes that index entries are removed for missing files, making side effects transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: the first states the core purpose, the second explains the return value and polling, and the third adds a critical lifecycle constraint. Every sentence contributes essential information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one optional parameter, no annotations, and no output schema, the description fully captures the tool's behavior, return format, and lifecycle. It also refers to sync_status for progress, completing the operational picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a 100% coverage description for the 'path' parameter, explaining its optionality, scope, and behavior. The tool description adds no extra parameter context, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Reconcile the index with the files on disk' and enumerates specific behaviors (ingest new/changed, leave unchanged, remove gone entries). This distinguishes it from sibling tools like ingest_file or delete_file, which handle single files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (reconciling an index with disk state) and implicitly contrasts with sync_status for polling. It lacks explicit 'when not to use' statements or alternative tool names, but the context is unambiguous enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current or latest sync job record: { jobId, state ("running" | "succeeded" | "failed"), total (null until scanning has counted the files on disk), completed (upserted + skipped + empty; pruned is counted separately), summary { upserted, skipped, empty, pruned }, warnings, error (null unless the job failed) }. An unknown jobId means the job was replaced by a newer one or lost with a previous server process.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | Identifier returned by sync_start. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes full responsibility for behavioral disclosure. It transparently explains field nullability (total null until scanning, error null unless failed), the enumerated state values, and the unknown jobId case. This gives the agent a complete picture of expected behavior and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but intentionally structured to mirror the returned object, making the field relationships clear. The second sentence adds essential edge-case information without fluff. It is compact given the amount of detail about the response shape.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description fully defines every return field and its conditional behavior, including a nested summary object. It also references sync_start and server process loss to situate usage, making the tool self-sufficient in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers jobId ('Identifier returned by sync_start') at 100% coverage. The description adds extra meaning beyond the schema by explaining the consequences of an unknown jobId, which enriches the parameter's semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get the current or latest sync job record', providing a specific verb+resource. It further details the exact output shape including state values, total/completed semantics, and nested summary, clearly distinguishing it from sibling tools like sync_start.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage: after starting a sync job, call this to retrieve its status. It explains the meaning of an unknown jobId (replaced or lost with server process), which guides the agent on interpreting results. However, it does not explicitly name alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.17.3list_files1 field changedInput schema / properties / scope / descriptionPrevious value: -"Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. \"/docs/api\" matches \"/docs/api/x.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed."New value: +"Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. \"/docs/api\" matches \"/docs/api/x.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing. A prefix outside every base directory yields an empty files list, so compare it against the baseDirs in the response before concluding no files exist. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed."sync_startsync_statusv0.16.1list_files1 field changedInput schema / properties / scopeAdded value: +{
+ "description": "Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. \"/docs/api\" matches \"/docs/api/x.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed.",
+ "oneOf": [
+ {
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ ]
+}v0.15.3ingest_data1 field changedInput schema / properties / metadata / properties / format / descriptionPrevious value: -"Content format: \"text\", \"html\", or \"markdown\""New value: +"Content format: text (plain/copied text), html (fetched web pages), or markdown."ingest_file2 fields changedInput schema / properties / visual / descriptionPrevious value: -"If true and the file is a PDF, run VLM captioning on figure pages. No effect on non-PDF files."New value: +"Run VLM captioning on figure pages (PDF only; default false)."Input schema / properties / visualQuality / descriptionPrevious value: -"VLM profile to use when visual is true. \"fast\" (default) is the lightweight SmolVLM-256M; \"quality\" is Qwen2.5-VL-3B-Instruct-ONNX with higher fidelity on figures with in-image text (~10x model-cache footprint, ~2x per-page inference). The server also accepts an empty string as a synonym for omitted (normalized to \"fast\"). Silently ignored when visual is false."New value: +"VLM profile when visual is true (default \"fast\"). \"quality\" is more accurate on figures with in-image text but much heavier and slower. Ignored when visual is false."query_documents3 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (default: 10, range: 1-20). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."New value: +"Max results (default 10, range 1-20). Lower favors precision, higher recall."Input schema / properties / query / descriptionPrevious value: -"Search query. Include specific terms and add context if needed."New value: +"Search query. Preserve specific user terms (for keyword match); add context when the query is vague (for semantic match)."Input schema / properties / scopeAdded value: +{
+ "description": "Optional absolute path prefix(es) — one string or a list (unioned) — restricting results to a filePath equal to or under a prefix. \"/docs/api\" matches \"/docs/api/auth.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing — derive one from a filePath returned by an earlier query, or omit scope.",
+ "oneOf": [
+ {
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ ]
+}read_chunk_neighbors2 fields changedInput schema / properties / filePath / descriptionPrevious value: -"Absolute path to the file (for documents ingested via ingest_file). Example: \"/Users/user/documents/manual.pdf\". Provide either filePath or source, not both."New value: +"Absolute path to the file (for ingest_file documents). Provide exactly one of filePath or source. Example: \"/Users/user/documents/manual.pdf\"."Input schema / properties / source / descriptionPrevious value: -"Source identifier used in ingest_data (for data ingested via ingest_data). Examples: \"https://example.com/page\", \"clipboard://2024-12-30\". Provide either filePath or source, not both."New value: +"Source identifier (for ingest_data documents). Provide exactly one of filePath or source. Examples: \"https://example.com/page\", \"clipboard://2024-12-30\"."v0.15.0query_documents3 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (default: 10). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."New value: +"Maximum number of results to return (default: 10, range: 1-20). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."Input schema / properties / limit / maximumAdded value: +20Input schema / properties / limit / minimumAdded value: +1v0.14.1ingest_file1 field changedInput schema / properties / visualQualityAdded value: +{
+ "default": "fast",
+ "description": "VLM profile to use when visual is true. \"fast\" (default) is the lightweight SmolVLM-256M; \"quality\" is Qwen2.5-VL-3B-Instruct-ONNX with higher fidelity on figures with in-image text (~10x model-cache footprint, ~2x per-page inference). The server also accepts an empty string as a synonym for omitted (normalized to \"fast\"). Silently ignored when visual is false.",
+ "enum": [
+ "fast",
+ "quality"
+ ],
+ "type": "string"
+}v0.14.0ingest_file1 field changedInput schema / properties / visualAdded value: +{
+ "description": "If true and the file is a PDF, run VLM captioning on figure pages. No effect on non-PDF files.",
+ "type": "boolean"
+}v0.13.0read_chunk_neighborsv1.0.0delete_fileingest_dataquery_documents2 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (default: 5, max recommended: 20)"New value: +"Maximum number of results to return (default: 10). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."Input schema / properties / query / descriptionPrevious value: -"Natural language search query (e.g., \"transformer architecture\", \"API documentation\")"New value: +"Search query. Include specific terms and add context if needed."ingest_filelist_filesquery_documentsstatusEach tool has a distinct purpose: sync_status tracks job progress while status reports index stats; ingest_file vs ingest_data clearly separate file-based and in-memory ingestion; query_documents, read_chunk_neighbors, delete_file, list_files, and sync_start all target different operations. No two tools are likely to be confused.
Most tools follow a verb_noun pattern (query_documents, ingest_file, delete_file, list_files, read_chunk_neighbors), but sync_status, sync_start, and status deviate, using noun compounds or a standalone noun. The mix is readable but not uniform.
9 tools is well-scoped for a local RAG server, covering ingestion (file and data), deletion, querying, context expansion, file listing, and status/sync operations without unnecessary redundancy or bloat.
The set covers the core lifecycle: ingest (file/data), delete, search, and context retrieval. Minor gaps include no direct way to fetch all chunks of a specific document or a bulk clear operation, but these can be worked around with existing tools like query_documents and sync_start.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Ingest, manage, and retrieve documents for RAG-powered AI applications
Versioned documentation registry and semantic search for AI tools and coding assistants.
Self-hosted AI-native knowledge workspace with hybrid search, GraphRAG, and MCP.
Search everything you save: YouTube, articles, podcasts, PDFs, Notion, Obsidian. API key or OAuth.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/shinpr/mcp-local-rag'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
