MCP Document Converter

🚀 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（轉換引擎）：協調解析器和渲染器完成文檔轉換。

支持的格式

輸入格式（解析器）

輸出格式（渲染器）

轉換矩陣

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": "/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 >= 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 Document Reader - 支持多種文檔格式的MCP文檔閱讀器
• Model Context Protocol - 官方模型上下文協議文檔