# 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](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

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

### Poking at it by hand

```bash
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

```bash
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)](https://creativecommons.org/licenses/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.