> ## Documentation Index
> Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Introducción a las herramientas MCP de Linkly AI
> Presentación de las herramientas que Linkly AI ofrece a los asistentes de IA
## Visión general de herramientas
Linkly AI expone siete herramientas a los asistentes de IA a través de MCP (Model Context Protocol), conformando un flujo de trabajo progresivo de acceso a documentos:
```
search → grep or outline → read
```
Tres herramientas de utilidad adicionales están disponibles: `list_libraries` (listar bibliotecas de conocimiento), `explore` (visión general de colecciones de documentos) y `find_paths` (localizar rutas de carpeta por palabra clave para alimentar el `path_glob` de `search`).
Buscar documentos y encontrar resultados relevantes
Ver el esquema del documento para comprender su estructura
Encontrar patrones de texto específicos con coincidencia regex
Leer el contenido del documento para obtener información detallada
Listar las bibliotecas de conocimiento y sus cantidades de documentos
Visión general de los temas y la estructura de la colección de documentos
Localizar rutas de carpeta por palabra clave para alimentar el `path_glob`
de `search`
Estas siete herramientas trabajan en conjunto para permitir que los asistentes de IA obtengan información de contexto de manera eficiente desde sus documentos locales.
## Búsqueda (search)
Busca en los documentos locales indexados y devuelve la lista de resultados más relevantes.
### Parámetros
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
| ----------------- | --------- | ----------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | string | Sí | — | Palabras clave o frase de búsqueda |
| `limit` | number | No | 20 | Número máximo de resultados (1-50) |
| `doc_types` | string\[] | No | Todos | Filtrar por tipo de documento, ej. `["pdf", "md", "docx", "pptx", "epub"]` |
| `library` | string | No | — | Restringir a una biblioteca específica. Local: un nombre simple o `local://`; nube: `cloud:///` (solo `--remote`). Utilice `list_libraries` para ver las bibliotecas disponibles |
| `path_glob` | string | No | — | Filtrar por ruta de archivo. El patrón se busca como **subcadena** de la ruta — puede aparecer en cualquier posición, sin `*` al inicio o al final. `*` coincide con cualquier carácter (incluido `/`), `?` con un solo carácter. Siempre distingue mayúsculas y minúsculas. Una ruta de directorio completa (`/Users/me/notes/`) limita la búsqueda a ese directorio. Cuando la ruta real es desconocida, llame primero a `find_paths` |
| `modified_after` | string | No | — | Límite inferior inclusivo de la fecha de modificación. ISO 8601 UTC: fecha simple `2024-01-01` (interpretada como `00:00:00Z`) o RFC 3339 completo `2024-01-01T00:00:00Z` |
| `modified_before` | string | No | — | Límite superior inclusivo de la fecha de modificación. Mismo formato que `modified_after` |
| `time_sort` | string | No | `default` | Reordenamiento temporal: `default` (preserva el orden de relevancia) / `newest` (más reciente primero) / `oldest` (más antiguo primero). Solo se reordena después de seleccionar y deduplicar el conjunto de candidatos |
| `output_format` | string | No | `markdown` | Establezca `json` para obtener salida JSON estructurada |
Si el modelo vectorial aún se está descargando, la búsqueda degradará
automáticamente a modo de solo palabras clave, sin afectar el uso.
**Acerca del filtrado y ordenamiento por fecha:**
* Cuando el usuario indique una ventana temporal explícita ("el mes pasado", "en 2024", "los últimos tres meses"), use `modified_after` / `modified_before`.
* Cuando el usuario solo dice "reciente", "más reciente", "más antiguo" sin un rango fijo, use `time_sort=newest` u `oldest`.
* Ambos pueden combinarse: "el más antiguo en 2024" es `modified_after=2024-01-01` + `modified_before=2024-12-31` + `time_sort=oldest`.
* Para fechas relativas ("el mes pasado"), lea primero la hora UTC actual desde el campo `[meta] now=...` al final de cualquier respuesta de herramienta, luego calcule la fecha — vea [Metadatos de respuesta](#metadatos-de-respuesta) más abajo.
### Campos de respuesta
Cada resultado de búsqueda incluye la siguiente información:
| Campo | Descripción |
| ------------- | --------------------------------------------------------------------------- |
| `doc_id` | Identificador único del documento para llamadas posteriores de outline/read |
| `title` | Título del documento |
| `path` | Ruta del archivo |
| `relevance` | Puntuación de relevancia (0-1) |
| `word_count` | Cantidad de palabras del documento |
| `total_lines` | Número total de líneas del documento |
| `has_outline` | Si tiene esquema disponible |
| `modified_at` | Fecha de última modificación |
| `keywords` | Lista de palabras clave extraídas |
| `snippet` | Fragmento del contenido coincidente |
### Ejemplos de uso
```bash theme={null}
# Vía CLI
linkly search "project management best practices" --limit 10
# Filtrar por tipo de documento
linkly search "quarterly report" --type pdf,docx --json
# Buscar dentro de una biblioteca específica
linkly search "deep learning" --library my-research --limit 10
# Filtrar por ruta de archivo
linkly search "report" --path-glob "*2024*"
# Limitar por ventana temporal (informes trimestrales del Q3 2024)
linkly search "quarterly report" --modified-after 2024-07-01 --modified-before 2024-09-30
# Ordenar por fecha ("el más reciente", "el más antiguo" — sin rango fijo)
linkly search "weekly retro" --time-sort newest --limit 5
```
## Esquema (outline)
Obtiene el esquema estructurado y los metadatos de uno o más documentos, ayudando a comprender rápidamente la estructura del documento y localizar las secciones objetivo.
### Parámetros
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
| --------------- | --------- | ----------- | -------------- | ---------------------------------------------------------------------------------------- |
| `doc_ids` | string\[] | Sí | — | Lista de IDs de documentos (de los resultados de búsqueda) |
| `expand` | string\[] | No | Automático | IDs de nodos a expandir (ej. `["2", "3.1"]`); si se omite, se muestran todos los niveles |
| `output_format` | string | No | `markdown` | Establezca `json` para obtener salida JSON estructurada |
### Cuándo usar el esquema
| Escenario | Recomendación |
| ---------------------------------- | ------------------------------------------------------------------ |
| Documento > 50 líneas con esquema | Ver primero el esquema, luego leer las secciones objetivo |
| Documento corto (\< 50 líneas) | Omitir el esquema, usar directamente `read` para el texto completo |
| Documento con `has_outline: false` | Usar `grep` para encontrar patrones o `read` página por página |
La función de esquema funciona mejor con **PDF con marcadores**, **Markdown**,
**DOCX**, **PowerPoint (PPTX)** y **EPUB**. Es especialmente efectiva al leer documentos
extensos y libros. El soporte de esquema para texto plano y PDF sin marcadores
se añadirá en futuras iteraciones.
### Ejemplos de uso
```bash theme={null}
# Ver esquema de un solo documento
linkly outline abc123
# Ver múltiples documentos a la vez
linkly outline id1 id2 id3
# Salida en formato JSON
linkly outline abc123 --json
```
## Grep
Localiza líneas específicas dentro de un solo documento mediante un patrón regex. Es ideal para documentos con `has_outline=false` donde el esquema no está disponible. Utilícelo después de `search` para ubicar posiciones exactas de nombres, fechas, términos, identificadores o cualquier patrón, y luego use `read` con offset para ver el contexto completo. Funciona con todos los tipos de documentos (PDF, Markdown, DOCX, PPTX, EPUB, TXT, HTML). Para buscar en múltiples documentos, llame a grep una vez por documento.
### Parámetros
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
| ------------------ | ------- | ----------- | -------------- | -------------------------------------------------------------------------------------------------- |
| `pattern` | string | Sí | — | Patrón de expresión regular a buscar |
| `doc_id` | string | Sí | — | ID del documento en el que buscar (de los resultados de búsqueda) |
| `context` | number | No | 3 | Líneas de contexto antes y después de cada coincidencia |
| `before` | number | No | — | Líneas de contexto antes de cada coincidencia (anula `context`) |
| `after` | number | No | — | Líneas de contexto después de cada coincidencia (anula `context`) |
| `case_insensitive` | boolean | No | false | Coincidencia sin distinguir mayúsculas y minúsculas |
| `output_mode` | string | No | `content` | `content` (líneas coincidentes con contexto) o `count` (solo recuento, para previsualizar totales) |
| `limit` | number | No | 20 | Máximo de líneas coincidentes a devolver (máximo 100) |
| `offset` | number | No | 0 | Número de coincidencias a omitir para paginación |
| `output_format` | string | No | `markdown` | Establezca `json` para obtener salida JSON estructurada |
### Cuándo usar Grep vs Esquema
| Escenario | Recomendación |
| -------------------------------------------------------- | ----------------------------------- |
| Necesita encontrar un término, nombre o fecha específica | Use `grep` con el patrón |
| Necesita comprender la estructura general del documento | Use `outline` |
| El documento no tiene esquema (`has_outline: false`) | Use `grep` para localizar contenido |
| Busca patrones (correos, IDs, números, etc.) | Use `grep` con regex |
### Ejemplos de uso
```bash theme={null}
# Encontrar términos específicos en un documento
linkly grep "quarterly revenue" 456
# Búsqueda sin distinción de mayúsculas con contexto
linkly grep "error|warning" 1044 -C 3 -i
# Previsualizar recuento de coincidencias antes de leer
linkly grep "TODO" 591 --mode count
```
## Lectura (read)
Lee el contenido del documento con posicionamiento por número de línea y paginación, ideal para leer partes específicas de documentos extensos. El comportamiento de la herramienta Read es consistente con el del SDK de Claude AI, lo que garantiza resultados óptimos en diversos modelos de IA agéntica.
### Parámetros
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
| --------------- | ------ | ----------- | -------------- | ------------------------------------------------------- |
| `doc_id` | string | Sí | — | ID del documento (de los resultados de búsqueda) |
| `offset` | number | No | 1 | Línea de inicio (desde 1) |
| `limit` | number | No | 200 | Número de líneas a leer (máximo 500) |
| `output_format` | string | No | `markdown` | Establezca `json` para obtener salida JSON estructurada |
### Formato de contenido
La herramienta `Read` devuelve contenido con números de línea para facilitar la referencia y el posicionamiento:
```
1 # Project Requirements Document
2
3 ## 1. Project Background
4
5 This project aims to build an efficient knowledge management system...
6 Target users are enterprise R&D teams and individual knowledge workers.
```
### Estrategia de paginación
Para documentos extensos, se recomienda la lectura por bloques:
```bash theme={null}
# Primera página: líneas 1-200
linkly read --offset 1 --limit 200
# Segunda página: líneas 201-400
linkly read --offset 201 --limit 200
# Tercera página: líneas 401-600
linkly read --offset 401 --limit 200
```
Combinar con el esquema es aún más efectivo: localice el rango de líneas de la sección objetivo a través del esquema y luego use `read` para leer con precisión el contenido de ese intervalo.
### Ejemplos de uso
```bash theme={null}
# Leer el inicio del documento
linkly read abc123
# Leer un rango específico
linkly read abc123 --offset 120 --limit 80
# Formato JSON (adecuado para procesamiento programático)
linkly read abc123 --json
```
## Listar bibliotecas (list\_libraries)
Lista todas las bibliotecas de conocimiento configuradas por el usuario, junto con sus descripciones y cantidades de documentos.
### Parámetros
No se requieren parámetros.
### Casos de uso
* Cuando el usuario pregunta "¿qué bibliotecas tengo?"
* Antes de utilizar el parámetro `library` en `search`, para verificar el nombre de una biblioteca
```bash theme={null}
linkly list-libraries
```
## Explorar (explore)
Obtiene una visión panorámica de todos los documentos indexados o de una biblioteca específica. Devuelve la distribución de tipos de documentos, la estructura de directorios (con recuentos de archivos y medianas de cantidad de palabras) y las palabras clave principales (con atribución de origen).
### Parámetros
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
| --------- | ------ | ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `library` | string | No | — | Restringir a una biblioteca específica. Local: un nombre simple o `local://`; nube: `cloud:///` (solo `--remote`). Omita para explorar todos los documentos locales |
### Casos de uso
* El usuario desea saber qué contiene su base de conocimiento o colección de documentos
* El usuario no tiene un tema de búsqueda específico y desea descubrir temas y direcciones disponibles
* El asistente de IA necesita comprender la escala y la distribución temática para formular estrategias de búsqueda efectivas
Después de explorar, utilice las palabras clave y los nombres de directorio de la salida como pistas para consultas `search` posteriores.
```bash theme={null}
# Explorar todos los documentos
linkly explore
# Explorar una biblioteca específica
linkly explore --library my-research
```
## Localización de rutas (find\_paths)
Realiza una coincidencia aproximada de palabras clave contra el campo **ruta de archivo** de los documentos indexados, agrega las coincidencias a nivel de carpeta y devuelve los mejores candidatos. Está posicionada como una herramienta auxiliar de `search`: cuando el usuario nombra un contenedor ("en mis notas de Notion", "en mi carpeta de papers de Dropbox") sin conocer su ruta en el disco, llame primero a `find_paths` para descubrir la ruta real, y luego pásela como `path_glob` a `search`.
El nombre real de la carpeta en el disco a menudo difiere del nombre coloquial del usuario (por ejemplo, una exportación puede residir en `Notion-Export-c58e430f...` en lugar de simplemente `Notion`), por lo que adivinar directamente un `path_glob` es frágil.
### Parámetros
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
| --------------- | --------- | ----------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `patterns` | string\[] | Sí | — | Arreglo de palabras clave; cada una se envuelve internamente como SQL `LIKE %palabra%` contra la ruta. Múltiples palabras clave se combinan por OR, **así que pase varias variantes en una sola llamada** (pares de traducción, mayúsculas/minúsculas, identificadores reales de aplicación/SDK), ej. `["Notion", "notion", "notion-export"]`. Insensible a mayúsculas/minúsculas para ASCII; CJK coincide literalmente |
| `library` | string | No | — | Restringir a una biblioteca específica. Local: un nombre simple o `local://`; nube: `cloud:///` (solo `--remote`). Utilice `list_libraries` para ver las bibliotecas disponibles |
| `limit` | number | No | 10 | Número máximo de carpetas candidatas (máx 50) |
| `output_format` | string | No | `markdown` | Establezca `json` para obtener salida JSON estructurada |
### Campos de respuesta (modo JSON)
| Campo | Descripción |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `total_files` | Número total de archivos agregados a los candidatos retornados (antes del recorte por `limit`) |
| `truncated` | Indica si `limit` cortó la lista de directorios (`true` significa que existen más candidatos) |
| `directories` | Carpetas candidatas, ordenadas por `file_count` descendente. Cada entrada tiene `path` (la ruta absoluta completa), `path_glob` (el `path` convertido en un patrón `path_glob` listo para usar: los metacaracteres glob `* ? [` del nombre de la carpeta se escapan para que coincida literalmente con esa carpeta — igual a `path` cuando el nombre no tiene metacaracteres; cópielo tal cual en un `search` posterior para limitar a toda la carpeta) y `file_count` (archivos coincidentes) |
### Comportamiento de agregación
* Los archivos cuyos patrones solo coinciden con el **segmento de nombre de archivo** (sin coincidencia en algún segmento de directorio) se descartan silenciosamente — esta es una herramienta para "encontrar carpetas", no para "encontrar archivos". Si una consulta no devuelve carpetas candidatas a pesar de que existan archivos coincidentes, recurra a llamar `search` directamente.
* Cada coincidencia se agrupa por la posición **menos profunda** de cualquier patrón en la ruta, truncada en el siguiente `/`. Así `local:///Users/me/Documents/Notion-Export-abc/workspace/page.md` coincidente con `Notion` se agrega bajo `.../Documents/Notion-Export-abc`, sin importar cuán profundo viva el archivo.
### Cuándo usarla
* El usuario nombra un contenedor con una palabra ambigua o multilingüe ("en mis notas de Notion", "en mi carpeta de papers de Dropbox", "en mi respaldo de trabajo") y no conoce la ruta real
* Antes de `search`, para determinar el valor de `path_glob`
### Cuándo no usarla
* Consultas puramente de contenido / tema ("encuentra mis CV", "encuentra papers de IA") — llame `search` directamente; su búsqueda híbrida ya cubre título, nombre de archivo, contenido y ruta
* Filtrado solo por tipo de archivo ("todos los PDF") — llame `search` con `path_glob="*.pdf"` directamente
* Consultas vagas sin intención de contenedor ("encuentra cosas recientes") — llame `search`
### Ejemplo de uso
```bash theme={null}
# Usuario: "encuentra mis recibos de compra en mis notas de Notion"
# Paso 1: localizar la ruta real
linkly find-paths --patterns Notion,notion --limit 5
# Supongamos que devuelve .../Documents/Notion-Export-abc/workspace (1240 archivos)
# Paso 2: buscar dentro de ese contenedor
linkly search "shopping receipt" --path-glob "*Notion-Export*"
```
## Metadatos de respuesta
Cada respuesta exitosa de herramienta lleva la hora UTC actual, lo que permite a quien llama calcular fechas relativas ("el mes pasado", "este año", "los últimos 30 días") sin depender de la fecha de corte de entrenamiento del modelo.
* **Salida Markdown**: un bloque de pie de página al final de la respuesta, formateado como:
```
---
[meta] now=2026-05-08T14:43:14Z
```
* **Salida JSON**: un objeto `_meta` de nivel superior:
```json theme={null}
{ ..., "_meta": { "now": "2026-05-08T14:43:14Z" } }
```
Las respuestas de error (`isError: true`) **no** incluyen estos metadatos — el cuerpo del error ya transmite la causa, y agregar una marca de tiempo solo diluiría la señal.
Cuando el usuario use una fecha relativa, lea `now` desde la respuesta de herramienta más reciente, calcule la fecha ISO 8601 correspondiente, y pásela a `modified_after` / `modified_before` de `search`.
## Ejemplos de flujo de trabajo
### Flujo de trabajo completo: vía CLI
El siguiente ejemplo demuestra cómo realizar una búsqueda completa de documentos mediante CLI:
```bash theme={null}
# Paso 1: Buscar documentos relevantes
linkly search "microservice architecture design" --limit 5
# Paso 2: Ver el esquema del documento objetivo (supongamos que doc_id es abc123)
linkly outline abc123
# Paso 3: Leer la sección de interés (supongamos que está entre las líneas 80-150)
linkly read abc123 --offset 80 --limit 70
```
### Flujo de trabajo completo: vía MCP
Cuando el asistente de IA invoca las herramientas a través del protocolo MCP, el formato de solicitud es el siguiente:
```json theme={null}
// Paso 1: Búsqueda
{
"method": "tools/call",
"params": {
"name": "search",
"arguments": {
"query": "microservice architecture design",
"limit": 5
}
}
}
// Paso 2: Ver esquema
{
"method": "tools/call",
"params": {
"name": "outline",
"arguments": {
"doc_ids": ["abc123"]
}
}
}
// Paso 3: Leer contenido
{
"method": "tools/call",
"params": {
"name": "read",
"arguments": {
"doc_id": "abc123",
"offset": 80,
"limit": 70
}
}
}
```
## Preguntas frecuentes
Linkly AI actualmente es compatible con los siguientes formatos:
| Formato | Extensiones | Soporte de esquema |
| ------------ | ---------------------------------------- | ------------------ |
| Markdown | `.md`, `.mdx` | Yes |
| Word | `.docx` | Yes |
| EPUB | `.epub` | Yes |
| PDF | `.pdf` | Partial |
| Texto plano | `.txt` | No |
| HTML | `.html`, `.htm` | Partial |
| Imagen (OCR) | `.png`, `.jpg`, `.jpeg`, `.bmp`, `.webp` | No |
Si el documento no tiene un esquema disponible (`has_outline: false`), puede:
1. Usar directamente la herramienta `read` para navegar por el contenido del documento página por página
2. Leer primero el inicio del documento (200 líneas por defecto) para tener una idea general del contenido antes de decidir si continuar leyendo
Flujo recomendado:
1. Primero, comprender la estructura del documento a través de `outline` (si tiene esquema)
2. Según el rango de líneas del esquema, usar los parámetros `offset` y `limit` de `read` para leer con precisión las secciones objetivo
3. Leer como máximo 500 líneas por vez, paginando mediante el ajuste de `offset`
El puerto predeterminado es **60606**. Si ese puerto está ocupado, la aplicación intentará automáticamente otros puertos. Puede consultar el puerto en uso en la configuración de Linkly AI Desktop.
Puede intentar:
* Usar palabras clave más precisas
* Usar descripciones en lenguaje natural (aprovechando la coincidencia semántica vectorial)
* Combinar palabras clave y sinónimos, como `"authentication auth login sign-in"`
* Usar `--type` para filtrar tipos de documentos específicos y reducir el alcance de la búsqueda