Skip to content
Back to search

pdf-booklet-mcp

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/macbeth76--pdf-booklet-mcp/badge.svg)](/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
  1. # pdf-booklet-mcp
  2. An MCP server that turns **any content** into a **printable saddle-stitch
  3. booklet PDF**. An LLM sends the content; the MCP builds the PDF and returns
  4. it to the user to print out.
  5. This is a **separate project** from Live Panels. It has no Cloudflare /
  6. Worker component and nothing to do with the Alexa skill.
  7. ## The format
  8. - **Book page:** 5.5 × 8.5 in, portrait. Comfortable book margins, serif
  9. (Times) body text at 11 pt, page numbers centred at the foot of every
  10. content page (no number on the cover or back cover).
  11. - **Physical sheet:** US Letter, **landscape** — 11 × 8.5 in. Printed
  12. **double-sided** and folded in half vertically. Each folded half is one
  13. book page, so one sheet holds 4 book pages.
  14. - **Any length:** the MCP pads with blank pages (inserted just before the
  15. back cover, so the back cover stays the last page) until the book page
  16. count is a multiple of 4.
  17. - **Front cover = book page 1. Back cover = the last book page.**
  18. ## Imposition map (saddle-stitch, pre-rotated for long-edge duplex)
  19. For `N` book pages (a multiple of 4), sheet `s` (1-based):
  20. | Sheet | Front side — outside of the sheet (upright) | Back side — inside of the sheet (pre-rotated 180° in the file) |
  21. |-------|----------------------------------------------|------------------------------------------------------------------|
  22. | `s` | left `N − 2(s−1)`, right `2(s−1) + 1` | left `N − 2(s−1) − 1`, right `2(s−1) + 2` |
  23. The imposed PDF has **2 pages per sheet** — front, then back — so a
  24. double-sided printer puts PDF pages 1–2 on the first physical sheet,
  25. 3–4 on the second, and so on.
  26. **Why the back side is swapped and upside down in the file:** a
  27. double-sided printer flips the sheet to print the back, which rotates
  28. the whole back side 180° — upside down *and* left/right swapped. The
  29. first test print proved it: the folded booklet read
  30. **1, 7, 3, 5, 4, 6, 2, 8** — every back-side page upside down and in
  31. the other half's place, while every front-side page was correct. So
  32. the back side is pre-rotated 180° in the PDF (halves swapped, each
  33. half rotated in place). The printer's flip then cancels that out, and
  34. the folded booklet reads 1, 2, 3, … in order, all upright. **On
  35. screen the back PDF pages look upside down — that is intentional, not
  36. a bug. Do not "fix" it by switching the flip setting.**
  37. ### 8-page booklet (the sample)
  38. | Sheet | Front (outside, upright) | Back (inside, pre-rotated) |
  39. |-------|--------------------------|----------------------------|
  40. | 1 | left: **8** (back cover), right: **1** (front cover) | left: **7**, right: **2** |
  41. | 2 | left: **6**, right: **3** | left: **5**, right: **4** |
  42. ### 12-page booklet
  43. | Sheet | Front (outside, upright) | Back (inside, pre-rotated) |
  44. |-------|--------------------------|----------------------------|
  45. | 1 | left: **12** (back cover), right: **1** (front cover) | left: **11**, right: **2** |
  46. | 2 | left: **10**, right: **3** | left: **9**, right: **4** |
  47. | 3 | left: **8**, right: **5** | left: **7**, right: **6** |
  48. > ⚠️ **Open question — please confirm, Drew.** In the call you described
  49. > the first sheet as holding "the cover" and "page 1" on one side, and "the
  50. > last page" and "the back cover" on the other. This build implements the
  51. > **standard** saddle-stitch reading of that: the cover *is* page 1 and
  52. > the back cover *is* the last page, so sheet 1's outside is
  53. > `[back cover | front cover]` and its inside is `[page 2 | second-to-last
  54. > page]`. If you instead meant the cover to be an *extra, unnumbered*
  55. > page before page 1 (so page 1 sits inside the cover, facing the last
  56. > page), say so — that is a one-line change to the pagination, but it
  57. > changes every sheet's map, so it should be decided before printing a
  58. > long book.
  59. ## Install & run
  60. Requires Node 20+ and npm.
  61. ```bash
  62. npm install
  63. npm run build # tsc, strict mode — must be clean
  64. npm start # runs the MCP server on stdio: node dist/index.js
  65. ```
  66. The server speaks MCP over stdio only. It writes nothing to stdout
  67. except the protocol; logs go to stderr.
  68. ## Configure an LLM client
  69. Point any MCP client at the built server with a stdio command, e.g.
  70. (Claude Desktop `claude_desktop_config.json`):
  71. ```json
  72. {
  73. "mcpServers": {
  74. "pdf-booklet-mcp": {
  75. "command": "node",
  76. "args": ["/absolute/path/to/pdf-booklet-mcp/dist/index.js"]
  77. }
  78. }
  79. }
  80. ```
  81. ## Tool: `create_booklet_pdf`
  82. Input:
  83. | Field | Type | Notes |
  84. |---|---|---|
  85. | `title` | string, required | Booklet title; also the front cover. |
  86. | `author` | string | Shown on the front cover. |
  87. | `subtitle` | string | Shown on the front cover under the title. |
  88. | `markdown` | string | `#` / `##` / `###` headings, paragraphs. A line containing only `---` (or `<!-- pagebreak -->`) forces a page break. |
  89. | `pages` | array of `{title?, body?}` | Structured pages/sections; each entry starts on a new book page. Body paragraphs are separated by blank lines. |
  90. | `backCoverText` | string | Back-cover text. Defaults to a short closing line. |
  91. | `filename` | string | e.g. `my-booklet.pdf`. Defaults to a slug of the title. |
  92. Give `markdown`, `pages`, or both (markdown first, then the structured
  93. pages). At least one is required.
  94. Example call (what the LLM sends):
  95. ```json
  96. {
  97. "title": "The Little Book of Owls",
  98. "subtitle": "A short field guide for curious readers",
  99. "author": "Drew",
  100. "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...",
  101. "filename": "little-book-of-owls.pdf"
  102. }
  103. ```
  104. What it returns (also as `structuredContent`):
  105. ```json
  106. {
  107. "pdfPath": "/absolute/path/to/pdf-booklet-mcp/output/little-book-of-owls.pdf",
  108. "title": "The Little Book of Owls",
  109. "bookPages": 8,
  110. "paddedBlankPages": 0,
  111. "sheets": 2,
  112. "totalPdfPages": 4,
  113. "imposition": [
  114. { "sheet": 1, "front": { "leftPage": 8, "rightPage": 1 }, "back": { "leftPage": 7, "rightPage": 2 } },
  115. { "sheet": 2, "front": { "leftPage": 6, "rightPage": 3 }, "back": { "leftPage": 5, "rightPage": 4 } }
  116. ]
  117. }
  118. ```
  119. PDFs are saved under `output/` in this project.
  120. ## Print instructions
  121. 1. Open the PDF and print **double-sided**.
  122. 2. Set the duplex / flip option to **flip on long edge**. (This is the
  123. printer default on most printers. The back sides are pre-rotated
  124. 180° in the file to match exactly this flip — see the imposition
  125. map above. Do not use "flip on short edge": that is the other flip,
  126. and it would put the inside pages upside down and swapped again.)
  127. 3. Print at **100% / Actual size** on US Letter (11 × 8.5 in) — do not
  128. use "Fit to page", or the book pages will no longer be 5.5 × 8.5 in.
  129. 4. Stack the sheets in order, fold the whole stack in half vertically
  130. (fold line down the middle of each sheet, cover on the outside),
  131. and staple twice along the spine (saddle-stitch). For a thick booklet,
  132. crease with a bone folder or spoon handle so it sits flat.
  133. 5. If a test print comes out with inside pages upside down or swapped
  134. left/right, the printer's flip setting is wrong — switch it to the
  135. other flip option ("flip on short edge") and reprint one sheet
  136. before doing the whole run. (On screen the back PDF pages look
  137. upside down — that is expected; judge only the printed, folded
  138. booklet.)
  139. ## Sample & verification
  140. ```bash
  141. npm run sample # builds output/sample-booklet.pdf via the real tool code path
  142. npm run verify # re-parses the sample and checks it independently
  143. npm run smoke # spawns the real MCP server over stdio and calls the tool
  144. npm run check # typecheck + build + sample + verify, end to end
  145. ```
  146. The sample is **"The Little Book of Owls" — 8 book pages, 2 sheets,
  147. 4 imposed PDF pages, 0 blank padding pages** (6 content pages between
  148. the covers). `npm run verify` re-parses that PDF and checks, by
  149. positional text extraction (`pdftotext -bbox`, so it knows which half
  150. of each sheet a word sits on):
  151. - every imposed page is exactly Letter landscape, 792 × 612 pt;
  152. - page count is even, sheets = pages ÷ 2, book pages = sheets × 4;
  153. - every sheet side holds the book pages the imposition map predicts,
  154. in the predicted left/right positions (proved by each content page's
  155. footer page number sitting in the right half — near the bottom on
  156. upright front sides, near the top on pre-rotated back sides, which
  157. also proves the back-side rotation landed in the file);
  158. - the cover title is on the right half of sheet 1's front, and the
  159. back-cover closing line is on the left half of sheet 1's front.
  160. All 16 checks pass on the sample as built (see the `npm run verify`
  161. output). Generated PDFs are **not committed** — they are reproducible
  162. with `npm run sample`, so `output/*.pdf` is gitignored.
  163. ## Project layout
  164. ```
  165. src/
  166. booklet.ts Core: markdown/structured parsing, book-page
  167. rendering (pdf-lib), saddle-stitch imposition.
  168. index.ts MCP server (stdio) — the create_booklet_pdf tool.
  169. scripts/
  170. generate-sample.ts Builds output/sample-booklet.pdf.
  171. verify-sample.ts Independent re-parse verification (see above).
  172. smoke-test-mcp.ts End-to-end MCP call over stdio.
  173. output/ Generated PDFs land here (gitignored).
  174. ```
  175. Stack: TypeScript (`"strict": true`, Node 20+), the official TypeScript
  176. MCP SDK (`@modelcontextprotocol/sdk`, stdio transport), `pdf-lib` for
  177. PDF generation and imposition, `zod` for the tool schema. No `any`, no
  178. `ts-ignore` — `npm run typecheck` (`tsc --noEmit`) is clean.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.