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

正式包含在 Model Context Protocol 服务器 开源项目中。🎉

概述

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

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

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

演示

🎥 在 YouTube 上观看

更多内容即将推出...

工具

1. convert-contents
   • 在支持的格式之间转换内容
   • 输入：
     • contents (字符串): 要转换的源内容（如果未提供输入文件，则必填）
     • input_file (字符串): 输入文件的完整路径（如果未提供内容，则必填）
     • input_format (字符串): 内容的源格式（默认为 markdown）
     • output_format (字符串): 目标格式（默认为 markdown）
     • output_file (字符串): 输出文件的完整路径（对于 pdf, docx, rst, latex, epub 格式是必需的）
   • 支持的输入/输出格式：
     • markdown
     • html
     • pdf
     • docx
     • rst
     • latex
     • epub
     • txt
   • 注意：对于高级格式（pdf, docx, rst, latex, epub），需要提供 output_file 路径

支持的格式

当前支持的格式：

基本格式（直接转换）：

• 纯文本 (.txt)
• Markdown (.md)
• HTML (.html)

高级格式（需要完整的文件路径）：

• PDF (.pdf) - 需要安装 TeX Live
• DOCX (.docx)
• RST (.rst)
• LaTeX (.tex)
• EPUB (.epub)

注意：对于高级格式：

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

使用与配置

要使用已发布的版本

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

⚠️ 重要说明

关键要求

1. 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/
     

2. 文件路径要求

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

示例

✅ 正确用法：

# Converting content to PDF
"Convert this text to PDF and save as /path/to/document.pdf"

# Converting between file formats
"Convert /path/to/input.md to PDF and save as /path/to/output.pdf"

❌ 错误用法：

# Missing filename and extension
"Save this as PDF in /documents/"

# Missing complete path
"Convert this to PDF"

# Missing extension
"Save as /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

快速开始

安装

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

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

ℹ️ 将 替换为您的本地克隆项目路径

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

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

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

运行以下 bash 命令以自动通过 Smithery 安装已发布的 mcp-pandoc pypi 用于 Claude Desktop：

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

注意: 若要使用本地配置的 mcp-pandoc，请遵循上面的“开发/未发布服务器配置”步骤。

开发

构建与发布

准备包以进行分发：

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

uv sync

1. 构建包分发：

uv build

这将在 dist/ 目录中创建源码和 wheel 分发包。

1. 发布到 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，你可以在浏览器中访问该 URL 开始调试。

---

贡献

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

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

---