shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

mcp-document-converter

MCP文档转换器是一个基于MCP协议的多格式文档转换工具，支持Markdown、HTML、DOCX、PDF和文本五种格式之间的双向转换，为AI助手提供强大的文档处理能力。

article

README

🚀 MCP文档转换器

MCP（模型上下文协议）文档转换器是一款强大的MCP工具，可实现多种格式文档间的转换，助力AI智能体轻松完成文档格式转换。

🚀 快速开始

你可以通过以下方式安装MCP文档转换器：

📦 使用pip（推荐）

pip install mcp-document-converter

📦 从源代码安装

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

✨ 主要特性

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

📚 详细文档

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

🔧 技术细节

架构

flowchart TB
    subgraph Parsers["解析器"]
        MD[Markdown]
        DOCX1[DOCX]
        HTML1[HTML]
        PDF1[PDF]
        TXT1[文本]
    end

    subgraph IR["中间表示 (IR)"]
        DT[文档树]
        META[元数据]
        ASSETS[资源]
    end

    subgraph Renderers["渲染器"]
        HTML2[HTML]
        PDF2[PDF]
        MD2[Markdown]
        DOCX2[DOCX]
        TXT2[文本]
    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前置元数据，GFM扩展 | | HTML | .html, .htm | text/html | 语义标签解析 | | DOCX | .docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document | 样式、表格、图像 | | PDF | .pdf | application/pdf | 文本提取和结构识别 | | 文本 | .txt, .text | text/plain | 自动编码检测和结构识别 |

输出格式（渲染器）

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

转换矩阵

flowchart LR
    subgraph Sources["源格式"]
        MD_S[Markdown]
        HTML_S[HTML]
        DOCX_S[DOCX]
        PDF_S[PDF]
        TXT_S[文本]
    end

    subgraph Targets["目标格式"]
        MD_T[Markdown]
        HTML_T[HTML]
        DOCX_T[DOCX]
        PDF_T[PDF]
        TXT_T[文本]
    end

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

💻 使用示例

作为MCP工具

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

1. convert_document（推荐）

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

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

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

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

# 带选项的转换
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

# 注册解析器和渲染器
registry = get_registry()
registry.register_parser(MarkdownParser())
registry.register_parser(HTMLParser())
registry.register_renderer(HTMLRenderer())
registry.register_renderer(PDFRenderer())

# 创建转换器
converter = DocumentConverter(registry)

# 转换文档
result = converter.convert(
    source="input.md",
    target_format="html",
    output_path="output.html"
)

if result.success:
    print(f"✅ 转换成功: {result.output_path}")
else:
    print(f"❌ 转换失败: {result.error_message}")

📄 工具接口详情

convert_document

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

参数

| 参数 | 类型 | 是否必需 | 描述 | |------|------|----------|------| | source_path | 字符串 | ✅ | 源文件路径，支持绝对或相对路径 | | target_format | 字符串 | ✅ | 目标格式：html, pdf, markdown, docx, text | | output_path | 字符串 | ❌ | 输出文件路径（可选，默认为源文件名） | | source_format | 字符串 | ❌ | 源文件格式（可选，从文件扩展名自动检测） | | options | 对象 | ❌ | 转换选项 |

选项

| 选项 | 类型 | 默认值 | 描述 | |------|------|--------|------| | template | 字符串 | - | 模板名称 | | css | 字符串 | - | 自定义CSS样式 | | preserve_metadata | 布尔值 | true | 是否保留元数据 | | extract_images | 布尔值 | 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:
        # 读取源文件
        content = self._read_source(source)
        
        # 解析为DocumentIR
        document = DocumentIR()
        document.title = "My Document"
        
        # 添加内容节点
        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:
        # 将DocumentIR渲染为目标格式
        parts = []
        
        if document.title:
            parts.append(f"# {document.title}")
        
        for node in document.content:
            # 渲染每个节点
            pass
        
        return "\n".join(parts)

注册扩展

from mcp_document_converter.registry import get_registry

# 注册新的解析器和渲染器
registry = get_registry()
registry.register_parser(MyParser())
registry.register_renderer(MyRenderer())

🧪 测试

# 运行所有测试
python tests/test_conversion.py

# 运行特定测试
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许可证。

👥 贡献

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

🔗 相关项目

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端