{
"markdown": "# Mac-letterhead\n\n\n\n[](https://pypi.org/project/Mac-letterhead/)\n[](https://github.com/easytocloud/homebrew-tap)\n[](https://pypi.org/project/Mac-letterhead/)\n\n[](https://github.com/easytocloud/Mac-letterhead/actions/workflows/publish.yml)\n[](LICENSE)\n[](https://registry.modelcontextprotocol.io)\n[](https://pypi.org/project/Mac-letterhead/)\n\n\n ![\"Mac-letterhead\"](\"https://raw.githubusercontent.com/easytocloud/Mac-letterhead/main/letterhead_pdf/resources/icon.png\")
\n\n\n**Turn any Markdown file into a professionally-branded PDF on your company's letterhead — with no manual formatting.** Mac-letterhead treats your letterhead PDF as *digital stationery*: it prints your Markdown into the safe area of the page (never overlapping your header, footer, or logo) and applies your brand's typography from a small CSS file.\n\nRuns entirely on your Mac. Same engine as a drag-and-drop droplet, a command-line tool, or a Model Context Protocol server that Claude and other AI clients can call directly.\n\n\n\n---\n\n- [What it does](#what-it-does)\n- [Install](#install)\n- [Quick start (2 minutes)](#quick-start-2-minutes)\n- [Use it](#use-it) — [droplet](#-drag-and-drop-droplet) · [CLI](#-command-line) · [MCP server](#-mcp-server-for-ai-clients)\n- [Configure & fine-tune](#configure--fine-tune) — [brand CSS](#brand-your-typography-with-css) · [blend strategies](#choose-a-blend-strategy) · [multi-page](#multi-page-letterheads)\n- [Advanced](#advanced) · [Privacy](#privacy) · [License](#license)\n\n## What it does\n\nYou have a company letterhead — a PDF with your logo at the top, contact info at the bottom, maybe a subtle watermark. You have documents to write, and they need to be on that letterhead: proposals, reports, invoices, memos.\n\nThe traditional options are all painful: Word templates that never quite line up, copy-paste-adjust cycles into a designer's InDesign file, or manually placing text over the letterhead in a PDF editor. Or just giving up and sending unbranded.\n\nMac-letterhead does the whole thing automatically. It **analyzes your letterhead PDF to find the safe printable area** (the space around the header, footer, and logo), **renders your Markdown into that area** with your brand's typography (fonts and colors from a tiny CSS file), and hands you a finished PDF. Multi-page letterhead? First-page vs subsequent pages? Handled.\n\nThe same tool ships as three interfaces — a Mac drag-and-drop app (for you), a command-line utility (for scripting), and an MCP server (so Claude and other AI clients can produce your branded documents on request).\n\n## Install\n\nPick one:\n\n**Homebrew (recommended for everyday Mac use):**\n```bash\nbrew tap easytocloud/tap\nbrew install mac-letterhead\n```\n\n**uvx (no permanent install; uses uv's ephemeral env):**\n```bash\nuvx mac-letterhead --help\n```\n\n**Claude Desktop (double-click install):**\nDownload the latest `mac-letterhead-.mcpb` from the [releases page](https://github.com/easytocloud/Mac-letterhead/releases) and double-click it — Claude for macOS handles the rest.\n\n### System dependencies (optional but recommended)\n\nFor the best rendering quality (full CSS support via WeasyPrint), install the WeasyPrint system libraries once:\n\n```bash\nbrew install pango cairo fontconfig freetype harfbuzz\n```\n\nWithout them, Mac-letterhead falls back to ReportLab automatically — simpler output, no external deps, everything still works.\n\n## Quick start (2 minutes)\n\n1. **Put your letterhead somewhere Mac-letterhead can find it.** The default convention is `~/.letterhead/.pdf`:\n ```bash\n mkdir -p ~/.letterhead\n cp /path/to/your-letterhead.pdf ~/.letterhead/company.pdf\n ```\n\n2. **(Optional, but strongly recommended) Add typography.** Create `~/.letterhead/company.css` with your brand's fonts and colors:\n ```css\n body { font-family: \"Inter\", \"Helvetica Neue\", sans-serif; color: #1f2937; }\n h1, h2, h3 { color: #0b3d91; font-family: \"Merriweather\", Georgia, serif; }\n h1 { border-bottom: 2px solid #0b3d91; padding-bottom: 0.25em; }\n a { color: #0b3d91; }\n ```\n Skip this and Mac-letterhead uses a clean default.\n\n3. **Create the droplet on your Desktop:**\n ```bash\n mac-letterhead install --name \"company\"\n ```\n A `company.app` appears on your Desktop.\n\n4. **Drop any `.md` or `.pdf` file onto the droplet.** Choose where to save. You get a letterheaded PDF.\n\nThat's it. Every subsequent document is one drop.\n\n## Use it\n\nSame engine, three interfaces.\n\n### 🖱️ Drag-and-drop droplet\n\nBest for human workflows on a Mac. One-time setup, then every future document is a drag onto a Desktop icon.\n\n```bash\nmac-letterhead install --name \"company\" # uses ~/.letterhead/company.{pdf,css}\nmac-letterhead install --name \"personal\" # a second droplet for personal docs\nmac-letterhead install --name \"client-acme\" # one droplet per client / brand\n```\n\nEach droplet is a full macOS `.app` bundle you can drag around, put in the Dock, or Automator-chain. Dropping a file on it opens a save dialog for the output location.\n\n**Double-click the droplet** (without dropping anything) to see the safe-area preview for that droplet's letterhead — cut marks, colour-coded tint, source label, all in one PDF that opens in your default viewer. Handy for verifying \"will Markdown land where I expect it\" before committing to a merge.\n\n### ⌨️ Command line\n\nBest for scripting, CI, or one-shot conversions. No droplet needed.\n\n```bash\n# Markdown → letterheaded PDF\nmac-letterhead merge-md ~/.letterhead/company.pdf \"Q3 Report\" ~/Desktop report.md\n\n# Existing PDF → letterheaded PDF\nmac-letterhead merge ~/.letterhead/company.pdf \"Contract\" ~/Desktop contract.pdf\n\n# Preview the safe area (cut marks + tint) as a PDF\nmac-letterhead preview ~/.letterhead/company.pdf\n```\n\nFull reference: `mac-letterhead --help`.\n\n### 🤖 MCP server for AI clients\n\nBest when you want Claude, Claude Code, Cursor, Windsurf, or another AI assistant to produce branded documents on demand.\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"letterhead\": {\n \"command\": \"uvx\",\n \"args\": [\"mac-letterhead[mcp]\", \"mcp\"]\n }\n }\n}\n```\n\nThen in Claude: *\"Draft a Q3 investor update on our company letterhead.\"* Mac-letterhead handles the formatting; the PDF lands in `~/Desktop`.\n\nPublished on the [official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.easytocloud/mac-letterhead` — visible on [Glama](https://glama.ai/mcp/servers/easytocloud/mac-letterhead) and [PulseMCP](https://www.pulsemcp.com/servers/easytocloud). For full MCP configuration (style-specific servers, multiple brands from one client), see [README_MCP.md](README_MCP.md).\n\n## Configure & fine-tune\n\n### Preview and mark the safe area\n\nMac-letterhead needs to know where on your letterhead is *safe* to print content — the space between the header, footer, and any logos. It figures this out in three tiers:\n\n1. **You mark it explicitly.** Open your letterhead in Preview.app (Tools → Show Markup Toolbar → Rectangle), draw a box over the intended safe area, save. That's it — Preview.app doesn't offer any way to label annotations, so Mac-letterhead treats a **single Square annotation** on a page as the safe area even without a label. If you want to be unambiguous (or you're using a PDF editor that supports labeling), click your rectangle → sidebar → Description → type `safe-area` (or `printable-area` — case-insensitive, substring match). Then multiple rectangles per page work too — only the labeled one is used.\n2. **Auto-detected.** No annotation → Mac-letterhead analyses the letterhead's layout (text, drawings, logos) and derives a safe rectangle that avoids them, with a ~40 pt safety pad.\n3. **Fallback default.** No content detected → 1-inch margins on every side.\n\nPreview the resolution any time:\n\n```bash\nmac-letterhead preview ~/.letterhead/company.pdf\n# writes ~/.letterhead/company-preview.pdf\n```\n\nColour code in the preview PDF — glance to see how confident the tool is:\n\n| Colour | Source | What it means |\n|---|---|---|\n| **Green** | `annotation` | You marked it. Trusted verbatim. |\n| **Slate blue** | `auto-detected` | Heuristic derived it from the letterhead layout. |\n| **Amber** | `fallback default` | No content detected. Consider marking it. |\n\nCut marks at each corner give print-native precision; a very subtle tint fills the region for gestalt. A tiny label at the bottom-left tells you which source drove the result and the safe area's exact dimensions.\n\n### Per-document options via YAML front matter\n\nAny Markdown file can start with a YAML front-matter block declaring per-document overrides — the same convention Jekyll, Hugo, and Obsidian use. Mac-letterhead reads it, applies the options, and renders the body normally.\n\n```markdown\n---\ntitle: Q3 Investor Update\noutput-dir: ~/Documents/investor\npage-numbers: alternate\nblend-strategy: multiply\nauthor: Erik\n---\n\n# Q3 Investor Update\n\nExecutive summary…\n```\n\nSupported fields (all optional, kebab-case, unknown fields are logged and skipped):\n\n| Field | Values | Effect |\n|---|---|---|\n| `title` | string | PDF title metadata + auto-generated filename |\n| `output-dir` | path (supports `~`) | Where the resulting PDF is written |\n| `page-numbers` | `bottom-right` \\| `bottom-center` \\| `bottom-left` \\| `alternate` | See below. Omit to disable page numbers entirely (the default). |\n| `blend-strategy` | `darken` \\| `multiply` \\| `overlay` \\| `transparency` \\| `reverse` | Overrides the merge blend mode |\n| `style` | style name | Overrides the letterhead style (ignored on dedicated MCP servers — see [README_MCP.md](README_MCP.md)) |\n| `author`, `subject` | string | PDF metadata |\n\n**`page-numbers: alternate`** is designed for booklet-style multi-page letterheads: page 1 is treated as a title page (no number), subsequent left-hand pages get the number bottom-left, right-hand pages bottom-right. Requires the WeasyPrint backend.\n\n**Precedence** (most-specific wins):\n\n```\nexplicit CLI/MCP arg > front matter > server/droplet defaults > hard-coded\n```\n\nSo if an MCP tool call passes `output_path=…` explicitly *and* the document says `output-dir: …`, the MCP arg wins. Front matter fills in what the caller left unspecified.\n\n### Brand your typography with CSS\n\nThe letterhead PDF supplies the visual identity (logo, header, footer). CSS supplies the *typography*: fonts, colors, spacing, table styling, heading treatment. Together they make one reusable brand identity that any Markdown document can be rendered through.\n\nFull example — `~/.letterhead/company.css`:\n\n```css\nbody { font-family: \"Inter\", \"Helvetica Neue\", sans-serif; color: #1f2937; }\nh1, h2, h3 { color: #0b3d91; font-family: \"Merriweather\", Georgia, serif; }\nh1 { border-bottom: 2px solid #0b3d91; padding-bottom: 0.25em; }\na { color: #0b3d91; text-decoration: underline; }\ncode, pre { font-family: \"JetBrains Mono\", ui-monospace, monospace; background: #f5f7fa; }\ntable th { background: #0b3d91; color: white; }\ntable td { border-bottom: 1px solid #e5e7eb; }\nblockquote { border-left: 3px solid #0b3d91; color: #4b5563; }\n```\n\nCSS is applied inside the safe area, so branded typography stays clear of your header, footer, and logo automatically. (CSS is applied by the WeasyPrint backend; the ReportLab fallback supports a reduced subset.)\n\n### Choose a blend strategy\n\nDifferent letterheads need different overlay modes. Set with `--strategy` in the CLI, or when creating a droplet.\n\n| Strategy | Best for |\n| ------------------ | ------------------------------------------- |\n| `darken` (default) | Dark logo/artwork on light letterhead paper |\n| `multiply` | Watermark-like effects on subtle designs |\n| `overlay` | Better visibility across mixed contrasts |\n| `transparency` | Smooth blending with translucent layers |\n| `reverse` | Letterhead on top, content beneath |\n\n### Multi-page letterheads\n\nDifferent letterhead template per page position:\n\n| Letterhead PDF has… | Applied to |\n| ------------------- | ---------------------------------------------------- |\n| 1 page | Every document page |\n| 2 pages | Page 1 → first document page; page 2 → all others |\n| 3 pages | Page 1 → first; page 2 → even; page 3 → odd |\n\n## Advanced\n\n- **Rendering backends.** [WeasyPrint](https://weasyprint.org/) (preferred, full CSS support) with a [ReportLab](https://www.reportlab.com/) fallback. Install `brew install pango cairo fontconfig freetype harfbuzz` to opt into WeasyPrint.\n- **GitHub Flavored Markdown.** Tables, task lists, strikethrough, code blocks with syntax highlighting — all supported when `pycmarkgfm` is available (it's a default dependency).\n- **Custom overrides.** `mac-letterhead install --name X --letterhead /some/other.pdf --css /some/other.css` for one-off droplets with non-conventional paths.\n- **Publishing / release pipeline.** Contributor-facing: [`docs/publishing.md`](docs/publishing.md).\n- **Operator guide.** For contributors: [`CLAUDE.md`](CLAUDE.md) documents the architecture, release rules, and MCP registry constraints.\n\n## Privacy\n\nMac-letterhead runs entirely on your local machine. No network calls, no telemetry, no analytics, no cloud sync. See [PRIVACY.md](PRIVACY.md).\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nMIT.\n",
"bytes": 14964,
"sha": "2a1b8dadfd4e69d5352e5fabba97bb1e5fad80fca06e816cef08ff84c0f100e4",
"repo_slug": "easytocloud/mac-letterhead",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_easytocloud_mac_letterhead_47ed84bb/readme"
}