document-conversion-mcp

v1.0.2

Published

3 months ago

MCP server for document format conversion

0High
0Medium
0Low

smzy

mcp document conversion pdf word excel powerpoint markdown

Document Conversion MCP

一个强大的文档格式转换MCP (Model Context Protocol) 工具，支持多种文档格式之间的相互转换。

🌟 特性

多格式支持: 支持PDF、Word、Excel、PowerPoint、Markdown、HTML、文本等多种格式
批量转换: 支持批量处理多个文档
MCP协议: 完全兼容Model Context Protocol标准
本地运行: 在本地安装并运行，加速启动
跨平台: 支持任何有Node.js环境的系统
性能优化: 浏览器实例复用减少启动开销
增强错误处理: 详细日志记录和错误捕获
内存优化: 缓存大小限制防止内存泄漏

📋 支持的格式

输入格式

PDF (.pdf)
Microsoft Word (.docx, .doc)
Microsoft Excel (.xlsx, .xls)
Microsoft PowerPoint (.pptx, .ppt)
Markdown (.md, .markdown)
HTML (.html, .htm)
纯文本 (.txt)
CSV (.csv)
JSON (.json)

输出格式

PDF (.pdf)
Microsoft Word (.docx)
Microsoft Excel (.xlsx)
Microsoft PowerPoint (.pptx)
HTML (.html)
Markdown (.md)
纯文本 (.txt)
CSV (.csv)
JSON (.json)
图片 (.png, .jpg)

🚀 快速开始

系统要求

Node.js 18.0.0 或更高版本
npm 包管理器
支持MCP协议的客户端

推荐方式：NPX 一键部署 ⭐

最简单的使用方式，无需本地安装，自动获取最新版本！

在您的MCP客户端配置文件中添加以下配置：

{
  "mcpServers": {
    "document-conversion": {
      "command": "npx",
      "args": [
        "document-conversion-mcp"
      ],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

NPX 部署优势

✅ 零配置: 无需手动下载和安装
✅ 自动更新: 每次启动自动获取最新版本
✅ 跨平台: 支持Windows、macOS、Linux
✅ 即开即用: 一行配置即可使用
✅ 官方维护: 直接从npm官方源获取

本地开发部署

适合需要自定义修改或离线使用的场景。

MCP配置文件

{
  "mcpServers": {
    "document-conversion": {
      "command": "node",
      "args": [
        "e:\\Document-conversion\\mcp-tools.js"
      ],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

使用步骤

克隆项目: git clone https://github.com/renjismzy/Document-conversion.git
安装依赖: cd Document-conversion && npm install
配置MCP: 将上述配置添加到您的MCP客户端
启动服务: MCP客户端会直接启动本地服务

HTTP/SSE 云端部署

适合需要高可用性和负载均衡的生产环境。

使用streamable_http部署

{
  "mcpServers": {
    "document-conversion": {
      "type": "streamable_http",
      "url": "https://mcp.api-inference.modelscope.net/cd3990ec86b54d/mcp"
    }
  }
}

部署方式对比

| 特性 | NPX部署 (推荐) | 本地开发 | HTTP/SSE部署 | |------|----------------|----------|-------------| | 配置难度 | ⭐ 极简 | ⭐⭐ 简单 | ⭐ 极简 | | 启动速度 | ⭐⭐⭐ 快 | ⭐⭐⭐⭐ 最快 | ⭐⭐⭐ 快 | | 网络依赖 | 首次需要 | 无 | 需要 | | 自动更新 | ✅ 自动 | ❌ 手动 | ✅ 自动 | | 自定义修改 | ❌ 不支持 | ✅ 完全支持 | ❌ 不支持 | | 维护成本 | ⭐ 极低 | ⭐⭐⭐ 中等 | ⭐ 极低 |

使用建议

🎯 日常使用: 推荐 NPX部署，零配置，自动更新
🔧 开发调试: 推荐 本地开发，便于修改和调试
☁️ 云端环境: 推荐 HTTP/SSE部署，享受云端服务稳定性
📱 快速体验: 推荐 NPX部署，一行配置即可使用

🛠️ 统一转换工具

托管部署后，您将获得一个强大的统一文档转换工具 document_converter，支持8种不同的操作：

使用方法

所有功能都通过 document_converter 工具实现，通过 operation 参数指定具体操作：

1. 文档格式转换 (convert)

{
  "tool": "document_converter",
  "arguments": {
    "operation": "convert",
    "input_path": "./documents/report.docx",
    "output_path": "./output/report.pdf",
    "target_format": "pdf",
    "options": {
      "quality": 90
    }
  }
}

2. 获取文档信息 (get_info)

{
  "tool": "document_converter",
  "arguments": {
    "operation": "get_info",
    "file_path": "./documents/report.docx"
  }
}

3. 批量转换 (batch_convert)

{
  "tool": "document_converter",
  "arguments": {
    "operation": "batch_convert",
    "input_directory": "./documents",
    "output_directory": "./output",
    "target_format": "pdf",
    "file_pattern": "*.docx"
  }
}

4. 列出支持格式 (list_formats)

{
  "tool": "document_converter",
  "arguments": {
    "operation": "list_formats"
  }
}

5. 文件验证 (validate_file)

{
  "tool": "document_converter",
  "arguments": {
    "operation": "validate_file",
    "file_path": "./documents/report.docx"
  }
}

6. 目录扫描 (scan_directory)

{
  "tool": "document_converter",
  "arguments": {
    "operation": "scan_directory",
    "directory_path": "./documents",
    "file_extensions": ["docx", "pdf", "txt"]
  }
}

7. 转换预览 (preview_conversion)

{
  "tool": "document_converter",
  "arguments": {
    "operation": "preview_conversion",
    "input_path": "./documents/report.docx",
    "target_format": "pdf"
  }
}

8. 状态检查 (check_status)

{
  "tool": "document_converter",
  "arguments": {
    "operation": "check_status"
  }
}

📖 转换示例

PDF 转换

PDF → 文本: 提取PDF中的文本内容
PDF → Markdown: 转换为Markdown格式，自动识别标题
PDF → HTML: 转换为HTML网页格式
PDF → 图片: 将PDF页面转换为PNG/JPG图片

Word 文档转换

Word → PDF: 保持格式的PDF转换
Word → HTML: 转换为网页格式
Word → Markdown: 提取文本并转换为Markdown
Word → 文本: 纯文本提取

Excel 转换

Excel → CSV: 转换工作表为CSV格式
Excel → JSON: 将数据转换为JSON格式
Excel → HTML: 生成HTML表格

Markdown 转换

Markdown → HTML: 渲染为HTML网页
Markdown → PDF: 生成PDF文档
Markdown → Word: 转换为Word文档

⚙️ 配置选项

转换选项

quality: 图片质量 (0-100)
page_range: PDF页面范围，如 "1-5" 或 "1,3,5"
extract_images: 是否提取图片
sheet: Excel工作表名称

环境变量

NODE_ENV: 运行环境 (production/development)
MCP_SERVER_NAME: MCP服务器名称

🐛 故障排除

常见问题

npx下载失败
- 检查网络连接
- 确保npm版本为最新
- 尝试清除npm缓存: npm cache clean --force
Node.js版本不兼容
- 确保使用Node.js 18.0.0或更高版本
- 使用nvm管理Node.js版本
权限问题
- 在Windows上以管理员身份运行
- 在Linux/macOS上使用sudo（如需要）
PDF转换失败
- 确保PDF文件没有密码保护
- 检查文件路径是否正确

调试模式

如需调试，可以设置环境变量：

DEBUG=* npx --yes --package=https://github.com/renjismzy/Document-conversion.git -- node ./mcp-tools.js

🔄 版本更新

使用托管部署的优势之一是自动更新。每次启动MCP服务器时，npx会自动检查并下载最新版本。

如果您想强制更新到最新版本：

npm cache clean --force

更新日志

v1.0.0: 初始版本，支持基本转换
v1.1.0: 添加批量转换和文档信息提取
v1.2.0: 改进错误处理和添加更多格式支持
v1.3.0: 添加浏览器实例复用优化
v1.4.0: 添加增强错误处理、日志记录和内存优化

📞 支持与贡献

获取帮助

贡献代码

Fork 项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
打开Pull Request

📄 许可证

MIT License - 详见 LICENSE 文件

Document Conversion MCP - 让文档转换变得简单高效！ 🚀

💡 提示: 推荐使用托管部署方式，享受零配置、自动更新的便利体验！