星战科技xingzhan.cloud
返回市场
文件转换器MCP

文件转换器MCP

作者：MaitreyaM6 星标更新：2025-04-06
安装使用来源：spider==github.com

项目介绍

Pandoc MCP 服务器

License: MIT <!-- 可选：添加许可证徽章 --> smithery 徽章

一个基于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): 表明成功的信息（例如，“成功转换文档到'/data/my_output.pdf'”）或错误信息（例如，“错误：未找到输入文件...”，“转换过程中出错：Pandoc已终止...”）。

安装和运行

你可以选择本地运行此服务器（需要手动安装依赖项）或使用提供的Docker配置（推荐用于方便使用和部署）。

通过Smithery安装

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

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）连接到http://127.0.0.1:8000/sse，传输方式为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

代理: 思考中...
[代理调用convert_document工具，输入='/data/report.md'，输出='/data/report.pdf'，目标='pdf']
代理: 成功转换文档到'/data/report.pdf'
[机器人可能会尝试从本地项目目录上传report.pdf]

文件

  • pandoc_mcp_server.py: MCP服务器的主要Python脚本。
  • Dockerfile: 构建Docker容器镜像的指令。
  • requirements.txt: Docker容器内（或本地虚拟环境）所需的Python依赖项。
  • .gitignore: 为Git指定有意忽略的文件。
  • README.md: 本文档。

贡献

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