mcp-潘多克

Name: mcp-潘多克
Author: vivekVells

作者：vivekVells454 星标更新：2025-09-16

安装使用来源：spider==github.com

项目介绍

<br />

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

正式包含在模型上下文协议服务器开源项目中。🎉

概览

这是一个使用 pandoc 进行文档格式转换的模型上下文协议服务器。此服务器提供了工具，可以在不同的文档格式之间转换内容，同时保留格式和结构。

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

致谢：此项目使用了 Pandoc Python 包进行文档转换，构成了该项目的基础。

📋 快速参考

新用户？ 查看 📖 CHEATSHEET.md 获取：

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

非常适合快速查找和快速上手！

示例

🎥 在 YouTube 上观看

更多内容即将推出...

工具

convert-contents
- 在支持的格式之间转换内容
- 输入参数：
  - contents（字符串）：要转换的源内容（如果未提供 input_file，则需要）
  - input_file（字符串）：输入文件的完整路径（如果未提供 contents，则需要）
  - input_format（字符串）：内容的源格式（默认为 markdown）
  - output_format（字符串）：目标格式（默认为 markdown）
  - output_file（字符串）：输出文件的完整路径（对于 pdf、docx、rst、latex、epub 格式是必需的）
  - reference_doc（字符串）：用于样式的参考文档路径（仅支持 docx 输出格式）
  - defaults_file（字符串）：包含转换选项的 Pandoc 默认文件路径（YAML）
  - filters（数组）：在转换过程中应用的 Pandoc 过滤器路径列表
- 支持的输入/输出格式：
  - markdown
  - html
  - pdf
  - docx
  - rst
  - latex
  - epub
  - txt
  - ipynb
  - odt
- 注意：对于高级格式（pdf、docx、rst、latex、epub），需要提供 output_file 路径

🔧 高级特性

默认文件（YAML 配置）

使用默认文件创建可重复使用的转换模板，以保持一致的格式：

# academic-paper.yaml
from: markdown
to: pdf
number-sections: true
toc: true
metadata:
  title: "学术论文"
  author: "研究团队"

示例用法："将 paper.md 转换为 PDF，使用 defaults academic-paper.yaml，并保存为 paper.pdf"

Pandoc 过滤器

应用自定义过滤器以增强处理：

示例用法："将 docs.md 转换为 HTML，使用过滤器 ['/path/to/mermaid-filter.py'] 并保存为 docs.html"

💡 对于全面的示例和工作流程，请参阅 CHEATSHEET.md

📊 支持的格式及转换

双向转换矩阵

从\到	MD	HTML	TXT	DOCX	PDF	RST	LaTeX	EPUB	IPYNB	ODT
Markdown	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
HTML	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
TXT	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
DOCX	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
RST	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
LaTeX	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
EPUB	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
IPYNB	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
ODT	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅

关于 PDF 支持的一点说明

此工具使用 pandoc 进行转换，允许从上述格式生成 PDF 文件。然而，从 PDF 转换为其他格式是不被支持的。因此，PDF 应被视为一个只输出的格式。

格式类别

类别	格式	要求
基础	MD, HTML, TXT, IPYNB, ODT	无
高级	DOCX, PDF, RST, LaTeX, EPUB	必须指定 `output_file` 路径
样式化	DOCX 带参考文档	自定义模板支持 ⭐

格式要求

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

注意：对于高级格式：

完整文件路径包括文件名和扩展名是必需的
PDF 转换需要安装 TeX Live（参见关键要求部分 -> 对于 macOS：brew install texlive）
当没有指定输出路径时：
- 基础格式：在聊天中显示转换后的内容
- 高级格式：可能保存在系统临时目录（Unix 系统上的 /tmp/）

使用与配置

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

要使用已发布的版本

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

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

⚠️ 重要注意事项

关键要求

Pandoc 安装

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

安装命令：

# macOS
brew install pandoc

# Ubuntu/Debian
sudo apt-get install pandoc

# Windows
# 从 https://pandoc.org/installing.html 下载安装程序

验证：pandoc --version

UV 包安装

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

安装命令：

# macOS
brew install uv

# Windows/Linux
pip install uv

验证：uvx --version

PDF 转换前提条件：仅在需要转换并保存 PDF 时需要

在尝试 PDF 转换之前必须安装 TeX Live

安装命令：

# Ubuntu/Debian
sudo apt-get install texlive-xetex

# macOS
brew install texlive

# Windows
# 从 https://miktex.org/ 或 https://tug.org/texlive/ 安装 MiKTeX 或 TeX Live

文件路径要求

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

示例

✅ 正确用法：

# 将内容转换为 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"

常见问题及解决方案

PDF 转换失败
- 错误："xelatex 未找到"
- 解决方案：先安装 TeX Live（参见安装命令）
文件转换失败
- 错误："无效文件路径"
- 解决方案：提供完整的路径，包括文件名和扩展名
- 示例：/path/to/document.pdf 而不是仅仅 /path/to/
格式转换失败
- 错误："不支持的格式"
- 解决方案：仅使用支持的格式：
  - 基础：txt, html, markdown
  - 高级：pdf, docx, rst, latex, epub
参考文档问题
- 错误："参考文档未找到"
- 解决方案：确保参考文档路径存在且可访问
- 注意：参考文档仅适用于 DOCX 输出格式
- 如何创建：pandoc -o reference.docx --print-default-data-file reference.docx

快速开始

手动安装通过 claude_desktop_config.json 配置文件

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

a) 仅用于本地开发及对此仓库的贡献

<details> <summary>开发/未发布服务器配置</summary>

ℹ️ 用你的本地克隆项目路径替换 <DIRECTORY>

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

</details>

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

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

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

开发

测试

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

uv run pytest tests/test_conversions.py

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

构建和发布

要准备打包进行分发：

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

uv sync

构建包分布：

uv build

这将在 dist/ 目录中创建源代码和轮子分布。

发布到 PyPI：

uv publish

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

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

调试

由于 MCP 服务器通过标准 I/O 运行，调试可能会很困难。为了获得最佳的调试体验，我们强烈推荐使用 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 的增强贡献！以下是参与的方式：

报告问题：发现了一个 bug 或有功能请求？在我们的 GitHub Issues 页面上