Case study·pdf-edit-mcp

pdf-edit-mcp

Live

Bringing format-preserving PDF editing to AI agents — 38 tools, three guided workflows, the engine running in-process.

~/pdf-edit-mcp

$ uvx pdf-edit-mcp

[mcp] ready · 38 tools · 3 prompts

> pdf_inspect { "pdf_path": "quote.pdf" }

✓ 4 pages · 2 fonts · 12 annotations

> pdf_batch_replace { "edits": [...] }

✓ font_preserved · overflow: false

tools

Why this needed to exist.

Once pdf-edit-engine existed as a Python library, the next question was how to make it usable by AI agents. The first release (0.1.x) was a TypeScript MCP server that shelled out to a Python bridge.py over JSON-RPC — which meant a second runtime to install (Node.js), a subprocess to supervise, and a serialization boundary between the agent and the engine. And without structured workflows, agents would have no idea when to inspect a PDF, when to call analyze_subset before editing, or how to combine 38 tools into a coherent edit. Simply exposing the library's functions one-for-one would be a usability failure even if it technically worked.

02The approach

How I built it.

v0.2.0 rewrote the server in Python on FastMCP and imports pdf-edit-engine in-process — no subprocess, no JSON-RPC bridge, no Node.js. One runtime, one install (pip install pdf-edit-mcp or uvx pdf-edit-mcp), and no serialization boundary on the hot path. The 38 tools are organised into seven categories (reading, text edits, block ops, section ops, annotations, document manipulation, metadata/security) and backed by three built-in MCP prompts that teach agents the canonical workflow: quick-pdf-edit for typos and dates, section-swap for structural rewrites (including the subtle requirement that batch_replace_block must include all sibling sections for uniform spacing), and comprehensive-pdf-edit for multi-step edits. The tool names, inputs, and outputs stayed identical through the rewrite, so prompts and integrations built against 0.1.x keep working. Every tool result surfaces pdf-edit-engine's FidelityReport so agents can verify quality before calling it done.

03Impact

What it did.

Published to PyPI as pdf-edit-mcp, installable in one command across Claude Desktop, Claude Code, Cursor, Windsurf, and VS Code. Importing the engine in-process removes the entire Node.js + subprocess + JSON-RPC layer the 0.1.x bridge needed — one runtime to install and no IPC boundary, so a 500-edit batch call runs in essentially the same time as calling the engine directly. The three built-in prompts are workflow scaffolding agents can reference by name — teaching them the inspect → analyze → execute → verify loop rather than leaving them to discover it.

04Tech stack

What I used — and why.

FastMCP (MCP Python SDK)

The official Python MCP SDK's FastMCP server registers all 38 tools and 3 prompts over stdio transport — the canonical implementation every major MCP client expects, with no separate TypeScript layer to maintain.

In-process engine import

pdf-edit-mcp imports pdf-edit-engine directly instead of spawning it as a subprocess — no per-request interpreter startup, no JSON-RPC serialization, and a single runtime to install.

pdf-edit-engine

The format-preserving editing engine itself, pinned to >=0.2.0,<0.3 — every tool result surfaces its FidelityReport so agents can verify edit quality before calling it done.

pikepdf

Shared with the engine for PDF reading and document-level operations, keeping the entire dependency surface inside the Python ecosystem.

Want something similar?

Available for freelance projects and contract engineering. Usually reply within 24 hours.

Let's talk More work