# mcp-md2word

**Repository Path**: mcpfactory/mcp-md2word

## Basic Information

- **Project Name**: mcp-md2word
- **Description**: MCP Markdown to Word Converter
一个基于 MCP (Model Context Protocol) 的 Markdown 转 Word 文档服务。支持将 Markdown 格式文本转换为 Word 文档，并自动上传到阿里云 OSS，返回可下载链接。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-02
- **Last Updated**: 2025-11-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP Markdown to Word Converter

一个基于 MCP (Model Context Protocol) 的 Markdown 转 Word 文档服务。支持将 Markdown 格式文本转换为 Word 文档，并自动上传到阿里云 OSS，返回可下载链接。

An MCP (Model Context Protocol) server that converts Markdown to Word documents, automatically uploads to Alibaba Cloud OSS, and returns a download link.

## 功能特性 (Features)

- ✅ Markdown 到 Word 文档转换 (Markdown to Word conversion)
- ✅ 自动提取文档标题 (Automatic title extraction from markdown)
- ✅ 支持中文字体 (Chinese font support - SimSun)
- ✅ 自动生成目录 (Automatic table of contents generation)
- ✅ 自定义样式模板 (Custom styling with reference template)
- ✅ 云存储集成 (Alibaba Cloud OSS integration)
- ✅ A4 纸张格式，2.5cm 边距 (A4 paper with 2.5cm margins)

## 系统要求 (Requirements)

- Python 3.7+
- Pandoc 2.5+
- Alibaba Cloud OSS 账号 (Alibaba Cloud OSS account)

## 安装 (Installation)

### 1. 安装系统依赖 (Install System Dependencies)

首先安装 Pandoc 及相关包：

```bash
sudo apt-get update
sudo apt-get install -y pandoc pandoc-data pandoc-citeproc
```

或者使用项目提供的包列表：

```bash
# 从 packages.txt 安装
sudo apt-get install -y $(cat packages.txt)
```

### 2. 创建 Python 虚拟环境 (Create Python Virtual Environment)

```bash
# 使用 uv (推荐)
uv venv

# 或使用标准 venv
python3 -m venv venv
source venv/bin/activate
```

### 3. 安装 Python 依赖 (Install Python Dependencies)

```bash
# 使用 uv (推荐)
uv pip install -r requirements.txt

# 或使用 pip
pip install -r requirements.txt
```

### 4. 配置环境变量 (Configure Environment Variables)

复制示例配置文件并编辑：

```bash
cp .env.example .env
```

编辑 `.env` 文件，填入你的阿里云 OSS 配置：

```env
# OSS Configuration
OSS_ENDPOINT=https://oss-cn-shanghai.aliyuncs.com
OSS_BUCKET_NAME=your-bucket-name
OSS_REGION=cn-shanghai
OSS_ACCESS_KEY_ID=your-access-key-id
OSS_ACCESS_KEY_SECRET=your-access-key-secret
```

## 使用方法 (Usage)

### 在 MCP Factory 中调试 (Debug in MCP Factory)

在 MCP Factory 中调试非常简单，找到 `main.py` 即可一键实现单步调试，以避免频繁的部署，提升开发效率。

1. 打开 `main.py`
2. 运行 `__main__` 函数入口
3. 使用 IDE 的调试功能进行单步调试

### 作为 MCP 服务器运行 (Run as MCP Server)

```bash
python main.py
```

### 使用 markdown2word 工具 (Using the markdown2word Tool)

该服务提供了一个 MCP 工具 `markdown2word`，可以在 MCP 客户端中调用：

```python
# 示例：将 Markdown 转换为 Word
markdown_content = """
# 我的文档标题

## 介绍

这是一个示例文档。

## 主要内容

- 项目一
- 项目二
- 项目三
"""

# 调用工具，返回下载链接
download_url = markdown2word(markdown_content)
```

## 工作原理 (How It Works)

1. **标题提取** - 从 Markdown 内容中自动提取标题：
   - 优先使用一级标题 (`# Title`)
   - 如果没有标题，使用第一行非空内容
   - 默认标题为 "Document"

2. **Pandoc 转换** - 使用 Pandoc 将 Markdown 转换为 Word：
   - 应用自定义样式模板 (`reference.docx`)
   - 生成 3 级目录
   - 配置中文字体支持
   - A4 纸张，2.5cm 边距

3. **云存储上传** - 自动上传到阿里云 OSS：
   - 生成唯一文件名（UUID）
   - 上传到配置的 OSS bucket
   - 返回公共下载链接

## 项目结构 (Project Structure)

```
mcp-md2word/
├── main.py                 # MCP 服务器入口
├── handler.py              # 转换逻辑和 MCP 工具定义
├── reference.docx          # Word 样式模板
├── docx/                   # Word 模板源文件（解压格式）
│   ├── [Content_Types].xml
│   ├── docProps/          # 文档属性
│   └── word/              # 文档内容和样式
├── requirements.txt        # Python 依赖
├── packages.txt           # 系统包依赖
├── .env.example           # 环境变量示例
├── .env                   # 环境变量配置（需要创建）
└── README.md              # 项目文档
```

## 自定义样式模板 (Customizing the Style Template)

如果需要修改 Word 文档的样式：

1. 编辑 `docx/` 目录下的 XML 文件：
   - `docProps/core.xml` - 文档元数据
   - `word/styles.xml` - 样式定义
   - `word/document.xml` - 文档结构

2. 重新生成 `reference.docx`：
   ```bash
   cd docx
   zip -r ../reference.docx [Content_Types].xml _rels/ docProps/ word/
   ```

## 故障排除 (Troubleshooting)

### Pandoc 错误：openBinaryFile: inappropriate type

**问题**: Pandoc 无法打开参考文档

**解决方案**: 确保 `reference.docx` 文件存在：
```bash
cd docx
zip -r ../reference.docx [Content_Types].xml _rels/ docProps/ word/
```

### OSS 上传失败

**问题**: 无法上传到阿里云 OSS

**解决方案**:
1. 检查 `.env` 文件配置是否正确
2. 确认 OSS Access Key 有写入权限
3. 验证 bucket 名称和区域设置

### 中文字体显示问题

**问题**: 转换后的 Word 文档中文显示异常

**解决方案**:
1. 确保系统安装了 SimSun 字体
2. 检查 `reference.docx` 模板的字体配置

## 开发和测试 (Development and Testing)

项目包含多个测试文件：

```bash
# 测试转换功能
python test_conversion.py

# 测试本地转换
python test_local_conversion.py

# 测试 OSS 上传
python test_oss_upload.py

# 测试完整流程
python test_full_flow.py
```

## 依赖项 (Dependencies)

### Python 包
- `fastmcp` - MCP 服务器框架
- `pypandoc` - Pandoc Python 包装器
- `oss2` - 阿里云 OSS SDK
- `anyio` - 异步 I/O 支持
- `python-dotenv` - 环境变量加载

### 系统包
- `pandoc` - 文档转换工具
- `pandoc-data` - Pandoc 数据文件
- `pandoc-citeproc` - 引用处理

## 许可证 (License)

本项目采用 Apache License 2.0 许可证。详见 [LICENSE](LICENSE) 文件。

This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.

## 贡献 (Contributing)

欢迎提交 Issue 和 Pull Request！

## 相关链接 (Related Links)

- [MCP Factory](https://mcpfactory.com)
- [Pandoc 官方文档](https://pandoc.org)
- [阿里云 OSS 文档](https://help.aliyun.com/product/31815.html)