groupdocs-search-mcp

GroupDocs.Search MCP 服务

MCP 服务将 GroupDocs.Search 封装为 AI 可调用的工具，供 Claude、Cursor、GitHub Copilot 和其他 MCP Agent 使用。它会在本地为 PDF、Office、电子邮件、压缩包及其他 70 多种文档格式的文件夹建立索引，然后支持对其进行全文、布尔、短语、模糊和日期范围查询——文档绝不会离开你的设备。

安装

一键安装会预填所有受支持的设置：安装后，请编辑卷挂载中的占位主机路径；GROUPDOCS_LICENSE_PATH 为空时，将以评估模式运行。

更多客户端——Claude Code、Codex CLI、Visual Studio 2022、Cursor、Windsurf、Cline 和 JetBrains Rider 的现成配置位于 install/generated/ 中。

本产品仅通过 Docker（GHCR）分发。 GroupDocs.Search 引擎 DLL 大约为 200 MiB，且包含 ONNX Runtime 原生库，因此打包后的工具（约 281 MiB）超过了 NuGet.org 的 250 MB 限制——无法使用 dnx 和 dotnet tool install。待更精简的引擎打包后低于该限制，标准 NuGet 安装流程将恢复（请参阅 .github/workflows/publish_prod.yml 中的回退说明）。

docker run --rm -i \
  -v $(pwd)/documents:/data \
  ghcr.io/groupdocs-search/search-net-mcp:latest

镜像支持多架构（linux/amd64 + linux/arm64），每次发布都会标记为 latest，并附带一个不可变的版本标签（例如 :26.10.1）。如需固定版本，请将 :latest 替换为版本标签——共享配置和 CI 推荐采用此做法。

Linux：以你的用户身份运行容器

该映像以非 root 用户（uid 1654）运行。在 Linux 上，挂载的文件夹会保留其主机所有者，因此你拥有的文件夹在容器内是只读的，索引会失败，并显示 "The index folder … is not writable"。添加 --user，让容器以你的身份写入：

docker run --rm -i --user "$(id -u):$(id -g)" \
  -v $(pwd)/documents:/data \
  ghcr.io/groupdocs-search/search-net-mcp:latest

MCP 客户端配置（JSON）不会运行 shell，因此请直接填写数字——id -u 和 id -g 会显示这些数字，通常为 1000："args": ["run", "--rm", "-i", "--user", "1000:1000", "-v", …]。Windows 和 macOS 上的 Docker Desktop 不需要这样设置。

索引存放位置

搜索是 GroupDocs MCP 系列中唯一的有状态服务：索引是文档文本的持久化、可搜索副本，重启后仍会保留。默认情况下，索引存放在文档文件夹内的 .groupdocs-search-index 文件夹中（容器内路径为 /data/.groupdocs-search-index），因此只需使用上面的一个卷挂载，且索引本身永远不会被索引。

如果文档文件夹是只读的，请将索引存放在单独的文件夹中：

docker run --rm -i \
  -v /path/to/documents:/data:ro \
  -v /path/to/index:/index -e GROUPDOCS_MCP_INDEX_PATH=/index \
  ghcr.io/groupdocs-search/search-net-mcp:latest

可用的 MCP 工具

工具	描述
add_to_index	为文件、文件夹（递归处理）或整个存储文件夹建立索引。按需创建索引。
search	查找与查询匹配的文档，按相关性排序，并返回出现次数 — 以 JSON 格式返回
get_text_fragments	返回匹配段落及其周围的词语，以便 Agent 引用或据此作答
update_index	重新读取已更改的文件，将已索引文件夹中的新文件加入索引，并删除已删除文件对应的索引
remove_from_index	从索引中移除已索引的路径（传递给 add_to_index 的文件夹或文件）；不会改动磁盘上的文件
create_index	创建或打开命名索引（contracts、hr/2026），也可以将其清空并重新创建
get_index_info	报告索引是否存在、文档数量、已索引路径、版本及其他索引 — 以 JSON 格式返回
get_license_status	报告当前许可模式（评估版 / 已许可 / 按量计费）、引擎版本，以及在按量计费模式下的已用额度和剩余额度。不处理任何文档。

路径始终相对于文档文件夹（contracts、reports/2026/q3.pdf），索引则通过名称而非文件系统路径来指定。多个命名索引可以并存。

查询语法（GroupDocs.Search DSL）：单词（invoice）；双引号内的短语（"force majeure" — 不带引号的多词输入不会匹配）；AND、OR、NOT 和括号； ? 字符通配符（?ffect、princip?(2~4)）；daterange(2026-01-01 ~~ 2026-06-30)；数字范围（100 ~~ 500）；字段前缀（filename: lease）；以 ^ 开头的正则表达式；以及通过 fuzzy 参数进行模糊匹配。

可建立索引的格式包括 PDF、DOC/DOCX、XLS/XLSX、PPT/PPTX、ODT/ODS/ODP、RTF、TXT、HTML、EPUB、FB2、 EML/EMLX/MSG、PST/OST、ONE 和 ZIP — 包括压缩包内的文档和电子邮件附件。 使用 includeSupportedFormats: true 调用 get_index_info，可列出引擎支持的全部格式。

面向 AI Agent 的提示词示例

服务器连接后，可将以下任一提示词复制到 Claude Desktop、Cursor 或 GitHub Copilot Chat 中。

1. 让文件夹可搜索："为我的 contracts 文件夹中的所有内容建立索引。"
2. 查找合适的文档："哪些合同提到了终止罚金？"
3. 阅读证据，而不是文件列表："显示谈到 "force majeure" 的段落，并注明每段来自哪个文件。"
4. 保持内容最新："我编辑了 reports 中的一些文件 — 刷新索引，然后再次搜索 Q3 预测。"
5. 分开管理内容集："为 HR 文件夹创建一个名为 hr 的索引，然后在其中搜索育儿假。"

许可

MCP 服务本身采用 MIT 许可；底层 GroupDocs.Search 引擎在生产环境中使用需要许可证。如果没有许可证，服务会以评估模式运行，限制按数量计算，而非水印——结果看起来完整，实际并不完整：

• 每个索引最多保存 100 个文档（在一个存储库的所有索引中合计）；达到上限后会停止索引。
• 每次搜索最多返回 10 个文档。
• 在此限制适用期间，每个工具响应都会附带一条 evaluation 说明。
• 完整列表：评估限制。

有两种方式可以为服务授权。

许可证文件——将你的 GroupDocs.Search.lic（或 GroupDocs.Total.lic）挂载到容器中，并将 GROUPDOCS_LICENSE_PATH 指向该文件。无需联网即可使用。

按量付费——设置 GROUPDOCS_METERED_PUBLIC_KEY 和 GROUPDOCS_METERED_PRIVATE_KEY。你只需为实际处理的内容付费。这种方式很适合 AI Agent，因为它们的用量波动较大，难以提前预测。如果同时配置了按量付费密钥和许可证文件，按量付费优先，许可证文件将被忽略。

**按量付费模式需要出站网络连接。**用量会报告给 GroupDocs 服务器，因此隔离网络或受防火墙保护的部署必须允许出站连接，或者改用许可证文件。

随时调用 get_license_status 工具，即可查看当前激活的模式，以及按量付费模式下已使用的数量和剩余额度。调用不会处理任何文档，也不会更改任何内容。

避免在配置中暴露私钥

按量付费私钥属于机密信息。MCP 客户端配置是磁盘上的纯文本文件，而项目级 .mcp.json 通常会提交到版本库，因此建议按以下优先顺序处理：

1. **在操作系统环境中设置变量，完全不在配置中填写。**stdio MCP 服务会继承客户端的环境，因此此方法适用于所有客户端。在 macOS 上请注意，从 Finder 启动的应用不会继承 shell 导出的变量；请使用 launchctl setenv，或从终端启动客户端。
2. 如果客户端支持，则通过间接引用变量（Claude Code 会展开 ${VAR}；VS Code 使用 ${env:VAR} 和 ${input:...}）。
3. 在用户级配置中填写字面值（例如 ~/.claude.json），对于个人开发者可以接受。
4. 切勿将字面密钥提交到项目级 .mcp.json 中。

对于 Docker，应转发这些值，而不要将其写入任何文件——只传递变量名，确保密钥不会出现在命令行中：

docker run --rm -i \
  -e GROUPDOCS_METERED_PUBLIC_KEY -e GROUPDOCS_METERED_PRIVATE_KEY \
  -v /path/to/documents:/data \
  ghcr.io/groupdocs-search/search-net-mcp:latest

• 获取免费的 30 天临时许可证
• 购买许可证 | 产品页面

配置

变量	描述	默认值
GROUPDOCS_MCP_STORAGE_PATH	存放待索引文档的文件夹；工具路径相对于此目录	./Files（映像中为 /data）
GROUPDOCS_MCP_OUTPUT_PATH	*（可选）*可写文件夹；未设置 GROUPDOCS_MCP_INDEX_PATH 时，索引将存放在此目录下	GROUPDOCS_MCP_STORAGE_PATH
GROUPDOCS_MCP_INDEX_PATH	*（可选）*存放索引的文件夹，每个索引名称对应一个子文件夹	<output or storage>/.groupdocs-search-index
GROUPDOCS_LICENSE_PATH	GroupDocs 许可证文件的路径，以容器内可见的路径为准。设置按量付费密钥时会被忽略	（评估模式）
GROUPDOCS_METERED_PUBLIC_KEY	按量付费公钥。还需要私钥；优先级高于 GROUPDOCS_LICENSE_PATH	（未设置）
GROUPDOCS_METERED_PRIVATE_KEY	按量付费私钥。机密信息——请通过环境传递，切勿放入已提交的配置中	（未设置）

由 GroupDocs.Search 22.7–26.8 写入的索引在首次打开时会转换为 26.10 格式；原始索引会保存在旁边，文件名为 <name>.pre-26.10-backup。

与 Claude Desktop 配合使用

{
  "mcpServers": {
    "groupdocs-search": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "/path/to/documents:/data", "ghcr.io/groupdocs-search/search-net-mcp:latest"]
    }
  }
}

要使用许可证，请在镜像名称前添加 "-v", "/path/to/license-folder:/license", "-e", "GROUPDOCS_LICENSE_PATH=/license/GroupDocs.Total.lic"。 要固定版本，请将 :latest 替换为发布标签。

与 VS Code / GitHub Copilot 配合使用

使用上方的 在 VS Code 中安装 按钮，或添加到 .vscode/mcp.json （也可在 install/generated/vscode-mcp.json 中找到）：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "storage_path",
      "description": "Folder with the documents to index.",
      "password": false
    }
  ],
  "servers": {
    "groupdocs-search": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "${input:storage_path}:/data", "ghcr.io/groupdocs-search/search-net-mcp:latest"]
    }
  }
}

使用 Docker Compose

cd docker
docker compose up

编辑 docker/docker-compose.yml，将卷指向本地文档文件夹。

文档与指南

分步部署指南和已发布镜像的集成测试套件位于配套仓库 GroupDocs.Search.Mcp.Tests：

• 通过 Docker 运行
• 在 MCP 注册表中验证
• 与 Claude Desktop 配合使用
• 与 VS Code / GitHub Copilot 配合使用
• 运行集成测试

许可证

MIT — 请参阅 LICENSE