pdf-letter-mcp

pdf-letter-mcp

本地 MCP 服务（stdio），可将结构化信函数据转换为可打印的 PDF。仅提供一种固定版式：日常德语信函。收件人地址按 DIN 5008 定位，确保正好落在 DL 和 C6/C5 窗口信封的窗口内。无需 Web 服务或外部 API，所有操作都在你的计算机上离线完成。

功能

• 一种版式，无其他变体：回邮地址行、收件人、右对齐的“地点、日期”、下方带有参考信息的粗体主题栏、称呼、正文、结尾、签名、附件
• 地址栏高 45 mm，底边距左侧 105 mm，包含回邮地址行、备注区（挂号信、请勿转寄）和地址区
• 回邮地址、备注和收件人在地址栏内均匀排布，使整个区块在信封窗口中位置平衡，并能容纳更多地址行。addressLayout: "din" 可切换回固定区域边界
• 分页时将结尾、签名图片、姓名和附件保留在同一页；续页显示收件人、日期和页码
• 主题位于地址栏下方 33 mm 处，地点和日期位于其上方三行处
• 在 105 mm 和 210 mm 处设置折叠标记，在 148.5 mm 处设置打孔标记
• 符合 DIN 5008 的左侧 25 mm 书写边距，地址栏也沿用这一边距，因此地址、主题和正文共用同一左边缘。地址栏的右边缘保持在 105 mm 处，并位于 90 mm 宽的信封窗口内
• 结尾、一个空行、打印姓名。signature.spaceMm 可为手写签名预留更多空间
• 签名图片文件：带 alpha 通道的 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 会显示可用资料。若既未指定资料，也未提供发件人，则会拒绝生成信函，而不是编造信息。

该文件应保存在仓库之外，.gitignore 中已包含 profiles.json。

布局固定

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：强制分页

签名

有两种方式，最终都会在 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 许可证约束。