PaperSprocket

PaperSprocket MCP 服务

一个 Model Context Protocol（MCP）服务，可让 MCP 客户端直接访问 PaperSprocket API。它恰好提供两个工具：

工具	描述
render_html_to_pdf(html, page?)	通过 PaperSprocket API 将 HTML 渲染为 PDF。返回 PDF，作为 application/pdf MCP 资源（base64 数据块）；如果服务可以写入文件，还会返回本地文件路径和渲染元数据（render_id、page_count、charged_cents、balance_cents）。费用记入已配置的账户。
check_balance(account_id)	查询已配置的 PaperSprocket 账户的预付余额。返回 account_id、balance_cents、currency 和 page_price_cents。

这是一个直接基于 @modelcontextprotocol/sdk 构建的精简原生 MCP 服务。没有充值工具，也没有 API 密钥管理工具——只有渲染和余额查询。

什么是 PaperSprocket？

PaperSprocket 是一款托管式 API，可将 HTML 转换为 PDF。发送 HTML，即可获得格式规范的 PDF。无需学习业务字段架构：你可以使用自己的 HTML 和 CSS 控制布局，而 PDF 处理由 PaperSprocket 负责。请参阅官方文档。

要求

• Node.js >= 20
• PaperSprocket API 密钥。服务仅从服务端配置（环境变量或 .env）读取该密钥——它绝不会作为调用方提供的工具参数，也不会嵌入源代码、示例或本文档中。

安装

通过 npx 运行（首选）

npx -y papersprocket-mcp

软件包 papersprocket-mcp 已发布到 npm，并以标识 io.github.inde-x/papersprocket 注册在官方 MCP Registry 中（状态为 active，版本为 1.0.0）。将 MCP 客户端指向 npx -y papersprocket-mcp，并在客户端环境中提供 PAPERSPROCKET_API_KEY（服务仅在服务端读取该密钥）。

从源代码安装（可选／开发）

git clone https://github.com/inde-x/papersprocket-mcp.git
cd papersprocket-mcp
npm ci
cp .env.example .env   # then set PAPERSPROCKET_API_KEY (see Configuration)

配置

服务启动时会加载 <serverdir>/.env（不会覆盖已设置的环境变量）。.env 已加入 gitignore。

变量	必填	默认值	用途
PAPERSPROCKET_API_KEY	是	—	你的 PaperSprocket API 密钥。属于机密／配置状态，绝不能作为工具参数。
PAPERSPROCKET_BASE_URL	否	https://papersprocket.com/api	API 基础 URL。固定／配置状态。
PAPERSPROCKET_MCP_OUTPUT_DIR	否	./output	渲染后的 PDF 也会写入此目录（尽力而为），供本地文件系统客户端使用。

.env 示例（替换占位符——切勿提交真实密钥）：

PAPERSPROCKET_API_KEY=psk_your_api_key_here
# PAPERSPROCKET_BASE_URL=https://papersprocket.com/api
# PAPERSPROCKET_MCP_OUTPUT_DIR=./output

运行（stdio）

node server.js                 # MCP over stdio
node server.js --list-tools    # print tool schemas, then exit

连接 MCP 客户端

将 MCP 客户端指向一个 stdio 服务：

# primary — published npm distribution:
Command:   npx
Arguments: -y papersprocket-mcp

# or a local source checkout:
Command:   node
Arguments: /path/to/papersprocket-mcp/server.js

通过服务端 .env 或环境变量提供 PAPERSPROCKET_API_KEY——绝不要将其放在客户端配置中。

MCP Inspector

npx @modelcontextprotocol/inspector node /path/to/papersprocket-mcp/server.js

列出工具 → 确认恰好有两个：render_html_to_pdf 和 check_balance。

工具架构

render_html_to_pdf

{
  "html": { "type": "string", "description": "HTML to render (non-empty)." },
  "page": {
    "properties": {
      "size":            { "enum": ["A4", "Letter"] },
      "orientation":     { "enum": ["portrait", "landscape"] },
      "margin_mm":       { "top|right|bottom|left": { "type": "number", "minimum": 0, "maximum": 50 } },
      "print_background": { "type": "boolean" }
    }
  }
}

• html — 必填，非空字符串。
• page — 可选。默认值与服务封闭的 v1 架构一致：size 为 A4，orientation 为 portrait，所有边的 margin_mm 为 10，print_background 为 true。不接受未知字段。

结果（两个 MCP 内容块）：

1. text — 元数据 JSON：tool、format、render_id、page_count、charged_cents、balance_cents、bytes、file_path、idempotency_key。
2. resource — application/pdf 数据块（base64），带有 file://（或 urn:）URI。

check_balance

{ "account_id": { "type": "string" } }

• account_id — 必填，非空字符串。

结果： { account_id, balance_cents, currency, page_price_cents }（文本块）。

幂等性

• 每次逻辑渲染都会生成一个全新的随机幂等键。
• 遇到暂时性网络故障时，服务端最多重试 2 次，并复用同一个键，因此一次逻辑渲染的重试不会导致重复扣费。
• 在服务端，PaperSprocket 根据 (Idempotency-Key, request hash) 去重，因此真正的重放会返回原始结果，不会再次扣费。

安全性／密钥边界

• PAPERSPROCKET_API_KEY 从 .env／环境中读取，不是任何工具输入架构中的字段。
• PAPERSPROCKET_BASE_URL 是固定的配置状态，不是由 Agent 控制的参数。
• 密钥仅通过 Authorization HTTP 标头发送，不存在其他凭据。
• 写入 output/ 的渲染后 PDF 是你自己的内容；该目录已加入 git 忽略列表。

定价

• 初始预付额度为 $10
• 充值金额为 $10
• 每页 $0.02

获取密钥

创建 PaperSprocket 账户即可获取 API 密钥和预付额度：

• 注册：https://papersprocket.com/onboarding/?source=mcp

许可证

MIT — 请参阅 LICENSE。