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

> **GitHub**: [https://github.com/xt765/mcp-document-converter](https://github.com/xt765/mcp-document-converter)  
> **Gitee（国内镜像）**: [https://gitee.com/xt765/mcp-document-converter](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 输出都支持语法高亮：

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

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

## 如何快速使用？

### 安装

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

```bash
# 使用 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 配置中：

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

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

## 实际使用示例

### 示例 1：Markdown 转 HTML

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

### 示例 2：DOCX 转 Markdown

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

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

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

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

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

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

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

返回结果示例：

```json
{
  "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 分享给客户：

```python
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，构建静态文档网站：

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

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

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

```python
# 支持 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 时代的工具**。

## 如何扩展？

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

```python
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
```

然后注册到系统中：

```python
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](https://github.com/xt765/mcp-document-converter)
- Gitee（国内镜像）: [https://gitee.com/xt765/mcp-document-converter](https://gitee.com/xt765/mcp-document-converter)

## 写在最后

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

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

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

**立即体验**:
- [GitHub](https://github.com/xt765/mcp-document-converter)
- [Gitee（国内镜像）](https://gitee.com/xt765/mcp-document-converter)

---

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