Markdownify MCP Server - UTF-8 Enhanced

Markdownify MCP 服务 - UTF-8 增强版

这是 原始 Markdownify MCP 项目 的增强版本，改进了 UTF-8 编码支持，并优化了多语言内容处理。

中文文档

增强内容

• 全面支持 UTF-8 编码
• 优化了多语言内容处理
• 修复了 Windows 系统上的编码问题
• 改进了错误处理机制

与原始项目的主要区别

1. 增强编码支持：

   • 所有操作均全面支持 UTF-8
   • 正确处理中文、日文、韩文及其他非 ASCII 字符
   • 修复了 Windows 特有的编码问题（兼容 cmd.exe 和 PowerShell）

2. 改进错误处理：

   • 提供详细的中英文错误消息
   • 更妥善地处理网络问题引发的异常
   • 转换失败时提供平稳的回退机制

3. 扩展功能：

   • 新增对多个文件进行批量处理的支持
   • 增强了 YouTube 视频文字稿处理
   • 改进了从各种文件格式中提取元数据的能力
   • 更好地保留文档格式

4. 性能优化：

   • 优化了大型文件转换时的内存使用
   • 加快了多语言内容的处理速度
   • 减少了依赖项冲突

5. 改善开发体验：

   • 提供全面的调试选项
   • 提供详细的日志系统
   • 支持针对不同环境进行配置
   • 提供清晰的中英文文档

功能

支持将各种文件类型转换为 Markdown：

• PDF 文件
• 图像（含元数据）
• 音频（含转录文本）
• Word 文档（DOCX）
• Excel 电子表格（XLSX）
• PowerPoint 演示文稿（PPTX）
• 网页内容：
  • YouTube 视频文字稿
  • 搜索结果
  • 一般网页
• 现有 Markdown 文件

快速开始

1. 克隆此仓库：

   git clone https://github.com/JDJR2024/markdownify-mcp-utf8.git
   cd markdownify-mcp-utf8
   

2. 安装依赖项：

   pnpm install
   

   注意：这也会安装 uv 和相关的 Python 依赖项。

3. 构建项目：

   pnpm run build
   

4. 启动服务：

   pnpm start
   

要求

• Node.js 16.0 或更高版本
• Python 3.8 或更高版本
• pnpm 包管理器
• Git

详细安装指南

1. 环境设置

1. 安装 Node.js：

   • 从 Node.js 官方网站 下载
   • 验证安装：node --version

2. 安装 pnpm：

   npm install -g pnpm
   pnpm --version
   

3. 安装 Python：

   • 从 Python 官方网站 下载
   • 安装时确保将 Python 添加到 PATH
   • 验证安装：python --version

4. （仅限 Windows）配置 UTF-8 支持：

   # Set system-wide UTF-8
   setx PYTHONIOENCODING UTF-8
   # Set current session UTF-8
   set PYTHONIOENCODING=UTF-8
   # Enable UTF-8 in command prompt
   chcp 65001
   

2. 项目设置

1. 克隆仓库：

   git clone https://github.com/JDJR2024/markdownify-mcp-utf8.git
   cd markdownify-mcp-utf8
   

2. 创建并激活 Python 虚拟环境：

   # Windows
   python -m venv .venv
   .venv\Scripts\activate
   
   # Linux/macOS
   python3 -m venv .venv
   source .venv/bin/activate
   

3. 安装项目依赖项：

   # Install Node.js dependencies
   pnpm install
   
   # Install Python dependencies (will be handled by setup.sh)
   ./setup.sh
   

4. 构建项目：

   pnpm run build
   

3. 验证

1. 启动服务：

   pnpm start
   

2. 测试安装：

   # Convert a web page
   python convert_utf8.py "https://example.com"
   
   # Convert a local file
   python convert_utf8.py "path/to/your/file.docx"
   

使用指南

基本用法

1. 转换网页：

   python convert_utf8.py "https://example.com"
   

   转换后的 Markdown 将保存为 converted_result.md

2. 转换本地文件：

   # Convert DOCX
   python convert_utf8.py "document.docx"
   
   # Convert PDF
   python convert_utf8.py "document.pdf"
   
   # Convert PowerPoint
   python convert_utf8.py "presentation.pptx"
   
   # Convert Excel
   python convert_utf8.py "spreadsheet.xlsx"
   

3. 转换 YouTube 视频：

   python convert_utf8.py "https://www.youtube.com/watch?v=VIDEO_ID"
   

高级用法

1. 环境变量：

   # Set custom UV path
   export UV_PATH="/custom/path/to/uv"
   
   # Set custom output directory
   export MARKDOWN_OUTPUT_DIR="/custom/output/path"
   

2. 批量处理： 创建一个批处理文件（例如 convert_batch.txt），其中包含 URL 或文件路径：

   https://example1.com
   https://example2.com
   file1.docx
   file2.pdf
   

   然后运行：

   while read -r line; do python convert_utf8.py "$line"; done < convert_batch.txt
   

故障排除

1. 常见问题：

   • 如果遇到编码错误，请确保已正确设置 UTF-8
   • 如果在 Windows 上遇到权限问题，请以管理员身份运行
   • 如果遇到 Python 路径问题，请确保已激活虚拟环境

2. 调试：

   # Enable debug output
   export DEBUG=true
   python convert_utf8.py "your_file.docx"
   

用法

命令行

将网页转换为 Markdown：

python convert_utf8.py "https://example.com"

转换本地文件：

python convert_utf8.py "path/to/your/file.docx"

桌面应用集成

要将此服务与桌面应用集成，请在应用的服务配置中添加以下内容：

{
  "mcpServers": {
    "markdownify": {
      "command": "node",
      "args": [
        "{ABSOLUTE_PATH}/dist/index.js"
      ],
      "env": {
        "UV_PATH": "/path/to/uv"
      }
    }
  }
}

故障排除

1. 编码问题

   • 如果遇到字符编码问题，请确保将 PYTHONIOENCODING 环境变量设置为 utf-8
   • Windows 用户可能需要运行 chcp 65001 以启用 UTF-8 支持

2. 权限问题

   • 确保你拥有足够的文件读写权限
   • 在 Windows 上，你可能需要以管理员身份运行

致谢

本项目基于 Zach Caceres 的原始作品。感谢原作者的杰出贡献。

许可证

本项目继续采用 MIT License 授权。详情请参阅 LICENSE 文件。

贡献

欢迎贡献！提交 Pull Request 前，请：

1. 确保代码符合项目的编码规范
2. 添加必要的测试和文档
3. 更新 README 中的相关部分

联系方式

如有问题或建议：

1. 提交 Issue：https://github.com/JDJR2024/markdownify-mcp-utf8/issues
2. 创建 Pull Request：https://github.com/JDJR2024/markdownify-mcp-utf8/pulls
3. 电子邮件：[email protected]