pdf-letter-mcp

pdf-letter-mcp

構造化された手紙データから印刷用PDFを生成する、ローカルのMCPサーバー（stdio）です。レイアウトは固定で、日常的なドイツ語の手紙に対応します。宛先住所はDIN 5008に従って配置され、DLおよびC6/C5の窓付き封筒の窓にぴったり収まります。ウェブサービスや外部APIは不要で、すべてお使いのマシン上でオフライン実行できます。

特長

• レイアウトは1種類で、バリエーションはありません：差出人住所行、宛先、右揃えの「場所、日付」、参照情報を下に添えた太字の件名ブロック、頭語、本文、結語、署名、同封物
• 高さ45 mmの住所欄は左端から105 mmの位置で終わり、差出人住所行、備考欄（Einschreiben、Nicht nachsenden）、住所欄を含みます
• 差出人住所、備考、宛先は住所欄内でバランスよく配置されるため、ブロックが封筒の窓の中に均等に収まり、住所の行数が増えても入ります。addressLayout: "din" を指定すると、固定されたゾーン境界に戻ります
• ページ区切りでは結語、署名画像、氏名、同封物をまとめて配置し、続きのページには宛先、日付、ページ番号を表示します
• 件名は住所欄の33 mm下、場所と日付は住所欄の3行上に配置します
• 折り目マークは105 mmと210 mm、穴あけマークは148.5 mmの位置に表示します
• 左側にDIN 5008の25 mmの書字余白を設け、住所欄もそれに沿って配置するため、住所、件名、本文の左端が揃います。欄の右端は105 mmの位置に保たれ、幅90 mmの封筒窓の内側に収まります
• 結語、空行1行、印字する氏名。signature.spaceMm を指定すると、手書き署名用のスペースを広げられます
• 画像ファイルによる署名：アルファチャンネルを含むPNGは透明度が保たれ、印字する氏名の上にある空行に重ねて配置されるため、テキストの位置は変わりません。スキャン画像向けに、任意でトリミング、背景除去、インクの色変更ができます
• 多言語対応：de、en、fr、es、it、nl、pt、pl、tr、da、sv、cs。ロケールに応じた日付形式と国ごとの住所規則に対応します
• 言語に応じたハイフネーション、太字／斜体のマークアップ、箇条書きと番号付きリスト、続きページ用ヘッダー付きの自動ページ区切り
• ページ番号と、DIN 5008のゾーンを描画するレイアウトデバッグモード
• 埋め込みUnicodeフォント（DejaVu）、インストール済みのシステムフォント、または.ttfのパスに対応します

インストール

npm install
npm run build

Claude Codeにサーバーを登録します：

claude mcp add pdf-letter -- node "/absolute/path/to/pdf-letter-mcp/dist/src/index.js"

または、~/.claude.json / claude_desktop_config.json に登録します：

{
  "mcpServers": {
    "pdf-letter": {
      "command": "node",
      "args": ["/absolute/path/to/pdf-letter-mcp/dist/src/index.js"],
      "env": {
        "PDF_LETTER_OUTPUT_DIR": "~/Documents/Briefe"
      }
    }
  }
}

環境変数

変数	用途
PDF_LETTER_OUTPUT_DIR	生成したPDFのデフォルト保存先ディレクトリです。設定されていない場合は、システムの一時ディレクトリが使われます。
PDF_LETTER_FONT_DIR	フォントファミリーを名前で解決する際に検索する追加ディレクトリです。
PDF_LETTER_FONT	すべての手紙に使用するフォントファミリーです。例：Arial。デフォルトは同梱のDejaVu Sansです。
PDF_LETTER_FONT_SIZE	すべての手紙に使用するフォントサイズ（pt）です。デフォルトは11です。
PDF_LETTER_PROFILES	差出人プロフィールのパスです。デフォルトは~/.config/pdf-letter-mcp/profiles.jsonです。
PDF_LETTER_PROFILE	手紙にプロフィール名が指定されておらず、ファイルにもdefaultProfileがない場合に使用するプロフィールです。

差出人プロフィール

差出人の住所と署名は、プロンプトではなくマシン上のファイルに保存されます。手紙でプロフィールを指定すると、サーバーが住所、差出人住所行、署名画像をそのまま補います。

{
  "defaultProfile": "erika",
  "profiles": {
    "erika": {
      "description": "Erika Musterfrau, privat",
      "sender": {
        "name": "Erika Musterfrau",
        "street": "Musterstraße 12",
        "postalCode": "12345",
        "city": "Musterstadt",
        "country": "DE"
      },
      "place": "Musterstadt",
      "locale": "de",
      "signature": { "path": "/pfad/zur/unterschrift.png" }
    }
  }
}

create_letter では、コンテンツに加えて"profile": "erika"を指定するだけで済みます。本人情報はプロフィールが管理します。呼び出しで渡された差出人や署名はプロフィールの内容に置き換えられ、place、locale、closingはデフォルト値として使われますが、手紙側で上書きできます。list_profilesで利用可能なプロフィールを確認できます。プロフィールも差出人も指定されていない場合、差出人を推測して作成するのではなく、手紙の作成を拒否します。

このファイルはリポジトリの外に置きます。profiles.jsonは.gitignoreに含まれています。

レイアウトは固定です

MCP ツールが受け取るのは内容のみです。住所、日付、件名、参照情報、本文、署名、同封物に限られます。余白、間隔、フォント、画像のサイズや位置を指定するパラメーターはなく、クライアントから送られた未知のフィールドは破棄されます。タイポグラフィはインストール時の設定（PDF_LETTER_FONT、PDF_LETTER_FONT_SIZE）で決まるため、同じインストール環境で作成するすべてのレターは同じ見た目になります。会社のレターヘッド、情報ブロック、フッターを作成するための部品はライブラリに残っていますが、MCP 経由では利用できません。

ツール

ツール	用途
create_letter	レターをレンダリングして PDF を書き込みます。パス、ページ数、レイアウト指標、警告を返します。
preview_letter	ファイルを書き込まずに同じレンダリングを行い、レイアウトを確認します。
prepare_signature	スキャンした署名を整え（トリミング、背景の透過、インクの色）、PNG として書き込みます。
get_din5008_spec	用紙形式の寸法をミリメートル単位で返します。
list_locales	対応言語と、それぞれの固定テキストを一覧表示します。
list_fonts	組み込みフォントファミリーを一覧表示し、フォント名をインストール済みのシステムフォントと照合します。

create_letter

差出人は、受取人の上にある小さな返信用住所欄にのみ表示されます。場所と日付は太字の件名ブロックの上に右揃えで配置され、参照情報は件名の直下に配置されます。

{
  "locale": "de",
  "sender": {
    "name": "Erika Musterfrau",
    "street": "Musterstraße 12",
    "postalCode": "12345",
    "city": "Musterstadt",
    "country": "DE"
  },
  "recipient": {
    "company": "Stadtwerke Musterstadt",
    "street": "Industriestraße 8",
    "postalCode": "12345",
    "city": "Musterstadt"
  },
  "place": "Musterstadt",
  "date": "2026-07-24",
  "dateStyle": "long",
  "subject": "Widerspruch gegen die Jahresabrechnung vom 01.07.2026",
  "subjectLines": ["Zeichen: SW-2026-0815", "Kunden-Nummer: 000000000"],
  "body": "hiermit widerspreche ich der Jahresabrechnung.\n\n- korrigierte Abrechnung\n- Eingangsbestätigung",
  "signature": {
    "path": "/pfad/zur/unterschrift.png",
    "widthMm": 45,
    "removeBackground": true,
    "trim": true,
    "name": "Erika Musterfrau"
  },
  "enclosures": ["Kopie der Abrechnung"]
}

sender、recipient、body 以外はすべて省略可能です。宛名は受取人から生成されます（Frau と Dr. Erika Mustermann の組み合わせは Sehr geehrte Frau Dr. Mustermann, になります）。日付の既定値は今日で、結びの言葉はロケールの既定値になります。

本文のマークアップ

• 空行：新しい段落
• 単一の改行：改行（代わりに bodyMode を markdown に設定すると、折り返して整形されます）
• - item または 1. item：箇条書きまたは番号付きリスト
• **bold**、*italic*
• 行単独の \pagebreak：強制改ページ

署名

方法は2つあり、どちらも PDF 内では画像として扱われます。

1. ファイルを直接渡します：signature.path と trim、removeBackground を指定します。スキャン画像はレンダリングのたびに整えられます。
2. prepare_signature で一度だけ整えて、生成された PNG を再利用します。処理が速く、レターに挿入する前に結果を確認できます。

trim、removeBackground、inkColor にはオプションの sharp 依存関係が必要です。これは既定でインストールされています。すでに背景が透過している PNG なら、これがなくても使用できます。

画像はオーバーレイとして配置されます。結びの言葉、その後の空行、印字された氏名の位置は変わらず、署名は空行の上に重なり、結びの言葉にもかかります。これは、紙に「Mit freundlichen Grüßen」と書かれた結びの言葉に重ねて署名するのと同じ配置です。この重なりは意図したものです。

サイズと位置は呼び出し元ではなく、レンダラーが決定します。署名は結びの行とおよそ同じ幅（約50 mm）に拡大縮小され、その幅の1.2倍、縦28 mmを比例を保ったまま上限とします。幅、高さ、オフセット、間隔を指定するパラメーターはないため、レターごとにレイアウトがずれることはありません。

検証

npm test          # geometry, address rules, typography, rendering
npm run examples  # writes sample letters to examples/

examples/ には、ドイツ語のレター、同じレターの英語版、DIN 5008 のゾーンを描画するデバッグ版が含まれており、住所欄の位置を窓付き封筒に合わせて確認できます。preview_letter は同じ測定値を JSON として返し、住所が長すぎる場合や住所欄に収まらない場合は警告も返します。

ライセンス

MIT です。詳しくは LICENSE を参照してください。同梱の DejaVu フォントには、Bitstream Vera ライセンスおよび Arev ライセンスが適用されます。