mcp-pandoc: 一个文档转换MCP服务器

官方收录在 Model Context Protocol服务器 开源项目中。 🎉

概述

一个使用pandoc进行文档格式转换的Model Context Protocol服务器。该服务器提供工具，可以在不同文档格式之间转换内容，同时保留格式和结构。

请注意，mcp-pandoc目前处于早期开发阶段。PDF支持正在开发中，随着我们不断改进服务器，功能和可用工具可能会发生变化和扩展。

致谢：本项目使用Pandoc Python包进行文档转换，为本项目奠定了基础。

📋 快速参考

新使用mcp-pandoc？ 查看 📖 CHEATSHEET.md 以获取

• ⚡ 所有格式的复制粘贴示例
• 🔄 双向转换矩阵
• 🎯 常见工作流程和技巧
• 🌟 参考文档样式指南

非常适合快速查找和快速入门！

Demo

🎥 在YouTube上观看

截图

更多内容即将推出...

工具

1. convert-contents
   • 转换支持格式之间的内容
   • 输入：
     • contents (string): 要转换的源内容（如果未提供input_file则必需）
     • input_file (string): 输入文件的完整路径（如果未提供contents则必需）
     • input_format (string): 内容的源格式（默认为markdown）
     • output_format (string): 目标格式（默认为markdown）
     • output_file (string): 输出文件的完整路径（对于pdf、docx、rst、latex、epub格式必需）
     • reference_doc (string): 用于样式的参考文档路径（仅支持docx输出格式）
   • 支持的输入/输出格式：
     • markdown
     • html
     • pdf
     • docx
     • rst
     • latex
     • epub
     • txt
     • ipynb
     • odt
   • 注意：对于高级格式（pdf、docx、rst、latex、epub），需要指定output_file路径

📊 支持的格式和转换

双向转换矩阵

关于PDF支持的说明

该工具使用pandoc进行转换，这允许从上面列出的格式生成PDF文件。但是，从PDF转换到其他格式是不支持的。因此，PDF应被视为仅输出格式。

格式类别

每种格式的要求

• PDF (.pdf) - 需要 TeX Live 安装
• DOCX (.docx) - 支持通过参考文档自定义样式
• 所有其他 - 无需额外要求

注意：对于高级格式：

1. 需要带文件名和扩展名的完整文件路径
2. PDF转换需要安装TeX Live（见关键要求部分 -> 对于macOS: brew install texlive）
3. 当未指定输出路径时：
   • 基本格式：在聊天中显示转换后的内容
   • 高级格式：可能会保存在系统临时目录（/tmp/在Unix系统上）

使用和配置

注意：请确保完成安装下面“关键要求”中提到的必需包。

要使用发布的版本

{
  "mcpServers": {
    "mcp-pandoc": {
      "command": "uvx",
      "args": ["mcp-pandoc"]
    }
  }
}

💡 快速入门：查看 CHEATSHEET.md 获取复制粘贴示例和常见工作流程。

⚠️ 重要说明

关键要求

1. Pandoc安装

• 必需：安装pandoc - 核心文档转换引擎
• 安装：

  # macOS
  brew install pandoc
  
  # Ubuntu/Debian
  sudo apt-get install pandoc
  
  # Windows
  # 从以下链接下载安装程序：https://pandoc.org/installing.html
  

• 验证：pandoc --version

2. UV包安装

• 必需：安装uv包（包含uvx命令）
• 安装：

  # macOS
  brew install uv
  
  # Windows/Linux
  pip install uv
  

• 验证：uvx --version

3. PDF转换先决条件：仅当您需要转换并保存pdf时才需要

• 在尝试PDF转换之前必须安装TeX Live
• 安装命令：

  # Ubuntu/Debian
  sudo apt-get install texlive-xetex
  
  # macOS
  brew install texlive
  
  # Windows
  # 从以下链接安装MiKTeX或TeX Live：
  # https://miktex.org/ 或 https://tug.org/texlive/
  

4. 文件路径要求

• 当保存或转换文件时，您必须提供包括文件名和扩展名的完整文件路径
• 该工具不会自动生成文件名或扩展名

示例

✅ 正确用法：

# 转换内容为PDF
"将此文本转换为PDF并保存为 /path/to/document.pdf"

# 在文件格式之间转换
"将 /path/to/input.md 转换为PDF并保存为 /path/to/output.pdf"

# 使用参考文档模板转换为DOCX
"将 input.md 转换为DOCX，使用template.docx作为参考，并保存为 output.docx"

# 参考文档的逐步工作流程
"首先创建一个参考文档：pandoc -o custom-reference.docx --print-default-data-file reference.docx" 或如果您已经有了，使用那个
"然后使用自定义样式转换：将此文本转换为DOCX，使用 /path/to/custom-reference.docx作为参考，并保存为 /path/to/styled-output.docx"

❌ 错误用法：

# 缺少文件名和扩展名
"保存为PDF在 /documents/"

# 缺少完整路径
"转换为此为PDF"

# 缺少扩展名
"保存为 /documents/story"

常见问题和解决方案

1. PDF转换失败

   • 错误："xelatex not found"
   • 解决方案：首先安装TeX Live（见上面的安装命令）

2. 文件转换失败

   • 错误："Invalid file path"
   • 解决方案：提供包括文件名和扩展名的完整路径
   • 示例：/path/to/document.pdf 而不是 /path/to/

3. 格式转换失败

   • 错误："Unsupported format"
   • 解决方案：仅使用支持的格式：
     • 基本：txt, html, markdown
     • 高级：pdf, docx, rst, latex, epub

4. 参考文档问题

   • 错误："Reference document not found"
   • 解决方案：确保参考文档路径存在且可访问
   • 注意：参考文档仅适用于DOCX输出格式
   • 如何创建：pandoc -o reference.docx --print-default-data-file reference.docx

快速入门

安装

选项1：通过claude_desktop_config.json配置文件手动安装

• 在MacOS上：open ~/Library/Application\ Support/Claude/claude_desktop_config.json
• 在Windows上：%APPDATA%/Claude/claude_desktop_config.json

a) 仅用于本地开发和向此仓库贡献

"mcpServers": {
  "mcp-pandoc": {
    "command": "uv",
    "args": [
      "--directory",
      "<DIRECTORY>/mcp-pandoc",
      "run",
      "mcp-pandoc"
    ]
  }
}

b) 发布服务器配置 - 消费者应使用此配置

"mcpServers": {
  "mcp-pandoc": {
    "command": "uvx",
    "args": [
      "mcp-pandoc"
    ]
  }
}

选项2：通过Smithery自动安装发布服务器配置

运行以下bash命令，通过 Smithery 自动为Claude Desktop安装发布 mcp-pandoc pypi：

npx -y @smithery/cli install mcp-pandoc --client claude

• 如果您遇到任何问题，请直接使用上面"发布服务器配置"而不是此命令。

注意：要使用本地配置的mcp-pandoc，请按照上面"开发/未发布服务器配置"步骤操作。

开发

测试

要运行全面的测试套件并验证所有支持的双向转换，请使用以下命令：

uv run pytest tests/test_conversions.py

这确保了向后兼容性并验证了工具的核心功能。

构建和发布

为分发准备包：

1. 同步依赖项并更新锁文件：

uv sync

2. 构建包分发：

uv build

这将创建源和轮分发，保存在 dist/ 目录中。

3. 发布到PyPI：

uv publish

注意：您需要通过环境变量或命令标志设置PyPI凭证：

• 令牌：--token 或 UV_PUBLISH_TOKEN
• 或者用户名/密码：--username/UV_PUBLISH_USERNAME 和 --password/UV_PUBLISH_PASSWORD

调试

由于MCP服务器通过stdio运行，调试可能具有挑战性。为获得最佳调试体验，我们强烈建议使用 MCP Inspector。

您可以通过 npm 命令启动MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /Users/vivekvells/Desktop/code/ai/mcp-pandoc run mcp-pandoc

启动后，Inspector将显示一个URL，您可以在浏览器中访问以开始调试。

贡献

我们欢迎对mcp-pandoc的贡献！以下是您可以参与的方式：

1. 报告问题：发现错误或有功能请求？在我们的 GitHub Issues 页面打开问题。
2. 提交拉取请求：通过创建拉取请求来改进代码库或添加功能。