PaperSprocket

PaperSprocket MCP サーバー

[MCP クライアントにPaperSprocket APIへの直接アクセスを提供する Model Context Protocol（MCP）サーバーです。正確に2つのツールを公開します。

ツール	説明
render_html_to_pdf(html, page?)	PaperSprocket APIを介してHTMLをPDFにレンダリングします。PDFはapplication/pdfのMCPリソース（base64 blob）として返され、サーバーが書き込み可能な場合はローカルファイルパスも返します。また、レンダリングメタデータ（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は、HTMLをPDFに変換するホスト型APIです。HTMLを送信すると、整形式のPDFが返されます。習得が必要なビジネス分野固有のスキーマはありません。独自のHTMLとCSSでレイアウトを制御し、PDFの処理はPaperSprocketが担当します。公式ドキュメントをご覧ください。

要件

• Node.js >= 20
• PaperSprocket APIキー。サーバーはキーをサーバー側の設定のみ（環境変数または.env）から読み込みます。呼び出し元が指定するツール引数として渡すことは決してなく、ソース、例、またはこのドキュメントに埋め込まれることもありません。

インストール

npxで実行（推奨）

npx -y papersprocket-mcp

papersprocket-mcpパッケージはnpmで公開されており、ID io.github.inde-x/papersprocket（有効、バージョン1.0.0）で公式MCP Registryに登録されています。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

PAPERSPROCKET_API_KEYは、サーバーの.envまたは環境変数を介して設定します。クライアント設定に記載することは決してありません。

MCP Inspector

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

ツールを一覧表示し、render_html_to_pdfとcheck_balanceの正確に2つがあることを確認します。

ツールのスキーマ

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コンテンツブロック2つ）：

1. text — メタデータJSON：tool、format、render_id、page_count、charged_cents、balance_cents、bytes、file_path、idempotency_key。
2. resource — file://（またはurn:）URIを持つapplication/pdf blob（base64）。

check_balance

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

• account_id — 必須。空でない文字列です。

結果： { account_id, balance_cents, currency, page_price_cents }（テキストブロック）。

冪等性

• 各論理レンダリングごとに新しいランダムな冪等性キーが生成されます。
• 一時的なネットワーク障害が発生した場合、サーバーは同じキーを再利用して最大2回再試行するため、1つの論理レンダリングの再試行によって二重に課金されることはありません。
• サーバー側では、PaperSprocket が(Idempotency-Key, request hash)で重複排除を行うため、同じリクエストを再送すると、2回目の引き落としなしで元の結果が返されます。

セキュリティ／シークレットの境界

• PAPERSPROCKET_API_KEYは.env／環境変数から読み込まれ、いずれのツール入力スキーマにも含まれません。
• PAPERSPROCKET_BASE_URLは固定の設定状態であり、エージェントが制御する引数ではありません。
• キーはAuthorization HTTPヘッダーとしてのみ送信されます。他の認証情報は存在しません。
• output/に書き込まれるレンダリング済みPDFはお客様自身のコンテンツであり、このディレクトリはgitignoreの対象です。

料金

• $10 初回の前払いクレジット
• $10 チャージ単位
• 1ページあたり$0.02

キーの取得

PaperSprocketアカウントを作成すると、APIキーと前払いクレジットを取得できます。

• オンボーディング：https://papersprocket.com/onboarding/?source=mcp

ライセンス

MIT — LICENSEを参照してください。