# 我开发了一个 MCP 文档转换工具，让 AI 轻松搞定格式转换

> GitHub:https://github.com/xt765/mcp-document-converter
> Gitee（国内镜像）:https://gitee.com/xt765/mcp-document-converter

大家好，我是玄同765（xt765）。作为一名开发者，我一直想让 AI 更好地帮助我们处理日常工作。最近我遇到了一个痛点：如何让 AI 直接处理不同格式的文档？

比如，我想让 AI 读取一个 PDF 文件并总结内容，或者把 Markdown 转成 Word 文档发给同事。但 AI 往往只能输出文本，不能直接操作文件格式。这让我萌生了一个想法：开发一个能让 AI 直接调用的文档转换工具。

于是，MCP Document Converter诞生了。

## 为什么选择 MCP 协议？

在开发这个工具之前，我深入研究了 Anthropic 在 2024 年 11 月推出的MCP (Model Context Protocol，模型上下文协议)。

MCP 的设计理念让我眼前一亮：它就像 USB 接口统一了各种外设连接一样，旨在用一套标准协议打通所有 AI 工具与外部系统的连接。简单来说，MCP 就是 AI 世界的"通用语言"。

任何支持 MCP 的 AI 助手（如 Trae IDE、Claude Desktop 等），都可以通过统一的接口调用外部工具的能力。这正是我想要的！

## 我设计的核心功能

### 1. 支持 5 种主流格式

我选定了最常用的 5 种文档格式，覆盖绝大多数使用场景：

格式 | 扩展名 | 特点
--- | --- | ---
Markdown | .md, .markdown | 程序员最爱的文档格式，支持 YAML Front Matter
HTML | .html, .htm | 网页标准格式，支持代码高亮
DOCX | .docx | Microsoft Word 格式，办公必备
PDF | .pdf | 通用文档格式，适合打印和分享
Text | .txt, .text | 纯文本，最通用的格式

### 2. 25 种转换组合

我实现了任意格式之间的双向转换，形成5×5=25种转换组合：

    Markdown ↔ HTML ↔ DOCX ↔ PDF ↔ Text

无论你的源文档是什么格式，都可以轻松转换为目标格式。

### 3. 插件化架构

在设计架构时，我特别注重可扩展性。整个系统采用高度解耦的设计：

    ┌─────────────────────────────────────────────────────────┐
    │              MCP Document Converter                      │
    ├─────────────────────────────────────────────────────────┤
    │  Parsers (解析器)              Renderers (渲染器)        │
    │  ┌─────────────┐              ┌─────────────┐           │
    │  │ Markdown    │ ───────────→ │ HTML        │           │
    │  │ DOCX        │ ───────────→ │ PDF         │           │
    │  │ HTML        │ ───────────→ │ Markdown    │           │
    │  │ PDF         │ ───────────→ │ DOCX        │           │
    │  │ Text        │ ───────────→ │ Text        │           │
    │  └─────────────┘              └─────────────┘           │
    │         ↓                            ↓                  │
    │  ┌─────────────────────────────────────────────────┐    │
    │  │     统一中间表示 (Intermediate Representation)   │    │
    │  │  - Document Tree (文档树)                        │    │
    │  │  - Metadata (元数据)                             │    │
    │  │  - Assets (图片、附件等资源)                      │    │
    │  └─────────────────────────────────────────────────┘    │
    └─────────────────────────────────────────────────────────┘

核心设计思想：所有格式都先解析为统一的中间表示（DocumentIR），然后再渲染为目标格式。这样做的好处是：

- 新增格式只需实现一个解析器或渲染器
- 现有转换逻辑完全复用
- 代码高度解耦，易于维护

### 4. 代码高亮与样式定制

作为开发者，我特别在意代码的可读性。因此 HTML 和 PDF 输出都支持语法高亮：

    def hello_world():
        print("Hello, MCP Document Converter!")

同时支持自定义 CSS 样式，满足个性化需求。

## 如何快速使用？

### 安装

最简单的方式是通过`uvx`安装（无需手动配置 Python 环境）：

    # 使用 GitHub 仓库
    uvx --from git+https://github.com/xt765/mcp-document-converter mcp-document-converter

    # 或使用 Gitee 仓库（国内访问更快）
    uvx --from git+https://gitee.com/xt765/mcp-document-converter mcp-document-converter

### 在 Trae IDE 中配置

将以下内容添加到 Trae IDE 的 MCP 配置中：

    {
      "mcpServers": {
        "mcp-document-converter": {
          "command": "uvx",
          "args": [
            "--from",
            "git+https://github.com/xt765/mcp-document-converter",
            "mcp-document-converter"
          ]
        }
      }
    }

配置完成后，AI 助手就可以直接调用文档转换工具了！

## 实际使用示例

### 示例 1：Markdown 转 HTML

    # 让 AI 转换 Markdown 文件为 HTML
    convert_document(
        source_path="document.md",
        target_format="html",
        output_path="document.html"
    )

### 示例 2：DOCX 转 Markdown

    # 将 Word 文档转换为 Markdown
    convert_document(
        source_path="report.docx",
        target_format="markdown"
    )

### 示例 3：带自定义样式的转换

    # 转换并应用自定义 CSS
    convert_document(
        source_path="document.md",
        target_format="html",
        options={
            "css": "body { font-family: Arial; font-size: 14px; }",
            "preserve_metadata": True
        }
    )

### 示例 4：检查转换支持

    # 检查是否支持从 PDF 转到 DOCX
    can_convert(
        source_format="pdf",
        target_format="docx"
    )
    # 返回: {"can_convert": true, "message": "Supported: pdf to docx"}

### 示例 5：列出支持的格式

    # 获取所有支持的格式信息
    list_supported_formats()

返回结果示例：

    {
      "parsers": [
        {"format": "markdown", "extensions": [".md", ".markdown"]},
        {"format": "html", "extensions": [".html", ".htm"]},
        {"format": "docx", "extensions": [".docx"]},
        {"format": "pdf", "extensions": [".pdf"]},
        {"format": "text", "extensions": [".txt"]}
      ],
      "renderers": [...],
      "conversion_matrix": {
        "markdown": ["html", "pdf", "markdown", "docx", "text"],
        "html": ["html", "pdf", "markdown", "docx", "text"],
        ...
      },
      "summary": {
        "total_source_formats": 5,
        "total_target_formats": 5,
        "possible_conversions": 25
      }
    }

## 开发过程中的技术挑战

在开发这个工具的过程中，我遇到了几个技术挑战：

### 1. Windows 上的 PDF 渲染

最初我使用 WeasyPrint 作为 PDF 渲染引擎，但它依赖 GTK 库，在 Windows 上安装非常麻烦。为了解决这个问题，我：

- 将 WeasyPrint 设为可选依赖
- 引入 ReportLab 作为默认的 PDF 渲染方案
- 实现了自动检测和优雅降级

### 2. MCP 库的版本兼容性

MCP 库在 1.0.0 版本后有一些 API 变化，比如`ListToolsRequestParams`被移除。我及时更新了代码，确保兼容性。

### 3. 异步编程的处理

MCP 服务器使用异步编程模型，我设计了`main()`和`main_sync()`两个入口函数，确保 CLI 调用和 MCP 调用都能正常工作。

## 实际应用场景

这个工具在我的日常工作中已经帮了大忙：

### 场景 1：文档批量转换

我有一堆 Markdown 文档需要转换为 PDF 分享给客户：

    import os

    for file in os.listdir("docs"):
        if file.endswith(".md"):
            convert_document(
                source_path=f"docs/{file}",
                target_format="pdf",
                output_path=f"output/{file.replace('.md', '.pdf')}"
            )

### 场景 2：构建文档网站

将 Markdown 文档批量转换为 HTML，构建静态文档网站：

    convert_document(
        source_path="README.md",
        target_format="html",
        options={
            "css": "custom.css",
            "template": "docs"
        }
    )

### 场景 3：文档格式统一

团队成员使用不同格式编写文档，需要统一为 Markdown：

    # 支持 DOCX、PDF、Text 等多种格式转 Markdown
    convert_document(source_path="report.docx", target_format="markdown")
    convert_document(source_path="notes.txt", target_format="markdown")

## 与其他工具的比较

在开发之前，我调研了现有的文档转换工具：

特性 | MCP Document Converter | Pandoc | 在线转换工具
--- | --- | --- | ---
AI 集成 | ✅ 原生支持 MCP | ❌ 需命令行调用 | ❌ 手动操作
格式支持 | 5 种主流格式 | 50+ 格式 | 通常 5-10 种
自定义 | ✅ 支持 CSS/模板 | ✅ 支持模板 | ❌ 有限
批量处理 | ✅ 编程接口 | ✅ 命令行 | ❌ 通常不支持
私有化 | ✅ 完全本地 | ✅ 本地 | ❌ 上传云端
易用性 | ✅ AI 直接调用 | ⚠️ 需学习命令 | ✅ 图形界面

我的设计理念：不是要做功能最全的工具，而是要做最适合 AI 时代的工具。

## 如何扩展？

如果你想添加新的格式支持，只需实现相应的解析器或渲染器：

    from mcp_document_converter.core.parser import BaseParser
    from mcp_document_converter.core.ir import DocumentIR, Node, NodeType

    class MyParser(BaseParser):
        @property
        def supported_extensions(self) -> List[str]:
            return [".myext"]

        @property
        def format_name(self) -> str:
            return "myformat"

        def parse(self, source, **options) -> DocumentIR:
            # 实现解析逻辑
            document = DocumentIR()
            # ... 解析代码
            return document

然后注册到系统中：

    from mcp_document_converter.registry import get_registry

    registry = get_registry()
    registry.register_parser(MyParser())

## 未来规划

这个工具还在持续迭代中，我计划添加以下功能：

- [ ] 支持更多格式（如 EPUB、LaTeX、RTF）
- [ ] 添加图片和表格的高级处理
- [ ] 支持批量转换和目录监听
- [ ] 提供 REST API 接口
- [ ] 支持模板市场和自定义模板

## 邀请你一起参与

MCP Document Converter 是一个开源项目，我非常欢迎社区贡献：

- 提交 Issue: 如果你发现了 Bug 或有功能建议
- 提交 PR: 贡献代码，修复问题或添加新功能
- 分享使用经验: 帮助改进文档和示例

项目地址：
- GitHub:https://github.com/xt765/mcp-document-converter
- Gitee（国内镜像）:https://gitee.com/xt765/mcp-document-converter

## 写在最后

开发 MCP Document Converter 的初衷很简单：让 AI 更好地为我们服务。

在 AI 时代，我们不应该被文档格式所束缚。无论是开发者、内容创作者还是办公人员，只要需要处理不同格式的文档，这个工具都能为你节省大量时间和精力。

如果你也觉得这个工具有用，请在 GitHub 上给我一个 ⭐️ Star，这是对我最大的鼓励！

立即体验:
-GitHub
-Gitee（国内镜像）

我是玄同765（xt765），一个热爱开源和 AI 的开发者。欢迎与我交流！