Linkly AI MCP Tools Introduction

Tools Overview

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

search → grep or outline → read

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

These four 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"]`
`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.

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

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, and DOCX 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, 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

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
PDF	`.pdf`	Partial
Plain Text	`.txt`	No
HTML	`.html`, `.htm`	Partial

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

Getting Started

Advanced Usage

Linkly AI MCP Tools Introduction

Tools Overview

search

outline

grep

read

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

Usage Examples

Workflow Examples

Complete Workflow: CLI Method

Complete Workflow: MCP Method

FAQ

Getting Started

Advanced Usage

​Tools Overview

search

outline

grep

read

​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

​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

Workflow Examples

Complete Workflow: CLI Method

Complete Workflow: MCP Method

FAQ