Mac-letterhead

Mac-letterhead

将任意 Markdown 文件转换为印有公司信头的专业 PDF，无需手动排版。 Mac-letterhead 将信头 PDF 视为数字信纸：它会将 Markdown 内容打印在页面的安全区域内（绝不会与页眉、页脚或徽标重叠），并通过一个小型 CSS 文件应用品牌字体排版。

完全在 Mac 上运行。底层引擎与拖放应用、命令行工具以及可供 Claude 和其他 AI 客户端直接调用的 Model Context Protocol 服务相同。

---

• 功能介绍
• 安装
• 快速开始（2 分钟）
• 使用方法 — 拖放应用 · CLI · 面向 AI 客户端的 MCP 服务
• 配置与微调 — 品牌 CSS · 选择融合策略 · 多页信头
• 高级用法 · 隐私 · 许可证

功能介绍

你有一份公司信头——PDF 顶部有徽标，底部有联系信息，可能还有浅色水印。你需要撰写文件，并将它们印在这份信头上：提案、报告、发票、备忘录。

传统方法都很麻烦：总是对不齐的 Word 模板、将内容复制粘贴并反复调整到设计师的 InDesign 文件中，或在 PDF 编辑器里手动把文字放到信头上。也可以干脆放弃，发送没有品牌标识的文件。

Mac-letterhead 会自动完成整个流程。它会分析信头 PDF，找出安全的打印区域（页眉、页脚和徽标周围的空间），将 Markdown 渲染到该区域内，并应用品牌字体排版（字体和颜色来自一个小型 CSS 文件），最终生成完整的 PDF。多页信头？首页与后续页面分别处理？统统没问题。

同一工具提供三种使用方式——Mac 拖放应用（供你使用）、命令行工具（用于脚本编写）以及 MCP 服务（让 Claude 和其他 AI 客户端按需生成带有品牌标识的文件）。

安装

选择一种方式：

Homebrew（推荐日常在 Mac 上使用）：

brew tap easytocloud/tap
brew install mac-letterhead

uvx（无需永久安装；使用 uv 的临时环境）：

uvx mac-letterhead --help

Claude Desktop（双击安装）： 从 releases page 下载最新的 mac-letterhead-<version>.mcpb 并双击，Claude for macOS 会处理后续步骤。

系统依赖项（可选，但推荐安装）

若要获得最佳渲染质量（通过 WeasyPrint 提供完整的 CSS 支持），请一次性安装 WeasyPrint 系统库：

brew install pango cairo fontconfig freetype harfbuzz

如果没有安装这些库，Mac-letterhead 会自动回退到 ReportLab，输出更简单，不依赖外部组件，但所有功能仍可正常使用。

快速开始（2 分钟）

1. 将信头文件放在 Mac-letterhead 能找到的位置。 默认约定是 ~/.letterhead/<name>.pdf：

   mkdir -p ~/.letterhead
   cp /path/to/your-letterhead.pdf ~/.letterhead/company.pdf
   

2. （可选，但强烈推荐）添加字体排版样式。 创建 ~/.letterhead/company.css，设置品牌字体和颜色：

   body        { font-family: "Inter", "Helvetica Neue", sans-serif; color: #1f2937; }
   h1, h2, h3  { color: #0b3d91; font-family: "Merriweather", Georgia, serif; }
   h1          { border-bottom: 2px solid #0b3d91; padding-bottom: 0.25em; }
   a           { color: #0b3d91; }
   

   跳过此步骤时，Mac-letterhead 会使用简洁的默认样式。

3. 在桌面上创建 droplet：

   mac-letterhead install --name "company"
   

   桌面上会出现一个 company.app。

4. 将任意 .md 或 .pdf 文件拖到 droplet 上。 选择保存位置，即可获得带信头的 PDF。

就是这样。之后每份文档只需拖放一次。

使用方法

同一套引擎，三种使用方式。

🖱️ 拖放式 droplet

最适合在 Mac 上处理人工工作流。只需设置一次，之后每份文档都可以拖到桌面图标上。

mac-letterhead install --name "company"        # uses ~/.letterhead/company.{pdf,css}
mac-letterhead install --name "personal"       # a second droplet for personal docs
mac-letterhead install --name "client-acme"    # one droplet per client / brand

每个 droplet 都是完整的 macOS .app 软件包，可以拖动、更改位置、放入 Dock，或串接到 Automator 工作流中。将文件拖到它上面时，会打开保存对话框，让你选择输出位置。

双击 droplet（不拖入任何文件）可查看该 droplet 信头的安全区域预览——裁切标记、颜色编码的色调、来源标签，全部整合在一个 PDF 中，并在默认查看器中打开。提交合并前，可用它确认“Markdown 内容是否会出现在预期位置”。

⌨️ 命令行

最适合脚本、CI 或一次性转换。无需 droplet。

# Markdown → letterheaded PDF
mac-letterhead merge-md ~/.letterhead/company.pdf "Q3 Report" ~/Desktop report.md

# Existing PDF → letterheaded PDF
mac-letterhead merge ~/.letterhead/company.pdf "Contract" ~/Desktop contract.pdf

# Preview the safe area (cut marks + tint) as a PDF
mac-letterhead preview ~/.letterhead/company.pdf

完整参考：mac-letterhead --help。

🤖 面向 AI 客户端的 MCP 服务

适合希望 Claude、Claude Code、Cursor、Windsurf 或其他 AI 助手按需生成品牌文档的场景。

添加到 Claude Desktop 配置（~/Library/Application Support/Claude/claude_desktop_config.json）中：

{
  "mcpServers": {
    "letterhead": {
      "command": "uvx",
      "args": ["mac-letterhead[mcp]", "mcp"]
    }
  }
}

然后在 Claude 中输入：“用公司的信头起草一份第三季度投资者更新。” Mac-letterhead 会处理格式设置，PDF 会保存到 ~/Desktop。

该项目已发布在 official MCP Registry，名称为 io.github.easytocloud/mac-letterhead，并可在 Glama 和 PulseMCP 上查看。完整的 MCP 配置（特定样式的服务、通过一个客户端使用多个品牌）请参阅 README_MCP.md。

配置与微调

预览并标记安全区域

Mac-letterhead 需要知道信纸上哪些区域适合安全地打印内容——也就是页眉、页脚和任何徽标之间的空间。它会通过以下三个层级确定安全区域：

1. 手动标记。 在 Preview.app 中打开信纸（Tools → Show Markup Toolbar → Rectangle），在预期的安全区域上绘制矩形框，然后保存。就这么简单——Preview.app 不提供为注释添加标签的功能，因此 Mac-letterhead 会将页面上的单个方形注释视为安全区域，即使它没有标签也是如此。如果想明确标记（或者使用支持添加标签的 PDF 编辑器），请点击矩形 → 侧边栏 → Description → 输入 safe-area（或 printable-area——不区分大小写，按子字符串匹配）。这样每页也可以有多个矩形——只会使用带标签的那个。
2. 自动检测。 没有注释时，Mac-letterhead 会分析信纸布局（文本、图形、徽标），推导出一个避开这些内容的安全矩形，并留出约 40 pt 的安全边距。
3. 默认回退值。 未检测到内容时，四边均采用 1 英寸页边距。

随时预览解析结果：

mac-letterhead preview ~/.letterhead/company.pdf
# writes ~/.letterhead/company-preview.pdf

预览 PDF 中的颜色编码可让你一眼看出工具对此结果的置信程度：

颜色	来源	含义
绿色	annotation	由你标记，完全按标记采用。
灰蓝色	auto-detected	根据信纸布局通过启发式方法推导。
琥珀色	fallback default	未检测到内容。可考虑手动标记。

每个角上的裁切标记可提供适用于印刷的精度；区域内以非常浅的色调填充，便于整体查看。左下角的小标签会说明结果采用的来源以及安全区域的精确尺寸。

通过 YAML 前置元数据设置文档选项

任何 Markdown 文件都可以以 YAML 前置元数据块开头，用于声明文档级别的覆盖选项——Jekyll、Hugo 和 Obsidian 也使用相同的约定。Mac-letterhead 会读取该内容、应用选项，然后照常渲染正文。

---
title: Q3 Investor Update
output-dir: ~/Documents/investor
page-numbers: alternate
blend-strategy: multiply
author: Erik
---

# Q3 Investor Update

Executive summary…

支持的字段（均为可选项，采用 kebab-case；未知字段会记录日志并跳过）：

字段	值	效果
title	字符串	PDF 标题元数据 + 自动生成的文件名
output-dir	路径（支持 ~）	保存生成的 PDF 的位置
page-numbers	bottom-right | bottom-center | bottom-left | alternate	详见下文。省略此项可完全禁用页码（默认行为）。
blend-strategy	darken | multiply | overlay | transparency | reverse	覆盖合并混合模式
style	样式名称	覆盖信纸样式（在专用 MCP 服务上会忽略——参见 README_MCP.md）
author、subject	字符串	PDF 元数据

page-numbers: alternate 专为小册子式的多页信纸设计：第 1 页视为标题页（不显示页码），后续左页的页码显示在左下角，右页的页码显示在右下角。需要使用 WeasyPrint 后端。

优先级（最具体的设置优先）：

explicit CLI/MCP arg  >  front matter  >  server/droplet defaults  >  hard-coded

因此，如果 MCP 工具调用明确传入 output_path=…，且文档中也设置了 output-dir: …，则以 MCP 参数为准。前置元数据会补充调用方未指定的选项。

使用 CSS 打造品牌字体排印风格

信纸 PDF 提供视觉识别元素（徽标、页眉、页脚）。CSS 提供字体排印风格：字体、颜色、间距、表格样式和标题样式。两者结合后，就能形成一套可复用的品牌形象，供任意 Markdown 文档渲染时使用。

完整示例 — ~/.letterhead/company.css：

body        { font-family: "Inter", "Helvetica Neue", sans-serif; color: #1f2937; }
h1, h2, h3  { color: #0b3d91; font-family: "Merriweather", Georgia, serif; }
h1          { border-bottom: 2px solid #0b3d91; padding-bottom: 0.25em; }
a           { color: #0b3d91; text-decoration: underline; }
code, pre   { font-family: "JetBrains Mono", ui-monospace, monospace; background: #f5f7fa; }
table th    { background: #0b3d91; color: white; }
table td    { border-bottom: 1px solid #e5e7eb; }
blockquote  { border-left: 3px solid #0b3d91; color: #4b5563; }

CSS 会应用在安全区域内，因此品牌字体排印风格会自动避开页眉、页脚和徽标。（CSS 由 WeasyPrint 后端应用；ReportLab 回退方案支持的 CSS 子集较少。）

选择混合策略

不同的信头需要使用不同的叠加模式。在 CLI 中通过 --strategy 设置，或在创建 droplet 时设置。

策略	适用场景
darken（默认）	浅色信头纸上的深色徽标／图稿
multiply	在精致设计上营造水印效果
overlay	在对比度混杂的内容中获得更好的可见性
transparency	与半透明图层平滑混合
reverse	信头置于上层，内容置于下层

多页信头

根据页面位置应用不同的信头模板：

信头 PDF 页数	应用方式
1 页	应用于文档的每一页
2 页	第 1 页 → 文档首页；第 2 页 → 其余所有页面
3 页	第 1 页 → 首页；第 2 页 → 偶数页；第 3 页 → 奇数页

高级

• 渲染后端。 使用 WeasyPrint（首选，支持完整 CSS），并在其不可用时回退到 ReportLab。安装 brew install pango cairo fontconfig freetype harfbuzz 即可启用 WeasyPrint。
• GitHub Flavored Markdown。 支持表格、任务列表、删除线、带语法高亮的代码块——前提是可用 pycmarkgfm（它是默认依赖项）。
• 自定义覆盖项。 对于路径不符合惯例的一次性 droplet，可使用 mac-letterhead install --name X --letterhead /some/other.pdf --css /some/other.css。
• 发布／发行流程。 面向贡献者的说明：docs/publishing.md。
• 运维指南。 面向贡献者：CLAUDE.md 介绍了架构、发行规则和 MCP 注册表限制。

隐私

Mac-letterhead 完全在本地计算机上运行。不会发起网络请求、收集遥测数据或分析数据，也不会进行云同步。请参阅 PRIVACY.md。

贡献

请参阅 CONTRIBUTING.md。

许可证

MIT。