pdf-translator MCP

An MCP server that supplies translation guidance for turning English PDFs — papers, manuals, guides — into Korean while preserving document structure. Registered as a claude.ai custom connector.

This server does not translate. It never receives the PDF. Reading the document, working out its structure, translating it, and assembling the .md artifact are all done by Claude. The server returns one thing: the rules for how to translate.

Design rationale and the reasoning behind each decision live in DESIGN.md (Korean).

---

Tools

Tool	Purpose
start_translation(title, page_count, genre, resuming?)	Entry point. Size assessment, two-pass work order, output format, handoff-note format
get_rules(genre)	Structure preservation, do-not-translate zones, table/footnote/formula conventions, genre rules

genre is one of paper, manual, other.

Flow

User attaches a PDF
  → Claude reads it
  → start_translation   (may require splitting the file first)
  → get_rules
  → Pass 1: glossary, section map, do-not-translate list; confirm with the user
  → Pass 2: translate section by section, appending to one artifact

Documents past ~150 pages do not fit in a single conversation. The user splits the PDF, and the translation note at the end of the artifact is pasted into the next conversation to carry the glossary forward. Subsequent parts call the tool with resuming: true. The server stores nothing.

---

Development

npm install
npm run dev        # http://localhost:8787
npm run typecheck
npm run deploy

Poking at it by hand

curl -s -X POST http://localhost:8787/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s -X POST http://localhost:8787/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
        "name":"start_translation",
        "arguments":{"title":"Some Paper","page_count":19,"genre":"paper"}}}'

---

Layout

src/
  index.ts          Streamable HTTP + JSON-RPC. Stateless, unauthenticated, zero dependencies
  tools.ts          Tool definitions and profile validation
  guides.ts         Size tiering and template substitution
  guides/*.md       ← Guide content. This is the actual product

Most changes belong in src/guides/*.md. Translation quality is decided by those Markdown files, not by the server code. They are bundled as text modules, so you edit the Markdown directly. The guide text is written in Korean because it instructs the model on producing Korean output.

File	Contents
plan.md / plan-resume.md	Work plan — fresh start / resuming
tier-single.md / tier-caution.md / tier-split.md	How to proceed at each document size
rules-common.md	Output format, structure preservation, numbers and units, terminology
rules-paper.md / rules-manual.md / rules-other.md	Genre-specific rules

Substituted placeholders: {{TITLE}}, {{PAGE_COUNT}}, {{GENRE}}, {{GENRE_LABEL}}, {{SPLIT_HINT}}, {{TIER_BLOCK}}.

---

Why no MCP SDK

There are no sessions, no streaming, and no server-initiated notifications here, so the SDK solves nothing this server has. Implementing the non-SSE path of Streamable HTTP directly keeps the dependency count at zero and the bundle around 14 KiB gzipped.

Why no authentication

The server touches no user data. It holds no storage, never receives a document, and returns the same public guidelines to everyone. There is nothing to authenticate.

---

Deployment

npx wrangler deploy

Add the deployed /mcp URL as a custom connector in claude.ai. No further setup is needed.

---

Test fixture

journal.pone.0350400.pdf — a 19-page pharmacokinetics paper. Chosen because it exercises the hard cases in one document: multi-level merged table headers, statistical symbols, unit-heavy figures, and a reference list that must not be translated.

Zhou X, Deng Y, Guo C, Li Y, Fu Y, Wang Z, et al. (2026) Pharmacokinetic interactions between three SGLT2 inhibitors and telmisartan: A focus on empagliflozin, ertugliflozin, and henagliflozin. PLoS One 21(6): e0350400. https://doi.org/10.1371/journal.pone.0350400

© 2026 Zhou et al. This is an open access article distributed under the terms of the Creative Commons Attribution License (CC BY 4.0), which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited. This repository redistributes the original PDF under those terms.