使用说明

MCP Document Converter

MCP (Model Context Protocol) Document Converter - A powerful MCP tool for converting documents between multiple formats, enabling AI agents to easily transform documents.

🌐 Language: 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

核心组件

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

支持格式

输入格式（分析器）

格式	扩展名	MIME类型	功能
Markdown	.md、.Markdown、.mdown、.mkd	text/Markdown	YAML Front Matter、GFM扩展名
HTML	.HTML，.htm	text/HTML	语义标签解析
DOCX	.DOCX	应用程序/vnd.openxmlformats-offcedocument.wordprocessing.document	样式、表格、图像
PDF	.PDF	应用程序/PDF	文本提取和结构识别
文本	.txt、.Text	Text/plain	自动编码检测和结构识别

输出格式（渲染器）

格式	扩展名	MIME类型	功能
HTML	.HTML	text/HTML	美观的样式、代码突出显示、响应式设计
Markdown	.md	text/Markdown	标准Markdown格式，YAML Front Matter
DOCX	.DOCX	application/vnd.openxmlformats-offcedocument.wordprocessing.document	Word文档格式，样式保留
PDF	.PDF	应用程序/PDF	使用WeasyPrint生成，支持分页
文本	.txt	文本/纯文本	纯文本，保留基本格式

转换矩阵

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 （string，可选）：输出文件的路径。
source_format （字符串，可选）：源文件的格式（如果未提供，则自动检测）。
options （object，可选）：其他选项，如 template, css，以及 preserve_metadata.

配置

在Trae IDE/Claude桌面中使用

将以下内容添加到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()

3.get_conversion_matrix

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

get_conversion_matrix()

4.涵洞

检查是否支持从源格式到目标格式的转换。

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

5.获取格式信息

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

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_文档

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

参数：

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

选项：

选项	类型	默认值	描述
`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许可证

贡献

欢迎问题和拉取请求！