Introducción a las herramientas MCP de Linkly AI

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).

search

Buscar documentos y encontrar resultados relevantes

outline

Ver el esquema del documento para comprender su estructura

grep

Encontrar patrones de texto específicos con coincidencia regex

read

Leer el contenido del documento para obtener información detallada

list_libraries

Listar las bibliotecas de conocimiento y sus cantidades de documentos

explore

Visión general de los temas y la estructura de la colección de documentos

find_paths

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://<id>`; nube: `cloud://<owner>/<slug>` (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 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

# 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

# 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

# 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:

# Primera página: líneas 1-200
linkly read <DOC_ID> --offset 1 --limit 200

# Segunda página: líneas 201-400
linkly read <DOC_ID> --offset 201 --limit 200

# Tercera página: líneas 401-600
linkly read <DOC_ID> --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

# 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

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://<id>`; nube: `cloud://<owner>/<slug>` (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.

# 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://<id>`; nube: `cloud://<owner>/<slug>` (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

# 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:

{ ..., "_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:

# 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:

// 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

¿Qué formatos de documento son compatibles?

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

¿Qué hacer si el esquema no está disponible?

Si el documento no tiene un esquema disponible (has_outline: false), puede:

Usar directamente la herramienta read para navegar por el contenido del documento página por página
Leer primero el inicio del documento (200 líneas por defecto) para tener una idea general del contenido antes de decidir si continuar leyendo

¿Cómo manejar documentos extensos?

Flujo recomendado:

Primero, comprender la estructura del documento a través de outline (si tiene esquema)
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
Leer como máximo 500 líneas por vez, paginando mediante el ajuste de offset

¿Cuál es el puerto predeterminado del servicio MCP?

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.

¿Qué hacer si los resultados de búsqueda no son precisos?

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

​Visión general de herramientas

search

outline

grep

read

list_libraries

explore

find_paths

​Búsqueda (search)

​Parámetros

​Campos de respuesta

​Ejemplos de uso

​Esquema (outline)

​Parámetros

​Cuándo usar el esquema

​Ejemplos de uso

​Grep

​Parámetros

​Cuándo usar Grep vs Esquema

​Ejemplos de uso

​Lectura (read)

​Parámetros

​Formato de contenido

​Estrategia de paginación

​Ejemplos de uso

​Listar bibliotecas (list_libraries)

​Parámetros

​Casos de uso

​Explorar (explore)

​Parámetros

​Casos de uso

​Localización de rutas (find_paths)

​Parámetros

​Campos de respuesta (modo JSON)

​Comportamiento de agregación

​Cuándo usarla

​Cuándo no usarla

​Ejemplo de uso

​Metadatos de respuesta

​Ejemplos de flujo de trabajo

​Flujo de trabajo completo: vía CLI

​Flujo de trabajo completo: vía MCP

​Preguntas frecuentes

Visión general de herramientas

Búsqueda (search)

Parámetros

Campos de respuesta

Ejemplos de uso

Esquema (outline)

Parámetros

Cuándo usar el esquema

Ejemplos de uso

Grep

Parámetros

Cuándo usar Grep vs Esquema

Ejemplos de uso

Lectura (read)

Parámetros

Formato de contenido

Estrategia de paginación

Ejemplos de uso

Listar bibliotecas (list_libraries)

Parámetros

Casos de uso

Explorar (explore)

Parámetros

Casos de uso

Localización de rutas (find_paths)

Parámetros

Campos de respuesta (modo JSON)

Comportamiento de agregación

Cuándo usarla

Cuándo no usarla

Ejemplo de uso

Metadatos de respuesta

Ejemplos de flujo de trabajo

Flujo de trabajo completo: vía CLI

Flujo de trabajo completo: vía MCP

Preguntas frecuentes