Content
# MD2DOCX MCP Server
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
A unified document conversion server based on Model Context Protocol (MCP), supporting Markdown to DOCX, PPTX, and LaTeX/PDF formats.
## ✨ Features
- 🔄 **Unified Conversion** - Supports Markdown conversion to DOCX, PPTX, and LaTeX/PDF formats
- 📦 **Batch Processing** - Batch convert multiple files in a directory, supporting multiple output formats
- 🎨 **Template Support** - Built-in professional templates, supports custom templates
- ⚙️ **Intelligent Configuration** - Format-specific configuration options and parameters
- 🚀 **Parallel Processing** - Multi-threaded parallel conversion for improved efficiency
- 📊 **Detailed Logging** - Complete conversion process recording and statistics
- 🛡️ **Error Handling** - Intelligent error recovery and retry mechanism
- 📦 **Out-of-the-Box** - Built-in all dependencies, no additional installation required
- 🎯 **Table Optimization** - Improved table rendering, supports complex table structures
- 🌏 **Chinese Support** - Optimized Chinese font and typesetting processing
## 📚 Documentation
Detailed documentation and guides can be found in the [`docs/`](docs/) directory:
- 🚀 [MCP Installation Guide](docs/guides/MCP_INSTALLATION_GUIDE.md) - Quick installation and configuration
- 📊 [PPTX Template Guide](docs/guides/PPTX_TEMPLATE_GUIDE.md) - MD2PPTX format requirements
- 🚀 [Deployment Guide](docs/guides/DEPLOYMENT_GUIDE.md) - Detailed deployment instructions
- 🏗️ [PPTX Integration Design](docs/design/MD2PPTX_INTEGRATION_DESIGN.md) - PPTX architecture design document
- 🔧 [LaTeX Integration Design](docs/design/MD2LATEX_INTEGRATION_DESIGN.md) - LaTeX architecture design document
- 📝 [Example Files](docs/examples/) - Examples of various formats
- 🧪 [Test Files](tests/) - Functional test samples
## 🚀 Quick Start
### Method 1: One-Click Installation (Recommended)
```bash
# Clone the project (including all dependencies)
git clone --recursive https://github.com/ddipass/md2docx-mcp-server.git
cd md2docx-mcp-server
# Install dependencies
uv sync
# Ready to use!
```
### Method 2: Step-by-Step Installation
```bash
# Clone the main project
git clone https://github.com/ddipass/md2docx-mcp-server.git
cd md2docx-mcp-server
# Initialize submodules
git submodule update --init --recursive
# Install dependencies
uv sync
```
## 🔧 Amazon Q CLI Configuration
### 1. Get the Absolute Path of the Project
```bash
cd md2docx-mcp-server
pwd
# Copy the output path, e.g., /Users/username/md2docx-mcp-server
```
### 2. Configure the MCP Server
Add the following to the `~/.aws/amazonq/mcp.json` file:
```json
{
"mcpServers": {
"MD2DOCX": {
"command": "/absolute/path/to/md2docx-mcp-server/.venv/bin/mcp",
"args": [
"run",
"/absolute/path/to/md2docx-mcp-server/server.py"
],
"cwd": "/absolute/path/to/md2docx-mcp-server"
}
}
}
```
**Important**: Replace `/absolute/path/to/md2docx-mcp-server` with the actual path obtained in step 1.
### 3. Verify Installation
After starting the Amazon Q CLI, test the following command:
```
Use the get_conversion_status tool to check the server status
```
If you see output similar to the following, the installation was successful:
```
🔍 Unified Converter Status
🖥️ Server Information:
- Server Name: MD2DOCX-Converter (Unified Edition)
📊 Format Support:
- Supported Formats: DOCX, PPTX
- Available Converters: DOCX, PPTX
```
## 🎯 Usage Examples
### Basic Conversion
```python
# Convert to DOCX (default)
convert_markdown("/path/to/document.md")
# Convert to PPTX
convert_markdown("/path/to/document.md", "pptx")
# Convert to both formats simultaneously
convert_markdown("/path/to/document.md", "both")
```
### Batch Conversion
```python
# Batch convert to DOCX
batch_convert_markdown("/path/to/folder")
# Batch convert to multiple formats
batch_convert_markdown("/path/to/folder", ["docx", "pptx"])
```
### Template Conversion
```python
# Use a custom PPTX template
convert_with_template("/path/to/file.md", "pptx", "custom.pptx")
# Set the default template
quick_config_pptx_template("business.pptx")
```
## 🏗️ Architecture Design
### Project Structure
```
md2docx-mcp-server/
├── server.py # Main MCP server file
├── core/ # Core module
│ ├── config_manager.py # Configuration manager
│ ├── converter_manager.py # Original converter (backward compatibility)
│ └── unified_converter_manager.py # Unified converter
├── md2docx/ # Git Submodule (DOCX converter)
├── md2pptx/ # Git Submodule (PPTX converter)
├── config/ # Configuration file directory
├── output/ # Output directory
│ ├── docx/ # DOCX output
│ └── pptx/ # PPTX output
└── templates/ # Template directory (optional)
```
### Design Principles
1. **🔄 Unified Interface** - Same MCP tool interface, supports multiple output formats
2. **📦 Modularization** - Each format has an independent converter module
3. **⚙️ Configuration-Driven** - Unified configuration management, supports format-specific options
4. **🚀 Parallel Processing** - Supports simultaneous conversion of multiple formats
5. **🛡️ Error Isolation** - Failure in one format does not affect other formats
## 🛠️ Available Tools
### Unified Conversion Tools
| Tool Name | Description | Usage Example |
|---------|---------|---------|
| `convert_markdown` | Unified conversion tool | `convert_markdown("/path/to/file.md", "pptx")` |
| `batch_convert_markdown` | Batch multi-format conversion | `batch_convert_markdown("/path/to/folder", ["docx", "pptx"])` |
| `convert_with_template` | Template conversion | `convert_with_template("/path/to/file.md", "pptx", "template.pptx")` |
### Configuration Management Tools
| Tool Name | Description | Usage Example |
|---------|---------|---------|
| `quick_config_default_format` | Set the default format | `quick_config_default_format("pptx")` |
| `quick_config_pptx_template` | Set the PPTX template | `quick_config_pptx_template("business.pptx")` |
| `get_conversion_status` | Check the server status | `get_conversion_status()` |
### Backward Compatibility Tools
| Tool Name | Description | Usage Example |
|---------|---------|---------|
| `convert_md_to_docx` | Standalone DOCX conversion | `convert_md_to_docx("/path/to/file.md")` |
| `batch_convert_md_to_docx` | Batch DOCX conversion | `batch_convert_md_to_docx("/path/to/folder")` |
## 🎨 Template Support
### PPTX Templates
The project includes Martin Template.pptx as the default template. You can also:
1. **Use the built-in template**:
```python
quick_config_pptx_template("Martin Template.pptx")
```
2. **Use a custom template**:
```python
convert_with_template("/path/to/file.md", "pptx", "/path/to/custom.pptx")
```
### DOCX Templates
Custom DOCX templates are supported (feature under development).
## 🔧 Configuration Options
### Conversion Settings
- `supported_formats`: Supported output formats `["docx", "pptx"]`
- `default_format`: Default output format `"docx"`
- `debug_mode`: Debug mode switch
- `output_dir`: Default output directory
### PPTX Specific Settings
- `template_file`: Template file path
- `aspect_ratio`: Slide aspect ratio `"16:9"`
- `theme`: Theme settings
- `font_size`: Default font size
### DOCX Specific Settings
- `font_family`: Font family `"Arial"`
- `font_size`: Font size `12`
- `line_spacing`: Line spacing `1.15`
## 🚨 Troubleshooting
### Common Issues
1. **Submodules Not Initialized**
```bash
git submodule update --init --recursive
```
2. **Python Environment Issues**
```bash
source .venv/bin/activate
uv sync
```
3. **Permissions Issues**
```bash
chmod +x .venv/bin/mcp
```
4. **Incorrect Path Configuration**
- Ensure that absolute paths are used
- Check the `~/.aws/amazonq/mcp.json` configuration
### Getting Help
If you encounter any issues, please:
1. Run `get_conversion_status()` to check the status
2. Enable debug mode: `quick_config_debug_mode(True)`
3. View detailed error information
4. Report the issue on [GitHub Issues](https://github.com/ddipass/md2docx-mcp-server/issues)
## 📈 Version History
- **v1.2.0** - 🔧 Integrated MD2LaTeX improved version, supports LaTeX/PDF conversion, fixed table rendering issues
- **v1.1.0** - 🚀 Integrated md2pptx, supports unified DOCX/PPTX conversion
- **v1.0.0** - 🎉 First stable version, supports DOCX conversion
## 🤝 Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md).
## 📄 License
MIT License - See the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [md2docx](https://github.com/wangqiqi/md2docx) - DOCX conversion engine
- [md2pptx](https://github.com/MartinPacker/md2pptx) - PPTX conversion engine
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP protocol support
---
**🚀 Ready to get started? Follow the Quick Start guide above to get up and running in minutes!**
## 🛠️ MCP Tool Description
### Core Conversion Tools
#### `convert_md_to_docx`
Converts a single Markdown file to DOCX format
**Parameters:**
- `input_file` (str): Path to the input Markdown file
- `output_file` (str, optional): Path to the output DOCX file
- `debug` (bool, optional): Whether to enable debug mode
**Usage Examples:**
```python
convert_md_to_docx("/path/to/file.md")
convert_md_to_docx("/path/to/file.md", "/path/to/output.docx")
convert_md_to_docx("/path/to/file.md", debug=True)
```
#### `batch_convert_md_to_docx`
Batch converts Markdown files in a directory
**Parameters:**
- `input_dir` (str): Path to the input directory
- `output_dir` (str, optional): Path to the output directory
- `file_pattern` (str): File matching pattern (default "*.md")
- `parallel_jobs` (int, optional): Number of parallel jobs
**Usage Examples:**
```python
batch_convert_md_to_docx("/path/to/markdown/files")
batch_convert_md_to_docx("/input", "/output")
batch_convert_md_to_docx("/input", file_pattern="*.markdown")
batch_convert_md_to_docx("/input", parallel_jobs=8)
```
### File Management Tools
#### `list_markdown_files`
Lists Markdown files in a directory
**Parameters:**
- `directory` (str): Directory path
- `recursive` (bool): Whether to search recursively
**Usage Examples:**
```python
list_markdown_files("/path/to/directory")
list_markdown_files("/path/to/directory", recursive=True)
```
#### `validate_markdown_file`
Validates whether a Markdown file can be converted
**Parameters:**
- `file_path` (str): Path to the Markdown file
**Usage Examples:**
```python
validate_markdown_file("/path/to/file.md")
```
### Configuration Management Tools
#### `configure_converter`
Configures converter parameter settings
**Parameters:**
- `action` (str): Action type (show/update/reset)
- `setting_type` (str): Setting type (conversion/batch/file/server/all)
- `**kwargs`: Specific configuration parameters
**Usage Examples:**
```python
# Show all configurations
configure_converter("show", "all")
# Update conversion settings
configure_converter("update", "conversion", debug_mode=True, output_dir="/custom/output")
# Update batch settings
configure_converter("update", "batch", parallel_jobs=8, skip_existing=True)
# Update server settings
configure_converter("update", "server", md2docx_project_path="/path/to/md2docx")
# Reset configurations
configure_converter("reset")
```
#### Quick Configuration Tools
```python
# Quickly set debug mode
quick_config_debug_mode(True)
# Quickly set the output directory
quick_config_output_dir("/custom/output")
# Quickly set the number of parallel jobs
quick_config_parallel_jobs(8)
# Quickly set the MD2DOCX project path
quick_config_md2docx_path("/path/to/md2docx")
```
### Status Check Tools
#### `get_conversion_status`
Gets converter status and configuration information
**Usage Examples:**
```python
get_conversion_status()
```
## 🎯 MCP Prompts - Q CLI Smart Assistant
This server includes two intelligent MCP Prompts, providing interactive guidance for Q CLI users:
### 📄 `md2docx_conversion_guide`
**Smart Conversion Assistant** - Provides personalized conversion suggestions based on task type
**Features:**
- Automatically analyzes task type (single file, batch, configuration, debugging)
- Provides AI-recommended best solutions
- Displays a complete tool matrix and decision tree
- Includes quick start examples and important tips
**Q CLI Usage:**
```
Please use md2docx_conversion_guide to get conversion guidance
```
### 🔧 `md2docx_troubleshooting_guide`
**Troubleshooting Assistant** - Provides diagnosis and solutions for common issues
**Features:**
- Intelligently analyzes error type (path, format, permission, configuration issues)
- Provides a step-by-step diagnostic process
- Includes specific solutions for common problems
- Complete troubleshooting workflow
**Q CLI Usage:**
```
Please use md2docx_troubleshooting_guide to get troubleshooting help
```
These Prompts enable Q CLI to:
- 🤖 **Intelligent Recommendation**: Automatically recommend the most suitable tools and parameters based on user needs
- 📋 **Step-by-Step Guidance**: Provide clear operation steps and command examples
- 🔍 **Problem Diagnosis**: Quickly locate and resolve common issues
- 💡 **Best Practices**: Share usage tips and precautions
## Configuration Options
### ConversionSettings
- `debug_mode`: Debug mode switch
- `output_dir`: Default output directory
- `preserve_structure`: Preserve document structure
- `auto_timestamp`: Automatically add timestamp when file conflicts
- `max_retry_attempts`: Maximum number of retry attempts
### BatchSettings
- `parallel_jobs`: Number of parallel jobs
- `skip_existing`: Skip existing files
- `create_log`: Create conversion log
- `log_level`: Log level
### FileSettings
- `supported_extensions`: Supported file extensions
- `output_extension`: Output file extension
- `encoding`: File encoding
### ServerSettings
- `md2docx_project_path`: MD2DOCX project path
- `use_subprocess`: Whether to use subprocess calls
- `use_python_import`: Whether to directly import Python modules
## Usage
### 1. Subprocess Call Method (Recommended)
Call the CLI interface of the original md2docx project through a subprocess, completely isolated, safer and more stable.
### 2. Python Module Import Method
Directly import the Python module of the original md2docx project, which has better performance but requires handling dependency conflicts.
## 🔧 MCP Configuration
### Amazon Q CLI Configuration
Add the following configuration to the `~/.aws/amazonq/mcp.json` file:
```json
{
"mcpServers": {
"MD2DOCX": {
"command": "/absolute/path/to/md2docx-mcp-server/.venv/bin/mcp",
"args": [
"run",
"/absolute/path/to/md2docx-mcp-server/server.py"
],
"cwd": "/absolute/path/to/md2docx-mcp-server"
}
}
}
```
**Important**: Please replace `/absolute/path/to/md2docx-mcp-server` with your actual project path.
### Get Absolute Project Path
```bash
cd md2docx-mcp-server
pwd
# Copy the output path to the configuration file
```
### Verify Configuration
After starting the Amazon Q CLI, you should be able to see the MD2DOCX tool available. You can use the following command to test:
```
Use the get_conversion_status tool to check the server status
```
## 🎯 Q CLI Usage Guide
### Basic Usage Prompts
#### Single File Conversion
```
Please use the convert_md_to_docx tool to convert /path/to/document.md to DOCX format
```
#### Batch Conversion
```
Use the batch_convert_md_to_docx tool to batch convert all Markdown files in the /path/to/markdown/folder directory
```
#### Configuration Management
```
Use the configure_converter tool to update the server settings and set md2docx_project_path to /path/to/md2docx
```
For more detailed usage examples and prompts, please refer to:
- [Q CLI Usage Guide](./Q_CLI_USAGE_GUIDE.md) - Detailed prompt examples and workflows
- [Tool Reference Manual](./TOOLS_REFERENCE.md) - Complete tool function description
## Start Server (Development Mode)
```bash
# Activate the virtual environment
source .venv/bin/activate
# Start the MCP server
python server.py
```
## Error Handling
- **File Conflict**: Automatically add timestamp suffix
- **Permission Error**: Multiple retry mechanism
- **Encoding Error**: Automatic detection and handling
- **Path Error**: Detailed error information and suggestions
## Log Recording
- Support multi-level logging
- Automatically generate detailed log files for batch conversion
- Includes statistics such as conversion time, file size, and success rate
## Performance Optimization
- Multi-threaded parallel processing
- Intelligent task scheduling
- Memory usage optimization
- Asynchronous I/O operations
## Extensibility
- Modular design, easy to extend new functions
- Configuration-driven, supports custom parameters
- Plug-in architecture, supports adding new converters
## License
MIT License
## Contribution Guide
1. Fork the project
2. Create a feature branch
3. Submit changes
4. Push to the branch
5. Create a Pull Request
