@shuji-bonji/pdf-writer-mcp 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,190 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.5.0] - 2026-07-16
+
+### Added
+
+- **Tagged PDF / PDF/UA-1 (ISO 14289)** via `tagged: true` on the create tools.
+  Output is **verified compliant by veraPDF** (`--flavour ua1`, 106/106 rules) for
+  text, Markdown, and table documents.
+
+  Opt-in by design: existing behaviour is unchanged unless you ask for tagging.
+  PDF/UA mandates a document title, so `tagged: true` requires `title`.
+
+  - Structure tree (`StructTreeRoot`, `StructElem`, `ParentTree`) built from
+    pdf-lib's low-level object model — it has no logical-structure API.
+  - Every drawn line is wrapped in `/Tag <</MCID n>> BDC … EMC`, and decorations
+    (rules, cell borders, code backgrounds) become `/Artifact BMC … EMC` (7.1-3).
+  - Markdown maps to structure: headings → `H1`–`H6`, lists → `L`/`LI`/`LBody`,
+    tables → `Table`/`TR`/`TH`/`TD`, quotes → `BlockQuote`, code → `Code`.
+  - Heading levels are normalised so they start at H1 and never skip (7.4.2).
+    A Markdown `# → ###` jump becomes `H1 → H2`; visual sizes are untouched.
+  - Table headers carry `/A << /O /Table /Scope /Column >>` (7.5-1).
+  - XMP is generated in-house (pdf-lib has no XMP API) with the `pdfuaid`
+    declaration **and** the PDF/A extension schema description — veraPDF rejects
+    the declaration without it (5-1).
+  - `/Lang`, `/ViewerPreferences /DisplayDocTitle`, `/MarkInfo /Marked`.
+
+- **`lang` option** (BCP 47). When omitted under `tagged: true` the language is
+  inferred from the text and reported via `warnings`. Inference is conservative:
+  kana → `ja`, Hangul → `ko`, Han without kana → `ja` *with a warning that it
+  could be Chinese*. A wrong `/Lang` makes screen readers mispronounce text, so
+  the guess is always surfaced rather than silently applied.
+
+### Fixed
+
+- **Bullets in unordered lists rendered as `.notdef`** (blank boxes) — a
+  regression from 0.3.0. Font subsetting is driven by the *input* text, but the
+  Markdown renderer adds characters of its own: `- item` contains no bullet, yet
+  `•` is drawn. Those glyphs were missing from the subset. Renderer-generated
+  characters are now always subset in (`RENDERER_GENERATED_CHARS`).
+
+  Text extraction was unaffected, which is why no existing test caught it;
+  veraPDF's 7.21.8-1 (no `.notdef` references) is what surfaced it.
+
+- XMP metadata is written as UTF-8 bytes. `context.stream(string)` writes one
+  byte per character, which mangled Japanese titles.
+
+## [Unreleased]
+
+### Changed
+
+- **biome adopted** for linting and formatting, matching the rest of the family
+  (same `biome.json`, same scripts). `npm run check` now runs in CI and in the
+  publish workflow. Existing sources were reformatted; the suite is clean.
+- The version is pinned to an exact `2.5.4` rather than a caret range. Biome's
+  formatting output changes between minor releases, so a range lets a local
+  `npm install` drift ahead of CI and produce spurious diffs.
+
+### Fixed
+
+- `handleCreateTablePdf` duplicated the Latin-1 check as a regex containing
+  control characters; it now reuses the existing `hasNonLatin1` helper.
+- `src/config.ts` imports `node:module` rather than the bare `module` specifier.
+
+## [0.4.0] - 2026-07-16
+
+### Added
+
+- **Editing tools (Tier A, wave 2)**:
+  - `add_bookmarks` — set the document outline. Nestable via `children` (up to 8
+    levels, 2000 entries). Replaces any existing outline. Titles are written as
+    UTF-16BE so CJK round-trips correctly. Open items carry a positive `/Count`,
+    collapsed items a negative one, per ISO 32000-1 §12.3.3.
+  - `add_annotation` — add a `text` (sticky note), `highlight`, or `square`
+    annotation. Coordinates use PDF space (origin bottom-left, points). Colors
+    are `#rrggbb`; `contents` and `author` accept CJK.
+
+  pdf-lib exposes no outline or annotation API, so both are built from the
+  low-level object model (`services/outline.ts`, `services/annotation.ts`).
+
+## [0.3.1] - 2026-07-16
+
+### Fixed
+
+- **Text extraction broken for digits in Latin context** (regression introduced in
+  0.3.0): `subsetFont` is now called with `noLayoutClosure: true`.
+
+  pdf-lib's `CustomFontEmbedder` (used with `subset: false`) derives glyphs
+  through two independent paths: the CIDs written into the content stream come
+  from `font.layout(text)` — **after** GSUB substitution — while the ToUnicode
+  CMap is built from `font.characterSet` → `glyphForCodePoint` — **before**
+  substitution. Noto Sans JP substitutes ASCII digits with alternate forms in
+  Latin context (`layout('English 0')` yields glyph 17460, not 17), so the two
+  disagreed and extraction returned wrong characters (`v0.3.0` → `vô.õ.ô`, and
+  poppler dropped the digits entirely). Rendering was correct throughout, which
+  made this easy to miss.
+
+  Excluding layout-reachable glyphs from the subset prevents the substitution
+  altogether, so `layout()` and `glyphsForString()` agree again. Subsets also got
+  smaller as a side effect (9.1 KB → 4.5 KB for a typical page).
+
+### Added
+
+- `render.test.ts` now asserts that the CIDs written to the page match the
+  ToUnicode CMap, so this class of regression fails the suite.
+
+## [0.3.0] - 2026-07-16
+
+### Fixed
+
+- **Japanese text rendered as blank boxes in every viewer** (Chrome, Firefox,
+  Acrobat, poppler, Claude Desktop). Font subsetting no longer goes through
+  pdf-lib's `embedFont(subset: true)`: fonts are now pre-subset with harfbuzz
+  ([subset-font](https://github.com/papandreou/subset-font)) and embedded with
+  `subset: false`.
+
+  fontkit's subsetter drops glyph outlines for CJK fonts. Because the ToUnicode
+  CMap stayed correct, text extraction kept working and the existing tests
+  passed while the visible output was broken.
+
+  | Approach | PDF size | Rendering |
+  |---|---|---|
+  | fontkit `subset: true` (previous) | 24 KB | broken |
+  | pdf-lib `subset: false` alone | 3.9 MB | correct |
+  | harfbuzz + `subset: false` (current) | 14.5 KB | correct |
+
+- The note in the design doc claiming poppler's `Embedded font file may be
+  invalid` warning was harmless is retracted — poppler followed it with
+  `Couldn't create a font`, i.e. the warning was the breakage.
+
+### Added
+
+- `render.test.ts`: extracts the embedded font program from generated PDFs and
+  verifies that every rendered character retains a real glyph outline. Verified
+  to fail against the pre-0.3.0 implementation.
+- CI fetches Noto Sans JP and sets `TEST_FONT_PATH`, so the font-dependent tests
+  no longer skip.
+
+### Changed
+
+- `loadFont` split into `openFont` (read + glyph coverage) and `embedFontFor`
+  (subset + embed). Subsetting depends on the text being drawn, so embedding is
+  deferred until the input is final.
+- **Dependency added**: `subset-font` (harfbuzz/wasm, no native binaries).
+
+## [0.2.1] - 2026-07-16
+
+### Added
+
+- **`onMissingGlyph` option** for the create tools. Characters absent from the
+  font (e.g. ✔ U+2714, which Noto Sans JP does not include) were previously
+  embedded as `.notdef` and rendered as silent blanks.
+  - `error` (default) — list the offending characters and fail
+  - `replace` — substitute 〓 and report via `warnings`
+  - `ignore` — render as before and report via `warnings`
+- `CreateResult.warnings` reports substituted or ignored characters.
+
+## [0.2.0] - 2026-07-16
+
+### Added
+
+- **Editing tools (Tier A, wave 1)** — the server now edits existing PDFs in
+  addition to creating them:
+  - `set_metadata` — update Info dictionary fields, preserving the rest
+  - `merge_pdfs` — concatenate in order (metadata inherited from the first file)
+  - `split_pdf` — one file per page range
+  - `extract_pages` — extract in the requested order (doubles as reordering)
+  - `delete_pages` — remove pages (deleting all is rejected)
+  - `reorder_pages` — reorder by an explicit permutation
+  - `rotate_pages` — rotate clockwise, accumulating over existing rotation
+- **Signature guard**: editing a PDF with `/ByteRange` fails by default, since
+  pdf-lib rewrites the whole file and would invalidate existing signatures.
+  Pass `allowBreakingSignatures: true` to proceed anyway.
+- Page specs (`"1,3-5,8-"`, 1-based, order-preserving, duplicates removed).
+- CI (`ci.yml`) and npm publish via Trusted Publisher / OIDC (`publish.yml`).
+
+## [0.1.0] - 2026-07-15
+
+Initial release.
+
+### Added
+
+- `create_text_pdf` — plain text with paragraph breaks, wrapping, pagination
+- `create_markdown_pdf` — headings, lists, code blocks, quotes, rules, tables
+- `create_table_pdf` — ruled tables with automatic column widths and repeated
+  headers across page breaks
+- Japanese font embedding, ToUnicode CMap (extractable/searchable text),
+  file or base64 output, `asserts`-based input validation.

package/README.ja.md

@@ -0,0 +1,156 @@
+# pdf-writer-mcp
+
+[![CI](https://github.com/shuji-bonji/pdf-writer-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/shuji-bonji/pdf-writer-mcp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@shuji-bonji/pdf-writer-mcp.svg)](https://www.npmjs.com/package/@shuji-bonji/pdf-writer-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+[English](./README.md)
+
+テキスト / Markdown / 表データからの **PDF 生成** と、既存 PDF の **編集**（メタデータ・ページ操作）を行う MCP (Model Context Protocol) サーバです。[pdf-lib](https://pdf-lib.js.org/) をコアに、harfbuzz サブセットによる日本語フォント埋め込みに対応します。
+
+[pdf-reader-mcp](https://github.com/shuji-bonji/pdf-reader-mcp)（構造解析）、[pdf-verify-mcp](https://github.com/shuji-bonji/pdf-verify-mcp)（真正性検証）と同じ PDF family の一員です。`pdf-reader-mcp` が「何があるか」を読み、`pdf-verify-mcp` が「本物か」を検証するのに対し、`pdf-writer-mcp` は「それを書く」役割を担います。
+
+## ツール
+
+### 生成
+
+| ツール | 役割 |
+|--------|------|
+| `create_text_pdf` | プレーンテキスト — `\n` で改行、空行で段落区切り、長い行は自動折り返し |
+| `create_markdown_pdf` | Markdown — 見出し / 段落 / 箇条書き・番号リスト / コードブロック / 引用 / 水平線 / 表 |
+| `create_table_pdf` | 罫線付き表 — 列幅の自動算出、セル内折り返し、改ページ時のヘッダ再描画 |
+
+共通オプション: `outputPath` / `returnBase64` / `fontPath` / `fontSize` / `pageSize`（A4/A3/A5/LETTER/LEGAL）/ `margin` / `title` / `author` / `onMissingGlyph` / `tagged` / `lang`。
+
+### タグ付き PDF / PDF/UA（v0.5.0）
+
+`tagged: true` を指定すると、**PDF/UA-1（ISO 14289）準拠のタグ付き PDF**（アクセシブルな PDF）を生成します。veraPDF（`--flavour ua1`）で 106/106 規則の準拠を確認済みです。
+
+```jsonc
+{ "markdown": "# 見出し\n\n本文。", "title": "レポート", "tagged": true, "lang": "ja" }
+```
+
+Markdown は構造木に対応付けられます。見出し → `H1`〜`H6`、リスト → `L`/`LI`/`LBody`、表 → `Table`/`TR`/`TH`/`TD`（ヘッダには `/Scope`）、引用 → `BlockQuote`、コード → `Code`。水平線・罫線・コード背景は Artifact になります。見出しレベルは「H1 始まり・飛ばさない」よう正規化されるため、Markdown の `# → ###` は構造上 `H1 → H2` になります（見た目のサイズは元のままです）。
+
+PDF/UA はタイトルを要求するため、`tagged: true` では `title` が必須です。`lang`（BCP 47）は省略すると本文から推定し、`warnings` で報告します。**誤った `/Lang` はスクリーンリーダの誤読を招く**ため、分かっている場合は明示してください。
+
+> タグ付けは opt-in です（既定の出力は変わりません）。機械検証は「読み順や代替テキストが**適切か**」までは判定できず、存在の有無しか見られません。人手の確認は依然として必要です。
+
+### 編集
+
+| ツール | 役割 |
+|--------|------|
+| `set_metadata` | Info 辞書の更新（`title` / `author` / `subject` / `keywords` / `creator`）。指定フィールドのみ変更し、他は保持 |
+| `merge_pdfs` | 2〜50 個の PDF を指定順に結合。メタデータは先頭ファイルから引き継ぎ |
+| `split_pdf` | ページ範囲ごとに 1 ファイルへ分割 |
+| `extract_pages` | 指定順を保持して抽出（並べ替えを兼ねる） |
+| `delete_pages` | ページ削除（全ページの削除はエラー） |
+| `reorder_pages` | 全ページの順列による並べ替え |
+| `rotate_pages` | 時計回りに回転（90/180/270）。既存の回転に加算 |
+| `add_bookmarks` | しおり（アウトライン）の設定。`children` で入れ子にでき、既存のしおりは置換 |
+| `add_annotation` | 付箋（`text`）/ ハイライト（`highlight`）/ 矩形（`square`）の注釈を追加 |
+
+共通オプション: `outputPath` / `returnBase64` / `allowBreakingSignatures`。
+
+ページ指定は `"1,3-5,8-"` 形式（1 始まり。`-3` は先頭から 3 ページまで、`8-` は 8 ページから最終まで）。指定順を保持し、重複は除去します。
+
+> **署名について**: pdf-lib は保存時にファイル全体を再構築するため、編集すると既存の電子署名は必ず無効化されます。`/ByteRange` を含む PDF は既定でエラーとし、`allowBreakingSignatures: true` を指定したときのみ続行します。署名を保持する増分更新はロードマップ参照。
+
+## インストール
+
+```json
+{
+  "mcpServers": {
+    "pdf-writer": {
+      "command": "npx",
+      "args": ["-y", "@shuji-bonji/pdf-writer-mcp"],
+      "env": {
+        "PDF_WRITER_FONT": "/absolute/path/to/NotoSansJP-Regular.otf"
+      }
+    }
+  }
+}
+```
+
+`PDF_WRITER_FONT` を設定しておくと、各ツールで `fontPath` を省略しても日本語が出せます。
+
+## フォント
+
+標準 PDF フォント（Helvetica）は **ASCII のみ** です。日本語など非ラテン文字を描画するには、`fontPath` または `PDF_WRITER_FONT` で埋め込み可能な**単一フェイス**のフォント（`.ttf` / `.otf`）を指定してください。
+
+- 推奨入手先: [Noto Sans JP (SubsetOTF/JP)](https://github.com/notofonts/noto-cjk/tree/main/Sans/SubsetOTF/JP) — 静的・単一フェイス・SIL OFL。
+- **`.ttc`（TrueTypeCollection）は非対応**です。検知してエラーにするため、単一フェイスを抽出してください:
+
+  ```bash
+  python3 -c "from fontTools.ttLib import TTCollection; \
+    TTCollection('NotoSansCJK-Regular.ttc').fonts[0].save('NotoSansCJKjp-Regular.otf')"
+  ```
+
+### フォント未収録文字（グリフ欠落）
+
+フォントに存在しない文字（例: Noto Sans JP に無い ✔ U+2714）は、そのままだと `.notdef` として埋め込まれ、無警告で空白になります。`onMissingGlyph` でこの挙動を選べます。
+
+| 値 | 挙動 |
+|----|------|
+| `error`（既定） | 欠落文字を `"✔" (U+2714)` 形式で列挙してエラー |
+| `replace` | 〓 に置換して生成し、`warnings` で報告 |
+| `ignore` | 空白のまま生成し、`warnings` で報告 |
+
+## 返り値
+
+```jsonc
+{
+  "path": "/abs/out.pdf",     // outputPath 指定時
+  "base64": "JVBERi0xLj...",  // returnBase64 指定時、または outputPath 省略時
+  "pageCount": 3,
+  "bytes": 91788,
+  "font": "NotoSansJP-Regular.otf",
+  "warnings": ["Replaced 1 unsupported character(s) with \"〓\": \"✔\" (U+2714)"]
+}
+```
+
+編集ツールは `font` を除いた同じ形を返します。`split_pdf` は `{ files: [...], count }` を返します。
+
+## テキスト抽出
+
+生成される PDF はテキストの選択・コピー・全文検索・スクリーンリーダ読み上げが可能です。埋め込みサブセットフォントでも pdf-lib が ToUnicode CMap を出力するためで、この性質は回帰テスト（`extract.test.ts` / `render.test.ts`）で担保しています。
+
+> poppler 系のビューアは、OTF/CFF フォントを CIDFontType0 として埋め込む際に `Mismatch between font type and embedded font file` という警告を表示することがあります。これは無害で、描画・抽出とも正常です。
+
+## 開発
+
+```bash
+npm install
+npm run build      # dist/ に出力
+npm test           # vitest
+npm run typecheck  # tsc --noEmit
+```
+
+日本語フォント依存のテストは `TEST_FONT_PATH` を指定すると有効になります。
+
+```bash
+TEST_FONT_PATH=/path/to/NotoSansJP-Regular.otf npm test
+```
+
+## 既知の制約
+
+- **インライン装飾**: 太字・斜体はサイズ / 字面のみで、書体としては反映されません（1 文書につき単一フォントを埋め込むため）。
+- **`.ttc` フォント**: 単一フェイスへの抽出が必要です（上記参照）。
+- **サブセット名の接頭辞**: 慣習的な `ABCDEF+` を付けないため、一部ツールがサブセットでないと誤認します。描画・抽出には影響せず、PDF/A の厳密対応時のみ問題になります。
+
+## ロードマップ
+
+- [x] 編集系 Tier A 第1波 — メタデータ・ページ操作（v0.2.0）
+- [x] 編集系 Tier A 第2波 — しおり・注釈（v0.4.0）
+- [x] タグ付き PDF / PDF/UA-1 — veraPDF で準拠を確認（v0.5.0）
+- [ ] 編集系 Tier B — フォーム記入 / フラット化、透かし、添付ファイル、ページ番号スタンプ
+- [ ] 画像の代替テキスト（`Figure` + `/Alt`）、タグ付き出力での注釈の `Annot` タグ内包
+- [ ] `.ttc` からのフェイス自動抽出
+- [ ] 見出し用と本文用のフォント分け（太字フェイス埋め込み）
+- [ ] 画像埋め込み、ヘッダー / フッター
+- [ ] Tier C — 署名を保持する増分更新、本文テキスト編集、タグ木の保守
+- [ ] PDF/A 変換
+
+## ライセンス
+
+MIT © shuji-bonji