AI导哈

HTML转PDF服务

一个基于Puppeteer的快速可靠API服务，用于将HTML内容和网页转换为PDF文档，支持多种自定义选项和MCP集成。

  • by iamsalt
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 iamsalt/mcp-html2pdf

使用说明

HTML到PDF API服务器

一个快速可靠的API服务器，用于使用Puppeteer将HTML内容和网页转换为PDF文档。

特性

  • 🌐 HTML转PDF：将HTML字符串转换为PDF文档
  • 🔗 PDF的URL：将网页转换为PDF文档
  • 🤖 MCP集成：通过模型上下文协议实现Claude桌面兼容性
  • ⚙️ 可配置的：基于环境的配置
  • 💾 文件输出：可选文件保存，可自定义命名
  • 📊 灵活的选项：可定制的PDF格式、边距、方向
  • 🚀 演出：增强的浏览器池和超时管理
  • 🔒 安全：输入验证和可配置限制
  • ✅ CI/CD：使用GitHub Actions进行自动化测试
  • 📊 覆盖：测试覆盖率报告和质量门

快速开始

先决条件

  • Node.js 18+
  • Chrome/Chromium浏览器

安装

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

# Install dependencies
pnpm install

# Install Chrome for Puppeteer
npx puppeteer browsers install chrome

# Start the API server
pnpm start

# Or start as MCP server for Claude Desktop
pnpm mcp

API服务器将于启动 http://localhost:3000 默认情况下。

API使用

将HTML转换为PDF

curl -X POST http://localhost:3000/html2pdf \
  -H "Content-Type: application/json" \
  -d '{"html":"<h1>Hello World</h1>"}' \
  --output document.pdf

将URL转换为PDF

curl -X POST http://localhost:3000/html2pdf \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' \
  --output webpage.pdf

高级选项

curl -X POST http://localhost:3000/html2pdf \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "format": "A4",
      "orientation": "landscape",
      "margins": {"top": "1in", "bottom": "1in"},
      "printBackground": true,
      "filename": "custom.pdf",
      "saveToFile": true
    }
  }' \
  --output custom.pdf

MCP（模型上下文协议）集成

此服务器可以用作Claude Desktop的MCP服务器，允许您通过自然语言命令直接将HTML和URL转换为PDF。

Claude桌面设置

  1. 启动MCP服务器:

    pnpm mcp

  2. 配置Claude桌面: 添加到您的Claude Desktop配置文件中：

    macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json

    {
  "mcpServers": {
    "html2pdf": {
      "command": "node",
      "args": ["-r", "tsx/esm", "/absolute/path/to/mcp-html2pdf/src/mcp-server.ts"],
      "cwd": "/absolute/path/to/mcp-html2pdf"
    }
  }
}

  3. pnpm的替代方案:

    {
  "mcpServers": {
    "html2pdf": {
      "command": "pnpm",
      "args": ["mcp"],
      "cwd": "/absolute/path/to/mcp-html2pdf"
    }
  }
}

MCP使用示例

配置后，您可以在Claude Desktop中使用自然语言：

  • “将此HTML转换为PDF： <html><body><h1>Hello</h1></body></html>"
  • “转换https://example.com转换为PDF并将其另存为example.PDF“
  • “从该URL生成横向PDF：https://github.com"

可用的MCP工具

  • convert_html_to.pdf：将HTML内容转换为PDF
  • convert_url_to_pdf：将网页URL转换为PDF

这两个工具都支持与REST API相同的所有选项。

有关MCP设置的详细说明，请参阅 MCP_SETUP.md.

配置

通过环境变量进行配置：

# Server settings
PORT=3000
MAX_REQUEST_SIZE=50mb

# PDF settings
PDF_FORMAT=A4                    # A4, Letter, Legal
PDF_PRINT_BACKGROUND=true
PDF_MARGIN_TOP=0.5in
PDF_MARGIN_RIGHT=0.5in
PDF_MARGIN_BOTTOM=0.5in
PDF_MARGIN_LEFT=0.5in

# File output
FILE_OUTPUT_ENABLED=true
FILE_OUTPUT_DIR=./output
FILE_OUTPUT_TEMPLATE={domain}-{timestamp}.pdf

# Timeouts
REQUEST_TIMEOUT=30000            # 30 seconds
PAGE_LOAD_TIMEOUT=20000          # 20 seconds

# Browser settings
BROWSER_HEADLESS=true
CHROME_EXECUTABLE_PATH=/path/to/chrome

请求选项

选项 类型 默认值 描述
format 字符串 A4 纸张格式（A4、信纸、法律版）
orientation 字符串 portrait 页面方向
printBackground 布尔值 true 打印背景图形
scale 编号 1.0 比例因子
margins 对象 0.5in 页边距
waitFor.networkIdle 字符串 networkidle0 网络空闲状态
waitFor.timeout 编号 20000 页面加载超时
waitFor.selector string - 等待特定元素
filename 字符串 generated.pdf 输出文件名
saveToFile 布尔值 false 保存到服务器文件系统

Docker部署

FROM node:18-alpine

# Install Chrome dependencies
RUN apk add --no-cache \
    chromium \
    nss \
    freetype \
    harfbuzz

ENV CHROME_EXECUTABLE_PATH=/usr/bin/chromium-browser
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true

WORKDIR /app
COPY package*.json ./
RUN pnpm install --production

COPY . .
RUN pnpm build

EXPOSE 3000
CMD ["node", "dist/server.js"]

# Build and run
docker build -t html2pdf .
docker run -p 3000:3000 html2pdf

健康检查

curl http://localhost:3000/health

发展

设置

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

# Install dependencies
pnpm install

# Install Chrome for Puppeteer
npx puppeteer browsers install chrome

# Run in development mode
pnpm dev

# Run tests
pnpm test

# Build for production
pnpm build

脚本

  • pnpm start -启动生产API服务器
  • pnpm dev -开始开发API服务器
  • pnpm mcp -启动Claude Desktop的MCP服务器
  • pnpm test -运行测试
  • pnpm test:watch -在监视模式下运行测试
  • pnpm test:coverage -使用覆盖率报告运行测试
  • pnpm build -为生产而建
  • pnpm lint -运行ESLint
  • pnpm format -使用Prettier格式化代码

CI/CD

本项目使用GitHub Actions进行持续集成：

自动化测试

  • Node.js 20.x测试：针对Node.js 20.x兼容性进行了优化
  • 依赖管理：使用pnpm和锁文件验证
  • Chrome安装：Puppeteer测试的自动Chrome设置
  • Lint&Build：代码质量和TypeScript编译检查
  • MCP服务器测试：验证MCP服务器启动

覆盖范围报告

  • 测试覆盖率：Vitest与v8覆盖提供商合作
  • 覆盖阈值：分支、函数、行和语句的最小覆盖率为70%
  • Codecov集成：自动上传覆盖报告

质量门

  • 所有测试必须通过
  • 过梁必须通过（零错误策略）
  • 构建必须成功
  • 必须满足覆盖阈值

CI运行于：

  • 推到 main 和 develop 分支
  • 将请求拉到 main 分支

安全注意事项

在生产环境中部署时：

  • 使用反向代理（nginx、Apache）进行SSL终止
  • 配置防火墙规则以限制访问
  • 设置适当的资源限制
  • 监控滥用情况并实施限速
  • 考虑在容器化环境中运行

故障排除

未找到Chrome

npx puppeteer browsers install chrome

内存问题

  • 减少并发请求： MAX_CONCURRENT_REQUESTS=5
  • 如果页面加载缓慢，请增加超时值
  • 监控内存使用情况并定期重新启动服务
  • 浏览器池自动管理浏览器重用以提高效率

权限错误

  • 确保输出目录可写
  • 检查Chrome的可执行权限
  • 使用适当的用户权限运行

MCP集成问题

  • 确保Claude Desktop配置中的绝对路径
  • 配置更改后重新启动Claude Desktop
  • 检查MCP服务器日志： pnpm mcp （应显示“HTML转PDF MCP服务器在stdio上运行”）
  • 验证Chrome是否已安装： npx puppeteer browsers install chrome

CI/CD问题

  • 构建失败：检查TypeScript错误和lint问题
  • 测试失败：确保Chrome在CI环境中可用
  • 覆盖失败：在所有指标上保持至少70%的覆盖率

贡献

欢迎投稿！请按照以下步骤操作：

  1. 复刻仓库
  2. 创建要素分支： git checkout -b feature-name
  3. 进行更改并添加测试
  4. 确保所有检查均已通过：
    pnpm test           # Run tests
pnpm test:coverage  # Check coverage
pnpm lint           # Run linter
pnpm build          # Verify build
  5. 格式代码： pnpm format
  6. 以明确的信息承诺： git commit -m "feat: add new feature"
  7. 推送到分支： git push origin feature-name
  8. 提交拉取请求

CI将自动运行所有测试、linting和覆盖率检查。

提交消息格式

  • feat: 对于新功能
  • fix: 用于修复错误
  • docs: 文档更改
  • test: 用于测试更改

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

支持

相关 MCP