Introducción a las herramientas MCP de Linkly AI

Visión general de herramientas

Linkly AI expone seis 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

Dos herramientas de utilidad adicionales están disponibles: list_libraries (listar bibliotecas de conocimiento) y explore (visión general de colecciones de documentos).

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

Estas seis 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"]`
`library`	string	No	—	Restringir la búsqueda a una biblioteca específica. Utilice `list_libraries` para ver las bibliotecas disponibles
`path_glob`	string	No	—	Filtrar por ruta de archivo usando sintaxis GLOB de SQLite. `*` coincide con cualquier carácter (incluido `/`), `?` coincide con un solo carácter. Siempre distingue mayúsculas y minúsculas
`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.

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*"

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 y DOCX. 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, 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. Omita para explorar todos los documentos

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

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

Inicio rápido

Uso avanzado

Introducción a las herramientas MCP de Linkly AI

Visión general de herramientas

search

outline

grep

read

list_libraries

explore

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

Ejemplos de flujo de trabajo

Flujo de trabajo completo: vía CLI

Flujo de trabajo completo: vía MCP

Preguntas frecuentes

Inicio rápido

Uso avanzado

​Visión general de herramientas

search

outline

grep

read

list_libraries

explore

​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

​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

Ejemplos de flujo de trabajo

Flujo de trabajo completo: vía CLI

Flujo de trabajo completo: vía MCP

Preguntas frecuentes