pdf-edit-mcp: Instructions file for Claude Code

pdf-edit-mcp

MCP server for format-preserving PDF text editing, powered by pdf-edit-engine (Python). As of v0.2.0 this is a single-process Python (FastMCP) server — the engine is imported in-process. (The v0.1.x TypeScript server + bridge.py subprocess are gone; see git history / CHANGELOG.)

Architecture

Claude / AI Agent
    ↓ MCP protocol (stdio)
pdf_edit_mcp (FastMCP server, this package)
    ↓ in-process import
pdf-edit-engine (Python library: pikepdf + fonttools + pdfminer)

Module layout (dependency order)

__init__.py      __version__
app.py           FastMCP `mcp` instance + `engine_lock`  ← dependency LEAF
constants.py     input bounds (single source of truth)
validation.py    path_safety_error + PdfPath/OutputPath/DirPath + BBox/EditItem/BlockReplacement
serialize.py     serialize_edit_result + aggregate_fidelity (exact wire shapes)
_runtime.py      engine_guard (lock + error translation), READ_ONLY/WRITE annotations, page_count
tools_read.py    9 read tools        tools_edit.py     7 edit tools
tools_sections.py 3 section tools     tools_document.py 15 document tools
tools_annotations.py 5 annotation tools  prompts.py     3 prompts
server.py        version gate + main(); imports the tool/prompt modules to register them

Import-cycle rule: mcp and engine_lock live in app.py (a leaf). Tool modules import them from app, never from server. server imports the tool modules at the bottom for decorator side-effects. Do not move mcp/engine_lock back into server — that reintroduces the server → tools_* → _runtime → server cycle.

Critical rules

1. stdout is the MCP transport — never print() to stdout; diagnostics go to stderr (the engine version gate already does this).
2. The engine is NOT thread-safe — every engine call goes through _runtime.engine_guard(), which holds the module-level engine_lock. New tools must wrap their engine work in with engine_guard():.
3. Path validation is a security boundary — path parameters use the PdfPath / OutputPath / DirPath validated types from validation.py (absolute, .pdf, no .. traversal, no control chars, no Windows reserved/truncated basenames). Never accept a bare str for a path.
4. Error model — engine PDFEditError subclasses are translated by engine_guard into ToolError with a classified message + recovery hint. Raise PDFEditError for in-tool validation; do not leak raw pikepdf exceptions.
5. Engine version gate — server._check_engine_version() exits non-zero if the installed pdf-edit-engine < 0.2.0 (relies on the password= kwargs, fit=, and the 30-kind degradation taxonomy).
6. mypy --strict + ruff clean — mypy src/pdf_edit_mcp and ruff check src/ tests/ must pass. server.py has a per-file E402 ignore (intentional bottom-of-file registration imports).