groupdocs-comparison-mcp

GroupDocs.Comparison MCP 服务

MCP 服务将 GroupDocs.Comparison 封装为可供 Claude、Cursor、GitHub Copilot 和其他 MCP Agent 调用的工具。

安装

一键安装会预填所有受支持的设置：安装后请编辑占位符文档文件夹（输出默认使用同一文件夹）；GROUPDOCS_LICENSE_PATH 为空时将以评估模式运行；将其指向你的许可证即可解除限制。

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

需要 .NET 10 SDK。

使用 dnx 直接运行（推荐——无需安装）：

dnx GroupDocs.Comparison.Mcp --yes

每次调用都会拉取最新的稳定版本。若要固定到特定版本（建议用于共享配置和 CI），请追加 @<version>：

dnx [email protected] --yes

或者，安装为全局 dotnet 工具：

dotnet tool install -g GroupDocs.Comparison.Mcp
groupdocs-comparison-mcp

或者，通过 Docker 运行：

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

原生运行的前置条件

底层 GroupDocs 引擎在某些操作中会使用 System.Drawing（GDI+）。在 Linux 或 macOS 上原生运行服务（通过 dnx 或全局 dotnet 工具）时，请先安装原生 libgdiplus 库：

平台	配置
Windows	无需操作 — GDI+ 已内置于操作系统中。
Linux	sudo apt-get install -y libgdiplus libfontconfig1 ttf-mscorefonts-installer
macOS	brew install mono-libgdiplus
Docker	无需操作 — 镜像已包含 libgdiplus。

在 Linux/macOS 上跳过此步骤会导致工具响应中出现 DllNotFoundException: libgdiplus。在 Linux/macOS 上，最简单的零配置选项是使用Docker 镜像。

可用的 MCP 工具

工具	说明
Compare	比较两个文档（源文档与目标文档），生成带标记的结果文件，并提供更改数量摘要和结构化 JSON 更改列表（类型、页码、更改片段、周围的源文档/目标文档文本、表格单元格、样式更改）。当用户需要渲染后的差异文档时使用。支持 PDF、Word、Excel、PowerPoint、ODT、RTF、TXT、HTML 及 30 多种其他格式；可选的 sourcePassword / targetPassword 可用于受保护的文档。
AnalyzeChanges	以纯结构化数据的形式返回两个文档之间的差异 — 与 Compare 相同的 JSON 更改列表，但不会渲染或保存结果文件。成本低于 Compare；当用户想要总结、解释或分析更改了什么，而不是获取带标记的文件时使用。可选的 sourcePassword / targetPassword。
GetDocumentInfo	检查单个源文档，并以 JSON 格式返回文件类型、页数、文件大小和每页尺寸 — 不执行比较。适合在决定是否比较或预期的格式之前进行预检。受保护的文档可使用可选的 password。

面向 AI Agent 的提示词示例

将服务连接到 MCP 客户端（Claude Desktop、Cursor、VS Code Copilot 等）后，可以尝试：

Compare old.pdf and new.pdf and save the marked-up result.

Diff contract-v1.docx against contract-v2.docx and tell me the change count.

What changed between proposal-v1.docx and proposal-v2.docx? Summarize the edits.

Did the prices change between budget-q1.xlsx and budget-q2.xlsx? Which cells?

How many pages does report.pdf have? Who's the author?

Inspect /docs/legal-brief.pdf — what's the file type and page count?

用户需要渲染后的差异文件时，客户端会选择 Compare；用户只想了解更改了什么（摘要/分析，不需要文件）时，会选择 AnalyzeChanges；仅需检查文档的问题则会选择 GetDocumentInfo。

许可

MCP 服务本身采用 MIT 许可；底层 GroupDocs.Comparison 引擎用于生产环境时需要许可证。未提供许可证时，服务会以评估模式运行：

• 比较结果可能带有评估水印/通知。
• 单个服务进程最多可打开 15 个文档；此后调用会因评估模式容量限制而失败，直到服务重启。

有两种方式为服务授权。

许可证文件 — 将 GROUPDOCS_LICENSE_PATH 指向你的 GroupDocs.Total.lic。可离线使用。

按量计费 — 同时设置 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-comparison/comparison-net-mcp:latest

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

配置

变量	描述	默认值
GROUPDOCS_MCP_STORAGE_PATH	输入和输出文件的根目录	当前目录
GROUPDOCS_MCP_OUTPUT_PATH	（可选） 输出文件的单独目录	GROUPDOCS_MCP_STORAGE_PATH
GROUPDOCS_LICENSE_PATH	GroupDocs 许可证文件的路径	（评估模式）
GROUPDOCS_METERED_PUBLIC_KEY	计量版公钥。也需要私钥；优先于许可证文件	（未设置）
GROUPDOCS_METERED_PRIVATE_KEY	计量版私钥。机密 - 请参阅许可	（未设置）

与 Claude Desktop 搭配使用

{
  "mcpServers": {
    "groupdocs-comparison": {
      "type": "stdio",
      "command": "dnx",
      "args": ["GroupDocs.Comparison.Mcp", "--yes"],
      "env": {
        "GROUPDOCS_MCP_STORAGE_PATH": "/path/to/documents"
      }
    }
  }
}

若要固定到特定版本，请在 args 中将 "GroupDocs.Comparison.Mcp" 替换为 "[email protected]"。建议在共享配置或已提交的配置中固定版本， 以避免意外升级。

与 VS Code / GitHub Copilot 搭配使用

NuGet.org 会在包页面生成可直接使用的 mcp.json 片段。 将其直接复制到 .vscode/mcp.json 中。

或者，手动添加到 .vscode/mcp.json：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "storage_path",
      "description": "Base folder for input and output files.",
      "password": false
    }
  ],
  "servers": {
    "groupdocs-comparison": {
      "type": "stdio",
      "command": "dnx",
      "args": ["GroupDocs.Comparison.Mcp", "--yes"],
      "env": {
        "GROUPDOCS_MCP_STORAGE_PATH": "${input:storage_path}"
      }
    }
  }
}

固定版本的规则与上文相同——将 "GroupDocs.Comparison.Mcp" 替换为 "[email protected]"，即可锁定到特定版本。

与 Docker Compose 搭配使用

cd docker
docker compose up

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

文档与指南

分步部署指南和已发布程序包的集成测试套件位于配套仓库 GroupDocs.Comparison.Mcp.Tests：

• 从 NuGet 安装 — dnx、全局工具、固定版本与始终使用最新版本
• 通过 Docker 运行
• 在 MCP 注册表中验证
• 与 Claude Desktop 搭配使用
• 与 VS Code / GitHub Copilot 搭配使用
• 运行集成测试

该仓库还会在 CI 中针对 Linux、macOS 和 Windows，使用已发布的 NuGet 程序包测试所有已宣传的工具，因此上述示例在每次发布时都会经过端到端验证。

许可证

MIT — 参见 LICENSE