mcp-pandoc-ts: 文档转换 MCP 服务器 (TypeScript/宿主机服务版本)

⚠️ 状态：预览版 ⚠️

这是一个初始版本。虽然核心功能（Markdown、HTML、PDF、DOCX、TXT 转换）已经过测试，但其他格式如 LaTeX 和 EPUB 目前未经测试。请报告任何问题。

本项目通过模型上下文协议 (MCP) 提供文档转换功能。它使用双组件架构：

1. mcp-pandoc-ts (本目录): 一个基于 TypeScript 的 MCP 服务器，设计为在容器内运行（例如，在 LibreChat 中）。它通过 stdio 接收 MCP 请求。
2. pandoc-host-service (单独目录): 一个 Python Flask 服务，设计为在宿主机上运行。它监听来自容器服务的 HTTP 请求，并执行宿主机的 pandoc 命令。

这种架构允许利用宿主机上的 pandoc 安装，而无需在容器内安装它。

前提条件

对于宿主机 (运行 pandoc-host-service):

1. Python: 推荐 3.7+ 版本。
2. pip: Python 包安装器。
3. Pandoc: 核心转换工具。必须安装并在系统的 PATH 中可访问。请参阅 pandoc 安装说明。
4. TeX Live / MiKTeX (用于 PDF 输出): 仅当您需要通过宿主机服务将文档转换为 PDF 格式时才需要。
   • Ubuntu/Debian: sudo apt-get install texlive-xetex
   • macOS: brew install texlive
   • Windows: 安装 MiKTeX 或 TeX Live。

对于容器环境 (运行 mcp-pandoc-ts):

1. Node.js: 推荐 16 或更高版本。
2. npm 或 yarn: Node.js 的包管理器。
3. 与运行 pandoc-host-service 的宿主机之间的网络连接。
4. 宿主机服务 URL 配置 (至关重要): 此服务器必须知道正在运行的 pandoc-host-service 的 URL。这通过 PANDOC_HOST_URL 环境变量配置。
   • 部署 (例如，LibreChat, Docker Compose): 直接在您的部署配置中设置 PANDOC_HOST_URL 环境变量。 这是部署环境的推荐和最可靠的方法。有关示例，请参阅“MCP 集成”部分。此方法会覆盖任何 .env 文件。
   • 本地开发/测试: 仅为了本地开发期间的方便，您可以在项目根目录中创建一个 .env 文件（将 .env.example 复制到 .env）并在其中设置 PANDOC_HOST_URL。如果未设置外部环境变量，服务器将加载此值。
   • 值示例:
     • Docker Desktop (Mac/Win): http://host.docker.internal:5001
     • Linux (典型的桥接网络): http://172.17.0.1:5001 (验证 Docker 网络上的主机 IP)
   • 未能配置此变量（无论是通过外部方式还是通过 .env 进行本地测试）将阻止服务器联系宿主机服务并导致错误。

设置和运行

步骤 1: 设置并运行宿主机服务 (pandoc-host-service)

1. 导航到您的宿主机上的 pandoc-host-service 目录（与 mcp-pandoc-ts 同级）。
2. (推荐) 创建并激活一个 Python 虚拟环境:

   python -m venv venv
   source venv/bin/activate  # 在 Windows 上使用 `venv\Scripts\activate`
   

3. 安装依赖项:

   pip install -r requirements.txt
   

4. 使用 Waitress 运行宿主机服务:
   • 在您的宿主机上打开一个新的、单独的终端窗口。
   • 确保您仍然在 pandoc-host-service 目录中，并且您的虚拟环境（如果已创建）已激活。
   • 使运行脚本可执行（如果您尚未这样做）：chmod +x run_host_service.sh
   • 执行运行脚本:

     ./run_host_service.sh
     

   • 您应该看到 Waitress 的输出，指示它正在服务应用程序（例如，Serving on http://0.0.0.0:5001）。Flask 开发服务器警告应该不出现。
   • 重要提示: 此终端窗口必须保持打开状态，宿主机服务才能继续运行并处理来自 mcp-pandoc-ts 容器服务的请求。如果您关闭此终端，宿主机服务将停止。
   • (可选 - 高级): 对于更永久的设置，即使在关闭终端后服务也能运行，请考虑使用 nohup (nohup python app.py &)、screen 或 tmux 等工具，或将其设置为系统服务。

步骤 2: 设置并运行容器服务 (mcp-pandoc-ts)

1. 导航到 mcp-pandoc-ts 目录（本目录）。
2. 安装依赖项:

   npm install
   # 或
   yarn install
   

3. 编译 TypeScript 代码:

   npm run build
   # 或
   yarn build
   

   这会创建 dist/server.js 文件。
4. 配置宿主机服务 URL: 确保使用“前提条件”部分中描述的方法之一配置 PANDOC_HOST_URL（要么创建并编辑 .env 文件，要么在外部设置环境变量）。
5. 运行 MCP 服务器（例如，通过 LibreChat 配置或直接运行）:

   # 服务器将从 .env 或外部环境加载 PANDOC_HOST_URL
   npm start
   # 或
   yarn start
   # 或直接运行
   node dist/server.js
   

   此服务器将监听 stdin 上的 MCP 请求，并使用配置的 PANDOC_HOST_URL 将转换任务转发到宿主机服务。如果未配置该变量（通过 .env 或外部环境），服务器将记录错误并无法处理请求。

MCP 集成 (LibreChat 示例)

配置您的 MCP 客户端（LibreChat 或类似客户端）以使用 Node.js 启动 mcp-pandoc-ts 服务器。配置连接的推荐和最可靠的方法是直接在此服务器的 MCP 客户端配置中设置 PANDOC_HOST_URL 环境变量。 这确保了在部署环境中正确应用该设置。

示例配置片段（根据需要调整路径）:

{
  "mcpServers": {
    "mcp-pandoc-ts": {
      "command": "node",
      "args": ["/path/to/your/mcp-pandoc-ts/dist/server.js"],
      "env": {
        "PANDOC_HOST_URL": "http://host.docker.internal:5001" // <-- 将此设置为适合您环境的正确 URL
      }
    }
  }
}

工具

convert-contents

• 描述: 通过向宿主机 Pandoc 服务发送请求来转换不同格式的内容。
• 🚨 关键要求:
  • pandoc-host-service 必须在宿主机上运行。
  • 启动此服务器时，必须正确配置 PANDOC_HOST_URL（通过 .env 文件或外部环境变量），指向正在运行的 pandoc-host-service。
  • 宿主机需要 Pandoc（以及用于 PDF 的 TeX Live）。
• 当前限制:
  • 仅支持 contents 输入。由于容器和主机之间的路径复杂性，目前不处理 input_file。
  • 所有输出格式都支持 output_file。对于二进制格式（如 pdf、docx），宿主机服务发送以 base64 编码的文件内容，此容器服务对其进行解码并将其保存到指定的路径。对于文本格式，保存纯文本。
• 支持的格式 (通过主机): markdown, html, pdf, docx, rst, latex (未经测试), epub (未经测试), txt
• 输入模式:
  • contents (string): 要转换的内容 (必需)。
  • input_file (string): 当前不支持。
  • input_format (string, optional, default: markdown): 源格式。
  • output_format (string, optional, default: markdown): 目标格式。
  • output_file (string, optional): 容器内保存输出的绝对路径。仅适用于基本格式（txt、html、markdown pdf docx 等）。

开发

• 容器服务: 源代码位于 mcp-pandoc-ts/src 中。运行 npm run build 进行编译。
• 宿主机服务: 源代码位于 pandoc-host-service 中。运行 python app.py 启动。