mcp-document-converter

MCP 文档转换器

MCP（Model Context Protocol）文档转换器——一款功能强大的 MCP 工具，支持在多种格式之间转换文档，让 AI Agent 轻松转换文档。

🌐 语言：English | 中文

功能特性

• 多格式支持：支持 5 种主流文档格式：Markdown、HTML、DOCX、PDF 和 Text
• 双向转换：任意格式均可转换为其他任意格式（5×5=25 种转换组合）
• MCP 协议：符合 MCP 标准，可作为 Trae IDE 等 AI 助手的工具
• 插件架构：易于通过新解析器和渲染器进行扩展
• 语法高亮：HTML 和 PDF 输出支持代码语法高亮
• 样式自定义：支持自定义 CSS 样式
• 元数据保留：转换过程中保留文档标题、作者、创建时间等元数据

---

📚 文档

用户指南 · API 参考 · 贡献指南 · 更新日志 · 许可证

---

架构

flowchart TB
    subgraph Parsers["Parsers"]
        MD[Markdown]
        DOCX1[DOCX]
        HTML1[HTML]
        PDF1[PDF]
        TXT1[Text]
    end

    subgraph IR["Intermediate Representation (IR)"]
        DT[Document Tree]
        META[Metadata]
        ASSETS[Assets]
    end

    subgraph Renderers["Renderers"]
        HTML2[HTML]
        PDF2[PDF]
        MD2[Markdown]
        DOCX2[DOCX]
        TXT2[Text]
    end

    MD --> IR
    DOCX1 --> IR
    HTML1 --> IR
    PDF1 --> IR
    TXT1 --> IR
    
    IR --> HTML2
    IR --> PDF2
    IR --> MD2
    IR --> DOCX2
    IR --> TXT2

核心组件

1. DocumentIR（中间表示）：所有文档的统一抽象，包含文档树、元数据、资源等。
2. BaseParser（解析器基类）：定义解析器接口，将各种格式解析为 DocumentIR
3. BaseRenderer（渲染器基类）：定义渲染器接口，将 DocumentIR 渲染为各种格式
4. ConverterRegistry（注册表）：管理所有解析器和渲染器，提供格式查找和自动匹配
5. DocumentConverter（转换引擎）：协调解析器和渲染器，完成文档转换

支持的格式

输入格式（解析器）

格式	扩展名	MIME 类型	特性
Markdown	.md, .markdown, .mdown, .mkd	text/markdown	YAML Front Matter、GFM 扩展
HTML	.html, .htm	text/html	语义标签解析
DOCX	.docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document	样式、表格、图片
PDF	.pdf	application/pdf	文本提取与结构识别
Text	.txt, .text	text/plain	自动编码检测与结构识别

输出格式（渲染器）

格式	扩展名	MIME 类型	特性
HTML	.html	text/html	美观的样式、代码高亮、响应式设计
Markdown	.md	text/markdown	标准 Markdown 格式、YAML Front Matter
DOCX	.docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document	Word 文档格式、保留样式
PDF	.pdf	application/pdf	使用 WeasyPrint 生成，支持分页
Text	.txt	text/plain	纯文本，保留基本格式

转换矩阵

flowchart LR
    subgraph Sources["Source Formats"]
        MD_S[Markdown]
        HTML_S[HTML]
        DOCX_S[DOCX]
        PDF_S[PDF]
        TXT_S[Text]
    end

    subgraph Targets["Target Formats"]
        MD_T[Markdown]
        HTML_T[HTML]
        DOCX_T[DOCX]
        PDF_T[PDF]
        TXT_T[Text]
    end

    MD_S --> Targets
    HTML_S --> Targets
    DOCX_S --> Targets
    PDF_S --> Targets
    TXT_S --> Targets

安装

使用 pip（推荐）

pip install mcp-document-converter

从源代码安装

git clone https://github.com/xt765/mcp-document-converter.git
cd mcp-document-converter
pip install -e .

MCP 工具

此服务提供以下工具：

convert_document

将文档从一种格式转换为另一种格式。

参数：

• source_path（字符串，必填）：源文档的路径。
• target_format（字符串，必填）：目标格式（html、pdf、markdown、docx、text）。
• output_path（字符串，可选）：输出文件的路径。
• source_format（字符串，可选）：源文件的格式（如果未提供，则自动检测）。
• options（对象，可选）：其他选项，例如 template、css 和 preserve_metadata。

配置

在 Trae IDE / Claude Desktop 中使用

将以下内容添加到 MCP 配置文件中：

选项 1：使用 PyPI（推荐）

{
  "mcpServers": {
    "mcp-document-converter": {
      "command": "uvx",
      "args": [
        "mcp-document-converter"
      ]
    }
  }
}

选项 2：使用 GitHub 仓库

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

选项 3：使用 Gitee 仓库（在中国访问更快）

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

选项 4：使用 pip（手动安装）

首先安装软件包：

pip install mcp-document-converter

然后添加到配置中：

{
  "mcpServers": {
    "mcp-document-converter": {
      "command": "mcp-document-converter",
      "args": []
    }
  }
}

在 Cherry Studio 中使用

Cherry Studio 是一款功能强大的开源桌面 AI 客户端助手，支持通过 MCP 协议集成各种工具

配置示例：

使用示例：

用法

作为 MCP 工具

配置完成后，AI 助手可以直接调用以下工具：

1. convert_document（推荐）

使用统一接口转换任意受支持的文档类型。

# Markdown to HTML
convert_document(
    source_path="document.md",
    target_format="html"
)

# HTML to PDF
convert_document(
    source_path="document.html",
    target_format="pdf"
)

# DOCX to Markdown
convert_document(
    source_path="document.docx",
    target_format="markdown"
)

# Conversion with options
convert_document(
    source_path="document.md",
    target_format="html",
    output_path="output.html",
    options={
        "css": "custom.css",
        "preserve_metadata": True
    }
)

2. list_supported_formats

列出所有受支持的文档格式。

list_supported_formats()

3. get_conversion_matrix

获取完整的格式转换矩阵。

get_conversion_matrix()

4. can_convert

检查是否支持将源格式转换为目标格式。

can_convert(source_format="markdown", target_format="pdf")

5. get_format_info

获取特定格式的详细信息。

get_format_info(format="markdown")

作为 Python 库

from mcp_document_converter import DocumentConverter
from mcp_document_converter.registry import get_registry
from mcp_document_converter.parsers import MarkdownParser, HTMLParser
from mcp_document_converter.renderers import HTMLRenderer, PDFRenderer

# Register parsers and renderers
registry = get_registry()
registry.register_parser(MarkdownParser())
registry.register_parser(HTMLParser())
registry.register_renderer(HTMLRenderer())
registry.register_renderer(PDFRenderer())

# Create converter
converter = DocumentConverter(registry)

# Convert document
result = converter.convert(
    source="input.md",
    target_format="html",
    output_path="output.html"
)

if result.success:
    print(f"✅ Conversion successful: {result.output_path}")
else:
    print(f"❌ Conversion failed: {result.error_message}")

工具接口详情

convert_document

将文档从一种格式转换为另一种格式。

参数：

参数	类型	必填	说明
source_path	string	✅	源文件路径，支持绝对路径或相对路径
target_format	string	✅	目标格式：html、pdf、markdown、docx、text
output_path	string	❌	输出文件路径（可选，默认为源文件名）
source_format	string	❌	源格式（可选，根据文件扩展名自动检测）
options	object	❌	转换选项

选项：

选项	类型	默认值	说明
template	string	-	模板名称
css	string	-	自定义 CSS 样式
preserve_metadata	boolean	true	是否保留元数据
extract_images	boolean	true	是否提取图像

示例：

{
  "source_path": "/path/to/document.md",
  "target_format": "html",
  "output_path": "/path/to/output.html",
  "options": {
    "css": "body { font-family: Arial; }",
    "preserve_metadata": true
  }
}

扩展开发

添加新解析器

from typing import List, Union
from pathlib import Path
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"
    
    @property
    def mime_types(self) -> List[str]:
        return ["application/x-myformat"]
    
    def parse(self, source: Union[str, Path, bytes], **options) -> DocumentIR:
        # Read source file
        content = self._read_source(source)
        
        # Parse into DocumentIR
        document = DocumentIR()
        document.title = "My Document"
        
        # Add content nodes
        document.add_node(Node(
            type=NodeType.PARAGRAPH,
            content=[Node(type=NodeType.TEXT, content="Hello World")]
        ))
        
        return document

添加新渲染器

from typing import Any
from mcp_document_converter.core.renderer import BaseRenderer
from mcp_document_converter.core.ir import DocumentIR

class MyRenderer(BaseRenderer):
    @property
    def output_extension(self) -> str:
        return ".myext"
    
    @property
    def format_name(self) -> str:
        return "myformat"
    
    @property
    def mime_type(self) -> str:
        return "application/x-myformat"
    
    def render(self, document: DocumentIR, **options: Any) -> str:
        # Render DocumentIR to target format
        parts = []
        
        if document.title:
            parts.append(f"# {document.title}")
        
        for node in document.content:
            # Render each node
            pass
        
        return "\n".join(parts)

注册扩展

from mcp_document_converter.registry import get_registry

# Register new parser and renderer
registry = get_registry()
registry.register_parser(MyParser())
registry.register_renderer(MyRenderer())

测试

# Run all tests
python tests/test_conversion.py

# Run specific test
python tests/test_conversion.py::test_markdown_to_html

环境变量

变量	说明	默认值
MCP_CONVERTER_LOG_LEVEL	日志级别	INFO
MCP_CONVERTER_TEMP_DIR	临时文件目录	系统临时目录

依赖项

核心依赖项

• mcp >= 1.26.0 - MCP 协议实现
• pydantic >= 2.12.5 - 数据验证

解析器依赖项

• markdown >= 3.5.0 - Markdown 解析
• beautifulsoup4 >= 4.12.0 - HTML 解析
• python-docx >= 1.1.0 - DOCX 解析
• pypdf >= 6.7.4 - PDF 解析
• chardet >= 5.0.0 - 编码检测
• pyyaml >= 6.0.0 - YAML 解析

渲染器依赖项

• weasyprint >= 60.0 - PDF 渲染
• pygments >= 2.17.0 - 代码高亮
• jinja2 >= 3.1.6 - 模板引擎
• reportlab >= 4.0.0 - PDF 生成

开发依赖项

• pytest >= 7.0.0 - 测试框架
• pytest-asyncio >= 0.21.0 - 异步测试支持
• pytest-cov >= 4.0.0 - 覆盖率报告
• basedpyright >= 1.0.0 - 类型检查
• ruff >= 0.1.0 - 代码检查和格式化

许可证

MIT 许可证

参与贡献

欢迎提交问题和拉取请求！

相关项目

• MCP 文档阅读器 - 支持多种文档格式的 MCP 文档阅读器
• Model Context Protocol - Model Context Protocol 官方文档