Back to search
pdf-booklet-mcp
MCP serverGitHub
MCP server that turns any content into a printable saddle-stitch booklet PDF (US Letter landscape sheets, folded in half)
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/macbeth76--pdf-booklet-mcp)HTML
<a href="/listings/macbeth76--pdf-booklet-mcp"><img src="/api/listings/macbeth76--pdf-booklet-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Requires Node 20+ and npm.
npm install npm run build # tsc, strict mode — must be clean npm start # runs the MCP server on stdio: node dist/index.js
The server speaks MCP over stdio only. It writes nothing to stdout except the protocol; logs go to stderr.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 218 lines
- # pdf-booklet-mcp
- An MCP server that turns **any content** into a **printable saddle-stitch
- booklet PDF**. An LLM sends the content; the MCP builds the PDF and returns
- it to the user to print out.
- This is a **separate project** from Live Panels. It has no Cloudflare /
- Worker component and nothing to do with the Alexa skill.
- ## The format
- - **Book page:** 5.5 × 8.5 in, portrait. Comfortable book margins, serif
- (Times) body text at 11 pt, page numbers centred at the foot of every
- content page (no number on the cover or back cover).
- - **Physical sheet:** US Letter, **landscape** — 11 × 8.5 in. Printed
- **double-sided** and folded in half vertically. Each folded half is one
- book page, so one sheet holds 4 book pages.
- - **Any length:** the MCP pads with blank pages (inserted just before the
- back cover, so the back cover stays the last page) until the book page
- count is a multiple of 4.
- - **Front cover = book page 1. Back cover = the last book page.**
- ## Imposition map (saddle-stitch, pre-rotated for long-edge duplex)
- For `N` book pages (a multiple of 4), sheet `s` (1-based):
- | Sheet | Front side — outside of the sheet (upright) | Back side — inside of the sheet (pre-rotated 180° in the file) |
- |-------|----------------------------------------------|------------------------------------------------------------------|
- | `s` | left `N − 2(s−1)`, right `2(s−1) + 1` | left `N − 2(s−1) − 1`, right `2(s−1) + 2` |
- The imposed PDF has **2 pages per sheet** — front, then back — so a
- double-sided printer puts PDF pages 1–2 on the first physical sheet,
- 3–4 on the second, and so on.
- **Why the back side is swapped and upside down in the file:** a
- double-sided printer flips the sheet to print the back, which rotates
- the whole back side 180° — upside down *and* left/right swapped. The
- first test print proved it: the folded booklet read
- **1, 7, 3, 5, 4, 6, 2, 8** — every back-side page upside down and in
- the other half's place, while every front-side page was correct. So
- the back side is pre-rotated 180° in the PDF (halves swapped, each
- half rotated in place). The printer's flip then cancels that out, and
- the folded booklet reads 1, 2, 3, … in order, all upright. **On
- screen the back PDF pages look upside down — that is intentional, not
- a bug. Do not "fix" it by switching the flip setting.**
- ### 8-page booklet (the sample)
- | Sheet | Front (outside, upright) | Back (inside, pre-rotated) |
- |-------|--------------------------|----------------------------|
- | 1 | left: **8** (back cover), right: **1** (front cover) | left: **7**, right: **2** |
- | 2 | left: **6**, right: **3** | left: **5**, right: **4** |
- ### 12-page booklet
- | Sheet | Front (outside, upright) | Back (inside, pre-rotated) |
- |-------|--------------------------|----------------------------|
- | 1 | left: **12** (back cover), right: **1** (front cover) | left: **11**, right: **2** |
- | 2 | left: **10**, right: **3** | left: **9**, right: **4** |
- | 3 | left: **8**, right: **5** | left: **7**, right: **6** |
- > ⚠️ **Open question — please confirm, Drew.** In the call you described
- > the first sheet as holding "the cover" and "page 1" on one side, and "the
- > last page" and "the back cover" on the other. This build implements the
- > **standard** saddle-stitch reading of that: the cover *is* page 1 and
- > the back cover *is* the last page, so sheet 1's outside is
- > `[back cover | front cover]` and its inside is `[page 2 | second-to-last
- > page]`. If you instead meant the cover to be an *extra, unnumbered*
- > page before page 1 (so page 1 sits inside the cover, facing the last
- > page), say so — that is a one-line change to the pagination, but it
- > changes every sheet's map, so it should be decided before printing a
- > long book.
- ## Install & run
- Requires Node 20+ and npm.
- ```bash
- npm install
- npm run build # tsc, strict mode — must be clean
- npm start # runs the MCP server on stdio: node dist/index.js
- ```
- The server speaks MCP over stdio only. It writes nothing to stdout
- except the protocol; logs go to stderr.
- ## Configure an LLM client
- Point any MCP client at the built server with a stdio command, e.g.
- (Claude Desktop `claude_desktop_config.json`):
- ```json
- {
- "mcpServers": {
- "pdf-booklet-mcp": {
- "command": "node",
- "args": ["/absolute/path/to/pdf-booklet-mcp/dist/index.js"]
- }
- }
- }
- ```
- ## Tool: `create_booklet_pdf`
- Input:
- | Field | Type | Notes |
- |---|---|---|
- | `title` | string, required | Booklet title; also the front cover. |
- | `author` | string | Shown on the front cover. |
- | `subtitle` | string | Shown on the front cover under the title. |
- | `markdown` | string | `#` / `##` / `###` headings, paragraphs. A line containing only `---` (or `<!-- pagebreak -->`) forces a page break. |
- | `pages` | array of `{title?, body?}` | Structured pages/sections; each entry starts on a new book page. Body paragraphs are separated by blank lines. |
- | `backCoverText` | string | Back-cover text. Defaults to a short closing line. |
- | `filename` | string | e.g. `my-booklet.pdf`. Defaults to a slug of the title. |
- Give `markdown`, `pages`, or both (markdown first, then the structured
- pages). At least one is required.
- Example call (what the LLM sends):
- ```json
- {
- "title": "The Little Book of Owls",
- "subtitle": "A short field guide for curious readers",
- "author": "Drew",
- "markdown": "# The Tawny Owl\n\nThe tawny owl is a bird of quiet woods...\n\n---\n\n# At Dusk\n\nDusk is the tawny owl's morning...",
- "filename": "little-book-of-owls.pdf"
- }
- ```
- What it returns (also as `structuredContent`):
- ```json
- {
- "pdfPath": "/absolute/path/to/pdf-booklet-mcp/output/little-book-of-owls.pdf",
- "title": "The Little Book of Owls",
- "bookPages": 8,
- "paddedBlankPages": 0,
- "sheets": 2,
- "totalPdfPages": 4,
- "imposition": [
- { "sheet": 1, "front": { "leftPage": 8, "rightPage": 1 }, "back": { "leftPage": 7, "rightPage": 2 } },
- { "sheet": 2, "front": { "leftPage": 6, "rightPage": 3 }, "back": { "leftPage": 5, "rightPage": 4 } }
- ]
- }
- ```
- PDFs are saved under `output/` in this project.
- ## Print instructions
- 1. Open the PDF and print **double-sided**.
- 2. Set the duplex / flip option to **flip on long edge**. (This is the
- printer default on most printers. The back sides are pre-rotated
- 180° in the file to match exactly this flip — see the imposition
- map above. Do not use "flip on short edge": that is the other flip,
- and it would put the inside pages upside down and swapped again.)
- 3. Print at **100% / Actual size** on US Letter (11 × 8.5 in) — do not
- use "Fit to page", or the book pages will no longer be 5.5 × 8.5 in.
- 4. Stack the sheets in order, fold the whole stack in half vertically
- (fold line down the middle of each sheet, cover on the outside),
- and staple twice along the spine (saddle-stitch). For a thick booklet,
- crease with a bone folder or spoon handle so it sits flat.
- 5. If a test print comes out with inside pages upside down or swapped
- left/right, the printer's flip setting is wrong — switch it to the
- other flip option ("flip on short edge") and reprint one sheet
- before doing the whole run. (On screen the back PDF pages look
- upside down — that is expected; judge only the printed, folded
- booklet.)
- ## Sample & verification
- ```bash
- npm run sample # builds output/sample-booklet.pdf via the real tool code path
- npm run verify # re-parses the sample and checks it independently
- npm run smoke # spawns the real MCP server over stdio and calls the tool
- npm run check # typecheck + build + sample + verify, end to end
- ```
- The sample is **"The Little Book of Owls" — 8 book pages, 2 sheets,
- 4 imposed PDF pages, 0 blank padding pages** (6 content pages between
- the covers). `npm run verify` re-parses that PDF and checks, by
- positional text extraction (`pdftotext -bbox`, so it knows which half
- of each sheet a word sits on):
- - every imposed page is exactly Letter landscape, 792 × 612 pt;
- - page count is even, sheets = pages ÷ 2, book pages = sheets × 4;
- - every sheet side holds the book pages the imposition map predicts,
- in the predicted left/right positions (proved by each content page's
- footer page number sitting in the right half — near the bottom on
- upright front sides, near the top on pre-rotated back sides, which
- also proves the back-side rotation landed in the file);
- - the cover title is on the right half of sheet 1's front, and the
- back-cover closing line is on the left half of sheet 1's front.
- All 16 checks pass on the sample as built (see the `npm run verify`
- output). Generated PDFs are **not committed** — they are reproducible
- with `npm run sample`, so `output/*.pdf` is gitignored.
- ## Project layout
- ```
- src/
- booklet.ts Core: markdown/structured parsing, book-page
- rendering (pdf-lib), saddle-stitch imposition.
- index.ts MCP server (stdio) — the create_booklet_pdf tool.
- scripts/
- generate-sample.ts Builds output/sample-booklet.pdf.
- verify-sample.ts Independent re-parse verification (see above).
- smoke-test-mcp.ts End-to-end MCP call over stdio.
- output/ Generated PDFs land here (gitignored).
- ```
- Stack: TypeScript (`"strict": true`, Node 20+), the official TypeScript
- MCP SDK (`@modelcontextprotocol/sdk`, stdio transport), `pdf-lib` for
- PDF generation and imposition, `zod` for the tool schema. No `any`, no
- `ts-ignore` — `npm run typecheck` (`tsc --noEmit`) is clean.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.