docsift

DocSift

文档只需转换一次。只向 Agent 提供所需内容。

mcp-name: io.github.anishmoncivarghese/docsift

300 页的 PDF 无法放进大模型的上下文窗口；即使放得下，粘贴进去也会很昂贵。DocSift 会将文档转换为整洁的 Markdown、建立索引，然后仅返回能够回答问题的段落，并附上页码和章节标题，方便引用。

它在你的机器上运行。PDF 由 Docling 处理，其他格式由 MarkItDown 处理，两者通过同一个接口提供服务。无需云 API、账户或遥测。

**节省开销的关键：**检索，而非转换。清理 PDF 几乎无法减少 Token 数量，因为 Docling 已通过其版面模型移除了页眉和页脚。真正影响费用的是提出问题后只获取三个相关片段，而不是整个文档。

快速开始

选择所需的引擎——markitdown 适用于 Word、Excel、PowerPoint、HTML、CSV 和 EPUB；docling 适用于 PDF（下载量较大：包含 ML 版面模型）；all 则包含两个引擎以及 HTTP API 和 MCP 服务。

pip install "docsift[markitdown]"
pip install "docsift[docling]"
pip install "docsift[all]"

docsift convert report.pdf

这会将清理后的 Markdown、按 Token 预算分块的内容和 JSON 摘要写入 ./output/。单独运行 pip install docsift 只会安装 CLI，不包含任何引擎；执行转换时会明确告知这一点，而不是含糊地失败。

Office 指现代格式：.docx、.xlsx、.pptx。2007 年之前的二进制格式——.doc、.xls、.ppt——不受支持，DocSift 会根据文件名拒绝处理，而不会等到中途才失败。请先在 PowerPoint、Keynote、LibreOffice 或 Google Slides 中打开文件，并将其另存为 .pptx。

在 Claude、Codex 或其他 MCP 客户端中使用

这是使用该工具的最直接方式：让助手搜索你自己的文档，而无需将文档粘贴到任何地方。

支持的客户端

DocSift 通过 stdio 使用 MCP——客户端会在你的机器上将其作为程序启动。任何支持这种方式的客户端都可以使用：

客户端	支持情况	方法
Claude Code	是	claude mcp add — 第 2 步
Claude Desktop	是	claude_desktop_config.json
VS Code（Copilot Agent 模式）	是	.vscode/mcp.json
Codex CLI	是	~/.codex/config.toml
Cursor	是	JSON 配置，格式与 VS Code 相同
浏览器中的 claude.ai	否	需要远程服务
ChatGPT（网页版或桌面版）	否	需要远程服务

在安装任何内容之前，有必要先说清最后两项。它们的连接器功能只接受位于公共 HTTPS URL 上的远程 MCP 服务，而 DocSift 不支持远程传输——没有任何配置能让本地服务出现在这些界面中。

这是有意为之，并非疏忽。要连接这些客户端，就得在服务器上运行 DocSift 并将文档上传到服务器，这与本工具的用途背道而驰。未来增加可自托管的远程传输是合理的选择；把文件发送到别人的机器上则不是。

1. 将其安装为命令，而不是安装到项目中

MCP 客户端会将 DocSift 作为程序启动，因此它必须安装在任何虚拟环境之外。请将其安装为独立工具：

uv tool install --python 3.12 "docsift[mcp,docling,markitdown]"

也可以使用 pipx：

pipx install --python python3.12 "docsift[mcp,docling,markitdown]"

DocSift 需要 Python 3.11 或更高版本。如果你的默认版本较旧，上面的版本标志可避免出现无法满足依赖要求的错误。请预留较大的下载空间：docling 会安装 PyTorch 和布局模型。

在 Linux 上，请添加 --torch-backend auto。 默认配置会解析为 CUDA 版 PyTorch，安装后占用 5.3 GB，其中约 2 GB 是没有 NVIDIA GPU 的机器永远不会加载的 nvidia-* wheel。auto 会检测你的驱动并选择合适的版本：没有 GPU 的机器上占用 1.6 GB；有 GPU 的机器则会保留 CUDA：

uv tool install --python 3.12 --torch-backend auto "docsift[mcp,docling,markitdown]"

macOS 的 wheel 本来就只支持 CPU，因此这个标志在那里不会产生任何变化。这是 uv 的功能：使用 pipx 或 pip 时没有相应选项，因为 CPU 版本位于单独的索引上，而且没有已发布的包能将安装程序重定向到该索引。如果你在仅有 CPU 的 Linux 机器上通过这种方式安装，DocSift 会在首次转换后告知你，而不会对数 GB 未使用的文件只字不提。

确认安装成功。请逐条运行以下命令；第二条会打印可执行文件的路径，下一步需要用到它。

docsift --version

which docsift

2. 将其注册到客户端

选择你使用的客户端即可。以下只需选一项。

Claude Code

$(which docsift) 会自动填入路径，因此可以按原样运行：

claude mcp add --scope user docsift -- "$(which docsift)" mcp

然后确认服务已启动——查看是否显示 docsift ... ✔ Connected：

claude mcp list

--scope user 会让它在每个项目中都可用；如果不加此选项，服务只会注册到你所在的目录。

Claude Code 的设置到此完成。 跳过下方的其他客户端，直接进入第 3 步。

VS Code

Copilot Agent 模式会读取单个项目中的 .vscode/mcp.json，或者读取适用于所有项目的 MCP: Open User Configuration 命令所打开的文件：

{
  "servers": {
    "docsift": {
      "type": "stdio",
      "command": "/replace/with/the/path/from/which/docsift",
      "args": ["mcp"]
    }
  }
}

Codex CLI

~/.codex/config.toml：

[mcp_servers.docsift]
command = "/replace/with/the/path/from/which/docsift"
args = ["mcp"]
startup_timeout_sec = 60

请按示例提高超时时间。Codex 默认只允许 10 秒，而 DocSift 启动时会加载 PyTorch，因此默认设置会将仍在启动中的服务报告为启动失败。

Claude Desktop、Cursor

这些客户端会读取 JSON 配置文件。对于 macOS 上的 Claude Desktop，该文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json；如果文件不存在，请创建它。

如果文件为空或是新建的，完整内容如下——请将命令替换为第 1 步中 which docsift 打印的路径：

{
  "mcpServers": {
    "docsift": {
      "command": "/replace/with/the/path/from/which/docsift",
      "args": ["mcp"]
    }
  }
}

如果文件中已有其他服务，请将 docsift 添加到它们旁边，而不是替换整个文件——注意前一项后的逗号：

{
  "mcpServers": {
    "something-you-already-had": {
      "command": "..."
    },
    "docsift": {
      "command": "/replace/with/the/path/from/which/docsift",
      "args": ["mcp"]
    }
  }
}

请使用绝对路径，不要只写 docsift。这些客户端无法可靠地继承 shell 的 PATH，路径错误或只写命令名会导致 ENOENT: no such file or directory。

然后重启应用——配置会在启动时读取。

请使用 which docsift 返回的绝对路径，不要只写 docsift。 MCP 客户端无法可靠地继承 shell 的 PATH，这是本地服务无法启动却没有提示的最常见原因。

3. 提问

无需学习任何命令——描述你想做什么：

搜索 ~/Documents/contract.pdf 中的终止条款

report.pdf 中关于 Q3 收入的内容是什么？

第一次询问一个新文件时，系统会转换它；对于 PDF，这个过程很慢—— 大约需要三分钟。这是启动开销，与页数无关：Docling 会在首次转换时从 HuggingFace 下载布局和表格模型，然后加载 PyTorch。因此，转换一个三页的 测试文件所需的时间，和转换一份三十页的报告差不多；选一个小文件来“快速 试试”也无济于事。

这只会发生一次。之后，系统会根据文件内容识别文件，即使你移动或重命名 文件，也能立即返回答案。

对于较长的 PDF，请先转换，再提问：

docsift convert big-report.pdf

这会填充 MCP 服务读取的同一缓存，因此第一个问题的响应速度和后续问题一样快。 这样也能绕过一个实际限制——MCP 客户端会为工具调用设置自己的超时时间；转换时间 足够长时，可能会超时并显示错误，即使转换最终本可以完成。

4. 检查是否正常工作

在让它处理真实 PDF 之前，先用一个能立即转换的文件验证配置。创建一个文件：

printf '# Test\n\nDocSift returns only the passages that match a question.\n' > /tmp/docsift-check.md

然后让你的助手使用指定的工具提问：

使用 docsift search_document 工具，在 /tmp/docsift-check.md 中搜索 "passages"

明确指定工具名称，并留意实际运行的是哪个工具。 如果只是随口一问， 助手往往会用自己的文件读取工具打开小文件并作答——你得到的答案虽然正确， 却完全没有用到 DocSift，这会让有问题的配置看起来像是正常工作的。如果助手报告 的是读取了文件，而不是调用了 docsift，这次检查就没有告诉你任何事情。

第一次调用时，系统会询问你是否允许运行工具——请批准；如果客户端提供 “不要再次询问”选项，也请选择它，这样后续提问就不会在思路中途被打断。

成功时，记录中会出现一次 docsift 工具调用，并返回那一句话。这不需要 PDF 或模型权重，因此如果这里失败，问题出在配置——命令不在 PATH 中，或服务 未注册——而不是转换。

接下来试试你自己的真实 PDF，并预期第一次提问需要一分钟。对于这种大小的 文档，该选哪种方式不言自明：通读全文代价很高，这时搜索就成了显而易见的选择。

有一项测试值得专门运行：询问文档中没有提及的内容。 你应该得不到任何 结果，而不是一个听起来似乎合理的答案。搜索是基于词项的，因此文本中没有 的词不会匹配任何内容——亲眼看到这一点，比成功查询十几次更能说明你可以 信任它到什么程度。

你会得到什么

两个工具：

• search_document — 最重要的工具。提供文件路径和问题；它会在首次 遇到文件时转换文件，然后只返回匹配的段落，并附上页码和章节标题。
• convert_document — 转换并索引文件，返回摘要（页数、词元估算值、分块数）， 而不是文本。

预期效果

在搭载 Apple 芯片的 MacBook Air 上测试，使用一份 34 页、1.7 MB 的 PDF——一份 BusinessEurope 经济展望报告。选择它是因为它正是这款工具要处理的棘手文档类型：密集的表格、脚注，以及多栏排版内容。

整份文档	约 21,000 个 token，42 个分块
回答一个问题	约 4,000 个 token，5 段内容，并附可引用的页码
首次转换	约 3 分钟——大部分时间用于一次性下载模型
转换此后任意文件	几秒到一分钟，视文件大小而定
此后的每个问题	即时返回

Token 数量上的差距正是重点，而且文档越长，差距越大。

需要说清楚这 3 分钟花在哪里，因为很容易误以为“文档越大，处理越慢”。大部分时间都花在 Docling 首次运行时获取版面和表格模型，以及加载 PyTorch 上。在一台干净的 Linux 机器上，一份3 页、1.8 KB的 PDF 耗时 186 秒——与这份 34 页的报告基本相同。首次运行后，模型会保存在磁盘上，转换耗时便会随文档大小而变化。docsift convert 会全程显示动态进度指示器，你可以看到它正在工作，而不用猜测。

search_document 还接受 limit 和 max_tokens 参数；当你要求更多或更少内容时，模型会设置这些参数。默认设置会在 5,000-token 预算内返回 5 段内容。密集文档会产生较大的分块——上面那份报告中的每块约有 1,000 个 token——因此，如果回答似乎被截断，调高 max_tokens 即可；这比让模型反复回答同一个问题更省。

这些数字没有体现一个注意事项：搜索基于词汇匹配，而非语义。 DocSift 会在 SQLite FTS5 中为分块建立索引，并使用 BM25 排序。它匹配你输入的词语——而不是同义词、释义或含义。搜索“termination clause”（终止条款）时，如果某个章节只提到“ending the agreement”（结束协议），就不会返回该章节。询问这份报告中的“energy prices”（能源价格）时，结果出现了运输和化肥成本相关章节，因为这些段落恰好包含这个短语；如果把问题表述为“why did transport costs rise?”（运输成本为何上涨？），可能完全找不到相关内容。

这是有意为之的取舍，并非疏忽：无需下载嵌入模型，无需重建索引，无需 GPU，没有任何内容离开你的设备，而且首次运行只需几分钟，而非十几分钟。如果你需要语义检索，DocSift 写出的 Markdown 和分块 JSON 可作为向量存储的干净输入——这确实是合理的需求，但目前这款工具还不支持。请参阅已知限制。

PowerPoint 的回答会引用幻灯片编号。 演示文稿按每张幻灯片分别分块，因此返回的段落会注明来自哪张幻灯片及其标题——就像 PDF 段落会标注页码一样。两者的字段都叫 pages；对于演示文稿，它表示幻灯片。演讲者备注也会被提取，并可供搜索。

演示文稿无法提供的是图表关系。 一张包含三个方框和两条箭头的幻灯片会提取出三个标签。文字会保留，但各元素之间的关系不会保留，因此 DocSift 无法判断两个方框之间的箭头表示什么。幻灯片中的图像完全不会被读取——截图中的文字无法通过搜索找到。

所有操作都在你的设备上的该进程中完成。没有进程监听端口，也没有任何文档内容通过网络传输。该服务拥有的文件系统访问权限，与启动它的用户完全相同。

它不在 claude.ai 连接器目录中，也不可能出现在那里。 claude.ai 在云端运行，无法在你的电脑上启动程序。本地 MCP 服务适用于运行在你自己设备上的应用——Claude Code、Claude Desktop、Codex、Cursor——在 Web 应用的连接器列表中搜索 DocSift 永远找不到它。

命令行

docsift convert report.pdf --max-tokens 800 --overlap 100
docsift convert report.pdf --engine markitdown
docsift inspect report.pdf
docsift compare report.pdf
docsift search doc_xxxxxxxxxxxx "operational risk"
docsift search doc_xxxxxxxxxxxx '"operational risk"' --limit 5 --context 1
docsift cache info
docsift cache clear

inspect 会报告 DocSift 对文件的处理方式，包括引擎、标识和缓存状态，而不会转换文件。compare 会使用两种引擎处理同一份文档，并为结果生成差异文件。

转换时会清除重复的页眉和页脚、页码及图像引用，然后将文本拆分为符合 token 预算的文本块，并保留其标题上下文。--keep-furniture 和 --keep-image-refs 可关闭相应的清理阶段。

结果会缓存，因此文件和设置均未更改时，可立即返回结果。--no-cache 会强制重新运行。

搜索使用本地 SQLite FTS5 进行关键词排序，并支持带引号的词组。它会读取 HTTP 服务和 MCP 服务写入的存储库；docsift convert 会将独立文件写入输出目录，但不会将其添加到该存储库中。--context 会提取相邻文本块，--max-tokens 会限制整个响应的长度，且只会打印选中的文本块。分数用于对单次响应中的结果排序，不同请求之间的分数不可比较。

HTTP API

pip install "docsift[all]"
docsift serve

转换始终在后台运行：较长的 PDF 可能需要几分钟，而等待同步响应的客户端会超时。

上传后会返回 202，其中包含作业 ID 和文档 ID：

curl -sS -F [email protected] http://127.0.0.1:8000/v1/documents

轮询，直到状态变为 succeeded 或 failed：

curl -sS http://127.0.0.1:8000/v1/jobs/job_xxxxxxxxxxxxxxxx

然后获取整份文档：

curl -sS http://127.0.0.1:8000/v1/documents/doc_xxxxxxxxxxxx/markdown
curl -sS http://127.0.0.1:8000/v1/documents/doc_xxxxxxxxxxxx/chunks

也可以提出问题，只获取相关文本块：

curl -sS --get --data-urlencode 'q=operational risk' \
  --data 'limit=5' --data 'max_tokens=5000' \
  http://127.0.0.1:8000/v1/documents/doc_xxxxxxxxxxxx/search

DELETE /v1/documents/{id} 会删除文档、其搜索索引和缓存的转换结果，也会取消仍在进行的转换，因此删除操作不会因工作进程随后完成任务而被撤销。OpenAPI 文档位于 /openapi.json。

请先设置 DOCSIFT_API_KEY，再允许任何其他对象访问该服务。 设置后，每个 /v1/* 路由都需要 X-API-Key 请求头，而 /health、/version 和 API 文档仍保持开放，以便进行健康检查和连接器导入。整个服务共用一个密钥——它不代表每个用户的身份，也不能替代网络访问控制。该服务会转换收到的任何文件，因此请在自己控制的基础设施上运行它。

Power Platform、Copilot Studio 和 n8n

DOCSIFT_PUBLIC_URL=https://docsift.example docsift openapi --format swagger2 -o connector.json

将其导入为 Power Platform 自定义连接器。服务自身的 /openapi.json 使用 OpenAPI 3.1，自定义连接器会拒绝该格式；此命令会生成其支持的 Swagger 2.0 格式。已在真实租户中验证：文件可以导入并进行身份验证，且会返回符合架构的响应。

示例中提供了可运行的示例，包括可导入的 n8n 工作流、Copilot Studio 连接器操作指南，以及用于等待转换完成的 Power Automate Do until 流程。更详细的指南请参阅 docs/USING_DOCSIFT.md。

更多

已知限制	DocSift 不会做什么，直言不讳。在依赖它之前值得一读。
配置	所有环境变量。
Docker	在容器中运行服务。
部署到 Azure	端到端的托管部署。
隐私	哪些内容会写入磁盘，以及网络访问的三种情况。
安全	威胁模型，以及如何报告漏洞。
贡献	设置、门槛，以及评审关注的内容。
更新日志	发布了什么，以及发布时间。

许可证

MIT