pdf-toolbox-mcp 0.1.0__tar.gz

pdf_toolbox_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Something didn't work as expected
+title: "[bug] "
+labels: bug
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Also include what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: probe
+    attributes:
+      label: Dependency probe output
+      description: Output of `uv run pdftoolbox probe all` (or the `dependency_status` tool result)
+    validations:
+      required: true
+  - type: textarea
+    id: error
+    attributes:
+      label: Structured error JSON
+      description: The `{"ok": false, "error": ...}` payload if any
+  - type: dropdown
+    id: os
+    attributes:
+      label: OS
+      options: [macOS, Linux, Windows]
+    validations:
+      required: true
+  - type: textarea
+    id: client
+    attributes:
+      label: MCP client / version
+      description: e.g. Claude Desktop 1.x, Claude Code 2.x, Cursor …

pdf_toolbox_mcp-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,28 @@
+---
+name: Feature request
+about: Suggest a new capability or improvement
+title: "[feat] "
+labels: enhancement
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What do you want to do that isn't possible today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: How would you expect to ask the agent to do it?
+      description: The natural-language phrasing matters — tools are designed around agent workflows.
+  - type: dropdown
+    id: fits
+    attributes:
+      label: Which area?
+      options:
+        - OCR / text extraction
+        - Page surgery (split/merge/rotate)
+        - Security (encrypt/redact/sanitize)
+        - Inspection (fonts/images/repair)
+        - Batch / performance
+        - Distribution / docs

pdf_toolbox_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            install: sudo apt-get update -qq && sudo apt-get install -y -qq poppler-utils qpdf ghostscript tesseract-ocr
+          - os: macos-latest
+            install: brew install poppler qpdf ghostscript tesseract
+          # Windows: choco 预装在 runner 上。tesseract 包较大（~5min），
+          # 换来全量 engine 测试在 Windows 真实运行——验证 gswin64c 别名等平台适配。
+          - os: windows-latest
+            install: choco install -y poppler qpdf ghostscript tesseract
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Install system dependencies
+        run: ${{ matrix.install }}
+      - name: Lint (ruff)
+        run: uv run ruff check src tests tools
+      - name: Sync Python dependencies
+        run: uv sync --dev
+      - name: Run tests
+        run: uv run pytest -v
+      - name: Probe report
+        run: uv run pdftoolbox probe all

pdf_toolbox_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,20 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # PyPI trusted publishing（OIDC，无需 API token）
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: uv build
+      - name: Publish (trusted publishing)
+        run: uv publish

pdf_toolbox_mcp-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.uv/
+
+# 测试与工具
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# 编辑器与系统
+.idea/
+.vscode/
+.DS_Store
+
+# 项目运行产物（默认沙箱目录）
+PDF-Toolbox/
+.fixtures/
+.tessdata/
+
+# 本地私有材料（发版清单、教程草稿）与本机工具配置
+notes/
+opencode.json

pdf_toolbox_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/); versioning is [SemVer](https://semver.org/).
+
+## [Unreleased] — 0.1.0
+
+First functional build. Local-first PDF processing MCP server (OCRmyPDF + Poppler + qpdf + ghostscript), 24 tools, 105 tests green on macOS / Linux / Windows CI.
+
+### Added
+- **Content redaction**: `locate_text` (text → page + bounding boxes via `pdftotext -bbox`, CJK-safe normalized matching) and `redact_text` (redact by keyword — auto-locates every occurrence, no manual coordinates)
+- **P1a core**: `pdf_info`, `is_searchable` (smart routing), `extract_text` (exact page ranges), `ocr_pdf` (**OCR write-back** to searchable PDF, language fallback), `render_pages` (PNG, optional inline image blocks), `unlock_pdf` (user-password decrypt — competitors hard-fail here)
+- **P1b page surgery** (L0-pure qpdf): `split_pdf`, `merge_pdfs`, `rotate_pages`, `protect_pdf` (AES-256 + granular permissions)
+- **P2 inspection & batch**: `list_fonts`, `extract_images`, `extract_attachments`, `check_repair` (+ rebuild repair), `linearize`, `batch_ocr` (per-file results / retries / timeouts)
+- **P3 advanced**: `sanitize` (strip JS/metadata/attachments), `redact` (**true redaction** — affected pages rasterized, redacted text physically unrecoverable, other pages keep their text layer; `rasterize_all=true` for whole-doc protection), `fill_form`, `edit_metadata` (docinfo+XMP), `compress_pdf` (quality ladder to target size)
+- Capability-leveled dependencies (L0–L3) with structured `missing_dependency` errors carrying per-platform install commands; `_deps` summary injected into every successful response
+- CLI: `pdftoolbox` with all operations + `probe all`
+- Windows: `gswin64c` binary alias, UTF-8 console output; CI runs the full suite on windows-latest via choco
+- Research & plan docs (`RESEARCH.md`, `PLAN.md`, `docs/competitor-matrix.md` incl. hands-on survey of Citra / ODA / jztan / go-docs-mcp)
+
+### Verified
+- OCR write-back roundtrip (scan → searchable, marker asserted) on macOS + Linux + Windows
+- Redaction security: output text layer empty + black-box pixel assertion
+- Chinese OCR benchmark (synthetic): 99.03% clean / 93.69% deskewed / 81.07% heavy-noise
+- 50-file batch: 50/50 success, ~1.6 s/file
+
+[Unreleased]: https://github.com/twoer/pdf-toolbox-mcp/commits/main

pdf_toolbox_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing
+
+Thanks for your interest in improving pdf-toolbox-mcp!
+
+## Development setup
+
+```bash
+git clone https://github.com/twoer/pdf-toolbox-mcp
+cd pdf-toolbox-mcp
+uv sync --dev
+uv run pdftoolbox probe all   # 检查系统依赖级别（见 README 安装矩阵）
+```
+
+System tools are capability-leveled — you can develop and run most tests with just one of them installed; engine tests auto-skip when a binary is missing.
+
+## Before submitting
+
+```bash
+uv run ruff check src tests tools   # lint 必须全绿
+uv run pytest                       # 全量测试（按本机依赖自动跳过）
+```
+
+Both must pass. CI runs the full matrix (ubuntu / macos / windows) on every PR.
+
+## Adding a tool
+
+1. Implement the engine function in `src/pdf_toolbox/engine/` — pure function, `dict` in / `dict` out, no MCP imports; call `require()` for binaries and `assert_readable()`/`check_write()` for path safety.
+2. Wrap it in `server.py` via `_guard()` (structured errors + `_deps` injection) and add a `cli.py` command.
+3. Tests in `tests/` with the right capability marker (`requires_poppler` / `requires_qpdf` / `requires_tesseract` / `requires_gs`).
+4. Update both READMEs' tool table and `CHANGELOG.md`.
+
+## Conventions
+
+- Errors raise typed exceptions from `engine/errors.py`; the MCP layer converts them to `{"ok": false, "error": <code>, ...}`.
+- Outputs never overwrite silently — `overwrite=true` must be explicit.
+- All subprocess calls use argument lists (no shell interpolation).
+- Docs and user-facing messages are bilingual (English README + `README.zh-CN.md`); code comments in Chinese are fine.
+
+## Reporting issues
+
+Please include `uv run pdftoolbox probe all` output and the structured error JSON you got.

pdf_toolbox_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhangkun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdf_toolbox_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.5
+Name: pdf-toolbox-mcp
+Version: 0.1.0
+Summary: Local-first PDF processing MCP server — OCR write-back, text extraction, page rendering, page surgery, encryption (OCRmyPDF + Poppler + qpdf)
+Project-URL: Homepage, https://github.com/twoer/pdf-toolbox-mcp
+Project-URL: Repository, https://github.com/twoer/pdf-toolbox-mcp
+Project-URL: Issues, https://github.com/twoer/pdf-toolbox-mcp/issues
+Project-URL: Changelog, https://github.com/twoer/pdf-toolbox-mcp/commits/main/
+Author: zhangkun
+License-Expression: MIT
+License-File: LICENSE
+Keywords: local-first,mcp,model-context-protocol,ocr,ocrmypdf,pdf,poppler,qpdf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.12
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: ocrmypdf>=16.0
+Requires-Dist: pikepdf>=9.0
+Requires-Dist: pillow>=11.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# pdf-toolbox-mcp
+
+[中文文档](README.zh-CN.md) | Local-first PDF processing for AI agents.
+
+**Others help AI *read* PDFs. This one helps AI *process* them** — OCR a scan into a truly searchable file, unlock encrypted PDFs, split/merge/rotate, re-encrypt for sharing. 100% on your machine: no cloud calls, no file uploads, no per-page fees.
+
+## Why another PDF MCP?
+
+The PDF MCP space is crowded — but only on the *reading* side. Based on a [hands-on survey of the ecosystem](docs/competitor-matrix.md) (2026-09):
+
+| Capability | **pdf-toolbox** | Citra (916★) | ODA PDF-Tools (153★) | jztan/pdf-mcp (130★) | Cloud SaaS MCPs |
+|---|:-:|:-:|:-:|:-:|:-:|
+| **OCR write-back** → searchable PDF file | ✅ | ❌ read-out only | ❌ (no OCR) | ❌ read-out only | ☁️ paid |
+| **Unlock encrypted** (user password) | ✅ | ❌ hard fail | ⚠️ owner-pw only | ❌ hard fail | ☁️ paid |
+| Split / merge / rotate | ✅ | ❌ | ✅ | ❌ | ☁️ paid |
+| **Compress** to target size | ✅ | ❌ | ❌ | ❌ | ☁️ paid |
+| Render pages for vision | ✅ | ✅ | ✅ | ✅ | ☁️ |
+| 100% local & private | ✅ | ✅ | ✅ | ✅ | ❌ |
+
+Pain points this addresses directly:
+
+- Claude natively **refuses encrypted PDFs**; ChatGPT reports *"No text could be extracted"* on scans — here, OCR writes a real text layer back into the file, and `unlock_pdf` decrypts with just the user password.
+- Claude Code burns **~30× more tokens** reading a PDF page-as-image than extracting text locally.
+
+## Quick start
+
+Add to any MCP client (Claude Desktop / Claude Code / Cursor / …):
+
+```json
+{
+  "mcpServers": {
+    "pdf-toolbox": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/twoer/pdf-toolbox-mcp", "pdf-toolbox-mcp"]
+    }
+  }
+}
+```
+
+*(PyPI package `pdf-toolbox-mcp` is coming; the git install above works today.)*
+
+Python dependencies resolve automatically. System tools are **capability-leveled** — missing ones never crash the server; the tool returns a structured error with the exact install command:
+
+| Level | Binary | Unlocks | macOS | Debian/Ubuntu | Windows |
+|---|---|---|---|---|---|
+| L0 | qpdf | split / merge / rotate / protect / unlock | `brew install qpdf` | `apt install qpdf` | `choco/scoop install qpdf` |
+| L1 | poppler | extract_text / render / info | `brew install poppler` | `apt install poppler-utils` | `choco/scoop install poppler` or conda-forge |
+| L2 | tesseract | **ocr_pdf (write-back)** | `brew install tesseract tesseract-lang` | `apt install tesseract-ocr tesseract-ocr-chi-sim` | `choco/scoop install tesseract` |
+| L3 | ghostscript | compress | `brew install ghostscript` | `apt install ghostscript` | `scoop install ghostscript` / `winget install ArtifexSoftware.GhostScript` |
+
+> Windows note: Ghostscript's binary is `gswin64c.exe` there — the probe detects it automatically, so `compress_pdf` works out of the box. Tesseract language packs (e.g. `chi_sim`) must be downloaded to its `tessdata` folder separately.
+
+Every successful response carries a `_deps` summary (`{"level": 2, "missing": ["gs"]}`) so the agent always knows what's available.
+
+## Tools (24)
+
+| Tool | What it does | Engine |
+|---|---|---|
+| `pdf_info` | Pages, encryption status, metadata — always call first | pdfinfo |
+| `is_searchable` | Smart routing: text density check → recommends `extract_text` or `ocr_pdf` | pdftotext |
+| `extract_text` | Layout-aware text, exact page ranges `1-3,5`, per-page mode | pdftotext |
+| `ocr_pdf` | **OCR write-back**: scan → searchable PDF (deskew, skip/redo, lang fallback) | OCRmyPDF |
+| `batch_ocr` | Whole-directory OCR with per-file results, retries, timeouts | OCRmyPDF |
+| `render_pages` | PNG per page, `return_images=true` streams image blocks to the vision model | pdftoppm |
+| `extract_images` | Pull embedded images (inventory or PNG files) | pdfimages |
+| `extract_attachments` | Pull embedded attachment files | pdfdetach |
+| `list_fonts` | Font audit — non-embedded fonts risk missing glyphs on other machines | pdffonts |
+| `unlock_pdf` | Decrypt with **user password**, output a clean decrypted file | qpdf |
+| `protect_pdf` | AES-256 + granular permissions (print/extract/modify/…) | qpdf |
+| `split_pdf` | By ranges or every N pages | qpdf |
+| `merge_pdfs` | Ordered merge | qpdf |
+| `rotate_pages` | 90/180/270 on selected pages | qpdf |
+| `check_repair` | Structural check; `repair=true` rebuilds damaged files | qpdf |
+| `linearize` | Web-optimized progressive-loading output | qpdf |
+| `sanitize` | Publishing hygiene: strip JS/OpenAction/metadata/attachments | pikepdf |
+| `redact` | **True redaction**: affected pages rasterized + opaque boxes — redacted text physically unrecoverable, other pages keep their text layer (`rasterize_all=true` for max protection) | pdftoppm + PIL |
+| `redact_text` | Redact **by content**: locate every occurrence of the given keywords and black them out — no manual coordinates needed | pdftotext -bbox |
+| `locate_text` | Find where text occurs: page + bounding boxes (PDF points, top-left origin) — the foundation for redaction & highlighting | pdftotext -bbox |
+| `fill_form` | Fill AcroForm fields (missing fields reported) | pikepdf |
+| `edit_metadata` | Set/clear Title/Author/… (docinfo + XMP) | pikepdf |
+| `compress_pdf` | Compress, optionally down a quality ladder until hitting `target_mb` | ghostscript |
+| `dependency_status` | Probe system tools + install commands | — |
+
+**Error contract** (agents self-route): failures return `{"ok": false, "error": "<code>"}` — `missing_dependency` (with `install` per platform), `encrypted_pdf` (hint: call `unlock_pdf` first), `wrong_password`, `output_exists` (explicit overwrite required), `invalid_page_range`, …
+
+## Examples
+
+In an MCP client, just describe the outcome — the agent chains the tools itself, and the error contract makes it self-routing (an `encrypted_pdf` error tells it to call `unlock_pdf` first, and so on). For headless use, define once:
+
+```bash
+PTX="uvx --from git+https://github.com/twoer/pdf-toolbox-mcp pdftoolbox"
+# shortens to "uvx --from pdf-toolbox-mcp pdftoolbox" once the PyPI package lands
+```
+
+**1 · Scan → searchable PDF** (the flagship)
+
+> “`contract-scan.pdf` is a scanned contract I can't search. Make it searchable — mostly Chinese with some English.”
+
+Agent: `pdf_info` → `is_searchable` reports low text density → `ocr_pdf(path, lang="chi_sim+eng")` writes `contract-scan_ocr.pdf`. Text extraction and Ctrl+F now work on the output.
+
+```bash
+$PTX ocr contract-scan.pdf --lang chi_sim+eng
+$PTX text contract-scan_ocr.pdf --pages 1-3
+```
+
+**2 · Encrypted PDF → readable**
+
+> “`locked.pdf` is password-protected; the password is `hunter2`. Unlock it and summarize page 3.”
+
+Agent: `unlock_pdf(path, password="hunter2")` → `locked_unlocked.pdf` → `extract_text(pages="3")`.
+
+```bash
+$PTX unlock locked.pdf --password 'hunter2'
+$PTX text locked_unlocked.pdf --pages 3
+```
+
+**3 · Redact secrets before sharing**
+
+> “Black out every occurrence of `张三` and `HT-2026-088` in `draft.pdf` — it must be physically unrecoverable.”
+
+Agent: `redact_text(queries=["张三", "HT-2026-088"])` → `draft_redacted.pdf`. Pages containing hits are rasterized, so the strings vanish from the pixels *and* the text layer; other pages keep their selectable text. Verify by running `extract_text` on the output: zero hits expected.
+
+```bash
+$PTX redact-text draft.pdf --query 张三 --query HT-2026-088
+```
+
+**4 · Assemble & encrypt for sending**
+
+> “Merge `cover.pdf` + `report.pdf` into `annual.pdf`, then protect it: opens with password `k3y`, printing allowed, modification not.”
+
+Agent: `merge_pdfs(paths=["cover.pdf", "report.pdf"], output="annual.pdf")` → `protect_pdf(user_password="k3y")` (print/extract allowed, modify denied by default) → `annual_locked.pdf`.
+
+```bash
+$PTX merge cover.pdf report.pdf --output annual.pdf
+$PTX protect annual.pdf --user-password 'k3y'
+```
+
+**5 · Fit an email size limit**
+
+> “`big.pdf` is 38 MB and the mail cap is 10 MB. Shrink it.”
+
+Agent: `compress_pdf(path, target_mb=10)` walks the quality ladder (ebook → screen) until under target → `big_compressed.pdf`.
+
+```bash
+$PTX compress big.pdf --target-mb 10
+```
+
+More recipes — batch OCR, the publish-hygiene chain (`sanitize` → `edit_metadata` → `linearize`), vision rendering, locate-and-redact, form filling, damaged-file rescue — in the [cookbook](docs/cookbook.md).
+
+## Configuration
+
+| Env | Default | Meaning |
+|---|---|---|
+| `PDF_TOOLBOX_TESS_LANG` | `chi_sim+eng` | Default OCR languages; missing packs auto-fallback (flagged via `lang_fallback`) |
+| `PDF_TOOLBOX_WORKSPACE` | unset | If set, all writes are confined to this directory; system dirs are always denied |
+
+## CLI
+
+Everything is also available headless (great for scripts and CI):
+
+```bash
+uvx --from git+https://github.com/twoer/pdf-toolbox-mcp pdftoolbox ocr scan.pdf --lang chi_sim+eng
+uvx --from git+https://github.com/twoer/pdf-toolbox-mcp pdftoolbox unlock locked.pdf --password 'xxx'
+uvx --from git+https://github.com/twoer/pdf-toolbox-mcp pdftoolbox split big.pdf --every-n 10
+uvx --from git+https://github.com/twoer/pdf-toolbox-mcp pdftoolbox probe all
+```
+
+*(Shortens to `uvx --from pdf-toolbox-mcp …` once the PyPI package is published — see the note in Quick start.)*
+
+## Security & privacy
+
+- No network calls. Files never leave the machine.
+- All subprocess calls use argument lists (no shell interpolation); page-range parsing is shared and validated.
+- Outputs never silently overwrite: `overwrite=true` must be passed explicitly.
+- Passwords are never logged in error payloads.
+- Untrusted PDF content is flagged in tool descriptions (prompt-injection awareness).
+
+## License compliance
+
+MIT. System tools are invoked as independent processes (aggregation): poppler (GPL-2.0), qpdf (Apache-2.0), tesseract (Apache-2.0), ghostscript (AGPL, optional); Python deps ocrmypdf/pikepdf are MPL-2.0. See [PLAN.md](PLAN.md) §7 for the full table.
+
+## Development
+
+```bash
+uv sync --dev          # install
+uv run pytest          # 105 tests; auto-skip by capability level
+uv run pdftoolbox probe all
+```
+
+Cross-platform check without leaving macOS:
+
+```bash
+docker run --rm -v "$PWD":/src:ro python:3.12-slim bash -c \
+  'apt-get update -qq >/dev/null && apt-get install -y -qq poppler-utils tesseract-ocr qpdf ghostscript >/dev/null &&
+   pip install -q uv && cp -r /src /work && cd /work && uv sync --dev --quiet && uv run pytest -q'
+```
+
+Roadmap: v0.1.0 ships all 24 tools above. Next up: the PyPI package (drops the git prefix from every command) and hardening against real-world scanned documents. Explicit non-goals: editing existing text, password cracking — see [PLAN.md](PLAN.md).
+
+## License
+
+MIT