Introducción a las herramientas MCP de Linkly AI

Visión general de herramientas

Linkly AI expone nueve herramientas a los asistentes de IA a través de MCP (Model Context Protocol). El núcleo es un flujo de trabajo progresivo de acceso a documentos:

search → grep or outline → read

A su alrededor hay tres herramientas de descubrimiento — 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) — más list (enumerar un contenedor: los archivos de una carpeta, una biblioteca o sus notas) y la única herramienta de notas: note_save (crear o editar una nota).

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

list

Listar las entradas de un contenedor: una carpeta, una biblioteca o sus notas

note_save

Crear o editar una nota, la única herramienta de escritura

Salvo note_save, todas son herramientas de solo lectura: leen sus documentos, sin modificar nada. note_save solo puede escribir en el directorio de notas y no existe ninguna herramienta de borrado: las notas solo se eliminan desde la propia aplicación.

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. Valores admitidos: `pdf`, `docx`, `pptx`, `epub`, `md`, `txt`, `html`, `image`, `audio`, `video`
`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`
`scope`	string	No	`folder`	Ámbito de la búsqueda. `folder` (predeterminado) busca en todo lo indexado con la semántica de `library` / `path_glob` descrita arriba; `notes` busca solo en las notas locales e ignora `path_glob` y una `library` local; combinarlo con una biblioteca `cloud://` se rechaza, ya que las notas no tienen equivalente en la nube. Un valor desconocido se rechaza
`tags`	string[]	No	—	Filtrar por etiquetas de nota, con semántica AND (la nota debe llevar todas las etiquetas indicadas). Las etiquetas se normalizan (se quita la `#` inicial y el ASCII pasa a minúsculas). Para un OR, llame una vez por etiqueta y combine los resultados. Normalmente se usa junto con `scope="notes"`
`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
`fuzzy_whitespace`	boolean	No	Automático	Coincidencia tolerante al ruido de espacios en blanco, pensada para el texto extraído de un PDF, plagado de espacios sobrantes y saltos de línea. Si se omite, se decide automáticamente (activada en PDF, desactivada en el resto de formatos); también puede forzarse con `true` / `false`
`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)
`image_text`	string	No	`abstract`	Cuánta información acompaña a las imágenes referenciadas en el texto; ver Leer documentos con ilustraciones más abajo
`output_format`	string	No	`markdown`	Establezca `json` para obtener salida JSON estructurada

Leer documentos con ilustraciones

En muchos documentos (sobre todo notas en Markdown y documentación técnica) la información clave está en las ilustraciones. read resuelve las referencias a imágenes que aparecen dentro del rango de líneas que está leyendo hacia los documentos de imagen ya indexados, y las adjunta al final del resultado. image_text controla cuánto se adjunta:

Valor	Qué se adjunta
`none`	Solo la correspondencia: número de línea, archivo y `doc_id`
`abstract` (por defecto)	Además, un extracto de una línea y el número de palabras de cada imagen
`full`	Además, el texto OCR completo en línea

full tiene límites de presupuesto: 2000 caracteres como máximo por imagen y 20 000 caracteres en total por llamada. Las imágenes que se pasen del presupuesto bajan automáticamente a abstract, con una indicación de cómo leerlas por separado.

Sale mucho más a cuenta usar el abstract predeterminado para decidir qué imagen interesa y luego hacer un read específico sobre su doc_id, que lanzar un full de entrada.

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

Listar (list)

Lista las entradas de un contenedor, sin hacer coincidencia de texto completo: para buscar contenido por palabra clave o por significado, use search. Se admiten tres contenedores: folder (archivos indexados bajo un directorio del disco), library (los archivos de una biblioteca) y notes (las notas locales en forma de tarjeta). Reparto de papeles entre herramientas: explore = visión global → find_paths = encontrar un directorio → list = listar los archivos de un contenedor conocido → outline / read = leer el contenido. El listado es un barrido recursivo plano de todo el subárbol — no se devuelve ningún árbol de directorios; para profundizar, siga las rutas absolutas de las entradas o use find_paths.

Parámetros

Parámetro	Tipo	Obligatorio	Predeterminado	Descripción
`scope`	string	Sí	—	Contenedor que se quiere listar. `folder`: archivos indexados bajo un directorio del disco (omita `path` para barrer todas las raíces vigiladas); `library`: los archivos de una biblioteca (requiere `library`); `notes`: notas locales en forma de tarjeta. Un valor desconocido se rechaza. Ojo: `search.scope` también tiene un valor escrito `folder`, que significa «todo lo indexado» — es otro concepto y los valores no se comparten
`library`	string	Con `scope="library"`	—	Qué biblioteca listar. Local: un nombre o `local://<id>` (véase `list_libraries`); nube: `cloud://<owner>/<slug>` (solo con `--remote`)
`path`	string	No	—	Directorio a listar — una dirección, no un patrón: sin comodines; si solo conoce un nombre aproximado, llame antes a `find_paths` y copie su campo `path` (no `path_glob`, que viene con escapes y aquí no coincidiría con nada, en silencio). Local (`folder` / `library` local): ruta absoluta — una ruta que no existe en el disco o queda fuera de sus carpetas vigiladas se rechaza con un error. Si la biblioteca tiene un filtro por etiqueta para notas o recortes, también se aceptan las rutas dentro de ese directorio `Notes/` o `Clips/`: solo listan los documentos que coinciden con el filtro. Biblioteca en la nube: prefijo de directorio relativo (la forma que devuelve el `find_paths` de la nube); allí una ruta absoluta se rechaza
`doc_types`	string[]	No	Todos	Filtrar por tipo de documento (solo `folder` / `library`): `pdf`, `docx`, `pptx`, `epub`, `md`, `txt`, `html`, `image`, `audio`, `video`
`tags`	string[]	No	—	Filtrar por etiquetas, con semántica AND (solo `notes` — los demás ámbitos lo rechazan). Se quita la `#` inicial y el ASCII pasa a minúsculas, igual que en `search.tags`
`modified_after`	string	No	—	Cota inferior inclusiva de la fecha de modificación (solo `folder` / `library`). ISO 8601 UTC: fecha simple `2024-01-01` o RFC 3339 completo
`modified_before`	string	No	—	Cota superior inclusiva. Mismo formato
`sort`	string	No	`recent`	`recent` (más recientes primero — ancla en la fecha de creación para `notes` y en la de modificación para `folder` / `library`, de modo que una página truncada muestra la porción más reciente) / `oldest` (misma ancla, más antiguas primero) / `name` (nombre de archivo A→Z). Cada orden tiene un desempate determinista por ruta, así que la paginación es estable
`snippet`	boolean	No	Según scope	`notes`: `true` (unos 200 caracteres del principio del texto); `folder` / `library`: `false` (activado, el extracto sale del resumen indexado — sin leer el disco). Mientras está activado, `limit` se limita a 50
`limit`	number	No	50	Número máximo de entradas devueltas, hasta 200; el tope baja a 50 mientras `snippet` esté activado
`offset`	number	No	0	Omitir las N primeras entradas según el orden elegido (para paginar); use `has_more` para decidir si pedir la página siguiente
`output_format`	string	No	Según scope	`notes`: `json` (cada entrada es una credencial CAS para `note_save`, que no cabe en un formato de línea compacto); `folder` / `library`: `markdown`. Ambos pueden pedirse explícitamente

Campos de respuesta

Las entradas de folder / library traen: doc_id, title, path absoluta, doc_type, word_count, total_lines, has_outline, modified_at (milisegundos Unix; el mtime del sistema de archivos), keywords, snippet (null salvo que los extractos estén activados) y skip_reason — un skip_reason no nulo significa que el contenido no es legible, así que no le haga read / grep. Use total_lines + has_outline para decidir entre outline y read. En los ámbitos locales total cuenta todo el conjunto filtrado; una biblioteca en la nube puede devolver total: null cuando el recuento completo se desconoce — en cualquier caso, pagine con offset + has_more. Las entradas de notes traen: doc_id (que puede pasarse a read / grep / outline), note_id y la version actual (ambos son las credenciales de bloqueo optimista que necesita note_save para editar), title, ruta absoluta, created_at / modified_at (milisegundos Unix), tags, información de origen y el snippet que se adjunta por defecto. La respuesta incluye además available_tags: las 50 etiquetas más usadas entre todas las notas, listas para aprovecharlas como filtro tags en la siguiente llamada.

Puntero README: solo cuando se lista con un path explícito (scope folder o una library local) y un archivo de tipo README está directamente en ese directorio (no en un subdirectorio), la respuesta trae un puntero readme de nivel superior. Las bibliotecas en la nube nunca lo devuelven. Si está presente y necesita entender para qué sirve la carpeta, lea antes ese documento.

Primero el sistema de archivos (notes): una nota recién escrita aparece de inmediato en la lista, pero con doc_id a null e indexed a false (el número de palabras y de líneas también vienen vacíos) hasta que termine la indexación. Por eso es normal que «una nota recién escrita se liste pero no se encuentre al buscar»: no se ha perdido.title también puede ser null: las notas cuyo nombre de archivo se generó automáticamente no tienen un título aprovechable, así que en ese caso hay que identificarlas por el extracto, las etiquetas y las fechas.

Bibliotecas en la nube

folder solo entiende rutas de disco locales. Para listar una biblioteca en la nube, use scope="library" con library="cloud://<owner>/<slug>" (disponible con --remote) y pase en path un prefijo de directorio relativo — exactamente la forma que devuelve el find_paths de la nube. El prefijo se aplica a la unión de todas las fuentes de la biblioteca; un prefijo inexistente no puede distinguirse de un directorio vacío — en la primera página (offset=0) ambos devuelven total: 0, con una pista si se pasó un path. El listado en la nube difiere del local en algunos puntos: sort="name" no está disponible, skip_reason es siempre null, los extractos se recortan a unos 120 caracteres y, pasada la primera página, total puede ser null — pagine con has_more.

Ejemplos de uso

# Los archivos más recientes de todas las raíces vigiladas
linkly list --scope folder --limit 10

# PDF bajo un directorio, modificados este año
linkly list --scope folder --path /Users/me/Papers --type pdf --modified-after 2026-01-01

# Los archivos de una biblioteca
linkly list --scope library --library my-research

# Notas filtradas por etiqueta (salida predeterminada: JSON con credenciales CAS)
linkly list --scope notes --tags project

Guardar notas (note_save)

Crea o edita una nota local en formato Markdown. Es la única herramienta que escribe, y solo puede escribir en el directorio de notas; los metadatos YAML los genera el servidor por completo, así que quien llama no tiene que ocuparse de ellos.

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`mode`	string	Sí	`create` o `edit`
`content`	string	Sí	El texto en Markdown, sin front matter YAML. Al editar se envía el texto completo ya modificado
`note_id`	string	Obligatorio en `edit`	El UUID de la nota, que se obtiene con `list`
`base_version`	string	Obligatorio en `edit`	La `version` que se leyó, para la comprobación de bloqueo optimista
`tags`	string[]	No	Etiquetas que se quieren añadir (el servidor completa en el texto los `#tag` que falten). No sirve para borrar: para quitar una etiqueta hay que eliminar su `#tag` del `content`. Requiere Desktop 0.11.0+; en las versiones anteriores es obligatorio al editar y sustituye el conjunto completo
`app_name`	string	No	Nombre visible de la aplicación que aloja la conversación (p. ej. `ChatGPT`, `Cursor`); se muestra como insignia de origen de la nota. Es el nombre de la aplicación, no el del modelo — si solo conoces el nombre del modelo, omite el parámetro. En una conexión OAuth a través de la pasarela en la nube, el servidor lo rellena automáticamente. Máximo 64 caracteres

Dos reglas que hay que conocer

El formato del texto es una lista blanca, no vale cualquier cosa

Por esta vía solo se acepta la parte de Markdown que la barra de herramientas de la interfaz es capaz de producir: párrafos y saltos de línea, negrita, tachado, listas ordenadas y sin ordenar, y texto plano.Los encabezados, la cursiva, las citas, el código, los enlaces, las tablas, las listas de tareas, las imágenes y el HTML suelto se rechazan con NOTE_INVALID_INPUT. Cuando escribe usted a mano en la aplicación no tiene esta limitación.Los #tag que aparecen en el texto (fuera del código) son las etiquetas de la nota: el texto es la única fuente de verdad, igual que cuando escribe usted en el editor de la aplicación. Para quitar una etiqueta, elimine su #tag; el parámetro tags solo sirve para añadir. Las notas escritas por versiones anteriores, con las etiquetas únicamente en el YAML, se reparan solas: en la primera edición de la IA se completan en el texto los #tag que falten.

Editar exige un ciclo de bloqueo optimista (CAS)

El orden correcto para editar es:

list (con scope="notes") para obtener note_id y version
read(doc_id) para leer el texto completo actual
note_save con mode="edit", note_id, base_version (la version recién leída) y el texto completo ya modificado: deje los #tag que quiera conservar y borre los que quiera quitar

Si base_version ha caducado (porque la nota se modificó entretanto), se devuelve NOTE_VERSION_CONFLICT junto con el número de versión real: hay que releer, fusionar y reintentar, nunca sobrescribir a ciegas.Cada respuesta correcta devuelve el content efectivo de la nota (puede que el servidor haya añadido algún #tag) y su nueva version: cualquier edición posterior debe partir del content devuelto, nunca del que usted envió. Las notas que todavía no se han indexado tienen doc_id a null, así que esta es además la manera de editar una nota recién creada. Nunca reescriba una nota entera basándose solo en el extracto.

No hay herramienta de borrado. Las notas solo puede eliminarlas el usuario desde la interfaz de la aplicación.

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`	Sí
Word	`.docx`	Sí
PowerPoint	`.pptx`	Sí
EPUB	`.epub`	Sí
PDF	`.pdf`	Parcial
Texto plano	`.txt`	No
HTML	`.html`	Parcial
Imagen (OCR)	`.png`, `.jpg`, `.jpeg`, `.bmp`, `.webp`	No
Audio (transcripción)	`.mp3`, `.wav`, `.m4a`, `.flac`, `.aac`, `.ogg`	No
Vídeo (transcripción)	`.mp4`, `.mov`, `.mkv`, `.webm`	No

La transcripción de voz del audio y el vídeo está desactivada por defecto: estos archivos entran igualmente en el índice y se encuentran por su nombre, pero para poder buscar «lo que se dice dentro» hay que activar antes Transcripción de audio y Transcripción de vídeo en Ajustes → Índice. Más detalles en Ajustes de indexación.

¿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

list

note_save

​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

​Leer documentos con ilustraciones

​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

​Listar (list)

​Parámetros

​Campos de respuesta

​Bibliotecas en la nube

​Ejemplos de uso

​Guardar notas (note_save)

​Parámetros

​Dos reglas que hay que conocer

​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

Leer documentos con ilustraciones

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

Listar (list)

Parámetros

Campos de respuesta

Bibliotecas en la nube

Ejemplos de uso

Guardar notas (note_save)

Parámetros

Dos reglas que hay que conocer

Metadatos de respuesta

Ejemplos de flujo de trabajo

Flujo de trabajo completo: vía CLI

Flujo de trabajo completo: vía MCP

Preguntas frecuentes