如何在 .NET 上使用 GroupDocs.Parser 将文档工具接入 MCP 客户端

💡 完整可运行示例已在 GitHub 上提供: parser-mcp-document-tools-dotnet

平台挑战:为何文档工具在 MCP 边界卡住

基于 Docker 的文档工具用于 MCP 客户端是一种 GroupDocs.Parser.Mcp 在 .NET 上的部署模式,它将容器镜像与离线库检查(get_document_info、extract_text、extract_tables)配对。负责为助手提供文档工具的平台工程团队很少会纠结于“我们能解析 DOCX 吗?”而是会面对更棘手的问题:MCP 服务器必须以命名工具列表的形式出现在客户端配置中,而解析引擎体积太大,导致 GroupDocs.Parser.Mcp 只能以容器镜像形式发布,无法作为 NuGet 包提供。

当产品小组需要在 MCP 客户端中获取文档信息、纯文本以及可用于聊天的表格时,平台团队需要走两条路线。路线一是运维:使用 docker run 并挂载 /data 卷,使用诸如 :26.9.0 的固定标签,以及稳定的 mcpServers 条目。路线二是验证:在任何人依赖实时握手之前,证明 GroupDocs.Parser for .NET 返回的结果与这些工具返回的结果一致。任意一条路线出错,都会导致 MCP 客户端返回空结果,而不是单元测试失败。

这些团队真正需要的是:一段可以粘贴到 MCP 客户端的注册代码片段,以及离线的 C# 调用,用于生成 JSON、文本和 Markdown 供审查。我在合作伙伴要求在聊天中使用 extract_tables,但 Docker 尚未在开发者笔记本上获批时就遇到了这个问题——库的镜像让交付得以继续进行,而安全团队完成容器审查。

行业概览:GroupDocs.Parser.Mcp 发布在 ghcr.io/groupdocs-parser/parser-net-mcp,并且仅提供 Docker 分发,因为引擎体积超出 NuGet 大小限制。本地演示因此可以在不需要实时 MCP 会话的情况下验证等价工具 API(MCP 文档)。


为什么通用方案在这里行不通

团队在采用专用 MCP 文档服务器之前,通常会尝试以下路径:

  • 围绕桌面转换器的临时 Shell 脚本:在 DOCX 和 XLSX 上脆弱,且无法呈现命名的 MCP 工具。
  • 仅在私有 API 中调用 Parser:进程内可用,但 MCP 客户端永远看不到 get_document_info 或 extract_text 作为一等工具。
  • 等待 NuGet MCP 包:该服务器没有对应的 NuGet 包,唯一可用的路径是容器镜像。

GroupDocs.Parser 通过将 Docker MCP 服务器与您已有的 .NET 服务使用的相同 Parser API 配对,弥补了这一缺口。


方案:在平台 MCP 工作流中使用 GroupDocs.Parser

GroupDocs.Parser for .NET 成为 MCP 故事的验证半部。Parser.GetDocumentInfo、Parser.GetText、GetFormattedText(Markdown) 和 GetTables 镜像了 GroupDocs.Parser.Mcp 向 MCP 客户端公开的工具。示例仓库会生成 Result/mcp-server.example.json 用于注册,然后对捆绑的 DOCX 和 XLSX 文件执行三种最高频的工具,以便运维人员在 Result/ 下检查输出。

要按照下面的实现进行操作,您需要:

  • .NET 8 SDK
  • GroupDocs.Parser 26.10.0
    (临时许可证)
  • 示例文档(仓库中包含 sample.docx、sample.xlsx、sample.pdf)
  • 仅在启动实时 MCP 服务器时需要 Docker Engine
dotnet add package GroupDocs.Parser --version 26.10.0

步骤式实现 MCP 文档工具

下面展示如何注册 GroupDocs.Parser.Mcp 并验证等价工具 API。该场景对应平台小组在 .NET 8 上为助手上岗文档工具的过程。

步骤 1 - 生成 Docker MCP 注册信息

编写一个 mcpServers 条目,使容器以交互方式运行并挂载主机文档文件夹到 /data。在共享配置中固定标签。

// JSON for MCP clients: docker run --rm -i -v <host>:/data <image>
string normalizedHost = hostDocumentsPath.Replace('\\', '/');
var payload = new
{
    mcpServers = new
    {
        groupdocs_parser = new
        {
            command = "docker",
            args = new[]
            {
                "run", "--rm", "-i",
                "-v", $"{normalizedHost}:/data",
                McpImage
            }
        }
    },

继续添加工具列表并写入 UTF-8 JSON 供客户端导入:

    tools = new[]
    {
        "extract_text",
        "extract_tables",
        "extract_metadata",
        "extract_images",
        "extract_barcodes",
        "get_document_info",
        "get_license_status"
    },
    notes = "Pin the image tag in shared configs "
        + "(for example :26.9.0) instead of :latest."
};
var json = JsonSerializer.Serialize(
    payload,
    new JsonSerializerOptions { WriteIndented = true });
File.WriteAllText(outputPath, json, Encoding.UTF8);

步骤 2 - 镜像 get_document_info 进行预检

MCP 客户端通常在调用更重的工具前先执行 get_document_info。使用 Parser.GetDocumentInfo 镜像该合约,以保持模式稳定。

using var parser = new Parser(sourcePath);
var info = parser.GetDocumentInfo();

var payload = new
{
    fileName = Path.GetFileName(sourcePath),
    fileType = info?.FileType?.ToString(),
    pageCount = info?.PageCount,
    sizeBytes = info?.Size
};

File.WriteAllText(
    outputPath,
    JsonSerializer.Serialize(
        payload,
        new JsonSerializerOptions { WriteIndented = true }),
    Encoding.UTF8);

这些字段对平台运维的重要性:

  • fileType:确认解析器在文本工具运行前已识别文件格式
  • pageCount:为 MCP 客户端上下文预算提供廉价信号
  • sizeBytes:支持配额和对上传文件的异常检查

在捆绑的 sample.docx 上,记录的运行结果显示为 Microsoft Word Open XML 类型,2 页,15214 字节。

步骤 3 - 镜像 extract_text 生成助手可读输出

using var parser = new Parser(sourcePath);
using TextReader? reader = parser.GetText();
if (reader == null)
{
    File.WriteAllText(outputPath, string.Empty, Encoding.UTF8);
    return 0;
}

string text = reader.ReadToEnd();
File.WriteAllText(outputPath, text, Encoding.UTF8);
return text.Length;

返回字符数为 CI 和控制台提供可度量的成功信号,匹配运维人员对 MCP extract_text 工具的期望。

步骤 4 - 镜像 extract_tables 为聊天 UI 输出 Markdown

优先使用格式化的 Markdown,若不可用则回退到 GetTables 生成的管道表格,以保证聊天客户端拥有一致的渲染路径。

using var parser = new Parser(sourcePath);

using (TextReader? formatted = parser.GetFormattedText(
           new FormattedTextOptions(FormattedTextMode.Markdown)))
{
    if (formatted != null)
    {
        string markdown = formatted.ReadToEnd();
        File.WriteAllText(outputPath, markdown, Encoding.UTF8);
        int rows = 0;
        using var sr = new StringReader(markdown);
        string? line;
        while ((line = sr.ReadLine()) != null)
        {
            if (line.Contains('|', StringComparison.Ordinal))
                rows++;
        }
        return rows > 0
            ? rows
            : (string.IsNullOrWhiteSpace(markdown) ? 0 : 1);
    }
}

当格式化的 Markdown 不可用时,检查特性并处理结构化表格:

if (!parser.Features.Tables)
{
    File.WriteAllText(
        outputPath,
        "_Tables extraction is not supported for this file._\n",
        Encoding.UTF8);
    return 0;
}

IEnumerable<PageTableArea>? tables = parser.GetTables();
if (tables == null)
{
    File.WriteAllText(outputPath, "_No tables returned._\n", Encoding.UTF8);
    return 0;
}

下游系统可以将 Markdown 与源 XLSX 并存,或直接将管道表格喂入 MCP 客户端的聊天窗格,而无需二次转换。


为什么平台团队需要同时保留 Docker MCP 与库镜像?

当 MCP 客户端必须通过 ghcr.io/groupdocs-parser/parser-net-mcp 对 /data 下的文件调用命名工具时,保留 Docker MCP。 当需要在 PR 中证明 get_document_info、extract_text、extract_tables 在没有实时握手的情况下工作时,使用库镜像。这条双路径将容器策略与解析回归分离。固定生产标签并在每次 Parser 包升级时于 CI 中运行 .NET 镜像,如示例仓库所示。


实际工作流:为共享 MCP 客户端群组上岗文档工具

一个支持三个产品小组的平台团队维护一套 MCP 客户端基线。每个小组将 DOCX 政策文件和 XLSX 费率表放入共享文档卷。 在提升新的 parser-net-mcp 标签之前,团队运行 .NET 控制台宿主:重新生成注册 JSON,比较 document-info.json 与金标准值(烟雾 DOCX 为 2 页 / 15214 字节),记录文本字符数,并审查 XLSX 示例中 Sheet1/Sheet2 的 Markdown 是否符合管道表格结构。

该工作流直接对应上述步骤。步骤 1 为整机配置,步骤 2‑4 为离线闸门。只有闸门全部通过后,固定标签的容器镜像才会部署到 MCP 客户端主机。针对 Docker 特定的故障,运维人员可参考 MCP 故障排查指南。


业务影响:此举带来的改变

指标 之前(临时方案) 之后(GroupDocs.Parser + MCP)
客户端注册 手动记录,笔记本间漂移 已检入的 mcpServers JSON
工具合约检查 仅在实时 MCP 调用失败后发现 离线 JSON/文本/Markdown 固件
表格交付到聊天 自定义 CSV 转换器 与 extract_tables 对齐的 Markdown
包分发方式 期待 NuGet MCP 明确的仅 Docker 服务器 + NuGet 库
镜像漂移 使用 :latest 固定标签如 :26.9.0
审计轨迹 仅聊天日志 每次运行的 Result/ 产出

综合效果是加速 MCP 客户端的上岗流程,并在容器策略与解析行为不同步时减少生产环境的意外。


其他适用平台场景

注册和镜像就绪后,同样的 API 可支持:

  • 预摄取闸门:在 MCP 客户端运行前,根据 pageCount 或 sizeBytes 超出策略时拒绝上传
  • 电子表格简报:将 XLSX 中的 Markdown 表格发送至站会机器人
  • 多格式烟雾包:将 DOCX、XLSX、PDF 示例与 MCP 配置并存,进行每周回归
  • Sidecar 部署:在 .NET API 仍使用进程内 Parser 处理内部任务的同时,旁路运行 GroupDocs.Parser.Mcp

在您的平台环境中快速上手

您已经了解 GroupDocs.Parser 如何为平台团队在 .NET 上处理 MCP 文档工具。接下来的步骤:

资源