MCP Document Converter

🚀 MCP Document Converter

The MCP (Model Context Protocol) Document Converter is a powerful tool designed for converting documents across multiple formats. It empowers AI agents to effortlessly transform documents, streamlining the document handling process.

🚀 Quick Start

The MCP Document Converter can be quickly set up and used. You can install it via pip or from the source code. After installation, you can start converting documents using the provided interfaces.

✨ Features

• Multi-format Support: Supports 5 mainstream document formats: Markdown, HTML, DOCX, PDF, and Text.
• Bidirectional Conversion: Any format can be converted to any other format (5×5 = 25 conversion combinations).
• MCP Protocol: Compliant with MCP standards, can be used as a tool for AI assistants like Trae IDE.
• Plugin Architecture: Easy to extend with new parsers and renderers.
• Syntax Highlighting: HTML and PDF outputs support code syntax highlighting.
• Style Customization: Support for custom CSS styles.
• Metadata Preservation: Preserves document title, author, creation time, and other metadata during conversion.

📚 Documentation

• User Guide
• API Reference
• Contributing
• Changelog
• License

🔧 Technical Details

Architecture

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

Core Components

1. DocumentIR (Intermediate Representation): Unified abstraction for all documents, containing document tree, metadata, assets, etc.
2. BaseParser (Parser Base Class): Defines the parser interface, parses various formats into DocumentIR.
3. BaseRenderer (Renderer Base Class): Defines the renderer interface, renders DocumentIR into various formats.
4. ConverterRegistry (Registry): Manages all parsers and renderers, provides format lookup and auto - matching.
5. DocumentConverter (Conversion Engine): Coordinates parsers and renderers to complete document conversion.

Supported Formats

Input Formats (Parsers)

Output Formats (Renderers)

Conversion Matrix

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

📦 Installation

Using pip (Recommended)

pip install mcp - document - converter

From Source

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

💻 Usage Examples

As an MCP Tool

After configuration, AI assistants can directly call the following tools:

1. convert_document (Recommended)

Use a unified interface to convert any supported document type.

# 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 all supported document formats.

list_supported_formats()

3. get_conversion_matrix

Get the complete format conversion matrix.

get_conversion_matrix()

4. can_convert

Check if conversion from source format to target format is supported.

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

5. get_format_info

Get detailed information about a specific format.

get_format_info(format="markdown")

As a Python Library

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}")

📄 Tool Interface Details

convert_document

Convert a document from one format to another.

Parameters:

Options:

Example:

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

🔧 Extension Development

Adding a New Parser

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

Adding a New Renderer

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)

Registering Extensions

from mcp_document_converter.registry import get_registry

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

Testing

# Run all tests
python tests/test_conversion.py

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

Environment Variables

Dependencies

Core Dependencies

• mcp >= 1.26.0 - MCP protocol implementation
• pydantic >= 2.12.5 - Data validation

Parser Dependencies

• markdown >= 3.5.0 - Markdown parsing
• beautifulsoup4 >= 4.12.0 - HTML parsing
• python-docx >= 1.1.0 - DOCX parsing
• pypdf >= 6.7.4 - PDF parsing
• chardet >= 5.0.0 - Encoding detection
• pyyaml >= 6.0.0 - YAML parsing

Renderer Dependencies

• weasyprint >= 60.0 - PDF rendering
• pygments >= 2.17.0 - Code highlighting
• jinja2 >= 3.1.6 - Template engine
• reportlab >= 4.0.0 - PDF generation

Development Dependencies

• pytest >= 7.0.0 - Testing framework
• pytest-asyncio >= 0.21.0 - Async testing support
• pytest-cov >= 4.0.0 - Coverage reporting
• basedpyright >= 1.0.0 - Type checking
• ruff >= 0.1.0 - Linting and formatting

📄 License

MIT License

Contributing

Issues and Pull Requests are welcome!

Related Projects

• MCP Document Reader - MCP document reader supporting multiple document formats
• Model Context Protocol - Official Model Context Protocol documentation