Deno MCP Pandoc

Deno MCP-Pandoc

一个Deno/TypeScript的实现 MCP（最小成本路径/最小代价路径） 文档服务器 使用 Pandoc 进行转换。

归属（或“注明来源”）这个项目是一个受启发而做的Deno/TypeScript移植版本 MCP-Pandoc 由 @vivekVells（注：这是一个用户名或特定标识，直接翻译为中文并无实际意义，因此保持原样。在中文语境中，这类标识通常直接沿用原样，不进行翻译。）原始的Python实现提供了 该项目的基础与设计。

特点/功能

• 双传输模式Stdio（用于Claude桌面版）和HTTP/SSE（用于Web应用程序）
• 独立二进制文件编译成一个单独的可执行文件，使用 deno compile
• 10种格式支持Markdown、HTML、txt（纯文本）、ipynb、ODT、PDF、docx、rst、LaTeX、epub
• 双向转换在所有格式之间进行转换（输入格式不包括PDF）
• 高级功能：

- 通过参考文档实现DOCX样式 - 用于配置的YAML默认文件 - Pandoc过滤器支持 - 基于内容或文件的转换 - 自动过滤路径解析

先决条件

• Deno 版本1.40或更高版本
• Pandoc（注：Pandoc是一个文档转换工具，用于将Markdown等格式的文档转换为其他格式，如HTML、LaTeX等，此处直接保留原英文名称，因其在中文语境下通常不翻译） 已安装并添加到系统路径(PATH)中
• 对于PDF输出：XeLaTeX（包含在 TeX Live）

安装

使用 Deno

# Clone the repository
git clone https://github.com/yourusername/deno-mcp-pandoc.git
cd deno-mcp-pandoc

# Run directly with Deno
deno task start              # Stdio mode (default)
deno task start:http         # HTTP mode

# Or install globally
deno install --allow-all -n mcp-pandoc src/main.ts

编译为独立二进制文件

# Compile to a single executable
deno task compile

# The binary will be created at bin/mcp-pandoc
./bin/mcp-pandoc              # Stdio mode (default)
./bin/mcp-pandoc --http       # HTTP mode

# Optionally, copy to a directory in your PATH
cp bin/mcp-pandoc /usr/local/bin/

验证Pandoc的安装

pandoc --version

如果未找到 Pandoc，请进行安装：

• macOS（发音为 /ˈmækɒs/，中文常音译为“麦奥斯”或直接使用原名）: brew install pandoc
• Ubuntu/Debian（这两个都是Linux发行版的名称，可直接翻译为中文，无需额外解释）： sudo apt install pandoc
• Windows从……下载 pandoc.org（注：这是一个网站域名，直接翻译为中文并无实际意义，但按照要求指出其为“pandoc的官方网站”或保持原样作为专有名词即可，此处为保持简洁，直接给出原样）

使用方法

该服务器通过一个统一入口支持两种传输模式：

1. 标准I/O传输（用于Claude桌面版）

在您的Claude桌面配置文件中添加：

macOS（苹果电脑操作系统）: ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

使用Deno：

{
  "mcpServers": {
    "pandoc": {
      "command": "deno",
      "args": [
        "run",
        "--allow-all",
        "/absolute/path/to/deno-mcp-pandoc/src/main.ts"
      ]
    }
  }
}

或者使用编译后的二进制文件：

{
  "mcpServers": {
    "pandoc": {
      "command": "/absolute/path/to/bin/mcp-pandoc"
    }
  }
}

更改后重启 Claude Desktop。

2. HTTP传输（用于Web应用程序）

启动HTTP服务器：

# Using Deno tasks
deno task start:http

# Or run directly
deno run --allow-all src/main.ts --http

# Or using the compiled binary
./bin/mcp-pandoc --http

# Specify custom port and host via environment variables
PORT=8080 HOST=0.0.0.0 deno task start:http

服务器提供以下端点：

• 健康检查: GET http://localhost:3000/health
• SSE 终点（或：SSE 端点）： GET http://localhost:3000/sse (MCP的服务器发送事件)
• MCP 终端节点： GET http://localhost:3000/mcp (MCP消息处理)

配置您的Web应用程序以连接到用于MCP通信的SSE终端。

MCP 工具：转换内容

该服务器提供了一个强大的单一体工具用于文档转换。

参数

• 内容 （字符串，可选）：要转换的内容（使用此内容或输入文件）
• 输入文件 (字符串，可选)：输入文件的路径（使用此路径或文件内容）
• 输入格式 (字符串，默认值: "markdown")：输入格式
• 输出格式 (字符串，默认："markdown")：输出格式
• 输出文件 （字符串，可选）：输出文件的路径（对于PDF、DOCX、EPUB、ODT格式为必填）
• 参考文档 (字符串，可选)：用于样式设置的参考文档路径
• 默认文件 （字符串，可选）：指向 Pandoc 默认设置 YAML 文件的路径
• 过滤器 （数组，可选）：Pandoc 过滤器名称或路径的列表

支持的格式

示例

将Markdown转换为HTML

User: "Convert this markdown to HTML: # Hello World\n\nThis is **bold** text."

Claude uses the convert-contents tool:
{
  "contents": "# Hello World\n\nThis is **bold** text.",
  "input_format": "markdown",
  "output_format": "html"
}

将文件转换为PDF

User: "Convert my document.md to a PDF"

Claude uses the convert-contents tool:
{
  "input_file": "document.md",
  "output_file": "document.pdf",
  "input_format": "markdown",
  "output_format": "pdf"
}

使用默认文件

User: "Convert my essay to PDF using academic formatting"

Claude uses the convert-contents tool:
{
  "input_file": "essay.md",
  "output_file": "essay.pdf",
  "input_format": "markdown",
  "output_format": "pdf",
  "defaults_file": "examples/defaults/academic-pdf.yaml"
}

使用参考文档为DOCX设置样式

User: "Convert this to DOCX using my company template"

Claude uses the convert-contents tool:
{
  "input_file": "report.md",
  "output_file": "report.docx",
  "input_format": "markdown",
  "output_format": "docx",
  "reference_doc": "templates/company-template.docx"
}

YAML 默认文件

默认配置文件允许您以YAML格式配置Pandoc选项。

示例（examples/defaults/academic-pdf.yaml):

pdf-engine: xelatex
variables:
  geometry: margin=1in
  fontsize: 12pt
toc: true
number-sections: true

见 examples/defaults/ 目录中包含更多示例。

Pandoc 过滤器

过滤器允许您转换文档的抽象语法树（AST）。将过滤器置于 ~/.pandoc/filters/ 或指定 完整路径。

{
  "contents": "...",
  "filters": ["my-filter.lua", "/path/to/another-filter.py"]
}

服务器按以下顺序自动解析过滤器路径：

1. 绝对路径
2. 相对于当前工作目录
3. 相对于默认文件目录
4. ~/.pandoc/filters/

发展

运行服务器

# Stdio server (for Claude Desktop)
deno task start

# HTTP server (for web applications)
deno task start:http

# Development mode with file watching
deno task dev         # stdio server
deno task dev:http    # HTTP server

建筑；大楼

# Compile to standalone binary
deno task compile

# The binary will be created at bin/mcp-pandoc
# Run it with:
./bin/mcp-pandoc              # stdio mode
./bin/mcp-pandoc --http       # HTTP mode

运行测试

# Run all tests
deno task test

# Run specific test file
deno task test tests/unit/converter_test.ts

# Run with coverage
deno task coverage

代码质量

# Format code
deno task fmt

# Lint code
deno task lint

# Type check
deno task check

项目结构

deno-mcp-pandoc/
├── src/
│   ├── main.ts          # Unified entry point with CLI arg parsing
│   ├── mcp.ts           # Shared MCP server creation logic
│   ├── converter.ts     # Pandoc conversion logic
│   ├── validation.ts    # Input validation
│   ├── filters.ts       # Filter path resolution
│   ├── defaults.ts      # YAML defaults handling
│   └── errors.ts        # Custom error types
├── bin/
│   └── mcp-pandoc       # Compiled binary (created by deno task compile)
├── tests/
│   ├── unit/           # Unit tests
│   ├── integration/    # Integration tests (if any)
│   └── fixtures/       # Test fixtures
├── examples/
│   └── defaults/       # Example YAML configurations
├── deno.json           # Deno configuration
└── README.md           # This file

故障排除

未找到 Pandoc

错误： PandocNotFoundError: Pandoc not found

解决方案安装 Pandoc 并确保它已添加到你的 PATH 中，或者设置 PANDOC_PATH 环境 变量：

export PANDOC_PATH=/path/to/pandoc

PDF转换失败

错误： xelatex not found

解决方案安装一个LaTeX发行版（如TeX Live、MiKTeX等）：

• macOS: brew install --cask mactex
• Ubuntu/Debian（这两个都是Linux发行版）： sudo apt install texlive-xetex
• Windows安装 MiKTeX

未找到过滤器

错误： FilterNotFoundError: Filter "my-filter.lua" not found

解决方案：

1. 验证过滤文件是否存在
2. 检查文件权限（在类Unix系统上应可执行）
3. 使用过滤器的完整路径
4. 将过滤器放置在 ~/.pandoc/filters/

无效的默认设置文件

错误： DefaultsFileError: Failed to parse YAML

解决方案：

1. 使用YAML验证器验证YAML语法
2. 确保文件包含一个YAML对象（而非列表或基本类型）
3. 不要同时指定两者 from 和 to 在默认文件中（请使用参数代替）

贡献；助力

欢迎投稿！请确保：

1. 所有测试均通过： deno task test
2. 代码已格式化： deno task fmt
3. 代码通过了语法检查： deno task lint
4. 类型检查成功： deno task check
5. 测试覆盖率保持在90%以上

发布流程

对于负责创建发布版本的维护人员，请参阅 \RELEASING.md\ 翻译为中文是：“发布指南.md” 或 “发行说明.md”（具体翻译可能根据上下文有所调整，但基本意思是指一个关于发布或版本说明的Markdown文件） 关于详细的说明/指导，请参阅 使用自动化发布流程。

许可证

MIT 许可证 - 详见 LICENSE 文件

致谢

• 建立在……之上 Pandoc（潘多克） 由约翰·麦克法兰撰写
• 使用 模型上下文协议 由Anthropic开发
• 受启发并移植自 mcp-pandoc（可译为“MCP-Pandoc”，其中MCP可能代表某个特定项目或组织的缩写，Pandoc是一个文档转换工具） 由

@vivekVells（注：这可能是一个用户名或特定标识，直接翻译为中文保持原样）