Linkly AI MCP Tools Introduction

Tools Overview

Linkly AI exposes seven tools to AI assistants via MCP (Model Context Protocol), forming a progressive document access workflow:

search → grep or outline → read

Three additional utility tools are available: list_libraries (list knowledge libraries), explore (overview of document collections), and find_paths (locate folder paths by keyword to feed search’s path_glob).

search

Search documents and find relevant results

outline

View document outlines to understand structure

grep

Find specific text patterns with regex matching

read

Read document content for detailed information

list_libraries

List knowledge libraries and their document counts

explore

Overview of document collection themes and structure

find_paths

Locate folder paths by keyword to feed search’s path_glob

These seven tools work together to enable AI assistants to efficiently retrieve contextual information from your local documents.

Search

Searches indexed local documents and returns a list of the most relevant results.

Parameters

Parameter	Type	Required	Default	Description
`query`	string	Yes	—	Search keywords or phrase
`limit`	number	No	20	Maximum number of results (1-50)
`doc_types`	string[]	No	All	Filter by document type, e.g. `["pdf", "md", "docx", "pptx", "epub"]`
`library`	string	No	—	Restrict to a specific library. Local: a plain name or `local://<id>`; cloud: `cloud://<owner>/<slug>` (`--remote` only). Use `list_libraries` to see available libraries
`path_glob`	string	No	—	Filter by file path. The pattern is substring-matched against the path — it may appear anywhere, no leading/trailing `` needed. `` matches any characters (including `/`), `?` a single character. Always case-sensitive. A full directory path (`/Users/me/notes/`) scopes to that directory. When the actual path is unknown, call `find_paths` first to discover it.
`modified_after`	string	No	—	Inclusive lower bound on modification time. ISO 8601 UTC: bare date `2024-01-01` (treated as `00:00:00Z`) or full RFC 3339 `2024-01-01T00:00:00Z`
`modified_before`	string	No	—	Inclusive upper bound on modification time. Same format as `modified_after`
`time_sort`	string	No	`default`	Time-based reordering: `default` (preserves relevance order) / `newest` (most recent first) / `oldest` (earliest first). Reorders only after the candidate set is selected and deduplicated
`output_format`	string	No	`markdown`	Set to `json` for structured JSON output

If the vector model is still downloading, search will automatically fall back to keyword-only mode without affecting usability.

About time filtering and sorting:

When the user gives an explicit window (“last month”, “in 2024”, “in the last three months”), use modified_after / modified_before.
When the user only says “recent”, “latest”, “earliest” without a fixed window, use time_sort=newest or oldest.
The two can combine: “earliest in 2024” is modified_after=2024-01-01 + modified_before=2024-12-31 + time_sort=oldest.
For relative dates (“last month”), first read the current UTC time from the [meta] now=... field at the end of any tool response, then compute the date — see Response Metadata below.

Response Fields

Each search result contains the following information:

Field	Description
`doc_id`	Unique document identifier for subsequent outline/read calls
`title`	Document title
`path`	File path
`relevance`	Relevance score (0-1)
`word_count`	Document word count
`total_lines`	Total number of lines in the document
`has_outline`	Whether an outline is available
`modified_at`	Last modified time
`keywords`	Extracted keyword list
`snippet`	Matching content snippet

Usage Examples

# CLI method
linkly search "project management best practices" --limit 10

# Filter by document type
linkly search "quarterly report" --type pdf,docx --json

# Search within a specific library
linkly search "deep learning" --library my-research --limit 10

# Filter by file path
linkly search "report" --path-glob "*2024*"

# Limit by time window (Q3 2024 quarterly reports)
linkly search "quarterly report" --modified-after 2024-07-01 --modified-before 2024-09-30

# Sort by time ("the latest", "the earliest" — when there's no fixed window)
linkly search "weekly retro" --time-sort newest --limit 5

Outline

Retrieves the structured outline and metadata of one or more documents, helping to quickly understand document structure and locate target sections.

Parameters

Parameter	Type	Required	Default	Description
`doc_ids`	string[]	Yes	—	List of document IDs (from search results)
`expand`	string[]	No	Auto	Node IDs to expand (e.g. `["2", "3.1"]`); omit to automatically show all levels
`output_format`	string	No	`markdown`	Set to `json` for structured JSON output

When to Use Outline

Scenario	Recommendation
Document > 50 lines with outline	View outline first, then read target sections
Short document (< 50 lines)	Skip outline, `read` full text directly
Document with `has_outline: false`	Use `grep` to find patterns or `read` page by page

The outline feature works best with bookmarked PDFs, Markdown, DOCX, PowerPoint (PPTX), and EPUB documents. It is especially effective when reading lengthy documents and books. Outline support for plain text and unbookmarked PDFs will be added in future iterations.

Usage Examples

# View a single document's outline
linkly outline abc123

# View multiple documents at once
linkly outline id1 id2 id3

# JSON format output
linkly outline abc123 --json

Grep

Locate specific lines within a single document by regex pattern. Best for documents with has_outline=false where outline is unavailable. Use after search to pinpoint exact positions of names, dates, terms, identifiers, or any pattern — then use read with offset to see full context. Works on all document types (PDF, Markdown, DOCX, PPTX, EPUB, TXT, HTML). For searching across multiple documents, call grep once per document.

Parameters

Parameter	Type	Required	Default	Description
`pattern`	string	Yes	—	Regular expression pattern to search for
`doc_id`	string	Yes	—	Document ID to search within (from search results)
`context`	number	No	3	Lines of context before and after each match
`before`	number	No	—	Lines of context before each match (overrides `context`)
`after`	number	No	—	Lines of context after each match (overrides `context`)
`case_insensitive`	boolean	No	false	Case-insensitive matching
`output_mode`	string	No	`content`	`content` (matching lines with context) or `count` (match count only, preview totals first)
`limit`	number	No	20	Maximum matching lines to return (max 100)
`offset`	number	No	0	Number of matches to skip for pagination
`output_format`	string	No	`markdown`	Set to `json` for structured JSON output

When to Use Grep vs Outline

Scenario	Recommendation
Need to find a specific term, name, or date	Use `grep` with the pattern
Need to understand overall document structure	Use `outline`
Document has no outline (`has_outline: false`)	Use `grep` to locate content
Looking for patterns (emails, IDs, numbers, etc.)	Use `grep` with regex

Usage Examples

# Find specific terms in a document
linkly grep "quarterly revenue" 456

# Case-insensitive search with context
linkly grep "error|warning" 1044 -C 3 -i

# Preview match count before reading
linkly grep "TODO" 591 --mode count

Read

Reads document content with line number positioning and pagination, suitable for reading specific parts of long documents. The Read tool behaves consistently with the Claude AI SDK, ensuring optimal results across various Agentic AI models.

Parameters

Parameter	Type	Required	Default	Description
`doc_id`	string	Yes	—	Document ID (from search results)
`offset`	number	No	1	Starting line number (from 1)
`limit`	number	No	200	Number of lines to read (max 500)
`output_format`	string	No	`markdown`	Set to `json` for structured JSON output

Content Format

The Read tool returns content with line numbers for easy reference and positioning:

  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.

Pagination Strategy

For long documents, it is recommended to read in chunks:

# Page 1: Lines 1-200
linkly read <DOC_ID> --offset 1 --limit 200

# Page 2: Lines 201-400
linkly read <DOC_ID> --offset 201 --limit 200

# Page 3: Lines 401-600
linkly read <DOC_ID> --offset 401 --limit 200

Combining with outlines yields even better results — use the outline to locate the line range of the target section, then use read to precisely retrieve the content within that range.

Usage Examples

# Read the beginning of a document
linkly read abc123

# Read a specific range
linkly read abc123 --offset 120 --limit 80

# JSON format (suitable for programmatic processing)
linkly read abc123 --json

List Libraries

Lists all knowledge libraries configured by the user, along with their descriptions and document counts.

Parameters

No parameters required.

Use Cases

When the user asks “what libraries do I have?”
Before using the library parameter in search, to verify a library name

linkly list-libraries

Explore

Get a bird’s-eye overview of all indexed documents or a specific library. Returns document type distribution, directory structure (with file counts and median word counts), and top keywords (with source attribution).

Parameters

Parameter	Type	Required	Default	Description
`library`	string	No	—	Restrict to a specific library. Local: a plain name or `local://<id>`; cloud: `cloud://<owner>/<slug>` (`--remote` only). Omit to explore all local documents

Use Cases

The user wants to know what’s in their knowledge base or document collection
The user doesn’t have a specific search topic and wants to discover available themes and directions
The AI assistant needs to understand the scale and topic distribution to formulate effective search strategies

After exploring, use the keywords and directory names from the output as leads for subsequent search queries.

# Explore all documents
linkly explore

# Explore a specific library
linkly explore --library my-research

Find Paths (find_paths)

Fuzzy-matches keywords against the file path field of indexed documents, aggregates matches at folder granularity, and returns the top folder candidates. It is positioned as a helper for search: when the user names a container (“in my Notion notes”, “in my Dropbox papers folder”) but you don’t know its on-disk path, call find_paths first to discover the real path, then pass it as path_glob to search. The actual folder name on disk often differs from the user’s spoken name (e.g. an export might live under Notion-Export-c58e430f... rather than just Notion), so guessing a path_glob directly is fragile.

Parameters

Parameter	Type	Required	Default	Description
`patterns`	string[]	Yes	—	Array of keywords; each is wrapped internally as SQL `LIKE %keyword%` against the path. Multiple keywords are OR-matched, so pass several variants in one call (translation pairs, casings, real app/SDK identifiers when known), e.g. `["Notion", "notion", "notion-export"]`. Case-insensitive for ASCII; CJK matches literally.
`library`	string	No	—	Restrict to a specific library. Local: a plain name or `local://<id>`; cloud: `cloud://<owner>/<slug>` (`--remote` only). Use `list_libraries` to see available libraries
`limit`	number	No	10	Maximum number of candidate folders (max 50)
`output_format`	string	No	`markdown`	Set to `json` for structured JSON output

Response Fields (JSON mode)

Field	Description
`total_files`	Total number of files aggregated into the returned candidates (before `limit` truncation)
`truncated`	Whether `limit` cut off the directory list (`true` means more candidates exist)
`directories`	Candidate folders, ordered by `file_count` descending. Each entry has `path` (the full absolute path), `path_glob` (the `path` quoted into a ready-to-use `path_glob` pattern: glob metacharacters `* ? [` in the folder name are escaped so it matches that folder literally — equals `path` when the name has no metacharacters; copy it verbatim into a follow-up `search` to scope to the whole folder), and `file_count` (matching files inside that folder)

Aggregation behaviour

Files whose patterns only match the filename segment (no matching directory segment) are silently dropped — this is a “find folders” tool, not a “find files” tool. If a query yields zero candidate folders even though matching files exist, fall back to calling search directly.
Each match is bucketed by the shallowest position of any pattern in the path, truncated at the next /. So local:///Users/me/Documents/Notion-Export-abc/workspace/page.md matched by Notion aggregates under .../Documents/Notion-Export-abc, regardless of how deep the file lives.

When to use

The user names a container with a fuzzy or cross-language word (“in my Notion notes”, “in my Dropbox papers folder”, “in my work backup”) and you don’t know the actual path
Call before search to determine the right path_glob

When not to use

Pure content / topic queries (“find resumes”, “find AI papers”) — call search directly; its hybrid retrieval already covers title, filename, content, and path
Filter by file type only (“all PDFs”) — call search with path_glob="*.pdf" directly
Vague queries with no container intent (“find recent stuff”) — call search

Usage example

# User: "find shopping receipts in my Notion notes"
# Step 1: locate the real path
linkly find-paths --patterns Notion,notion --limit 5
# Suppose it returns .../Documents/Notion-Export-abc/workspace (1240 files)

# Step 2: search within that container
linkly search "shopping receipt" --path-glob "*Notion-Export*"

Response Metadata

Every successful tool response carries the current UTC time so callers can compute relative dates (“last month”, “this year”, “in the last 30 days”) without relying on the model’s training cutoff.

Markdown output: a footer block at the end of the response, formatted as:
--- [meta] now=2026-05-08T14:43:14Z

JSON output: a top-level _meta object:

{ ..., "_meta": { "now": "2026-05-08T14:43:14Z" } }

Error responses (isError: true) do not include this metadata — the error body itself already conveys the cause, and adding a timestamp would only dilute the signal. When the user uses a relative date, read now from the most recent tool response, compute the corresponding ISO 8601 date, and pass it to search’s modified_after / modified_before.

Workflow Examples

Complete Workflow: CLI Method

The following example demonstrates how to perform a complete document retrieval via CLI:

# Step 1: Search for relevant documents
linkly search "microservice architecture design" --limit 5

# Step 2: View the target document's outline (assuming doc_id is abc123)
linkly outline abc123

# Step 3: Read the section of interest (assuming the target is at lines 80-150)
linkly read abc123 --offset 80 --limit 70

Complete Workflow: MCP Method

When AI assistants call tools via the MCP protocol, the request format is as follows:

// Step 1: Search
{
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "microservice architecture design",
      "limit": 5
    }
  }
}

// Step 2: View outline
{
  "method": "tools/call",
  "params": {
    "name": "outline",
    "arguments": {
      "doc_ids": ["abc123"]
    }
  }
}

// Step 3: Read content
{
  "method": "tools/call",
  "params": {
    "name": "read",
    "arguments": {
      "doc_id": "abc123",
      "offset": 80,
      "limit": 70
    }
  }
}

FAQ

What document formats are supported?

Linkly AI currently supports the following formats:

Format	Extensions	Outline Support
Markdown	`.md`, `.mdx`	Yes
Word	`.docx`	Yes
EPUB	`.epub`	Yes
PDF	`.pdf`	Partial
Plain Text	`.txt`	No
HTML	`.html`, `.htm`	Partial
Image (OCR)	`.png`, `.jpg`, `.jpeg`, `.bmp`, `.webp`	No

What if an outline is not available?

If a document has no available outline (has_outline: false), you can:

Use the read tool directly to browse the document content page by page
Read the beginning of the document first (default 200 lines) to get a general idea, then decide whether to continue reading

How to handle long documents?

Recommended workflow:

First use outline to understand the document structure (if an outline is available)
Based on the line ranges in the outline, use the offset and limit parameters of read to precisely read target sections
Read up to 500 lines at a time, and paginate by adjusting offset

What is the default port for the MCP service?

The default port is 60606. If that port is occupied, the application will automatically try other ports. You can check the actual port in use in Linkly AI Desktop’s settings.

What if search results are inaccurate?

You can try:

Using more precise keywords
Using natural language descriptions (leveraging vector semantic matching)
Mixing keywords and synonyms, e.g. "authentication auth login sign-in"
Using --type to filter specific document types and narrow the search scope

​Tools Overview

search

outline

grep

read

list_libraries

explore

find_paths

​Search

​Parameters

​Response Fields

​Usage Examples

​Outline

​Parameters

​When to Use Outline

​Usage Examples

​Grep

​Parameters

​When to Use Grep vs Outline

​Usage Examples

​Read

​Parameters

​Content Format

​Pagination Strategy

​Usage Examples

​List Libraries

​Parameters

​Use Cases

​Explore

​Parameters

​Use Cases

​Find Paths (find_paths)

​Parameters

​Response Fields (JSON mode)

​Aggregation behaviour

​When to use

​When not to use

​Usage example

​Response Metadata

​Workflow Examples

​Complete Workflow: CLI Method

​Complete Workflow: MCP Method

​FAQ

Tools Overview

Search

Parameters

Response Fields

Usage Examples

Outline

Parameters

When to Use Outline

Usage Examples

Grep

Parameters

When to Use Grep vs Outline

Usage Examples

Read

Parameters

Content Format

Pagination Strategy

Usage Examples

List Libraries

Parameters

Use Cases

Explore

Parameters

Use Cases

Find Paths (find_paths)

Parameters

Response Fields (JSON mode)

Aggregation behaviour

When to use

When not to use

Usage example

Response Metadata

Workflow Examples

Complete Workflow: CLI Method

Complete Workflow: MCP Method

FAQ