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":"
Hello World
"}' \
  --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

1. 配置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"
       }
     }
   }

1. pnpm的替代方案:

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

MCP使用示例

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

• “将此HTML转换为PDF： `

Hello `"

• “转换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

请求选项

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

1. 格式代码： pnpm format
2. 以明确的信息承诺： git commit -m "feat: add new feature"
3. 推送到分支： git push origin feature-name
4. 提交拉取请求

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

提交消息格式

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

许可证

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

支持

• 🐛 报告错误
• 💡 请求功能
• 📖 文档