npm package: @mcpcn/markdown-converter
Description: Enhanced MCP server for converting markdown to PDF and Word documents with optimized code block display
Latest version: 1.0.11

# 统一Markdown转换MCP服务器

[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-1.0-orange.svg)](https://modelcontextprotocol.io/)

一个功能强大的MCP (Model Context Protocol) 服务器，支持将Markdown文档转换为PDF和Word格式。**特别优化了代码块显示效果**，确保在转换后的文档中代码的完美呈现。

## ✨ 主要特性

### 🔄 双格式支持
- **PDF转换**: 高质量PDF生成，支持模板、水印、语法高亮等高级功能
- **Word转换**: 专业级Word文档生成，**特别优化代码块显示效果**

### 🎨 丰富的自定义选项
- **PDF样式**: 内置经过优化的默认模板
- **Word主题**: default, github, dark, minimal 四种代码块主题
- **自定义样式**: 字体、颜色、间距等完全可定制

### ⚡ 性能优化
- **智能缓存**: 文件系统 + 内存双重缓存机制
- **并发控制**: 资源池管理，支持批量转换
- **增量处理**: 避免重复转换，提高效率

## 🛠️ 可用工具

### 1. `convert_to_pdf` - PDF转换
将Markdown内容或文件转换为PDF文件。

**参数:**
- `markdown` (必填): Markdown内容或.md文件路径
- `outputPath` (可选): 输出PDF文件路径
- `paperFormat` (可选): 页面格式 (a4/a3/a5/letter/legal/tabloid)
- `paperOrientation` (可选): 页面方向 (portrait/landscape)
- `watermark` (可选): 水印设置
- `enableSyntaxHighlight` (可选): 启用语法高亮
- `enableMermaid` (可选): 启用Mermaid图表

### 2. `convert_to_word` - Word转换
将Markdown内容或文件转换为Word文档，特别优化了代码块显示。

**参数:**
- `markdown` (必填): Markdown内容或.md文件路径
- `outputPath` (可选): 输出Word文件路径
- `theme` (可选): 代码块主题 (default/github/dark/minimal)
- `addFooter` (可选): 是否添加页脚页码
- `showLanguage` (可选): 是否显示代码块语言标识

### 3. `convert_batch` - 批量转换
批量转换多个Markdown文件。

**参数:**
- `files` (必填): Markdown文件路径列表
- `format` (可选): 输出格式 (pdf/word/both)
- `outputDir` (可选): 输出目录
- `theme` (可选): Word主题

### 4. `list_themes` - 列出主题
列出所有可用的Word代码块主题。

## 🎯 使用示例

### PDF转换示例
```javascript
// 转换文件
{
  "tool": "convert_to_pdf",
  "arguments": {
    "markdown": "/path/to/document.md",
    "outputPath": "/path/to/output.pdf",
    "watermark": {
      "text": "Draft",
      "opacity": 0.1
    }
  }
}

// 转换内容
{
  "tool": "convert_to_pdf",
  "arguments": {
    "markdown": "# 我的文档\n\n```python\nprint('Hello World')\n```"
  }
}
```

### Word转换示例
```javascript
// 转换文件
{
  "tool": "convert_to_word",
  "arguments": {
    "markdown": "/path/to/document.md",
    "outputPath": "/path/to/output.docx",
    "theme": "github",
    "showLanguage": true
  }
}

// 批量转换
{
  "tool": "convert_batch",
  "arguments": {
    "files": ["/path/to/doc1.md", "/path/to/doc2.md"],
    "format": "both",
    "outputDir": "/path/to/output",
    "theme": "dark"
  }
}
```

## 🎨 代码块主题

### Word文档主题
- **default**: 经典灰色背景，适合日常使用
- **github**: GitHub风格，清新简洁
- **dark**: 暗色主题，护眼舒适
- **minimal**: 极简风格，简约优雅

每个主题都经过精心调优，确保代码的可读性和美观性。

## ⚙️ 环境变量

- `OUTPUT_DIR`: 默认输出目录 (默认: 用户主目录)
- `MAX_CONCURRENT`: 最大并发数 (默认: 2)
- `MAX_BROWSERS`: 最大浏览器实例数 (默认: 3)
- `DISABLE_CACHE`: 禁用缓存 (设置为 'true' 禁用)

## 📁 项目结构

```
src/
├── core/                    # 核心转换器
│   ├── BaseConverter.ts     # 抽象基类
│   ├── PDFConverter.ts      # PDF转换器
│   └── WordConverter.ts     # Word转换器
├── config/                  # 配置文件
│   └── word.ts             # Word样式配置
├── templates/              # 模板资源
│   ├── pdf/               # PDF模板
│   └── word/              # Word模板
├── types/                 # 类型定义
└── index.ts              # MCP服务器入口
```

## 🔧 开发

### 安装依赖
```bash
npm install
```

### 构建项目
```bash
npm run build
```

### 运行服务器
```bash
npm start
```

### 开发模式
```bash
npm run dev
```

## 📄 技术栈

- **TypeScript**: 类型安全的JavaScript超集
- **MCP SDK**: Model Context Protocol 软件开发包
- **Puppeteer**: PDF生成和页面渲染
- **docx**: Word文档生成库
- **Remarkable**: Markdown解析器

## 🌟 亮点功能

### 1. 完美的代码块显示
基于原md-to-word-mcp项目的成功实现，每一行代码都作为独立段落处理，确保：
- 保持原有缩进结构
- 支持多种编程语言
- 语法高亮效果
- 边框和背景美化

### 2. 智能缓存机制
- **文件缓存**: 转换结果持久化存储
- **内存缓存**: HTML渲染结果临时缓存
- **自动清理**: 过期缓存自动清理
- **缓存键优化**: 基于内容和配置生成唯一键

### 3. 资源优化管理
- **浏览器池**: 复用Puppeteer实例
- **并发控制**: 防止资源过度使用
- **优雅关闭**: 确保资源正确释放

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📜 许可证

MIT License

---

**本项目融合了以下优秀项目的精华：**
- 原 `enhanced-markdown2pdf-mcp` 的高性能PDF转换能力
- 原 `md-to-word-mcp` 的优化Word代码块显示技术

通过统一架构设计，为用户提供一站式Markdown文档转换解决方案。