内容
# GroupDocs MCP — 一键安装程序
在开发人员机器上，从单个配置文件或引导式向导中设置任意GroupDocs MCP服务器子集。将其注册到您的AI客户端和/或生成`docker-compose.yml`文件。跨平台（PowerShell 5.1和7+）。
```powershell
./install-groupdocs-mcp.ps1 -Interactive # 首次运行：向导询问所有问题（包括安装后验证），保存配置
./verify-groupdocs-mcp.ps1 # 任何时候：重新验证每个已安装的产品
```
新机器？[`setup/`](setup/) 包含每个操作系统的单次运行前提条件引导程序（macOS / Linux / Windows — PowerShell，Docker 或 .NET 10 SDK，本地依赖项）。常见设置的预制配置位于 [`samples/`](samples/) 中。
## 文件
| 文件 | 用途 |
|---|---|
| `manifest.json` | 信任源目录：产品 → NuGet ID，Docker 镜像，服务器名称。添加产品时更新。 |
| `groupdocs-mcp.config.json` | **您的设置** — 产品，通道，客户端，共享路径，许可证，验证案例。由向导写入或手动编辑。 |
| `install-groupdocs-mcp.ps1` | 安装程序 / 卸载程序 / 向导。读取上述两个文件，写入客户端配置 / compose。 |
| `verify-groupdocs-mcp.ps1` | 安装后烟雾测试。读取 **相同的** 配置；对每个服务器运行 MCP 握手。 |
## 共享设置（所有产品的统一位置）
`groupdocs-mcp.config.json` 中的 `storagePath`、`outputPath` 和 `licensePath` **适用于所有产品** — 只需设置一次。安装程序会将其映射到每个通道：Docker 挂载 `storagePath → /data`，许可证目录 → `/license:ro`；NuGet 将其作为 `GROUPDOCS_MCP_*` 环境变量传递。缺少存储/输出文件夹时会创建；缺少许可证文件时会产生警告（服务器会回退到评估模式 — 空的 `licensePath` 始终是安全的）。验证脚本会重用相同的值，因此有效的安装会在无需额外设置的情况下通过验证。
## 快速入门
```powershell
# 1. 向导（或手动编辑 groupdocs-mcp.config.json）：
./install-groupdocs-mcp.ps1 -Interactive
# 2. 预览而不做任何更改：
./install-groupdocs-mcp.ps1 -DryRun
# 3. 应用，预热缓存，并在一次运行中验证设置：
./install-groupdocs-mcp.ps1 -Verify
# 4. 重启您的 AI 客户端。
```
## 配置文件
```jsonc
{
"channel": "docker", // docker | nuget
"registry": "ghcr", // ghcr | dockerhub （仅限 docker 通道）
"clients": ["claude-desktop", "vscode"],
"version": "latest", // "latest" 或固定版本，例如 "26.7.2"
"storagePath": "C:/docs", // 共享文档文件夹（如果不存在则创建）
"outputPath": "", // 可选的单独输出文件夹
"licensePath": "", // .lic 文件的可选路径（"" = 评估模式）
"products": ["metadata", "conversion", "comparison"]
}
```
- `products` **始终是显式列表**。使用 `"all"` 展开到每个单独的产品（不包括 Total — 它是捆绑包等效项）。单独列出 `"total"` 以获取一体化服务器。
- 任何 CLI 开关都会覆盖配置文件：
`-Channel`、`-Registry`、`-Products`、`-Clients`、`-Version`。
## 客户端
| 客户端 ID | 注册方式 | 位置 |
|---|---|---|
| `claude-desktop` | 文件合并 | `%APPDATA%\Claude\claude_desktop_config.json` （Win）/ `~/Library/Application Support/Claude/…` （mac）/ `~/.config/Claude/…` （Linux）— 根 `mcpServers` |
| `claude-code` | **`claude` CLI** (`claude mcp add --scope user`) | Claude Code 用户范围 |
| `vscode` | 文件合并 | VS Code **用户级** `mcp.json` （`%APPDATA%\Code\User\mcp.json` 等）— 根 `servers`；适用于每个工作区 |
| `vscode-workspace` | 文件合并 | `./.vscode/mcp.json` （当前目录）— 根 `servers` |
| `vs2022` | 文件合并 | `./.mcp.json` 在当前目录（放在您的 **解决方案根目录**）— 根 `servers` |
| `cursor` | 文件合并 | `~/.cursor/mcp.json` — 根 `mcpServers` |
| `windsurf` | 文件合并 | `~/.codeium/windsurf/mcp_config.json` — 根 `mcpServers` |
| `cline` | 文件合并 | VS Code 全局存储 `…/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` — 根 `mcpServers` |
| `codex` | **`codex` CLI** (`codex mcp add`) | Codex CLI 配置 |
通过 CLI 注册的客户端（`claude-code`、`codex`）需要其 CLI 位于 `PATH`；如果它丢失，则会跳过该客户端并显示警告，然后继续处理其他客户端。
JetBrains Rider 没有稳定的配置文件/CLI 接口 — 使用生成的条目作为参考，在那里手动注册（设置 → 工具 → AI 助手 → MCP）。
文件合并保留文件中的其他服务器，并在每次写入前创建带时间戳的 `.bak` 备份。所有 JSON 均以 **无 BOM 的 UTF-8** 编写。
## 通道
| | `docker` | `nuget` |
|---|---|---|
| 先决条件 | 仅限 Docker | .NET 10 SDK（+ Linux/macOS 上的 `libgdiplus`/`libfontconfig1`） |
| 本地依赖项 | 包含在镜像中 | 您安装它们 |
| Total / Parser | ✅ 支持 | ⛔ NuGet 阻止（> 250 MB）— 自动跳过 |
| 编写条目 | `docker run … <image>` | `dnx <pkg> --yes` + 环境变量 |
Docker 是推荐的默认通道（自包含，在发布矩阵上经过验证为绿色）。NuGet 对于 .NET 开发人员和每个产品的子集来说很方便。
## 开关
| 开关 | 效果 |
|---|---|
| `-Interactive` | 引导式向导；将答案保存到配置文件中。还会在没有配置文件时自动运行。 |
| `-SkipPreflight` | 跳过先决条件预检查。默认情况下，安装程序会在 **触摸任何内容之前** 验证通道的运行时（Docker 守护进程可达 / .NET 10 SDK + `dnx` 存在）；如果失败，它会打印确切的 `setup/<os>` 命令（向导会提供运行它）。Dry-runs 会发出警告并继续。 |
| `-Verify` | 安装后：预热缓存，然后对相同的产品/通道（自动级别）运行验证器。退出代码 = 验证结果。向导将其作为最后一个问题提供。 |
| `-DryRun` | 打印所有内容，不写入任何内容。始终先预览。 |
| `-Prewarm` | docker：`docker pull` 每个镜像。nuget：下载 **并首次启动** 每个包，关闭标准输入（服务器读取 EOF 并干净退出）— 防止冷缓存失败，即客户端在下载完成之前启动的大型包的管道内启动失败。 |
| `-EmitCompose` | 还会在当前目录中写入 `docker-compose.yml`（docker 通道）。 |
| `-Config <path>` | 使用不同的配置文件。 |
## 卸载 / 删除
`uninstall-groupdocs-mcp.ps1` 是可配置的删除工具。其默认设置是 "清理此机器" 的情况：**每个已知的 GroupDocs 服务器，从每个已知的客户端** — 与配置文件的内容无关，因此它也可以捕获配置更改后留下的条目。
```powershell
./uninstall-groupdocs-mcp.ps1 -DryRun # 预览完整扫描
./uninstall-groupdocs-mcp.ps1 # 从所有客户端删除所有 GroupDocs 服务器
./uninstall-groupdocs-mcp.ps1 -Products metadata,conversion # 仅限这些产品
./uninstall-groupdocs-mcp.ps1 -Clients claude-desktop,cursor # 仅限这些客户端
./uninstall-groupdocs-mcp.ps1 -RemoveImages # 还删除 docker 镜像
./uninstall-groupdocs-mcp.ps1 -PurgeNugetCache # 还删除缓存的 NuGet 包（dnx 重新下载）
./uninstall-groupdocs-mcp.ps1 -RemoveCompose # 还删除 ./docker-compose.yml
```
- `-Products` / `-Clients` 接受 `all` （默认值）或逗号分隔的子集。
- 配置文件中相同的非 GroupDocs 服务器保持不变，每个修改的文件在写入前都会有带时间戳的 `.bak` 备份。
- CLI 客户端通过 `claude mcp remove` / `codex mcp remove` 清除（如果 CLI 不在 PATH 中，则跳过并显示警告）。
- `-RemoveImages` 遵循 `-Registry` / `-Version` 以删除标签。
`./install-groupdocs-mcp.ps1 -Uninstall` 仍然有效 — 它转发到同一个脚本，范围限定在您的配置文件中列出的客户端。
## 验证已安装的产品
```powershell
./install-groupdocs-mcp.ps1 -Verify # 一键安装 + 预热 + 验证
./verify-groupdocs-mcp.ps1 # 自动级别（默认）- 零配置
./verify-groupdocs-mcp.ps1 -Level handshake # 最小：服务器启动 + 列出工具
./verify-groupdocs-mcp.ps1 -Level toolcalls # 严格：仅限显式 verify.cases
```
| 级别 | 证明内容 | 需要设置？ |
|---|---|---|
| `auto` （默认）| 握手 **加**，在可能的情况下，进行实际文档检查：在 `tools/list` 之后，验证器选择服务器的信息工具（`get_document_info` 或 `get_view_info` for Viewer）并针对 **存储路径中的第一个找到的文档** （或设置的 `verify.sampleFile`）调用它。无文档 / 无信息工具 → 降级为仅握手，仍然通过。 | 否 — 将任何文档放入存储文件夹中进行更深入的检查 |
| `handshake` | 服务器 **启动** （镜像拉取/运行或 `dnx` 解析）并通过 `initialize` → `tools/list` 返回其工具列表。适用于所有产品 + 两个通道。 | 否 |
| `toolcalls` | 握手 **加** 恰好是 `verify.cases` 中每个产品定义的 `tools/call`，针对 `verify.sampleFile`。没有案例的产品报告 `no-case`。 | 是 |
显式 `verify.cases` 条目始终优先于自动选择 — 使用它们来执行特定的工具或参数形状：
```jsonc
"verify": {
"level": "auto", // auto | handshake | toolcalls
"sampleFile": "sample.docx", // 可选 - 否则存储路径中的第一个文档
"cases": { // 可选的每个产品覆盖
"metadata": { "tool": "get_document_info", "args": { "file": { "filePath": "sample.docx" } } },
"conversion": { "tool": "get_document_info", "args": { "file": { "filePath": "sample.docx" } } }
}
}
```
当所有产品通过时，退出代码为 `0`，否则为 `1` — 因此可以直接用于 CI。工具参数使用 Mcp.Core 的 `FileInput` 形状：`{ "file": { "filePath": "<name>" } }`。
## docker-compose 替代方案
对于仅限 Docker 的商店，请跳过客户端注册并直接：
```powershell
./install-groupdocs-mcp.ps1 -EmitCompose -Clients @() # 写入 docker-compose.yml
docker compose up
```
## 交付渠道说明（为什么有此设计）
- **NuGet（`dnx`）** — 零预安装，自动拉取；需要 .NET 10 SDK 和 Linux/macOS 上的本机图形库。总/解析器超过 NuGet 的 250 MB 限制。
- **Docker（GHCR / Docker Hub）** — 自包含，本机依赖项捆绑；**开箱即用** 的跨平台路径和此处的首选通道。
- **GitHub Copilot / VS Code / Cursor / Windsurf / Cline** — *客户端* （注册目标），不是运行时；它们仍然在下面运行 dnx 或 docker。
- **MCP 注册表** (`io.github.groupdocs-*/…`) — 一个发现/验证索引，**尚不是批量安装程序**。
