Pandoc MCP 服务器

<!-- 可选：添加许可徽章 -->

一个基于 Python 的 MCP (模型上下文协议) 服务器，通过 Pandoc 提供强大的文档转换功能。该服务器允许 AI 代理（例如通过 LangChain/LangGraph 的 Claude）请求在各种格式之间进行文件转换，例如 Markdown、DOCX、HTML、PDF、EPUB 等等。

本项目使用：

• FastMCP: 一个用于轻松创建 MCP 服务器的 Python 库。
• pypandoc: Pandoc 命令行工具的 Python 封装器。
• Pandoc: 通用文档转换器。
• (可选) Docker: 用于容器化部署，捆绑所有依赖项（Python、Pandoc、LaTeX）。

特性

• 公开一个 MCP 工具：convert_document。
• 支持 Pandoc 处理的各种输入和输出格式。
• 允许指定输入格式（如果自动检测失败）和输出格式。
• 支持将额外的命令行参数传递给 Pandoc 以进行高级控制（例如，目录、PDF 边距、独立文件）。
• 包含 Docker 配置 (Dockerfile)，用于创建包含 Pandoc 和必要的 LaTeX 组件（用于 PDF 生成）的自包含服务器环境。
• 专为与 MCP 客户端集成而设计，特别是 LangChain/LangGraph 代理。

公开的 MCP 工具

convert_document

使用 Pandoc 将文档从一种格式转换为另一种格式。

参数：

• input_file_path (str, 必需): 服务器可访问的输入文档文件的路径。 如果在 Docker 中运行并挂载卷，则这应该是容器内部的路径（例如，/data/my_doc.docx）。
• output_file_path (str, 必需): 服务器可访问的转换后的输出文件应保存的路径。 如果在 Docker 中运行，则这应该是容器内部的路径（例如，/data/my_output.pdf）。 如果目录在服务器可访问的文件系统中不存在，则将创建该目录。
• to_format (str, 必需): 转换的目标格式（例如，'markdown'、'docx'、'pdf'、'html'、'rst'、'epub'）。 有关完整列表，请参见 Pandoc 文档 (--list-output-formats)。
• from_format (str, 可选): 输入文件的格式。 如果为 None，则 pandoc 将尝试从文件扩展名中猜测。 如果扩展名不明确或缺失，请指定（例如，'md'、'docx'、'html'）。 默认为 None。
• extra_args (List[str], 可选): 要直接传递给 pandoc 的其他命令行参数的列表（例如，['--toc']、['-V', 'geometry:margin=1.5cm']、['--standalone']）。 默认为 None。

返回值：

• (str): 指示成功的消息（例如，“Successfully converted document to '/data/my_output.pdf'”）或错误消息（例如，“Error: Input file not found...”、“Error during conversion: Pandoc died...”）。

设置和运行

您可以本地运行此服务器（需要手动安装依赖项），也可以使用提供的 Docker 配置（建议使用，以便于使用和部署）。

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 Pandoc 文档转换器：

npx -y @smithery/cli install @MaitreyaM/file-converter-mcp --client claude

选项 1：使用 Docker 运行（推荐）

此方法将 Python、Pandoc、LaTeX 和所需的库捆绑到一个容器中。 您只需要在本地安装 Docker Desktop。

1. 安装 Docker： 下载并安装适用于您操作系统的 Docker Desktop。 启动 Docker Desktop。
2. 克隆存储库： 获取项目文件：

   git clone https://github.com/your-username/pandoc-mcp-server.git # 替换为您的存储库 URL
   cd pandoc-mcp-server
   

3. 构建 Docker 镜像： 此命令使用 Dockerfile 构建镜像。 它在镜像内部安装 Pandoc、一个功能强大的 TeX Live 发行版（用于 PDF 支持）和 Python 依赖项。 首次执行此步骤可能需要几分钟。

   docker build -t pandoc-converter-server .
   

4. 运行容器： 这将在容器内部启动服务器。
   • 选择主机上的一个目录，以便与容器共享输入/输出文件（例如，当前项目目录）。
   • 运行容器，将主机目录映射到容器内部的 /data，并将端口 8000 映射出去。 将 /path/to/your/local/project 替换为您的机器上项目目录的实际绝对路径。

   # 示例：使用当前目录 (.) 作为主机路径：
   docker run -it --rm -p 8000:8000 -v "$(pwd)":/data pandoc-converter-server
   
   # 或者使用绝对路径（替换）：
   # docker run -it --rm -p 8000:8000 -v "/path/to/your/local/project":/data pandoc-converter-server
   

   • -it：以交互方式运行（显示日志，允许 Ctrl+C）。
   • --rm：停止时删除容器。
   • -p 8000:8000：将主机上的端口 8000 映射到容器中的端口 8000。
   • -v "$(pwd)":/data：将主机上的当前工作目录挂载到容器内部的 /data。 放置在本地项目目录中的文件将显示在容器内部的 /data 中，并且服务器保存到 /data 的文件将显示在您的本地项目目录中。
   • pandoc-converter-server：您构建的镜像的名称。
5. 服务器正在运行： 您应该看到日志指示服务器已启动并在 SSE 上侦听 (http://0.0.0.0:8000)。 它已准备好接受来自您的 MCP 客户端（如 LangChain 代理）的连接。
6. 从客户端连接： 配置您的 MCP 客户端（例如，MultiServerMCPClient）以使用 transport: "sse" 连接到 http://127.0.0.1:8000/sse。
7. 使用该工具： 与您的代理/客户端交互时，请使用它们在容器内部的路径来引用文件，并以 /data/ 为前缀。 例如：convert /data/my_input.docx to pdf at /data/my_output.pdf。 由于卷映射，输出文件将显示在您的本地项目目录中。

选项 2：本地运行（手动安装依赖项）

这需要您直接在主机上安装 Python、Pandoc 和 LaTeX 发行版。

1. 安装 Python： 确保您已安装 Python >= 3.10。
2. 安装 Pandoc： 为您的操作系统安装 Pandoc 命令行工具。 按照 pandoc.org/installing.html 上的说明进行操作。 通过在新终端中运行 pandoc --version 进行验证。
3. 安装 LaTeX： 对于 PDF 生成，请安装 TeX 发行版。
   • macOS： brew install --cask mactex-no-gui（推荐通过 Homebrew）
   • Debian/Ubuntu： sudo apt-get update && sudo apt-get install texlive-latex-base texlive-fonts-recommended texlive-latex-extra texlive-fonts-extra（或者 texlive-full 用于所有内容，但体积很大）。
   • Windows： 安装 MiKTeX 或 TeX Live。 确保包含 pdflatex.exe 的 bin 目录已添加到系统的 PATH 中。
   • 通过在新终端中运行 pdflatex --version 进行验证。
4. 克隆存储库：

   git clone https://github.com/your-username/pandoc-mcp-server.git # 替换为您的存储库 URL
   cd pandoc-mcp-server
   

5. 创建虚拟环境（推荐）：

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

   (或者使用 Conda：conda create --name pandoc-env python=3.11 && conda activate pandoc-env)
6. 安装 Python 依赖项：

   pip install -r requirements.txt
   

7. 运行服务器：

   python pandoc_mcp_server.py
   

8. 服务器正在运行： 它将在 http://127.0.0.1:8000/sse 上侦听。
9. 从客户端连接： 配置您的 MCP 客户端以连接到 http://127.0.0.1:8000/sse。
10. 使用该工具： 使用它们在本地计算机上的常规路径来引用文件（例如，convert my_input.docx to pdf at my_output.pdf，假设文件位于同一目录中，或者使用绝对路径）。

示例代理交互（在 Docker 中运行服务器）

假设服务器容器正在运行并挂载了卷：

你: convert /data/report.md to pdf

代理: Thinking...
[代理使用 input='/data/report.md', output='/data/report.pdf', to='pdf' 调用 convert_document 工具]
代理: Successfully converted document to '/data/report.pdf'
[然后，机器人可能会尝试从本地项目目录上传 report.pdf]

文件

• pandoc_mcp_server.py：MCP 服务器的主要 Python 脚本。
• Dockerfile：用于构建 Docker 容器镜像的说明。
• requirements.txt：Docker 容器（或本地 venv）中需要的 Python 依赖项。
• .gitignore：指定 Git 故意不跟踪的文件。
• README.md：此文件。

贡献

欢迎贡献！ 请随时提交 Pull Request 或打开 Issue。