Linkly AI MCP 工具介绍

工具概览

Linkly AI 通过 MCP（Model Context Protocol）向 AI 助理暴露七个工具，构成一个渐进式的文档访问工作流：

search → grep 或 outline → read
搜索      正则匹配/大纲      阅读

另有三个辅助工具：list_libraries（列出知识库）、explore（概览文档集合）和 find_paths（按关键词定位文件夹路径，配合 search 的 path_glob 使用）。

search

搜索文档，找到相关结果

outline

查看文档大纲，了解结构

grep

正则匹配，精确定位文本模式

read

阅读文档内容，获取详情

list_libraries

列出知识库及其文档数量

explore

概览文档集合的主题和结构

find_paths

按关键词定位文件夹路径，给 search 的 path_glob 提供候选

这七个工具配合使用，让 AI 助理能够高效地从你的本地文档中获取上下文信息。

检索（search）

搜索已索引的本地文档，返回最相关的结果列表。

参数

参数	类型	必填	默认值	说明
`query`	string	是	—	搜索关键词或短语
`limit`	number	否	20	最大返回结果数（1-50）
`doc_types`	string[]	否	全部	按文档类型过滤，如 `["pdf", "md", "docx"]`
`library`	string	否	—	限定在某个知识库内搜索，使用 `list_libraries` 查看可用知识库
`path_glob`	string	否	—	按文件路径过滤，SQLite GLOB 语法。`*` 匹配任意字符（含 `/`），`?` 匹配单个字符，区分大小写。当真实路径未知时，先调 `find_paths` 获取
`modified_after`	string	否	—	修改时间下界（含），ISO 8601 UTC 格式：日期 `2024-01-01`（视为 `00:00:00Z`）或完整 RFC 3339 `2024-01-01T00:00:00Z`
`modified_before`	string	否	—	修改时间上界（含），格式同 `modified_after`
`time_sort`	string	否	`default`	时间排序模式：`default`（保留相关度排序）/ `newest`（最新优先）/ `oldest`（最旧优先）。命中候选集去重之后才重排
`output_format`	string	否	`markdown`	设为 `json` 可获得结构化 JSON 输出

如果向量模型尚在下载中，搜索会自动降级为纯关键词模式，不影响使用。

关于时间过滤和排序：

当用户给出明确的时间窗口（“上个月”、“在 2024 年”、“近三个月”）时，用 modified_after / modified_before。
当用户只是说”最近的”、“最新的”、“最早的”，没有具体范围时，用 time_sort=newest 或 oldest。
两者可以组合：“2024 年里最早的”等于 modified_after=2024-01-01 + modified_before=2024-12-31 + time_sort=oldest。
计算”上个月”等相对时间时，先从任何工具响应末尾的 [meta] now=... 字段读取当前 UTC 时间，再做日期推算（详见下方响应元数据）。

返回字段

每条搜索结果包含以下信息：

字段	说明
`doc_id`	文档唯一标识，用于后续 outline/read 调用
`title`	文档标题
`path`	文件路径
`relevance`	相关度分数（0-1）
`word_count`	文档字数
`total_lines`	文档总行数
`has_outline`	是否有可用大纲
`modified_at`	最后修改时间
`keywords`	提取的关键词列表
`snippet`	匹配的内容摘要片段

使用示例

# CLI 方式
linkly search "项目管理最佳实践" --limit 10

# 过滤文档类型
linkly search "季度报告" --type pdf,docx --json

# 在指定知识库中搜索
linkly search "深度学习" --library my-research --limit 10

# 按路径过滤
linkly search "报告" --path-glob "*2024*"

# 限定时间窗口（2024 年 Q3 的季度报告）
linkly search "季度报告" --modified-after 2024-07-01 --modified-before 2024-09-30

# "最新的周会纪要" — 没有具体窗口时，按时间倒序
linkly search "周会纪要" --time-sort newest --limit 5

大纲（outline）

获取一个或多个文档的结构化大纲和元数据，帮助快速了解文档结构并定位目标章节。

参数

参数	类型	必填	默认值	说明
`doc_ids`	string[]	是	—	文档 ID 列表（来自搜索结果）
`expand`	string[]	否	自动	要展开的节点 ID（如 `["2", "3.1"]`），省略则自动展示所有层级
`output_format`	string	否	`markdown`	设为 `json` 可获得结构化 JSON 输出

何时使用大纲

场景	建议
文档 > 50 行且有大纲	先查看大纲，再读取目标章节
短文档（< 50 行）	跳过大纲，直接 `read` 全文
`has_outline: false` 的文档	使用 `grep` 定位模式或 `read` 逐页浏览

大纲功能对有书签的 PDF、 Markdown 和 DOCX 文档效果最好，在阅读大部头的文档、书籍的时候会获得事半功倍的效果。纯文本和无书签的 PDF 将在后续迭代中提供大纲支持。

使用示例

# 查看单个文档大纲
linkly outline abc123

# 批量查看多个文档
linkly outline id1 id2 id3

# JSON 格式输出
linkly outline abc123 --json

正则匹配（grep）

在单个文档内通过正则表达式定位具体行。最适合 has_outline=false 的文档（无法使用 outline 浏览结构时）。在 search 之后使用，用于精确定位特定文本（人名、日期、术语、标识符等），然后用 read 跳转到匹配位置深入阅读。适用于所有文档类型（PDF、Markdown、DOCX、TXT、HTML）。如需跨多个文档搜索，请对每个文档分别调用 grep。

参数

参数	类型	必填	默认值	说明
`pattern`	string	是	—	要搜索的正则表达式模式
`doc_id`	string	是	—	要搜索的文档 ID（来自搜索结果）
`context`	number	否	3	每个匹配行前后各 N 行上下文
`before`	number	否	—	匹配行前 N 行上下文（覆盖 `context`）
`after`	number	否	—	匹配行后 N 行上下文（覆盖 `context`）
`case_insensitive`	boolean	否	false	大小写不敏感匹配
`output_mode`	string	否	`content`	`content`（匹配行及上下文）或 `count`（仅统计匹配数，用于预览总量）
`limit`	number	否	20	最大返回匹配行数（最多 100）
`offset`	number	否	0	跳过前 N 条匹配（分页用）
`output_format`	string	否	`markdown`	设为 `json` 可获得结构化 JSON 输出

何时使用 grep 而非 outline

场景	建议
需要查找特定术语、人名或日期	使用 `grep`
需要了解文档整体结构	使用 `outline`
文档没有大纲	使用 `grep` 定位
查找模式（邮箱、编号、数字等）	使用 `grep` 正则

使用示例

# 在文档中查找特定术语
linkly grep "季度营收" 456

# 大小写不敏感搜索，带上下文
linkly grep "error|warning" 1044 -C 3 -i

# 先预览匹配数量再分页阅读
linkly grep "TODO" 591 --mode count

阅读（read）

读取文档内容，支持行号定位和分页，适合阅读长文档的特定部分。Read 工具行为与 Claude AI SDK 的行为一致，因此能够在各种 Agentic AI 模型中获得最佳效果。

参数

参数	类型	必填	默认值	说明
`doc_id`	string	是	—	文档 ID（来自搜索结果）
`offset`	number	否	1	起始行号（从 1 开始）
`limit`	number	否	200	读取行数（最多 500）
`output_format`	string	否	`markdown`	设为 `json` 可获得结构化 JSON 输出

内容格式

Read 工具将返回带有行号的内容，方便引用和定位：

  1	# 项目需求文档
  2
  3	## 一、项目背景
  4
  5	本项目旨在构建一个高效的知识管理系统...
  6	目标用户为企业研发团队和个人知识工作者。

分页策略

对于长文档，建议分块读取：

# 第一页：第 1-200 行
linkly read <DOC_ID> --offset 1 --limit 200

# 第二页：第 201-400 行
linkly read <DOC_ID> --offset 201 --limit 200

# 第三页：第 401-600 行
linkly read <DOC_ID> --offset 401 --limit 200

结合大纲使用效果更佳 — 通过大纲定位到目标章节的行范围，然后用 read 精确读取该区间的内容。

使用示例

# 读取文档开头
linkly read abc123

# 读取特定范围
linkly read abc123 --offset 120 --limit 80

# JSON 格式（适合程序处理）
linkly read abc123 --json

知识库列表（list_libraries）

列出用户配置的所有知识库及其描述和文档数量。

参数

无需参数。

使用场景

用户询问”我有哪些知识库”时调用
在使用 search 的 library 参数前，确认知识库名称

linkly list-libraries

概览（explore）

获取全部已索引文档或特定知识库的鸟瞰概览。返回文档类型分布、目录结构（含文件数和中位字数）以及高频关键词（标注集中来源）。

参数

参数	类型	必填	默认值	说明
`library`	string	否	—	指定知识库名称，省略则概览全部已索引文档

使用场景

用户想了解知识库或文档集合中大概有什么内容
用户没有明确的搜索主题，想先发现可用的主题和方向
AI 助理需要了解文档集合的规模和主题分布，以便制定有效的搜索策略

概览返回后，可利用其中的关键词和目录名称作为后续 search 查询的线索。

# 概览全部文档
linkly explore

# 概览特定知识库
linkly explore --library my-research

路径定位（find_paths）

按关键词在已索引文档的文件路径上做模糊匹配，聚合到文件夹粒度，返回最匹配的若干候选目录。其定位是 search 的辅助工具：当用户描述容器名（如”在我的微信里”、“在 Notion 笔记里”）但你不知道这个容器在磁盘上的真实路径时，先用 find_paths 探测真实路径，再把它作为 search 的 path_glob 参数。实际目录名往往和用户的口语不一致（“微信”对应 xinWeChat、“Notion 笔记”对应 notion 笔记 等），盲填 path_glob 容易失败。

参数

参数	类型	必填	默认值	说明
`patterns`	string[]	是	—	关键词数组，对每个元素在路径上做子串匹配（内部包装为 SQL `LIKE %关键词%`）。多个关键词之间是 OR 关系，鼓励一次传入多个变体（中英对照、大小写、应用真实命名等），如 `["WeChat", "微信", "wxid", "xinWeChat"]`。ASCII 大小写不敏感；CJK 字面匹配
`library`	string	否	—	限定在某个知识库内查找，使用 `list_libraries` 查看可用知识库
`limit`	number	否	10	最大候选目录数（最多 50）
`output_format`	string	否	`markdown`	设为 `json` 可获得结构化 JSON 输出

返回字段（JSON 模式）

字段	说明
`total_files`	命中并被聚合到候选目录的文件总数（在 `limit` 截断之前）
`truncated`	是否因 `limit` 截断（`true` 表示候选目录还有更多）
`directories`	候选目录数组，按 `file_count` 降序排列。每项含 `path`（路径，遵循”显示完整路径”开关）和 `file_count`（该目录下的命中文件数）

聚合行为

关键词只匹配到文件名段（不是任何目录段）的文件会被静默丢弃 —— 这是”找文件夹”工具，不是”找文件”工具。如果某个查询返回 0 个候选目录但你确认有匹配文件，应回退到直接用 search。
每条匹配按其路径中最浅的关键词出现位置做截断聚合：例如 local:///Users/me/Library/.../com.tencent.xinWeChat/Data/... 被关键词 WeChat 命中后，聚合 key 是 .../com.tencent.xinWeChat，无论文件本身嵌得多深。

何时使用

用户用模糊或跨语言词描述容器（“在我微信里”、“在 Notion 笔记里”、“在我的工作备份里”），且你不知道真实路径
在调用 search 之前先确定 path_glob 的值

何时不使用

单纯按内容/主题搜索（“找简历”、“找 AI 论文”）—— 直接调 search，其混合检索本身已覆盖标题、文件名、内容、路径
仅按文件类型过滤（“所有 PDF”）—— 直接调 search 加 path_glob="*.pdf"
没有容器意图的笼统查询（“找最近的东西”）—— 直接调 search

使用示例

# 用户："找我微信里的购物订单"
# 第 1 步：定位真实路径
linkly find-paths --patterns WeChat,微信,wxid --limit 5
# 假设返回 .../com.tencent.xinWeChat/Data/Documents/xwechat_files (940 文件)

# 第 2 步：在该容器下按内容搜索
linkly search "购物订单" --path-glob "*xinWeChat*"

响应元数据（Response Metadata）

每次成功的工具响应都会附带一个当前 UTC 时间字段，方便调用方推算”上个月”、“今年”、“过去 30 天”等相对日期，避免依赖模型训练截止时间瞎猜。

Markdown 输出：响应末尾追加一行分隔块，形如：
```
---
[meta] now=2026-05-08T14:43:14Z
```

JSON 输出：在响应顶层添加 _meta 对象：

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

错误响应（isError: true）不附加这个元数据 —— 错误体本身已经传达了失败原因，再附加时间戳反而会稀释信号。当用户使用相对日期（“上个月”、“近三个月”）时，应当从最近一次工具响应中读取 now 字段，以此为基准换算出具体的 ISO 8601 日期，再传给 search 的 modified_after / modified_before。

调用示例

完整工作流：CLI 方式

以下示例演示如何通过 CLI 完成一次完整的文档检索：

# 第 1 步：搜索相关文档
linkly search "微服务架构设计" --limit 5

# 第 2 步：查看目标文档的大纲（假设 doc_id 为 abc123）
linkly outline abc123

# 第 3 步：阅读感兴趣的章节（假设目标在第 80-150 行）
linkly read abc123 --offset 80 --limit 70

完整工作流：MCP 方式

AI 助理通过 MCP 协议调用工具时，请求格式如下：

// 第 1 步：搜索
{
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "微服务架构设计",
      "limit": 5
    }
  }
}

// 第 2 步：查看大纲
{
  "method": "tools/call",
  "params": {
    "name": "outline",
    "arguments": {
      "doc_ids": ["abc123"]
    }
  }
}

// 第 3 步：阅读内容
{
  "method": "tools/call",
  "params": {
    "name": "read",
    "arguments": {
      "doc_id": "abc123",
      "offset": 80,
      "limit": 70
    }
  }
}

常见问题

支持哪些文档格式？

Linkly AI 目前支持以下格式：

格式	扩展名	大纲支持
Markdown	`.md`, `.mdx`	✅
Word	`.docx`	✅
PDF	`.pdf`	部分支持
纯文本	`.txt`	❌
HTML	`.html`, `.htm`	部分支持
图片 (OCR)	`.png`, `.jpg`, `.jpeg`, `.bmp`, `.webp`	❌

大纲不可用怎么办？

如果文档没有可用的大纲（has_outline: false），你可以：

直接使用 read 工具分页浏览文档内容
先读取文档开头（默认 200 行），了解大致内容后再决定是否继续阅读

如何处理长文档？

推荐流程：

先通过 outline 了解文档结构（如果有大纲）
根据大纲中的行范围，使用 read 的 offset 和 limit 参数精确读取目标章节
每次最多读取 500 行，通过调整 offset 分页读取

MCP 服务的默认端口是多少？

默认端口为 60606。如果该端口被占用，应用会自动尝试其他端口。你可以在 Linkly AI Desktop 的设置中查看实际使用的端口。

搜索结果不准确怎么办？

Documentation Index

​工具概览

search

outline

grep

read

list_libraries

explore

find_paths

​检索（search）

​参数

​返回字段

​使用示例

​大纲（outline）

​参数

​何时使用大纲

​使用示例

​正则匹配（grep）

​参数

​何时使用 grep 而非 outline

​使用示例

​阅读（read）

​参数

​内容格式

​分页策略

​使用示例

​知识库列表（list_libraries）

​参数

​使用场景

​概览（explore）

​参数

​使用场景

​路径定位（find_paths）

​参数

​返回字段（JSON 模式）

​聚合行为

​何时使用

​何时不使用

​使用示例

​响应元数据（Response Metadata）

​调用示例

​完整工作流：CLI 方式

​完整工作流：MCP 方式

​常见问题

工具概览

检索（search）

参数

返回字段

使用示例

大纲（outline）

参数

何时使用大纲

使用示例

正则匹配（grep）

参数

何时使用 grep 而非 outline

使用示例

阅读（read）

参数

内容格式

分页策略

使用示例

知识库列表（list_libraries）

参数

使用场景

概览（explore）

参数

使用场景

路径定位（find_paths）

参数

返回字段（JSON 模式）

聚合行为

何时使用

何时不使用

使用示例

响应元数据（Response Metadata）

调用示例

完整工作流：CLI 方式

完整工作流：MCP 方式

常见问题