> ## Documentation Index > Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Linkly AI MCP Tools Introduction > Introduction to the tools Linkly AI provides for AI assistants ## 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 documents and find relevant results View document outlines to understand structure Find specific text patterns with regex matching Read document content for detailed information List knowledge libraries and their document counts Overview of document collection themes and structure 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://`; cloud: `cloud:///` (`--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](#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 ```bash theme={null} # 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 ```bash theme={null} # 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 ```bash theme={null} # 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: ```bash theme={null} # Page 1: Lines 1-200 linkly read --offset 1 --limit 200 # Page 2: Lines 201-400 linkly read --offset 201 --limit 200 # Page 3: Lines 401-600 linkly read --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 ```bash theme={null} # 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 ```bash theme={null} 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://`; cloud: `cloud:///` (`--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. ```bash theme={null} # 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://`; cloud: `cloud:///` (`--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 ```bash theme={null} # 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: ```json theme={null} { ..., "_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: ```bash theme={null} # 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: ```json theme={null} // 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 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 | If a document has no available outline (`has_outline: false`), you can: 1. Use the `read` tool directly to browse the document content page by page 2. Read the beginning of the document first (default 200 lines) to get a general idea, then decide whether to continue reading Recommended workflow: 1. First use `outline` to understand the document structure (if an outline is available) 2. Based on the line ranges in the outline, use the `offset` and `limit` parameters of `read` to precisely read target sections 3. Read up to 500 lines at a time, and paginate by adjusting `offset` 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. 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